The
Flac module that provides functionality
for encoding WAV/PCM audio to Flac and decoding Flac to PCM.Methods
-
create_libflac_decoder(is_verify){number}
-
Create a decoder.
Name Type Description is_verifyboolean optional enable/disable checksum verification during decoding
DEFAULT: trueReturns:
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_ratenumber the sample rate of the input PCM data channelsnumber the number of channels of the input PCM data bpsnumber bits per sample of the input PCM data compression_levelnumber the desired Flac compression level: [0, 8] total_samplesnumber 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_verifyboolean optional OPTIONAL enable/disable checksum verification during encoding
DEFAULT: true
NOTE: this argument is positional (i.e. total_samples must also be given)block_sizenumber 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 decodernumber 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 decodernumber 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 decodernumber the ID of the decoder instance Returns:
if MD5 verification is enabled
-
FLAC__stream_decoder_get_state(decoder){number}
-
Name Type Description decodernumber 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 encodernumber 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 decodernumber 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 decodernumber 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 decodernumber 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 encodernumber the ID of the encoder instance -
FLAC__stream_encoder_finish(encoder){boolean}
-
Finish the encoding process.
Name Type Description encodernumber 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 encodernumber 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 encodernumber the ID of the encoder instance bufferTypedArray the audio data in a typed array with signed integers (and size according to the set bits-per-sample setting) num_of_samplesnumber 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 decodernumber the ID of the decoder instance read_callback_fnfunction 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_fnfunction 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_fnfunction 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_fnfunction 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 encodernumber the ID of the encoder instance write_callback_fnfunction 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_fnfunction 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)
-
isReady(){boolean}
-
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... }; }