Classes | Defines | Typedefs | Functions

nestegg.h File Reference

The libnestegg C API. More...

#include <nestegg/nestegg-stdint.h>
Include dependency graph for nestegg.h:

Classes

struct  nestegg_io
 User supplied IO context. More...
struct  nestegg_video_params
 Parameters specific to a video track. More...
struct  nestegg_audio_params
 Parameters specific to an audio track. More...

Defines

#define NESTEGG_TRACK_VIDEO   0
 Track is of type video.
#define NESTEGG_TRACK_AUDIO   1
 Track is of type audio.
#define NESTEGG_CODEC_VP8   0
 Track uses Google On2 VP8 codec.
#define NESTEGG_CODEC_VORBIS   1
 Track uses Xiph Vorbis codec.
#define NESTEGG_VIDEO_MONO   0
 Track is mono video.
#define NESTEGG_VIDEO_STEREO_LEFT_RIGHT   1
 Track is side-by-side stereo video.
#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP   2
 Track is top-bottom stereo video.
#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM   3
 Track is top-bottom stereo video.
#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT   11
 Track is side-by-side stereo video.
#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.

Typedefs

typedef struct nestegg nestegg
 Opaque handle referencing the stream state.
typedef struct nestegg_packet nestegg_packet
 Opaque handle referencing a packet of data.
typedef void(* nestegg_log )(nestegg *context, unsigned int severity, char const *format,...)
 Logging callback function pointer.

Functions

int nestegg_init (nestegg **context, nestegg_io io, nestegg_log callback)
 Initialize a nestegg context.
void nestegg_destroy (nestegg *context)
 Destroy a nestegg context and free associated memory.
int nestegg_duration (nestegg *context, uint64_t *duration)
 Query the duration of the media stream in nanoseconds.
int nestegg_tstamp_scale (nestegg *context, uint64_t *scale)
 Query the tstamp scale of the media stream in nanoseconds.
int nestegg_track_count (nestegg *context, unsigned int *tracks)
 Query the number of tracks in the media stream.
int nestegg_track_seek (nestegg *context, unsigned int track, uint64_t tstamp)
 Seek track to tstamp.
int nestegg_track_type (nestegg *context, unsigned int track)
 Query the type specified by track.
int nestegg_track_codec_id (nestegg *context, unsigned int track)
 Query the codec ID specified by track.
int nestegg_track_codec_data_count (nestegg *context, unsigned int track, unsigned int *count)
 Query the number of codec initialization chunks for track.
int nestegg_track_codec_data (nestegg *context, unsigned int track, unsigned int item, unsigned char **data, size_t *length)
 Get a pointer to chunk number item of codec initialization data for track.
int nestegg_track_video_params (nestegg *context, unsigned int track, nestegg_video_params *params)
 Query the video parameters specified by track.
int nestegg_track_audio_params (nestegg *context, unsigned int track, nestegg_audio_params *params)
 Query the audio parameters specified by track.
int nestegg_read_packet (nestegg *context, nestegg_packet **packet)
 Read a packet of media data.
void nestegg_free_packet (nestegg_packet *packet)
 Destroy a nestegg_packet and free associated memory.
int nestegg_packet_track (nestegg_packet *packet, unsigned int *track)
 Query the track number of packet.
int nestegg_packet_tstamp (nestegg_packet *packet, uint64_t *tstamp)
 Query the time stamp in nanoseconds of packet.
int nestegg_packet_count (nestegg_packet *packet, unsigned int *count)
 Query the number of data chunks contained in packet.
int nestegg_packet_data (nestegg_packet *packet, unsigned int item, unsigned char **data, size_t *length)
 Get a pointer to chunk number item of packet data.

Detailed Description

The libnestegg C API.


Define Documentation

#define NESTEGG_CODEC_VORBIS   1

Track uses Xiph Vorbis codec.

#define NESTEGG_CODEC_VP8   0

Track uses Google On2 VP8 codec.

#define NESTEGG_LOG_CRITICAL   10000

Critical level log message.

#define NESTEGG_LOG_DEBUG   1

Debug level log message.

#define NESTEGG_LOG_ERROR   1000

Error level log message.

#define NESTEGG_LOG_INFO   10

Informational level log message.

#define NESTEGG_LOG_WARNING   100

Warning level log message.

#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_SEEK_SET   0

Seek offset relative to beginning of stream.

#define NESTEGG_TRACK_AUDIO   1

Track is of type audio.

#define NESTEGG_TRACK_VIDEO   0

Track is of type video.

#define NESTEGG_VIDEO_MONO   0

Track is mono video.

#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP   2

Track is top-bottom stereo video.

Right first.

#define NESTEGG_VIDEO_STEREO_LEFT_RIGHT   1

Track is side-by-side stereo video.

Left first.

#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT   11

Track is side-by-side stereo video.

Right first.

#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM   3

Track is top-bottom stereo video.

Left first.


Typedef Documentation

typedef struct nestegg nestegg

Opaque handle referencing the stream state.

typedef void(* nestegg_log)(nestegg *context, unsigned int severity, char const *format,...)

Logging callback function pointer.

Opaque handle referencing a packet of data.


Function Documentation

void nestegg_destroy ( nestegg context  ) 

Destroy a nestegg context and free associated memory.

Parameters:
context nestegg context to be freed.
See also:
nestegg_init
int nestegg_duration ( nestegg context,
uint64_t *  duration 
)

Query the duration of the media stream in nanoseconds.

Parameters:
context Stream context initialized by nestegg_init.
duration Storage for the queried duration.
Return values:
0 Success.
-1 Error.
void nestegg_free_packet ( nestegg_packet packet  ) 

Destroy a nestegg_packet and free associated memory.

Parameters:
packet nestegg_packet to be freed.
See also:
nestegg_read_packet
int nestegg_init ( nestegg **  context,
nestegg_io  io,
nestegg_log  callback 
)

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.

Parameters:
context Storage for the new nestegg context.
See also:
nestegg_destroy
Parameters:
io User supplied IO context.
callback Optional logging callback function pointer. May be NULL.
Return values:
0 Success.
-1 Error.
int nestegg_packet_count ( nestegg_packet packet,
unsigned int *  count 
)

Query the number of data chunks contained in packet.

Parameters:
packet Packet initialized by nestegg_read_packet.
count Storage for the queried timestamp in nanoseconds.
Return values:
0 Success.
-1 Error.
int nestegg_packet_data ( nestegg_packet packet,
unsigned int  item,
unsigned char **  data,
size_t *  length 
)

Get a pointer to chunk number item of packet data.

Parameters:
packet Packet initialized by nestegg_read_packet.
item Zero based chunk item number.
data Storage for the queried data pointer. The data is owned by the nestegg_packet packet.
length Storage for the queried data size.
Return values:
0 Success.
-1 Error.
int nestegg_packet_track ( nestegg_packet packet,
unsigned int *  track 
)

Query the track number of packet.

Parameters:
packet Packet initialized by nestegg_read_packet.
track Storage for the queried zero based track index.
Return values:
0 Success.
-1 Error.
int nestegg_packet_tstamp ( nestegg_packet packet,
uint64_t *  tstamp 
)

Query the time stamp in nanoseconds of packet.

Parameters:
packet Packet initialized by nestegg_read_packet.
tstamp Storage for the queried timestamp in nanoseconds.
Return values:
0 Success.
-1 Error.
int nestegg_read_packet ( nestegg context,
nestegg_packet **  packet 
)

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 also:
nestegg_free_packet
Parameters:
context Context returned by nestegg_init.
packet Storage for the returned nestegg_packet.
Return values:
1 Additional packets may be read in subsequent calls.
0 End of stream.
-1 Error.
int nestegg_track_audio_params ( nestegg context,
unsigned int  track,
nestegg_audio_params params 
)

Query the audio parameters specified by track.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
params Storage for the queried audio parameters.
Return values:
0 Success.
-1 Error.
int nestegg_track_codec_data ( nestegg context,
unsigned int  track,
unsigned int  item,
unsigned char **  data,
size_t *  length 
)

Get a pointer to chunk number item of codec initialization data for track.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
item Zero based chunk item number.
data Storage for the queried data pointer. The data is owned by the nestegg context.
length Storage for the queried data size.
Return values:
0 Success.
-1 Error.
int nestegg_track_codec_data_count ( nestegg context,
unsigned int  track,
unsigned int *  count 
)

Query the number of codec initialization chunks for track.

Each chunk of data should be passed to the codec initialization functions in the order returned.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
count Storage for the queried chunk count.
Return values:
0 Success.
-1 Error.
int nestegg_track_codec_id ( nestegg context,
unsigned int  track 
)

Query the codec ID specified by track.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
Return values:
NESTEGG_CODEC_VP8 Track codec is VP8.
NESTEGG_CODEC_VORBIS Track codec is Vorbis.
-1 Error.
int nestegg_track_count ( nestegg context,
unsigned int *  tracks 
)

Query the number of tracks in the media stream.

Parameters:
context Stream context initialized by nestegg_init.
tracks Storage for the queried track count.
Return values:
0 Success.
-1 Error.
int nestegg_track_seek ( nestegg context,
unsigned int  track,
uint64_t  tstamp 
)

Seek track to tstamp.

Stream seek will terminate at the earliest key point in the stream at or before tstamp. Other tracks in the stream will output packets with unspecified but nearby timestamps.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
tstamp Absolute timestamp in nanoseconds.
Return values:
0 Success.
-1 Error.
int nestegg_track_type ( nestegg context,
unsigned int  track 
)

Query the type specified by track.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
Return values:
NESTEGG_TRACK_VIDEO Track type is video.
NESTEGG_TRACK_AUDIO Track type is audio.
-1 Error.
int nestegg_track_video_params ( nestegg context,
unsigned int  track,
nestegg_video_params params 
)

Query the video parameters specified by track.

Parameters:
context Stream context initialized by nestegg_init.
track Zero based track number.
params Storage for the queried video parameters.
Return values:
0 Success.
-1 Error.
int nestegg_tstamp_scale ( nestegg context,
uint64_t *  scale 
)

Query the tstamp scale of the media stream in nanoseconds.

Timecodes presented by nestegg have been scaled by this value before presentation to the caller.

Parameters:
context Stream context initialized by nestegg_init.
scale Storage for the queried scale factor.
Return values:
0 Success.
-1 Error.