iPod Sync

A fast, modular, incremental music downloader and sync manager for Apple iPod Nano and all iPod models.

Quick Start (Double-Click)

Double-click iPod Sync.command on your Desktop to open the interactive menu.

Features

1. One-Click Auto-Sync (Plug & Play):

   • Select [1] Auto-Sync Everything to iPod (or run ipod-sync auto-sync).
   • Detects your connected iPod, checks flash storage capacity, scans all Apple Music playlists, downloads missing tracks, mirrors playlist deletions, and bridges into Apple Music in one step.

2. Direct Apple Music Sync (Single Playlist):

   • Select [2] Sync from Apple Music (Select Playlist) (or run ipod-sync music-sync [NAME]).
   • Reads tracks directly from macOS Apple Music via AppleScript without manual exports.

3. Music Search Engine with Multi-Select Cart:

   • Select [3] Search & Download Music (or run ipod-sync search "<query>").
   • Search songs, singles, or albums directly.
   • Select multiple tracks at once using cart syntax (e.g. 1, 3, 5, ranges 1-4, or all).
   • Download directly to your library or assign to a specific playlist on the fly.

4. Audio & Visual Enhancements Built-in:

   • Square Cover Art: 16:9 YouTube thumbnails are automatically center-cropped to 1:1 square artwork (crop=ih:ih). No black bars on iPod color screens.
   • Volume Normalization: Audio is normalized via ffmpeg loudnorm (-16 LUFS target) to match Apple Sound Check. Eliminates volume jumps between songs.
   • Storage Capacity Guard: Checks required storage against available iPod flash memory before downloading to prevent disk full errors.
   • Mirror Playlist Sync: Deleting a track from an Apple Music playlist removes it from the iPod playlist on sync while keeping audio files intact in the shared pool.

5. Consolidated .txt Playlist Import:

   • Select [4] Import .txt Playlist.
   • Processes pending exports in ~/Downloads/iPod_Inbox/, or prompts for drag & drop file path if inbox is empty.

6. Library & Storage Overview:

   • Select [5] Library & Storage Overview (or run ipod-sync storage / ipod-sync library list).
   • Displays track pool sizes, iPod flash storage savings, and all tracked playlists in one consolidated view.

Directory Layout

• Inbox: ~/Downloads/iPod_Inbox/ (drop .txt playlist files here)
• Audio Pool: ~/Downloads/iPod_Library/Tracks/ (shared pool of .m4a files)
• Playlists: ~/Downloads/iPod_Library/Playlists/ (generated .m3u8 files)
• State DB: ~/.config/ipod-sync/history.json (track deduplication index)

Terminal Commands

ipod-sync                           # Opens interactive menu
ipod-sync auto-sync                 # One-click auto-sync all playlists to iPod
ipod-sync music-sync                # Sync specific Apple Music playlist
ipod-sync search "Artist Song"      # Search and cart download tracks
ipod-sync sync                      # Process inbox playlists
ipod-sync transfer                  # Import all playlists into Apple Music for sync
ipod-sync library list              # View all tracked playlists
ipod-sync storage                   # Disk analysis and deduplication savings

Support

Submit issues, questions, or bug reports to the GitHub issue tracker: https://github.com/ADM1SH/ipod-sync/issues

Roadmap

• Done: Core architecture and baseline implementation.
• Done: Functional verification and test coverage.
• To do: Add Rockbox playlist format export
• To do: Implement automated FLAC to ALAC lossless conversion

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/improvement.
3. Commit your changes: git commit -m "feat: enhance functionality".
4. Push to the branch: git push origin feature/improvement.
5. Open a Pull Request.

Authors and Acknowledgment

• Adam Anwar (ADM1SH) - Lead architect and developer.
• Created by Adam Anwar for physical iPod Classic hardware music synchronization.

License

Licensed under the MIT License. See LICENSE for details.

Project Status

Stable CLI. 183 tests passing with zero failures.