Usage Guide

Music Sync is a two-screen terminal application. You start on the setup screen, then move to the sync screen where all the action happens.

Setup Screen

On first launch you will see the setup screen. Enter the absolute path to your PC music library (source) and the Android music folder (destination). Optionally enable MD5 checksums if you want to catch content-only changes that don't affect file size or modification time.

Note: The destination must already exist and be writable. On Linux, MTP-mounted devices typically appear under /run/media/$USER/.

Sync Screen

After saving your paths, the sync screen opens. It shows a summary panel, two progress bars, and a live action log.

Workflow

Run a dry run

Press d to scan both directories without making changes. The log shows every file that would be copied (green) or deleted (red), along with a total count.

Review the summary

The summary panel shows how many files will be copied, how many deleted, and the total data transfer size. Verify this matches your expectations.

Start the sync

Press s once to scan (if you skipped the dry run), then press s again to apply. Progress bars track overall completion and the current file being processed.

Verify the result

When sync completes, the log shows a green confirmation and the summary resets. Your Android device now has an exact mirror of your source library.

Keyboard Shortcuts

Key	Action
`s`	Scan directories, or sync after a scan
`d`	Dry run (scan and list changes without applying)
`r`	Reset state and clear the log
`escape`	Go back to the setup screen
`q`	Quit the application

Project Structure

music-sync/
  main.py            # Entry point
  config.py          # ~/.config/music-sync/config.ini persistence
  sync_engine.py     # Diff engine (walk, compare, copy, delete)
  tui_app.py         # Textual application (setup + sync screens)
  requirements.txt   # Dependencies (textual)

Back to home