Namespace: Flac

Flac

The Flac module that provides functionality for encoding WAV/PCM audio to Flac and decoding Flac to PCM.
See:

Methods

create_libflac_decoder(is_verify){number}

Create a decoder.
Name Type Description
is_verify boolean optional enable/disable checksum verification during decoding
DEFAULT: true
Returns:
ID of the created decoder instance (or 0, if there was an error)

create_libflac_encoder(sample_rate, channels, bps, compression_level, total_samples, is_verify, block_size){number}

Create an encoder.
Name Type Description
sample_rate number the sample rate of the input PCM data
channels number the number of channels of the input PCM data
bps number bits per sample of the input PCM data
compression_level number the desired Flac compression level: [0, 8]
total_samples number optional OPTIONAL the number of total samples of the input PCM data:
Sets an estimate of the total samples that will be encoded. This is merely an estimate and may be set to 0 if unknown. This value will be written to the STREAMINFO block before encoding, and can remove the need for the caller to rewrite the value later if the value is known before encoding.
If specified, the it will be written into metadata of the FLAC header.
DEFAULT: 0 (i.e. unknown number of samples)
is_verify boolean optional OPTIONAL enable/disable checksum verification during encoding
DEFAULT: true
NOTE: this argument is positional (i.e. total_samples must also be given)
block_size number optional OPTIONAL the number of samples to use per frame.
DEFAULT: 0 (i.e. encoder sets block size automatically) NOTE: this argument is positional (i.e. total_samples and is_verify must also be given)
Returns:
ID of the created encoder instance (or 0, if there was an error)

FLAC__stream_decoder_delete(decoder)

Delete the decoder instance, and free up its resources.
Name Type Description
decoder number the ID of the decoder instance

FLAC__stream_decoder_finish(decoder){boolean}

Finish the decoding process. The decoder can be reused, after initializing it again.
Name Type Description
decoder number the ID of the decoder instance
Returns:
if MD5 checking is on AND a STREAMINFO block was available AND the MD5 signature in the STREAMINFO block was non-zero AND the signature does not match the one computed by the decoder; else true.

FLAC__stream_decoder_get_md5_checking(decoder){boolean}

Get if MD5 verification is enabled for decoder
Name Type Description
decoder number the ID of the decoder instance
Returns:
if MD5 verification is enabled

FLAC__stream_decoder_get_state(decoder){number}

Name Type Description
decoder number the ID of the decoder instance
Returns:
decoder state:
0	FLAC__STREAM_DECODER_SEARCH_FOR_METADATA:		The decoder is ready to search for metadata
1	FLAC__STREAM_DECODER_READ_METADATA:				The decoder is ready to or is in the process of reading metadata
2	FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC:		The decoder is ready to or is in the process of searching for the frame sync code
3	FLAC__STREAM_DECODER_READ_FRAME:				The decoder is ready to or is in the process of reading a frame
4	FLAC__STREAM_DECODER_END_OF_STREAM:				The decoder has reached the end of the stream
5	FLAC__STREAM_DECODER_OGG_ERROR:					An error occurred in the underlying Ogg layer
6	FLAC__STREAM_DECODER_SEEK_ERROR:				An error occurred while seeking. The decoder must be flushed with FLAC__stream_decoder_flush() or reset with FLAC__stream_decoder_reset() before decoding can continue
7	FLAC__STREAM_DECODER_ABORTED:					The decoder was aborted by the read callback
8	FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR:	An error occurred allocating memory. The decoder is in an invalid state and can no longer be used
9	FLAC__STREAM_DECODER_UNINITIALIZED:				The decoder is in the uninitialized state; one of the FLAC__stream_decoder_init_*() functions must be called before samples can be processed.

FLAC__stream_decoder_process_single(encoder){boolean}

Decodes a single frame. To check decoding progress, use #FLAC__stream_decoder_get_state().
Name Type Description
encoder number the ID of the encoder instance
Returns:
if an error occurred

FLAC__stream_decoder_process_until_end_of_metadata(decoder){boolean}

Decodes data until end of metadata.
Name Type Description
decoder number the ID of the decoder instance
Returns:
if any fatal read, write, or memory allocation error occurred (meaning decoding must stop), else true.

FLAC__stream_decoder_process_until_end_of_stream(decoder){boolean}

Decodes data until end of stream.
Name Type Description
decoder number the ID of the decoder instance
Returns:
if an error occurred

FLAC__stream_decoder_reset(decoder){boolean}

Reset the decoder for reuse.
Name Type Description
decoder number the ID of the decoder instance
Returns:
if successful

FLAC__stream_encoder_delete(encoder)

Delete the encoder instance, and free up its resources.
Name Type Description
encoder number the ID of the encoder instance

FLAC__stream_encoder_finish(encoder){boolean}

Finish the encoding process.
Name Type Description
encoder number the ID of the encoder instance
Returns:
if an error occurred processing the last frame; or if verify mode is set, there was a verify mismatch; else true. If false, caller should check the state with FLAC__stream_encoder_get_state() for more information about the error.

FLAC__stream_encoder_get_state(encoder){number}

Name Type Description
encoder number the ID of the encoder instance
Returns:
encoder state:
0	FLAC__STREAM_ENCODER_OK								The encoder is in the normal OK state and samples can be processed.
1	FLAC__STREAM_ENCODER_UNINITIALIZED					The encoder is in the uninitialized state; one of the FLAC__stream_encoder_init_*() functions must be called before samples can be processed.
2	FLAC__STREAM_ENCODER_OGG_ERROR						An error occurred in the underlying Ogg layer.
3	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR			An error occurred in the underlying verify stream decoder; check FLAC__stream_encoder_get_verify_decoder_state().
4	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA	The verify decoder detected a mismatch between the original audio signal and the decoded audio signal.
5	FLAC__STREAM_ENCODER_CLIENT_ERROR					One of the callbacks returned a fatal error.
6	FLAC__STREAM_ENCODER_IO_ERROR						An I/O error occurred while opening/reading/writing a file. Check errno.
7	FLAC__STREAM_ENCODER_FRAMING_ERROR					An error occurred while writing the stream; usually, the write_callback returned an error.
8	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR		Memory allocation failed.

FLAC__stream_encoder_process_interleaved(encoder, buffer, num_of_samples){boolean}

Encode / submit data for encoding. This version allows you to supply the input data where the channels are interleaved into a single array (i.e. channel0_sample0, channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). The samples need not be block-aligned but they must be sample-aligned, i.e. the first value should be channel0_sample0 and the last value channelN_sampleM. Each sample should be a signed integer, right-justified to the resolution set by bits-per-sample. For example, if the resolution is 16 bits per sample, the samples should all be in the range [-32768,32767]. For applications where channel order is important, channels must follow the order as described in the frame header.
Name Type Description
encoder number the ID of the encoder instance
buffer TypedArray the audio data in a typed array with signed integers (and size according to the set bits-per-sample setting)
num_of_samples number the number of samples in buffer
Returns:
if successful, else false; in this case, check the encoder state with FLAC__stream_encoder_get_state() to see what went wrong.

FLAC__stream_encoder_set_blocksize()

FLAC__stream_encoder_set_compression_level()

FLAC__stream_encoder_set_verify()

init_decoder_stream(decoder, read_callback_fn, write_callback_fn, error_callback_fn, metadata_callback_fn)

Initialize the decoder.
Name Type Description
decoder number the ID of the decoder instance
read_callback_fn function the callback for reading the Flac data that should get decoded:
				read_callback_fn(numberOfBytes: Number) : {buffer: ArrayBuffer, readDataLength: number, error: boolean}
				
				numberOfBytes: the maximal number of bytes that the read callback can return

				RETURN.buffer: a TypedArray (e.g. Uint8Array) with the read data
				RETURN.readDataLength: the number of read data bytes. A number of 0 (zero) indicates that the end-of-stream is reached.
				RETURN.error: TRUE indicates that an error occurs (decoding will be aborted)
				
write_callback_fn function the callback for writing the decoded data:
				write_callback_fn(data: TypedArray, frameInfo: Metadata)

				data: the decoded PCM data as Uint8Array
				frameInfo: the metadata information for the decoded data with
				frameInfo.blocksize (Number): the block size (bytes)
				frameInfo.sampleRate (Number): the sample rate (Hz)
				frameInfo.channels (Number): number of channels
				frameInfo.bitsPerSample (Number): bits per sample
				frameInfo.number (Number):  the number of the decoded sample
				frameInfo.crc (String): the MD5 checksum for the decoded data (if validation is active)
				
error_callback_fn function optional OPTIONAL the error callback:
				error_callback_fn(errorCode: Number, errorMessage: String)
				
				where
					FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC        		An error in the stream caused the decoder to lose synchronization.
					FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER       		The decoder encountered a corrupted frame header.
					FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH   	The frame's data did not match the CRC in the footer.
					FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM   	The decoder encountered reserved fields in use in the stream.
				
metadata_callback_fn function optional OPTIONAL callback for receiving the metadata of the decoded PCM data:
				metadata_callback_fn(metadata: StreamMetadata)

				metadata.min_blocksize (Number): the minimal block size (bytes)
				metadata.max_blocksize (Number): the maximal block size (bytes) 
				metadata.min_framesize (Number): the minimal frame size (bytes)
				metadata.max_framesize (Number): the maximal frame size (bytes)
				metadata.sampleRate (Number): the sample rate (Hz)
				metadata.channels (Number): the number of channels
				metadata.bitsPerSample (Number): bits per sample
				metadata.total_samples (Number): the total number of (decoded) samples
				metadata.md5sum (String): the MD5 checksum for the decoded data (if validation is active)
				

init_encoder_stream(encoder, write_callback_fn, metadata_callback_fn)

Initialize the decoder.
Name Type Description
encoder number the ID of the encoder instance
write_callback_fn function the callback for writing the encoded Flac data:
				write_callback_fn(data: Uint8Array, numberOfBytes: Number, samples: Number, currentFrame: Number)

				data: the encoded Flac data
				numberOfBytes: the number of bytes in data
				samples: the number of samples encoded in data
				currentFrame: the number of the (current) encoded frame in data
				
metadata_callback_fn function optional OPTIONAL the callback for the metadata of the encoded Flac data:
				metadata_callback_fn(metadata: StreamMetadata)

				metadata.min_blocksize (Number): the minimal block size (bytes)
				metadata.max_blocksize (Number): the maximal block size (bytes) 
				metadata.min_framesize (Number): the minimal frame size (bytes)
				metadata.max_framesize (Number): the maximal frame size (bytes)
				metadata.sampleRate (Number): the sample rate (Hz)
				metadata.channels (Number): the number of channels
				metadata.bitsPerSample (Number): bits per sample
				metadata.total_samples (Number): the total number of (decoded) samples
				metadata.md5sum (String): the MD5 checksum for the decoded data (if validation is active)
				
Returns if Flac has been initialized / is ready to be used.
Returns:
if Flac is ready to be used
Callback that gets called, when asynchronous initialization has finished. Note that this function is not called again, after #isReady() is TRUE
Example
if(!Flac.isReady()){
   Flac.onready = function(){
      //gets executed when library becomes ready...
   };
 }