Previous  Up  

Module Ogg_demuxer

module Ogg_demuxer: sig .. end

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 = {
   read : int -> string * 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 video_plane = (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

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; (*

Width of the Y' luminance plane

*)
   height : int; (*

Height of the luminance plane

*)
}

Type for video information.

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 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_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; (*

This function is called after seeking to notify the decoder of the new Ogg.Stream.stream that is should use to pull data packets.

*)
   samples_of_granulepos : Stdlib.Int64.t -> Stdlib.Int64.t;
}

Generic type for a decoder.

type decoders =
| Video of (video_info, video_data) decoder
| Audio of (audio_info, audio_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) Stdlib.Hashtbl.t

Register a new decoder.