libtheora Documentation
1.0beta2
This is the documentation for the libtheora C API. libtheora is the reference implementation for
Theora, a free video codec. Theora is derived from On2's VP3 codec with improved integration for Ogg multimedia formats by
Xiph.Org.
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 can be separated into the following steps:
- 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);
- 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);
}
- 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);
- 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);
}
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.
See
examples/dump_video.c for a simple decoder implementation.
See
examples/encoder_example.c for a simple encoder implementation.