diff options
Diffstat (limited to 'media/libnestegg/include/nestegg.h')
| -rw-r--r-- | media/libnestegg/include/nestegg.h | 467 |
1 files changed, 467 insertions, 0 deletions
diff --git a/media/libnestegg/include/nestegg.h b/media/libnestegg/include/nestegg.h new file mode 100644 index 000000000..d91483b93 --- /dev/null +++ b/media/libnestegg/include/nestegg.h @@ -0,0 +1,467 @@ +/* + * Copyright © 2010 Mozilla Foundation + * + * This program is made available under an ISC-style license. See the + * accompanying file LICENSE for details. + */ +#if !defined(NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79) +#define NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 + +#include <limits.h> +#include <stdint.h> + +#if defined(__cplusplus) +extern "C" { +#endif + +/** @mainpage + + @section intro Introduction + + This is the documentation for the <tt>libnestegg</tt> C API. + <tt>libnestegg</tt> is a demultiplexing library for <a + href="http://www.webmproject.org/code/specs/container/">WebM</a> + media files. + + @section example Example code + + @code + nestegg * demux_ctx; + nestegg_init(&demux_ctx, io, NULL); + + nestegg_packet * pkt; + while ((r = nestegg_read_packet(demux_ctx, &pkt)) > 0) { + unsigned int track; + + nestegg_packet_track(pkt, &track); + + // This example decodes the first track only. + if (track == 0) { + unsigned int chunk, chunks; + + nestegg_packet_count(pkt, &chunks); + + // Decode each chunk of data. + for (chunk = 0; chunk < chunks; ++chunk) { + unsigned char * data; + size_t data_size; + + nestegg_packet_data(pkt, chunk, &data, &data_size); + + example_codec_decode(codec_ctx, data, data_size); + } + } + + nestegg_free_packet(pkt); + } + + nestegg_destroy(demux_ctx); + @endcode +*/ + + +/** @file + The <tt>libnestegg</tt> C API. */ + +#define NESTEGG_TRACK_VIDEO 0 /**< Track is of type video. */ +#define NESTEGG_TRACK_AUDIO 1 /**< Track is of type audio. */ +#define NESTEGG_TRACK_UNKNOWN INT_MAX /**< Track is of type unknown. */ + +#define NESTEGG_CODEC_VP8 0 /**< Track uses Google On2 VP8 codec. */ +#define NESTEGG_CODEC_VORBIS 1 /**< Track uses Xiph Vorbis codec. */ +#define NESTEGG_CODEC_VP9 2 /**< Track uses Google On2 VP9 codec. */ +#define NESTEGG_CODEC_OPUS 3 /**< Track uses Xiph Opus codec. */ +#define NESTEGG_CODEC_UNKNOWN INT_MAX /**< Track uses unknown codec. */ + +#define NESTEGG_VIDEO_MONO 0 /**< Track is mono video. */ +#define NESTEGG_VIDEO_STEREO_LEFT_RIGHT 1 /**< Track is side-by-side stereo video. Left first. */ +#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP 2 /**< Track is top-bottom stereo video. Right first. */ +#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM 3 /**< Track is top-bottom stereo video. Left first. */ +#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT 11 /**< Track is side-by-side stereo video. Right first. */ + +#define NESTEGG_SEEK_SET 0 /**< Seek offset relative to beginning of stream. */ +#define NESTEGG_SEEK_CUR 1 /**< Seek offset relative to current position in stream. */ +#define NESTEGG_SEEK_END 2 /**< Seek offset relative to end of stream. */ + +#define NESTEGG_LOG_DEBUG 1 /**< Debug level log message. */ +#define NESTEGG_LOG_INFO 10 /**< Informational level log message. */ +#define NESTEGG_LOG_WARNING 100 /**< Warning level log message. */ +#define NESTEGG_LOG_ERROR 1000 /**< Error level log message. */ +#define NESTEGG_LOG_CRITICAL 10000 /**< Critical level log message. */ + +#define NESTEGG_ENCODING_COMPRESSION 0 /**< Content encoding type is compression. */ +#define NESTEGG_ENCODING_ENCRYPTION 1 /**< Content encoding type is encryption. */ + +#define NESTEGG_PACKET_HAS_SIGNAL_BYTE_FALSE 0 /**< Packet does not have signal byte */ +#define NESTEGG_PACKET_HAS_SIGNAL_BYTE_UNENCRYPTED 1 /**< Packet has signal byte and is unencrypted */ +#define NESTEGG_PACKET_HAS_SIGNAL_BYTE_ENCRYPTED 2 /**< Packet has signal byte and is encrypted */ + +#define NESTEGG_PACKET_HAS_KEYFRAME_FALSE 0 /**< Packet contains only keyframes. */ +#define NESTEGG_PACKET_HAS_KEYFRAME_TRUE 1 /**< Packet does not contain any keyframes */ +#define NESTEGG_PACKET_HAS_KEYFRAME_UNKNOWN 2 /**< Packet may or may not contain keyframes */ + +typedef struct nestegg nestegg; /**< Opaque handle referencing the stream state. */ +typedef struct nestegg_packet nestegg_packet; /**< Opaque handle referencing a packet of data. */ + +/** User supplied IO context. */ +typedef struct { + /** User supplied read callback. + @param buffer Buffer to read data into. + @param length Length of supplied buffer in bytes. + @param userdata The #userdata supplied by the user. + @retval 1 Read succeeded. + @retval 0 End of stream. + @retval -1 Error. */ + int (* read)(void * buffer, size_t length, void * userdata); + + /** User supplied seek callback. + @param offset Offset within the stream to seek to. + @param whence Seek direction. One of #NESTEGG_SEEK_SET, + #NESTEGG_SEEK_CUR, or #NESTEGG_SEEK_END. + @param userdata The #userdata supplied by the user. + @retval 0 Seek succeeded. + @retval -1 Error. */ + int (* seek)(int64_t offset, int whence, void * userdata); + + /** User supplied tell callback. + @param userdata The #userdata supplied by the user. + @returns Current position within the stream. + @retval -1 Error. */ + int64_t (* tell)(void * userdata); + + /** User supplied pointer to be passed to the IO callbacks. */ + void * userdata; +} nestegg_io; + +/** Parameters specific to a video track. */ +typedef struct { + unsigned int stereo_mode; /**< Video mode. One of #NESTEGG_VIDEO_MONO, + #NESTEGG_VIDEO_STEREO_LEFT_RIGHT, + #NESTEGG_VIDEO_STEREO_BOTTOM_TOP, or + #NESTEGG_VIDEO_STEREO_TOP_BOTTOM. */ + unsigned int width; /**< Width of the video frame in pixels. */ + unsigned int height; /**< Height of the video frame in pixels. */ + unsigned int display_width; /**< Display width of the video frame in pixels. */ + unsigned int display_height; /**< Display height of the video frame in pixels. */ + unsigned int crop_bottom; /**< Pixels to crop from the bottom of the frame. */ + unsigned int crop_top; /**< Pixels to crop from the top of the frame. */ + unsigned int crop_left; /**< Pixels to crop from the left of the frame. */ + unsigned int crop_right; /**< Pixels to crop from the right of the frame. */ + unsigned int alpha_mode; /**< 1 if an additional opacity stream is available, otherwise 0. */ +} nestegg_video_params; + +/** Parameters specific to an audio track. */ +typedef struct { + double rate; /**< Sampling rate in Hz. */ + unsigned int channels; /**< Number of audio channels. */ + unsigned int depth; /**< Bits per sample. */ + uint64_t codec_delay; /**< Nanoseconds that must be discarded from the start. */ + uint64_t seek_preroll;/**< Nanoseconds that must be discarded after a seek. */ +} nestegg_audio_params; + +/** Logging callback function pointer. */ +typedef void (* nestegg_log)(nestegg * context, unsigned int severity, char const * format, ...); + +/** Initialize a nestegg context. During initialization the parser will + read forward in the stream processing all elements until the first + block of media is reached. All track metadata has been processed at this point. + @param context Storage for the new nestegg context. @see nestegg_destroy + @param io User supplied IO context. + @param callback Optional logging callback function pointer. May be NULL. + @param max_offset Optional maximum offset to be read. Set -1 to ignore. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_init(nestegg ** context, nestegg_io io, nestegg_log callback, int64_t max_offset); + +/** Destroy a nestegg context and free associated memory. + @param context #nestegg context to be freed. @see nestegg_init */ +void nestegg_destroy(nestegg * context); + +/** Query the duration of the media stream in nanoseconds. + @param context Stream context initialized by #nestegg_init. + @param duration Storage for the queried duration. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_duration(nestegg * context, uint64_t * duration); + +/** Query the tstamp scale of the media stream in nanoseconds. + @note Timecodes presented by nestegg have been scaled by this value + before presentation to the caller. + @param context Stream context initialized by #nestegg_init. + @param scale Storage for the queried scale factor. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_tstamp_scale(nestegg * context, uint64_t * scale); + +/** Query the number of tracks in the media stream. + @param context Stream context initialized by #nestegg_init. + @param tracks Storage for the queried track count. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_count(nestegg * context, unsigned int * tracks); + +/** Query the start and end offset for a particular cluster. + @param context Stream context initialized by #nestegg_init. + @param cluster_num Zero-based cluster number; order they appear in cues. + @param max_offset Optional maximum offset to be read. Set -1 to ignore. + @param start_pos Starting offset of the cluster. -1 means non-existant. + @param end_pos Starting offset of the cluster. -1 means non-existant or + final cluster. + @param tstamp Starting timestamp of the cluster. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_get_cue_point(nestegg * context, unsigned int cluster_num, + int64_t max_offset, int64_t * start_pos, + int64_t * end_pos, uint64_t * tstamp); + +/** Seek to @a offset. Stream will seek directly to offset. + Must be used to seek to the start of a cluster; the parser will not be + able to understand other offsets. + @param context Stream context initialized by #nestegg_init. + @param offset Absolute offset in bytes. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_offset_seek(nestegg * context, uint64_t offset); + +/** Seek @a track to @a tstamp. Stream seek will terminate at the earliest + key point in the stream at or before @a tstamp. Other tracks in the + stream will output packets with unspecified but nearby timestamps. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param tstamp Absolute timestamp in nanoseconds. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_seek(nestegg * context, unsigned int track, uint64_t tstamp); + +/** Query the type specified by @a track. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @retval #NESTEGG_TRACK_VIDEO Track type is video. + @retval #NESTEGG_TRACK_AUDIO Track type is audio. + @retval #NESTEGG_TRACK_UNKNOWN Track type is unknown. + @retval -1 Error. */ +int nestegg_track_type(nestegg * context, unsigned int track); + +/** Query the codec ID specified by @a track. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @retval #NESTEGG_CODEC_VP8 Track codec is VP8. + @retval #NESTEGG_CODEC_VP9 Track codec is VP9. + @retval #NESTEGG_CODEC_VORBIS Track codec is Vorbis. + @retval #NESTEGG_CODEC_OPUS Track codec is Opus. + @retval #NESTEGG_CODEC_UNKNOWN Track codec is unknown. + @retval -1 Error. */ +int nestegg_track_codec_id(nestegg * context, unsigned int track); + +/** Query the number of codec initialization chunks for @a track. Each + chunk of data should be passed to the codec initialization functions in + the order returned. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param count Storage for the queried chunk count. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_codec_data_count(nestegg * context, unsigned int track, + unsigned int * count); + +/** Get a pointer to chunk number @a item of codec initialization data for + @a track. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param item Zero based chunk item number. + @param data Storage for the queried data pointer. + The data is owned by the #nestegg context. + @param length Storage for the queried data size. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_codec_data(nestegg * context, unsigned int track, unsigned int item, + unsigned char ** data, size_t * length); + +/** Query the video parameters specified by @a track. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param params Storage for the queried video parameters. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_video_params(nestegg * context, unsigned int track, + nestegg_video_params * params); + +/** Query the audio parameters specified by @a track. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param params Storage for the queried audio parameters. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_audio_params(nestegg * context, unsigned int track, + nestegg_audio_params * params); + +/** Query the encoding status for @a track. If a track has multiple encodings + the first will be returned. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @retval #NESTEGG_ENCODING_COMPRESSION The track is compressed, but not encrypted. + @retval #NESTEGG_ENCODING_ENCRYPTION The track is encrypted and compressed. + @retval -1 Error. */ +int nestegg_track_encoding(nestegg * context, unsigned int track); + +/** Query the ContentEncKeyId for @a track. Will return an error if the track + in not encrypted, or is not recognized. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param content_enc_key_id Storage for queried id. The content encryption key used. + Owned by nestegg and will be freed separately. + @param content_enc_key_id_length Length of the queried ContentEncKeyId in bytes. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_content_enc_key_id(nestegg * context, unsigned int track, + unsigned char const ** content_enc_key_id, + size_t * content_enc_key_id_length); + +/** Query the default frame duration for @a track. For a video track, this + is typically the inverse of the video frame rate. + @param context Stream context initialized by #nestegg_init. + @param track Zero based track number. + @param duration Storage for the default duration in nanoseconds. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_track_default_duration(nestegg * context, unsigned int track, + uint64_t * duration); + +/** Reset parser state to the last valid state before nestegg_read_packet failed. + @param context Stream context initialized by #nestegg_init. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_read_reset(nestegg * context); + +/** Read a packet of media data. A packet consists of one or more chunks of + data associated with a single track. nestegg_read_packet should be + called in a loop while the return value is 1 to drive the stream parser + forward. @see nestegg_free_packet + @param context Context returned by #nestegg_init. + @param packet Storage for the returned nestegg_packet. + @retval 1 Additional packets may be read in subsequent calls. + @retval 0 End of stream. + @retval -1 Error. */ +int nestegg_read_packet(nestegg * context, nestegg_packet ** packet); + +/** Destroy a nestegg_packet and free associated memory. + @param packet #nestegg_packet to be freed. @see nestegg_read_packet */ +void nestegg_free_packet(nestegg_packet * packet); + +/** Query the keyframe status for a given packet. + @param packet Packet initialized by #nestegg_read_packet. + @retval #NESTEGG_PACKET_HAS_KEYFRAME_FALSE Packet contains no keyframes. + @retval #NESTEGG_PACKET_HAS_KEYFRAME_TRUE Packet contains keyframes. + @retval #NESTEGG_PACKET_HAS_KEYFRAME_UNKNOWN Unknown packet keyframe content. + @retval -1 Error. */ +int nestegg_packet_has_keyframe(nestegg_packet * packet); + +/** Query the track number of @a packet. + @param packet Packet initialized by #nestegg_read_packet. + @param track Storage for the queried zero based track index. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_track(nestegg_packet * packet, unsigned int * track); + +/** Query the time stamp in nanoseconds of @a packet. + @param packet Packet initialized by #nestegg_read_packet. + @param tstamp Storage for the queried timestamp in nanoseconds. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_tstamp(nestegg_packet * packet, uint64_t * tstamp); + +/** Query the duration in nanoseconds of @a packet. + @param packet Packet initialized by #nestegg_read_packet. + @param duration Storage for the queried duration in nanoseconds. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_duration(nestegg_packet * packet, uint64_t * duration); + +/** Query the number of data chunks contained in @a packet. + @param packet Packet initialized by #nestegg_read_packet. + @param count Storage for the queried chunk count. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_count(nestegg_packet * packet, unsigned int * count); + +/** Get a pointer to chunk number @a item of packet data. + @param packet Packet initialized by #nestegg_read_packet. + @param item Zero based chunk item number. + @param data Storage for the queried data pointer. + The data is owned by the #nestegg_packet packet. + @param length Storage for the queried data size. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_data(nestegg_packet * packet, unsigned int item, + unsigned char ** data, size_t * length); + +/** Get a pointer to additional data with identifier @a id of additional packet + data. If @a id isn't present in the packet, returns -1. + @param packet Packet initialized by #nestegg_read_packet. + @param id Codec specific identifer. For VP8, use 1 to get a VP8 encoded + frame containing an alpha channel in its Y plane. + @param data Storage for the queried data pointer. + The data is owned by the #nestegg_packet packet. + @param length Storage for the queried data size. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_additional_data(nestegg_packet * packet, unsigned int id, + unsigned char ** data, size_t * length); + +/** Returns discard_padding for given packet + @param packet Packet initialized by #nestegg_read_packet. + @param discard_padding pointer to store discard padding in. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_discard_padding(nestegg_packet * packet, + int64_t * discard_padding); + +/** Query if a packet is encrypted. + @param packet Packet initialized by #nestegg_read_packet. + @retval #NESTEGG_PACKET_HAS_SIGNAL_BYTE_FALSE No signal byte, encryption + information not read from packet. + @retval #NESTEGG_PACKET_HAS_SIGNAL_BYTE_UNENCRYPTED Encrypted bit not + set, encryption information not read from packet. + @retval #NESTEGG_PACKET_HAS_SIGNAL_BYTE_ENCRYPTED Encrypted bit set, + encryption infomation read from packet. + @retval -1 Error.*/ +int nestegg_packet_encryption(nestegg_packet * packet); + +/** Query the IV for an encrypted packet. Expects a packet from an encrypted + track, and will return error if given a packet that has no signal btye. + @param packet Packet initialized by #nestegg_read_packet. + @param iv Storage for queried iv. + @param length Length of returned iv, may be 0. + The data is owned by the #nestegg_packet packet. + @retval 0 Success. + @retval -1 Error. + */ +int nestegg_packet_iv(nestegg_packet * packet, unsigned char const ** iv, + size_t * length); + +/** Returns reference_block given packet + @param packet Packet initialized by #nestegg_read_packet. + @param reference_block pointer to store reference block in. + @retval 0 Success. + @retval -1 Error. */ +int nestegg_packet_reference_block(nestegg_packet * packet, + int64_t * reference_block); + +/** Query the presence of cues. + @param context Stream context initialized by #nestegg_init. + @retval 0 The media has no cues. + @retval 1 The media has cues. */ +int nestegg_has_cues(nestegg * context); + +/** Try to determine if the buffer looks like the beginning of a WebM file. + @param buffer A buffer containing the beginning of a media file. + @param length The size of the buffer. + @retval 0 The file is not a WebM file. + @retval 1 The file is a WebM file. */ +int nestegg_sniff(unsigned char const * buffer, size_t length); + +#if defined(__cplusplus) +} +#endif + +#endif /* NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 */ |