File‑Based Music Library Synchronization with rsync

1. Scope and Intent

This guide documents a deterministic way to mirror a music library using rsync.

Target topology:

• Primary host: Windows or Linux
• Secondary devices: Windows, Linux, Android

The library exists only as files and folders. No media servers. No proprietary sync clients. No database layer.

The objective is predictable replication, not convenience.

2. Operating Assumptions

• One canonical source of truth
• One‑way synchronization only
• All writes happen on the primary host
• All secondaries are disposable mirrors

Not covered:

• Streaming
• Real‑time sync
• Bidirectional merge logic
• Playlist portability

3. Library Layout Requirements

A stable layout is mandatory.

Recommended structure:

• Music/

  • Artist/

    • Year - Album/

      • TrackNumber - Title.ext

Constraints:

• No random nesting
• No spaces at start or end of names
• Avoid special characters except dash and underscore
• Fixed depth

This minimizes path translation issues across platforms.

4. Core Concept: One‑Way Mirror

All devices are mirrors of the primary host.

No device except the primary is allowed to:

• Rename files
• Delete files
• Edit tags
• Add new tracks

Violating this rule produces silent divergence.

5. Prerequisites

Primary host:

• rsync installed
• SSH server or SMB share enabled
• Static local IP or stable hostname

Secondary hosts:

• rsync installed
• SSH client or SMB mount capability

Android:

• Terminal environment (Termux or equivalent)
• Sufficient local storage
• No reliance on Android media indexing

Dependencies:

• rsync is required on all non‑Android systems
• SSH is recommended for encrypted transport

These are explicit external dependencies.

6. Transport Layer Options

6.1 SSH Transport

Characteristics:

• Encrypted
• Authenticated
• Works across OS boundaries

Process:

• Primary exposes SSH
• Secondary connects via SSH
• rsync streams data over the tunnel

Limitations:

• Requires firewall configuration
• Requires user account on primary

6.2 SMB Transport

Characteristics:

• Native on Windows
• Mountable on Linux
• Accessible from Android file managers

Process:

• Primary exposes Music/ as read‑only SMB share
• Secondary mounts the share
• rsync operates on the mounted path

Limitations:

• No encryption
• Slower metadata propagation
• Permission mapping issues

7. rsync Behavior Model

rsync does not copy blindly.

It compares:

• File size
• Modification time
• Optional checksums

Only changed files are transferred.

Deletion propagation:

• Optional
• Must be explicitly enabled

This makes destructive operations irreversible.

8. Linux → Linux or Windows

Process Description

• Define a local Music/ mirror directory
• Run rsync in recursive mode

• Enable:

  • Timestamp comparison
  • Partial transfer resume
  • Deletion of removed files

Optional:

• Enable checksum verification for integrity

Operational Notes

• Run manually or via scheduler
• Keep a dry‑run mode for testing
• Log every execution

9. Windows → Windows or Linux

Process Description

• Install rsync via:

  • WSL
  • MSYS2
  • Cygwin
• Expose Music/ over SSH or SMB
• Run rsync from the secondary host

Path Normalization

Windows paths must be:

• Mapped to POSIX style
• Free of drive‑letter ambiguity

This is a frequent failure source.

10. Android Pull Model

Android is treated as a passive mirror.

Process Description

• Install a terminal environment
• Install rsync inside it
• Connect to the primary via SSH
• Pull Music/ into a fixed local folder

Constraints:

• No background scheduling
• No reliable timestamp semantics
• Slow I/O on SD cards

Deletion propagation is discouraged on Android.

11. Integrity Verification

Minimal checks:

• File count comparison
• Directory size comparison

Robust checks:

• Recursive checksums
• Manifest generation
• Spot verification on random albums

Checksum mode is CPU‑intensive.

Use it selectively.

12. Automation Strategy

Safe automation model:

• One‑way only
• Manual trigger or scheduled pull
• Dry‑run before destructive sync

Avoid:

• Bidirectional cron jobs
• Simultaneous multi‑target sync

These cause race conditions.

13. Common Failure Modes

• Timestamp skew between hosts
• Case‑sensitive vs case‑insensitive paths
• Unicode normalization differences
• Interrupted transfers
• FAT‑based SD card corruption

Mitigations:

• Enforce naming rules
• Use checksums
• Avoid hot‑unplug
• Keep backup snapshots

14. Trade‑Offs

15. Known Limitations

• No real‑time sync
• No conflict resolution
• No playlist portability
• No metadata merging
• No device‑side edits

These are structural constraints.

16. Minimal Recommended Topology

• Primary: Linux
• Transport: SSH
• Tool: rsync
• Direction: One‑way
• Android: Manual pull only

This minimizes state corruption.

17. Final Notes

File‑based libraries scale predictably.

They trade convenience for control.

They fail slowly and visibly.

Test every change on a small folder first.

Never trust automation without logs.