fix(core): 统一音频时间轴并加固重采样安全边界

Author: apoint123

crates/ffmpeg_audio/src/core/format.rs

@@ -1,33 +1,45 @@
 use crate::sys;
 
+mod private {
+    pub trait Sealed {}
+}
+
 /// A trait binding Rust native numeric types to FFmpeg's `AVSampleFormat`.
 ///
 /// This trait is used to ensure type safety when extracting resampled audio data.
-pub trait AudioSample: Copy + Send + Sync + 'static {
+///
+/// This trait is sealed because the resampler reinterprets bytes written by FFmpeg as `Self`.
+/// Allowing downstream implementations would make it possible to violate Rust's layout,
+/// alignment, or valid-bit-pattern requirements through an otherwise safe API.
+pub trait AudioSample: private::Sealed + Copy + Send + Sync + 'static {
     /// The FFmpeg sample format enum corresponding to the packed (interleaved) layout.
     const PACKED_FORMAT: sys::AVSampleFormat;
 
     /// The FFmpeg sample format enum corresponding to the planar layout.
     const PLANAR_FORMAT: sys::AVSampleFormat;
 }
 
+impl private::Sealed for f32 {}
 impl AudioSample for f32 {
     const PACKED_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_FLT;
     const PLANAR_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_FLTP;
 }
 
+impl private::Sealed for i16 {}
 impl AudioSample for i16 {
     const PACKED_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_S16;
     const PLANAR_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_S16P;
 }
 
+impl private::Sealed for i32 {}
 impl AudioSample for i32 {
     #[expect(clippy::use_self)]
     const PACKED_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_S32;
     #[expect(clippy::use_self)]
     const PLANAR_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_S32P;
 }
 
+impl private::Sealed for u8 {}
 impl AudioSample for u8 {
     const PACKED_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_U8;
     const PLANAR_FORMAT: sys::AVSampleFormat = sys::AVSampleFormat_AV_SAMPLE_FMT_U8P;

crates/ffmpeg_audio/src/core/frame.rs

@@ -16,6 +16,7 @@ use crate::{
 pub struct AudioFrame<'a> {
     ptr: NonNull<sys::AVFrame>,
     time_base: TimeBase,
+    timeline_origin_pts: i64,
     sample_offset: usize,
     _marker: PhantomData<&'a mut ()>,
 }
@@ -31,6 +32,7 @@ impl AudioFrame<'_> {
         Self {
             ptr: NonNull::new(ptr.cast_mut()).expect("FFmpeg returned a null AVFrame pointer"),
             time_base,
+            timeline_origin_pts: 0,
             sample_offset: 0,
             _marker: PhantomData,
         }
@@ -42,6 +44,12 @@ impl AudioFrame<'_> {
         self
     }
 
+    /// Defines the stream timestamp that corresponds to the public timeline origin.
+    pub(crate) const fn with_timeline_origin(mut self, origin_pts: i64) -> Self {
+        self.timeline_origin_pts = origin_pts;
+        self
+    }
+
     /// Extracts the underlying raw FFmpeg `AVFrame` pointer.
     ///
     /// This is used internally to pass the raw frame data into FFmpeg's FFI functions
@@ -80,11 +88,15 @@ impl AudioFrame<'_> {
         unsafe { (*self.ptr.as_ptr()).sample_rate }
     }
 
-    /// Returns the Presentation Timestamp (PTS) in microseconds, if available.
+    /// Returns the PTS in microseconds relative to the stream timeline origin, if available.
     pub(crate) fn pts_micros(&self) -> Option<i64> {
         let raw_pts = unsafe { (*self.ptr.as_ptr()).pts };
+        if raw_pts == sys::AV_NOPTS_VALUE {
+            return None;
+        }
+        let relative_pts = raw_pts.saturating_sub(self.timeline_origin_pts);
 
-        self.time_base.calc_micros(raw_pts).map(|mut micros| {
+        self.time_base.calc_micros(relative_pts).map(|mut micros| {
             let sample_rate = self.frame_sample_rate();
 
             if self.sample_offset > 0 && sample_rate > 0 {
@@ -96,7 +108,8 @@ impl AudioFrame<'_> {
         })
     }
 
-    /// Returns the Presentation Timestamp (PTS) of this frame, if available.
+    /// Returns the Presentation Timestamp (PTS) of this frame relative to the stream timeline
+    /// origin, if available.
     ///
     /// The timestamp is automatically adjusted forward by the internal sample offset.
     ///
@@ -106,15 +119,58 @@ impl AudioFrame<'_> {
     #[must_use]
     pub fn pts(&self) -> Option<Duration> {
         let raw_pts = unsafe { (*self.ptr.as_ptr()).pts };
+        if raw_pts == sys::AV_NOPTS_VALUE {
+            return None;
+        }
+        let relative_pts = raw_pts.saturating_sub(self.timeline_origin_pts);
+
+        self.time_base
+            .calc_duration(relative_pts)
+            .map(|mut duration| {
+                let sample_rate = self.frame_sample_rate();
+
+                if self.sample_offset > 0 && sample_rate > 0 {
+                    let offset_secs = self.sample_offset as f64 / f64::from(sample_rate);
+                    duration += Duration::from_secs_f64(offset_secs);
+                }
+                duration
+            })
+    }
+}
 
-        self.time_base.calc_duration(raw_pts).map(|mut duration| {
-            let sample_rate = self.frame_sample_rate();
-
-            if self.sample_offset > 0 && sample_rate > 0 {
-                let offset_secs = self.sample_offset as f64 / f64::from(sample_rate);
-                duration += Duration::from_secs_f64(offset_secs);
-            }
-            duration
+#[cfg(test)]
+mod tests {
+    use std::{
+        mem,
+        time::Duration,
+    };
+
+    use super::*;
+
+    #[test]
+    fn pts_is_relative_to_the_timeline_origin() {
+        let mut raw_frame = unsafe { mem::zeroed::<sys::AVFrame>() };
+        raw_frame.pts = 10_000_000;
+        raw_frame.nb_samples = 1_024;
+        raw_frame.sample_rate = 48_000;
+
+        let time_base = TimeBase::try_new(sys::AVRational {
+            num: 1,
+            den: 1_000_000,
         })
+        .unwrap();
+
+        let frame = AudioFrame::new(&raw const raw_frame, time_base)
+            .with_timeline_origin(10_000_000)
+            .with_offset(48);
+
+        assert_eq!(frame.pts_micros(), Some(1_000));
+        assert_eq!(frame.pts(), Some(Duration::from_micros(1_000)));
+
+        raw_frame.pts = sys::AV_NOPTS_VALUE;
+        let no_pts_frame =
+            AudioFrame::new(&raw const raw_frame, time_base).with_timeline_origin(-1);
+        assert_eq!(no_pts_frame.pts_micros(), None);
+        assert_eq!(no_pts_frame.pts(), None);
     }
 }

crates/ffmpeg_audio/src/decode/decoder.rs

@@ -64,6 +64,10 @@ impl Decoder {
         self.frame
     }
 
+    pub const fn is_flushing(&self) -> bool {
+        self.is_flushing
+    }
+
     pub fn send_packet(&mut self, packet: *const sys::AVPacket) -> Result<()> {
         unsafe {
             sys::avcodec_send_packet(self.ctx, packet).into_ff_result()?;
@@ -82,10 +86,12 @@ impl Decoder {
         if self.is_flushing {
             return Ok(());
         }
-        self.is_flushing = true;
+
         unsafe {
             sys::avcodec_send_packet(self.ctx, ptr::null()).into_ff_result()?;
         }
+
+        self.is_flushing = true;
         Ok(())
     }
 

crates/ffmpeg_audio/src/decode/demuxer.rs

@@ -127,6 +127,19 @@ impl Demuxer {
         }
     }
 
+    /// Returns the raw stream PTS corresponding to the public timeline origin.
+    pub fn timeline_origin_pts(&self) -> i64 {
+        unsafe {
+            let stream_ptr = *(*self.ctx).streams.add(self.audio_stream_idx);
+            let start_time = (*stream_ptr).start_time;
+            if start_time == sys::AV_NOPTS_VALUE {
+                0
+            } else {
+                start_time
+            }
+        }
+    }
+
     pub fn seek_to(&mut self, target: Duration) -> Result<()> {
         unsafe {
             let stream_ptr = *(*self.ctx).streams.add(self.audio_stream_idx);
@@ -136,10 +149,7 @@ impl Demuxer {
 
             let mut pts = sys::av_rescale_q(target_us, sys::MICROSECONDS_Q, time_base);
 
-            let start_time = (*stream_ptr).start_time;
-            if start_time != sys::AV_NOPTS_VALUE {
-                pts = pts.saturating_add(start_time);
-            }
+            pts = pts.saturating_add(self.timeline_origin_pts());
 
             let min_pts = i64::MIN;
             let max_pts = pts;

crates/ffmpeg_audio/src/decode/engine.rs

@@ -54,6 +54,9 @@ pub struct DecodeEngine {
     /// The fundamental unit of time representation for the current stream.
     time_base: TimeBase,
 
+    /// Raw stream PTS that maps to the public zero-based timeline.
+    timeline_origin_pts: i64,
+
     /// The presentation timestamp (PTS) of the most recently decoded frame, if available.
     current_pts: Option<Duration>,
 
@@ -89,11 +92,13 @@ impl DecodeEngine {
         let decoder = Decoder::new(codec_params)?;
 
         let time_base = demuxer.time_base()?;
+        let timeline_origin_pts = demuxer.timeline_origin_pts();
 
         Ok(Self {
             demuxer,
             decoder,
             time_base,
+            timeline_origin_pts,
             current_pts: None,
             is_exhausted: false,
             has_buffered_seek_frame: false,
@@ -130,8 +135,9 @@ impl DecodeEngine {
         if self.has_buffered_seek_frame {
             self.has_buffered_seek_frame = false;
             let frame_ptr = self.decoder.current_frame();
-            let audio_frame =
-                AudioFrame::new(frame_ptr, self.time_base).with_offset(self.buffered_seek_offset);
+            let audio_frame = AudioFrame::new(frame_ptr, self.time_base)
+                .with_timeline_origin(self.timeline_origin_pts)
+                .with_offset(self.buffered_seek_offset);
 
             self.buffered_seek_offset = 0;
             self.current_pts = audio_frame.pts();
@@ -143,16 +149,26 @@ impl DecodeEngine {
         loop {
             match self.decoder.receive_frame() {
                 Ok(Some(frame)) => {
-                    let audio_frame = AudioFrame::new(frame, self.time_base);
+                    let audio_frame = AudioFrame::new(frame, self.time_base)
+                        .with_timeline_origin(self.timeline_origin_pts);
                     self.current_pts = audio_frame.pts();
 
                     self.debug_verify();
                     return Ok(Some(audio_frame));
                 }
-                Err(AudioError::Eagain) => match self.demuxer.read_packet()? {
-                    Some(packet) => self.decoder.send_packet(packet)?,
-                    None => self.decoder.send_eof_flush()?,
-                },
+                Err(AudioError::Eagain) => {
+                    if let Some(packet) = self.demuxer.read_packet()? {
+                        self.decoder.send_packet(packet)?;
+                    } else {
+                        if self.decoder.is_flushing() {
+                            self.is_exhausted = true;
+                            self.debug_verify();
+                            return Ok(None);
+                        }
+
+                        self.decoder.send_eof_flush()?;
+                    }
+                }
                 Ok(None) => {
                     self.is_exhausted = true;
                     self.debug_verify();
@@ -234,6 +250,37 @@ impl DecodeEngine {
         Ok(())
     }
 
+    /// Returns the position from which the next `receive_frame` call should resume.
+    fn next_read_position(&self) -> Duration {
+        if self.has_buffered_seek_frame {
+            let frame_ptr = self.decoder.current_frame();
+            return AudioFrame::new(frame_ptr, self.time_base)
+                .with_timeline_origin(self.timeline_origin_pts)
+                .with_offset(self.buffered_seek_offset)
+                .pts()
+                .unwrap_or(Duration::ZERO);
+        }
+
+        if self.current_pts.is_none() {
+            return Duration::ZERO;
+        }
+
+        let frame_ptr = self.decoder.current_frame();
+        let frame = AudioFrame::new(frame_ptr, self.time_base)
+            .with_timeline_origin(self.timeline_origin_pts);
+        let sample_rate = frame.frame_sample_rate();
+
+        frame.pts().map_or(Duration::ZERO, |pts| {
+            if sample_rate > 0 {
+                let frame_duration_us =
+                    (frame.samples() as u64).saturating_mul(1_000_000) / sample_rate as u64;
+                pts.saturating_add(Duration::from_micros(frame_duration_us))
+            } else {
+                pts
+            }
+        })
+    }
+
     /// Scans the audio stream to determine its exact total duration.
     ///
     /// This operation performs internal seeking and state resets. It is recommended to
@@ -248,15 +295,10 @@ impl DecodeEngine {
     /// * `Ok(None)` if the file is completely empty or lacks valid timestamp data.
     /// * `Err(AudioError)` if an I/O or parsing failure halts the scanning process.
     pub fn scan_duration(&mut self, mode: ScanMode) -> Result<Option<Duration>> {
-        let original_position = if self.has_buffered_seek_frame {
-            let frame_ptr = self.decoder.current_frame();
-            AudioFrame::new(frame_ptr, self.time_base)
-                .with_offset(self.buffered_seek_offset)
-                .pts()
-        } else {
-            self.current_pts
-        }
-        .unwrap_or(Duration::ZERO);
+        let was_exhausted = self.is_exhausted;
+        let original_current_pts = self.current_pts;
+
+        let original_position = self.next_read_position();
 
         self.seek(Duration::ZERO, SeekMode::Coarse)?;
 
@@ -323,7 +365,15 @@ impl DecodeEngine {
             },
         }
 
-        let seek_result = self.seek(original_position, SeekMode::Accurate);
+        let seek_result = if was_exhausted {
+            self.is_exhausted = true;
+            self.current_pts = original_current_pts;
+            self.has_buffered_seek_frame = false;
+            self.buffered_seek_offset = 0;
+            Ok(())
+        } else {
+            self.seek(original_position, SeekMode::Accurate)
+        };
 
         if let Some(e) = scan_error {
             return Err(e);

crates/ffmpeg_audio/src/lib.rs

@@ -130,12 +130,15 @@ impl AudioReader {
     /// internal FFmpeg `SwrContext` allocation and initialization fail.
     pub fn build_resampler(&self, options: ResampleOptions) -> Result<Resampler> {
         let decoder = self.engine.decoder();
-        Resampler::new(
-            &decoder.channel_layout(),
-            decoder.sample_fmt(),
-            decoder.sample_rate(),
-            options,
-        )
+        // Decoder-derived FFmpeg layouts are initialized and remain valid for this call.
+        unsafe {
+            Resampler::new(
+                &decoder.channel_layout(),
+                decoder.sample_fmt(),
+                decoder.sample_rate(),
+                options,
+            )
+        }
     }
 
     /// Consumes the current [`AudioReader`] and wraps it in a [`ResampledReader`]