NaviPod/README.md

NaviPod

A native Rust application to sync songs and albums from your self-hosted Navidrome instance to your iPod running either stock OS or Rockbox.

Features

• 🎵 Sync songs and albums from Navidrome
• 🎼 Sync playlists from Navidrome (as M3U8 files)
• 📱 Support for iPod stock OS
• 🎸 Support for Rockbox firmware
• 📊 Scrobble listening history to ListenBrainz
• ⚙️ Configurable sync options
• 🔄 Incremental sync support
• 📈 Terminal progress bars with live status

Installation

cargo build --release

Configuration

1. Copy config.example.toml to config.toml:

   cp config.example.toml config.toml
   

2. Edit config.toml with your settings:

   [navidrome]
   url = "http://localhost:4533"
   username = "your_username"
   password = "your_password"
   
   [ipod]
   mount_point = "/media/ipod"
   firmware = "rockbox"  # or "stock"
   
   [sync]
   albums = true
   playlists = false
   format = "mp3"
   
   [listenbrainz]
   # Optional - only needed for scrobbling to ListenBrainz
   token = "your_listenbrainz_token"
   

3. Alternatively, use environment variables (prefixed with NAVIPOD__):

   export NAVIPOD__NAVIDROME__URL="http://localhost:4533"
   export NAVIPOD__NAVIDROME__USERNAME="your_username"
   export NAVIPOD__NAVIDROME__PASSWORD="your_password"
   export NAVIPOD__IPOD__MOUNT_POINT="/media/ipod"
   export NAVIPOD__IPOD__FIRMWARE="rockbox"
   

Note: Navidrome must have JSON API enabled (default in recent versions). The application uses Subsonic API with f=json parameter.

Usage

# Sync all configured content (with progress bar)
cargo run -- sync

# Sync specific album
cargo run -- sync --album "Album Name"

# Sync specific artist
cargo run -- sync --artist "Artist Name"

# Sync specific playlist only
cargo run -- sync --playlist "Playlist Name"

# List available albums
cargo run -- list-albums

# List available playlists
cargo run -- list-playlists

# Check iPod connection
cargo run -- check

# Scrobble listening history to ListenBrainz
cargo run -- scrobble

# Scrobble and clear the log (with backup)
cargo run -- scrobble --clear

# Scrobble and clear without backup
cargo run -- scrobble --clear --no-backup

Syncing Playlists

NaviPod can sync your Navidrome playlists to your iPod as M3U8 files:

1. Enable playlist syncing in your config.toml:

   [sync]
   playlists = true
   

2. Run the sync command:

   # Sync all playlists
   cargo run -- sync
   
   # Or sync a specific playlist only
   cargo run -- sync --playlist "My Favorites"
   

3. Playlists will be created in the Playlists folder on your iPod
4. Only songs that are already on your iPod will be included in the playlists

Note: Playlists use M3U8 format (UTF-8 encoded) with relative paths, which works with both Rockbox and most other media players.

Scrobbling to ListenBrainz

NaviPod can read the .scrobbler.log file from your Rockbox iPod and submit your listening history to ListenBrainz:

1. Get your ListenBrainz user token from https://listenbrainz.org/profile/
2. Add it to your config.toml:

   [listenbrainz]
   token = "your_token_here"
   

3. Run the scrobble command:

   cargo run -- scrobble --clear
   

The --clear flag will remove the scrobbler log after successful submission (with automatic backup). This is useful to avoid re-submitting the same listens next time.

Requirements

• Rust 1.70+ (and Cargo)
• C compiler (for building native dependencies)
• iPod mounted and accessible
• Navidrome instance running and accessible
• Navidrome with JSON API support (enabled by default)

NixOS Setup

If you're using NixOS, enter the development shell:

nix-shell

This will provide Rust, Cargo, and all necessary build tools. The shell.nix file is already configured for this project.

Building

# On NixOS, first enter the development shell:
nix-shell

# Build in release mode
cargo build --release

# The binary will be at:
# - target/release/navipod

# Install to your PATH (optional)
cargo install --path .

Development

# Run in debug mode
cargo run -- sync

# Run tests
cargo test

# Check code
cargo check

License

MIT OR Apache-2.0