Skip to content

frontend: add sample-accurate gapless MP4 decoding - #238

Merged
fabiangreffrath merged 1 commit into
knik0:masterfrom
nschimme:fix-gapless-decoding-cli-tags
Aug 27, 2026
Merged

frontend: add sample-accurate gapless MP4 decoding#238
fabiangreffrath merged 1 commit into
knik0:masterfrom
nschimme:fix-gapless-decoding-cli-tags

Conversation

@nschimme

Copy link
Copy Markdown
Contributor

This is a new feature to ease automated regression testing and eliminate extra padding that reference .wav files didn't have.

This PR adds sample-accurate gapless MP4 trimming via elst edit lists (with fallback to iTunSMPB metadata tags), fixes -g flag parsing, and hardens MP4 metadata atom handling.

It incorporates two critical rate-domain fixes discovered during reference testing against FFmpeg and Apple's AudioToolbox (afconvert):

  • Dynamic Frame-Size Trimming: Replaces the hardcoded 1024-sample front-trim offset (net_start_trim = gapless_delay - 1024) with the actual framesize calculated from the Audio Specific Config (ASC). The fixed 1024 offset was causing 1-frame over-trimming on SBR/HE-AAC streams.
  • Implicit SBR Rate Rescaling: Rescales gapless_delay and valid sample counts when container timescales match the core (pre-SBR) rate rather than the output rate. This resolves output truncation on files authored via fdkaac or afconvert.

Verification & Proof of Safety

Trim boundaries were verified for sample accuracy by decoding test files from multiple encoders across faad2, ffmpeg, and Apple's afconvert, then measuring sample counts and RMS alignment against the raw uncompressed source:

Source Encoder Profile Content faad2 Samples ffmpeg Samples Source Match RMS-Optimal Shift
FAAC LC Synthetic + Speech/Noise Exact match Exact match Exact match 0
FAAC HE-AAC Synthetic + Speech/Noise Exact match Exact match Exact match 0
ffmpeg (native) LC Synthetic Exact match Exact match Exact match 0
fdkaac HE-AAC Synthetic + Speech Exact match (±1)* Exact match ≈ Match 0
Apple afconvert LC, HE-AAC Synthetic + Speech Exact match (±1)* Exact match ≈ Match 0

*Matches Apple's native sample-rounding behavior.

Key Impact

  • RMS Shift = 0: Confirms sample-accurate boundary trimming. Shifting decoded PCM output by ±1024 or ±2048 samples increases error by 50–80×.
  • HE-AAC: Resolves the ~50% audio truncation bug on core-rate timescale files (fdkaac, afconvert) and eliminates the 1-frame over-trim on all SBR streams.
  • LC Streams: Zero regression; standard AAC-LC output remains unaffected.

Test Checklist

  • Builds cleanly (cmake + ninja) on current master.
  • Verified sample count and RMS alignment against ffmpeg for all encoder/profile permutations.
  • Verified sample count against afconvert / aac_at for fdkaac and afconvert files.
  • Validated LC output regression neutrality.

Implement sample-accurate MP4 gapless trimming via 'elst' edit lists
and 'iTunSMPB' metadata tags.

- Dynamic frame-size trimming: Use ASC 'framesize' for front-trim
  calculation instead of a fixed 1024-sample offset.
- Implicit SBR rate rescaling: Rescale delay and valid sample counts
  when container timescale matches the core rate rather than output rate.
- Fix `-g` flag parsing and harden MP4 metadata atom parsing ('hdlr', '----').
@nschimme nschimme mentioned this pull request Aug 27, 2026
@fabiangreffrath
fabiangreffrath merged commit 3fbf62c into knik0:master Aug 27, 2026
6 checks passed
@nschimme
nschimme deleted the fix-gapless-decoding-cli-tags branch August 27, 2026 13:56
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