1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libnestegg/include/nestegg.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,377 @@
1.4 +/*
1.5 + * Copyright © 2010 Mozilla Foundation
1.6 + *
1.7 + * This program is made available under an ISC-style license. See the
1.8 + * accompanying file LICENSE for details.
1.9 + */
1.10 +#if !defined(NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79)
1.11 +#define NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79
1.12 +
1.13 +#include <nestegg/nestegg-stdint.h>
1.14 +
1.15 +#if defined(__cplusplus)
1.16 +extern "C" {
1.17 +#endif
1.18 +
1.19 +/** @mainpage
1.20 +
1.21 + @section intro Introduction
1.22 +
1.23 + This is the documentation for the <tt>libnestegg</tt> C API.
1.24 + <tt>libnestegg</tt> is a demultiplexing library for <a
1.25 + href="http://www.webmproject.org/code/specs/container/">WebM</a>
1.26 + media files.
1.27 +
1.28 + @section example Example code
1.29 +
1.30 + @code
1.31 + nestegg * demux_ctx;
1.32 + nestegg_init(&demux_ctx, io, NULL);
1.33 +
1.34 + nestegg_packet * pkt;
1.35 + while ((r = nestegg_read_packet(demux_ctx, &pkt)) > 0) {
1.36 + unsigned int track;
1.37 +
1.38 + nestegg_packet_track(pkt, &track);
1.39 +
1.40 + // This example decodes the first track only.
1.41 + if (track == 0) {
1.42 + unsigned int chunk, chunks;
1.43 +
1.44 + nestegg_packet_count(pkt, &chunks);
1.45 +
1.46 + // Decode each chunk of data.
1.47 + for (chunk = 0; chunk < chunks; ++chunk) {
1.48 + unsigned char * data;
1.49 + size_t data_size;
1.50 +
1.51 + nestegg_packet_data(pkt, chunk, &data, &data_size);
1.52 +
1.53 + example_codec_decode(codec_ctx, data, data_size);
1.54 + }
1.55 + }
1.56 +
1.57 + nestegg_free_packet(pkt);
1.58 + }
1.59 +
1.60 + nestegg_destroy(demux_ctx);
1.61 + @endcode
1.62 +*/
1.63 +
1.64 +
1.65 +/** @file
1.66 + The <tt>libnestegg</tt> C API. */
1.67 +
1.68 +#define NESTEGG_TRACK_VIDEO 0 /**< Track is of type video. */
1.69 +#define NESTEGG_TRACK_AUDIO 1 /**< Track is of type audio. */
1.70 +
1.71 +#define NESTEGG_CODEC_VP8 0 /**< Track uses Google On2 VP8 codec. */
1.72 +#define NESTEGG_CODEC_VORBIS 1 /**< Track uses Xiph Vorbis codec. */
1.73 +#define NESTEGG_CODEC_VP9 2 /**< Track uses Google On2 VP9 codec. */
1.74 +#define NESTEGG_CODEC_OPUS 3 /**< Track uses Xiph Opus codec. */
1.75 +
1.76 +#define NESTEGG_VIDEO_MONO 0 /**< Track is mono video. */
1.77 +#define NESTEGG_VIDEO_STEREO_LEFT_RIGHT 1 /**< Track is side-by-side stereo video. Left first. */
1.78 +#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP 2 /**< Track is top-bottom stereo video. Right first. */
1.79 +#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM 3 /**< Track is top-bottom stereo video. Left first. */
1.80 +#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT 11 /**< Track is side-by-side stereo video. Right first. */
1.81 +
1.82 +#define NESTEGG_SEEK_SET 0 /**< Seek offset relative to beginning of stream. */
1.83 +#define NESTEGG_SEEK_CUR 1 /**< Seek offset relative to current position in stream. */
1.84 +#define NESTEGG_SEEK_END 2 /**< Seek offset relative to end of stream. */
1.85 +
1.86 +#define NESTEGG_LOG_DEBUG 1 /**< Debug level log message. */
1.87 +#define NESTEGG_LOG_INFO 10 /**< Informational level log message. */
1.88 +#define NESTEGG_LOG_WARNING 100 /**< Warning level log message. */
1.89 +#define NESTEGG_LOG_ERROR 1000 /**< Error level log message. */
1.90 +#define NESTEGG_LOG_CRITICAL 10000 /**< Critical level log message. */
1.91 +
1.92 +typedef struct nestegg nestegg; /**< Opaque handle referencing the stream state. */
1.93 +typedef struct nestegg_packet nestegg_packet; /**< Opaque handle referencing a packet of data. */
1.94 +
1.95 +/** User supplied IO context. */
1.96 +typedef struct {
1.97 + /** User supplied read callback.
1.98 + @param buffer Buffer to read data into.
1.99 + @param length Length of supplied buffer in bytes.
1.100 + @param userdata The #userdata supplied by the user.
1.101 + @retval 1 Read succeeded.
1.102 + @retval 0 End of stream.
1.103 + @retval -1 Error. */
1.104 + int (* read)(void * buffer, size_t length, void * userdata);
1.105 +
1.106 + /** User supplied seek callback.
1.107 + @param offset Offset within the stream to seek to.
1.108 + @param whence Seek direction. One of #NESTEGG_SEEK_SET,
1.109 + #NESTEGG_SEEK_CUR, or #NESTEGG_SEEK_END.
1.110 + @param userdata The #userdata supplied by the user.
1.111 + @retval 0 Seek succeeded.
1.112 + @retval -1 Error. */
1.113 + int (* seek)(int64_t offset, int whence, void * userdata);
1.114 +
1.115 + /** User supplied tell callback.
1.116 + @param userdata The #userdata supplied by the user.
1.117 + @returns Current position within the stream.
1.118 + @retval -1 Error. */
1.119 + int64_t (* tell)(void * userdata);
1.120 +
1.121 + /** User supplied pointer to be passed to the IO callbacks. */
1.122 + void * userdata;
1.123 +} nestegg_io;
1.124 +
1.125 +/** Parameters specific to a video track. */
1.126 +typedef struct {
1.127 + unsigned int stereo_mode; /**< Video mode. One of #NESTEGG_VIDEO_MONO,
1.128 + #NESTEGG_VIDEO_STEREO_LEFT_RIGHT,
1.129 + #NESTEGG_VIDEO_STEREO_BOTTOM_TOP, or
1.130 + #NESTEGG_VIDEO_STEREO_TOP_BOTTOM. */
1.131 + unsigned int width; /**< Width of the video frame in pixels. */
1.132 + unsigned int height; /**< Height of the video frame in pixels. */
1.133 + unsigned int display_width; /**< Display width of the video frame in pixels. */
1.134 + unsigned int display_height; /**< Display height of the video frame in pixels. */
1.135 + unsigned int crop_bottom; /**< Pixels to crop from the bottom of the frame. */
1.136 + unsigned int crop_top; /**< Pixels to crop from the top of the frame. */
1.137 + unsigned int crop_left; /**< Pixels to crop from the left of the frame. */
1.138 + unsigned int crop_right; /**< Pixels to crop from the right of the frame. */
1.139 +} nestegg_video_params;
1.140 +
1.141 +/** Parameters specific to an audio track. */
1.142 +typedef struct {
1.143 + double rate; /**< Sampling rate in Hz. */
1.144 + unsigned int channels; /**< Number of audio channels. */
1.145 + unsigned int depth; /**< Bits per sample. */
1.146 + uint64_t codec_delay; /**< Nanoseconds that must be discarded from the start. */
1.147 + uint64_t seek_preroll;/**< Nanoseconds that must be discarded after a seek. */
1.148 +} nestegg_audio_params;
1.149 +
1.150 +/** Logging callback function pointer. */
1.151 +typedef void (* nestegg_log)(nestegg * context, unsigned int severity, char const * format, ...);
1.152 +
1.153 +/** Initialize a nestegg context. During initialization the parser will
1.154 + read forward in the stream processing all elements until the first
1.155 + block of media is reached. All track metadata has been processed at this point.
1.156 + @param context Storage for the new nestegg context. @see nestegg_destroy
1.157 + @param io User supplied IO context.
1.158 + @param callback Optional logging callback function pointer. May be NULL.
1.159 + @param max_offset Optional maximum offset to be read. Set -1 to ignore.
1.160 + @retval 0 Success.
1.161 + @retval -1 Error. */
1.162 +int nestegg_init(nestegg ** context, nestegg_io io, nestegg_log callback, int64_t max_offset);
1.163 +
1.164 +/** Destroy a nestegg context and free associated memory.
1.165 + @param context #nestegg context to be freed. @see nestegg_init */
1.166 +void nestegg_destroy(nestegg * context);
1.167 +
1.168 +/** Query the duration of the media stream in nanoseconds.
1.169 + @param context Stream context initialized by #nestegg_init.
1.170 + @param duration Storage for the queried duration.
1.171 + @retval 0 Success.
1.172 + @retval -1 Error. */
1.173 +int nestegg_duration(nestegg * context, uint64_t * duration);
1.174 +
1.175 +/** Query the tstamp scale of the media stream in nanoseconds.
1.176 + Timecodes presented by nestegg have been scaled by this value
1.177 + before presentation to the caller.
1.178 + @param context Stream context initialized by #nestegg_init.
1.179 + @param scale Storage for the queried scale factor.
1.180 + @retval 0 Success.
1.181 + @retval -1 Error. */
1.182 +int nestegg_tstamp_scale(nestegg * context, uint64_t * scale);
1.183 +
1.184 +/** Query the number of tracks in the media stream.
1.185 + @param context Stream context initialized by #nestegg_init.
1.186 + @param tracks Storage for the queried track count.
1.187 + @retval 0 Success.
1.188 + @retval -1 Error. */
1.189 +int nestegg_track_count(nestegg * context, unsigned int * tracks);
1.190 +
1.191 +/** Query the start and end offset for a particular cluster.
1.192 + @param context Stream context initialized by #nestegg_init.
1.193 + @param cluster_num Zero-based cluster number; order they appear in cues.
1.194 + @param max_offset Optional maximum offset to be read. Set -1 to ignore.
1.195 + @param start_pos Starting offset of the cluster. -1 means non-existant.
1.196 + @param end_pos Starting offset of the cluster. -1 means non-existant or
1.197 + final cluster.
1.198 + @param tstamp Starting timestamp of the cluster.
1.199 + @retval 0 Success.
1.200 + @retval -1 Error. */
1.201 +int nestegg_get_cue_point(nestegg * context, unsigned int cluster_num,
1.202 + int64_t max_offset, int64_t * start_pos,
1.203 + int64_t * end_pos, uint64_t * tstamp);
1.204 +
1.205 +/** Seek to @a offset. Stream will seek directly to offset.
1.206 + Should be used to seek to the start of a resync point, i.e. cluster; the
1.207 + parser will not be able to understand other offsets.
1.208 + @param context Stream context initialized by #nestegg_init.
1.209 + @param offset Absolute offset in bytes.
1.210 + @retval 0 Success.
1.211 + @retval -1 Error. */
1.212 +int nestegg_offset_seek(nestegg * context, uint64_t offset);
1.213 +
1.214 +/** Seek @a track to @a tstamp. Stream seek will terminate at the earliest
1.215 + key point in the stream at or before @a tstamp. Other tracks in the
1.216 + stream will output packets with unspecified but nearby timestamps.
1.217 + @param context Stream context initialized by #nestegg_init.
1.218 + @param track Zero based track number.
1.219 + @param tstamp Absolute timestamp in nanoseconds.
1.220 + @retval 0 Success.
1.221 + @retval -1 Error. */
1.222 +int nestegg_track_seek(nestegg * context, unsigned int track, uint64_t tstamp);
1.223 +
1.224 +/** Query the type specified by @a track.
1.225 + @param context Stream context initialized by #nestegg_init.
1.226 + @param track Zero based track number.
1.227 + @retval #NESTEGG_TRACK_VIDEO Track type is video.
1.228 + @retval #NESTEGG_TRACK_AUDIO Track type is audio.
1.229 + @retval -1 Error. */
1.230 +int nestegg_track_type(nestegg * context, unsigned int track);
1.231 +
1.232 +/** Query the codec ID specified by @a track.
1.233 + @param context Stream context initialized by #nestegg_init.
1.234 + @param track Zero based track number.
1.235 + @retval #NESTEGG_CODEC_VP8 Track codec is VP8.
1.236 + @retval #NESTEGG_CODEC_VORBIS Track codec is Vorbis.
1.237 + @retval -1 Error. */
1.238 +int nestegg_track_codec_id(nestegg * context, unsigned int track);
1.239 +
1.240 +/** Query the number of codec initialization chunks for @a track. Each
1.241 + chunk of data should be passed to the codec initialization functions in
1.242 + the order returned.
1.243 + @param context Stream context initialized by #nestegg_init.
1.244 + @param track Zero based track number.
1.245 + @param count Storage for the queried chunk count.
1.246 + @retval 0 Success.
1.247 + @retval -1 Error. */
1.248 +int nestegg_track_codec_data_count(nestegg * context, unsigned int track,
1.249 + unsigned int * count);
1.250 +
1.251 +/** Get a pointer to chunk number @a item of codec initialization data for
1.252 + @a track.
1.253 + @param context Stream context initialized by #nestegg_init.
1.254 + @param track Zero based track number.
1.255 + @param item Zero based chunk item number.
1.256 + @param data Storage for the queried data pointer.
1.257 + The data is owned by the #nestegg context.
1.258 + @param length Storage for the queried data size.
1.259 + @retval 0 Success.
1.260 + @retval -1 Error. */
1.261 +int nestegg_track_codec_data(nestegg * context, unsigned int track, unsigned int item,
1.262 + unsigned char ** data, size_t * length);
1.263 +
1.264 +/** Query the video parameters specified by @a track.
1.265 + @param context Stream context initialized by #nestegg_init.
1.266 + @param track Zero based track number.
1.267 + @param params Storage for the queried video parameters.
1.268 + @retval 0 Success.
1.269 + @retval -1 Error. */
1.270 +int nestegg_track_video_params(nestegg * context, unsigned int track,
1.271 + nestegg_video_params * params);
1.272 +
1.273 +/** Query the audio parameters specified by @a track.
1.274 + @param context Stream context initialized by #nestegg_init.
1.275 + @param track Zero based track number.
1.276 + @param params Storage for the queried audio parameters.
1.277 + @retval 0 Success.
1.278 + @retval -1 Error. */
1.279 +int nestegg_track_audio_params(nestegg * context, unsigned int track,
1.280 + nestegg_audio_params * params);
1.281 +
1.282 +/** Query the default frame duration for @a track. For a video track, this
1.283 + is typically the inverse of the video frame rate.
1.284 + @param context Stream context initialized by #nestegg_init.
1.285 + @param track Zero based track number.
1.286 + @param duration Storage for the default duration in nanoseconds.
1.287 + @retval 0 Success.
1.288 + @retval -1 Error. */
1.289 +int nestegg_track_default_duration(nestegg * context, unsigned int track,
1.290 + uint64_t * duration);
1.291 +
1.292 +/** Read a packet of media data. A packet consists of one or more chunks of
1.293 + data associated with a single track. nestegg_read_packet should be
1.294 + called in a loop while the return value is 1 to drive the stream parser
1.295 + forward. @see nestegg_free_packet
1.296 + @param context Context returned by #nestegg_init.
1.297 + @param packet Storage for the returned nestegg_packet.
1.298 + @retval 1 Additional packets may be read in subsequent calls.
1.299 + @retval 0 End of stream.
1.300 + @retval -1 Error. */
1.301 +int nestegg_read_packet(nestegg * context, nestegg_packet ** packet);
1.302 +
1.303 +/** Destroy a nestegg_packet and free associated memory.
1.304 + @param packet #nestegg_packet to be freed. @see nestegg_read_packet */
1.305 +void nestegg_free_packet(nestegg_packet * packet);
1.306 +
1.307 +/** Query the track number of @a packet.
1.308 + @param packet Packet initialized by #nestegg_read_packet.
1.309 + @param track Storage for the queried zero based track index.
1.310 + @retval 0 Success.
1.311 + @retval -1 Error. */
1.312 +int nestegg_packet_track(nestegg_packet * packet, unsigned int * track);
1.313 +
1.314 +/** Query the time stamp in nanoseconds of @a packet.
1.315 + @param packet Packet initialized by #nestegg_read_packet.
1.316 + @param tstamp Storage for the queried timestamp in nanoseconds.
1.317 + @retval 0 Success.
1.318 + @retval -1 Error. */
1.319 +int nestegg_packet_tstamp(nestegg_packet * packet, uint64_t * tstamp);
1.320 +
1.321 +/** Query the duration in nanoseconds of @a packet.
1.322 + @param packet Packet initialized by #nestegg_read_packet.
1.323 + @param duration Storage for the queried duration in nanoseconds.
1.324 + @retval 0 Success.
1.325 + @retval -1 Error. */
1.326 +int nestegg_packet_duration(nestegg_packet * packet, uint64_t * duration);
1.327 +
1.328 +/** Query the number of data chunks contained in @a packet.
1.329 + @param packet Packet initialized by #nestegg_read_packet.
1.330 + @param count Storage for the queried timestamp in nanoseconds.
1.331 + @retval 0 Success.
1.332 + @retval -1 Error. */
1.333 +int nestegg_packet_count(nestegg_packet * packet, unsigned int * count);
1.334 +
1.335 +/** Get a pointer to chunk number @a item of packet data.
1.336 + @param packet Packet initialized by #nestegg_read_packet.
1.337 + @param item Zero based chunk item number.
1.338 + @param data Storage for the queried data pointer.
1.339 + The data is owned by the #nestegg_packet packet.
1.340 + @param length Storage for the queried data size.
1.341 + @retval 0 Success.
1.342 + @retval -1 Error. */
1.343 +int nestegg_packet_data(nestegg_packet * packet, unsigned int item,
1.344 + unsigned char ** data, size_t * length);
1.345 +
1.346 +/** Returns discard_padding for given packet
1.347 + @param packet Packet initialized by #nestegg_read_packet.
1.348 + @param discard_padding pointer to store discard padding in.
1.349 + @retval 0 Success.
1.350 + @retval -1 Error. */
1.351 +int nestegg_packet_discard_padding(nestegg_packet * packet,
1.352 + int64_t * discard_padding);
1.353 +
1.354 +/** Query the presence of cues.
1.355 + @param context Stream context initialized by #nestegg_init.
1.356 + @retval 0 The media has no cues.
1.357 + @retval 1 The media has cues. */
1.358 +int nestegg_has_cues(nestegg * context);
1.359 +
1.360 +/**
1.361 + * Try to determine if the buffer looks like the beginning of a WebM file.
1.362 + *
1.363 + * @param buffer A buffer containing the beginning of a media file.
1.364 + * @param length The size of the buffer.
1.365 + * @retval 0 The file is not a WebM file.
1.366 + * @retval 1 The file is a WebM file. */
1.367 +int nestegg_sniff(unsigned char const * buffer, size_t length);
1.368 +
1.369 +/**
1.370 + * Set the underlying allocation function for library allocations.
1.371 + *
1.372 + * @param realloc_func The desired function.
1.373 + */
1.374 +void nestegg_set_halloc_func(void * (* realloc_func)(void *, size_t));
1.375 +
1.376 +#if defined(__cplusplus)
1.377 +}
1.378 +#endif
1.379 +
1.380 +#endif /* NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 */
