### th_setup_info

Source: https://theora.org/doc/libtheora-1.2/theoradec_8h.html

Setup information typedef containing auxiliary information decoded from the setup header.

```APIDOC
## th_setup_info

### Description
Setup information. This contains auxiliary information (Huffman tables and quantization parameters) decoded from the setup header by th_decode_headerin() to be passed to th_decode_alloc(). It can be re-used to initialize any number of decoders, and can be freed via th_setup_free() at any time.

### Type
typedef struct th_setup_info th_setup_info

### Usage
Pass this to th_decode_alloc() when initializing a decoder. Free with th_setup_free() when no longer needed.
```

--------------------------------

### th_setup_free()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Frees setup information. This function is part of the theoradec.h API.

```APIDOC
## th_setup_free()

### Description
Frees setup information.

### Header
theoradec.h

### Parameters
- **setup** (th_setup_info*) - The setup information to free.

### Returns
void
```

--------------------------------

### th_setup_free

Source: https://theora.org/doc/libtheora-1.2/theoradec_8h_source.html

Releases all storage used for the decoder setup information. This function frees the setup information structure.

```APIDOC
## th_setup_free

### Description
Releases all storage used for the decoder setup information. This function frees the setup information structure.

### Function Signature
```c
void th_setup_free(th_setup_info *_setup);
```

### Parameters
- **_setup** (th_setup_info*) - The setup information to free.
```

--------------------------------

### theora_encode_tables

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Generates the setup header packet for the Theora stream. This function encodes the codec setup tables.

```APIDOC
## theora_encode_tables

### Description
Generates the setup header packet for the Theora stream. This function encodes the codec setup tables.

### Function Signature
`int theora_encode_tables(theora_state *t, ogg_packet *op)`

### Parameters
- **t** (theora_state*) - Pointer to the Theora encoder state.
- **op** (ogg_packet*) - Pointer to the output packet structure.

### Return Value
Returns 0 on success, or a negative value on error.
```

--------------------------------

### TH_ENCCTL_SET_COMPAT_CONFIG

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Sets the encoder configuration to be compatible with a given setup header. This ensures packets encoded will be decodable by a decoder configured with that setup header. It does not guarantee bit-identical setup headers.

```APIDOC
## TH_ENCCTL_SET_COMPAT_CONFIG

### Description
Sets the configuration to be compatible with that from the given setup header. This sets Huffman codebooks and quantization parameters to match those in the setup header. It does not guarantee bit-identical setup headers, only compatibility. VP3 compatibility is not affected by this command.

### Method
Encoder control command (th_encode_ctl)

### Parameters
#### Input Parameters
- **_buf** (unsigned char[]) - Required - The encoded setup header to copy the configuration from. Should be the original, undecoded setup header packet.

### Return Values
- **TH_EFAULT** - _enc_ or _buf_ is NULL.
- **TH_EINVAL** - Encoding has already begun, or the data in the setup header was not supported.
- **TH_EBADHEADER** - _buf_ did not contain a valid setup header packet.
- **TH_ENOTFORMAT** - _buf_ did not contain a Theora header at all.
- **TH_EIMPL** - Not supported by this implementation.

```

--------------------------------

### th_encode_flushheader()

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Outputs the next header packet. This should be called repeatedly after encoder initialization until it returns 0 in order to get all of the header packets, in order, before encoding actual video data.

```APIDOC
## th_encode_flushheader()

### Description
Outputs the next header packet. This should be called repeatedly after encoder initialization until it returns 0 in order to get all of the header packets, in order, before encoding actual video data.

### Method
Function call

### Endpoint
th_encode_flushheader(th_enc_ctx *__enc_, th_comment *__comments_, ogg_packet *__op_)

### Parameters
- **__enc_** (th_enc_ctx *) - Required - A th_enc_ctx handle.
- **__comments_** (th_comment *) - Required - The metadata to place in the comment header, when it is encoded.
- **__op_** (ogg_packet *) - Required - An `ogg_packet` structure to fill. All of the elements of this structure will be set, including a pointer to the header data. The memory for the header data is owned by `libtheoraenc`, and may be invalidated when the next encoder function is called.

### Returns
A positive value indicates that a header packet was successfully produced.

### Return Values
- **0** - No packet was produced, and no more header packets remain.
- **TH_EFAULT** - __enc_, __comments_, or __op_ was `NULL`.
```

--------------------------------

### Initialize theora_info and theora_comment structures

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Initializes theora_info and theora_comment structures using theora_info_init() and theora_comment_init(). This is the first step in the decoding process.

```c
theora_info     info;
theora_comment  comment;

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

```

--------------------------------

### theora_info_init()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Initializes a theora_info structure. This function is part of the legacy theora.h API.

```APIDOC
## theora_info_init()

### Description
Initializes a theora_info structure.

### Header
theora.h

### Parameters
- **i** (theora_info*) - The info structure to initialize.

### Returns
void
```

--------------------------------

### Initialize the decoder with theora_decode_init

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Initializes the decoder based on the information retrieved into the theora_info struct. Requires a theora_state struct.

```c
theora_state state;

theora_decode_init(&state, &info);

```

--------------------------------

### th_granule_frame

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Converts a granule position to an absolute frame index, starting at 0.

```APIDOC
## th_granule_frame

### Description
Converts a granule position to an absolute frame index, starting at 0.

### Function Signature
ogg_int64_t th_granule_frame (void *_encdec, ogg_int64_t _granpos)

### Parameters
- **_encdec** (void*) - The encoder or decoder context.
- **_granpos** (ogg_int64_t) - The granule position to convert.

### Returns
The absolute frame index.
```

--------------------------------

### theora_decode_init()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Initializes the decoder. This function is part of the legacy theora.h API.

```APIDOC
## theora_decode_init()

### Description
Initializes the decoder.

### Header
theora.h

### Parameters
- **t** (theora_state*) - The state.
- **info** (theora_info*) - The info structure.

### Returns
int - 0 on success, or an error code.
```

--------------------------------

### theora_control

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Controls the Theora codec. This function allows setting or getting codec-specific parameters.

```APIDOC
## theora_control

### Description
Controls the Theora codec. This function allows setting or getting codec-specific parameters.

### Function Signature
`int theora_control(theora_state *th, int req, void *buf, size_t buf_sz)`

### Parameters
- **th** (theora_state*) - Pointer to the Theora state.
- **req** (int) - The control request identifier.
- **buf** (void*) - Pointer to the buffer for input/output.
- **buf_sz** (size_t) - Size of the buffer.

### Return Value
Returns 0 on success, or a negative value on error.
```

--------------------------------

### theora_granule_frame

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Converts a granulepos to an absolute frame index, starting at 0. This is used for frame indexing.

```APIDOC
## theora_granule_frame

### Description
Convert a granulepos to an absolute frame index, starting at 0.

### Function Signature
`ogg_int64_t theora_granule_frame(theora_state *th, ogg_int64_t granulepos)`

### Parameters
- **th** (theora_state*) - Pointer to the theora_state handle.
- **granulepos** (ogg_int64_t) - The granule position.

### Return Value
- **ogg_int64_t** - The absolute frame index.
```

--------------------------------

### theora_decode_init

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Initializes the decoder state. This function prepares the decoder for decoding using the provided info.

```APIDOC
## theora_decode_init

### Description
Initializes the decoder state. This function prepares the decoder for decoding using the provided info.

### Function Signature
`int theora_decode_init(theora_state *th, theora_info *c)`

### Parameters
- **th** (theora_state*) - Pointer to the decoder state to initialize.
- **c** (theora_info*) - Pointer to the info structure.

### Return Value
Returns 0 on success, or a negative value on error.
```

--------------------------------

### th_decode_headerin

Source: https://theora.org/doc/libtheora-1.2/theoradec_8h_source.html

Decodes the header packets of a Theora stream. This function processes the header packets to extract stream information and setup data.

```APIDOC
## th_decode_headerin

### Description
Decodes the header packets of a Theora stream. This function processes the header packets to extract stream information and setup data.

### Function Signature
```c
int th_decode_headerin(th_info *_info, th_comment *_tc, th_setup_info **_setup, ogg_packet *_op);
```

### Parameters
- **_info** (th_info*) - Theora bitstream information structure to be filled.
- **_tc** (th_comment*) - The comment information structure to be filled.
- **_setup** (th_setup_info**) - Pointer to a pointer where the setup information will be stored.
- **_op** (ogg_packet*) - The header packet to decode.

### Return Value
Returns an integer indicating success or failure. A value of 0 indicates success, a positive value indicates more headers are needed, and a negative value indicates an error.
```

--------------------------------

### th_info_init

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Initializes a th_info structure.

```APIDOC
## th_info_init

### Description
Initializes a th_info structure.

### Function Signature
void th_info_init (th_info *_info)

### Parameters
- **_info** (th_info*) - The structure to initialize.

### Returns
None
```

--------------------------------

### th_granule_frame()

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Converts a granule position to an absolute frame index, starting at 0. The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle.

```APIDOC
## th_granule_frame()

### Description
Converts a granule position to an absolute frame index, starting at 0. The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle.

### Method
Function

### Signature
ogg_int64_t th_granule_frame(void *__encdec_, ogg_int64_t __granpos_)

### Parameters
- **__encdec_** (void *) - Required - A previously allocated th_enc_ctx or th_dec_ctx handle.
- **__granpos_** (ogg_int64_t) - Required - The granule position to convert.

### Returns
The absolute frame index corresponding to __granpos_.

### Return Values
- **-1** - The given granule position was invalid (i.e. negative).
```

--------------------------------

### theora_encode_init()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Initializes the encoder. This function is part of the legacy theora.h API.

```APIDOC
## theora_encode_init()

### Description
Initializes the encoder.

### Header
theora.h

### Parameters
- **t** (theora_state*) - The state.
- **info** (theora_info*) - The info structure.

### Returns
int - 0 on success, or an error code.
```

--------------------------------

### th_info_init()

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Initializes a th_info structure. This should be called on a freshly allocated th_info structure before attempting to use it.

```APIDOC
## th_info_init()

### Description
Initializes a th_info structure. This should be called on a freshly allocated th_info structure before attempting to use it.

### Method
th_info_init

### Signature
void th_info_init(th_info *_info)

### Parameters
- **_info** (th_info*) - Required - The th_info struct to initialize.

```

--------------------------------

### TH_DECCTL_GET_PPLEVEL_MAX

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Gets the maximum post-processing level supported by the decoder. This value corresponds to the highest level of post-processing, which provides maximum improvement in image appearance at the cost of computational expense.

```APIDOC
## TH_DECCTL_GET_PPLEVEL_MAX

### Description
Gets the maximum post-processing level. The decoder supports a post-processing filter that can improve the appearance of the decoded images. This returns the highest level setting for this post-processor, corresponding to maximum improvement and computational expense.

### Constant
`#define TH_DECCTL_GET_PPLEVEL_MAX (1)`

### Usage
Use with the decoder control function to retrieve the maximum post-processing level.

### Return Value
The maximum post-processing level (integer).
```

--------------------------------

### TH_ENCCTL_GET_SPLEVEL

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Gets the current encoding speed level. The default speed level may vary by implementation; if unsupported, the slowest speed (0) is assumed. The maximum speed level can be obtained via TH_ENCCTL_GET_SPLEVEL_MAX.

```APIDOC
## TH_ENCCTL_GET_SPLEVEL

### Description
Gets the current encoding speed level. The default speed level may vary according to encoder implementation, but if this control code is not supported (it returns TH_EIMPL), the default may be assumed to be the slowest available speed (0). The maximum encoding speed level may be implementation- and encoding mode-specific, and can be obtained via TH_ENCCTL_GET_SPLEVEL_MAX.

### Control Code
`TH_ENCCTL_GET_SPLEVEL` (16)

### Parameters
- **_buf** (int*) - Output - The current encoding speed level. 0 is slowest, larger values use less CPU.

### Return Values
- **TH_EFAULT** - `_enc` or `_buf` is `NULL`.
- **TH_EINVAL** - `_buf_sz` is not `sizeof(int)`.
- **TH_EIMPL** - Not supported by this implementation in the current encoding mode.
```

--------------------------------

### th_version_string

Source: https://theora.org/doc/libtheora-1.2/codec_8h_source.html

Returns a string describing the version of the Theora library.

```APIDOC
## th_version_string

### Description
Returns a string describing the version of the Theora library.

### Function Signature
`extern const char *th_version_string(void);`

### Parameters
None.

### Return Value
A string describing the version of the Theora library.
```

--------------------------------

### TH_ENCCTL_GET_SPLEVEL_MAX

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Gets the maximum encoding speed level. Higher speed levels favor quicker encoding over better quality per bit. The maximum value and meaning of each value may change depending on the current encoding mode.

```APIDOC
## TH_ENCCTL_GET_SPLEVEL_MAX

### Description
Gets the maximum speed level. Higher speed levels favor quicker encoding over better quality per bit. Depending on the encoding mode, and the internal algorithms used, quality may actually improve, but in this case bitrate will also likely increase. In any case, overall rate/distortion performance will probably decrease. The maximum value, and the meaning of each value, may change depending on the current encoding mode (VBR vs. constant quality, etc.).

### Control Code
`TH_ENCCTL_GET_SPLEVEL_MAX` (12)

### Parameters
- **_buf** (int*) - Output - The maximum encoding speed level.

### Return Values
- **TH_EFAULT** - `_enc` or `_buf` is `NULL`.
- **TH_EINVAL** - `_buf_sz` is not `sizeof(int)`.
- **TH_EIMPL** - Not supported by this implementation in the current encoding mode.
```

--------------------------------

### theora_version_string()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Returns the version string of the library. This function is part of the legacy theora.h API.

```APIDOC
## theora_version_string()

### Description
Returns the version string of the library.

### Header
theora.h

### Parameters
None

### Returns
const char* - The version string.
```

--------------------------------

### theora_encode_init

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Initializes a theora_state for encoding with the given theora_info. This function is part of the public API for setting up an encoder.

```APIDOC
## theora_encode_init

### Description
Initializes a theora_state for encoding with the given theora_info.

### Function Signature
`int theora_encode_init(theora_state *th, theora_info *ti);`

### Parameters
- **th** (theora_state*) - Required - Pointer to the theora_state to initialize.
- **ti** (theora_info*) - Required - Pointer to the theora_info containing encoding parameters.

### Return Value
An integer indicating success (0) or failure (non-zero).
```

--------------------------------

### theora_comment_init()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Initializes a theora_comment structure. This function is part of the legacy theora.h API.

```APIDOC
## theora_comment_init()

### Description
Initializes a theora_comment structure.

### Header
theora.h

### Parameters
- **tc** (theora_comment*) - The comment structure to initialize.

### Returns
void
```

--------------------------------

### th_version_string()

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Retrieves a human-readable string to identify the library vendor and version.

```APIDOC
## th_version_string()

### Description
Retrieves a human-readable string to identify the library vendor and version.

### Method
Function

### Signature
const char * th_version_string(void)

### Parameters
None

### Returns
- **const char *** - The version string.
```

--------------------------------

### th_version_string

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Retrieves a human-readable string identifying the library vendor and version.

```APIDOC
## th_version_string

### Description
Retrieves a human-readable string to identify the library vendor and version.

### Function Signature
const char * th_version_string (void)

### Parameters
None

### Returns
A string identifying the library vendor and version.
```

--------------------------------

### theora_version_string

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Retrieves a human-readable string identifying the encoder vendor and version.

```APIDOC
## theora_version_string

### Description
Retrieve a human-readable string to identify the encoder vendor and version.

### Function Signature
const char * theora_version_string(void)

### Parameters
None.

### Return Value
- **const char*** - A string identifying the encoder vendor and version.
```

--------------------------------

### Decoding Process

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Steps to decode Theora packets from an Ogg stream into raw YUV frames.

```APIDOC
## Decoding Process

### Description
Steps to decode Theora packets from an Ogg stream into raw YUV frames.

### Steps
1. Initialize theora_info and theora_comment structures using theora_info_init() and theora_comment_init().
2. Retrieve header packets from Ogg stream (there should be 3) and decode into theora_info and theora_comment structures using theora_decode_header().
3. Initialize the decoder based on the information retrieved into the theora_info struct by theora_decode_header(). You will need a theora_state struct.
4. Pass in packets and retrieve decoded frames using theora_decode_packetin() and theora_decode_YUVout().

### Example Code
```
theora_info     info;
theora_comment  comment;

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

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

theora_state state;

theora_decode_init(&state, &info);

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);
}
```
```

--------------------------------

### theora_version_number

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Retrieves a 32-bit version number.

```APIDOC
## theora_version_number

### Description
Retrieve a 32-bit version number.

### Function Signature
ogg_uint32_t theora_version_number(void)

### Parameters
None.

### Return Value
- **ogg_uint32_t** - A 32-bit version number.
```

--------------------------------

### th_info

Source: https://theora.org/doc/libtheora-1.2/codec_8h_source.html

Theora bitstream information.

```APIDOC
## th_info

### Description
Theora bitstream information.

### Structure Definition
struct th_info {
    ogg_uint32_t aspect_denominator;
    // ... other fields not shown in source
};

### Fields
- **aspect_denominator** (ogg_uint32_t) - The denominator of the aspect ratio.

### Definition
codec.h:206
```

--------------------------------

### libtheora 1.2 API Index

Source: https://theora.org/doc/libtheora-1.2/globals.html

Alphabetical index of all documented functions, types, constants, and control identifiers in the libtheora 1.2 API, organized by header file.

```APIDOC
## libtheora 1.2 API Index

### Description
Alphabetical index of all documented functions, types, constants, and control identifiers in the libtheora 1.2 API, organized by header file.

### Functions
- `th_comment_add()` - codec.h
- `th_comment_add_tag()` - codec.h
- `th_comment_clear()` - codec.h
- `th_comment_init()` - codec.h
- `th_comment_query()` - codec.h
- `th_comment_query_count()` - codec.h
- `th_decode_alloc()` - theoradec.h
- `th_decode_ctl()` - theoradec.h
- `th_decode_free()` - theoradec.h
- `th_decode_headerin()` - theoradec.h
- `th_decode_packetin()` - theoradec.h
- `th_decode_ycbcr_out()` - theoradec.h
- `th_encode_alloc()` - theoraenc.h
- `th_encode_ctl()` - theoraenc.h
- `th_encode_flushheader()` - theoraenc.h
- `th_encode_free()` - theoraenc.h
- `th_encode_packetout()` - theoraenc.h
- `th_encode_ycbcr_in()` - theoraenc.h
- `th_granule_frame()` - codec.h
- `th_granule_time()` - codec.h
- `th_info_clear()` - codec.h
- `th_info_init()` - codec.h
- `th_packet_isheader()` - codec.h
- `th_packet_iskeyframe()` - codec.h
- `th_setup_free()` - theoradec.h
- `th_version_number()` - codec.h
- `th_version_string()` - codec.h
- `theora_clear()` - theora.h
- `theora_comment_add()` - theora.h
- `theora_comment_add_tag()` - theora.h
- `theora_comment_clear()` - theora.h
- `theora_comment_init()` - theora.h
- `theora_comment_query()` - theora.h
- `theora_comment_query_count()` - theora.h
- `theora_control()` - theora.h
- `theora_decode_header()` - theora.h
- `theora_decode_init()` - theora.h
- `theora_decode_packetin()` - theora.h
- `theora_decode_YUVout()` - theora.h
- `theora_encode_comment()` - theora.h
- `theora_encode_header()` - theora.h
- `theora_encode_init()` - theora.h
- `theora_encode_packetout()` - theora.h
- `theora_encode_tables()` - theora.h
- `theora_encode_YUVin()` - theora.h
- `theora_granule_frame()` - theora.h
- `theora_granule_shift()` - theora.h
- `theora_granule_time()` - theora.h
- `theora_info_clear()` - theora.h
- `theora_info_init()` - theora.h
- `theora_packet_isheader()` - theora.h
- `theora_packet_iskeyframe()` - theora.h
- `theora_version_number()` - theora.h
- `theora_version_string()` - theora.h

### Types
- `th_colorspace` - codec.h
- `th_comment` - codec.h
- `th_dec_ctx` - theoradec.h
- `th_enc_ctx` - theoraenc.h
- `th_pixel_fmt` - codec.h
- `th_quant_base` - codec.h
- `th_setup_info` - theoradec.h
- `th_stripe_decoded_func` - theoradec.h
- `th_ycbcr_buffer` - codec.h
- `theora_colorspace` - theora.h
- `theora_comment` - theora.h
- `theora_pixelformat` - theora.h

### Constants
- `TH_CS_ITU_REC_470BG` - codec.h
- `TH_CS_ITU_REC_470M` - codec.h
- `TH_CS_NSPACES` - codec.h
- `TH_CS_UNSPECIFIED` - codec.h
- `TH_DUPFRAME` - codec.h
- `TH_EBADHEADER` - codec.h
- `TH_EBADPACKET` - codec.h
- `TH_EFAULT` - codec.h
- `TH_EIMPL` - codec.h
- `TH_EINVAL` - codec.h
- `TH_ENOTFORMAT` - codec.h
- `TH_EVERSION` - codec.h
- `TH_NDCT_TOKENS` - codec.h
- `TH_NHUFFMAN_TABLES` - codec.h
- `TH_PF_420` - codec.h
- `TH_PF_422` - codec.h
- `TH_PF_444` - codec.h
- `TH_PF_NFORMATS` - codec.h
- `TH_PF_RSVD` - codec.h
- `TH_RATECTL_CAP_OVERFLOW` - theoraenc.h
- `TH_RATECTL_CAP_UNDERFLOW` - theoraenc.h
- `TH_RATECTL_DROP_FRAMES` - theoraenc.h
- `TH_VP31_HUFF_CODES` - theoraenc.h
- `TH_VP31_QUANT_INFO` - theoraenc.h

### Control Identifiers
- `TH_DECCTL_GET_PPLEVEL_MAX` - theora.h, theoradec.h
- `TH_DECCTL_SET_GRANPOS` - theora.h, theoradec.h
- `TH_DECCTL_SET_PPLEVEL` - theoradec.h, theora.h
- `TH_DECCTL_SET_STRIPE_CB` - theoradec.h
- `TH_DECCTL_SET_TELEMETRY_BITS` - theoradec.h
- `TH_DECCTL_SET_TELEMETRY_MBMODE` - theoradec.h
- `TH_DECCTL_SET_TELEMETRY_MV` - theoradec.h
- `TH_DECCTL_SET_TELEMETRY_QI` - theoradec.h
- `TH_ENCCTL_2PASS_IN` - theoraenc.h
- `TH_ENCCTL_2PASS_OUT` - theoraenc.h
- `TH_ENCCTL_GET_SPLEVEL` - theoraenc.h
- `TH_ENCCTL_GET_SPLEVEL_MAX` - theora.h, theoraenc.h
- `TH_ENCCTL_SET_BITRATE` - theoraenc.h
- `TH_ENCCTL_SET_COMPAT_CONFIG` - theoraenc.h
- `TH_ENCCTL_SET_DUP_COUNT` - theoraenc.h
- `TH_ENCCTL_SET_HUFFMAN_CODES` - theoraenc.h
- `TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE` - theora.h, theoraenc.h
- `TH_ENCCTL_SET_QUALITY` - theoraenc.h
- `TH_ENCCTL_SET_QUANT_PARAMS` - theora.h, theoraenc.h
- `TH_ENCCTL_SET_RATE_BUFFER` - theoraenc.h
- `TH_ENCCTL_SET_RATE_FLAGS` - theoraenc.h
- `TH_ENCCTL_SET_SPLEVEL` - theora.h, theoraenc.h
- `TH_ENCCTL_SET_VP3_COMPATIBLE` - theora.h, theoraenc.h
```

--------------------------------

### TH_ENCCTL_SET_VP3_COMPATIBLE

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Disables any encoder features that would prevent lossless transcoding back to VP3. This primarily means disabling block-adaptive quantization and always coding all four luma blocks in a macro block when 4MV is used.

```APIDOC
## TH_ENCCTL_SET_VP3_COMPATIBLE

### Description
Disables any encoder features that would prevent lossless transcoding back to VP3. This primarily means disabling block-adaptive quantization and always coding all four luma blocks in a macro block when 4MV is used. It also includes using the VP3 quantization tables and Huffman codes; if you set them explicitly after calling this function, the resulting stream will not be VP3-compatible. If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source material, or when using a picture region smaller than the full frame (e.g. a non-multiple-of-16 width or height), then non-VP3 bitstream features will still be disabled, but the stream will still not be VP3-compatible, as VP3 was not capable of encoding such formats. If you call this after encoding has already begun, then the quantization tables and codebooks cannot be changed, but the frame-level features will be enabled or disabled as requested.

### Macro Definition
#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)

### Parameters
#### Input Buffer
- **_buf** (int) - Required - A non-zero value to enable VP3 compatibility, or 0 to disable it (the default).

#### Output Buffer
- **_buf** (int) - 1 if all bitstream features required for VP3-compatibility could be set, and 0 otherwise. The latter will be returned if the pixel format is not 4:2:0, the picture region is smaller than the full frame, or if encoding has begun, preventing the quantization tables and codebooks from being set.

### Return Values
- **TH_EFAULT** - __enc_ or __buf_ is `NULL`.
- **TH_EINVAL** - __buf_sz_ is not `sizeof(int)`.
- **TH_EIMPL** - Not supported by this implementation.
```

--------------------------------

### th_comment_init

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Initializes a th_comment structure.

```APIDOC
## th_comment_init

### Description
Initializes a th_comment structure.

### Function Signature
void th_comment_init (th_comment *_tc)

### Parameters
- **_tc** (th_comment*) - The structure to initialize.

### Returns
None
```

--------------------------------

### theora_version_number()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Returns the version number of the library. This function is part of the legacy theora.h API.

```APIDOC
## theora_version_number()

### Description
Returns the version number of the library.

### Header
theora.h

### Parameters
None

### Returns
int - The version number.
```

--------------------------------

### TH_ENCCTL_SET_VP3_COMPATIBLE

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Sets VP3 compatibility mode for the Theora encoder. Pass a non-zero integer to enable, or zero to disable. Returns 1 if all required bitstream features could be set, otherwise 0.

```APIDOC
## TH_ENCCTL_SET_VP3_COMPATIBLE

### Description
Disables any encoder features that would prevent lossless transcoding back to VP3. This primarily means disabling block-level QI values and not using 4MV mode when any of the luma blocks in a macro block are not coded. It also includes using the VP3 quantization tables and Huffman codes; if you set them explicitly after calling this function, the resulting stream will not be VP3-compatible. If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source material, or when using a picture region smaller than the full frame (e.g. a non-multiple-of-16 width or height), then non-VP3 bitstream features will still be disabled, but the stream will still not be VP3-compatible, as VP3 was not capable of encoding such formats. If you call this after encoding has already begun, then the quantization tables and codebooks cannot be changed, but the frame-level features will be enabled or disabled as requested.

### Parameters
#### Input Parameters
- **buf** (int) - Required - A non-zero value to enable VP3 compatibility, or 0 to disable it (the default).

#### Output Parameters
- **buf** (int) - Required - 1 if all bitstream features required for VP3-compatibility could be set, and 0 otherwise. The latter will be returned if the pixel format is not 4:2:0, the picture region is smaller than the full frame, or if encoding has begun, preventing the quantization tables and codebooks from being set.

### Return Values
- **OC_FAULT** - Returned if _theora_state_ or _buf_ is `NULL`.
- **OC_EINVAL** - Returned if _buf_sz_ is not `sizeof(int)`.
- **OC_IMPL** - Returned if not supported by this implementation.

```

--------------------------------

### th_dec_ctx

Source: https://theora.org/doc/libtheora-1.2/theoradec_8h.html

The decoder context typedef.

```APIDOC
## th_dec_ctx

### Description
The decoder context.

### Type
typedef struct th_dec_ctx th_dec_ctx

### Usage
This opaque type represents the decoder context. It is allocated and managed by the Theora decoder API.
```

--------------------------------

### TH_ENCCTL_2PASS_OUT

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Enables pass 1 of two-pass encoding mode and retrieves the first pass metrics. Must be called before the first frame is encoded and after setting a target bitrate. Returns a pointer to internal storage containing the two-pass metrics data.

```APIDOC
## TH_ENCCTL_2PASS_OUT

### Description
Enables pass 1 of two-pass encoding mode and retrieves the first pass metrics. Must be called before the first frame is encoded and after setting a target bitrate. Returns a pointer to internal storage containing the two-pass metrics data.

### Method
Control (th_encode_ctl)

### Parameters
#### Output Parameters
- **char *_buf** - Returns a pointer to internal storage containing the two-pass metrics data. This storage is only valid until the next call or until the encoder context is freed, and must be copied by the application.

### Return Values
- **>=0** - The number of bytes of metric data available in the returned buffer.
- **TH_EFAULT** - __enc_ or __buf_ is `NULL`.
- **TH_EINVAL** - __buf_sz_ is not `sizeof(char *)`, no target bitrate has been set, or the first call was made after the first frame was submitted for encoding.
- **TH_EIMPL** - Not supported by this implementation.

```

--------------------------------

### th_pixel_fmt

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Enumeration of the currently defined pixel format tags for Theora video frames.

```APIDOC
## th_pixel_fmt

### Description
Enumeration of the currently defined pixel format tags. See the Theora specification, Section 4.4, for details on the precise sample locations.

### Enumerators
- **TH_PF_420** - Chroma decimation by 2 in both the X and Y directions (4:2:0). The Cb and Cr chroma planes are half the width and half the height of the luma plane.
- **TH_PF_RSVD** - Currently reserved.
- **TH_PF_422** - Chroma decimation by 2 in the X direction (4:2:2). The Cb and Cr chroma planes are half the width of the luma plane, but full height.
- **TH_PF_444** - No chroma decimation (4:4:4). The Cb and Cr chroma planes are full width and full height.
- **TH_PF_NFORMATS** - The total number of currently defined pixel formats.
```

--------------------------------

### th_comment_init()

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Initializes a th_comment structure. This should be called on a freshly allocated th_comment structure before attempting to use it.

```APIDOC
## th_comment_init()

### Description
Initialize a th_comment structure. This should be called on a freshly allocated th_comment structure before attempting to use it.

### Method
Function

### Signature
void th_comment_init(th_comment *_tc)

### Parameters
- **_tc** (th_comment*) - The th_comment struct to initialize.

### Returns
void
```

--------------------------------

### th_colorspace

Source: https://theora.org/doc/libtheora-1.2/codec_8h_source.html

The currently defined color space tags.

```APIDOC
## th_colorspace

### Description
The currently defined color space tags.

### Type Definition
th_colorspace

### Values
- **TH_CS_UNSPECIFIED** - The color space was not specified at the encoder.
- **TH_CS_ITU_REC_470M** - A color space designed for NTSC content.
- **TH_CS_ITU_REC_470BG** - A color space designed for PAL/SECAM content.
- **TH_CS_NSPACES** - The total number of currently defined color spaces.

### Definition
codec.h:100
```

--------------------------------

### TH_ENCCTL_SET_QUANT_PARAMS

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Sets the quantization parameters to use. The parameters are copied, not stored by reference, so they can be freed after this call. NULL may be specified to revert to default parameters.

```APIDOC
## TH_ENCCTL_SET_QUANT_PARAMS

### Description
Sets the quantization parameters to use. The parameters are copied, not stored by reference, so they can be freed after this call. `NULL` may be specified to revert to the default parameters.

### Parameters
#### Input Parameters
- **_buf** (th_quant_info) - Required - The quantization parameters to use.

### Return Values
- **TH_EFAULT** - `_enc_` is `NULL`.
- **TH_EINVAL** - Encoding has already begun, `_buf_` is `NULL` and `_buf_sz_` is not zero, or `_buf_` is non-`NULL` and `_buf_sz_` is not `sizeof(th_quant_info)`.
- **TH_EIMPL** - Not supported by this implementation.
```

--------------------------------

### OC_IMPL

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Error code indicating that a feature or action is not implemented.

```APIDOC
## OC_IMPL

### Description
Feature or action not implemented.

### Value
-23
```

--------------------------------

### th_version_number()

Source: https://theora.org/doc/libtheora-1.2/codec_8h.html

Retrieves the library version number as an ogg_uint32_t. The version number is composed of major, minor, and sub-version components.

```APIDOC
## th_version_number()

### Description
Retrieves the library version number. This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. The version number is composed of a 16-bit major version, 8-bit minor version and 8-bit sub-version, composed as follows: (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR).

### Method
Function

### Signature
ogg_uint32_t th_version_number(void)

### Parameters
None

### Returns
- **ogg_uint32_t** - The version number.
```

--------------------------------

### theora_encode_header

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Requests a packet containing the initial header. This is used to generate the header packet for the stream.

```APIDOC
## theora_encode_header

### Description
Request a packet containing the initial header.

### Function Signature
`int theora_encode_header(theora_state *t, ogg_packet *op)`

### Parameters
- **t** (theora_state*) - Pointer to the theora_state handle.
- **op** (ogg_packet*) - Pointer to the Ogg packet to fill.

### Return Value
- **int** - Returns 0 on success, or a negative value on error.
```

--------------------------------

### OC_NEWPACKET

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Error code indicating that the packet is an (ignorable) unhandled extension.

```APIDOC
## OC_NEWPACKET

### Description
Packet is an (ignorable) unhandled extension.

### Value
-25
```

--------------------------------

### Retrieve and decode header packets

Source: https://theora.org/doc/libtheora-1.2/theora_8h.html

Retrieves three header packets from the Ogg stream and decodes them into theora_info and theora_comment structures using theora_decode_header(). The loop assumes a theora packet 'op' is obtained from the Ogg stream.

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

```

--------------------------------

### TH_ENCCTL_2PASS_IN

Source: https://theora.org/doc/libtheora-1.2/theoraenc_8h.html

Submits two-pass encoding metric data collected during the first pass to the second pass. Must be called before the first frame is encoded and requires a target bitrate to be set. The function sets the encoder to pass 2 mode and must be called repeatedly before each frame until all pass 1 data is consumed.

```APIDOC
## TH_ENCCTL_2PASS_IN

### Description
Submits two-pass encoding metric data collected the first encoding pass to the second pass. The first call must be made before the first frame is encoded, and a target bitrate must have already been specified to the encoder. It sets the encoder to pass 2 mode implicitly; this cannot be disabled. The encoder may require reading data from some or all of the frames in advance, depending on, e.g., the reservoir size used in the second pass. You must call this function repeatedly before each frame to provide data until either a) it fails to consume all of the data presented or b) all of the pass 1 data has been consumed. In the first case, you must save the remaining data to be presented after the next frame. You can call this function with a NULL argument to get an upper bound on the number of bytes that will be required before the next frame.

When pass 2 is first enabled, the default bit reservoir is set to the entire file; this gives maximum flexibility but can lead to very high peak rates. You can subsequently set it to another value with TH_ENCCTL_SET_RATE_BUFFER (e.g., to set it to the keyframe interval for non-live streaming), however, you may then need to provide more data before the next frame.

### Parameters
#### Input Parameters
- **_buf** (char[]) - Required - A buffer containing the data returned by TH_ENCCTL_2PASS_OUT in pass 1. You may pass `NULL` for _buf to return an upper bound on the number of additional bytes needed before the next frame. The summary data returned at the end of pass 1 must be at the head of the buffer on the first call with a non-`NULL` _buf, and the placeholder data returned at the start of pass 1 should be omitted. After each call you should advance this buffer by the number of bytes consumed.

### Return Values
- **>0** - The number of bytes of metric data required/consumed.
- **0** - No more data is required before the next frame.
- **TH_EFAULT** - _enc_ is `NULL`.
- **TH_EINVAL** - No target bitrate has been set, or the first call was made after the first frame was submitted for encoding.
- **TH_ENOTFORMAT** - The data did not appear to be pass 1 from a compatible implementation of this library.
- **TH_EBADHEADER** - The data was invalid; this may be returned when attempting to read an aborted pass 1 file that still has the placeholder data in place of the summary data.
- **TH_EIMPL** - Not supported by this implementation.
```

--------------------------------

### TH_DECCTL_SET_TELEMETRY_MBMODE

Source: https://theora.org/doc/libtheora-1.2/theoradec_8h.html

Sets the macroblock display mode. Set to 0 to disable displaying macroblocks.

```APIDOC
## TH_DECCTL_SET_TELEMETRY_MBMODE

### Description
Sets the macroblock display mode. Set to 0 to disable displaying macroblocks.

### Constant
TH_DECCTL_SET_TELEMETRY_MBMODE (9)

### Usage
Pass this constant as the control parameter to the decoder control function to set the macroblock display mode.

### Parameters
- **value** (int) - Required - Set to 0 to disable displaying macroblocks.
```

--------------------------------

### th_quant_info and th_quant_ranges

Source: https://theora.org/doc/libtheora-1.2/codec_8h_source.html

These types define quantization parameters for Theora encoding, including base matrices and range sizes.

```APIDOC
## th_quant_info and th_quant_ranges

### Description
th_quant_info represents a complete set of quantization parameters. th_quant_ranges defines a set of qi ranges, including base matrices and their sizes.

### th_quant_ranges Fields
- **base_matrices** (const th_quant_base *) - nranges + 1 base matrices.
- **nranges** (int) - The number of ranges in the set.
- **sizes** (const int *) - The size of each of the nranges ranges.

### Usage
These types are used to specify quantization settings for Theora encoding.
```

--------------------------------

### theora_comment struct

Source: https://theora.org/doc/libtheora-1.2/theora_8h_source.html

Comment header metadata structure.

```APIDOC
## theora_comment

### Description
Comment header metadata.

### Structure
struct theora_comment theora_comment
```

--------------------------------

### theora_encode_tables()

Source: https://theora.org/doc/libtheora-1.2/globals_func.html

Encodes the tables. This function is part of the legacy theora.h API.

```APIDOC
## theora_encode_tables()

### Description
Encodes the tables.

### Header
theora.h

### Parameters
- **t** (theora_state*) - The state.
- **op** (ogg_packet*) - The output packet.

### Returns
int - 0 on success, or an error code.
```