libnestegg  0.1git
Data Structures | Macros | Typedefs | Functions
nestegg.h File Reference
#include <limits.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

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...
 

Macros

#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_AV1   4
 Track uses AOMedia AV1 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. More...
 
#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP   2
 Track is top-bottom stereo video. More...
 
#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM   3
 Track is top-bottom stereo video. More...
 
#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT   11
 Track is side-by-side stereo video. More...
 
#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_SIGNAL_BYTE_PARTITIONED   4
 Packet has signal byte and is partitioned.
 
#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.
 

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, int64_t max_offset)
 Initialize a nestegg context. More...
 
void nestegg_destroy (nestegg *context)
 Destroy a nestegg context and free associated memory. More...
 
int nestegg_duration (nestegg *context, uint64_t *duration)
 Query the duration of the media stream in nanoseconds. More...
 
int nestegg_tstamp_scale (nestegg *context, uint64_t *scale)
 Query the tstamp scale of the media stream in nanoseconds. More...
 
int nestegg_track_count (nestegg *context, unsigned int *tracks)
 Query the number of tracks in the media stream. More...
 
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)
 Query the start and end offset for a particular cluster. More...
 
int nestegg_offset_seek (nestegg *context, uint64_t offset)
 Seek to offset. More...
 
int nestegg_track_seek (nestegg *context, unsigned int track, uint64_t tstamp)
 Seek track to tstamp. More...
 
int nestegg_track_type (nestegg *context, unsigned int track)
 Query the type specified by track. More...
 
int nestegg_track_codec_id (nestegg *context, unsigned int track)
 Query the codec ID specified by track. More...
 
int nestegg_track_codec_data_count (nestegg *context, unsigned int track, unsigned int *count)
 Query the number of codec initialization chunks for track. More...
 
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. More...
 
int nestegg_track_video_params (nestegg *context, unsigned int track, nestegg_video_params *params)
 Query the video parameters specified by track. More...
 
int nestegg_track_audio_params (nestegg *context, unsigned int track, nestegg_audio_params *params)
 Query the audio parameters specified by track. More...
 
int nestegg_track_encoding (nestegg *context, unsigned int track)
 Query the encoding status for track. More...
 
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 ContentEncKeyId for track. More...
 
int nestegg_track_default_duration (nestegg *context, unsigned int track, uint64_t *duration)
 Query the default frame duration for track. More...
 
int nestegg_read_reset (nestegg *context)
 Reset parser state to the last valid state before nestegg_read_packet failed. More...
 
int nestegg_read_packet (nestegg *context, nestegg_packet **packet)
 Read a packet of media data. More...
 
void nestegg_free_packet (nestegg_packet *packet)
 Destroy a nestegg_packet and free associated memory. More...
 
int nestegg_packet_has_keyframe (nestegg_packet *packet)
 Query the keyframe status for a given packet. More...
 
int nestegg_packet_track (nestegg_packet *packet, unsigned int *track)
 Query the track number of packet. More...
 
int nestegg_packet_tstamp (nestegg_packet *packet, uint64_t *tstamp)
 Query the timestamp in nanoseconds of packet. More...
 
int nestegg_packet_duration (nestegg_packet *packet, uint64_t *duration)
 Query the duration in nanoseconds of packet. More...
 
int nestegg_packet_count (nestegg_packet *packet, unsigned int *count)
 Query the number of data chunks contained in packet. More...
 
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. More...
 
int nestegg_packet_additional_data (nestegg_packet *packet, unsigned int id, unsigned char **data, size_t *length)
 Get a pointer to additional data with identifier id of additional packet data. More...
 
int nestegg_packet_discard_padding (nestegg_packet *packet, int64_t *discard_padding)
 Returns discard_padding for given packet. More...
 
int nestegg_packet_encryption (nestegg_packet *packet)
 Query if a packet is encrypted. More...
 
int nestegg_packet_iv (nestegg_packet *packet, unsigned char const **iv, size_t *length)
 Query the IV for an encrypted packet. More...
 
int nestegg_packet_offsets (nestegg_packet *packet, uint32_t const **partition_offsets, uint8_t *num_offsets)
 Query the packet for offsets. More...
 
int nestegg_packet_reference_block (nestegg_packet *packet, int64_t *reference_block)
 Returns reference_block given packet. More...
 
int nestegg_has_cues (nestegg *context)
 Query the presence of cues. More...
 
int nestegg_sniff (unsigned char const *buffer, size_t length)
 Try to determine if the buffer looks like the beginning of a WebM file. More...
 

Detailed Description

The libnestegg C API.

Macro Definition Documentation

◆ NESTEGG_VIDEO_STEREO_LEFT_RIGHT

#define NESTEGG_VIDEO_STEREO_LEFT_RIGHT   1

Track is side-by-side stereo video.

Left first.

◆ NESTEGG_VIDEO_STEREO_BOTTOM_TOP

#define NESTEGG_VIDEO_STEREO_BOTTOM_TOP   2

Track is top-bottom stereo video.

Right first.

◆ NESTEGG_VIDEO_STEREO_TOP_BOTTOM

#define NESTEGG_VIDEO_STEREO_TOP_BOTTOM   3

Track is top-bottom stereo video.

Left first.

◆ NESTEGG_VIDEO_STEREO_RIGHT_LEFT

#define NESTEGG_VIDEO_STEREO_RIGHT_LEFT   11

Track is side-by-side stereo video.

Right first.

Function Documentation

◆ nestegg_init()

int nestegg_init ( nestegg **  context,
nestegg_io  io,
nestegg_log  callback,
int64_t  max_offset 
)

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
contextStorage for the new nestegg context.
See also
nestegg_destroy
Parameters
ioUser supplied IO context.
callbackOptional logging callback function pointer. May be NULL.
max_offsetOptional maximum offset to be read. Set -1 to ignore.
Return values
0Success.
-1Error.

◆ nestegg_destroy()

void nestegg_destroy ( nestegg context)

Destroy a nestegg context and free associated memory.

Parameters
contextnestegg context to be freed.
See also
nestegg_init

◆ nestegg_duration()

int nestegg_duration ( nestegg context,
uint64_t *  duration 
)

Query the duration of the media stream in nanoseconds.

Parameters
contextStream context initialized by nestegg_init.
durationStorage for the queried duration.
Return values
0Success.
-1Error.

◆ nestegg_tstamp_scale()

int nestegg_tstamp_scale ( nestegg context,
uint64_t *  scale 
)

Query the tstamp scale of the media stream in nanoseconds.

Note
Timestamps presented by nestegg have been scaled by this value before presentation to the caller.
Parameters
contextStream context initialized by nestegg_init.
scaleStorage for the queried scale factor.
Return values
0Success.
-1Error.

◆ nestegg_track_count()

int nestegg_track_count ( nestegg context,
unsigned int *  tracks 
)

Query the number of tracks in the media stream.

Parameters
contextStream context initialized by nestegg_init.
tracksStorage for the queried track count.
Return values
0Success.
-1Error.

◆ nestegg_get_cue_point()

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 
)

Query the start and end offset for a particular cluster.

Parameters
contextStream context initialized by nestegg_init.
cluster_numZero-based cluster number; order they appear in cues.
max_offsetOptional maximum offset to be read. Set -1 to ignore.
start_posStarting offset of the cluster. -1 means non-existant.
end_posStarting offset of the cluster. -1 means non-existant or final cluster.
tstampStarting timestamp of the cluster.
Return values
0Success.
-1Error.

◆ nestegg_offset_seek()

int nestegg_offset_seek ( nestegg context,
uint64_t  offset 
)

Seek to 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.

Parameters
contextStream context initialized by nestegg_init.
offsetAbsolute offset in bytes.
Return values
0Success.
-1Error.

◆ nestegg_track_seek()

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
contextStream context initialized by nestegg_init.
trackZero based track number.
tstampAbsolute timestamp in nanoseconds.
Return values
0Success.
-1Error.

◆ nestegg_track_type()

int nestegg_track_type ( nestegg context,
unsigned int  track 
)

Query the type specified by track.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
Return values
NESTEGG_TRACK_VIDEOTrack type is video.
NESTEGG_TRACK_AUDIOTrack type is audio.
NESTEGG_TRACK_UNKNOWNTrack type is unknown.
-1Error.

◆ nestegg_track_codec_id()

int nestegg_track_codec_id ( nestegg context,
unsigned int  track 
)

Query the codec ID specified by track.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
Return values
NESTEGG_CODEC_VP8Track codec is VP8.
NESTEGG_CODEC_VP9Track codec is VP9.
NESTEGG_CODEC_AV1Track codec is AV1.
NESTEGG_CODEC_VORBISTrack codec is Vorbis.
NESTEGG_CODEC_OPUSTrack codec is Opus.
NESTEGG_CODEC_UNKNOWNTrack codec is unknown.
-1Error.

◆ nestegg_track_codec_data_count()

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
contextStream context initialized by nestegg_init.
trackZero based track number.
countStorage for the queried chunk count.
Return values
0Success.
-1Error.

◆ nestegg_track_codec_data()

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
contextStream context initialized by nestegg_init.
trackZero based track number.
itemZero based chunk item number.
dataStorage for the queried data pointer. The data is owned by the nestegg context.
lengthStorage for the queried data size.
Return values
0Success.
-1Error.

◆ nestegg_track_video_params()

int nestegg_track_video_params ( nestegg context,
unsigned int  track,
nestegg_video_params params 
)

Query the video parameters specified by track.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
paramsStorage for the queried video parameters.
Return values
0Success.
-1Error.

◆ nestegg_track_audio_params()

int nestegg_track_audio_params ( nestegg context,
unsigned int  track,
nestegg_audio_params params 
)

Query the audio parameters specified by track.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
paramsStorage for the queried audio parameters.
Return values
0Success.
-1Error.

◆ nestegg_track_encoding()

int nestegg_track_encoding ( nestegg context,
unsigned int  track 
)

Query the encoding status for track.

If a track has multiple encodings the first will be returned.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
Return values
NESTEGG_ENCODING_COMPRESSIONThe track is compressed, but not encrypted.
NESTEGG_ENCODING_ENCRYPTIONThe track is encrypted and compressed.
-1Error.

◆ nestegg_track_content_enc_key_id()

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 ContentEncKeyId for track.

Will return an error if the track in not encrypted, or is not recognized.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
content_enc_key_idStorage for queried id. The content encryption key used. Owned by nestegg and will be freed separately.
content_enc_key_id_lengthLength of the queried ContentEncKeyId in bytes.
Return values
0Success.
-1Error.

◆ nestegg_track_default_duration()

int nestegg_track_default_duration ( nestegg context,
unsigned int  track,
uint64_t *  duration 
)

Query the default frame duration for track.

For a video track, this is typically the inverse of the video frame rate.

Parameters
contextStream context initialized by nestegg_init.
trackZero based track number.
durationStorage for the default duration in nanoseconds.
Return values
0Success.
-1Error.

◆ nestegg_read_reset()

int nestegg_read_reset ( nestegg context)

Reset parser state to the last valid state before nestegg_read_packet failed.

Parameters
contextStream context initialized by nestegg_init.
Return values
0Success.
-1Error.

◆ nestegg_read_packet()

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
contextContext returned by nestegg_init.
packetStorage for the returned nestegg_packet.
Return values
1Additional packets may be read in subsequent calls.
0End of stream.
-1Error.

◆ nestegg_free_packet()

void nestegg_free_packet ( nestegg_packet packet)

Destroy a nestegg_packet and free associated memory.

Parameters
packetnestegg_packet to be freed.
See also
nestegg_read_packet

◆ nestegg_packet_has_keyframe()

int nestegg_packet_has_keyframe ( nestegg_packet packet)

Query the keyframe status for a given packet.

Parameters
packetPacket initialized by nestegg_read_packet.
Return values
NESTEGG_PACKET_HAS_KEYFRAME_FALSEPacket contains no keyframes.
NESTEGG_PACKET_HAS_KEYFRAME_TRUEPacket contains keyframes.
NESTEGG_PACKET_HAS_KEYFRAME_UNKNOWNUnknown packet keyframe content.
-1Error.

◆ nestegg_packet_track()

int nestegg_packet_track ( nestegg_packet packet,
unsigned int *  track 
)

Query the track number of packet.

Parameters
packetPacket initialized by nestegg_read_packet.
trackStorage for the queried zero based track index.
Return values
0Success.
-1Error.

◆ nestegg_packet_tstamp()

int nestegg_packet_tstamp ( nestegg_packet packet,
uint64_t *  tstamp 
)

Query the timestamp in nanoseconds of packet.

Parameters
packetPacket initialized by nestegg_read_packet.
tstampStorage for the queried timestamp in nanoseconds.
Return values
0Success.
-1Error.

◆ nestegg_packet_duration()

int nestegg_packet_duration ( nestegg_packet packet,
uint64_t *  duration 
)

Query the duration in nanoseconds of packet.

Parameters
packetPacket initialized by nestegg_read_packet.
durationStorage for the queried duration in nanoseconds.
Return values
0Success.
-1Error.

◆ nestegg_packet_count()

int nestegg_packet_count ( nestegg_packet packet,
unsigned int *  count 
)

Query the number of data chunks contained in packet.

Parameters
packetPacket initialized by nestegg_read_packet.
countStorage for the queried chunk count.
Return values
0Success.
-1Error.

◆ nestegg_packet_data()

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
packetPacket initialized by nestegg_read_packet.
itemZero based chunk item number.
dataStorage for the queried data pointer. The data is owned by the nestegg_packet packet.
lengthStorage for the queried data size.
Return values
0Success.
-1Error.

◆ nestegg_packet_additional_data()

int nestegg_packet_additional_data ( nestegg_packet packet,
unsigned int  id,
unsigned char **  data,
size_t *  length 
)

Get a pointer to additional data with identifier id of additional packet data.

If id isn't present in the packet, returns -1.

Parameters
packetPacket initialized by nestegg_read_packet.
idCodec specific identifer. For VP8, use 1 to get a VP8 encoded frame containing an alpha channel in its Y plane.
dataStorage for the queried data pointer. The data is owned by the nestegg_packet packet.
lengthStorage for the queried data size.
Return values
0Success.
-1Error.

◆ nestegg_packet_discard_padding()

int nestegg_packet_discard_padding ( nestegg_packet packet,
int64_t *  discard_padding 
)

Returns discard_padding for given packet.

Parameters
packetPacket initialized by nestegg_read_packet.
discard_paddingpointer to store discard padding in.
Return values
0Success.
-1Error.

◆ nestegg_packet_encryption()

int nestegg_packet_encryption ( nestegg_packet packet)

Query if a packet is encrypted.

Parameters
packetPacket initialized by nestegg_read_packet.
Return values
NESTEGG_PACKET_HAS_SIGNAL_BYTE_FALSENo signal byte, encryption information not read from packet.
NESTEGG_PACKET_HAS_SIGNAL_BYTE_UNENCRYPTEDEncrypted bit not set, encryption information not read from packet.
NESTEGG_PACKET_HAS_SIGNAL_BYTE_ENCRYPTEDEncrypted bit set, encryption infomation read from packet.
NESTEGG_PACKET_HAS_SIGNAL_BYTE_PARTITIONEDPartitioned bit set, encryption and parition information read from packet.
-1Error.

◆ nestegg_packet_iv()

int nestegg_packet_iv ( nestegg_packet packet,
unsigned char const **  iv,
size_t *  length 
)

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.

Parameters
packetPacket initialized by nestegg_read_packet.
ivStorage for queried iv.
lengthLength of returned iv, may be 0. The data is owned by the nestegg_packet packet.
Return values
0Success.
-1Error.

◆ nestegg_packet_offsets()

int nestegg_packet_offsets ( nestegg_packet packet,
uint32_t const **  partition_offsets,
uint8_t *  num_offsets 
)

Query the packet for offsets.

Parameters
packetPacket initialized by nestegg_read_packet.
partition_offsetsStorage for queried offsets.
num_offsetsLength of returned offsets, may be 0. The data is owned by the nestegg_packet packet.
Return values
0Success.
-1Error.

◆ nestegg_packet_reference_block()

int nestegg_packet_reference_block ( nestegg_packet packet,
int64_t *  reference_block 
)

Returns reference_block given packet.

Parameters
packetPacket initialized by nestegg_read_packet.
reference_blockpointer to store reference block in.
Return values
0Success.
-1Error.

◆ nestegg_has_cues()

int nestegg_has_cues ( nestegg context)

Query the presence of cues.

Parameters
contextStream context initialized by nestegg_init.
Return values
0The media has no cues.
1The media has cues.

◆ nestegg_sniff()

int nestegg_sniff ( unsigned char const *  buffer,
size_t  length 
)

Try to determine if the buffer looks like the beginning of a WebM file.

Parameters
bufferA buffer containing the beginning of a media file.
lengthThe size of the buffer.
Return values
0The file is not a WebM file.
1The file is a WebM file.