Skip to main content

rusttorch_codec/
lib.rs

1//! Stream CPU-decoded video and audio from local media with explicit timestamps.
2//!
3//! Enable `system` for an existing FFmpeg 8 installation, or `vcpkg` for vcpkg
4//! linking. No native libraries are downloaded or embedded in this package.
5//! Without either feature, the time/frame types remain available for docs.rs.
6//!
7//! ```no_run
8//! # #[cfg(any(feature="system",feature="vcpkg"))]
9//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
10//! use rusttorch_codec::{MediaDecoder, StreamKind};
11//! use rusttorch_data::{batches, ResourceLimits};
12//! let decoder = MediaDecoder::open("clip.mkv", StreamKind::Video, ResourceLimits::default())?;
13//! for frames in batches(decoder, 8, false)? {
14//!     for frame in frames? { println!("{:?}", frame.timestamp()); }
15//! }
16//! # Ok(()) }
17//! ```
18#![deny(missing_docs)]
19#![doc = include_str!("../README.md")]
20use rusttorch_core::{Device, Tensor};
21use rusttorch_data::{MemoryFootprint, PinMemory};
22use serde::{Deserialize, Serialize};
23/// Codec, resource-limit or local I/O failure.
24#[derive(Debug, thiserror::Error)]
25#[non_exhaustive]
26pub enum CodecError {
27    /// Local media file failure.
28    #[error(transparent)]
29    Io(#[from] std::io::Error),
30    /// Invalid time, dimensions, format or requested capability.
31    #[error("{0}")]
32    Invalid(String),
33    /// Configured input/output ceiling exceeded.
34    #[error(transparent)]
35    Limit(#[from] rusttorch_core::RustTorchError),
36    /// LibTorch tensor construction failed.
37    #[error(transparent)]
38    Tensor(#[from] tch::TchError),
39    /// Native decoder error, with original source retained.
40    #[cfg(any(feature = "system", feature = "vcpkg"))]
41    #[error(transparent)]
42    Native(#[from] rsmpeg::error::RsmpegError),
43}
44/// Result returned by media operations.
45pub type Result<T> = std::result::Result<T, CodecError>;
46/// Positive rational seconds per tick, kept exact until display conversion.
47#[derive(Clone, Copy, Debug, Serialize, PartialEq, Eq)]
48pub struct TimeBase {
49    numerator: u32,
50    denominator: u32,
51}
52impl TimeBase {
53    /// Validates positive numerator and denominator.
54    pub fn new(numerator: u32, denominator: u32) -> Result<Self> {
55        if numerator == 0 || denominator == 0 {
56            return Err(CodecError::Invalid(
57                "time base requires positive numerator and denominator".into(),
58            ));
59        }
60        Ok(Self {
61            numerator,
62            denominator,
63        })
64    }
65    /// Rational numerator.
66    pub const fn numerator(self) -> u32 {
67        self.numerator
68    }
69    /// Rational denominator.
70    pub const fn denominator(self) -> u32 {
71        self.denominator
72    }
73    /// Converts ticks to approximate floating-point seconds.
74    pub fn seconds(self, ticks: i64) -> f64 {
75        ticks as f64 * self.numerator as f64 / self.denominator as f64
76    }
77    /// Rescales timestamps with checked i128 arithmetic and truncation toward zero.
78    pub fn rescale(self, ticks: i64, target: Self) -> Result<i64> {
79        let value = (ticks as i128) * (self.numerator as i128) * (target.denominator as i128)
80            / ((self.denominator as i128) * (target.numerator as i128));
81        i64::try_from(value)
82            .map_err(|_| CodecError::Invalid("rescaled timestamp overflows i64".into()))
83    }
84}
85impl<'de> Deserialize<'de> for TimeBase {
86    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
87        #[derive(Deserialize)]
88        struct Wire {
89            numerator: u32,
90            denominator: u32,
91        }
92        let w = Wire::deserialize(d)?;
93        Self::new(w.numerator, w.denominator).map_err(serde::de::Error::custom)
94    }
95}
96/// Timestamp carrying its exact rational tick unit.
97#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
98pub struct Timestamp {
99    /// Presentation ticks, possibly negative.
100    pub ticks: i64,
101    /// Seconds per tick.
102    pub time_base: TimeBase,
103}
104impl Timestamp {
105    /// Approximate presentation time in seconds.
106    pub fn seconds(self) -> f64 {
107        self.time_base.seconds(self.ticks)
108    }
109}
110/// Kind of stream selected for decoding.
111#[derive(Clone, Copy, Debug, PartialEq, Eq)]
112pub enum StreamKind {
113    /// CPU RGB video.
114    Video,
115    /// CPU interleaved source audio, normalized to planar Float mono/stereo.
116    Audio,
117}
118/// One decoded RGB frame.
119#[derive(Debug)]
120pub struct VideoFrame {
121    /// RGB Uint8 CHW pixels.
122    pub pixels: Tensor,
123    /// Presentation time, absent when the source provides none.
124    pub timestamp: Option<Timestamp>,
125}
126/// One decoded Float mono/stereo audio block.
127#[derive(Debug)]
128pub struct AudioFrame {
129    /// `[channels,frames]` normalized Float samples.
130    pub samples: Tensor,
131    /// Frames per second.
132    pub sample_rate: u32,
133    /// Presentation time, absent when unknown.
134    pub timestamp: Option<Timestamp>,
135}
136/// A typed decoded item. MediaDecoder selects exactly one stream kind.
137#[derive(Debug)]
138pub enum MediaFrame {
139    /// RGB image.
140    Video(VideoFrame),
141    /// Normalized audio block.
142    Audio(AudioFrame),
143}
144impl MediaFrame {
145    /// Returns the source presentation timestamp without inventing missing values.
146    pub fn timestamp(&self) -> Option<Timestamp> {
147        match self {
148            Self::Video(v) => v.timestamp,
149            Self::Audio(a) => a.timestamp,
150        }
151    }
152}
153impl MemoryFootprint for VideoFrame {
154    fn resident_bytes(&self) -> usize {
155        self.pixels.resident_bytes()
156    }
157}
158impl MemoryFootprint for AudioFrame {
159    fn resident_bytes(&self) -> usize {
160        self.samples.resident_bytes()
161    }
162}
163impl MemoryFootprint for MediaFrame {
164    fn resident_bytes(&self) -> usize {
165        match self {
166            Self::Video(v) => v.resident_bytes(),
167            Self::Audio(a) => a.resident_bytes(),
168        }
169    }
170}
171impl PinMemory for VideoFrame {
172    fn pin_memory(mut self, d: Device) -> rusttorch_core::Result<Self> {
173        self.pixels = self.pixels.pin_memory(d)?;
174        Ok(self)
175    }
176}
177impl PinMemory for AudioFrame {
178    fn pin_memory(mut self, d: Device) -> rusttorch_core::Result<Self> {
179        self.samples = self.samples.pin_memory(d)?;
180        Ok(self)
181    }
182}
183impl PinMemory for MediaFrame {
184    fn pin_memory(self, d: Device) -> rusttorch_core::Result<Self> {
185        match self {
186            Self::Video(v) => Ok(Self::Video(v.pin_memory(d)?)),
187            Self::Audio(a) => Ok(Self::Audio(a.pin_memory(d)?)),
188        }
189    }
190}
191/// Selected stream metadata, without assuming a constant frame rate.
192#[derive(Clone, Debug)]
193pub struct StreamInfo {
194    /// Zero-based container stream index.
195    pub index: usize,
196    /// Selected media kind.
197    pub kind: StreamKind,
198    /// Stream tick unit.
199    pub time_base: TimeBase,
200    /// Duration in ticks when available.
201    pub duration: Option<i64>,
202    /// Native decoder name.
203    pub decoder: String,
204}
205/// Actual linked FFmpeg build diagnostics; configuration determines licensing.
206#[derive(Clone, Debug)]
207pub struct CodecCapabilities {
208    /// Runtime version string.
209    pub version: String,
210    /// FFmpeg configure flags, without labeling arbitrary builds approved.
211    pub configuration: String,
212    /// Reported native license.
213    pub license: String,
214    /// CPU decoding baseline is available.
215    pub cpu_decode: bool,
216}
217#[cfg(any(feature = "system", feature = "vcpkg"))]
218mod native;
219#[cfg(any(feature = "system", feature = "vcpkg"))]
220pub use native::{MediaDecoder, capabilities};