symphonia_core/codecs/
video.rs

1// Symphonia
2// Copyright (c) 2019-2026 The Project Symphonia Developers.
3//
4// This Source Code Form is subject to the terms of the Mozilla Public
5// License, v. 2.0. If a copy of the MPL was not distributed with this
6// file, You can obtain one at https://mozilla.org/MPL/2.0/.
7
8//! Video decoder specific support.
9
10use std::fmt;
11
12#[cfg(feature = "exp-video-codecs")]
13use crate::codecs::CodecInfo;
14use crate::codecs::CodecProfile;
15use crate::common::FourCc;
16
17/// An `VideoCodecId` is a unique identifier used to identify a specific video codec.
18///
19/// # Creating a Codec ID
20///
21/// Using a [well-known](well_known) codec ID is *highly* recommended to maximize compatibility
22/// between components, libraries, and applications. However, if a codec requires custom codec ID,
23/// or there is no well-known ID, then the [`FourCc`] for the codec may be converted into a codec
24/// ID.
25#[repr(transparent)]
26#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
27pub struct VideoCodecId(u32);
28
29/// Null video codec ID
30pub const CODEC_ID_NULL_VIDEO: VideoCodecId = VideoCodecId(0x0);
31
32impl Default for VideoCodecId {
33    fn default() -> Self {
34        CODEC_ID_NULL_VIDEO
35    }
36}
37
38impl VideoCodecId {
39    /// Create a new video codec ID from a FourCC.
40    pub const fn new(cc: FourCc) -> VideoCodecId {
41        // A FourCc always only contains ASCII characters. Therefore, the upper bits are always 0.
42        Self(0x8000_0000 | u32::from_be_bytes(cc.get()))
43    }
44}
45
46impl From<FourCc> for VideoCodecId {
47    fn from(value: FourCc) -> Self {
48        VideoCodecId::new(value)
49    }
50}
51
52impl fmt::Display for VideoCodecId {
53    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
54        write!(f, "{:#x}", self.0)
55    }
56}
57
58/// An `VideoExtraDataId` is a unique identifier used to identify a specific video extra data.
59#[repr(transparent)]
60#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
61pub struct VideoExtraDataId(u32);
62
63/// Null video extra data ID.
64pub const VIDEO_EXTRA_DATA_ID_NULL: VideoExtraDataId = VideoExtraDataId(0x0);
65
66impl Default for VideoExtraDataId {
67    fn default() -> Self {
68        VIDEO_EXTRA_DATA_ID_NULL
69    }
70}
71
72/// Extra data for a video codec.
73#[derive(Clone, Debug, Default)]
74pub struct VideoExtraData {
75    /// The extra data ID.
76    pub id: VideoExtraDataId,
77    /// Extra data (defined by codec)
78    pub data: Box<[u8]>,
79}
80
81/// Codec parameters for video codecs.
82#[derive(Clone, Debug, Default)]
83pub struct VideoCodecParameters {
84    /// The codec ID.
85    pub codec: VideoCodecId,
86    /// The codec-defined profile.
87    pub profile: Option<CodecProfile>,
88    /// The codec-defined level.
89    pub level: Option<u32>,
90    /// Video width.
91    pub width: Option<u16>,
92    /// Video height.
93    pub height: Option<u16>,
94    /// Extra data (defined by the codec).
95    pub extra_data: Vec<VideoExtraData>,
96}
97
98impl VideoCodecParameters {
99    /// Provide the `VideoCodecId`.
100    pub fn for_codec(&mut self, codec: VideoCodecId) -> &mut Self {
101        self.codec = codec;
102        self
103    }
104
105    /// Provide codec profile.
106    pub fn with_profile(&mut self, profile: CodecProfile) -> &mut Self {
107        self.profile = Some(profile);
108        self
109    }
110
111    /// Provide codec level.
112    pub fn with_level(&mut self, level: u32) -> &mut Self {
113        self.level = Some(level);
114        self
115    }
116
117    /// Provide video width.
118    pub fn with_width(&mut self, width: u16) -> &mut Self {
119        self.width = Some(width);
120        self
121    }
122
123    /// Provide video height.
124    pub fn with_height(&mut self, height: u16) -> &mut Self {
125        self.height = Some(height);
126        self
127    }
128
129    /// Adds codec's extra data.
130    pub fn add_extra_data(&mut self, data: VideoExtraData) -> &mut Self {
131        self.extra_data.push(data);
132        self
133    }
134}
135
136/// `VideoDecoderOptions` is a common set of options that all subtitle decoders use.
137#[cfg(feature = "exp-video-codecs")]
138#[non_exhaustive]
139#[derive(Copy, Clone, Debug, Default)]
140pub struct VideoDecoderOptions {
141    // None yet.
142}
143
144/// A `VideoDecoder` implements a video codec's decode algorithm. It consumes `Packet`s and
145/// produces video frames.
146#[cfg(feature = "exp-video-codecs")]
147pub trait VideoDecoder: Send + Sync {
148    /// Reset the decoder.
149    ///
150    /// A decoder must be reset when the next packet is discontinuous with respect to the last
151    /// decoded packet. Most notably, this occurs after a seek.
152    ///
153    /// # For Implementations
154    ///
155    /// For codecs that do a lot of pre-computation, reset should only reset the absolute minimum
156    /// amount of state.
157    fn reset(&mut self);
158
159    /// Get basic information about the codec.
160    fn codec_info(&self) -> &CodecInfo;
161
162    /// Gets a reference to an updated set of `VideoCodecParameters` based on the codec parameters
163    /// the decoder was instantiated with.
164    fn codec_params(&self) -> &VideoCodecParameters;
165}
166
167/// Codec IDs and profiles for well-known video codecs.
168pub mod well_known {
169    use super::VideoCodecId;
170
171    /// Motion JPEG
172    pub const CODEC_ID_MJPEG: VideoCodecId = VideoCodecId(0x100);
173
174    // RAD Games Tools (Epic Games Tools) codecs
175
176    /// Bink Video
177    pub const CODEC_ID_BINK_VIDEO: VideoCodecId = VideoCodecId(0x200);
178    /// Smacker Video
179    pub const CODEC_ID_SMACKER_VIDEO: VideoCodecId = VideoCodecId(0x201);
180
181    /// Cinepak
182    pub const CODEC_ID_CINEPAK: VideoCodecId = VideoCodecId(0x300);
183
184    // Intel codecs
185
186    /// Intel Indeo Video 2
187    pub const CODEC_ID_INDEO2: VideoCodecId = VideoCodecId(0x400);
188    /// Intel Indeo Video 3
189    pub const CODEC_ID_INDEO3: VideoCodecId = VideoCodecId(0x401);
190    /// Intel Indeo Video Interactive 4
191    pub const CODEC_ID_INDEO4: VideoCodecId = VideoCodecId(0x402);
192    /// Intel Indeo Video Interactive 5
193    pub const CODEC_ID_INDEO5: VideoCodecId = VideoCodecId(0x403);
194
195    // Sorenson codecs
196
197    /// Sorenson Video 1 (SVQ1)
198    pub const CODEC_ID_SVQ1: VideoCodecId = VideoCodecId(0x500);
199    /// Sorenson Video 1 (SVQ3)
200    pub const CODEC_ID_SVQ3: VideoCodecId = VideoCodecId(0x501);
201    /// Flash Video (Sorenson Spark, Sorenson H.263, FLV1)
202    pub const CODEC_ID_FLV: VideoCodecId = VideoCodecId(0x502);
203
204    // RealNetworks codecs
205
206    /// RealVideo 1.0 (RV10)
207    pub const CODEC_ID_RV10: VideoCodecId = VideoCodecId(0x600);
208    /// RealVideo 2.0 (RV20)
209    pub const CODEC_ID_RV20: VideoCodecId = VideoCodecId(0x601);
210    /// RealVideo 3.0 (RV30)
211    pub const CODEC_ID_RV30: VideoCodecId = VideoCodecId(0x602);
212    /// RealVideo 4.0 (RV40)
213    pub const CODEC_ID_RV40: VideoCodecId = VideoCodecId(0x603);
214
215    // Microsoft codecs
216
217    /// Microsoft MPEG-4 Part 2 version 1 (MPG4)
218    pub const CODEC_ID_MSMPEG4V1: VideoCodecId = VideoCodecId(0x700);
219    /// Microsoft MPEG-4 Part 2 version 2 (MP42)
220    pub const CODEC_ID_MSMPEG4V2: VideoCodecId = VideoCodecId(0x701);
221    /// Microsoft MPEG-4 Part 2 version 3 (MP43)
222    pub const CODEC_ID_MSMPEG4V3: VideoCodecId = VideoCodecId(0x702);
223    /// Windows Media Video 7 (WMV1)
224    pub const CODEC_ID_WMV1: VideoCodecId = VideoCodecId(0x703);
225    /// Windows Media Video 8 (WMV2)
226    pub const CODEC_ID_WMV2: VideoCodecId = VideoCodecId(0x704);
227    /// Windows Media Video 9 (WMV3)
228    pub const CODEC_ID_WMV3: VideoCodecId = VideoCodecId(0x705);
229
230    // On2 Technologies & Google codecs
231
232    /// On2 TrueMotion VP3 (VP3)
233    pub const CODEC_ID_VP3: VideoCodecId = VideoCodecId(0x800);
234    /// On2 TrueMotion VP4 (VP4)
235    pub const CODEC_ID_VP4: VideoCodecId = VideoCodecId(0x801);
236    /// On2 TrueMotion VP5 (VP5)
237    pub const CODEC_ID_VP5: VideoCodecId = VideoCodecId(0x802);
238    /// On2 TrueMotion VP6 (VP6)
239    pub const CODEC_ID_VP6: VideoCodecId = VideoCodecId(0x803);
240    /// On2 TrueMotion VP7 (VP7)
241    pub const CODEC_ID_VP7: VideoCodecId = VideoCodecId(0x804);
242    /// On2 TrueMotion VP8 (VP8)
243    pub const CODEC_ID_VP8: VideoCodecId = VideoCodecId(0x805);
244    /// On2 TrueMotion VP9 (VP9)
245    pub const CODEC_ID_VP9: VideoCodecId = VideoCodecId(0x806);
246
247    // Xiph codecs
248
249    /// Theora
250    pub const CODEC_ID_THEORA: VideoCodecId = VideoCodecId(0x900);
251    /// AOMedia Video 1 (AV1)
252    pub const CODEC_ID_AV1: VideoCodecId = VideoCodecId(0x901);
253
254    // ISO, IEC, MPEG codecs
255
256    /// MPEG-1 Video (MPEG-1 Part 2)
257    pub const CODEC_ID_MPEG1: VideoCodecId = VideoCodecId(0xa00);
258    /// MPEG-2 Video (MPEG-2 Part 2)
259    pub const CODEC_ID_MPEG2: VideoCodecId = VideoCodecId(0xa01);
260    /// MPEG-4 Video (MPEG-2 Part 2)
261    pub const CODEC_ID_MPEG4: VideoCodecId = VideoCodecId(0xa02);
262
263    // ITU-T codecs
264
265    /// H.261
266    pub const CODEC_ID_H261: VideoCodecId = VideoCodecId(0xb01);
267    /// H.263
268    pub const CODEC_ID_H263: VideoCodecId = VideoCodecId(0xb03);
269    /// Advanced Video Codec (AVC, MPEG-4 AVC, MPEG-4 Part 10, H.264)
270    pub const CODEC_ID_H264: VideoCodecId = VideoCodecId(0xb04);
271    /// High Efficiency Video Coding (HEVC, H.265, MPEG-H Part 2)
272    pub const CODEC_ID_HEVC: VideoCodecId = VideoCodecId(0xb05);
273    /// Versatile Video Coding (VVC, H.266, MPEG-I Part 3)
274    pub const CODEC_ID_VVC: VideoCodecId = VideoCodecId(0xb06);
275
276    // SMPTE codecs
277
278    /// SMPTE VC-1
279    pub const CODEC_ID_VC1: VideoCodecId = VideoCodecId(0xc00);
280
281    // Audio Video Standard (AVS) codecs
282
283    /// Audio Video Standard (AVS) 1
284    pub const CODEC_ID_AVS1: VideoCodecId = VideoCodecId(0xd00);
285    /// Audio Video Standard (AVS) 2
286    pub const CODEC_ID_AVS2: VideoCodecId = VideoCodecId(0xd01);
287    /// Audio Video Standard (AVS) 3
288    pub const CODEC_ID_AVS3: VideoCodecId = VideoCodecId(0xd02);
289
290    /// Codec profiles for well-known video codecs.
291    pub mod profiles {
292        use crate::codecs::CodecProfile;
293
294        // AV1 profiles
295        //-------------
296
297        /// AV1 Main Profile
298        pub const CODEC_PROFILE_AV1_MAIN: CodecProfile = CodecProfile(0);
299        /// AV1 High Profile
300        pub const CODEC_PROFILE_AV1_HIGH: CodecProfile = CodecProfile(1);
301        /// AV1 Professional Profile
302        pub const CODEC_PROFILE_AV1_PROFESSIONAL: CodecProfile = CodecProfile(2);
303
304        // MPEG-2 profiles
305        //----------------
306
307        /// MPEG-2 Video Simple Profile (SP)
308        pub const CODEC_PROFILE_MPEG2_SIMPLE: CodecProfile = CodecProfile(0);
309        /// MPEG-2 Video Main Profile (MP)
310        pub const CODEC_PROFILE_MPEG2_MAIN: CodecProfile = CodecProfile(1);
311        /// MPEG-2 Video SNR Scalable Profile
312        pub const CODEC_PROFILE_MPEG2_SNR_SCALABLE: CodecProfile = CodecProfile(2);
313        /// MPEG-2 Video Spatial Scalable Profile
314        pub const CODEC_PROFILE_MPEG2_SPATIAL_SCALABLE: CodecProfile = CodecProfile(3);
315        /// MPEG-2 Video High Profile (HP)
316        pub const CODEC_PROFILE_MPEG2_HIGH: CodecProfile = CodecProfile(4);
317        /// MPEG-2 Video 4:2:2 Profile (422)
318        pub const CODEC_PROFILE_MPEG2_422: CodecProfile = CodecProfile(5);
319
320        // MPEG-4 profiles
321        //---------------
322
323        /// MPEG-4 Video Simple Profile (SP)
324        pub const CODEC_PROFILE_MPEG4_SIMPLE: CodecProfile = CodecProfile(0);
325        /// MPEG-4 Video Advanced Simple Profile (ASP)
326        pub const CODEC_PROFILE_MPEG4_ADVANCED_SIMPLE: CodecProfile = CodecProfile(1);
327
328        // H264 profiles
329        //--------------
330
331        /// H.264 Baseline Profile (BP)
332        pub const CODEC_PROFILE_H264_BASELINE: CodecProfile = CodecProfile(66);
333        /// H.264 Contrained Baseline Profile (CBP)
334        pub const CODEC_PROFILE_H264_CONSTRAINED_BASELINE: CodecProfile =
335            CodecProfile(66 | 1 << (8 + 1)); // Constraint set 1
336        /// H.264 Main Profile (MP)
337        pub const CODEC_PROFILE_H264_MAIN: CodecProfile = CodecProfile(77);
338        /// H.264 Extended Profile (XP)
339        pub const CODEC_PROFILE_H264_EXTENDED: CodecProfile = CodecProfile(88);
340        /// H.264 High Profile (HiP)
341        pub const CODEC_PROFILE_H264_HIGH: CodecProfile = CodecProfile(100);
342        /// H.264 Progressive High Profile (PHiP)
343        pub const CODEC_PROFILE_H264_PROGRESSIVE_HIGH: CodecProfile =
344            CodecProfile(100 | 1 << (8 + 4)); // Constraint set 4
345        /// H.264 Constrained High profile
346        pub const CODEC_PROFILE_H264_CONSTRAINED_HIGH: CodecProfile =
347            CodecProfile(100 | 1 << (8 + 4) | 1 << (8 + 5)); // Constraint set 4 & 5
348        /// H.264 High 10 Profile (Hi10P)
349        pub const CODEC_PROFILE_H264_HIGH_10: CodecProfile = CodecProfile(110);
350        /// H.264 High 10 Intra Profile
351        pub const CODEC_PROFILE_H264_HIGH_10_INTRA: CodecProfile = CodecProfile(110 | 1 << (8 + 3)); // Constraint set 3
352        /// H.264 High 4:2:2 Profile (Hi422P)
353        pub const CODEC_PROFILE_H264_HIGH_422: CodecProfile = CodecProfile(122);
354        /// H.264 High 4:2:2 Intra Profile
355        pub const CODEC_PROFILE_H264_HIGH_422_INTRA: CodecProfile =
356            CodecProfile(122 | 1 << (8 + 3)); // Constraint set 3
357        /// H.264 High 4:4:4 Profile (Hi444P)
358        pub const CODEC_PROFILE_H264_HIGH_444: CodecProfile = CodecProfile(144);
359        /// H.264 High 4:4:4 Predictive Profile (Hi444PP)
360        pub const CODEC_PROFILE_H264_HIGH_444_PREDICTIVE: CodecProfile = CodecProfile(244);
361        /// H.264 High 4:4:4 Intra Profile
362        pub const CODEC_PROFILE_H264_HIGH_444_INTRA: CodecProfile =
363            CodecProfile(244 | 1 << (8 + 3)); // Constraint set 3
364        /// H.264 CAVLC 4:4:4 Profile
365        pub const CODEC_PROFILE_H264_CAVLC_444: CodecProfile = CodecProfile(44);
366
367        // HEVC profiles
368        //--------------
369
370        /// HEVC Main Profile
371        pub const CODEC_PROFILE_HEVC_MAIN: CodecProfile = CodecProfile(1);
372        /// HEVC Main 10 Profile
373        pub const CODEC_PROFILE_HEVC_MAIN_10: CodecProfile = CodecProfile(2);
374        /// HEVC Main Still Picture Profile
375        pub const CODEC_PROFILE_HEVC_MAIN_STILL_PICTURE: CodecProfile = CodecProfile(3);
376
377        // VP9 profiles
378        //-------------
379
380        /// VP9 Profile 0
381        pub const CODEC_PROFILE_VP9_0: CodecProfile = CodecProfile(0);
382        /// VP9 Profile 1
383        pub const CODEC_PROFILE_VP9_1: CodecProfile = CodecProfile(1);
384        /// VP9 Profile 2
385        pub const CODEC_PROFILE_VP9_2: CodecProfile = CodecProfile(2);
386        /// VP9 Profile 3
387        pub const CODEC_PROFILE_VP9_3: CodecProfile = CodecProfile(3);
388
389        // VC1 profiles
390        //-------------
391
392        /// VC-1 Simple Profile
393        pub const CODEC_PROFILE_VC1_SIMPLE: CodecProfile = CodecProfile(0);
394        /// VC-1 Main Profile
395        pub const CODEC_PROFILE_VC1_MAIN: CodecProfile = CodecProfile(1);
396        /// VC-1 Advanced Profile
397        pub const CODEC_PROFILE_VC1_ADVANCED: CodecProfile = CodecProfile(2);
398    }
399
400    pub mod extra_data {
401        use crate::codecs::video::VideoExtraDataId;
402
403        /// AVCDecoderConfigurationRecord
404        pub const VIDEO_EXTRA_DATA_ID_AVC_DECODER_CONFIG: VideoExtraDataId = VideoExtraDataId(1);
405
406        /// HEVCDecoderConfigurationRecord
407        pub const VIDEO_EXTRA_DATA_ID_HEVC_DECODER_CONFIG: VideoExtraDataId = VideoExtraDataId(2);
408
409        /// VP9DecoderConfiguration
410        pub const VIDEO_EXTRA_DATA_ID_VP9_DECODER_CONFIG: VideoExtraDataId = VideoExtraDataId(3);
411
412        /// AV1DecoderConfiguration
413        pub const VIDEO_EXTRA_DATA_ID_AV1_DECODER_CONFIG: VideoExtraDataId = VideoExtraDataId(4);
414
415        /// DolbyVisionConfiguration
416        pub const VIDEO_EXTRA_DATA_ID_DOLBY_VISION_CONFIG: VideoExtraDataId = VideoExtraDataId(5);
417
418        /// DolbyVision EL HEVC
419        pub const VIDEO_EXTRA_DATA_ID_DOLBY_VISION_EL_HEVC: VideoExtraDataId = VideoExtraDataId(6);
420    }
421}
symphonia_core/codecs/video.rs

symphonia_core/codecs/
video.rs
