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

```bash
cargo build --release
```

## Configuration

1. Copy `config.example.toml` to `config.toml`:
   ```bash
   cp config.example.toml config.toml
   ```

2. Edit `config.toml` with your settings:
   ```toml
   [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__`):
   ```bash
   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

```bash
# 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`:
   ```toml
   [sync]
   playlists = true
   ```
2. Run the sync command:
   ```bash
   # 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`:
   ```toml
   [listenbrainz]
   token = "your_token_here"
   ```
3. Run the scrobble command:
   ```bash
   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:

```bash
nix-shell
```

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

## Building

```bash
# 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

```bash
# Run in debug mode
cargo run -- sync

# Run tests
cargo test

# Check code
cargo check
```

## License

MIT OR Apache-2.0