package ogg

  1. Overview
  2. Docs
package ogg
Legend:
Library
Module
Module type
Parameter
Class
Class type

Ogg stream demuxer

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 = {
  1. read : bytes -> int -> int -> int;
  2. seek : (int -> int) option;
  3. tell : (unit -> int) option;
}

Type for callbacks used to acess encoded data.

type track =
  1. | Audio_track of string * nativeint
  2. | 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 = {
  1. mutable audio_track : track option;
  2. 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 = {
  1. channels : int;
  2. sample_rate : int;
}

Type for audio information.

type audio_data = float array array

Type for audio data.

type audio_ba_data = (float, Stdlib.Bigarray.float32_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t array
type video_plane = (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t

Type of a video plane.

type video_format =
  1. | Yuvj_420
  2. | Yuvj_422
  3. | Yuvj_444

Supported video formats.

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

    Length, in bytes, per line

    *)
  5. uv_stride : int;
    (*

    Length, in bytes, per line

    *)
  6. y : video_plane;
    (*

    luminance data

    *)
  7. u : video_plane;
    (*

    Cb data

    *)
  8. 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 = {
  1. name : string;
  2. info : unit -> 'a * metadata;
  3. decode : ('b -> unit) -> unit;
  4. restart : Ogg.Stream.stream -> unit;
  5. samples_of_granulepos : Stdlib.Int64.t -> Stdlib.Int64.t;
}

Generic type for a decoder.

type decoders =
  1. | Video of (video_info, video_data) decoder
  2. | Audio of (audio_info, audio_data) decoder
  3. | Audio_ba of (audio_info, audio_ba_data) decoder
  4. | Audio_both of (audio_info, audio_data) decoder * (audio_info, audio_ba_data) decoder
  5. | 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) Stdlib.Hashtbl.t

Register a new decoder.