Configuration

podkit uses a TOML configuration file to define where your music lives, which devices to sync to, and how to transcode. This guide introduces the core concepts — see the Config File Reference for the complete schema.

Creating the Config File

The config file lives at ~/.config/podkit/config.toml. Generate one with:

podkit init

Or create it manually:

mkdir -p ~/.config/podkit
touch ~/.config/podkit/config.toml

You can override the config file location with --config <path> or the PODKIT_CONFIG environment variable.

Core Concepts

A podkit config has three main parts:

Collections — where your music (and video) lives
Devices — the iPods you sync to
Defaults — what happens when you just run podkit sync

Collections

Collections are named music sources. Each one points to either a local directory or a Subsonic-compatible server:

# A local music library
[music.main]
path = "/Volumes/Media/music/library"

# A Subsonic server (Navidrome, Airsonic, etc.)
[music.navidrome]
type = "subsonic"
url = "https://music.example.com"
username = "user"
path = "/tmp/navidrome-cache"

You can define as many collections as you need and sync them independently:

podkit sync -c main          # Sync just the "main" collection
podkit sync -c navidrome     # Sync just the Subsonic collection

For details on each source type, see:

Devices

Devices are named iPods registered in your config. The easiest way to add one is with a connected iPod:

podkit device add myipod

This auto-detects the device and writes the config entry:

[devices.myipod]
volumeUuid = "ABC-123-DEF-456"
volumeName = "IPOD"

Each device can have its own quality and artwork settings, so a high-capacity Classic can use lossless audio while a Nano uses compressed:

[devices.classic]
volumeUuid = "ABCD-1234"
volumeName = "CLASSIC"
audioQuality = "lossless"

[devices.nano]
volumeUuid = "EFGH-5678"
volumeName = "NANO"
quality = "medium"
artwork = false

See Managing Devices for the full device setup guide.

Defaults

The [defaults] section sets which collection and device to use when you don’t specify them on the command line:

[defaults]
device = "classic"
music = "main"
video = "movies"

With these defaults, podkit sync is equivalent to podkit sync --device classic -c main. You can always override on the command line:

podkit sync --device nano -c vinyl-rips

Quality

Quality controls how podkit transcodes audio and video. The simplest approach is a single quality setting — either globally or per device:

quality = "high"              # Global default for audio and video

For finer control, audioQuality and videoQuality override quality independently. This is useful when you want lossless audio but compressed video:

[devices.classic]
audioQuality = "lossless"
videoQuality = "high"

See Quality Settings for a practical guide to choosing presets, and Quality Presets Reference for the full preset specifications.

Transforms

Transforms modify track metadata during sync. Currently, the ftintitle transform moves featured artist credits from the Artist field into the Title field — useful for cleaner artist browsing on iPods:

[transforms.ftintitle]
enabled = true

Transforms can be overridden per device. See Artist Transforms for a setup guide and the Transform Reference for all options.

Minimal Example

Here’s a complete working config with one collection, one device, and sensible defaults:

[music.main]
path = "/path/to/your/music"

[devices.myipod]
volumeUuid = "ABC-123"
volumeName = "IPOD"

[defaults]
device = "myipod"
music = "main"