theora.h File Reference

The libtheora pre-1.0 legacy C API. More...

#include <stddef.h>
#include <ogg/ogg.h>

Go to the source code of this file.

Data Structures
struct	yuv_buffer
	A YUV buffer for passing uncompressed frames to and from the codec. More...
struct	theora_info
	Theora bitstream info. More...
struct	theora_state
	Codec internal state and context. More...
struct	theora_comment
	Comment header metadata. More...
Defines
#define	OC_FAULT   -1
	General failure.
#define	OC_EINVAL   -10
	Library encountered invalid internal data.
#define	OC_DISABLED   -11
	Requested action is disabled.
#define	OC_BADHEADER   -20
	Header packet was corrupt/invalid.
#define	OC_NOTFORMAT   -21
	Packet is not a theora packet.
#define	OC_VERSION   -22
	Bitstream version is not handled.
#define	OC_IMPL   -23
	Feature or action not implemented.
#define	OC_BADPACKET   -24
	Packet is corrupt.
#define	OC_NEWPACKET   -25
	Packet is an (ignorable) unhandled extension.
#define	OC_DUPFRAME   1
	Packet is a dropped frame.
theora_control() codes
#define	TH_DECCTL_GET_PPLEVEL_MAX   (1)
	Get the maximum post-processing level.
#define	TH_DECCTL_SET_PPLEVEL   (3)
	Set the post-processing level.
#define	TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE   (4)
	Sets the maximum distance between key frames.
#define	TH_DECCTL_SET_GRANPOS   (5)
	Set the granule position.
#define	TH_ENCCTL_SET_QUANT_PARAMS   (2)
	Sets the quantization parameters to use.
#define	TH_ENCCTL_SET_VP3_COMPATIBLE   (10)
	Disables any encoder features that would prevent lossless transcoding back to VP3.
#define	TH_ENCCTL_GET_SPLEVEL_MAX   (12)
	Gets the maximum speed level.
#define	TH_ENCCTL_SET_SPLEVEL   (14)
	Sets the speed level.
Typedefs
typedef struct theora_comment	theora_comment
	Comment header metadata.
Enumerations
enum	theora_colorspace { OC_CS_UNSPECIFIED, OC_CS_ITU_REC_470M, OC_CS_ITU_REC_470BG, OC_CS_NSPACES }
	A Colorspace. More...
enum	theora_pixelformat { OC_PF_420, OC_PF_RSVD, OC_PF_422, OC_PF_444 }
	A Chroma subsampling. More...
Functions
const char *	theora_version_string (void)
	Retrieve a human-readable string to identify the encoder vendor and version.
ogg_uint32_t	theora_version_number (void)
	Retrieve a 32-bit version number.
int	theora_encode_init (theora_state *th, theora_info *ti)
	Initialize the theora encoder.
int	theora_encode_YUVin (theora_state *t, yuv_buffer *yuv)
	Submit a YUV buffer to the theora encoder.
int	theora_encode_packetout (theora_state *t, int last_p, ogg_packet *op)
	Request the next packet of encoded video.
int	theora_encode_header (theora_state *t, ogg_packet *op)
	Request a packet containing the initial header.
int	theora_encode_comment (theora_comment *tc, ogg_packet *op)
	Request a comment header packet from provided metadata.
int	theora_encode_tables (theora_state *t, ogg_packet *op)
	Request a packet containing the codebook tables for the stream.
int	theora_decode_header (theora_info *ci, theora_comment *cc, ogg_packet *op)
	Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables.
int	theora_decode_init (theora_state *th, theora_info *c)
	Initialize a theora_state handle for decoding.
int	theora_decode_packetin (theora_state *th, ogg_packet *op)
	Input a packet containing encoded data into the theora decoder.
int	theora_decode_YUVout (theora_state *th, yuv_buffer *yuv)
	Output the next available frame of decoded YUV data.
int	theora_packet_isheader (ogg_packet *op)
	Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use theora_decode_header() for that.
int	theora_packet_iskeyframe (ogg_packet *op)
	Report whether a theora packet is a keyframe or not.
int	theora_granule_shift (theora_info *ti)
	Report the granulepos shift radix.
ogg_int64_t	theora_granule_frame (theora_state *th, ogg_int64_t granulepos)
	Convert a granulepos to an absolute frame index, starting at 0.
double	theora_granule_time (theora_state *th, ogg_int64_t granulepos)
	Convert a granulepos to absolute time in seconds.
void	theora_info_init (theora_info *c)
	Initialize a theora_info structure.
void	theora_info_clear (theora_info *c)
	Clear a theora_info structure.
void	theora_clear (theora_state *t)
	Free all internal data associated with a theora_state handle.
void	theora_comment_init (theora_comment *tc)
	Initialize an allocated theora_comment structure.
void	theora_comment_add (theora_comment *tc, char *comment)
	Add a comment to an initialized theora_comment structure.
void	theora_comment_add_tag (theora_comment *tc, char *tag, char *value)
	Add a comment to an initialized theora_comment structure.
char *	theora_comment_query (theora_comment *tc, char *tag, int count)
	Look up a comment value by tag.
int	theora_comment_query_count (theora_comment *tc, char *tag)
	Look up the number of instances of a tag.
void	theora_comment_clear (theora_comment *tc)
	Clear an allocated theora_comment struct so that it can be freed.
int	theora_control (theora_state *th, int req, void *buf, size_t buf_sz)
	Encoder control function.

---

Detailed Description

The libtheora pre-1.0 legacy C API.

Introduction

This is the documentation for the libtheora legacy C API, declared in the theora.h header, which describes the old interface used before the 1.0 release. This API was widely deployed for several years and remains supported, but for new code we recommend the cleaner API declared in theoradec.h and theoraenc.h.

libtheora is the reference implementation for Theora, a free video codec. Theora is derived from On2's VP3 codec with improved integration with Ogg multimedia formats by Xiph.Org.

Overview

This library will both decode and encode theora packets to/from raw YUV frames. In either case, the packets will most likely either come from or need to be embedded in an Ogg stream. Use libogg or liboggz to extract/package these packets.

Decoding Process

Decoding can be separated into the following steps:

1. initialise theora_info and theora_comment structures using theora_info_init() and theora_comment_init():

    theora_info     info;
    theora_comment  comment;
      
    theora_info_init(&info);
    theora_comment_init(&comment);
    

2. retrieve header packets from Ogg stream (there should be 3) and decode into theora_info and theora_comment structures using theora_decode_header(). See Identifying Theora Packets for more information on identifying which packets are theora packets.

    int i;
    for (i = 0; i < 3; i++)
    {
      (get a theora packet "op" from the Ogg stream)
      theora_decode_header(&info, &comment, op);
    }
    

3. initialise the decoder based on the information retrieved into the theora_info struct by theora_decode_header(). You will need a theora_state struct.

    theora_state state;
    
    theora_decode_init(&state, &info);
    

4. pass in packets and retrieve decoded frames! See the yuv_buffer documentation for information on how to retrieve raw YUV data.

    yuf_buffer buffer;
    while (last packet was not e_o_s) {
      (get a theora packet "op" from the Ogg stream)
      theora_decode_packetin(&state, op);
      theora_decode_YUVout(&state, &buffer);
    }
    

Identifying Theora Packets

All streams inside an Ogg file have a unique serial_no attached to the stream. Typically, you will want to

• retrieve the serial_no for each b_o_s (beginning of stream) page encountered within the Ogg file;
• test the first (only) packet on that page to determine if it is a theora packet;
• once you have found a theora b_o_s page then use the retrieved serial_no to identify future packets belonging to the same theora stream.

Note that you cannot use theora_packet_isheader() to determine if a packet is a theora packet or not, as this function does not perform any checking beyond whether a header bit is present. Instead, use the theora_decode_header() function and check the return value; or examine the header bytes at the beginning of the Ogg page.