jellypod

Reliable CLI sync from a Jellyfin Subsonic endpoint to iPod using podkit direct Subsonic mode.

Warning

Highly experimental software. Use at your own risk. Always keep independent backups of your iPod/music library before running sync.

Project Status

• Supported platforms: macOS and Linux.
• Runtime requirements: Node.js 20+, podkit on PATH, Jellyfin with Subfin/OpenSubsonic enabled.
• Support boundary: music sync only, CLI only, Jellyfin Subsonic endpoint only.
• Stability: active development, but intended for daily-use personal syncing.

Quick Start (5 Minutes)

1. Install prerequisites

Do this now:

1. Install Node.js 20+.
2. Install podkit (current tested version: 0.6.0).
3. Enable Jellyfin Subsonic endpoint using Subfin.

Details: Subfin setup guide

2. Install jellypod

Do this now:

git clone <repo-url>
cd jellypod
npm install
npm run build
npm link

Expected outcome:

jellypod --help

3. Initialize config and state

Do this now:

jellypod init

Default config path:

• $XDG_CONFIG_HOME/jellypod/config.json
• fallback: ~/.config/jellypod/config.json

Edit config and set Subfin credentials:

{
  "version": 1,
  "jellyfin": {
    "baseUrl": "https://stream.example.com",
    "subsonicUsername": "your-subfin-user",
    "subsonicPassword": "your-subfin-password"
  },
  "ipod": {
    "enforceModelNumStr": "MC293"
  }
}

Full key reference: Config reference

4. Run health checks and first sync

Do this now:

jellypod doctor
jellypod sync --dry-run
jellypod sync

Expected outcomes:

• doctor reports podkit, subsonic-auth, and ipod-scan as [ok].
• sync --dry-run prints a non-empty podkit plan.
• sync completes and writes a success run into local SQLite state.

Common Commands

• jellypod init: create config, .env.example, and initialize SQLite state.
• jellypod doctor: validate podkit, storage paths, iPod scan, identity checks, Subsonic auth.
• jellypod sync: run resilient sync with retry, stall recovery, and convergence verification.
• jellypod status: show trusted devices, run history, and local state paths.

Complete command/flag docs: CLI reference

How Sync Safety Works

• Device trust: first unknown auto-detected iPod requires confirmation and stores UUID trust.
• First-sync policy: safe-adoption defaults to non-destructive first real sync.
• Delete behavior: --delete behavior is controlled by config and first-sync state.
• Convergence pass: jellypod verifies post-sync add/update/remove counts and re-runs sync passes until converged (bounded by config).
• Recovery: transient network failures, no-output stalls, and no-progress stalls trigger automated retries.

Deep details: Reliability guide

Common Pitfalls

1. subsonic-auth 404 in doctor The Jellyfin Subfin plugin is missing, mismatched, or not exposed through your reverse proxy. Fix: follow Subfin setup guide and verify /rest/ping.view.

2. Sync appears stuck podkit can stall on a transfer; jellypod auto-recovers, but large libraries can take time. Fix: run jellypod sync --verbose and review Troubleshooting.

3. No songs visible after sync iPod DB identity/artwork state may be inconsistent. Fix: run jellypod doctor and the remediation steps in Troubleshooting.

Where to Go Next

• Setup walkthrough: docs/getting-started.md
• Jellyfin + Subfin setup: docs/jellyfin-subfin-setup.md
• Config reference: docs/config-reference.md
• CLI reference: docs/cli-reference.md
• Reliability model: docs/reliability.md
• Troubleshooting: docs/troubleshooting.md
• Development and contribution workflow: docs/development.md
• Security guidance: docs/security.md

Docs Versioning Note

Docs in this repository track the current main branch behavior. When making behavior changes, update README and affected files under docs/ in the same pull request.

License and Security

• License: MIT
• Security policy: SECURITY.md