Module Theora

module Theora: sig .. end

Functions for encoding theora files using libtheora.

Author(s): Samuel Mimram, Romain Beauxis

Exceptions

exception Internal_error

General failure.

Library encountered invalid internal data.

exception Invalid_data

An unhandled error happened.

exception Unknown_error of int

The decoded packet represented a dropped frame. The player can continue to display the current frame, as the contents of the decoded frame buffer have not changed.

exception Duplicate_frame

exception Done

Exceptions used by the decoding module.

exception Not_initialized

General functions

val version_string : string

Human-readable string to identify the encoder vendor and version.

val version_number : int * int * int

major, minor and sub version numbers of the encoder.

val is_keyframe : Ogg.Stream.packet -> bool

Determines whether a theora packet is a key frame or not.

raises Invalid_data if The packet is not a video data packet.

Types and datastructures

type colorspace =

`\|`	`CS_unspecified`	`(*`	The colorspace is unknown or unspecified	`*)`
`\|`	`CS_ITU_REC_470M`	`(*`	This is the best option for 'NTSC' content	`*)`
`\|`	`CS_ITU_REC_470BG`	`(*`	This is the best option for 'PAL' content	`*)`
`\|`	`CS_NSPACES`	`(*`	This marks the end of the defined colorspaces	`*)`

A Colorspace.

type pixelformat =

`\|`	`PF_420`	`(*`	Chroma subsampling by 2 in each direction (4:2:0)	`*)`
`\|`	`PF_reserved`	`(*`	Reserved value	`*)`
`\|`	`PF_422`	`(*`	Horizonatal chroma subsampling by 2 (4:2:2)	`*)`
`\|`	`PF_444`	`(*`	No chroma subsampling at all (4:4:4)	`*)`

A Chroma subsampling

These enumerate the available chroma subsampling options supported by the theora format. See Section 4.4 of the specification for exact definitions.

type info = {

`frame_width : int;`	`(*`	The encoded frame width.	`*)`
`frame_height : int;`	`(*`	The encoded frame height.	`*)`
`picture_width : int;`	`(*`	The displayed picture width.	`*)`
`picture_height : int;`	`(*`	The displayed picture height.	`*)`
`picture_x : int;`	`(*`	The X offset of the displayed picture.	`*)`
`picture_y : int;`	`(*`	The Y offset of the displayed picture.	`*)`
`colorspace : colorspace;`	`(*`	The color space.	`*)`
`pixel_fmt : pixelformat;`	`(*`	The pixel format.	`*)`
`target_bitrate : int;`	`(*`	The target bit-rate in bits per second.	`*)`
`quality : int;`	`(*`	The target quality level.	`*)`
`keyframe_granule_shift : int;`	`(*`	The amount to shift to extract the last keyframe number from the granule position.	`*)`
`version_major : int;`
`version_minor : int;`
`version_subminor : int;`
`fps_numerator : int;`
`fps_denominator : int;`
`aspect_numerator : int;`
`aspect_denominator : int;`

}

Theora bitstream info.

val default_granule_shift : int

type data_buffer = (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

type yuv_buffer = {

	`y_width : int;`
	`y_height : int;`
	`y_stride : int;`
	`y : data_buffer;`
	`u_width : int;`
	`u_height : int;`
	`u_stride : int;`
	`u : data_buffer;`
	`v_width : int;`
	`v_height : int;`
	`v_stride : int;`
	`v : data_buffer;`

}

A YUV buffer for passing uncompressed frames to and from the codec. This holds a Y'CbCr frame in planar format. The CbCr planes can be subsampled and have their own separate dimensions and row stride offsets. Note that the strides may be negative in some configurations. For theora the width and height of the largest plane must be a multiple of 16. The actual meaningful picture size and offset are stored in the info structure; frames returned by the decoder may need to be cropped for display.

All samples are 8 bits. Within each plane samples are ordered by row from the top of the frame to the bottom. Within each row samples are ordered from left to right.

Encoding

module Encoder: sig .. end

module Decoder: sig .. end

module Skeleton: sig .. end