ogg

Bindings to libogg
back to documentation root
package ogg
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library ogg.decoder
Module Ogg_decoder

This module provides a functional abstract API to * decode and seek in Ogg streams. * * Decoders are also provided in ocaml-vorbis, * ocaml-speex, ocaml-schroedinger, ocaml-flac and * ocaml-theora. * * Functions in this module are not thread safe!

Decoding

Types

type t

Type of an ogg stream decoder.

type callbacks = {
read : bytes -> int -> int -> int;
seek : ( int -> int ) option;
tell : ( unit -> int ) option;
}

Type for callbacks used to acess encoded data.

type track =
| Audio_track of string * nativeint
| Video_track of string * nativeint

Type for a decodable track. * First element is a string describing * the decoder used to decode the track. * Second element is the serial number * associated to the Ogg.Stream.stream logical * stream used to pull data packets for that * track.

type standard_tracks = {
mutable audio_track : track option;
mutable video_track : track option;
}

Type for standard tracks (see get_standard_tracks below).

type metadata = string * (string * string) list

Type for metadata. First element * is a string describing the vendor, second * element is a list of metadata of the form: * (label,value).

type audio_info = {
channels : int;
sample_rate : int;
}

Type for audio information.

type audio_data = float array array

Type for audio data.

type audio_ba_data = ( float, Bigarray.float32_elt, Bigarray.c_layout ) Bigarray.Array1.t array

Type of a video plane.

type video_format =
| Yuvj_420
| Yuvj_422
| Yuvj_444

Supported video formats.

type video_info = {
fps_numerator : int;
fps_denominator : int;
width : int;
height : int;
}
type video_data = {
format : video_format;
frame_width : int;
frame_height : int;
y_stride : int;(*

Length, in bytes, per line

*)
uv_stride : int;(*

Length, in bytes, per line

*)
y : video_plane;(*

luminance data

*)
u : video_plane;(*

Cb data

*)
v : video_plane;(*

Cr data

*)
}

Type for video data.

Exceptions

exception Invalid_stream
exception Not_available
exception End_of_stream

Initialization functions

val init : ?log:( string -> unit ) -> callbacks -> t

Initiate a decoder with the given callbacks. * log is an optional functioned used to * return logged messages during the deocding * process.

val init_from_file : ?log:( string -> unit ) -> string -> t * Unix.file_descr

Initiate a decoder from a given file name.

val init_from_fd : ?log:( string -> unit ) -> Unix.file_descr -> t

Initate a decoder from a given Unix.file_descriptor

val get_ogg_sync : t -> Ogg.Sync.t

Get the Ogg.Sync handler associated to * the decoder. Use only if know what you are doing.

val reset : t -> unit

Reset encoder, try to parse a new sequentialized stream. * To use when end_of_stream has been reached.

val abort : t -> unit

Consume all remaining pages of the current * stream. This function may be called to skip * a sequentialized stream but it may be quite * CPU intensive if there are many pages remaining.. * * eos dec is true after this call.

val eos : t -> bool

true if the decoder has reached the end of each * logical streams and all data has been decoded. * * If you do not plan on decoding some data, * you should use drop_track to indicate it * to the decoder. Otherwise, eos will return * false until you have decoded all data.

val get_tracks : t -> track list

Get all decodable tracks available.

val get_standard_tracks : t -> standard_tracks

Get the first available audio and * video tracks and drop the other one.

val update_standard_tracks : t -> standard_tracks -> unit

Update a given record of standard tracks. You should * use this after a reset to update the standard tracks * with the newly created tracks.

val drop_track : t -> track -> unit

Remove all tracks of the given type.

Information functions

val audio_info : t -> track -> audio_info * metadata

Get informations about the * audio track.

val can_decode_ba : t -> track -> bool

true if the decoder can decoder to bigarray data.

val video_info : t -> track -> video_info * metadata

Get informations about the * video track.

val sample_rate : t -> track -> int * int

Get the sample_rate of the track * of that type. Returns a pair (numerator,denominator).

val get_track_position : t -> track -> float

Get track absolute position.

val get_position : t -> float

Get absolute position in the stream.

Seeking functions

val can_seek : t -> bool

Returns true if the decoder * can be used with the seek function.

val seek : ?relative:bool -> t -> float -> float

Seek to an absolute or relative position in seconds. * * Raises Not_available if seeking is * not possible. * * Raises End_of_stream if the end of * current stream has been reached while * seeking. You may call reset in this * situation to see if there is a new seqentialized * stream available. * * Returns the time actually reached, either in * relative time or absolute time.

Decoding functions

val decode_audio : t -> track -> ( audio_data -> unit ) -> unit

Decode audio data, if possible. * Decoded data is passed to the second argument. * * Raises End_of_stream if all stream have ended. * In this case, you can try reset to see if there is a * new sequentialized stream.

val decode_audio_ba : t -> track -> ( audio_ba_data -> unit ) -> unit

Decode audio data, if possible. * Decoded data is passed to the second argument. * * Raises End_of_stream if all stream have ended. * In this case, you can try reset to see if there is a * new sequentialized stream.

val decode_video : t -> track -> ( video_data -> unit ) -> unit

Decode video data, if possible. * Decoded data is passed to the second argument. * * Raises End_of_stream if all streams have ended. * In this case, you can try reset to see if there is a * new sequentialized stream.

Implementing decoders

Types

type ('a, 'b) decoder = {
name : string;
info : unit -> 'a * metadata;
decode : ( 'b -> unit ) -> unit;
restart : Ogg.Stream.stream -> unit;
samples_of_granulepos : Int64.t -> Int64.t;
}

Generic type for a decoder.

type decoders =
| Video of ( video_info, video_data ) decoder
| Audio of ( audio_info, audio_data ) decoder
| Audio_ba of ( audio_info, audio_ba_data ) decoder
| Audio_both of ( audio_info, audio_data ) decoder * ( audio_info, audio_ba_data ) decoder
| Unknown

Type for a generic logical stream decoder.

type register_decoder = ( Ogg.Stream.packet -> bool ) * ( Ogg.Stream.stream -> decoders )

Type used to register a new decoder. First * element is a function used to check if the initial Ogg.Stream.packet * of an Ogg.Stream.stream matches the format decodable by this decoder. * Second element is a function that instanciates the actual decoder * using the initial Ogg.Stream.stream used to pull data packets for the * decoder.

Functions

val ogg_decoders : ( string, register_decoder ) Hashtbl.t

Register a new decoder.