refactor(core): 统一处理负数 PTS

Author: apoint123

crates/ffmpeg_audio/src/core/frame.rs

@@ -105,6 +105,37 @@ impl<'a> AudioFrame<'a> {
         unsafe { (*self.ptr.as_ptr()).sample_rate }
     }
 
+    /// Converts a time span in microseconds to the corresponding number of samples based on the
+    /// current frame sample rate
+    pub(crate) fn calc_samples(&self, micros: i64) -> usize {
+        let sample_rate = i64::from(self.frame_sample_rate());
+
+        if sample_rate > 0 && micros > 0 {
+            let samples_i64 = ((micros * sample_rate) + 999_999) / 1_000_000;
+            samples_i64 as usize
+        } else {
+            0
+        }
+    }
+
+    /// Returns the exact physical duration of this frame in microseconds.
+    pub(crate) fn duration_micros(&self) -> i64 {
+        let sample_rate = i64::from(self.frame_sample_rate());
+        if sample_rate > 0 {
+            (self.samples() as i64 * 1_000_000) / sample_rate
+        } else {
+            0
+        }
+    }
+
+    /// Returns the physical end time of this frame in microseconds.
+    ///
+    /// Returns None if the frame lacks a valid start PTS.
+    pub(crate) fn end_micros(&self) -> Option<i64> {
+        self.pts_micros()
+            .map(|start| start.saturating_add(self.duration_micros()))
+    }
+
     /// 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 };
@@ -125,6 +156,12 @@ impl<'a> AudioFrame<'a> {
         })
     }
 
+    /// Returns the precise playback duration of this audio frame.
+    #[must_use]
+    pub fn duration(&self) -> Duration {
+        Duration::from_micros(self.duration_micros().cast_unsigned())
+    }
+
     /// Returns the Presentation Timestamp (PTS) of this frame relative to the stream timeline
     /// origin, if available.
     ///
@@ -135,23 +172,8 @@ impl<'a> AudioFrame<'a> {
     /// - `None` if the underlying frame lacks a valid PTS (`AV_NOPTS_VALUE`).
     #[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.pts_micros()
+            .map(|micros| Duration::from_micros(micros.max(0).cast_unsigned()))
     }
 
     /// Zero-copy extraction of raw PCM audio data directly from the underlying FFmpeg AVFrame.
@@ -213,6 +235,8 @@ mod tests {
         time::Duration,
     };
 
+    use ffmpeg_audio_sys::MICROSECONDS_Q;
+
     use super::*;
 
     #[test]
@@ -222,12 +246,7 @@ mod tests {
         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 time_base = TimeBase::try_new(MICROSECONDS_Q).unwrap();
         let frame = AudioFrame::new(&raw const raw_frame, time_base)
             .with_timeline_origin(10_000_000)
             .with_offset(48);
@@ -241,4 +260,45 @@ mod tests {
         assert_eq!(no_pts_frame.pts_micros(), None);
         assert_eq!(no_pts_frame.pts(), None);
     }
+
+    #[test]
+    fn test_frame_time_boundary_calculations() {
+        let mut raw_frame = unsafe { mem::zeroed::<sys::AVFrame>() };
+        raw_frame.pts = 10_000;
+        raw_frame.nb_samples = 480;
+        raw_frame.sample_rate = 48_000;
+
+        let time_base = TimeBase::try_new(MICROSECONDS_Q).unwrap();
+        let frame = AudioFrame::new(&raw const raw_frame, time_base).with_timeline_origin(0);
+
+        assert_eq!(frame.duration_micros(), 10_000);
+        assert_eq!(frame.end_micros(), Some(20_000));
+    }
+
+    #[test]
+    fn test_calc_samples_for_micros_with_ceiling() {
+        let mut raw_frame = unsafe { mem::zeroed::<sys::AVFrame>() };
+        raw_frame.sample_rate = 44_100;
+        let time_base = TimeBase::try_new(sys::AVRational { num: 1, den: 1 }).unwrap();
+        let frame = AudioFrame::new(&raw const raw_frame, time_base);
+
+        assert_eq!(frame.calc_samples(1_000_000), 44_100);
+        assert_eq!(frame.calc_samples(1), 1);
+        assert_eq!(frame.calc_samples(12), 1);
+    }
+
+    #[test]
+    fn test_frame_fallback_on_invalid_sample_rate() {
+        let mut raw_frame = unsafe { mem::zeroed::<sys::AVFrame>() };
+        raw_frame.nb_samples = 1024;
+        raw_frame.pts = 1000;
+        raw_frame.sample_rate = 0;
+
+        let time_base = TimeBase::try_new(MICROSECONDS_Q).unwrap();
+        let frame = AudioFrame::new(&raw const raw_frame, time_base);
+
+        assert_eq!(frame.duration_micros(), 0);
+        assert_eq!(frame.end_micros(), Some(1000));
+        assert_eq!(frame.calc_samples(5_000_000), 0);
+    }
 }

crates/ffmpeg_audio/src/core/time.rs

@@ -1,5 +1,3 @@
-use std::time::Duration;
-
 use crate::{
     AudioError,
     Result,
@@ -48,31 +46,11 @@ impl TimeBase {
     /// The resulting value **can be negative** if the frame represents
     /// encoder delay or padding before the physical start of the track (0.0s).
     #[must_use]
-    pub fn calc_micros(self, pts: i64) -> Option<i64> {
+    pub(crate) fn calc_micros(self, pts: i64) -> Option<i64> {
         if pts == sys::AV_NOPTS_VALUE {
             return None;
         }
 
         unsafe { Some(sys::av_rescale_q(pts, self.0, sys::MICROSECONDS_Q)) }
     }
-
-    /// Converts a PTS into a `Duration`.
-    ///
-    /// This method is for high-level business logic, UI progress bars,
-    /// or playback synchronization where time must be positive.
-    ///
-    /// # Returns
-    /// - `Some(Duration)` representing the clamped physical playback time.
-    /// - `None` if the provided PTS is invalid (`sys::AV_NOPTS_VALUE`).
-    ///
-    /// # Note
-    /// If the underlying physical time evaluates to a negative value, it is
-    /// clamped to `Duration::ZERO`.
-    #[must_use]
-    pub fn calc_duration(self, pts: i64) -> Option<Duration> {
-        self.calc_micros(pts).map(|micros| {
-            let safe_micros = micros.max(0) as u64;
-            Duration::from_micros(safe_micros)
-        })
-    }
 }

crates/ffmpeg_audio/src/decode/demuxer.rs

@@ -135,7 +135,7 @@ impl Demuxer {
             if start_time == sys::AV_NOPTS_VALUE {
                 0
             } else {
-                start_time
+                start_time.max(0)
             }
         }
     }

crates/ffmpeg_audio/src/decode/engine.rs

@@ -149,10 +149,33 @@ impl DecodeEngine {
         loop {
             match self.decoder.receive_frame() {
                 Ok(Some(frame)) => {
-                    let audio_frame = AudioFrame::new(frame, self.time_base)
+                    let mut audio_frame = AudioFrame::new(frame, self.time_base)
                         .with_timeline_origin(self.timeline_origin_pts);
-                    self.current_pts = audio_frame.pts();
 
+                    if let (Some(start_us), Some(end_us)) =
+                        (audio_frame.pts_micros(), audio_frame.end_micros())
+                    {
+                        if end_us <= 0 {
+                            #[cfg(feature = "tracing")]
+                            tracing::debug!(
+                                "Dropped preroll frame (start: {start_us} us, end: {end_us} us)"
+                            );
+                            continue;
+                        }
+
+                        if start_us < 0 && audio_frame.offset() == 0 {
+                            let delta_us = 0 - start_us;
+                            let offset_samples = audio_frame.calc_samples(delta_us);
+
+                            if offset_samples < audio_frame.samples() {
+                                audio_frame = audio_frame.with_offset(offset_samples);
+                            } else {
+                                continue;
+                            }
+                        }
+                    }
+
+                    self.current_pts = audio_frame.pts();
                     self.debug_verify();
                     return Ok(Some(audio_frame));
                 }
@@ -209,21 +232,10 @@ impl DecodeEngine {
             match self.receive_frame() {
                 Ok(Some(frame)) => {
                     if let Some(pts_us) = frame.pts_micros() {
-                        let sample_rate = i64::from(frame.frame_sample_rate());
-
-                        let duration_us = if sample_rate > 0 {
-                            (frame.samples() as i64 * 1_000_000) / sample_rate
-                        } else {
-                            0
-                        };
-
-                        if pts_us.saturating_add(duration_us) >= target_us {
+                        if pts_us.saturating_add(frame.duration_micros()) >= target_us {
                             let delta_us = target_us.saturating_sub(pts_us).max(0);
-                            let offset_samples = if sample_rate > 0 {
-                                ((delta_us * sample_rate) + 999_999) / 1_000_000
-                            } else {
-                                0
-                            } as usize;
+
+                            let offset_samples = frame.calc_samples(delta_us);
 
                             if offset_samples >= frame.samples() {
                                 continue;
@@ -268,17 +280,10 @@ impl DecodeEngine {
         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
-            }
-        })
+
+        frame
+            .pts()
+            .map_or(Duration::ZERO, |pts| pts.saturating_add(frame.duration()))
     }
 
     /// Scans the audio stream to determine its exact total duration.
@@ -325,8 +330,12 @@ impl DecodeEngine {
                             };
                             let end_us = self.time_base.calc_micros(end_pts).unwrap_or(start_us);
 
-                            min_start_us = Some(min_start_us.map_or(start_us, |m| m.min(start_us)));
-                            max_end_us = Some(max_end_us.map_or(end_us, |m| m.max(end_us)));
+                            let safe_start = start_us.max(0);
+                            let safe_end = end_us.max(0);
+
+                            min_start_us =
+                                Some(min_start_us.map_or(safe_start, |m| m.min(safe_start)));
+                            max_end_us = Some(max_end_us.map_or(safe_end, |m| m.max(safe_end)));
                         }
                     },
                     Ok(None) => break,
@@ -339,19 +348,12 @@ impl DecodeEngine {
             ScanMode::Frame => loop {
                 match self.receive_frame() {
                     Ok(Some(frame)) => {
-                        let sample_rate = i64::from(frame.frame_sample_rate());
-
-                        let frame_duration_us = if sample_rate > 0 {
-                            (frame.samples() as i64 * 1_000_000) / sample_rate
-                        } else {
-                            0
-                        };
-
                         total_duration_us_fallback =
-                            total_duration_us_fallback.saturating_add(frame_duration_us);
+                            total_duration_us_fallback.saturating_add(frame.duration_micros());
 
-                        if let Some(start_us) = frame.pts_micros() {
-                            let end_us = start_us.saturating_add(frame_duration_us);
+                        if let (Some(start_us), Some(end_us)) =
+                            (frame.pts_micros(), frame.end_micros())
+                        {
                             min_start_us = Some(min_start_us.map_or(start_us, |m| m.min(start_us)));
                             max_end_us = Some(max_end_us.map_or(end_us, |m| m.max(end_us)));
                         }

crates/ffmpeg_audio/tests/assets/negative_pts.mkv

@@ -501,6 +501,7 @@ mod file_tests {
 
     const AAC_SEEK_PATH: &str = "tests/assets/seek_test.aac";
     const MUTATION_AAC_PATH: &str = "tests/assets/format_mutation.aac";
+    const NEGATIVE_PTS_MKV_PATH: &str = "tests/assets/negative_pts.mkv";
 
     #[test]
     fn test_seek_accuracy() {
@@ -610,4 +611,39 @@ mod file_tests {
             RawAudioData::Packed(_) => panic!("AAC 应该被解码为 Planar 布局，却得到了 Packed"),
         }
     }
+
+    #[test]
+    fn test_blocks_negative_pts_from_raw_container() {
+        // ffmpeg -f lavfi -i "aevalsrc=sin(440*2*PI*t):s=48000:d=1" -c:a pcm_s16le
+        // -output_ts_offset -0.1 -avoid_negative_ts disabled -y negative_pts.mkv
+        let file = std::fs::File::open(NEGATIVE_PTS_MKV_PATH).unwrap();
+        let mut reader = AudioReader::new(file).unwrap();
+
+        let mut total_samples = 0;
+        let mut first_frame_pts = None;
+
+        while let Some(frame) = reader.receive_frame().unwrap() {
+            if first_frame_pts.is_none() {
+                first_frame_pts = frame.pts();
+
+                assert_eq!(
+                    first_frame_pts.unwrap().as_millis(),
+                    0,
+                    "First output frame is not aligned to 0ms"
+                );
+            }
+            total_samples += frame.samples();
+        }
+
+        // 1. The MKV container timebase is 1/1000s (millisecond precision).
+        // 2. 1024 samples per packet at 48kHz (approx. 21.33ms).
+        // 3. After millisecond quantization, the PTS of the 5th packet is marked as -15ms.
+        // 4. Remove the first 4 packets (4096) and the first 15ms of the 5th packet (720 samples),
+        //    totaling 4816 samples removed.
+        // 5. The final remaining valid sample count is 43184.
+        assert_eq!(
+            total_samples, 43_184,
+            "Should trim exactly 0.1s of negative PTS data. Expected 43184 samples, got {total_samples}"
+        );
+    }
 }