Sound Check (volume normalization) support

[jvgomg]

Feature Request

Support iPod Sound Check (volume normalization) by reading existing normalization data from source files and writing the soundcheck value to the iPod database during sync.

Description

iPod Sound Check normalises playback volume across tracks so you don't need to adjust volume between songs. The iPod firmware reads a pre-computed soundcheck value from its database and applies it as a gain adjustment — it does no analysis itself.

Currently, podkit does not set this value. Many users already have volume normalization data on their files from various tools, but that data is ignored during sync, meaning the iPod's Sound Check toggle does nothing for podkit-synced music.

Supported normalization formats

podkit should read normalization data from two common sources:

Format	Written by	Tag format
iTunNORM	iTunes, Apple Music, dBpoweramp, Mp3tag	10 hex values in a comment/atom tag
ReplayGain	beets, foobar2000, MusicBee, Picard, loudgain	REPLAYGAIN_TRACK_GAIN / REPLAYGAIN_ALBUM_GAIN tags

Both formats encode essentially the same information (a dB gain adjustment and peak value) and can be converted to the iPod's soundcheck field using well-documented formulas:

• ReplayGain → soundcheck: round(1000 * 10^(gain_dB / -10))
• iTunNORM → soundcheck: Parse fields 0/1 (already in the right unit, take the max)

If a file has both, iTunNORM could take priority (since it's the native Apple format), or this could be configurable.

Visibility and insight

Users should be able to understand the normalization state of their collection:

• During sync: Surface how many tracks have normalization data vs. how many are missing it (e.g., in --dry-run output or sync summary)
• Device inspection: podkit device music could show whether tracks have Sound Check values set
• Collection audit: A way to check which source files are missing normalization data, so users can act on it

Adding normalization data

For users whose files lack normalization data, podkit should at minimum document how to add it using existing tools:

• beets users: beet replaygain (ReplayGain plugin)
• foobar2000 users: Built-in ReplayGain scanner
• iTunes/Apple Music users: Enable Sound Check in preferences (analyzes on import)
• CLI users: loudgain, mp3gain, aacgain, rg2itunnorm

Whether podkit itself should offer built-in analysis (e.g., podkit analyze wrapping ffmpeg's loudnorm filter) is a separate question worth discussing — it would be convenient but adds scope.

Use Cases

• iTunes/Apple Music users migrating to podkit already have iTunNORM tags — Sound Check should just work
• beets / foobar2000 / MusicBee users with ReplayGain-tagged libraries get normalization without re-analyzing
• Mixed libraries where some tracks have data and others don't — users need visibility into what's missing so they can fix gaps
• New users who haven't thought about normalization — documentation and audit tools help them understand and adopt it

Status

Released in v0.3.0 — see the Sound Check documentation for the full guide.

[jvgomg]

Sound Check support shipped in v0.3.0! Here's what landed:

• ReplayGain and iTunNORM tags are read from source files and written to the iPod database during sync — if your files have normalization data, Sound Check just works
• Subsonic/Navidrome servers are also supported via the OpenSubsonic API, so ReplayGain data from your server is picked up automatically
• Dry-run and stats show Sound Check coverage with percentage format (e.g., "620 of 650 tracks (95%)")
• Verbose mode (-v) breaks down which tag formats were found in your collection (iTunNORM, ReplayGain track, ReplayGain album)
• Contextual tips nudge you when coverage is partial, suggesting how to add normalization tags to the remaining files
• soundcheck is available as a display field in device music and collection music via --fields

For the full guide, see the Sound Check documentation.