Plex to iPod Sync

Intelligent music sync tool for syncing Plex music libraries and playlists to Rockbox-enabled iPods with automatic organization and playlist generation.

Overview

This tool provides two intelligent sync modes for managing music on your Rockbox iPod:

• Full Library Sync: Automatically syncs your entire Plex music library when it fits on your device (< 90% capacity)
• Playlist Sync: Selectively syncs chosen playlists when your library is too large or you prefer manual curation

The tool maintains proper Artist/Album/Song folder structure, creates Rockbox-compatible .m3u playlists, and intelligently tracks sync state for efficient incremental updates.

Key Features

Intelligent Sync Modes

• Automatic Mode Detection: Analyzes library size vs device capacity and recommends appropriate sync mode
• Full Library Sync: Copies entire music library plus all playlists when space permits
• Playlist Sync: Interactive playlist selection with granular control
• Growth Detection: Automatically transitions from full library to playlist mode when library exceeds capacity
• Per-Device Preferences: Sync mode saved on device, works across multiple computers

Auto-Complete Albums

• Intelligent Album Completion: Automatically includes all tracks from albums when any track is in a playlist
• Per-Playlist Control: Enable/disable auto-complete on a per-playlist basis
• Orphan Cleanup: Removes auto-complete tracks when no longer needed
• Smart Source Tracking: Distinguishes between playlist, auto-complete, and library tracks

Advanced Sync Features

• Mirror Mode: Keeps iPod perfectly synchronized with Plex (adds new, removes old)
• Smart Incremental Sync: Only copies changed/new files, skips existing tracks
• Graceful Failure Recovery: Resumes interrupted syncs from last saved position
• Multi-Device Support: Different settings and playlists per device
• State Versioning: Automatic state migration and backward compatibility

User Interface

• Interactive Playlist Selection: Toggle playlists on/off before each sync
• Clean Progress Display: Professional progress bars and status indicators
• Dry-Run Mode: Preview all changes before executing
• Verbose Mode: Optional detailed logging with --verbose flag
• Quick-Sync Launcher: One-click sync script with auto-detection

Network & Storage

• Auto-Mount SMB Shares: Automatically connects to network music libraries
• Keychain Integration: Secure password storage in macOS Keychain
• Path Mapping: Translates remote server paths to local mount points
• Multiple Protocol Support: SMB, NFS, and AFP network shares
• Free Space Validation: Ensures sufficient device capacity before sync

Reliability

• Incremental State Saving: Saves progress every 10 tracks during copy operations
• Process Locking: Prevents concurrent syncs from corrupting state
• State Backup: Device-side and client-side backup files
• Error Recovery: Graceful handling of interruptions and failures

Requirements

• Python 3.7 or higher
• Plex Media Server with music library
• Rockbox-enabled iPod (FAT32 formatted)
• Network access to Plex server
• Music files accessible from your Mac (local or mounted network share)

Installation

Step 1: Run Setup Script

cd /path/to/plex-ipod-playlist-sync
./setup.sh

The setup script will:

• Create a Python virtual environment
• Install all required dependencies
• Create config.yaml from template

Step 2: Get Your Plex Token

Option A: From Plex Web Interface

1. Open any media item in Plex Web
2. Click the three dots menu
3. Select "Get Info"
4. Click "View XML"
5. Look for X-Plex-Token in the URL
6. Copy the token value

Option B: From Plex Settings

1. Go to Plex Settings → Account
2. Click "Show Advanced"
3. Find your X-Plex-Token

Step 3: Configure the Tool

cp config.yaml.template config.yaml
nano config.yaml

Basic Configuration:

plex:
  url: "http://192.168.1.50:32400"  # Use local IP for best performance
  use_token: true
  token: "your_plex_token_here"
  music_library: "Music"

ipod:
  mount_point: "/Volumes/IPOD"
  music_dir: "/Volumes/IPOD/Music"
  playlist_dir: "/Volumes/IPOD/Playlists"

sync:
  mirror_mode: true

For Remote Plex Servers:

If your Plex server runs on a different machine, you'll need path mapping:

plex:
  # ... basic config ...

  # Map server paths to local mount points
  path_mapping:
    server_path: "/mnt/music"                      # Path as Plex sees it
    local_path: "/Users/you/Music/ServerMusic"     # Where it's mounted on Mac

  # Optional: Auto-mount SMB share
  smb_mount:
    enabled: true
    smb_url: "server.local/music"
    mount_point: "/Users/you/Music/ServerMusic"
    username: "your_username"
    # Password stored in macOS Keychain (prompted on first run)

See docs/FILE_ACCESS_GUIDE.md for detailed network setup instructions.

Usage

Quick Start

# One-click launcher with auto-detection
./quick-sync.sh

The quick launcher will:

• Auto-detect and mount your iPod
• Auto-mount SMB share (if configured)
• Show interactive menu for sync options
• Offer to eject iPod when done

Basic Sync

# Mount your iPod (if not auto-mounted)
diskutil mount /dev/disk4s2

# Run sync with playlist selection
./sync.sh

# Run sync without interaction (use saved settings)
./sync.sh --no-interaction

Dry Run (Preview Mode)

Preview all changes before making them:

./sync.sh --dry-run

Dry run will:

• Show current playlist selections
• Display which tracks would be added/removed
• Show which playlists would be created/updated
• Make no actual changes to your iPod

Verbose Mode

Enable detailed logging:

./sync.sh --verbose

Sync Modes

First Sync Experience

On your first sync, the tool will:

1. Analyze your library: Calculate total library size
2. Check device capacity: Determine available space on iPod
3. Recommend sync mode:
   • If library fits (< 90% capacity): Offer choice between Full Library or Playlist mode
   • If library too large: Automatically use Playlist mode
4. Save preference: Mode stored on device for future syncs

Full Library Sync

When enabled, the tool will:

• Copy your entire Plex music library to iPod
• Create .m3u files for all Plex playlists
• Monitor library growth on each sync
• Automatically prompt to transition to Playlist mode if library grows too large

Playlist Sync

Provides granular control over which playlists to sync:

PLAYLIST STATUS
  [✓] Japanese Classics (89 tracks)
  [✓] Rock Favorites (45 tracks)
  [✗] Workout Mix (32 tracks)

Enabled: 2 | Disabled: 1

Change playlist selection? (y/n):

• Interactive toggle interface
• Selections saved per-device
• New playlists automatically enabled
• Space-efficient for large libraries

Auto-Complete Albums

When enabled, incomplete albums are automatically completed:

Album: Pink Floyd - The Dark Side of the Moon
  Tracks in playlist: 3/10
  Action: Auto-completing remaining 7 tracks

Auto-complete summary:
  Albums to complete: 5
  Additional tracks: 32

Configure per playlist:

• Enable during interactive sync
• Tracks labeled as "auto_complete" in state
• Orphaned AC tracks automatically removed when no longer needed

File Organization

iPod Structure

/Volumes/IPOD/
├── Music/
│   ├── The Beatles/
│   │   └── Abbey Road/
│   │       ├── 01 - Come Together.mp3
│   │       ├── 02 - Something.mp3
│   │       └── ...
│   ├── Pink Floyd/
│   │   └── The Dark Side of the Moon/
│   │       └── ...
│   └── [More Artists]/
│
├── Playlists/
│   ├── Rock Favorites.m3u
│   ├── Japanese Classics.m3u
│   └── Workout Mix.m3u
│
├── .rockbox/
│   └── [Rockbox system files]
│
└── .plex_sync_state.yaml  [Hidden sync state file]

Track Organization

Tracks are organized as:

Artist Name/Album Name/## - Track Name.ext

Example:

Pink Floyd/The Dark Side of the Moon/01 - Speak to Me.flac

Playlist Format

Playlists use extended M3U format:

#EXTM3U
#EXTINF:343,Pink Floyd - Time
/Music/Pink Floyd/The Dark Side of the Moon/03 - Time.flac
#EXTINF:235,The Beatles - Come Together
/Music/The Beatles/Abbey Road/01 - Come Together.mp3

Sync State Management

Device State File

The tool creates .plex_sync_state.yaml on your iPod to track:

• Which tracks are currently synced (with source: playlist/auto_complete/library)
• Sync mode preference (full_library/playlist)
• Device ID and name
• Track file sizes and paths
• Playlist associations
• State version (for automatic migration)

Client State Files

Per-device playlist selections saved in:

.playlist_selection_[DEVICE_NAME].yaml

State Backups

• Device-side backup: .plex_sync_state.yaml.backup (before each overwrite)
• Client-side backups: Timestamped backups in project directory
• Automatic restoration: Validates and restores from backup if corruption detected

Incremental State Saving

State is saved every 10 tracks during copy operations:

• Prevents loss of progress on interruption
• Resumes from last saved position
• No wasted time re-copying tracks

Advanced Features

Multi-Device Support

Sync different iPods from the same computer:

• Automatic device detection via unique ID
• Per-device playlist selections
• Per-device sync mode preferences
• Per-device sync state tracking

Example:

Device 1 (Work iPod): Playlist mode with 3 playlists
Device 2 (Home iPod): Full library mode

Path Mapping for Remote Servers

When Plex runs on a network server:

1. Mount server's music directory:

mount_smbfs //username@server/music ~/Music/ServerMusic

2. Configure path mapping:

path_mapping:
  server_path: "/mnt/music"                # Server's perspective
  local_path: "~/Music/ServerMusic"        # Your Mac's mount point

3. Translation example:

Plex reports:    /mnt/music/Artist/Album/Song.mp3
Script maps to:  ~/Music/ServerMusic/Artist/Album/Song.mp3
Copies to iPod:  /Volumes/IPOD/Music/Artist/Album/Song.mp3

Process Locking

Prevents concurrent syncs from corrupting state:

• Lock file created at sync start: .plex_sync.lock
• Released automatically on completion or failure
• Prevents multiple sync processes running simultaneously

Automation

Desktop Shortcut (macOS)

Using Automator:

1. Open Automator
2. Create new Application
3. Add "Run Shell Script" action:

cd /path/to/plex-ipod-playlist-sync
./quick-sync.sh

4. Save as "Sync iPod" on Desktop

Using Shortcuts:

1. Open Shortcuts app
2. Create new shortcut with "Run Shell Script" action
3. Add script path
4. Save and add to Dock

Auto-Sync on iPod Connect

Using Keyboard Maestro:

1. Create new macro
2. Trigger: Volume Mounted (named "IPOD")
3. Action: Execute Shell Script

cd /path/to/plex-ipod-playlist-sync
./sync.sh --no-interaction

Custom Sync Scripts

Create ~/sync-ipod.sh:

#!/bin/bash
SCRIPT_DIR="/path/to/plex-ipod-playlist-sync"

# Check if iPod is connected
if [ ! -d "/Volumes/IPOD" ]; then
    echo "Mounting iPod..."
    diskutil mount /dev/disk4s2
    sleep 2
fi

# Run sync
cd "$SCRIPT_DIR"
./sync.sh --no-interaction

# Optional: Eject when done
read -p "Eject iPod? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    diskutil unmount /Volumes/IPOD
    echo "iPod ejected safely."
fi

Supported File Formats

Rockbox supports these audio formats (all are synced):

Lossy: MP3, AAC/M4A, OGG Vorbis, Opus, WMA

Lossless: FLAC, ALAC, WavPack, APE, WAV

Other: AIFF, AU, SHN

Troubleshooting

iPod Not Detected

# List all mounted volumes
diskutil list

# Find your iPod (usually disk4 or disk5)
# Mount manually
diskutil mount /dev/disk4s2

Plex Connection Failed

• Verify Plex server URL (use local IP: http://192.168.1.X:32400)
• Check Plex token is correct
• Ensure Plex server is running
• Test connection: curl http://YOUR_PLEX_IP:32400/identity

File Not Found Errors

If syncing from remote Plex server:

1. Check server is mounted:

ls ~/Music/ServerMusic/

2. Remount if needed:

mount_smbfs //username@server/music ~/Music/ServerMusic

3. Verify path mapping in config.yaml matches server paths exactly

Playlists Don't Work on iPod

• Check playlist paths in .m3u files start with /Music/
• Ensure paths are relative to iPod root
• Rockbox is case-sensitive (check capitalization)
• Verify track files actually exist on device

Sync is Slow

• Use local Plex server IP instead of plex.tv
• Check network speed to Plex server
• Large FLAC files take longer to copy
• First sync always slower (copies everything)
• Subsequent syncs use incremental updates

Interrupted Sync

If sync is interrupted (Ctrl+C, power loss, etc.):

• State is saved every 10 tracks
• Next sync will resume from last saved position
• No need to re-copy already synced tracks
• State always reflects actual device state

Configuration Options

Sync Settings

sync:
  mirror_mode: true              # Remove tracks not in playlists
  allowed_formats: [".mp3", ".flac", ".m4a"]  # Filter by format

iPod Settings

ipod:
  mount_point: "/Volumes/IPOD"
  music_dir: "/Volumes/IPOD/Music"
  playlist_dir: "/Volumes/IPOD/Playlists"

Device Settings (per-device)

Stored in device state file:

• sync_mode: "playlist" or "full_library"
• auto_complete_albums: true/false
• copy_album_art: true/false
• cleanup_empty_folders: true/false

Command Reference

# Initial setup (run once)
./setup.sh

# Edit configuration
nano config.yaml

# Quick launcher (recommended)
./quick-sync.sh

# Basic sync with interaction
./sync.sh

# Sync without prompts
./sync.sh --no-interaction

# Preview changes (dry run)
./sync.sh --dry-run

# Detailed logging
./sync.sh --verbose

# Combine options
./sync.sh --dry-run --verbose --no-interaction

# Mount iPod manually
diskutil mount /dev/disk4s2

# Unmount iPod
diskutil unmount /dev/disk4s2

# Check iPod contents
ls /Volumes/IPOD/Music/
ls /Volumes/IPOD/Playlists/

Documentation

• Easy Setup Guide - One-click setup and automation
• File Access Guide - Network shares and path mapping
• Testing Guide - Comprehensive testing scenarios
• Changelog - Version history and release notes

Best Practices

1. Always run dry-run first on a new setup to preview changes
2. Use local IP for Plex server (faster than plex.tv)
3. Enable auto-mount for SMB shares to simplify workflow
4. Regular syncs ensure iPod stays current with library
5. Check disk space before syncing large libraries
6. Use verbose mode when troubleshooting issues
7. Keep playlists organized in Plex as your source of truth

Architecture

The tool is organized into modular components:

plex_ipod_sync/
├── config/           # Configuration management
├── plex/             # Plex API integration
├── network/          # SMB mounting
├── storage/          # File operations and state
├── sync/             # Sync orchestration
├── ui/               # User interface
└── utils/            # Utilities (filesystem, keychain)

Key features:

• Type hints throughout
• Comprehensive docstrings
• Separation of concerns
• State versioning
• Virtual environment support

License

This tool is provided as-is for personal use.

Credits

Created: 2025-10-29 Version: 2.0.0 For: Rockbox iPod (5th/6th/7th Generation) Plex API: python-plexapi UI Framework: Rich