Skip to content

frontend: add iTunes gapless playback metadata (iTunSMPB) - #177

Merged
fabiangreffrath merged 1 commit into
knik0:masterfrom
nschimme:jules-8823638380961382221-0ffc6256
Aug 25, 2026
Merged

frontend: add iTunes gapless playback metadata (iTunSMPB)#177
fabiangreffrath merged 1 commit into
knik0:masterfrom
nschimme:jules-8823638380961382221-0ffc6256

Conversation

@nschimme

Copy link
Copy Markdown
Contributor

This PR adds support for iTunes-compatible gapless playback metadata (iTunSMPB) in MP4 container outputs and exposes exact encoder delay numbers via the public API.


End-User Impact

  • Seamless Track Transitions: Fixes micro-pauses, silent gaps, and clicks between songs when playing live albums, DJ mixes, or continuous concept albums on Apple Music, iTunes, and iOS devices.
  • Exact Audio Length: AAC encoders naturally introduce extra silent samples (priming delay and trailing padding) to pad frames. Media players will now read the iTunSMPB tag and skip those extra samples, ensuring audio track lengths match original source files down to the exact millisecond.
  • Correct HE-AAC Playback: Correctly accounts for complex internal buffering in HE-AAC audio streams so low-bitrate files won't cut off early or glitch on playback.

Technical Breakdown

  1. Exposes Encoder Delay via Public API (faac.h / libfaac)

    • Adds encoder_delay to faac_encoder_info to report priming delay in samples/channel at the output rate.
    • Calculates delay per profile (faacEncoderDelay):
      • LC-AAC: 1 frame of MDCT overlap (FRAME_LEN).
      • HE-AAC: SBR pipeline buffering minus resampler group delay (3 * FRAME_LEN - RESAMPLE_FILTER_LEN / 2).
    • Note on ABI: Adding encoder_delay to faac_encoder_info changes the struct size. Since we are already bumping the ABI version in this release, including this public API addition now is harmless and avoids needing another ABI bump later.
  2. Frontend Gapless Calculation (frontend/encode_engine.c)

    • Calculates exact priming delay and padding samples using input vs. output sample totals.
    • Passes gapless parameters directly to mp4_set_gapless().
  3. iTunes iTunSMPB Metadata (frontend/mp4write.c)

    • Formats and writes standard iTunSMPB hex strings under the com.apple.iTunes freeform atom in ilst.----.
    • Fixes put_tag_ext(): Corrects freeform atom structure to write a single data child atom inside ilst.---- for spec compliance.

Verification

image

Calculate encoder priming delay and trailing padding in
frontend/encode_engine.c and write standard iTunes gapless playback
metadata (iTunSMPB) in frontend/mp4write.c for MP4 container outputs.

Priming delay comes from a new faac_encoder_info.encoder_delay field
(libfaac/faac.c), resolved per object type: one frame of MDCT overlap
for LC, plus the SBR/resample pipeline's extra buffering for HE-AAC.
Both values verified against decoded output (impulse test) across
sample rates, bitrates, and channel counts, not derived from spec.

Fix freeform atom generation in put_tag_ext() to emit a single data
atom child inside ilst.----.
@fabiangreffrath
fabiangreffrath merged commit b6d4ca3 into knik0:master Aug 25, 2026
7 checks passed
@nschimme
nschimme deleted the jules-8823638380961382221-0ffc6256 branch August 25, 2026 12:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants