audiowaveform 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb87df06de7ce7961d87d2767b4c95aae8adbaec3f8b1db21bebf25a9ab4a9da
-  data.tar.gz: 223edeea93936a8d61b59bd55fa3bd7950eb41b76d1a9d1410ea2bdf201e045b
+  metadata.gz: 1fcec27bd2209df4025fd9f56381076fc2cb5895eb16a21b8adaa8a3799cef0c
+  data.tar.gz: 55946fa15f894fd69e3e77ffdf20a9f5c648efe49c8155b19c75f89775d70f4e
 SHA512:
-  metadata.gz: 9c9323f816013d497dab718a9232d46dd830cd03ae78c6cb3d6d5e8ff5c407ffc325119e23de75da454c0e409d0e8f466726928284302a88a4ec6559b7b55b5c
-  data.tar.gz: 855a327090b96e12dd25620817e886da8086c0acf265a923279f3a25695970086156a104a3cdbc68a5d31c31e9087c75add7934ddd652f4103a424f510f4cf7f
+  metadata.gz: 2f00da3a08370cde0a4222930f7571db9c0e23ff0fb5577574e2b622f69bcb5df54a64b1ff5a48ca4e3634722cc47ff4de6715cdf6e5241efe22f766660b27cb
+  data.tar.gz: f7d628c44628243c53f940c24f7f63f942226597411ae8884ff6f5dadd54fe4280f968a248908d5c7d526d8531bf11a2258a7300f91ff9678b0fe4e14f8442b9

data/README.md

@@ -113,7 +113,11 @@ 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
+genuine recorded silence is also preserved. Short packet timing slots clip
+surplus decoded samples from that packet's tail; gaps between packets contribute
+silence. This handles recording timestamp jitter without rejecting valid audio.
+Gaps are emitted only when the next packet arrives, so an overstated final
+packet duration still fails validation. 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.

data/VALIDATION.md

@@ -279,3 +279,30 @@ 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.
+
+## AAC packet timing follow-up (Ruby 0.4.2)
+
+AAC/MP4 now places decoded packets in their declared sample-table slots:
+short slots clip packet tails, and gaps before a subsequent packet contribute
+silence. Sub-tick rounding preserves continuous PCM, while an overstated final
+packet duration still fails validation. Existing AAC fixture peaks are unchanged.
+
+Owned synthetic fixtures cover the 712/1,000-frame overlap pattern, a 5,120-frame
+gap, and mixed gaps/overlaps in stereo. Exact-count and fixed-resolution peaks,
+mono/split output, both gains, and both bit depths match an independent batch
+oracle. Larger gaps reuse buffer capacities and remain cancellable. Real timing
+changes on a coarse media clock are accepted without hiding truncated tails.
+
+Local validation on macOS arm64 with Rust 1.98.1 and Ruby 4.0.5 passes:
+all-feature and no-default-feature Rust tests, formatting, strict Clippy in both
+Cargo workspaces, and Ruby/RBS checks (73 tests, 1,749 assertions).
+
+A privately supplied failing voice recording was transcoded with FFmpeg's AAC
+encoder using `-map_metadata -1 -vn -c:a aac -q:a 2`. Version 0.4.1 rejects its
+non-contiguous timestamps. The patched core returns 609,264 frames at 48 kHz
+(12.693 seconds), 110 points, and one decode pass with 8,192 bytes of scratch.
+All 220 peaks match an independent FFmpeg decode after removing the two
+surplus packet tails (312 and 24 samples), at 8 and 16 bits with fixed gain and
+normalization. Unadjusted FFmpeg PCM is 7 ms longer; its 8-bit peaks differ in
+9 of 220 values at fixed gain (8 when normalized), by at most 4. The recording
+and its derived media remain outside the repository.

data/bindings/ruby/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.2 (2026-09-23)
+
+- Accept AAC/MP4 packet timing overlaps and gaps, including browser recordings
+  transcoded to AAC. Clip packets to shorter timing slots and render gaps as
+  silence with bounded, cancellable buffers. Preserve edit-list delay/padding
+  trimming, coarse-clock rounding, and truncated-tail validation. Continuous
+  inputs retain their existing peaks; valid exact-point counts use one pass.
+
 ## 0.4.1 (2026-09-22)
 
 - Generate exact `points:` for nonfragmented AAC/MP4 in one decoding pass using

data/bindings/ruby/README.md

@@ -129,8 +129,10 @@ feed their PCM into `generate_pcm`. Decoder gapless trimming removes reported
 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.
+intentional recorded silence is preserved. Short packet timing slots trim the
+packet's tail, and gaps between packets contribute silence. Rounded media
+timestamps are supported, though coarse metadata may still round duration
+slightly. An overstated final packet duration still raises an error.
 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`
@@ -154,7 +156,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.1.gem`.
+`ruby bindings/ruby/script/test_source_gem.rb pkg/audiowaveform-0.4.2.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.1"
+  VERSION = "0.4.2"
 end

data/contract/SPEC.md

@@ -1,6 +1,6 @@
 # Audio peak generation contract, revision 3
 
-Updated after Ruby 0.4.0 with AAC/MP4 playback trimming. Normative
+Updated after Ruby 0.4.1 with AAC/MP4 playback timing. Normative
 requirements below apply to the library. No BBC command-line, file-format,
 rendering, or byte-for-byte implementation compatibility is required.
 
@@ -12,7 +12,7 @@ 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 number of playback frames (retained decoded frames plus silence
-from supported leading empty edits), `F` the positive sample rate,
+from supported leading empty edits and gaps between AAC/MP4 packets), `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.
@@ -43,11 +43,16 @@ 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
+media-clock tick, without accumulating that allowance per packet. Outside that
+rounding tolerance, clip decoded packets to shorter sample-table slots and fill
+gaps before subsequent packets with silence, using bounded, cancellable buffers.
+Convert absolute boundaries to frames by rounding up. Apply playback-range
+trimming to both samples and silence. Never synthesize an unverified trailing
+gap: a media end rounded beyond available 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, negative timestamps, and backwards timing beyond the rounding tolerance.
+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

data/src/decode.rs

@@ -202,7 +202,7 @@ fn resize_scratch(scratch: &mut Vec<f64>, size: usize) -> Result<(), Error> {
     Ok(())
 }
 
-/// Advance the playback timeline through empty edits using the same bounded
+/// Advance the playback timeline through silence using the same bounded
 /// buffer as decoded audio, including during the counting pass and replay.
 fn consume_silence<C: FnMut() -> bool>(
     mut progress: Scan,
@@ -366,8 +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 media_end = 0_u64;
+        let mut silence = self.playback.map_or(0, |playback| playback.leading_frames);
         let mut demux_error = None;
         loop {
             poll(cancelled)?;
@@ -402,20 +402,27 @@ impl Session {
                     if signal.rate != playback.rate {
                         return Err(Error::InvalidAudio("AAC/MP4 sample rate changed"));
                     }
-                    playback.slice(decoded_frames, decoded.frames(), packet.pts.get())?
+                    let part = playback.packet(
+                        media_end,
+                        decoded.frames(),
+                        packet.pts.get(),
+                        packet.dur.get(),
+                    )?;
+                    media_end = part.end;
+                    silence = silence
+                        .checked_add(part.silence)
+                        .ok_or(Error::SizeOverflow)?;
+                    part.samples
                 }
                 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,
+                &mut silence,
                 scratch,
                 cancelled,
                 &mut consume,
@@ -488,13 +495,13 @@ impl Session {
                 frames,
                 track: self.track,
             },
-            &mut leading,
+            &mut silence,
             scratch,
             cancelled,
             &mut consume,
         )?;
         if let Some(playback) = self.playback {
-            playback.verify(decoded_frames, frames)?;
+            playback.verify(media_end, frames)?;
         }
         Ok((
             stream,

data/src/mp4/tests.rs

@@ -81,21 +81,75 @@ fn versions_clocks_and_selected_track() {
         ));
         let bounds = parse(&movie(version, 1000, &tracks), 7, 44100).unwrap();
         assert_eq!(
-            (bounds.start, bounds.end, bounds.minimum_decoded_frames),
+            (bounds.start, bounds.end, bounds.minimum_media_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_eq!(bounds.slice(0, 1024), 1024..1024);
+        assert_eq!(bounds.slice(1024, 1024), 0..1024);
+        assert_eq!(bounds.slice(3072, 1024), 0..157);
+        assert_eq!(bounds.slice(4096, 1024), 0..0);
+        assert!(bounds.packet(1024, 1024, 1024, 2048).is_err());
+        assert!(bounds.packet(0, 1024, -1, 2048).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 packet_slots_clip_overlaps_and_fill_only_observed_gaps() {
+    let timing = [(1, 1024), (1, 712), (1, 6144), (1, 1000), (1, 352)];
+    let bytes = movie(
+        0,
+        48000,
+        &track(1, 0, 48000, &timing, &edit(0, &[(8208, 1024, 65536)])),
+    );
+    let bounds = parse(&bytes, 1, 48000).unwrap();
+    let mut position = 0;
+    let mut retained = 0;
+    for (pts, duration, samples, silence, end) in [
+        (0, 1024, 1024..1024, 0, 1024),
+        (1024, 712, 0..712, 0, 1736),
+        (1736, 6144, 0..1024, 0, 2760),
+        (7880, 1000, 0..1000, 5120, 8880),
+        (8880, 352, 0..352, 0, 9232),
+    ] {
+        let part = bounds.packet(position, 1024, pts, duration).unwrap();
+        assert_eq!(
+            (part.samples.clone(), part.silence, part.end),
+            (samples, silence, end)
+        );
+        position = part.end;
+        retained += part.silence + part.samples.len() as u64;
+    }
+    assert!(bounds.verify(position, retained).is_ok());
+    // The last decoded packet cannot invent a trailing gap to satisfy metadata.
+    assert!(bounds.verify(2760, 1736).is_err());
+    assert!(bounds.packet(1024, 1024, -1, 1024).is_err());
+    assert!(bounds.packet(1024, 1024, 0, 1024).is_err());
+    assert!(matches!(
+        bounds.packet(1024, 1024, 1024, u64::MAX),
+        Err(Error::SizeOverflow)
+    ));
+
+    // An edit entirely inside a gap retains only that portion of silence.
+    let bytes = movie(
+        0,
+        48000,
+        &track(1, 0, 48000, &timing, &edit(0, &[(500, 3500, 65536)])),
+    );
+    let bounds = parse(&bytes, 1, 48000).unwrap();
+    let part = bounds.packet(2760, 1024, 7880, 1000).unwrap();
+    assert_eq!(part.silence, 500);
+    assert!(part.samples.is_empty());
+
+    // A zero-duration slot is decoded for AAC state but contributes no samples.
+    let part = bounds.packet(1024, 1024, 1024, 0).unwrap();
+    assert_eq!(part.end, 1024);
+    assert_eq!(part.silence, 0);
+    assert!(part.samples.is_empty());
+}
+
 #[test]
 fn edit_end_is_added_before_rounding_and_can_cut_within_a_packet() {
     let bytes = movie(
@@ -105,7 +159,7 @@ fn edit_end_is_added_before_rounding_and_can_cut_within_a_packet() {
     );
     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);
+    assert_eq!(bounds.slice(0, 10), 4..5);
 }
 
 #[test]
@@ -204,15 +258,15 @@ fn rounded_media_timestamps_allow_less_than_one_tick_without_accumulating_drift(
     );
     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_eq!(bounds.boundary(timestamp, position).unwrap(), position);
     }
-    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.boundary(24, 1024).unwrap(), 1024); // rounded upward
+    assert_eq!(bounds.boundary(22, 1024).unwrap(), 971);
+    assert_eq!(bounds.boundary(25, 1024).unwrap(), 1103);
+    assert_eq!(bounds.boundary(1001, 44100).unwrap(), 44145); // one tick
+    assert_eq!(bounds.boundary(69, 3072).unwrap(), 3072);
+    assert_eq!(bounds.boundary(92, 4096).unwrap(), 4096);
+    assert_eq!(bounds.boundary(115, 5120).unwrap(), 5072); // real drift
     assert_eq!(bounds.end, 3220);
     assert!(bounds.verify(4096, 3220).is_ok());
 }

data/src/mp4.rs

@@ -23,7 +23,7 @@ pub(crate) struct Playback {
     timescale: u32,
     start: u64,
     end: u64,
-    minimum_decoded_frames: u64,
+    minimum_media_frames: u64,
     pub leading_frames: u64,
 }
 
@@ -36,38 +36,78 @@ impl Playback {
         self.end - self.start + self.leading_frames
     }
 
-    pub fn slice(self, position: u64, frames: usize, pts: i64) -> Result<Range<usize>, Error> {
+    /// Place decoded samples on the media timeline. A short sample-table slot
+    /// clips the packet's tail; a long slot leaves silence before the next
+    /// packet. Never fill an unverified trailing gap at EOF.
+    pub fn packet(
+        self,
+        position: u64,
+        decoded: usize,
+        pts: i64,
+        duration: u64,
+    ) -> Result<PacketSlice, 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.
+        let start = self.boundary(timestamp, position)?;
+        if start < position {
+            return Err(Error::InvalidAudio("backwards AAC/MP4 sample timing"));
+        }
+        let decoded_end = start
+            .checked_add(u64::try_from(decoded).map_err(|_| Error::SizeOverflow)?)
+            .ok_or(Error::SizeOverflow)?;
+        let timestamp_end = timestamp.checked_add(duration).ok_or(Error::SizeOverflow)?;
+        let end = self
+            .boundary(timestamp_end, decoded_end)?
+            .min(decoded_end)
+            .max(start);
+        Ok(PacketSlice {
+            silence: self.end.min(start).saturating_sub(self.start.max(position)),
+            samples: self.slice(start, end - start),
+            end,
+        })
+    }
+
+    fn boundary(self, timestamp: u64, expected: u64) -> Result<u64, Error> {
+        // Preserve continuous PCM when absolute boundaries differ by less than
+        // one media-clock tick. Comparing absolute times avoids accumulating a
+        // per-packet rounding allowance or independently rounding durations.
         if (u128::from(timestamp) * u128::from(self.rate))
-            .abs_diff(u128::from(position) * u128::from(self.timescale))
-            >= u128::from(self.rate)
+            .abs_diff(u128::from(expected) * u128::from(self.timescale))
+            < u128::from(self.rate)
         {
-            return Err(Error::InvalidAudio("non-contiguous AAC/MP4 sample timing"));
+            Ok(expected)
+        } else {
+            frames(u128::from(timestamp), self.timescale, self.rate)
         }
-        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> {
+    fn slice(self, position: u64, length: u64) -> Range<usize> {
+        // Only called for decoded buffers, so length already fits usize.
+        self.start.saturating_sub(position).min(length) as usize
+            ..self.end.saturating_sub(position).min(length) as usize
+    }
+
+    pub fn verify(self, media_end: 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)
+            .min(media_end)
             .saturating_sub(self.start)
             .checked_add(self.leading_frames)
             .ok_or(Error::SizeOverflow)?;
-        if decoded < self.minimum_decoded_frames || retained != expected {
+        if media_end < self.minimum_media_frames || retained != expected {
             return Err(Error::InvalidAudio("truncated AAC/MP4 playback range"));
         }
         Ok(())
     }
 }
 
+pub(crate) struct PacketSlice {
+    pub silence: u64,
+    pub samples: Range<usize>,
+    pub end: u64,
+}
+
 /// `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.
@@ -187,9 +227,9 @@ impl<R: Read + Seek, C: FnMut() -> bool> Parser<'_, R, C> {
         if start > end {
             return Err(INVALID);
         }
-        // Require decoded time to lie strictly after the preceding media tick.
+        // Require available media to extend strictly past the preceding media tick.
         // With a sample-rate clock this still requires every declared frame.
-        let minimum_decoded_frames = if media_duration == 0 {
+        let minimum_media_frames = if media_duration == 0 {
             0
         } else {
             u64::try_from(
@@ -207,7 +247,7 @@ impl<R: Read + Seek, C: FnMut() -> bool> Parser<'_, R, C> {
             timescale: media_scale,
             start,
             end,
-            minimum_decoded_frames,
+            minimum_media_frames,
             leading_frames,
         }))
     }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: audiowaveform
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Andrii Dmytrenko