vast4_rs/
media_file.rs

1/// The container for [`<MediaFile>`](MediaFile), [`<Mezzanine>`](Mezzanine),
2/// [`<InteractiveCreativeFile>`](InteractiveCreativeFile) and
3/// [`ClosedCaptionFiles`](ClosedCaptionFiles).
4///
5/// ```text
6/// <xs:element name="MediaFiles" minOccurs="1" maxOccurs="1">
7///   <xs:complexType>
8///     <xs:sequence>
9///       <xs:element name="ClosedCaptionFiles" minOccurs="0" maxOccurs="1">
10///       <xs:element name="MediaFile" minOccurs="1" maxOccurs="unbounded">
11///       <xs:element name="Mezzanine" minOccurs="0" maxOccurs="unbounded">
12///       <xs:element name="InteractiveCreativeFile" minOccurs="0" maxOccurs="unbounded">
13///     </xs:sequence>
14///   </xs:complexType>
15/// </xs:element>
16/// ```
17#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
18#[xml(tag = "MediaFiles")]
19pub struct MediaFiles<'a> {
20    /// The container for zero or one [`<ClosedCaptionFiles>`](ClosedCaptionFiles) element.
21    #[xml(child = "ClosedCaptionFiles", default)]
22    pub closed_caption_files: Option<ClosedCaptionFiles<'a>>,
23    /// The container for one or more [`<MediaFile>`](MediaFile) element.
24    #[xml(child = "MediaFile", default)]
25    pub media_files: Vec<MediaFile<'a>>,
26    /// The container for zero or more [`<Mezzanine>`](Mezzanine) elements.
27    #[xml(child = "Mezzanine", default)]
28    pub mezzanines: Vec<Mezzanine<'a>>,
29    /// The container for zero or more [`<InteractiveCreativeFile>`](InteractiveCreativeFile)
30    /// elements.
31    #[xml(child = "InteractiveCreativeFile", default)]
32    pub interactive_creative_files: Vec<InteractiveCreativeFile<'a>>,
33}
34
35/// In VAST 4.x `<MediaFile>` should only be used to contain the video or audio file for a
36/// [`Linear`](crate::Linear) ad.
37///
38/// ```text
39/// <xs:element name="MediaFile">
40///   <xs:complexType>
41///     <xs:simpleContent>
42///       <xs:extension base="xs:anyURI">
43///         <xs:attribute name="id" type="xs:string" use="optional">
44///         <xs:attribute name="delivery" use="required">
45///         <xs:attribute name="type" type="xs:string" use="required">
46///         <xs:attribute name="width" type="xs:integer" use="required">
47///         <xs:attribute name="height" type="xs:integer" use="required">
48///         <xs:attribute name="codec" type="xs:string" use="optional">
49///         <xs:attribute name="bitrate" type="xs:integer" use="optional">
50///         <xs:attribute name="minBitrate" type="xs:integer" use="optional">
51///         <xs:attribute name="maxBitrate" type="xs:integer" use="optional">
52///         <xs:attribute name="scalable" type="xs:boolean" use="optional">
53///         <xs:attribute name="maintainAspectRatio" type="xs:boolean" use="optional">
54///         <xs:attribute name="fileSize" type="xs:integer" use="optional">
55///         <xs:attribute name="mediaType" type="xs:string" use="optional">
56///         <xs:attribute name="apiFramework" type="xs:string" use="optional">
57///       </xs:extension>
58///     </xs:simpleContent>
59///   </xs:complexType>
60/// </xs:element>
61/// ```
62#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
63#[xml(tag = "MediaFile")]
64pub struct MediaFile<'a> {
65    /// An identifier for the media file.
66    #[xml(attr = "id", default)]
67    pub id: Option<std::borrow::Cow<'a, str>>,
68    /// Either “progressive” for progressive download protocols (such as HTTP) or
69    /// “streaming” for streaming protocols.
70    #[xml(attr = "delivery", default)]
71    pub delivery: DeliveryProtocol,
72    // TODO: typed value
73    /// MIME type for the file container. Popular MIME types include, but are not
74    /// limited to “video/mp4” for MP4, “audio/mpeg” and "audio/aac" for audio ads.
75    #[xml(attr = "type", default)]
76    pub mime_type: std::borrow::Cow<'a, str>,
77    /// The native width of the video file, in pixels. (0 for audio ads)
78    #[xml(attr = "width", default)]
79    pub width: i32,
80    /// The native height of the video file, in pixels. (0 for audio ads)
81    #[xml(attr = "height", default)]
82    pub height: i32,
83    // TODO: typed value
84    /// The codec used to encode the file which can take values as specified by
85    /// [RFC 4281](http://tools.ietf.org/html/rfc4281).
86    #[xml(attr = "codec", default)]
87    pub codec: Option<std::borrow::Cow<'a, str>>,
88    /// For progressive load video or audio, the `bitrate` value specifies the average
89    /// bitrate for the media file; otherwise the `minBitrate` and `maxBitrate` can be
90    /// used together to specify the minimum and maximum bitrates for streaming
91    /// videos or audio files.
92    #[xml(attr = "bitrate", default)]
93    pub bitrate: Option<i32>,
94    /// The `minBitrate` is minimum bitrate for streaming videos or audio files.
95    /// Can be used with `maxBitrate` to specify bitrate.
96    #[xml(attr = "minBitrate", default)]
97    pub min_bitrate: Option<i32>,
98    /// The `maxBitrate` is maximum bitrate for streaming videos or audio files.
99    /// Can be used with `minBitrate` to specify bitrate.
100    #[xml(attr = "maxBitrate", default)]
101    pub max_bitrate: Option<i32>,
102    /// A Boolean value that indicates whether the media file is meant to scale to larger
103    /// dimensions.
104    #[xml(attr = "scalable", default)]
105    pub scalable: Option<bool>,
106    /// A Boolean value that indicates whether aspect ratio for media file dimensions
107    /// should be maintained when scaled to new dimensions.
108    #[xml(attr = "maintainAspectRatio", default)]
109    pub maintain_aspect_ratio: Option<bool>,
110    /// Optional field that helps eliminate the need to calculate the size based on
111    /// bitrate and duration.
112    /// Units - Bytes
113    #[xml(attr = "fileSize", default)]
114    pub file_size: Option<i32>,
115    // TODO: typed value
116    /// Type of media file (2D / 3D / 360 / etc).
117    /// Optional. Default value = 2D
118    #[xml(attr = "mediaType", default)]
119    pub media_type: Option<std::borrow::Cow<'a, str>>,
120    /// Identifies the API needed to execute an interactive media file,
121    /// but current support is for backward compatibility. Please use the
122    /// [`<InteractiveCreativeFile>`](InteractiveCreativeFile) element to
123    /// include files that require an API for execution.
124    #[deprecated(since = "VAST 4.1")]
125    #[xml(attr = "apiFramework", default)]
126    pub api_framework: Option<std::borrow::Cow<'a, str>>,
127
128    /// A CDATA-wrapped URI to a media file.
129    #[xml(text, cdata, default)]
130    pub uri: std::borrow::Cow<'a, str>,
131}
132
133/// Represents the video delivery protocol type.
134///
135/// ```text
136/// <xs:simpleType>
137///   <xs:restriction base="xs:token">
138///     <xs:enumeration value="streaming" />
139///     <xs:enumeration value="progressive" />
140///   </xs:restriction>
141/// </xs:simpleType>
142/// ```
143#[derive(Default, PartialEq, Clone, Debug)]
144pub enum DeliveryProtocol {
145    /// Progressive download protocols (such as HTTP).
146    #[default]
147    Progressive,
148    /// Streaming protocols.
149    Streaming,
150    // Catch All
151    Unknown(crate::UnknownEvent),
152}
153
154impl std::str::FromStr for DeliveryProtocol {
155    type Err = crate::VastParseError;
156
157    fn from_str(s: &str) -> Result<Self, Self::Err> {
158        Ok(match s {
159            "progressive" => Self::Progressive,
160            "streaming" => Self::Streaming,
161            _ => Self::Unknown(crate::UnknownEvent {
162                body: s.to_string(),
163            }),
164        })
165    }
166}
167
168impl std::fmt::Display for DeliveryProtocol {
169    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
170        match self {
171            Self::Progressive => write!(f, "progressive"),
172            Self::Streaming => write!(f, "streaming"),
173            Self::Unknown(b) => write!(f, "{}", b.body),
174        }
175    }
176}
177
178/// The mezzanine file specifications are defined in the [Digital Video Ad Format Guidelines](https://www.iab.com/wp-content/uploads/2016/01/DVAFG_2015-01-08.pdf).
179///
180/// ```text
181/// <xs:element name="Mezzanine" minOccurs="0" maxOccurs="unbounded">
182///   <xs:complexType>
183///     <xs:simpleContent>
184///       <xs:extension base="xs:anyURI">
185///         <xs:attribute name="id" type="xs:string" use="optional">
186///         <xs:attribute name="delivery" use="required">
187///         <xs:attribute name="type" type="xs:string" use="required">
188///         <xs:attribute name="width" type="xs:integer" use="required">
189///         <xs:attribute name="height" type="xs:integer" use="required">
190///         <xs:attribute name="codec" type="xs:string" use="optional">
191///         <xs:attribute name="fileSize" type="xs:integer" use="optional">
192///         <xs:attribute name="mediaType" type="xs:string" use="optional">
193///       </xs:extension>
194///     </xs:simpleContent>
195///   </xs:complexType>
196/// </xs:element>
197/// ```
198#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
199#[xml(tag = "Mezzanine")]
200pub struct Mezzanine<'a> {
201    /// An identifier for the media file.
202    #[xml(attr = "id", default)]
203    pub id: Option<std::borrow::Cow<'a, str>>,
204    /// Either “progressive” for progressive download protocols (such as HTTP) or
205    /// “streaming” for streaming protocols.
206    #[xml(attr = "delivery", default)]
207    pub delivery: DeliveryProtocol,
208    /// MIME type for the file container. Popular MIME types include, but are not
209    /// limited to “video/mp4” for MP4, “audio/mpeg” and "audio/aac" for audio ads.
210    #[xml(attr = "type", default)]
211    pub mime_type: std::borrow::Cow<'a, str>,
212    /// The native width of the video file, in pixels. (0 for audio ads)
213    #[xml(attr = "width", default)]
214    pub width: i32,
215    /// The native height of the video file, in pixels. (0 for audio ads)
216    #[xml(attr = "height", default)]
217    pub height: i32,
218    /// The codec used to encode the file which can take values as specified by
219    /// [RFC 4281](http://tools.ietf.org/html/rfc4281).
220    #[xml(attr = "codec", default)]
221    pub codec: Option<std::borrow::Cow<'a, str>>,
222    /// Optional field that helps eliminate the need to calculate the size based on
223    /// bitrate and duration.
224    /// Units - Bytes
225    #[xml(attr = "fileSize", default)]
226    pub file_size: Option<i32>,
227    // TODO: typed value
228    /// Type of media file (2D / 3D / 360 / etc).
229    /// Optional. Default value = 2D
230    #[xml(attr = "mediaType", default)]
231    pub media_type: Option<std::borrow::Cow<'a, str>>,
232
233    /// A CDATA-wrapped URI to a raw, high-quality media file.
234    #[xml(text, cdata, default)]
235    pub uri: std::borrow::Cow<'a, str>,
236}
237
238/// The `<InteractiveCreativeFile>` element is used to identify the file and the framework
239/// needed for execution.
240///
241/// ```text
242/// <xs:element name="InteractiveCreativeFile" minOccurs="0" maxOccurs="unbounded">
243///   <xs:complexType>
244///     <xs:simpleContent>
245///       <xs:extension base="xs:anyURI">
246///         <xs:attribute name="type" type="xs:string" use="optional">
247///         <xs:attribute name="apiFramework" type="xs:string" use="optional">
248///         <xs:attribute name="variableDuration" type="xs:boolean" use="optional">
249///       </xs:extension>
250///     </xs:simpleContent>
251///   </xs:complexType>
252/// </xs:element>
253/// ```
254#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
255#[xml(tag = "InteractiveCreativeFile")]
256pub struct InteractiveCreativeFile<'a> {
257    /// Identifies the MIME type of the file provided.
258    #[xml(attr = "type", default)]
259    pub mime_type: Option<std::borrow::Cow<'a, str>>,
260    /// Identifies the API needed to execute the resource file if applicable.
261    #[xml(attr = "apiFramework", default)]
262    pub api_framework: Option<std::borrow::Cow<'a, str>>,
263    /// Useful for interactive use cases. Identifies whether the ad always drops when the
264    /// duration is reached, or if it can potentially extend the duration by pausing the
265    /// underlying video or delaying the adStopped call after adVideoComplete.
266    #[xml(attr = "variableDuration", default)]
267    pub variable_duration: Option<bool>,
268
269    /// A CDATA-wrapped URI to a file providing creative functions for the media file.
270    #[xml(text, cdata, default)]
271    pub uri: std::borrow::Cow<'a, str>,
272}
273
274/// Optional node that enables closed caption sidecar files associated with the ad media (video or
275/// audio) to be provided to the player.
276///
277/// ```text
278/// <xs:element name="ClosedCaptionFiles">
279///   <xs:complexType>
280///     <xs:sequence>
281///       <xs:element name="ClosedCaptionFile" minOccurs="0" maxOccurs="unbounded">
282///     </xs:sequence>
283///   </xs:complexType>
284/// </xs:element>
285/// ```
286#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
287#[xml(tag = "ClosedCaptionFiles")]
288pub struct ClosedCaptionFiles<'a> {
289    /// The container for zero or more [`<ClosedCaptionFile>`](ClosedCaptionFile) element.
290    #[xml(child = "ClosedCaptionFile")]
291    pub closed_caption_files: Vec<ClosedCaptionFile<'a>>,
292}
293
294/// Individual closed caption files for various languages.
295///
296/// ```text
297/// <xs:element name="ClosedCaptionFile">
298///   <xs:complexType>
299///     <xs:simpleContent>
300///       <xs:extension base="xs:anyURI">
301///         <xs:attribute name="type" type="xs:string" use="optional">
302///         <xs:attribute name="language" type="xs:string" use="optional">
303///       </xs:extension>
304///     </xs:simpleContent>
305///   </xs:complexType>
306/// </xs:element>
307/// ```
308#[derive(hard_xml::XmlWrite, hard_xml::XmlRead, Default, PartialEq, Clone, Debug)]
309#[xml(tag = "ClosedCaptionFile")]
310pub struct ClosedCaptionFile<'a> {
311    /// Identifies the MIME type of the file provided.
312    #[xml(attr = "type", default)]
313    pub mime_type: Option<std::borrow::Cow<'a, str>>,
314    // TODO: typed value
315    /// Language of the Closed Caption File using ISO 631-1 codes. An optional locale
316    /// suffix can also be provided.
317    /// Example:- “en”, “en-US”, “zh-TW”
318    #[xml(attr = "language", default)]
319    pub language: Option<std::borrow::Cow<'a, str>>,
320
321    /// A CDATA-wrapped URI to a file providing Closed Caption info for the media file.
322    #[xml(text, cdata, default)]
323    pub uri: std::borrow::Cow<'a, str>,
324}
vast4_rs/media_file.rs

vast4_rs/
media_file.rs
