1 /* 2 * Copyright 2010 Mozilla Foundation 3 * 4 * This program is made available under an ISC-style license. See the 5 * accompanying file LICENSE for details. 6 */ 7 #ifndef NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 8 #define NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 9 10 #include "vpx/vpx_integer.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** @mainpage 17 18 @section intro Introduction 19 20 This is the documentation fot the <tt>libnestegg</tt> C API. 21 <tt>libnestegg</tt> is a demultiplexing library for <a 22 href="http://www.matroska.org/">Matroska</a> and <a 23 href="http://www.webmproject.org/">WebMedia</a> media files. 24 25 @section example Example code 26 27 @code 28 nestegg * demux_ctx; 29 nestegg_init(&demux_ctx, io, NULL); 30 31 nestegg_packet * pkt; 32 while ((r = nestegg_read_packet(demux_ctx, &pkt)) > 0) { 33 unsigned int track; 34 35 nestegg_packet_track(pkt, &track); 36 37 // This example decodes the first track only. 38 if (track == 0) { 39 unsigned int chunk, chunks; 40 41 nestegg_packet_count(pkt, &chunks); 42 43 // Decode each chunk of data. 44 for (chunk = 0; chunk < chunks; ++chunk) { 45 unsigned char * data; 46 size_t data_size; 47 48 nestegg_packet_data(pkt, chunk, &data, &data_size); 49 50 example_codec_decode(codec_ctx, data, data_size); 51 } 52 } 53 54 nestegg_free_packet(pkt); 55 } 56 57 nestegg_destroy(demux_ctx); 58 @endcode 59 */ 60 61 62 /** @file 63 The <tt>libnestegg</tt> C API. */ 64 65 #define NESTEGG_TRACK_VIDEO 0 /**< Track is of type video. */ 66 #define NESTEGG_TRACK_AUDIO 1 /**< Track is of type audio. */ 67 68 #define NESTEGG_CODEC_VP8 0 /**< Track uses Google On2 VP8 codec. */ 69 #define NESTEGG_CODEC_VORBIS 1 /**< Track uses Xiph Vorbis codec. */ 70 #define NESTEGG_CODEC_VP9 2 /**< Track uses Google On2 VP9 codec. */ 71 72 #define NESTEGG_SEEK_SET 0 /**< Seek offset relative to beginning of stream. */ 73 #define NESTEGG_SEEK_CUR 1 /**< Seek offset relative to current position in stream. */ 74 #define NESTEGG_SEEK_END 2 /**< Seek offset relative to end of stream. */ 75 76 #define NESTEGG_LOG_DEBUG 1 /**< Debug level log message. */ 77 #define NESTEGG_LOG_INFO 10 /**< Informational level log message. */ 78 #define NESTEGG_LOG_WARNING 100 /**< Warning level log message. */ 79 #define NESTEGG_LOG_ERROR 1000 /**< Error level log message. */ 80 #define NESTEGG_LOG_CRITICAL 10000 /**< Critical level log message. */ 81 82 typedef struct nestegg nestegg; /**< Opaque handle referencing the stream state. */ 83 typedef struct nestegg_packet nestegg_packet; /**< Opaque handle referencing a packet of data. */ 84 85 /** User supplied IO context. */ 86 typedef struct { 87 /** User supplied read callback. 88 @param buffer Buffer to read data into. 89 @param length Length of supplied buffer in bytes. 90 @param userdata The #userdata supplied by the user. 91 @retval 1 Read succeeded. 92 @retval 0 End of stream. 93 @retval -1 Error. */ 94 int (* read)(void * buffer, size_t length, void * userdata); 95 96 /** User supplied seek callback. 97 @param offset Offset within the stream to seek to. 98 @param whence Seek direction. One of #NESTEGG_SEEK_SET, 99 #NESTEGG_SEEK_CUR, or #NESTEGG_SEEK_END. 100 @param userdata The #userdata supplied by the user. 101 @retval 0 Seek succeeded. 102 @retval -1 Error. */ 103 int (* seek)(int64_t offset, int whence, void * userdata); 104 105 /** User supplied tell callback. 106 @param userdata The #userdata supplied by the user. 107 @returns Current position within the stream. 108 @retval -1 Error. */ 109 int64_t (* tell)(void * userdata); 110 111 /** User supplied pointer to be passed to the IO callbacks. */ 112 void * userdata; 113 } nestegg_io; 114 115 /** Parameters specific to a video track. */ 116 typedef struct { 117 unsigned int width; /**< Width of the video frame in pixels. */ 118 unsigned int height; /**< Height of the video frame in pixels. */ 119 unsigned int display_width; /**< Display width of the video frame in pixels. */ 120 unsigned int display_height; /**< Display height of the video frame in pixels. */ 121 unsigned int crop_bottom; /**< Pixels to crop from the bottom of the frame. */ 122 unsigned int crop_top; /**< Pixels to crop from the top of the frame. */ 123 unsigned int crop_left; /**< Pixels to crop from the left of the frame. */ 124 unsigned int crop_right; /**< Pixels to crop from the right of the frame. */ 125 } nestegg_video_params; 126 127 /** Parameters specific to an audio track. */ 128 typedef struct { 129 double rate; /**< Sampling rate in Hz. */ 130 unsigned int channels; /**< Number of audio channels. */ 131 unsigned int depth; /**< Bits per sample. */ 132 } nestegg_audio_params; 133 134 /** Logging callback function pointer. */ 135 typedef void (* nestegg_log)(nestegg * context, unsigned int severity, char const * format, ...); 136 137 /** Initialize a nestegg context. During initialization the parser will 138 read forward in the stream processing all elements until the first 139 block of media is reached. All track metadata has been processed at this point. 140 @param context Storage for the new nestegg context. @see nestegg_destroy 141 @param io User supplied IO context. 142 @param callback Optional logging callback function pointer. May be NULL. 143 @retval 0 Success. 144 @retval -1 Error. */ 145 int nestegg_init(nestegg ** context, nestegg_io io, nestegg_log callback); 146 147 /** Destroy a nestegg context and free associated memory. 148 @param context #nestegg context to be freed. @see nestegg_init */ 149 void nestegg_destroy(nestegg * context); 150 151 /** Query the duration of the media stream in nanoseconds. 152 @param context Stream context initialized by #nestegg_init. 153 @param duration Storage for the queried duration. 154 @retval 0 Success. 155 @retval -1 Error. */ 156 int nestegg_duration(nestegg * context, uint64_t * duration); 157 158 /** Query the tstamp scale of the media stream in nanoseconds. 159 Timecodes presented by nestegg have been scaled by this value 160 before presentation to the caller. 161 @param context Stream context initialized by #nestegg_init. 162 @param scale Storage for the queried scale factor. 163 @retval 0 Success. 164 @retval -1 Error. */ 165 int nestegg_tstamp_scale(nestegg * context, uint64_t * scale); 166 167 /** Query the number of tracks in the media stream. 168 @param context Stream context initialized by #nestegg_init. 169 @param tracks Storage for the queried track count. 170 @retval 0 Success. 171 @retval -1 Error. */ 172 int nestegg_track_count(nestegg * context, unsigned int * tracks); 173 174 /** Seek @a track to @a tstamp. Stream seek will terminate at the earliest 175 key point in the stream at or before @a tstamp. Other tracks in the 176 stream will output packets with unspecified but nearby timestamps. 177 @param context Stream context initialized by #nestegg_init. 178 @param track Zero based track number. 179 @param tstamp Absolute timestamp in nanoseconds. 180 @retval 0 Success. 181 @retval -1 Error. */ 182 int nestegg_track_seek(nestegg * context, unsigned int track, uint64_t tstamp); 183 184 /** Query the type specified by @a track. 185 @param context Stream context initialized by #nestegg_init. 186 @param track Zero based track number. 187 @retval #NESTEGG_TRACK_VIDEO Track type is video. 188 @retval #NESTEGG_TRACK_AUDIO Track type is audio. 189 @retval -1 Error. */ 190 int nestegg_track_type(nestegg * context, unsigned int track); 191 192 /** Query the codec ID specified by @a track. 193 @param context Stream context initialized by #nestegg_init. 194 @param track Zero based track number. 195 @retval #NESTEGG_CODEC_VP8 Track codec is VP8. 196 @retval #NESTEGG_CODEC_VORBIS Track codec is Vorbis. 197 @retval -1 Error. */ 198 int nestegg_track_codec_id(nestegg * context, unsigned int track); 199 200 /** Query the number of codec initialization chunks for @a track. Each 201 chunk of data should be passed to the codec initialization functions in 202 the order returned. 203 @param context Stream context initialized by #nestegg_init. 204 @param track Zero based track number. 205 @param count Storage for the queried chunk count. 206 @retval 0 Success. 207 @retval -1 Error. */ 208 int nestegg_track_codec_data_count(nestegg * context, unsigned int track, 209 unsigned int * count); 210 211 /** Get a pointer to chunk number @a item of codec initialization data for 212 @a track. 213 @param context Stream context initialized by #nestegg_init. 214 @param track Zero based track number. 215 @param item Zero based chunk item number. 216 @param data Storage for the queried data pointer. 217 The data is owned by the #nestegg context. 218 @param length Storage for the queried data size. 219 @retval 0 Success. 220 @retval -1 Error. */ 221 int nestegg_track_codec_data(nestegg * context, unsigned int track, unsigned int item, 222 unsigned char ** data, size_t * length); 223 224 /** Query the video parameters specified by @a track. 225 @param context Stream context initialized by #nestegg_init. 226 @param track Zero based track number. 227 @param params Storage for the queried video parameters. 228 @retval 0 Success. 229 @retval -1 Error. */ 230 int nestegg_track_video_params(nestegg * context, unsigned int track, 231 nestegg_video_params * params); 232 233 /** Query the audio parameters specified by @a track. 234 @param context Stream context initialized by #nestegg_init. 235 @param track Zero based track number. 236 @param params Storage for the queried audio parameters. 237 @retval 0 Success. 238 @retval -1 Error. */ 239 int nestegg_track_audio_params(nestegg * context, unsigned int track, 240 nestegg_audio_params * params); 241 242 /** Read a packet of media data. A packet consists of one or more chunks of 243 data associated with a single track. nestegg_read_packet should be 244 called in a loop while the return value is 1 to drive the stream parser 245 forward. @see nestegg_free_packet 246 @param context Context returned by #nestegg_init. 247 @param packet Storage for the returned nestegg_packet. 248 @retval 1 Additional packets may be read in subsequent calls. 249 @retval 0 End of stream. 250 @retval -1 Error. */ 251 int nestegg_read_packet(nestegg * context, nestegg_packet ** packet); 252 253 /** Destroy a nestegg_packet and free associated memory. 254 @param packet #nestegg_packet to be freed. @see nestegg_read_packet */ 255 void nestegg_free_packet(nestegg_packet * packet); 256 257 /** Query the track number of @a packet. 258 @param packet Packet initialized by #nestegg_read_packet. 259 @param track Storage for the queried zero based track index. 260 @retval 0 Success. 261 @retval -1 Error. */ 262 int nestegg_packet_track(nestegg_packet * packet, unsigned int * track); 263 264 /** Query the time stamp in nanoseconds of @a packet. 265 @param packet Packet initialized by #nestegg_read_packet. 266 @param tstamp Storage for the queried timestamp in nanoseconds. 267 @retval 0 Success. 268 @retval -1 Error. */ 269 int nestegg_packet_tstamp(nestegg_packet * packet, uint64_t * tstamp); 270 271 /** Query the number of data chunks contained in @a packet. 272 @param packet Packet initialized by #nestegg_read_packet. 273 @param count Storage for the queried timestamp in nanoseconds. 274 @retval 0 Success. 275 @retval -1 Error. */ 276 int nestegg_packet_count(nestegg_packet * packet, unsigned int * count); 277 278 /** Get a pointer to chunk number @a item of packet data. 279 @param packet Packet initialized by #nestegg_read_packet. 280 @param item Zero based chunk item number. 281 @param data Storage for the queried data pointer. 282 The data is owned by the #nestegg_packet packet. 283 @param length Storage for the queried data size. 284 @retval 0 Success. 285 @retval -1 Error. */ 286 int nestegg_packet_data(nestegg_packet * packet, unsigned int item, 287 unsigned char ** data, size_t * length); 288 289 #ifdef __cplusplus 290 } 291 #endif 292 293 #endif /* NESTEGG_671cac2a_365d_ed69_d7a3_4491d3538d79 */ 294
