mp4ra_rust/
lib.rs

1//! Types with associated constants representing code points managed by the
2//! [MPEG4 Registration Authority](https://mp4ra.org/).
3//!
4//! This crate has been generated from
5//! [metadata published by the MP4RA](https://github.com/mp4ra/mp4ra.github.io/tree/dev/CSV)
6//! (by code in the [mp4ra-rust project](https://github.com/dholroyd/mp4ra-rust)).
7
8#![forbid(unsafe_code)]
9#![deny(rust_2018_idioms, future_incompatible, missing_docs)]
10
11pub use four_cc::FourCC;
12use std::fmt;
13
14include!("generated.rs");
15
16/// _Object Type Identification_ values.
17///
18/// See also,
19///  - the [Object Types section on mp4ra.org](http://mp4ra.org/#/object_types)
20///
21/// ## Conversions to and from `u8`
22///
23/// Conversion to or from `u8` will work for any value.
24///
25/// ```rust
26/// # use mp4ra_rust::ObjectTypeIdentifier;
27/// assert_eq!(ObjectTypeIdentifier::VISUAL_ISO_IEC_13818_2_MAIN_PROFILE, 0x61.into());
28/// assert_eq!(0x61u8, ObjectTypeIdentifier::VISUAL_ISO_IEC_13818_2_MAIN_PROFILE.into());
29/// ```
30///
31/// ## `Debug` implementation
32///
33/// The implementation of `Debug` tries to be helpful,
34///
35/// ```rust
36/// # use mp4ra_rust::ObjectTypeIdentifier;
37/// assert_eq!(
38///     "VISUAL_ISO_IEC_13818_2_MAIN_PROFILE(0x61)",
39///     format!("{:?}", ObjectTypeIdentifier::VISUAL_ISO_IEC_13818_2_MAIN_PROFILE)
40/// );
41/// ```
42///
43/// ## Identifier values without provided constants
44///
45/// Constants are not provided for the range of values that the spec notes are _reserved_, but
46/// you are still able to create ObjectTypeIdentification instances taking these values for the
47/// sake of forward compatibility.
48///
49/// The spec also notes that some identifier values have been withdrawn and are deprecated.
50/// Constants are not provided for these either.
51///
52/// Finally, some values are marked for _user private_ use, meaning that future versions of the
53/// spec will avoid using these values.
54///
55/// While there are no specific constants for any of these, the implementation of `Debug` still
56/// gives them special treatment,
57///
58/// ```rust
59/// # use mp4ra_rust::ObjectTypeIdentifier;
60/// assert_eq!("RESERVED(0x0b)", format!("{:?}", ObjectTypeIdentifier::from(0x0b)));
61/// assert_eq!("WITHDRAWN(0xa5)", format!("{:?}", ObjectTypeIdentifier::from(0xa5)));
62/// assert_eq!("USER_PRIVATE(0xc0)", format!("{:?}", ObjectTypeIdentifier::from(0xc0)))
63/// ```
64///
65/// ## Defining constants
66///
67/// You may define your own constant values.  For example for application specific values that the
68/// spec puts in the _user private_ range.  Note however that you can't change the output which
69/// the `Debug` implementation produces for these values.
70///
71/// ```rust
72/// # use mp4ra_rust::ObjectTypeIdentifier;
73/// # let other_oti = ObjectTypeIdentifier::AFX_STREAM;
74/// const MY_SPECIAL_OBJECT_TYPE: ObjectTypeIdentifier = ObjectTypeIdentifier(0xc1);
75/// match other_oti {
76///     MY_SPECIAL_OBJECT_TYPE => println!("special object"),
77///     _ => println!("other type"),
78/// }
79/// // can't customise this "USER_PRIVATE" text,
80/// assert_eq!("USER_PRIVATE(0xc1)", format!("{:?}", MY_SPECIAL_OBJECT_TYPE))
81/// ```
82#[derive(Clone, Copy, Eq, PartialEq)]
83pub struct ObjectTypeIdentifier(pub u8);
84impl From<ObjectTypeIdentifier> for u8 {
85    fn from(val: ObjectTypeIdentifier) -> Self {
86        val.0
87    }
88}
89impl From<u8> for ObjectTypeIdentifier {
90    fn from(val: u8) -> Self {
91        ObjectTypeIdentifier(val)
92    }
93}
94
95/// Codes identifying _handlers_, that declare track-types.
96///
97/// Commonly used values,
98///  - [`HandlerCode::VIDE`](#associatedconstant.VIDE) - the code for video
99///  - [`HandlerCode::SOUN`](#associatedconstant.SOUN) - the code for audio
100///  - [`HandlerCode::TEXT`](#associatedconstant.TEXT) - the code for timed-text
101///
102/// See also,
103///  - the [Handlers section on mp4ra.org](http://mp4ra.org/#/handlers)
104#[derive(Clone, Copy, Eq, PartialEq, Debug)]
105pub struct HandlerCode(pub FourCC);
106impl HandlerCode {
107    /// Construct a `HandlerCode` from its four-cc value
108    pub const fn new(code: [u8; 4]) -> HandlerCode {
109        HandlerCode(FourCC(code))
110    }
111}
112impl From<HandlerCode> for FourCC {
113    fn from(val: HandlerCode) -> Self {
114        val.0
115    }
116}
117impl From<FourCC> for HandlerCode {
118    fn from(val: FourCC) -> Self {
119        HandlerCode(val)
120    }
121}
122
123/// Codes identifying _sample entries_ registered with ISO.
124///
125/// The `handler()` method will give you the code for the handler specified for this kind of
126/// _sample entry_, if a single handler is defined for it by MP4RA.
127///
128/// For example, to test if the _sample entry_ is audio or video,
129///
130/// ```rust
131/// # use mp4ra_rust::SampleEntryCode;
132/// use mp4ra_rust::HandlerCode;
133///
134/// let sample_entry1 = SampleEntryCode::AVC1;
135/// assert_eq!(sample_entry1.handler(), Some(HandlerCode::VIDE));
136///
137/// let sample_entry2 = SampleEntryCode::MP4A;
138/// assert_eq!(sample_entry2.handler(), Some(HandlerCode::SOUN));
139/// ```
140///
141/// See also,
142///  - the [Sample Entry Codes section on mp4ra.org](http://mp4ra.org/#/qtcodecs)
143#[derive(Clone, Copy, Eq, PartialEq, Debug)]
144pub struct SampleEntryCode(pub FourCC);
145impl SampleEntryCode {
146    /// Construct a `SampleEntryCode` from its four-cc value
147    pub const fn new(code: [u8; 4]) -> SampleEntryCode {
148        SampleEntryCode(FourCC(code))
149    }
150}
151impl From<SampleEntryCode> for FourCC {
152    fn from(val: SampleEntryCode) -> Self {
153        val.0
154    }
155}
156impl From<FourCC> for SampleEntryCode {
157    fn from(val: FourCC) -> Self {
158        SampleEntryCode(val)
159    }
160}
161
162/// Codes for ISO-family _box_ entries within an MP4 file.
163///
164/// See also,
165///  - the [Boxes section on mp4ra.org](http://mp4ra.org/#/atoms)
166#[derive(Clone, Copy, Eq, PartialEq, Debug)]
167pub struct BoxCode(pub FourCC);
168impl BoxCode {
169    /// Construct a `BoxCode` from its four-cc value
170    pub const fn new(code: [u8; 4]) -> BoxCode {
171        BoxCode(FourCC(code))
172    }
173}
174impl From<BoxCode> for FourCC {
175    fn from(val: BoxCode) -> Self {
176        val.0
177    }
178}
179impl From<FourCC> for BoxCode {
180    fn from(val: FourCC) -> Self {
181        BoxCode(val)
182    }
183}
184
185/// Codes for MPEG4 _brands_, identifying with which specification some MP4 data is compatible .
186///
187/// See also,
188///  - the [Brands section on mp4ra.org](http://mp4ra.org/#/brands)
189#[derive(Clone, Copy, Eq, PartialEq, Debug)]
190pub struct BrandCode(pub FourCC);
191impl BrandCode {
192    /// Construct a `BrandCode` from its four-cc value
193    pub const fn new(code: [u8; 4]) -> BrandCode {
194        BrandCode(FourCC(code))
195    }
196}
197impl From<BrandCode> for FourCC {
198    fn from(val: BrandCode) -> Self {
199        val.0
200    }
201}
202impl From<FourCC> for BrandCode {
203    fn from(val: FourCC) -> Self {
204        BrandCode(val)
205    }
206}
207
208/// Codes for _track reference link types_.
209///
210/// See also,
211///  - the [Track References section on mp4ra.org](http://mp4ra.org/#/track_references)
212#[derive(Clone, Copy, Eq, PartialEq, Debug)]
213pub struct TrackReferenceCode(pub FourCC);
214impl TrackReferenceCode {
215    /// Construct a `TrackReferenceCode` from its four-cc value
216    pub const fn new(code: [u8; 4]) -> TrackReferenceCode {
217        TrackReferenceCode(FourCC(code))
218    }
219}
220impl From<TrackReferenceCode> for FourCC {
221    fn from(val: TrackReferenceCode) -> Self {
222        val.0
223    }
224}
225impl From<FourCC> for TrackReferenceCode {
226    fn from(val: FourCC) -> Self {
227        TrackReferenceCode(val)
228    }
229}
mp4ra_rust/lib.rs

mp4ra_rust/
lib.rs
