FFmpeg
imf.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /*
20  *
21  * Copyright (c) Sandflow Consulting LLC
22  *
23  * Redistribution and use in source and binary forms, with or without
24  * modification, are permitted provided that the following conditions are met:
25  *
26  * * Redistributions of source code must retain the above copyright notice, this
27  * list of conditions and the following disclaimer.
28  * * Redistributions in binary form must reproduce the above copyright notice,
29  * this list of conditions and the following disclaimer in the documentation
30  * and/or other materials provided with the distribution.
31  *
32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
33  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
34  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
35  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
36  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
37  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
38  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
39  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
40  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
41  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
42  * POSSIBILITY OF SUCH DAMAGE.
43  */
44 
45 /**
46  * Public header file for the processing of Interoperable Master Format (IMF)
47  * packages.
48  *
49  * @author Pierre-Anthony Lemieux
50  * @author Valentin Noel
51  * @file
52  * @ingroup lavu_imf
53  */
54 
55 #ifndef AVFORMAT_IMF_H
56 #define AVFORMAT_IMF_H
57 
58 #include "avformat.h"
59 #include "libavformat/avio.h"
60 #include "libavutil/rational.h"
61 #include <libxml/tree.h>
62 
63 #define FF_IMF_UUID_FORMAT \
64  "urn:uuid:%02hhx%02hhx%02hhx%02hhx-%02hhx%02hhx-" \
65  "%02hhx%02hhx-%02hhx%02hhx-%02hhx%02hhx%02hhx%02hhx%02hhx%02hhx"
66 
67 /**
68  * UUID as defined in IETF RFC 422
69  */
70 typedef uint8_t FFIMFUUID[16];
71 
72 /**
73  * IMF Composition Playlist Base Resource
74  */
75 typedef struct FFIMFBaseResource {
76  AVRational edit_rate; /**< BaseResourceType/EditRate */
77  uint32_t entry_point; /**< BaseResourceType/EntryPoint */
78  uint32_t duration; /**< BaseResourceType/Duration */
79  uint32_t repeat_count; /**< BaseResourceType/RepeatCount */
81 
82 /**
83  * IMF Composition Playlist Track File Resource
84  */
85 typedef struct FFIMFTrackFileResource {
87  FFIMFUUID track_file_uuid; /**< TrackFileResourceType/TrackFileId */
89 
90 /**
91  * IMF Marker
92  */
93 typedef struct FFIMFMarker {
94  xmlChar *label_utf8; /**< Marker/Label */
95  xmlChar *scope_utf8; /**< Marker/Label/\@scope */
96  uint32_t offset; /**< Marker/Offset */
97 } FFIMFMarker;
98 
99 /**
100  * IMF Composition Playlist Marker Resource
101  */
102 typedef struct FFIMFMarkerResource {
104  uint32_t marker_count; /**< Number of Marker elements */
105  FFIMFMarker *markers; /**< Marker elements */
107 
108 /**
109  * IMF Composition Playlist Virtual Track
110  */
111 typedef struct FFIMFBaseVirtualTrack {
112  FFIMFUUID id_uuid; /**< TrackId associated with the Virtual Track */
114 
115 /**
116  * IMF Composition Playlist Virtual Track that consists of Track File Resources
117  */
120  uint32_t resource_count; /**< Number of Resource elements present in the Virtual Track */
121  FFIMFTrackFileResource *resources; /**< Resource elements of the Virtual Track */
122  unsigned int resources_alloc_sz; /**< Size of the resources buffer */
124 
125 /**
126  * IMF Composition Playlist Virtual Track that consists of Marker Resources
127  */
128 typedef struct FFIMFMarkerVirtualTrack {
130  uint32_t resource_count; /**< Number of Resource elements present in the Virtual Track */
131  FFIMFMarkerResource *resources; /**< Resource elements of the Virtual Track */
133 
134 /**
135  * IMF Composition Playlist
136  */
137 typedef struct FFIMFCPL {
138  FFIMFUUID id_uuid; /**< CompositionPlaylist/Id element */
139  xmlChar *content_title_utf8; /**< CompositionPlaylist/ContentTitle element */
140  AVRational edit_rate; /**< CompositionPlaylist/EditRate element */
141  FFIMFMarkerVirtualTrack *main_markers_track; /**< Main Marker Virtual Track */
142  FFIMFTrackFileVirtualTrack *main_image_2d_track; /**< Main Image Virtual Track */
143  uint32_t main_audio_track_count; /**< Number of Main Audio Virtual Tracks */
144  FFIMFTrackFileVirtualTrack *main_audio_tracks; /**< Main Audio Virtual Tracks */
145 } FFIMFCPL;
146 
147 /**
148  * Parse an IMF CompositionPlaylist element into the FFIMFCPL data structure.
149  * @param[in] doc An XML document from which the CPL is read.
150  * @param[out] cpl Pointer to a memory area (allocated by the client), where the
151  * function writes a pointer to the newly constructed FFIMFCPL structure (or
152  * NULL if the CPL could not be parsed). The client is responsible for freeing
153  * the FFIMFCPL structure using ff_imf_cpl_free().
154  * @return A non-zero value in case of an error.
155  */
156 int ff_imf_parse_cpl_from_xml_dom(xmlDocPtr doc, FFIMFCPL **cpl);
157 
158 /**
159  * Parse an IMF Composition Playlist document into the FFIMFCPL data structure.
160  * @param[in] in The context from which the CPL is read.
161  * @param[out] cpl Pointer to a memory area (allocated by the client), where the
162  * function writes a pointer to the newly constructed FFIMFCPL structure (or
163  * NULL if the CPL could not be parsed). The client is responsible for freeing
164  * the FFIMFCPL structure using ff_imf_cpl_free().
165  * @return A non-zero value in case of an error.
166  */
167 int ff_imf_parse_cpl(AVIOContext *in, FFIMFCPL **cpl);
168 
169 /**
170  * Allocates and initializes an FFIMFCPL data structure.
171  * @return A pointer to the newly constructed FFIMFCPL structure (or NULL if the
172  * structure could not be constructed). The client is responsible for freeing
173  * the FFIMFCPL structure using ff_imf_cpl_free().
174  */
176 
177 /**
178  * Deletes an FFIMFCPL data structure previously instantiated with ff_imf_cpl_alloc().
179  * @param[in] cpl The FFIMFCPL structure to delete.
180  */
181 void ff_imf_cpl_free(FFIMFCPL *cpl);
182 
183 /**
184  * Reads an unsigned 32-bit integer from an XML element
185  * @return 0 on success, < 0 AVERROR code on error.
186  */
187 int ff_imf_xml_read_uint32(xmlNodePtr element, uint32_t *number);
188 
189 /**
190  * Reads an AVRational from an XML element
191  * @return 0 on success, < 0 AVERROR code on error.
192  */
193 int ff_imf_xml_read_rational(xmlNodePtr element, AVRational *rational);
194 
195 /**
196  * Reads a UUID from an XML element
197  * @return 0 on success, < 0 AVERROR code on error.
198  */
199 int ff_imf_xml_read_uuid(xmlNodePtr element, uint8_t uuid[16]);
200 
201 /**
202  * Returns the first child element with the specified local name
203  * @return A pointer to the child element, or NULL if no such child element exists.
204  */
205 xmlNodePtr ff_imf_xml_get_child_element_by_name(xmlNodePtr parent, const char *name_utf8);
206 
207 #endif
ff_imf_parse_cpl_from_xml_dom
int ff_imf_parse_cpl_from_xml_dom(xmlDocPtr doc, FFIMFCPL **cpl)
Parse an IMF CompositionPlaylist element into the FFIMFCPL data structure.
Definition: imf_cpl.c:679
FFIMFTrackFileVirtualTrack::resources
FFIMFTrackFileResource * resources
Resource elements of the Virtual Track.
Definition: imf.h:121
FFIMFCPL::id_uuid
FFIMFUUID id_uuid
CompositionPlaylist/Id element.
Definition: imf.h:138
FFIMFMarkerVirtualTrack::resources
FFIMFMarkerResource * resources
Resource elements of the Virtual Track.
Definition: imf.h:131
rational.h
FFIMFTrackFileVirtualTrack::resource_count
uint32_t resource_count
Number of Resource elements present in the Virtual Track.
Definition: imf.h:120
ff_imf_xml_read_uint32
int ff_imf_xml_read_uint32(xmlNodePtr element, uint32_t *number)
Reads an unsigned 32-bit integer from an XML element.
Definition: imf_cpl.c:122
FFIMFMarkerVirtualTrack
IMF Composition Playlist Virtual Track that consists of Marker Resources.
Definition: imf.h:128
FFIMFCPL::content_title_utf8
xmlChar * content_title_utf8
CompositionPlaylist/ContentTitle element.
Definition: imf.h:139
FFIMFCPL::main_audio_tracks
FFIMFTrackFileVirtualTrack * main_audio_tracks
Main Audio Virtual Tracks.
Definition: imf.h:144
FFIMFMarkerResource::base
FFIMFBaseResource base
Definition: imf.h:103
ff_imf_cpl_free
void ff_imf_cpl_free(FFIMFCPL *cpl)
Deletes an FFIMFCPL data structure previously instantiated with ff_imf_cpl_alloc().
Definition: imf_cpl.c:769
FFIMFBaseResource::duration
uint32_t duration
BaseResourceType/Duration.
Definition: imf.h:78
FFIMFMarker
IMF Marker.
Definition: imf.h:93
ff_imf_xml_get_child_element_by_name
xmlNodePtr ff_imf_xml_get_child_element_by_name(xmlNodePtr parent, const char *name_utf8)
Returns the first child element with the specified local name.
Definition: imf_cpl.c:59
FFIMFCPL::main_markers_track
FFIMFMarkerVirtualTrack * main_markers_track
Main Marker Virtual Track.
Definition: imf.h:141
FFIMFBaseVirtualTrack::id_uuid
FFIMFUUID id_uuid
TrackId associated with the Virtual Track.
Definition: imf.h:112
FFIMFTrackFileVirtualTrack
IMF Composition Playlist Virtual Track that consists of Track File Resources.
Definition: imf.h:118
ff_imf_xml_read_uuid
int ff_imf_xml_read_uuid(xmlNodePtr element, uint8_t uuid[16])
Reads a UUID from an XML element.
Definition: imf_cpl.c:73
FFIMFCPL::edit_rate
AVRational edit_rate
CompositionPlaylist/EditRate element.
Definition: imf.h:140
FFIMFTrackFileVirtualTrack::resources_alloc_sz
unsigned int resources_alloc_sz
Size of the resources buffer.
Definition: imf.h:122
FFIMFBaseVirtualTrack
IMF Composition Playlist Virtual Track.
Definition: imf.h:111
FFIMFBaseResource
IMF Composition Playlist Base Resource.
Definition: imf.h:75
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
FFIMFMarkerVirtualTrack::base
FFIMFBaseVirtualTrack base
Definition: imf.h:129
FFIMFTrackFileVirtualTrack::base
FFIMFBaseVirtualTrack base
Definition: imf.h:119
FFIMFBaseResource::edit_rate
AVRational edit_rate
BaseResourceType/EditRate.
Definition: imf.h:76
AVIOContext
Bytestream IO Context.
Definition: avio.h:162
avio.h
FFIMFBaseResource::repeat_count
uint32_t repeat_count
BaseResourceType/RepeatCount.
Definition: imf.h:79
ff_imf_parse_cpl
int ff_imf_parse_cpl(AVIOContext *in, FFIMFCPL **cpl)
Parse an IMF Composition Playlist document into the FFIMFCPL data structure.
Definition: imf_cpl.c:795
FFIMFBaseResource::entry_point
uint32_t entry_point
BaseResourceType/EntryPoint.
Definition: imf.h:77
ff_imf_cpl_alloc
FFIMFCPL * ff_imf_cpl_alloc(void)
Allocates and initializes an FFIMFCPL data structure.
Definition: imf_cpl.c:758
FFIMFUUID
uint8_t FFIMFUUID[16]
UUID as defined in IETF RFC 422.
Definition: imf.h:70
FFIMFTrackFileResource::track_file_uuid
FFIMFUUID track_file_uuid
TrackFileResourceType/TrackFileId.
Definition: imf.h:87
FFIMFMarkerResource
IMF Composition Playlist Marker Resource.
Definition: imf.h:102
FFIMFMarkerResource::markers
FFIMFMarker * markers
Marker elements.
Definition: imf.h:105
avformat.h
FFIMFTrackFileResource
IMF Composition Playlist Track File Resource.
Definition: imf.h:85
FFIMFMarker::offset
uint32_t offset
Marker/Offset.
Definition: imf.h:96
FFIMFCPL::main_audio_track_count
uint32_t main_audio_track_count
Number of Main Audio Virtual Tracks.
Definition: imf.h:143
FFIMFMarkerVirtualTrack::resource_count
uint32_t resource_count
Number of Resource elements present in the Virtual Track.
Definition: imf.h:130
FFIMFCPL::main_image_2d_track
FFIMFTrackFileVirtualTrack * main_image_2d_track
Main Image Virtual Track.
Definition: imf.h:142
FFIMFMarkerResource::marker_count
uint32_t marker_count
Number of Marker elements.
Definition: imf.h:104
FFIMFCPL
IMF Composition Playlist.
Definition: imf.h:137
FFIMFMarker::label_utf8
xmlChar * label_utf8
Marker/Label.
Definition: imf.h:94
ff_imf_xml_read_rational
int ff_imf_xml_read_rational(xmlNodePtr element, AVRational *rational)
Reads an AVRational from an XML element.
Definition: imf_cpl.c:107
FFIMFMarker::scope_utf8
xmlChar * scope_utf8
Marker/Label/@scope.
Definition: imf.h:95
FFIMFTrackFileResource::base
FFIMFBaseResource base
Definition: imf.h:86