1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27#ifndef VC_CONTAINERS_H
28#define VC_CONTAINERS_H
29
30/** \file containers.h
31 * Public API for container readers and writers
32 */
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38#include "containers/containers_types.h"
39
40/** \defgroup VcContainerApi Container API
41 * API for container readers and writers */
42/* @{ */
43
44/** Status codes returned by the container API */
45typedef enum
46{
47 VC_CONTAINER_SUCCESS = 0, /**< No error */
48 VC_CONTAINER_ERROR_FORMAT_NOT_SUPPORTED, /**< Format of container is not supported */
49 VC_CONTAINER_ERROR_FORMAT_FEATURE_NOT_SUPPORTED, /**< Format of container uses unsupported features */
50 VC_CONTAINER_ERROR_FORMAT_INVALID, /**< Format of container is invalid */
51 VC_CONTAINER_ERROR_CORRUPTED, /**< Container is corrupted */
52 VC_CONTAINER_ERROR_URI_NOT_FOUND, /**< URI could not be found */
53 VC_CONTAINER_ERROR_URI_OPEN_FAILED, /**< URI could not be opened */
54 VC_CONTAINER_ERROR_OUT_OF_MEMORY, /**< Out of memory */
55 VC_CONTAINER_ERROR_OUT_OF_SPACE, /**< Out of disk space (used when writing) */
56 VC_CONTAINER_ERROR_OUT_OF_RESOURCES, /**< Out of resources (other than memory) */
57 VC_CONTAINER_ERROR_EOS, /**< End of stream reached */
58 VC_CONTAINER_ERROR_LIMIT_REACHED, /**< User defined limit reached (used when writing) */
59 VC_CONTAINER_ERROR_BUFFER_TOO_SMALL, /**< Given buffer is too small for data to be copied */
60 VC_CONTAINER_ERROR_INCOMPLETE_DATA, /**< Requested data is incomplete */
61 VC_CONTAINER_ERROR_NO_TRACK_AVAILABLE, /**< Container doesn't have any track */
62 VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED, /**< Format of the track is not supported */
63 VC_CONTAINER_ERROR_UNSUPPORTED_OPERATION, /**< The requested operation is not supported */
64 VC_CONTAINER_ERROR_INVALID_ARGUMENT, /**< The argument provided is invalid */
65 VC_CONTAINER_ERROR_CONTINUE, /**< The requested operation was interrupted and needs to be tried again */
66 VC_CONTAINER_ERROR_ABORTED, /**< The requested operation was aborted */
67 VC_CONTAINER_ERROR_NOT_FOUND, /**< The requested data was not found */
68 VC_CONTAINER_ERROR_DRM_NOT_AUTHORIZED, /**< The DRM was not authorized */
69 VC_CONTAINER_ERROR_DRM_EXPIRED, /**< The DRM has expired */
70 VC_CONTAINER_ERROR_DRM_FAILED, /**< Generic DRM error */
71 VC_CONTAINER_ERROR_FAILED, /**< Generic error */
72 VC_CONTAINER_ERROR_NOT_READY /**< The container was not yet able to carry out the operation. */
73} VC_CONTAINER_STATUS_T;
74
75/** Four Character Code type used to identify codecs, etc. */
76typedef uint32_t VC_CONTAINER_FOURCC_T;
77
78/** Type definition for language codes.
79 * Language are defined as ISO639 Alpha-3 codes (http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) */
80typedef uint8_t VC_CONTAINER_LANGUAGE_T[3];
81
82/** Enumeration of the character encodings supported. */
83typedef enum {
84 VC_CONTAINER_CHAR_ENCODING_UNKNOWN = 0, /**< Encoding is unknown */
85 VC_CONTAINER_CHAR_ENCODING_UTF8 /**< UTF8 encoding */
86} VC_CONTAINER_CHAR_ENCODING_T;
87
88/** \name Container Capabilities
89 * The following flags are exported by containers to describe their capabilities */
90/* @{ */
91/** Type definition for container capabilities */
92typedef uint32_t VC_CONTAINER_CAPABILITIES_T;
93/** The container can seek */
94#define VC_CONTAINER_CAPS_CAN_SEEK 0x1
95/** Seeking is fast. The absence of this flag can be used as a hint to avoid seeking as much as possible */
96#define VC_CONTAINER_CAPS_SEEK_IS_FAST 0x2
97/** The container controls the pace at which it is reading the data */
98#define VC_CONTAINER_CAPS_CAN_CONTROL_PACE 0x4
99/** The container provides an index. This basically means that seeking will be precise and fast */
100#define VC_CONTAINER_CAPS_HAS_INDEX 0x8
101/** The container provides keyframe information */
102#define VC_CONTAINER_CAPS_DATA_HAS_KEYFRAME_FLAG 0x10
103/** The container supports adding tracks after TRACK_ADD_DONE control message has been sent */
104#define VC_CONTAINER_CAPS_DYNAMIC_TRACK_ADD 0x20
105/** The container supports forcing reading of a given track */
106#define VC_CONTAINER_CAPS_FORCE_TRACK 0x40
107/* @} */
108
109/** \defgroup VcContainerMetadata Container Metadata
110 * Container metadata contains descriptive information which is associated with the multimedia data */
111/* @{ */
112
113/** Enumeration of the different metadata keys available. */
114typedef enum {
115 /* Metadata of global scope */
116 VC_CONTAINER_METADATA_KEY_TITLE = VC_FOURCC('t','i','t','l'),
117 VC_CONTAINER_METADATA_KEY_ARTIST = VC_FOURCC('a','r','t','i'),
118 VC_CONTAINER_METADATA_KEY_ALBUM = VC_FOURCC('a','l','b','m'),
119 VC_CONTAINER_METADATA_KEY_DESCRIPTION = VC_FOURCC('d','e','s','c'),
120 VC_CONTAINER_METADATA_KEY_YEAR = VC_FOURCC('y','e','a','r'),
121 VC_CONTAINER_METADATA_KEY_GENRE = VC_FOURCC('g','e','n','r'),
122 VC_CONTAINER_METADATA_KEY_TRACK = VC_FOURCC('t','r','a','k'),
123 VC_CONTAINER_METADATA_KEY_LYRICS = VC_FOURCC('l','y','r','x'),
124
125 VC_CONTAINER_METADATA_KEY_UNKNOWN = 0
126
127} VC_CONTAINER_METADATA_KEY_T;
128
129/** Definition of the metadata type.
130 * This type is used to store one element of metadata */
131typedef struct VC_CONTAINER_METADATA_T
132{
133 /** Identifier for the type of metadata the value refers to.
134 * Using an enum for the id will mean that a list of possible values will have to be
135 * defined and maintained. This might limit extensibility and customisation.\n
136 * Maybe it would be better to use a FOURCC or even a string here. */
137 VC_CONTAINER_METADATA_KEY_T key;
138
139 VC_CONTAINER_LANGUAGE_T language; /**< Language code for the metadata */
140 VC_CONTAINER_CHAR_ENCODING_T encoding; /**< Encoding of the metadata */
141
142 /** Metadata value. This value is defined as null-terminated UTF-8 string.\n
143 * Do we want to support other types than strings (e.g. integer) ?\n
144 * We need an encoding conversion library! */
145 char *value;
146
147 /** Size of the memory area reserved for metadata value (including any
148 * terminating characters). */
149 unsigned int size;
150} VC_CONTAINER_METADATA_T;
151/* @} */
152
153/** \defgroup VcContainerESFormat Container Elementary Stream Format
154 * This describes the format of an elementary stream associated with a track */
155/* @{ */
156
157/** Enumeration of the different types of elementary streams.
158 * This divides elementary streams into 4 big categories. */
159typedef enum
160{
161 VC_CONTAINER_ES_TYPE_UNKNOWN, /**< Unknown elementary stream type */
162 VC_CONTAINER_ES_TYPE_AUDIO, /**< Audio elementary stream */
163 VC_CONTAINER_ES_TYPE_VIDEO, /**< Video elementary stream */
164 VC_CONTAINER_ES_TYPE_SUBPICTURE /**< Sub-picture elementary stream (e.g. subtitles, overlays) */
165
166} VC_CONTAINER_ES_TYPE_T;
167
168/** Definition of a video format.
169 * This describes the properties specific to a video stream */
170typedef struct VC_CONTAINER_VIDEO_FORMAT_T
171{
172 uint32_t width; /**< Width of the frame */
173 uint32_t height; /**< Height of the frame */
174 uint32_t visible_width; /**< Width of the visible area of the frame */
175 uint32_t visible_height; /**< Height of the visible area of the frame */
176 uint32_t x_offset; /**< Offset to the start of the visible width */
177 uint32_t y_offset; /**< Offset to the start of the visible height */
178 uint32_t frame_rate_num; /**< Frame rate numerator */
179 uint32_t frame_rate_den; /**< Frame rate denominator */
180 uint32_t par_num; /**< Pixel aspect ratio numerator */
181 uint32_t par_den; /**< Pixel aspect ratio denominator */
182} VC_CONTAINER_VIDEO_FORMAT_T;
183
184/** Enumeration for the different channel locations */
185typedef enum
186{
187 VC_CONTAINER_AUDIO_CHANNEL_LEFT = 0, /**< Left channel */
188 VC_CONTAINER_AUDIO_CHANNEL_RIGHT, /**< Right channel */
189 VC_CONTAINER_AUDIO_CHANNEL_CENTER, /**< Center channel */
190 VC_CONTAINER_AUDIO_CHANNEL_LOW_FREQUENCY, /**< Low frequency channel */
191 VC_CONTAINER_AUDIO_CHANNEL_BACK_LEFT, /**< Back left channel */
192 VC_CONTAINER_AUDIO_CHANNEL_BACK_RIGHT, /**< Back right channel */
193 VC_CONTAINER_AUDIO_CHANNEL_BACK_CENTER, /**< Back center channel */
194 VC_CONTAINER_AUDIO_CHANNEL_SIDE_LEFT, /**< Side left channel */
195 VC_CONTAINER_AUDIO_CHANNEL_SIDE_RIGHT, /**< Side right channel */
196
197 VC_CONTAINER_AUDIO_CHANNELS_MAX = 32 /**< Maximum number of channels supported */
198
199} VC_CONTAINER_AUDIO_CHANNEL_T;
200
201/** \name Audio format flags
202 * \anchor audioformatflags
203 * The following flags describe properties of an audio stream */
204/* @{ */
205#define VC_CONTAINER_AUDIO_FORMAT_FLAG_CHANNEL_MAPPING 0x1 /**< Channel mapping available */
206/* @} */
207
208/** Definition of an audio format.
209 * This describes the properties specific to an audio stream */
210typedef struct VC_CONTAINER_AUDIO_FORMAT_T
211{
212 uint32_t channels; /**< Number of audio channels */
213 uint32_t sample_rate; /**< Sample rate */
214
215 uint32_t bits_per_sample; /**< Bits per sample */
216 uint32_t block_align; /**< Size of a block of data */
217
218 uint32_t flags; /**< Flags describing the audio format.
219 * See \ref audioformatflags "Audio format flags". */
220
221 /** Mapping of the channels in order of appearance */
222 VC_CONTAINER_AUDIO_CHANNEL_T channel_mapping[VC_CONTAINER_AUDIO_CHANNELS_MAX];
223
224 uint16_t gap_delay; /**< Delay introduced by the encoder. Used for gapless playback */
225 uint16_t gap_padding; /**< Padding introduced by the encoder. Used for gapless playback */
226
227 /** Replay gain information. First element is the track information and the second
228 * is the album information. */
229 struct {
230 float peak; /**< Peak value (full range is 1.0) */
231 float gain; /**< Gain value in dB */
232 } replay_gain[2];
233
234} VC_CONTAINER_AUDIO_FORMAT_T;
235
236/** Definition of a subpicture format.
237 * This describes the properties specific to a subpicture stream */
238typedef struct VC_CONTAINER_SUBPICTURE_FORMAT_T
239{
240 VC_CONTAINER_CHAR_ENCODING_T encoding; /**< Encoding for text based subpicture formats */
241 uint32_t x_offset; /**< Width offset to the start of the subpicture */
242 uint32_t y_offset; /**< Height offset to the start of the subpicture */
243} VC_CONTAINER_SUBPICTURE_FORMAT_T;
244
245/** \name Elementary stream format flags
246 * \anchor esformatflags
247 * The following flags describe properties of an elementary stream */
248/* @{ */
249#define VC_CONTAINER_ES_FORMAT_FLAG_FRAMED 0x1 /**< Elementary stream is framed */
250/* @} */
251
252/** Definition of the type specific format.
253 * This describes the type specific information of the elementary stream. */
254typedef union
255{
256 VC_CONTAINER_AUDIO_FORMAT_T audio; /**< Audio specific information */
257 VC_CONTAINER_VIDEO_FORMAT_T video; /**< Video specific information */
258 VC_CONTAINER_SUBPICTURE_FORMAT_T subpicture; /**< Subpicture specific information */
259} VC_CONTAINER_ES_SPECIFIC_FORMAT_T;
260
261/** Definition of an elementary stream format */
262typedef struct VC_CONTAINER_ES_FORMAT_T
263{
264 VC_CONTAINER_ES_TYPE_T es_type; /**< Type of the elementary stream */
265 VC_CONTAINER_FOURCC_T codec; /**< Coding of the elementary stream */
266 VC_CONTAINER_FOURCC_T codec_variant; /**< If set, indicates a variant of the coding */
267
268 VC_CONTAINER_ES_SPECIFIC_FORMAT_T *type; /**< Type specific information for the elementary stream */
269
270 uint32_t bitrate; /**< Bitrate */
271
272 VC_CONTAINER_LANGUAGE_T language; /**< Language code for the elementary stream */
273 uint32_t group_id; /**< ID of the group this elementary stream belongs to */
274
275 uint32_t flags; /**< Flags describing the properties of an elementary stream.
276 * See \ref esformatflags "Elementary stream format flags". */
277
278 unsigned int extradata_size; /**< Size of the codec specific data */
279 uint8_t *extradata; /**< Codec specific data */
280
281} VC_CONTAINER_ES_FORMAT_T;
282/* @} */
283
284/** \defgroup VcContainerPacket Container Packet
285 * A container packet is the unit of data that is being read from or written to a container */
286/* @{ */
287
288/** Structure describing a data packet */
289typedef struct VC_CONTAINER_PACKET_T
290{
291 struct VC_CONTAINER_PACKET_T *next; /**< Used to build lists of packets */
292 uint8_t *data; /**< Pointer to the buffer containing the actual data for the packet */
293 unsigned int buffer_size; /**< Size of the p_data buffer. This is used to indicate how much data can be read in p_data */
294 unsigned int size; /**< Size of the data contained in p_data */
295 unsigned int frame_size; /**< If set, indicates the size of the frame this packet belongs to */
296 int64_t pts; /**< Presentation Timestamp of the packet */
297 int64_t dts; /**< Decoding Timestamp of the packet */
298 uint64_t num; /**< Number of this packet */
299 uint32_t track; /**< Track associated with this packet */
300 uint32_t flags; /**< Flags associated with this packet */
301
302 void *user_data; /**< Field reserved for use by the client */
303 void *framework_data; /**< Field reserved for use by the framework */
304
305} VC_CONTAINER_PACKET_T;
306
307/** \name Container Packet Flags
308 * The following flags describe properties of the data packet */
309/* @{ */
310#define VC_CONTAINER_PACKET_FLAG_KEYFRAME 0x01 /**< Packet is a keyframe */
311#define VC_CONTAINER_PACKET_FLAG_FRAME_START 0x02 /**< Packet starts a frame */
312#define VC_CONTAINER_PACKET_FLAG_FRAME_END 0x04 /**< Packet ends a frame */
313#define VC_CONTAINER_PACKET_FLAG_FRAME 0x06 /**< Packet contains only complete frames */
314#define VC_CONTAINER_PACKET_FLAG_DISCONTINUITY 0x08 /**< Packet comes after a discontinuity in the stream. Decoders might have to be flushed */
315#define VC_CONTAINER_PACKET_FLAG_ENCRYPTED 0x10 /**< Packet contains DRM encrypted data */
316#define VC_CONTAINER_PACKET_FLAG_CONFIG 0x20 /**< Packet contains stream specific config data */
317/* @} */
318
319/** \name Special Unknown Time Value
320 * This is the special value used to signal that a timestamp is not known */
321/* @{ */
322#define VC_CONTAINER_TIME_UNKNOWN (INT64_C(1)<<63) /**< Special value for signalling that time is not known */
323/* @} */
324
325/* @} */
326
327/** \name Track flags
328 * \anchor trackflags
329 * The following flags describe properties of a track */
330/* @{ */
331#define VC_CONTAINER_TRACK_FLAG_CHANGED 0x1 /**< Track definition has changed */
332/* @} */
333
334/** Definition of the track type */
335typedef struct VC_CONTAINER_TRACK_T
336{
337 struct VC_CONTAINER_TRACK_PRIVATE_T *priv; /**< Private member used by the implementation */
338 uint32_t is_enabled; /**< Flag to specify if the track is enabled */
339 uint32_t flags; /**< Flags describing the properties of a track.
340 * See \ref trackflags "Track flags". */
341
342 VC_CONTAINER_ES_FORMAT_T *format; /**< Format of the elementary stream contained in the track */
343
344 unsigned int meta_num; /**< Number of metadata elements associated with the track */
345 VC_CONTAINER_METADATA_T **meta; /**< Array of metadata elements associated with the track */
346
347} VC_CONTAINER_TRACK_T;
348
349/** Definition of the DRM type */
350typedef struct VC_CONTAINER_DRM_T
351{
352 VC_CONTAINER_FOURCC_T format; /**< Four character code describing the format of the DRM in use */
353 unsigned int views_max; /**< Maximum number of views allowed */
354 unsigned int views_current; /**< Current number of views */
355
356} VC_CONTAINER_DRM_T;
357
358/** Type definition for the progress reporting function. This function will be called regularly
359 * by the container during a call which blocks for too long and will report the progress of the
360 * operation as an estimated total length in microseconds and a percentage done.
361 * Returning anything else than VC_CONTAINER_SUCCESS in this function will abort the current
362 * operation. */
363typedef VC_CONTAINER_STATUS_T (*VC_CONTAINER_PROGRESS_REPORT_FUNC_T)(void *userdata,
364 int64_t length, unsigned int percentage_done);
365
366/** \name Container Events
367 * The following flags are exported by containers to notify the application of events */
368/* @{ */
369/** Type definition for container events */
370typedef uint32_t VC_CONTAINER_EVENTS_T;
371#define VC_CONTAINER_EVENT_TRACKS_CHANGE 1 /**< Track information has changed */
372#define VC_CONTAINER_EVENT_METADATA_CHANGE 2 /**< Metadata has changed */
373/* @} */
374
375/** Definition of the container context */
376typedef struct VC_CONTAINER_T
377{
378 struct VC_CONTAINER_PRIVATE_T *priv; /**< Private member used by the implementation */
379
380 VC_CONTAINER_EVENTS_T events; /**< Events generated by the container */
381 VC_CONTAINER_CAPABILITIES_T capabilities; /**< Capabilities exported by the container */
382
383 VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress; /**< Progress report function pointer */
384 void *progress_userdata; /**< Progress report user data */
385
386 int64_t duration; /**< Duration of the media in microseconds */
387 int64_t position; /**< Current time position into the media */
388 int64_t size; /**< Size of the media in bytes */
389
390 unsigned int tracks_num; /**< Number of tracks available */
391 /** Pointer to an array of pointers to track elements.
392 * The reasoning for using a pointer to pointers here is to allow us to extend
393 * VC_CONTAINER_TRACK_T without losing binary backward compatibility. */
394 VC_CONTAINER_TRACK_T **tracks;
395
396 unsigned int meta_num; /**< Number of metadata elements associated with the container */
397 VC_CONTAINER_METADATA_T **meta; /**< Array of metadata elements associated with the container */
398
399 VC_CONTAINER_DRM_T *drm; /**< Description used for DRM protected content */
400
401} VC_CONTAINER_T;
402
403/** Forward declaration of a container input / output context.
404 * This structure defines the context for a container io instance */
405typedef struct VC_CONTAINER_IO_T VC_CONTAINER_IO_T;
406
407/** Opens the media container pointed to by the URI for reading.
408 * This will create an an instance of a container reader and its associated context.
409 * The context returned will also be filled with the information retrieved from the media.
410 *
411 * If the media isn't accessible or recognized, this will return a null pointer as well as
412 * an error code indicating why this failed.
413 *
414 * \param psz_uri Unified Resource Identifier pointing to the media container
415 * \param status Returns the status of the operation
416 * \param pf_progress User provided function pointer to a progress report function. Can be set to
417 * null if no progress report is wanted. This function will be used during
418 * the whole lifetime of the instance (i.e. it will be used during
419 * open / seek / close)
420 * \param progress_userdata User provided pointer that will be passed during the progress report
421 * function call.
422 * \return A pointer to the context of the new instance of the
423 * container reader. Returns NULL on failure.
424 */
425VC_CONTAINER_T *vc_container_open_reader( const char *psz_uri, VC_CONTAINER_STATUS_T *status,
426 VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
427
428/** Opens for reading the media container pointed to by the container i/o.
429 * This will create an an instance of a container reader and its associated context.
430 * The context returned will also be filled with the information retrieved from the media.
431 *
432 * If the media isn't accessible or recognized, this will return a null pointer as well as
433 * an error code indicating why this failed.
434 *
435 * \param p_io Instance of the container i/o to use
436 * \param psz_uri Unified Resource Identifier pointing to the media container (optional)
437 * \param status Returns the status of the operation
438 * \param pf_progress User provided function pointer to a progress report function. Can be set to
439 * null if no progress report is wanted. This function will be used during
440 * the whole lifetime of the instance (i.e. it will be used during
441 * open / seek / close)
442 * \param progress_userdata User provided pointer that will be passed during the progress report
443 * function call.
444 * \return A pointer to the context of the new instance of the
445 * container reader. Returns NULL on failure.
446 */
447VC_CONTAINER_T *vc_container_open_reader_with_io( VC_CONTAINER_IO_T *p_io,
448 const char *psz_uri, VC_CONTAINER_STATUS_T *status,
449 VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
450
451/** Opens the media container pointed to by the URI for writing.
452 * This will create an an instance of a container writer and its associated context.
453 * The context returned will be initialised to sensible values.
454 *
455 * The application will need to add all the media tracks using \ref vc_container_control before
456 * it starts writing data using \ref vc_container_write.
457 *
458 * If the media isn't accessible or recognized, this will return a null pointer as well as
459 * an error code indicating why this failed.
460 *
461 * \param psz_uri Unified Resource Identifier pointing to the media container
462 * \param status Returns the status of the operation
463 * \param pf_progress User provided function pointer to a progess report function. Can be set to
464 * null if no progress report is wanted.
465 * \param progress_userdata User provided pointer that will be passed during the progress report
466 * function call.
467 * \return A pointer to the context of the new instance of the
468 * container writer. Returns NULL on failure.
469 */
470VC_CONTAINER_T *vc_container_open_writer( const char *psz_uri, VC_CONTAINER_STATUS_T *status,
471 VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
472
473/** Closes an instance of a container reader / writer.
474 * This will free all the resources associated with the context.
475 *
476 * \param context Pointer to the context of the instance to close
477 * \return the status of the operation
478 */
479VC_CONTAINER_STATUS_T vc_container_close( VC_CONTAINER_T *context );
480
481/** \name Container read flags
482 * The following flags can be passed during a read call */
483/* @{ */
484/** Type definition for the read flags */
485typedef uint32_t VC_CONTAINER_READ_FLAGS_T;
486/** Ask the container to only return information on the next packet without reading it */
487#define VC_CONTAINER_READ_FLAG_INFO 1
488/** Ask the container to skip the next packet */
489#define VC_CONTAINER_READ_FLAG_SKIP 2
490/** Force the container to read data from the specified track */
491#define VC_CONTAINER_READ_FLAG_FORCE_TRACK 4
492/* @} */
493
494/** Reads a data packet from a container reader.
495 * By default, the reader will read whatever packet comes next in the container and update the
496 * given \ref VC_CONTAINER_PACKET_T structure with this packet's information.
497 * This behaviour can be changed using the \ref VC_CONTAINER_READ_FLAGS_T.\n
498 * \ref VC_CONTAINER_READ_FLAG_INFO will instruct the reader to only return information on the
499 * following packet but not its actual data. The data can be retreived later by issuing another
500 * read request.\n
501 * \ref VC_CONTAINER_READ_FLAG_FORCE_TRACK will force the reader to read the next packet for the
502 * selected track (as present in the \ref VC_CONTAINER_PACKET_T structure) instead of defaulting
503 * to reading the packet which comes next in the container.\n
504 * \ref VC_CONTAINER_READ_FLAG_SKIP will instruct the reader to skip the next packet. In this case
505 * it isn't necessary for the caller to pass a pointer to a \ref VC_CONTAINER_PACKET_T structure
506 * unless the \ref VC_CONTAINER_READ_FLAG_INFO is also given.\n
507 * A combination of all these flags can be used.
508 *
509 * \param context Pointer to the context of the reader to use
510 * \param packet Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
511 * This needs to be partially filled before the call (buffer, buffer_size)
512 * \param flags Flags controlling the read operation
513 * \return the status of the operation
514 */
515VC_CONTAINER_STATUS_T vc_container_read( VC_CONTAINER_T *context,
516 VC_CONTAINER_PACKET_T *packet, VC_CONTAINER_READ_FLAGS_T flags );
517
518/** Writes a data packet to a container writer.
519 *
520 * \param context Pointer to the context of the writer to use
521 * \param packet Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
522 * \return the status of the operation
523 */
524VC_CONTAINER_STATUS_T vc_container_write( VC_CONTAINER_T *context,
525 VC_CONTAINER_PACKET_T *packet );
526
527/** Definition of the different seek modes */
528typedef enum
529{
530 /** The offset provided for seeking is an absolute time offset in microseconds */
531 VC_CONTAINER_SEEK_MODE_TIME = 0,
532 /** The offset provided for seeking is a percentage (Q32 ?) */
533 VC_CONTAINER_SEEK_MODE_PERCENT
534
535} VC_CONTAINER_SEEK_MODE_T;
536
537/** \name Container Seek Flags
538 * The following flags control seek operations */
539/* @{ */
540/** Type definition for the seek flags */
541typedef uint32_t VC_CONTAINER_SEEK_FLAGS_T;
542/** Choose precise seeking even if slower */
543#define VC_CONTAINER_SEEK_FLAG_PRECISE 0x1
544/** By default a seek will always seek to the keyframe which comes just before the requested
545 * position. This flag allows the caller to force the container to seek to the keyframe which
546 * comes just after the requested position. */
547#define VC_CONTAINER_SEEK_FLAG_FORWARD 0x2
548/* @} */
549
550/** Seek into a container reader.
551 *
552 * \param context Pointer to the context of the reader to use
553 * \param offset Offset to seek to. Used as an input as well as output value.
554 * \param mode Seeking mode requested.
555 * \param flags Flags affecting the seeking operation.
556 * \return the status of the operation
557 */
558VC_CONTAINER_STATUS_T vc_container_seek( VC_CONTAINER_T *context, int64_t *offset,
559 VC_CONTAINER_SEEK_MODE_T mode, VC_CONTAINER_SEEK_FLAGS_T flags);
560
561/** Performance statistics.
562 */
563/** The maximum number of bins a statistics value is held in */
564#define VC_CONTAINER_STATS_BINS 10
565
566/** This type is used to represent multiple values of a statistic.
567 */
568typedef struct VC_CONTAINER_STATS_T
569{
570 /** The number of places to right shift count before using. Resulting values
571 * of zero are rounded to 1. */
572 uint32_t shift;
573
574 /** We store VC_CONTAINER_STATS_BINS+1 records, in sorted order of numpc.
575 * At least one will be invalid and all zero. We combine adjacent records
576 * as necessary. */
577 struct {
578 /** Sum of count. For single value statistics this is the freqency, for paired statistics
579 * this is the number of bytes written. */
580 uint32_t count;
581 /** Number of count. For single value statistics this is the total value, for paired statistics
582 * this is the total length of time. */
583 uint32_t num;
584 /** Number>>shift per count. Stored to save recalculation. */
585 uint32_t numpc;
586 } record[VC_CONTAINER_STATS_BINS+1];
587} VC_CONTAINER_STATS_T;
588
589/** This type represents the statistics saved by the io layer. */
590typedef struct VC_CONTAINER_WRITE_STATS_T
591{
592 /** This logs the number of bytes written in count, and the microseconds taken to write
593 * in num. */
594 VC_CONTAINER_STATS_T write;
595 /** This logs the length of time the write function has to wait for the asynchronous task. */
596 VC_CONTAINER_STATS_T wait;
597 /** This logs the length of time that we wait for a flush command to complete. */
598 VC_CONTAINER_STATS_T flush;
599} VC_CONTAINER_WRITE_STATS_T;
600
601
602/** Control operations which can be done on containers. */
603typedef enum
604{
605 /** Adds a new track to the list of tracks. This should be used by writers to create
606 * their list of tracks.\n
607 * Arguments:\n
608 * arg1= VC_CONTAINER_ES_FORMAT_T *: format of the track to add\n
609 * return= VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
610 VC_CONTAINER_CONTROL_TRACK_ADD = 0,
611
612 /** Specifies that we're done adding new tracks. This is optional but can be used by writers
613 * to trigger the writing of the container header early. If this isn't used, the header will be
614 * written when the first data packet is received.\n
615 * No arguments.\n
616 * return= VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
617 VC_CONTAINER_CONTROL_TRACK_ADD_DONE,
618
619 /** Change the format of a track in the list of tracks. This should be used by writers to modify
620 * the format of a track at run-time.\n
621 * Arguments:\n
622 * arg1= unsigned int: index of track to change\n
623 * arg2= VC_CONTAINER_ES_FORMAT_T *: format of the track to add\n
624 * return= VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
625 VC_CONTAINER_CONTROL_TRACK_CHANGE,
626
627 /** Deletes a track from the list of tracks. This should be used by writers to delete tracks
628 * during run-time. Note that vc_container_close will automatically delete all track so it
629 * isn't necessary to call this before closing a writer.\n
630 * Arguments:\n
631 * arg1= index of the track to delete */
632 VC_CONTAINER_CONTROL_TRACK_DEL,
633
634 /** Activate the playback of DRM protected content.\n
635 * No arguments.\n
636 * return= one of the VC_CONTAINER_ERROR_DRM error codes if content can't be played */
637 VC_CONTAINER_CONTROL_DRM_PLAY,
638
639 /** TBD */
640 VC_CONTAINER_CONTROL_METADATA_ADD,
641 /** TBD */
642 VC_CONTAINER_CONTROL_METADATA_CHANGE,
643 /** TBD */
644 VC_CONTAINER_CONTROL_METADATA_DEL,
645
646 /** TBD */
647 VC_CONTAINER_CONTROL_CHAPTER_ADD,
648 /** TBD */
649 VC_CONTAINER_CONTROL_CHAPTER_DEL,
650
651 /** Set a maximum size for files generated by writers.\n
652 * Arguments:\n
653 * arg1= uint64_t: maximum size */
654 VC_CONTAINER_CONTROL_SET_MAXIMUM_SIZE,
655
656 /** Enables/disabled performance statistic gathering.\n
657 * Arguments:\n
658 * arg1= bool: enable or disable */
659 VC_CONTAINER_CONTROL_SET_IO_PERF_STATS,
660
661 /** Collects performance statistics.\n
662 * Arguments:\n
663 * arg1= VC_CONTAINER_WRITE_STATS_T *: */
664 VC_CONTAINER_CONTROL_GET_IO_PERF_STATS,
665
666 /** HACK.\n
667 * Arguments:\n
668 * arg1= void (*)(void *): callback function
669 * arg1= void *: opaque pointer to pass during the callback */
670 VC_CONTAINER_CONTROL_SET_IO_BUFFER_FULL_CALLBACK,
671
672 /** Set the I/O read buffer size to be used.\n
673 * Arguments:\n
674 * arg1= uint32_t: New buffer size in bytes*/
675 VC_CONTAINER_CONTROL_IO_SET_READ_BUFFER_SIZE,
676
677 /** Set the timeout on I/O read operations, if applicable.\n
678 * Arguments:\n
679 * arg1= uint32_t: New timeout in milliseconds, or VC_CONTAINER_READ_TIMEOUT_BLOCK */
680 VC_CONTAINER_CONTROL_IO_SET_READ_TIMEOUT_MS,
681
682 /** Set the timestamp base.\n
683 * The timestamp passed equates to time zero for the stream.\n
684 * Arguments:\n
685 * arg1= uint32_t: Timestamp base in stream clock units. */
686 VC_CONTAINER_CONTROL_SET_TIMESTAMP_BASE,
687
688 /** Set the next expected sequence number for the stream.\n
689 * Arguments:\n
690 * arg1= uint32_t: Next expected sequence number. */
691 VC_CONTAINER_CONTROL_SET_NEXT_SEQUENCE_NUMBER,
692
693 /** Set the source ID for the container.\n
694 * Arguments:\n
695 * arg1= uint32_t: Source identifier. */
696 VC_CONTAINER_CONTROL_SET_SOURCE_ID,
697
698 /** Arguments:\n
699 * arg1= void *: metadata buffer
700 * arg2= unsigned long: length of metadata in bytes */
701 VC_CONTAINER_CONTROL_GET_DRM_METADATA,
702
703 /** Arguments:\n
704 * arg1= unsigned long: track number
705 * arg2= VC_CONTAINER_FOURCC_T : drm type
706 * arg3= void *: encryption configuration parameters.
707 * arg4= unsigned long: configuration data length */
708 VC_CONTAINER_CONTROL_ENCRYPT_TRACK,
709
710 /** Causes the io to be flushed.\n
711 * Arguments: none */
712 VC_CONTAINER_CONTROL_IO_FLUSH,
713
714 /** Request the container reader to packetize data for the specified track.
715 * Arguments:\n
716 * arg1= unsigned long: track number
717 * arg2= VC_CONTAINER_FOURCC_T: codec variant to output */
718 VC_CONTAINER_CONTROL_TRACK_PACKETIZE,
719
720 /** Private user extensions must be above this number */
721 VC_CONTAINER_CONTROL_USER_EXTENSIONS = 0x1000
722
723} VC_CONTAINER_CONTROL_T;
724
725/** Used with the VC_CONTAINER_CONTROL_IO_SET_READ_TIMEOUT_MS control to indicate the read shall
726 * block until either data is available, or an error occurs.
727 */
728#define VC_CONTAINER_READ_TIMEOUT_BLOCK (uint32_t)(-1)
729
730/** Extensible control function for container readers and writers.
731 * This function takes a variable number of arguments which will depend on the specific operation.
732 *
733 * \param context Pointer to the VC_CONTAINER_T context to use
734 * \param operation The requested operation
735 * \return the status of the operation. Can be \ref VC_CONTAINER_ERROR_UNSUPPORTED_OPERATION
736 * if the operation is not supported or implemented by the container.
737 */
738VC_CONTAINER_STATUS_T vc_container_control( VC_CONTAINER_T *context, VC_CONTAINER_CONTROL_T operation, ... );
739
740/* @} */
741
742#ifdef __cplusplus
743}
744#endif
745
746#endif /* VC_CONTAINERS_H */
747