Up  

Module Theora


module Theora: sig .. end
Functions for encoding theora files using libtheora.


Author(s): Samuel Mimram


Exceptions


exception Internal_error
General failure.

Library encountered invalid internal data.

exception Invalid_data
An unhandled error happened.
exception Unknown_error of int

General functions


val version_string : unit -> string
Retrieve a human-readable string to identify the encoder vendor and version.
val version_number : unit -> int * int * int
Retrive the major, minor and sub version numbers of the encoder.

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 = {
   width : int; (*encoded frame width (should be divisible by 16)*)
   height : int; (*encoded frame height (should be divisible by 16)*)
   frame_width : int; (*display frame width*)
   frame_height : int; (*display frame height*)
   offset_x : int; (*horizontal offset of the displayed frame*)
   offset_y : int; (*vertical offset of the displayed frame*)
   fps_numerator : int; (*frame rate numerator*)
   fps_denominator : int; (*frame rate denominator*)
   aspect_numerator : int; (*pixel aspect ratio numerator*)
   aspect_denominator : int; (*pixel aspect ratio denominator*)
   colorspace : colorspace; (*colorspace*)
   target_bitrate : int; (*nominal bitrate in bits per second (between 45kbps and 2000kbps)*)
   quality : int; (*Nominal quality setting, (between 0 and 63)*)
   quick_p : bool; (*Quick encode/decode*)
   version_major : int;
   version_minor : int;
   version_subminor : int;
   dropframes_p : bool;
   keyframe_auto_p : bool;
   keyframe_frequency : int;
   keyframe_frequency_force : int; (*also used for decode init to get granpos shift correct*)
   keyframe_data_target_bitrate : int;
   keyframe_auto_threshold : int;
   keyframe_mindistance : int;
   noise_sensitivity : int;
   sharpness : int;
   pixelformat : pixelformat; (*chroma subsampling mode to expect*)
}
Theora bitstream info. Contains the basic playback parameters for a stream, corresponds to the initial 'info' header packet.

Encoded theora frames must be a multiple of 16 is size; this is what the width and height members represent. To handle other sizes, a crop rectangle is specified in frame_height and frame_width, offset_x and offset_y. The offset and size should still be a multiple of 2 to avoid chroma sampling shifts. Offset values in this structure are measured from the upper left of the image.

Frame rate, in frames per second, is stored as a rational fraction. So is the aspect ratio. Note that this refers to the aspect ratio of the frame pixels, not of the overall frame itself.

See the example code for use of the other parameters and good default settings for the encoder parameters.

This type is private since it needs private theora parameters. Une the new_info function to create an empty one.

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

type yuv_buffer = {
   y_width : int; (*Width of the Y' luminance plane*)
   y_height : int; (*Height of the luminance plane*)
   y_stride : int; (*Lenth, in bytes, per line*)
   uv_width : int; (*Width of the Cb and Cr chroma planes*)
   uv_height : int; (*Height of the chroma planes*)
   uv_stride : int; (*Length, in bytes, per line*)
   y : data_buffer; (*luminance data*)
   u : data_buffer; (*Cb data*)
   v : data_buffer; (*Cr data*)
}
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