audiowaveform 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31dd551b71c1465095aca4ead96165c3c1920fc2ef2825092def2eee860a9f13
-  data.tar.gz: 3bdef833753c357a394c0d521954781b641c061037b86478c6cf8ec7eb1762d2
+  metadata.gz: eb87df06de7ce7961d87d2767b4c95aae8adbaec3f8b1db21bebf25a9ab4a9da
+  data.tar.gz: 223edeea93936a8d61b59bd55fa3bd7950eb41b76d1a9d1410ea2bdf201e045b
 SHA512:
-  metadata.gz: 240d389339b46118b7ff7e1868ebee7c3dd35feb65361711b5b4832fc96af79450f283d979c9eb3d47eabe83a4b1f1503cdb227836374c981526f889aabdf210
-  data.tar.gz: 35b3317544ecc55b8d8d83b6b286466776f93afa2c775d4dcd2e3d725239647e033a9bd2dad42b9f8cc2c72e25aff95b9f5614dbbd135182fb6d2358a7aaf57a
+  metadata.gz: 9c9323f816013d497dab718a9232d46dd830cd03ae78c6cb3d6d5e8ff5c407ffc325119e23de75da454c0e409d0e8f466726928284302a88a4ec6559b7b55b5c
+  data.tar.gz: 855a327090b96e12dd25620817e886da8086c0acf265a923279f3a25695970086156a104a3cdbc68a5d31c31e9087c75add7934ddd652f4103a424f510f4cf7f

data/PROVENANCE.md

@@ -91,3 +91,20 @@ repository's synthetic tone fixtures and their known source length, with no
 copied legacy golden arrays. Raw PCM conversion/streaming was implemented from
 standard signed PCM scaling, IEEE float encodings, and Rust byte-conversion APIs;
 no legacy raw-input implementation was used or copied.
+
+## AAC/MP4 timing follow-up
+
+The focused MP4 timing reader was written for this project using Apple's
+[AAC priming explanation](https://developer.apple.com/documentation/quicktime-file-format/background_aac_encoding),
+[edit-list format](https://developer.apple.com/documentation/quicktime-file-format/edit_list_atom),
+and time-to-sample/media/movie-header field definitions. Symphonia 0.6.1's
+registry source was consulted for track IDs, packet timestamps, and its current
+edit-list limitation; no parser implementation was copied. No legacy core code
+was read or reused for this change. New arithmetic tone/silence fixtures and
+encoding commands are recorded in `tests/build_aac_fixtures.py` and
+`tests/fixtures/aac/manifest.json`. Peak expectations use independent batch
+arithmetic over untrimmed Symphonia output sliced at known fixture boundaries.
+The compatibility follow-up adds an FFmpeg start-offset remux and newly
+constructed millisecond timing tables. Expected leading silence follows Apple's
+[empty-edit definition](https://developer.apple.com/documentation/quicktime-file-format/edit_list_atom/edit_list_table);
+timing uses the documented [media timescale](https://developer.apple.com/documentation/quicktime-file-format/media_header_atom/time_scale).

data/README.md

@@ -64,17 +64,18 @@ by Ruby and never run inside an unprotected native callback. See the
 ## Memory and cancellation
 
 Fixed resolution decodes once. Exact point counts also decode once for PCM/float
-WAV and native FLAC with an exact header frame count. The count and signal
-metadata are checked against the actual decoded audio. Missing/unsupported
-metadata uses a counting pass and replay of the same open file. If a header
-count disagrees, provisional peaks are discarded and the completed first pass
-supplies the actual count for replay: at most two decoding passes. Decoder
-errors, checksum failures, and truncation remain errors.
-
-This optimization never uses duration estimates and preserves the same peak
-boundaries and values. AAC/M4A, MP3, Ogg/WebM and other formats still use the
-two-pass path for exact points. Empty audio does not allocate the requested
-point count. Keep input files unchanged during generation; replay mismatches
+WAV and native FLAC with an exact header frame count, and for nonfragmented
+AAC/MP4 with parsed playback bounds. The count and signal metadata are checked
+against the actual playback frames. Missing/unsupported metadata uses a counting
+pass and replay of the same open file. If a count disagrees (including an AAC
+media end rounded past decoded EOF), provisional peaks are discarded and the
+completed first pass supplies the actual count for replay: at most two decoding
+passes. Decoder errors, checksum failures, and truncation remain errors.
+
+This optimization preserves the same peak boundaries and values. Raw ADTS AAC,
+fragmented MP4, MP3, Ogg/WebM and other formats still use the two-pass path for
+exact points. Empty audio does not allocate the requested point count. Keep
+input files unchanged during generation; replay mismatches
 in frame count, track, rate, or channel count are errors.
 
 A decoded-block scratch buffer and channel extrema are reused. Exact output
@@ -104,8 +105,22 @@ AAC-LC decoding targets mono/stereo. Multichannel AAC, HE-AAC, Opus, and Wave64
 are outside this revision. Codec availability is separate from container
 recognition. Decoder gapless trimming is enabled, removing delay/padding where
 Symphonia supplies it (including MP3 and Vorbis priming). Duration counts the
-frames actually delivered after trimming. AAC/MP4 edit-list trimming is still
-limited by the decoder, so AAC duration can differ from playback.
+playback frames retained after trimming, including silence from supported
+leading empty MP4 edits.
+
+For nonfragmented AAC/MP4, the core reads the selected track's edit list and
+sample timing table. It decodes priming packets normally, then excludes frames
+outside the playback range before counting or aggregating peaks in either pass.
+This supports leading empty edits followed by a single contiguous media edit
+at normal speed. Empty edits contribute silence on the playback timeline;
+genuine recorded silence is also preserved. Edit duration uses the movie
+timescale, and packet timestamps may be rounded by less than one media-clock
+tick. The sample table and available decoded frames cap the end. Coarse
+metadata can still round the reported playback duration.
+No edit means no assumed leading delay. Fragmented MP4 and iTunSMPB-only delay
+metadata are not covered; their duration can still differ from playback.
+Multiple media edits, empty edits after media, and non-unit playback rates
+return an error; decode those inputs to PCM externally and use `generate_pcm`.
 
 Track selection uses explicit default-audio flags exposed by Symphonia, then
 the first reported audio track. Unsupported selected audio is an error.

data/VALIDATION.md

@@ -199,3 +199,83 @@ The Ruby 0.4.0 version bump passes 72 Ruby tests / 1,393 assertions and RBS
 validation. The built `audiowaveform-0.4.0.gem` installs into an isolated gem
 directory and passes the contract vectors, codec matrix, PCM streaming, and
 MP3 gapless checks. Both unpublished Rust packages remain at 0.1.0.
+
+## AAC/MP4 playback trimming (unreleased)
+
+Local all-feature, no-default-feature, and M4A-only Rust tests pass, along with
+formatting and strict all-target Clippy for both workspaces. Ten parser tests
+cover edit-list/header versions 0/1, different movie/media/sample clocks, selected
+track IDs, partial packet boundaries, malformed/truncated atoms and timing
+tables, unsupported edits, overflow, cancellation, and shared-file cursor
+restoration. Nine integration tests decode newly generated AAC fixtures and
+compare peaks with independent batch arithmetic over the known playback slice.
+
+The 44.1 kHz 50 ms fixture decodes to 4,096 raw frames but retains exactly 2,205
+frames and 110 points. Other cases cover 32/48/88.2/96 kHz, one-frame and odd-length
+clips, mono/stereo, fixed/normalized gain, direct 8-bit output, true silence and
+silent edges, changed edit offsets (including 2,112), empty playback, absent
+edits, coarse movie-clock rounding, video before multiple audio tracks,
+impossible sample-table lengths, and the documented fragmented-MP4 fallback.
+Exact points and fixed-size buckets both use the same trimmed frame range.
+
+The metadata reader uses fixed-size stack buffers and seeks past media; it
+retains neither packet tables nor decoded audio. A manual comparison of 50 ms
+and 30-second mono AAC at 44.1 kHz, each producing 110 points, reports identical
+application capacities: 8,192 bytes of sample scratch and 456 bytes of
+peak/current storage. Decoder/container allocations are outside these figures.
+
+Ruby 4.0.5 passes 73 tests / 1,689 assertions and RBS validation. An isolated
+source-gem installation passes the numeric/codec/PCM checks plus an AAC check
+requiring a 50 ms duration and 110 points at 44.1, 88.2, and 96 kHz. This is a
+local development build of the unchanged 0.4.0 package version, not a published
+release.
+
+The compatibility follow-up covers leading empty edits (including versions 0/1
+and summed movie-clock durations), coarse media timestamps with and without an
+edit, and a final media timestamp rounded beyond the decoded sample count.
+An FFmpeg start-offset remux now yields a 150 ms waveform including its leading
+silence. Both passes use that same timeline. Millisecond-clock fixtures retain
+the frames inside their declared ranges without failing exact-time equality;
+rounding past decoded EOF is clamped, while full-tick jumps, cumulative drift,
+and larger shortages still fail. Source-gem smoke tests exercise both fixes.
+
+Increasing a leading empty edit to ten seconds preserves application buffer
+capacities with fixed and normalized gain at 110 points. A much larger empty
+edit is cancelled during generation in both resolution modes, without building
+a whole-gap sample buffer. The original 50 ms regression remains covered.
+
+Playback bounds use the initialized AAC decoder's sample rate from
+AudioSpecificConfig, which can differ from the container sample-entry rate.
+The 88.2 and 96 kHz fixtures failed with `AAC/MP4 sample rate changed` before
+this correction. They now retain exactly 4,410 and 4,800 frames, respectively,
+with peaks checked in both resolution modes and installed-gem coverage.
+
+Exact points now use those parsed bounds as a verified frame-count hint. The
+AAC fixture matrix checks one decoding pass, including 88.2/96 kHz, leading
+gaps, empty playback, and selected tracks following video, with unchanged peaks.
+The rounded-media-end fixture predicts 4,102 frames but actually supplies 4,096;
+it still uses two passes and matches the independent oracle with fixed and
+normalized gain. Fragmented MP4 also retains two passes. A truncated final AAC
+packet fails even when all requested playback frames (or an empty range) were
+already delivered. Existing buffer-capacity and cancellation checks still pass.
+
+Release-build comparison against `193f789` on an arm64 Mac, 48 kHz AAC at
+128 kbit/s and 110 exact points, with warm caches and alternating before/after
+processes. Values are median library wall times from five paired trials (three
+for 30 minutes), excluding a warmup generation in each process:
+
+| Input | Two passes | Verified one pass |
+| --- | ---: | ---: |
+| 50 ms mono | 0.419 ms | 0.209 ms |
+| 30 seconds mono | 28.69 ms | 17.79 ms |
+| 5 minutes mono | 309.93 ms | 173.28 ms |
+| 30 minutes mono | 1,741.00 ms | 1,069.14 ms |
+| 5 minutes stereo, mixed to mono | 413.75 ms | 242.39 ms |
+| 5 minutes mono, normalized | 283.62 ms | 173.16 ms |
+
+Longer inputs took 38–44% less time in these local measurements. Fixed buckets
+remain one-pass and measured 176.43 vs. 174.75 ms for five minutes. Mono scratch
+and peak/current capacities remain 8,192 and 456 bytes; normalized peaks use
+2,216 bytes and stereo scratch uses 16,384 bytes. Maximum measured process RSS
+was about 3.9 MiB. These timings are host-specific, not isolated-system results
+or a constant-memory guarantee for decoder/container internals.

data/bindings/ruby/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.1 (2026-09-22)
+
+- Generate exact `points:` for nonfragmented AAC/MP4 in one decoding pass using
+  parsed playback bounds and the decoder's resolved signal parameters. Verify
+  the actual count before returning peaks; rounded endpoints that overstate it
+  replay with the observed count. Fragmented MP4 and raw ADTS retain two passes.
+- Trim AAC/MP4 priming and padding from the selected track's edit list and
+  sample timing before counting frames or generating peaks. A 50 ms clip now
+  produces a 50 ms waveform with either exact points or fixed-size buckets.
+  Use the decoder's resolved sample rate, including 88.2 and 96 kHz AAC.
+  Keep streaming buffers and genuine silence; do not guess encoder delay.
+- Support leading empty edits followed by one contiguous, normal-speed media
+  edit in nonfragmented MP4. Render the leading gap as silence with bounded
+  buffers. Accept media-clock timestamp rounding without tolerating cumulative
+  drift or padding past the available decoded samples. Other complex edits
+  return an error; fragmented MP4 and iTunSMPB-only gapless metadata remain
+  outside this support.
+
 ## 0.4.0 (2026-09-21)
 
 - Generate exact `points:` in one decoding pass for PCM/float WAV and native

data/bindings/ruby/README.md

@@ -27,10 +27,12 @@ waveform.duration            # actual decoded seconds
 
 At most one resolution option may be non-nil. Each resolution is an Integer no
 larger than 4,294,967,295. Exact counts use one decoding pass for PCM/float WAV
-and native FLAC with an exact header frame count; the decoded count is verified.
-Other inputs use two passes on the same open file without requiring duration
-metadata. A mismatched header count discards provisional peaks and replays once
-using the count from that first pass. Decoding/corruption errors still fail.
+and native FLAC with an exact header frame count, and nonfragmented AAC/MP4
+with parsed playback bounds. The actual playback count is verified. Other inputs
+use two passes on the same open file without requiring duration metadata.
+A mismatched count, including AAC timestamp rounding beyond decoded EOF,
+discards provisional peaks and replays once using the count from that first
+pass. Decoding/corruption errors still fail.
 Results are unchanged, and no new keyword is required. Keep the file unchanged
 during the operation. This method accepts regular seekable files. Use `generate_pcm` below
 for raw PCM streams. Neither method fetches URLs.
@@ -104,7 +106,8 @@ at EOF and nonfinite float samples raise `AudioWaveform::Error`.
 - `sample_rate`, `channels`, `length` (`size`), `empty?`
 - `samples_per_pixel`: nominal frames per point. For exact-count timing use
   `duration / length`; bucket widths may differ by one source frame.
-- `duration` (`duration_seconds`): decoded frames divided by sample rate.
+- `duration` (`duration_seconds`): playback frames divided by sample rate,
+  including silence from supported leading empty MP4 edits.
 - `storage_bits` (`bits`): always 16.
 - `data(bits: 16)`: a new Array of signed integers, ordered by point, channel,
   then minimum/maximum. `bits: 8` converts with signed truncation by 256.
@@ -123,9 +126,15 @@ AAC/M4A, ALAC, MP1/MP2/MP3, AIFF, CAF, and Matroska/WebM audio codecs. Container
 recognition does not imply every codec is supported. Multichannel AAC, HE-AAC,
 Opus, and Wave64 are unsupported by file decoding; a caller-managed decoder can
 feed their PCM into `generate_pcm`. Decoder gapless trimming removes reported
-delay/padding, including MP3 and Vorbis priming. AAC/MP4 trimming remains limited
-by Symphonia, so decoded duration can differ from playback. See the root README
-for track-selection limits.
+delay/padding, including MP3 and Vorbis priming. Nonfragmented AAC/MP4 also trims
+to the selected track's single, normal-speed media edit and sample timing range
+in both passes. Leading empty edits contribute silence before the audio;
+intentional recorded silence is preserved. Rounded media timestamps are
+supported, though coarse metadata may still round duration slightly.
+Fragmented MP4 and iTunSMPB-only delay metadata remain unsupported for gapless
+trimming. Multiple media edits, empty edits after media, or non-unit playback
+rates raise `AudioWaveform::Error`; use external decoding and `generate_pcm`
+for those inputs. See the root README for track-selection limits.
 
 Version 0.3 removes exports and tightens argument coercion. PCM quantization and
 fixed-resolution duration also change; do not expect byte-identical 0.2 peaks.
@@ -145,7 +154,7 @@ ruby bindings/ruby/script/test_native_gem.rb PATH_TO_NATIVE_GEM
 
 The normal rake task compiles, runs contract/codec/GC/cancellation tests, and
 validates RBS. Source installation is checked with
-`ruby bindings/ruby/script/test_source_gem.rb pkg/audiowaveform-0.4.0.gem`.
+`ruby bindings/ruby/script/test_source_gem.rb pkg/audiowaveform-0.4.1.gem`.
 Native cross-builds and ABI checks are configured in `.github/workflows`.
 
 Release tags use `ruby-vX.Y.Z`. The release workflow verifies the tag against

data/bindings/ruby/lib/audiowaveform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AudioWaveform
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/contract/SPEC.md

@@ -1,6 +1,6 @@
-# Audio peak generation contract, revision 2
+# Audio peak generation contract, revision 3
 
-Updated for Ruby 0.4.0 with gapless trimming, raw PCM, and exact-count metadata. Normative
+Updated after Ruby 0.4.0 with AAC/MP4 playback trimming. Normative
 requirements below apply to the library. No BBC command-line, file-format,
 rendering, or byte-for-byte implementation compatibility is required.
 
@@ -11,8 +11,9 @@ PCM stream and returns waveform peaks in memory. A frame is one time instant con
 channel. A point is a minimum/maximum pair for each output channel. Resolution
 arguments count **frames**, despite the historical `samples_per_pixel` name.
 
-Let `N` be the actual number of decoded frames, `F` the positive sample rate,
-and `C` the output channel count. Container duration estimates must not determine
+Let `N` be the number of playback frames (retained decoded frames plus silence
+from supported leading empty edits), `F` the positive sample rate,
+and `C` the output channel count. General container duration estimates must not determine
 `N`, point boundaries, or the returned duration. Channel count and sample rate
 must remain constant throughout the selected track; otherwise return an error.
 
@@ -28,12 +29,34 @@ This is an acceptance target, not a claim of completed decoder coverage.
 Codec availability is distinct from container recognition. Multichannel AAC,
 HE-AAC, Opus, and Wave64 are not required for the first replacement.
 
-Enable decoder-provided gapless trimming. `N` counts frames actually delivered
-by the decoder after trimming; count and aggregation passes use identical
+Enable decoder-provided gapless trimming. Count and aggregation passes use identical
 settings. Do not manually subtract delay a second time. MP3 delay/padding and
 Vorbis priming must not create extra leading buckets. Available trimming depends
-on the codec/container metadata exposed by Symphonia; AAC/MP4 edit-list handling
-remains a documented limitation. Raw PCM receives no automatic trimming.
+on the codec/container metadata exposed by Symphonia, with this additional rule:
+nonfragmented AAC/MP4 uses the selected track's media timescale, time-to-sample
+table, and optional single unit-rate media edit, preceded by zero or more empty
+edits. Decode all packets, including priming,
+but retain only frames whose timestamps lie in that half-open playback range,
+capped at the sample table's end. Apply the same range in each pass. Never infer
+delay from silence or a fixed encoder-specific constant. Missing edits mean no
+assumed encoder delay. Sum leading empty-edit durations in movie ticks before
+converting to frames (rounding up), and prepend that many zero frames using
+bounded buffers. Those frames are part of `N`, duration, and bucket placement.
+Allow absolute packet timestamps to differ from decoded time by less than one
+media-clock tick, without accumulating that allowance per packet. A media end
+rounded beyond decoded audio by less than one tick is clamped to the actual
+end; larger shortages remain errors. Sample-rate clocks retain exact checks.
+Reject multiple media edits, empty edits after media, dwell/non-unit rates, and
+inconsistent packet timing. Fragmented MP4 retains the decoder timeline; iTunSMPB-only delay
+metadata is not interpreted. Raw PCM receives no automatic trimming.
+
+For exact points, use parsed nonfragmented AAC/MP4 bounds to generate provisional
+peaks in one pass with `N = end - start + leading_frames`. Use the initialized
+decoder's sample rate and channel layout. Verify the observed playback count
+before returning those peaks. If a rounded endpoint overstates the count,
+discard provisional peaks and replay using the observed count; retain all
+decoding and timing checks, including after the playback range ends. Fragmented
+MP4 and raw ADTS AAC keep the two-pass path.
 
 ## 2. Ruby generation API
 

data/src/decode.rs

@@ -8,8 +8,8 @@ use symphonia::core::{
     codecs::audio::{
         AudioDecoder, AudioDecoderOptions,
         well_known::{
-            CODEC_ID_FLAC, CODEC_ID_PCM_F32LE, CODEC_ID_PCM_F64LE, CODEC_ID_PCM_S16LE,
-            CODEC_ID_PCM_S24LE, CODEC_ID_PCM_S32LE, CODEC_ID_PCM_U8,
+            CODEC_ID_AAC, CODEC_ID_FLAC, CODEC_ID_PCM_F32LE, CODEC_ID_PCM_F64LE,
+            CODEC_ID_PCM_S16LE, CODEC_ID_PCM_S24LE, CODEC_ID_PCM_S32LE, CODEC_ID_PCM_U8,
         },
     },
     formats::{FormatReader, TrackFlags, TrackType, probe::Hint},
@@ -52,16 +52,18 @@ fn generate_inner(
     #[cfg(feature = "wav")]
     crate::wave_header::validate(&mut file, &mut cancelled)?;
     file.seek(SeekFrom::Start(0))?;
+    let metadata = file.try_clone()?;
     let stream = MediaSourceStream::new(Box::new(file), Default::default());
     let mut hint = Hint::new();
     if let Some(extension) = path.extension().and_then(|ext| ext.to_str()) {
         hint.with_extension(extension);
     }
-    let session = Session::open(stream, &hint)?;
+    let mut source = Source { hint, metadata };
+    let session = Session::open(stream, &mut source, &mut cancelled)?;
     let mut scratch = Vec::new();
     let (reducer, decode_passes) = match options.resolution {
         Resolution::Points(_) => {
-            reduce_points(session, options, &hint, &mut scratch, &mut cancelled)?
+            reduce_points(session, options, &mut source, &mut scratch, &mut cancelled)?
         }
         _ => (
             reduce_fixed(session, options, &mut scratch, &mut cancelled)?,
@@ -97,12 +99,12 @@ fn reduce_fixed(
 fn reduce_points(
     session: Session,
     options: Options,
-    hint: &Hint,
+    source: &mut Source,
     scratch: &mut Vec<f64>,
     cancelled: &mut impl FnMut() -> bool,
 ) -> Result<(Reducer, u8), Error> {
     let mut provisional = session
-        .exact_frame_count()
+        .frame_count_hint()
         .map(|expected| ProvisionalPoints {
             expected,
             reducer: None,
@@ -133,7 +135,7 @@ fn reduce_points(
     if counted.frames == 0 {
         return Ok((reducer, 1));
     }
-    replay(stream, hint, counted, &mut reducer, scratch, cancelled)?;
+    replay(stream, source, counted, &mut reducer, scratch, cancelled)?;
     Ok((reducer, 2))
 }
 
@@ -164,7 +166,7 @@ impl ProvisionalPoints {
 
 fn replay(
     mut stream: MediaSourceStream<'static>,
-    hint: &Hint,
+    source: &mut Source,
     counted: Scan,
     reducer: &mut Reducer,
     scratch: &mut Vec<f64>,
@@ -172,7 +174,7 @@ fn replay(
 ) -> Result<(), Error> {
     poll(cancelled)?;
     stream.seek(SeekFrom::Start(0))?;
-    let session = Session::open(stream, hint)?;
+    let session = Session::open(stream, source, cancelled)?;
     let (_, generated) = session.scan(scratch, cancelled, |progress, samples, cancel| {
         if progress.signal != counted.signal {
             return Err(Error::InputChanged);
@@ -192,16 +194,61 @@ struct Scan {
     track: u32,
 }
 
+fn resize_scratch(scratch: &mut Vec<f64>, size: usize) -> Result<(), Error> {
+    if size > scratch.len() {
+        scratch.try_reserve(size - scratch.len())?;
+    }
+    scratch.resize(size, 0.0);
+    Ok(())
+}
+
+/// Advance the playback timeline through empty edits using the same bounded
+/// buffer as decoded audio, including during the counting pass and replay.
+fn consume_silence<C: FnMut() -> bool>(
+    mut progress: Scan,
+    remaining: &mut u64,
+    scratch: &mut Vec<f64>,
+    cancelled: &mut C,
+    consume: &mut impl FnMut(Scan, &[f64], &mut C) -> Result<(), Error>,
+) -> Result<u64, Error> {
+    while *remaining > 0 {
+        poll(cancelled)?;
+        let count = (*remaining).min(1024) as usize;
+        let size = count
+            .checked_mul(progress.signal.channels)
+            .ok_or(Error::SizeOverflow)?;
+        resize_scratch(scratch, size)?;
+        scratch.fill(0.0);
+        progress.frames = progress
+            .frames
+            .checked_add(count as u64)
+            .ok_or(Error::SizeOverflow)?;
+        consume(progress, scratch, cancelled)?;
+        *remaining -= count as u64;
+    }
+    Ok(progress.frames)
+}
+
+struct Source {
+    hint: Hint,
+    metadata: File,
+}
+
 struct Session {
+    playback: Option<crate::mp4::Playback>,
     format: Box<dyn FormatReader>,
     decoder: Box<dyn AudioDecoder>,
     track: u32,
 }
 
 impl Session {
-    fn open(stream: MediaSourceStream<'static>, hint: &Hint) -> Result<Self, Error> {
+    fn open(
+        stream: MediaSourceStream<'static>,
+        source: &mut Source,
+        cancelled: &mut impl FnMut() -> bool,
+    ) -> Result<Self, Error> {
         let format = symphonia::default::get_probe().probe(
-            hint,
+            &source.hint,
             stream,
             Default::default(),
             Default::default(),
@@ -227,23 +274,57 @@ impl Session {
             .as_ref()
             .and_then(|params| params.audio())
             .ok_or(Error::InvalidAudio("missing audio codec parameters"))?;
+        let aac_mp4 = format.format_info().short_name == "isomp4" && params.codec == CODEC_ID_AAC;
         let decoder = symphonia::default::get_codecs().make_audio_decoder(
             params,
-            &AudioDecoderOptions::default().gapless(true).verify(true),
+            // This layer owns AAC/MP4 trimming, including the untrimmed fallback
+            // for fragmented files. Other codecs keep the decoder's gapless mode.
+            &AudioDecoderOptions::default()
+                .gapless(!aac_mp4)
+                .verify(true),
         )?;
+        let playback = if aac_mp4 {
+            crate::mp4::playback(
+                &mut source.metadata,
+                track.id,
+                // AudioSpecificConfig can override the container sample-entry
+                // rate, notably above the 16.16 field's 65,535 Hz limit.
+                decoder
+                    .codec_params()
+                    .sample_rate
+                    .filter(|rate| *rate > 0)
+                    .ok_or(Error::InvalidAudio("AAC/MP4 has no sample rate"))?,
+                cancelled,
+            )?
+        } else {
+            None
+        };
         let track = track.id;
         Ok(Self {
+            playback,
             format,
             decoder,
             track,
         })
     }
 
-    /// Only native FLAC STREAMINFO and WAV PCM data extents have been audited
-    /// as exact frame counts here. Container durations, ADPCM block counts,
-    /// and counts affected by lossy codec delay/padding are not trusted.
-    /// Even these hints are checked against all frames actually decoded.
-    fn exact_frame_count(&self) -> Option<Scan> {
+    /// Audited counts from WAV PCM extents, native FLAC STREAMINFO, or parsed
+    /// AAC/MP4 playback bounds. Every hint is checked against actual playback
+    /// frames before returning peaks; other container durations are not used.
+    fn frame_count_hint(&self) -> Option<Scan> {
+        if let Some(playback) = self.playback {
+            // Use the decoder's resolved channel layout, just as playback
+            // bounds use its sample rate instead of the container entry's.
+            let channels = self.decoder.codec_params().channels.as_ref()?.count();
+            return (channels > 0).then_some(Scan {
+                signal: Signal {
+                    rate: playback.rate,
+                    channels,
+                },
+                frames: playback.frame_count(),
+                track: self.track,
+            });
+        }
         let track = self
             .format
             .tracks()
@@ -285,6 +366,8 @@ impl Session {
     ) -> Result<(MediaSourceStream<'static>, Scan), Error> {
         let mut observed = None;
         let mut frames = 0_u64;
+        let mut decoded_frames = 0_u64;
+        let mut leading = self.playback.map_or(0, |playback| playback.leading_frames);
         let mut demux_error = None;
         loop {
             poll(cancelled)?;
@@ -314,17 +397,40 @@ impl Session {
                 return Err(Error::InvalidAudio("sample rate or channel count changed"));
             }
             observed = Some(signal);
+            let range = match self.playback {
+                Some(playback) => {
+                    if signal.rate != playback.rate {
+                        return Err(Error::InvalidAudio("AAC/MP4 sample rate changed"));
+                    }
+                    playback.slice(decoded_frames, decoded.frames(), packet.pts.get())?
+                }
+                None => 0..decoded.frames(),
+            };
+            decoded_frames = decoded_frames
+                .checked_add(u64::try_from(decoded.frames()).map_err(|_| Error::SizeOverflow)?)
+                .ok_or(Error::SizeOverflow)?;
+            frames = consume_silence(
+                Scan {
+                    signal,
+                    frames,
+                    track: self.track,
+                },
+                &mut leading,
+                scratch,
+                cancelled,
+                &mut consume,
+            )?;
+            if range.is_empty() {
+                continue;
+            }
             let size = decoded
                 .frames()
                 .checked_mul(signal.channels)
                 .ok_or(Error::SizeOverflow)?;
-            if size > scratch.len() {
-                scratch.try_reserve(size - scratch.len())?;
-            }
-            scratch.resize(size, 0.0);
+            resize_scratch(scratch, size)?;
             decoded.copy_to_slice_interleaved(scratch.as_mut_slice());
             frames = frames
-                .checked_add(u64::try_from(decoded.frames()).map_err(|_| Error::SizeOverflow)?)
+                .checked_add(u64::try_from(range.len()).map_err(|_| Error::SizeOverflow)?)
                 .ok_or(Error::SizeOverflow)?;
             consume(
                 Scan {
@@ -332,7 +438,7 @@ impl Session {
                     frames,
                     track: self.track,
                 },
-                scratch,
+                &scratch[range.start * signal.channels..range.end * signal.channels],
                 cancelled,
             )?;
         }
@@ -374,6 +480,22 @@ impl Session {
                 Signal { rate, channels }
             }
         };
+        // Empty media may still have a declared leading gap and valid signal
+        // metadata; emit that timeline even when no decoder block was returned.
+        frames = consume_silence(
+            Scan {
+                signal,
+                frames,
+                track: self.track,
+            },
+            &mut leading,
+            scratch,
+            cancelled,
+            &mut consume,
+        )?;
+        if let Some(playback) = self.playback {
+            playback.verify(decoded_frames, frames)?;
+        }
         Ok((
             stream,
             Scan {

data/src/lib.rs

@@ -17,6 +17,7 @@ mod decode;
 mod error;
 #[cfg(feature = "mkv")]
 mod matroska;
+mod mp4;
 mod options;
 mod pcm;
 mod reduce;

data/src/mp4/tests.rs

@@ -0,0 +1,311 @@
+use super::*;
+use std::io::{Cursor, Write};
+
+fn atom(kind: &[u8; 4], data: &[u8]) -> Vec<u8> {
+    let mut result = ((data.len() + 8) as u32).to_be_bytes().to_vec();
+    result.extend(kind);
+    result.extend(data);
+    result
+}
+
+fn header(kind: &[u8; 4], version: u8, value: u32) -> Vec<u8> {
+    let mut data = vec![0; if version == 0 { 12 } else { 20 }];
+    data[0] = version;
+    data.extend(value.to_be_bytes());
+    atom(kind, &data)
+}
+
+fn edit(version: u8, entries: &[(u64, i64, u32)]) -> Vec<u8> {
+    let mut data = vec![version, 0, 0, 0];
+    data.extend((entries.len() as u32).to_be_bytes());
+    for &(duration, start, rate) in entries {
+        if version == 0 {
+            data.extend((duration as u32).to_be_bytes());
+            data.extend((start as i32).to_be_bytes());
+        } else {
+            data.extend(duration.to_be_bytes());
+            data.extend(start.to_be_bytes());
+        }
+        data.extend(rate.to_be_bytes());
+    }
+    atom(b"edts", &atom(b"elst", &data))
+}
+
+fn track(id: u32, version: u8, scale: u32, timing: &[(u32, u32)], edits: &[u8]) -> Vec<u8> {
+    let mut times = vec![0; 4];
+    times.extend((timing.len() as u32).to_be_bytes());
+    for (count, delta) in timing {
+        times.extend(count.to_be_bytes());
+        times.extend(delta.to_be_bytes());
+    }
+    let mut media = header(b"mdhd", version, scale);
+    media.extend(atom(b"minf", &atom(b"stbl", &atom(b"stts", &times))));
+    let mut data = header(b"tkhd", version, id);
+    data.extend(atom(b"mdia", &media));
+    data.extend(edits);
+    atom(b"trak", &data)
+}
+
+fn movie(version: u8, scale: u32, tracks: &[u8]) -> Vec<u8> {
+    let mut data = header(b"mvhd", version, scale);
+    data.extend(tracks);
+    atom(b"moov", &data)
+}
+
+fn parse(bytes: &[u8], id: u32, rate: u32) -> Result<Playback, Error> {
+    Parser {
+        input: &mut Cursor::new(bytes),
+        cancelled: &mut || false,
+    }
+    .playback(bytes.len() as u64, id, rate)
+    .map(Option::unwrap)
+}
+
+#[test]
+fn versions_clocks_and_selected_track() {
+    for version in [0, 1] {
+        // An unrelated track has an unsupported edit. Only id 7 applies.
+        let mut tracks = track(
+            3,
+            version,
+            48000,
+            &[(1, 500)],
+            &edit(version, &[(20, -1, 65536)]),
+        );
+        tracks.extend(track(
+            7,
+            version,
+            88200,
+            &[(3, 2048), (1, 314)],
+            &edit(version, &[(51, 2048, 65536)]),
+        ));
+        let bounds = parse(&movie(version, 1000, &tracks), 7, 44100).unwrap();
+        assert_eq!(
+            (bounds.start, bounds.end, bounds.minimum_decoded_frames),
+            (1024, 3229, 3229)
+        );
+        assert_eq!(bounds.slice(0, 1024, 0).unwrap(), 1024..1024);
+        assert_eq!(bounds.slice(1024, 1024, 2048).unwrap(), 0..1024);
+        assert_eq!(bounds.slice(3072, 1024, 6144).unwrap(), 0..157);
+        assert_eq!(bounds.slice(4096, 1024, 8192).unwrap(), 0..0);
+        assert!(bounds.slice(1024, 1024, 1024).is_err());
+        assert!(bounds.slice(0, 1024, -1).is_err());
+        assert!(bounds.verify(4096, 2205).is_ok());
+        assert!(bounds.verify(3072, 2205).is_err());
+        assert!(bounds.verify(4096, 2204).is_err());
+    }
+}
+
+#[test]
+fn edit_end_is_added_before_rounding_and_can_cut_within_a_packet() {
+    let bytes = movie(
+        0,
+        10,
+        &track(1, 0, 3, &[(3, 3)], &edit(0, &[(1, 1, 65536)])),
+    );
+    let bounds = parse(&bytes, 1, 10).unwrap();
+    assert_eq!((bounds.start, bounds.end), (4, 5)); // ceil(10/3), ceil(10/3 + 1)
+    assert_eq!(bounds.slice(0, 10, 0).unwrap(), 4..5);
+}
+
+#[test]
+fn absent_and_empty_edit_use_sample_table_duration() {
+    for edits in [vec![], edit(0, &[])] {
+        let bytes = movie(
+            0,
+            44100,
+            &track(1, 0, 44100, &[(3, 1024), (1, 157)], &edits),
+        );
+        let bounds = parse(&bytes, 1, 44100).unwrap();
+        assert_eq!((bounds.start, bounds.end), (0, 3229));
+    }
+}
+
+#[test]
+fn complex_edits_and_ranges_beyond_media_are_rejected() {
+    for version in [0, 1] {
+        for entries in [
+            vec![(50, -1, 65536)],
+            vec![(50, 1024, 0)],
+            vec![(50, 1024, 131072)],
+            vec![(50, 0, 65536), (50, 1024, 65536)],
+            vec![(50, 1024, 65536), (50, -1, 65536)],
+            vec![(50, -2, 65536), (50, 1024, 65536)],
+            vec![(50, 5000, 65536)],
+        ] {
+            let bytes = movie(
+                version,
+                1000,
+                &track(1, version, 44100, &[(4, 1024)], &edit(version, &entries)),
+            );
+            assert!(matches!(
+                parse(&bytes, 1, 44100),
+                Err(Error::InvalidAudio(_))
+            ));
+        }
+    }
+}
+
+#[test]
+fn leading_empty_edits_advance_movie_time_without_changing_media_range() {
+    for version in [0, 1] {
+        let edits = edit(
+            version,
+            &[(33, -1, 65536), (67, -1, 65536), (50, 1024, 65536)],
+        );
+        let bytes = movie(
+            version,
+            1000,
+            &track(1, version, 44100, &[(3, 1024), (1, 157)], &edits),
+        );
+        let bounds = parse(&bytes, 1, 44100).unwrap();
+        assert_eq!(
+            (bounds.start, bounds.end, bounds.leading_frames),
+            (1024, 3229, 4410)
+        );
+        assert!(bounds.verify(4096, 6615).is_ok());
+        assert!(bounds.verify(4096, 2205).is_err());
+    }
+    // Sum movie ticks before converting so several short gaps do not each add
+    // another rounded frame. Metadata remains constant-size for many edits.
+    let bytes = movie(
+        0,
+        3,
+        &track(
+            1,
+            0,
+            10,
+            &[(1, 10)],
+            &edit(0, &[(1, -1, 65536), (1, -1, 65536), (1, 0, 65536)]),
+        ),
+    );
+    assert_eq!(parse(&bytes, 1, 10).unwrap().leading_frames, 7);
+
+    let huge = movie(
+        1,
+        1,
+        &track(
+            1,
+            1,
+            44100,
+            &[(1, 1024)],
+            &edit(1, &[(u64::MAX, -1, 65536), (1, -1, 65536), (1, 0, 65536)]),
+        ),
+    );
+    assert!(matches!(parse(&huge, 1, 44100), Err(Error::SizeOverflow)));
+}
+
+#[test]
+fn rounded_media_timestamps_allow_less_than_one_tick_without_accumulating_drift() {
+    let bytes = movie(
+        0,
+        1000,
+        &track(1, 0, 1000, &[(2, 23), (1, 24), (1, 3)], &[]),
+    );
+    let bounds = parse(&bytes, 1, 44100).unwrap();
+    for (position, timestamp) in [(0, 0), (1024, 23), (2048, 46), (3072, 70)] {
+        assert!(bounds.slice(position, 1024, timestamp).is_ok());
+    }
+    assert!(bounds.slice(1024, 1024, 24).is_ok()); // rounded upward
+    assert!(bounds.slice(1024, 1024, 22).is_err());
+    assert!(bounds.slice(1024, 1024, 25).is_err());
+    assert!(bounds.slice(44100, 1024, 1001).is_err()); // exactly one tick
+    assert!(bounds.slice(3072, 1024, 69).is_ok());
+    assert!(bounds.slice(4096, 1024, 92).is_ok());
+    assert!(bounds.slice(5120, 1024, 115).is_err()); // repeated 23-tick drift
+    assert_eq!(bounds.end, 3220);
+    assert!(bounds.verify(4096, 3220).is_ok());
+}
+
+#[test]
+fn rounded_media_end_is_clamped_to_decoded_frames_but_truncation_is_rejected() {
+    let bytes = movie(
+        0,
+        1000,
+        &track(1, 0, 1000, &[(2, 23), (1, 24), (1, 23)], &[]),
+    );
+    let bounds = parse(&bytes, 1, 44100).unwrap();
+    assert_eq!(bounds.end, 4102); // 93 ms, rounded beyond 4,096 decoded frames
+    assert!(bounds.verify(4096, 4096).is_ok());
+    assert!(bounds.verify(3072, 3072).is_err());
+    assert!(bounds.verify(4096, 4102).is_err());
+    let bytes = movie(0, 1000, &track(1, 0, 1000, &[(4, 24)], &[]));
+    assert!(parse(&bytes, 1, 44100).unwrap().verify(4096, 4096).is_err());
+    let exact = movie(0, 44100, &track(1, 0, 44100, &[(4, 1024)], &[]));
+    assert!(parse(&exact, 1, 44100).unwrap().verify(4095, 4095).is_err());
+}
+
+#[test]
+fn extended_and_open_ended_atoms_and_parent_bounds() {
+    let valid = movie(0, 44100, &track(1, 0, 44100, &[(2, 1024)], &[]));
+    let mut extended = 1_u32.to_be_bytes().to_vec();
+    extended.extend(b"moov");
+    extended.extend((valid.len() as u64 + 8).to_be_bytes());
+    extended.extend(&valid[8..]);
+    assert_eq!(parse(&extended, 1, 44100).unwrap().end, 2048);
+    let mut open = valid.clone();
+    open[..4].copy_from_slice(&0_u32.to_be_bytes());
+    assert_eq!(parse(&open, 1, 44100).unwrap().end, 2048);
+    for length in 0..valid.len() {
+        assert!(
+            parse(&valid[..length], 1, 44100).is_err(),
+            "length={length}"
+        );
+    }
+    for size in [4_u32, 7, u32::MAX] {
+        let mut bad = valid.clone();
+        bad[8..12].copy_from_slice(&size.to_be_bytes());
+        assert!(parse(&bad, 1, 44100).is_err());
+    }
+    let duplicate = [valid.clone(), valid].concat();
+    assert!(parse(&duplicate, 1, 44100).is_err());
+}
+
+#[test]
+fn invalid_timing_tables_and_overflow_are_errors() {
+    for scale in [0, 44100] {
+        let bytes = movie(0, scale, &track(1, 0, 0, &[], &[]));
+        assert!(parse(&bytes, 1, 44100).is_err());
+    }
+    let overflow = movie(
+        0,
+        44100,
+        &track(1, 0, 44100, &[(u32::MAX, u32::MAX); 3], &[]),
+    );
+    assert!(matches!(
+        parse(&overflow, 1, 44100),
+        Err(Error::SizeOverflow)
+    ));
+    let mut bad = movie(0, 44100, &track(1, 0, 44100, &[(2, 1024)], &[]));
+    let position = bad.windows(4).position(|x| x == b"stts").unwrap();
+    bad[position + 8..position + 12].copy_from_slice(&u32::MAX.to_be_bytes());
+    assert!(parse(&bad, 1, 44100).is_err());
+    let duplicate = movie(
+        0,
+        44100,
+        &[track(1, 0, 44100, &[], &[]), track(1, 0, 44100, &[], &[])].concat(),
+    );
+    assert!(parse(&duplicate, 1, 44100).is_err());
+}
+
+#[test]
+fn metadata_scan_restores_the_shared_file_position_on_success_error_and_cancellation() {
+    let bytes = movie(0, 44100, &track(1, 0, 44100, &[(4, 1024)], &[]));
+    let mut file = tempfile::tempfile().unwrap();
+    file.write_all(&bytes).unwrap();
+    file.seek(SeekFrom::Start(11)).unwrap();
+    let mut clone = file.try_clone().unwrap();
+    assert!(playback(&mut clone, 1, 44100, &mut || false).is_ok());
+    assert_eq!(file.stream_position().unwrap(), 11);
+    assert!(playback(&mut clone, 9, 44100, &mut || false).is_err());
+    assert_eq!(file.stream_position().unwrap(), 11);
+    let mut calls = 0;
+    assert!(matches!(
+        playback(&mut clone, 1, 44100, &mut || {
+            calls += 1;
+            calls == 5
+        }),
+        Err(Error::Cancelled)
+    ));
+    assert_eq!(file.stream_position().unwrap(), 11);
+}

data/src/mp4.rs

@@ -0,0 +1,376 @@
+//! AAC playback bounds from ISO BMFF timing, without loading media or tables.
+//! Supports leading empty edits and one contiguous, unit-rate media segment.
+//! References:
+//! <https://developer.apple.com/documentation/quicktime-file-format/edit_list_atom>
+//! <https://developer.apple.com/documentation/quicktime-file-format/time-to-sample_atom>
+
+use std::{
+    fs::File,
+    io::{Read, Seek, SeekFrom},
+    ops::Range,
+};
+
+use crate::{Error, error::poll};
+
+const INVALID: Error = Error::InvalidAudio("invalid MP4 playback timing");
+const UNSUPPORTED_EDIT: Error = Error::InvalidAudio(
+    "AAC/MP4 requires a single unit-rate media edit; decode complex edits to PCM",
+);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Playback {
+    pub rate: u32,
+    timescale: u32,
+    start: u64,
+    end: u64,
+    minimum_decoded_frames: u64,
+    pub leading_frames: u64,
+}
+
+impl Playback {
+    /// Expected playback length, verified against actual frames at EOF. A
+    /// rounded media end can overstate this count and require peak generation
+    /// to replay using the smaller observed count.
+    pub fn frame_count(self) -> u64 {
+        // Parsing already checked the ordering and this sum for overflow.
+        self.end - self.start + self.leading_frames
+    }
+
+    pub fn slice(self, position: u64, frames: usize, pts: i64) -> Result<Range<usize>, Error> {
+        let timestamp = u64::try_from(pts).map_err(|_| INVALID)?;
+        // Packet boundaries may be rounded to media-clock ticks. Compare each
+        // absolute timestamp with decoded time, allowing less than one tick;
+        // do not accumulate a per-packet allowance that could hide real drift.
+        if (u128::from(timestamp) * u128::from(self.rate))
+            .abs_diff(u128::from(position) * u128::from(self.timescale))
+            >= u128::from(self.rate)
+        {
+            return Err(Error::InvalidAudio("non-contiguous AAC/MP4 sample timing"));
+        }
+        let length = u64::try_from(frames).map_err(|_| Error::SizeOverflow)?;
+        Ok(self.start.saturating_sub(position).min(length) as usize
+            ..self.end.saturating_sub(position).min(length) as usize)
+    }
+
+    pub fn verify(self, decoded: u64, retained: u64) -> Result<(), Error> {
+        // A coarse final timestamp can round slightly beyond the decoded end.
+        // Clamp to the frames actually available, never synthesize AAC padding.
+        let expected = self
+            .end
+            .min(decoded)
+            .saturating_sub(self.start)
+            .checked_add(self.leading_frames)
+            .ok_or(Error::SizeOverflow)?;
+        if decoded < self.minimum_decoded_frames || retained != expected {
+            return Err(Error::InvalidAudio("truncated AAC/MP4 playback range"));
+        }
+        Ok(())
+    }
+}
+
+/// `file` is a duplicate of the decoder's open file description. Restore its
+/// physical cursor before decoding resumes, including when metadata is invalid.
+/// No pathname is reopened, so both decoding passes keep using the same file.
+pub(crate) fn playback(
+    file: &mut File,
+    track: u32,
+    rate: u32,
+    cancelled: &mut impl FnMut() -> bool,
+) -> Result<Option<Playback>, Error> {
+    let saved = file.stream_position()?;
+    let length = file.metadata()?.len();
+    let result = Parser {
+        input: &mut *file,
+        cancelled,
+    }
+    .playback(length, track, rate);
+    let restored = file.seek(SeekFrom::Start(saved));
+    let result = result?;
+    restored?;
+    Ok(result)
+}
+
+#[derive(Clone, Copy)]
+struct Atom {
+    kind: [u8; 4],
+    data: u64,
+    end: u64,
+}
+
+struct Edit {
+    start: u64,
+    duration: u64,
+    leading: u64,
+}
+
+struct Parser<'a, R, C> {
+    input: &'a mut R,
+    cancelled: &'a mut C,
+}
+
+impl<R: Read + Seek, C: FnMut() -> bool> Parser<'_, R, C> {
+    fn playback(&mut self, length: u64, track: u32, rate: u32) -> Result<Option<Playback>, Error> {
+        let root = Atom {
+            kind: *b"root",
+            data: 0,
+            end: length,
+        };
+        let moov = self.required(root, *b"moov")?;
+        // Fragment sample timing lives in moof/trun, not this initial stts.
+        // Leave fragmented inputs on the existing decoded-frame timeline.
+        if self.find(moov, *b"mvex")?.is_some() {
+            return Ok(None);
+        }
+        let movie = self.required(moov, *b"mvhd")?;
+        let movie_scale = self.timescale(movie)?;
+        let mut selected = None;
+        let mut position = moov.data;
+        while position < moov.end {
+            let atom = self.atom(position, moov.end)?;
+            if atom.kind == *b"trak" {
+                let header = self.required(atom, *b"tkhd")?;
+                let offset = match self.version(header)? {
+                    0 => 12,
+                    1 => 20,
+                    _ => return Err(INVALID),
+                };
+                if u32::from_be_bytes(self.bytes(header, offset)?) == track
+                    && selected.replace(atom).is_some()
+                {
+                    return Err(INVALID);
+                }
+            }
+            position = atom.end;
+        }
+        let selected = selected.ok_or(INVALID)?;
+        let media = self.required(selected, *b"mdia")?;
+        let header = self.required(media, *b"mdhd")?;
+        let media_scale = self.timescale(header)?;
+        let info = self.required(media, *b"minf")?;
+        let table = self.required(info, *b"stbl")?;
+        let stts = self.required(table, *b"stts")?;
+        let media_duration = self.duration(stts)?;
+        let media_frames = frames(u128::from(media_duration), media_scale, rate)?;
+        let edit = match self.find(selected, *b"edts")? {
+            Some(edts) => match self.find(edts, *b"elst")? {
+                Some(elst) => self.edit(elst)?,
+                None => None,
+            },
+            None => None,
+        };
+        let (start, end, leading_frames) = match edit {
+            Some(Edit {
+                start,
+                duration,
+                leading,
+            }) => {
+                let start_frame = frames(u128::from(start), media_scale, rate)?;
+                // Add in rational time before rounding, and clamp rounded movie
+                // duration to the sample table's precise end of media.
+                let end_time = u128::from(start) * u128::from(movie_scale)
+                    + u128::from(duration) * u128::from(media_scale);
+                let numerator = end_time
+                    .checked_mul(u128::from(rate))
+                    .ok_or(Error::SizeOverflow)?;
+                let denominator = u128::from(movie_scale) * u128::from(media_scale);
+                let end_frame = u64::try_from(numerator.div_ceil(denominator))
+                    .map_err(|_| Error::SizeOverflow)?
+                    .min(media_frames);
+                (
+                    start_frame,
+                    end_frame,
+                    frames(u128::from(leading), movie_scale, rate)?,
+                )
+            }
+            None => (0, media_frames, 0),
+        };
+        if start > end {
+            return Err(INVALID);
+        }
+        // Require decoded time to lie strictly after the preceding media tick.
+        // With a sample-rate clock this still requires every declared frame.
+        let minimum_decoded_frames = if media_duration == 0 {
+            0
+        } else {
+            u64::try_from(
+                u128::from(media_duration - 1) * u128::from(rate) / u128::from(media_scale),
+            )
+            .map_err(|_| Error::SizeOverflow)?
+            .checked_add(1)
+            .ok_or(Error::SizeOverflow)?
+        };
+        leading_frames
+            .checked_add(end - start)
+            .ok_or(Error::SizeOverflow)?;
+        Ok(Some(Playback {
+            rate,
+            timescale: media_scale,
+            start,
+            end,
+            minimum_decoded_frames,
+            leading_frames,
+        }))
+    }
+
+    fn atom(&mut self, position: u64, limit: u64) -> Result<Atom, Error> {
+        poll(self.cancelled)?;
+        let remaining = limit.checked_sub(position).ok_or(INVALID)?;
+        if remaining < 8 {
+            return Err(INVALID);
+        }
+        self.input.seek(SeekFrom::Start(position))?;
+        let mut header = [0; 8];
+        self.input.read_exact(&mut header)?;
+        let short = u32::from_be_bytes(header[..4].try_into().unwrap());
+        let (size, width) = match short {
+            0 => (remaining, 8),
+            1 => {
+                if remaining < 16 {
+                    return Err(INVALID);
+                }
+                let mut size = [0; 8];
+                self.input.read_exact(&mut size)?;
+                (u64::from_be_bytes(size), 16)
+            }
+            n => (u64::from(n), 8),
+        };
+        if size < width || size > remaining {
+            return Err(INVALID);
+        }
+        Ok(Atom {
+            kind: header[4..].try_into().unwrap(),
+            data: position + width,
+            end: position + size,
+        })
+    }
+
+    fn find(&mut self, parent: Atom, kind: [u8; 4]) -> Result<Option<Atom>, Error> {
+        let mut found = None;
+        let mut position = parent.data;
+        while position < parent.end {
+            let atom = self.atom(position, parent.end)?;
+            if atom.kind == kind && found.replace(atom).is_some() {
+                return Err(INVALID);
+            }
+            position = atom.end;
+        }
+        Ok(found)
+    }
+
+    fn required(&mut self, parent: Atom, kind: [u8; 4]) -> Result<Atom, Error> {
+        self.find(parent, kind)?.ok_or(INVALID)
+    }
+
+    fn bytes<const N: usize>(&mut self, atom: Atom, offset: u64) -> Result<[u8; N], Error> {
+        let position = atom.data.checked_add(offset).ok_or(INVALID)?;
+        if position
+            .checked_add(N as u64)
+            .is_none_or(|end| end > atom.end)
+        {
+            return Err(INVALID);
+        }
+        self.input.seek(SeekFrom::Start(position))?;
+        let mut bytes = [0; N];
+        self.input.read_exact(&mut bytes)?;
+        Ok(bytes)
+    }
+
+    fn version(&mut self, atom: Atom) -> Result<u8, Error> {
+        let header = self.bytes::<4>(atom, 0)?;
+        if header[1..] != [0, 0, 0] && atom.kind != *b"tkhd" {
+            return Err(INVALID);
+        }
+        Ok(header[0])
+    }
+
+    fn timescale(&mut self, atom: Atom) -> Result<u32, Error> {
+        let offset = match self.version(atom)? {
+            0 => 12,
+            1 => 20,
+            _ => return Err(INVALID),
+        };
+        let value = u32::from_be_bytes(self.bytes(atom, offset)?);
+        if value == 0 {
+            return Err(INVALID);
+        }
+        Ok(value)
+    }
+
+    fn duration(&mut self, atom: Atom) -> Result<u64, Error> {
+        if self.version(atom)? != 0 {
+            return Err(INVALID);
+        }
+        let entries = u32::from_be_bytes(self.bytes(atom, 4)?);
+        if atom.end - atom.data != 8 + u64::from(entries) * 8 {
+            return Err(INVALID);
+        }
+        let mut duration = 0_u64;
+        for index in 0..entries {
+            poll(self.cancelled)?;
+            let entry = self.bytes::<8>(atom, 8 + u64::from(index) * 8)?;
+            let count = u32::from_be_bytes(entry[..4].try_into().unwrap());
+            let delta = u32::from_be_bytes(entry[4..].try_into().unwrap());
+            duration = duration
+                .checked_add(u64::from(count) * u64::from(delta))
+                .ok_or(Error::SizeOverflow)?;
+        }
+        Ok(duration)
+    }
+
+    fn edit(&mut self, atom: Atom) -> Result<Option<Edit>, Error> {
+        let version = self.version(atom)?;
+        let entries = u32::from_be_bytes(self.bytes(atom, 4)?);
+        let width = match version {
+            0 => 12,
+            1 => 20,
+            _ => return Err(INVALID),
+        };
+        if atom.end - atom.data != 8 + u64::from(entries) * width {
+            return Err(INVALID);
+        }
+        if entries == 0 {
+            return Ok(None);
+        }
+        let mut leading = 0_u64;
+        for index in 0..entries {
+            poll(self.cancelled)?;
+            let offset = 8 + u64::from(index) * width;
+            let (duration, start, rate) = match version {
+                0 => (
+                    u64::from(u32::from_be_bytes(self.bytes(atom, offset)?)),
+                    i64::from(i32::from_be_bytes(self.bytes(atom, offset + 4)?)),
+                    u32::from_be_bytes(self.bytes(atom, offset + 8)?),
+                ),
+                _ => (
+                    u64::from_be_bytes(self.bytes(atom, offset)?),
+                    i64::from_be_bytes(self.bytes(atom, offset + 8)?),
+                    u32::from_be_bytes(self.bytes(atom, offset + 16)?),
+                ),
+            };
+            if rate != 0x0001_0000 {
+                return Err(UNSUPPORTED_EDIT);
+            }
+            if start == -1 {
+                leading = leading.checked_add(duration).ok_or(Error::SizeOverflow)?;
+            } else if start >= 0 && index == entries - 1 {
+                return Ok(Some(Edit {
+                    start: start as u64,
+                    duration,
+                    leading,
+                }));
+            } else {
+                return Err(UNSUPPORTED_EDIT);
+            }
+        }
+        // A sequence of empty edits with no media segment has no audio range.
+        Err(UNSUPPORTED_EDIT)
+    }
+}
+
+fn frames(time: u128, scale: u32, rate: u32) -> Result<u64, Error> {
+    u64::try_from((time * u128::from(rate)).div_ceil(u128::from(scale)))
+        .map_err(|_| Error::SizeOverflow)
+}
+
+#[cfg(test)]
+mod tests;

data/src/waveform.rs

@@ -25,6 +25,7 @@ impl Waveform {
     pub fn channels(&self) -> usize {
         self.channels
     }
+    /// Playback frames after trimming, including supported MP4 leading silence.
     pub fn source_frames(&self) -> u64 {
         self.source_frames
     }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audiowaveform
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Andrii Dmytrenko
@@ -57,6 +57,8 @@ files:
 - src/error.rs
 - src/lib.rs
 - src/matroska.rs
+- src/mp4.rs
+- src/mp4/tests.rs
 - src/options.rs
 - src/pcm.rs
 - src/reduce.rs