Module Flac.Decoder

module Decoder: sig .. end

Decode native FLAC data

Usage

A typical use of the FLAC decoder is the following:

 (* Raise this when streams has ended. *)
 exception End_of_stream
 (* Define a read function *)
 let input = (..a function of type read..) in
 (* Define a write function *)
 let output = (..a function of type write..) in
 (* Create callbacks *)
 let callbacks = Flac.Decoder.get_callbacks input write in
 (* Create an unitialized decoder *)
 let decoder = Flac.Decoder.create in
 (* Initialize decoder *)
 let decoder,info,comments = Flac.Decoder.init decoder in
 (..do something with info and comments..)
 (* Decode data *)
 match Flac.Decoder.state decoder c with
   | `Search_for_metadata
   | `Read_metadata
   | `Search_for_frame_sync
   | `Read_frame ->
         Flac.Decoder.process decoder callbacks
   | _ -> raise End_of_stream

Some remarks:

Exceptions raised by callbacks should be treated as fatal errors. The dehaviour of the flac library after being interrupted by an exception is unknown. The only notable exception is Ogg/flac decoding, where the read callback raises Ogg.Not_enough_data.
The state of the decoder should be checked prior to calling process. Termination may not be detected nor raise an exception so it is the caller's responsibility to check on this.
See FLAC documentation for the information on the callbacks.
The variant type for decoder and callbacks is used to make sure that different type of decoders (generic, file, ogg) are only used with the same type of callbacks.

Types

type 'a dec

Type of an uninitialized decoder.

type 'a t

Type of an initialized decoder.

type write = float array array -> unit

Type of a write callback.

type read = int -> string * int

Type of a read callback.

type 'a callbacks

Type of a collection of callbacks.

type generic

Generic variant type for callbacks and decoder.

type info = {

	`sample_rate : int;`
	`channels : int;`
	`bits_per_sample : int;`
	`total_samples : int64;`
	`md5sum : string;`

}

Info about decoded FLAC data.

type comments = string * (string * string) list

(Vorbis) comments of decoded FLAC data.

type state = [ `Aborted
       | `End_of_stream
       | `Memory_allocation_error
       | `Ogg_error
       | `Read_frame
       | `Read_metadata
       | `Search_for_frame_sync
       | `Search_for_metadata
       | `Seek_error
       | `Uninitialized ]

Possible states of a decoder.

Exceptions

exception Lost_sync

An error in the stream caused the decoder to lose synchronization.

exception Bad_header

The decoder encountered a corrupted frame header.

exception Frame_crc_mismatch

The frame's data did not match the CRC in the footer.

exception Unparseable_stream

The decoder encountered reserved fields in use in the stream.

exception Not_flac

Raised if trying to decode a stream that is not flac.

Functions

val get_callbacks : ?seek:(int64 -> unit) ->
       ?tell:(unit -> int64) ->
       ?length:(unit -> int64) ->
       ?eof:(unit -> bool) ->
       read ->
       write -> generic callbacks

Create a set of callbacks.

val create : 'a callbacks -> 'a dec

Create an uninitialized decoder.

val init : 'a dec ->
       'a callbacks ->
       'a t * info * comments option

Initialize a decoder. The decoder will be used to decode all metadata. Initial audio data shall be immediatly available after this call.

val process : 'a t -> 'a callbacks -> unit

Decode one frame of audio data.

val seek : 'a t -> 'a callbacks -> Int64.t -> bool

Flush the input and seek to an absolute sample. Decoding will resume at the given sample. Note that because of this, the next write callback may contain a partial block. The client must support seeking the input or this function will fail and return false. Furthermore, if the decoder state is `Seek_error then the decoder must be flushed or reset before decoding can continue.

val flush : 'a t -> 'a callbacks -> bool

Flush the stream input. The decoder's input buffer will be cleared and the state set to `Search_for_frame_sync. This will also turn off MD5 checking.

val reset : 'a t -> 'a callbacks -> bool

Reset the decoding process. The decoder's input buffer will be cleared and the state set to `Search_for_metadata. MD5 checking will be restored to its original setting.

If the decoder is seekable, the decoder will also attempt to seek to the beginning of the stream. If this rewind fails, this function will return false. It follows that reset cannot be used when decoding from stdin.

If the decoder is not seekable (i.e. no seek callback was provided) it is the duty of the client to start feeding data from the beginning of the stream on the next process.

val state : 'a t -> 'a callbacks -> state

Get the state of a decoder.

Convenience

val to_s16le : float array array -> string

Convert an audio array to a S16LE string for decoding FLAC to WAV and raw PCM

module File: sig .. end

Local file decoding.