Sync Tags

Sync tags are small metadata markers that podkit writes into the iPod track’s comment field. They record exactly what transcode settings produced each file, enabling precise preset change detection and artwork change detection.

Format

Sync tags use a versioned key-value format:

[podkit:v1 quality=high encoding=vbr]

The tag is embedded in the track’s comment field alongside any existing comment text. podkit reads and updates only the [podkit:...] block, leaving the rest of the comment untouched.

Fields

Field	Required	Values	Description
`quality`	Yes	`lossless`, `high`, `medium`, `low`, `max`, `copy`	The quality preset (or `copy` for non-transcoded lossy tracks)
`encoding`	No	`vbr`, `cbr`	Encoding mode. Omitted for lossless audio and video
`bitrate`	No	`64`–`320`	Only present when a custom bitrate override was used
`art`	No	8-character hex string	Artwork fingerprint (xxHash truncated to 32 bits)

Examples

[podkit:v1 quality=high encoding=vbr]              # VBR transcode at high preset
[podkit:v1 quality=medium encoding=cbr]             # CBR transcode at medium preset
[podkit:v1 quality=high encoding=cbr bitrate=256]   # CBR with custom bitrate override
[podkit:v1 quality=lossless art=a1b2c3d4]           # ALAC transcode with artwork fingerprint
[podkit:v1 quality=copy art=deadbeef]               # Copied lossy track with artwork fingerprint
[podkit:v1 quality=max]                             # Video transcode

When Sync Tags Are Written

Sync tags are written automatically during normal syncs:

Transcoded tracks get a tag recording the quality preset and encoding mode
Artwork transfers add the art field to the existing tag (or create a minimal quality=copy tag for non-transcoded tracks)

This means sync tag coverage grows naturally over time as you sync new tracks or upgrade existing ones.

Writing tags to all tracks at once

Use --force-sync-tags to write or update sync tags for all matched tracks without re-transferring audio:

podkit sync --force-sync-tags

This is a metadata-only operation. It’s useful for:

Establishing sync tags on a library that was synced before sync tags existed
Populating artwork fingerprints for artwork change detection (combine with --check-artwork)

# Write sync tags and artwork fingerprints in one pass
podkit sync --force-sync-tags --check-artwork

How Sync Tags Are Used

Preset change detection

When you change your quality preset (e.g., medium to high), podkit compares the new target settings against each track’s sync tag. If they don’t match, the track is re-transcoded.

Without sync tags, podkit falls back to comparing the track’s bitrate against the target bitrate using a percentage tolerance (30% for VBR, 10% for CBR). This works but is less precise — VBR encoding naturally produces variable bitrates that can trigger false re-transcodes. Sync tags eliminate this ambiguity with an exact comparison.

Artwork change detection

When --check-artwork is enabled, podkit computes a fingerprint of each track’s current source artwork and compares it against the art field in the sync tag. A mismatch means the artwork has changed since the last sync. See Artwork for details.

Consistency

podkit device music reports sync tag consistency — how many tracks have complete sync tags:

Symbol	State	Meaning
`✓`	Consistent	Has sync tag with artwork fingerprint (or track has no artwork)
`◐`	Partial	Has sync tag but missing artwork fingerprint
`✗`	Missing	No sync tag at all

Tracks without sync tags still sync normally — they just use the bitrate tolerance fallback for preset change detection and can’t participate in artwork change detection.

Forward Compatibility

Sync tags are designed to be resilient to future changes:

The v1 version prefix means future tag formats won’t conflict with existing ones
Unknown fields are silently ignored during parsing
Unknown tag versions are left untouched