libtheora Documentation

1.0beta1

Introduction

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.

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.

Example Decoder

See examples/dump_video.c for a simple decoder implementation.

Encoding Process

See examples/encoder_example.c for a simple encoder implementation.

---