FLAC/file_encoder.h: file encoder interface

Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# FLAC/file_encoder.h: file encoder interface
[FLAC/_encoder.h: encoder interfaces]

This module contains the functions which implement the file encoder. More...

## Compounds

struct | FLAC__FileEncoder

## Typedefs

typedef void(* | FLAC__FileEncoderProgressCallback )(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data)

## Enumerations

enum

FLAC__FileEncoderState {
FLAC__FILE_ENCODER_OK = 0, FLAC__FILE_ENCODER_NO_FILENAME, FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR, FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
FLAC__FILE_ENCODER_ERROR_OPENING_FILE, FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR, FLAC__FILE_ENCODER_ALREADY_INITIALIZED, FLAC__FILE_ENCODER_UNINITIALIZED
}

## Functions

FLAC__FileEncoder * | FLAC__file_encoder_new ()
void | FLAC__file_encoder_delete (FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_set_verify (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_streamable_subset (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_do_mid_side_stereo (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_loose_mid_side_stereo (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_channels (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_bits_per_sample (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_sample_rate (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_blocksize (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_max_lpc_order (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_qlp_coeff_precision (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_do_qlp_coeff_prec_search (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_do_escape_coding (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_do_exhaustive_model_search (FLAC__FileEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__file_encoder_set_min_residual_partition_order (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_max_residual_partition_order (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_rice_parameter_search_dist (FLAC__FileEncoder *encoder, unsigned value)
FLAC__bool | FLAC__file_encoder_set_total_samples_estimate (FLAC__FileEncoder *encoder, FLAC__uint64 value)
FLAC__bool | FLAC__file_encoder_set_metadata (FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks)
FLAC__bool | FLAC__file_encoder_set_filename (FLAC__FileEncoder *encoder, const char *value)
FLAC__bool | FLAC__file_encoder_set_progress_callback (FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value)
FLAC__bool | FLAC__file_encoder_set_client_data (FLAC__FileEncoder *encoder, void *value)
FLAC__FileEncoderState | FLAC__file_encoder_get_state (const FLAC__FileEncoder *encoder)
FLAC__SeekableStreamEncoderState | FLAC__file_encoder_get_seekable_stream_encoder_state (const FLAC__FileEncoder *encoder)
FLAC__StreamEncoderState | FLAC__file_encoder_get_stream_encoder_state (const FLAC__FileEncoder *encoder)
FLAC__StreamDecoderState | FLAC__file_encoder_get_verify_decoder_state (const FLAC__FileEncoder *encoder)
const char * | FLAC__file_encoder_get_resolved_state_string (const FLAC__FileEncoder *encoder)
void | FLAC__file_encoder_get_verify_decoder_error_stats (const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got)
FLAC__bool | FLAC__file_encoder_get_verify (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_streamable_subset (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_do_mid_side_stereo (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_loose_mid_side_stereo (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_channels (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_bits_per_sample (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_sample_rate (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_blocksize (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_max_lpc_order (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_qlp_coeff_precision (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_do_qlp_coeff_prec_search (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_do_escape_coding (const FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_get_do_exhaustive_model_search (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_min_residual_partition_order (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_max_residual_partition_order (const FLAC__FileEncoder *encoder)
unsigned | FLAC__file_encoder_get_rice_parameter_search_dist (const FLAC__FileEncoder *encoder)
FLAC__uint64 | FLAC__file_encoder_get_total_samples_estimate (const FLAC__FileEncoder *encoder)
FLAC__FileEncoderState | FLAC__file_encoder_init (FLAC__FileEncoder *encoder)
void | FLAC__file_encoder_finish (FLAC__FileEncoder *encoder)
FLAC__bool | FLAC__file_encoder_process (FLAC__FileEncoder *encoder, const FLAC__int32 *const buffer[], unsigned samples)
FLAC__bool | FLAC__file_encoder_process_interleaved (FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples)

## Variables

const char *const | FLAC__FileEncoderStateString []

## Detailed Description

This module contains the functions which implement the file encoder.

The basic usage of this encoder is as follows:

- The program creates an instance of an encoder using FLAC__file_encoder_new().
- The program overrides the default settings using FLAC__file_encoder_set_*() functions.
- The program initializes the instance to validate the settings and prepare for encoding using FLAC__file_encoder_init().
- The program calls FLAC__file_encoder_process() or FLAC__file_encoder_process_interleaved() to encode data, which subsequently writes data to the output file.
- The program finishes the encoding with FLAC__file_encoder_finish(), which causes the encoder to encode any data still in its input pipe, rewind and write the STREAMINFO metadata to file, and finally reset the encoder to the uninitialized state.
- The instance may be used again or deleted with FLAC__file_encoder_delete().

The file encoder is a wrapper around the seekable stream encoder which supplies all callbacks internally; the user need specify only the filename.

Make sure to read the detailed description of the seekable stream encoder module since the stream encoder module since the file encoder inherits much of its behavior from them.

Note:
  The "set" functions may only be called when the encoder is in the state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but before FLAC__file_encoder_init(). If this is the case they will return `true`, otherwise `false`.

Note:
  FLAC__file_encoder_finish() resets all settings to the constructor defaults.

## Typedef Documentation

typedef void(* FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data)

Signature for the progress callback. See FLAC__file_encoder_set_progress_callback() for more info.

Parameters:

  encoder | The encoder instance calling the callback.
  bytes_written | Bytes written so far.
  samples_written | Samples written so far.
  frames_written | Frames written so far.
  total_frames_estimate | The estimate of the total number of frames to be written.
  client_data | The callee's client data set through FLAC__file_encoder_set_client_data().

## Enumeration Type Documentation

enum FLAC__FileEncoderState

State values for a FLAC__FileEncoder

The encoder's state can be obtained by calling FLAC__file_encoder_get_state().

Enumeration values:

  FLAC__FILE_ENCODER_OK | The encoder is in the normal OK state.
  FLAC__FILE_ENCODER_NO_FILENAME | FLAC__file_encoder_init() was called without first calling FLAC__file_encoder_set_filename().
  FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR | An error occurred in the underlying seekable stream encoder; check FLAC__file_encoder_get_seekable_stream_encoder_state().
  FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING | A fatal error occurred while writing to the encoded file.
  FLAC__FILE_ENCODER_ERROR_OPENING_FILE | An error occurred opening the output file for writing.
  FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR | Memory allocation failed.
  FLAC__FILE_ENCODER_ALREADY_INITIALIZED | FLAC__file_encoder_init() was called when the encoder was already initialized, usually because FLAC__file_encoder_finish() was not called.
  FLAC__FILE_ENCODER_UNINITIALIZED | The encoder is in the uninitialized state.

## Function Documentation

FLAC__FileEncoder* FLAC__file_encoder_new | ( |  | ) |

Create a new file encoder instance. The instance is created with default settings; see the individual FLAC__file_encoder_set_*() functions for each setting's default.

Return values:

  FLAC__FileEncoder | * `NULL` if there was an error allocating memory, else the new instance.

void FLAC__file_encoder_delete | ( | FLAC__FileEncoder * | encoder | ) |

Free an encoder instance. Deletes the object pointed to by encoder.

Parameters:

  encoder | A pointer to an existing encoder.

Assertions:

      encoder != NULL

FLAC__bool FLAC__file_encoder_set_verify | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_verify().

Default Value:
  `true`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_streamable_subset | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_streamable_subset().

Default Value:
  `true`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_do_mid_side_stereo().

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_channels | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_channels().

Default Value:
  `2`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_bits_per_sample | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_bits_per_sample().

Warning:
  Do not feed the encoder data that is wider than the value you set here or you will generate an invalid stream.

Default Value:
  `16`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_sample_rate | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_sample_rate().

Default Value:
  `44100`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_blocksize | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_blocksize().

Default Value:
  `1152`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_max_lpc_order | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_max_lpc_order().

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_qlp_coeff_precision().

Note:
  In the current implementation, qlp_coeff_precision + bits_per_sample must be less than 32.

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_do_escape_coding | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_do_escape_coding().

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_min_residual_partition_order | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_min_residual_partition_order().

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_max_residual_partition_order | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_max_residual_partition_order().

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist | ( | FLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_total_samples_estimate | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__uint64 | value
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_total_samples_estimate().

Default Value:
  `0`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_metadata | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__StreamMetadata ** | metadata,
|  | unsigned | num_blocks
| ) |

This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_set_metadata().

Default Value:
  `NULL`, 0

Parameters:

  encoder | An encoder instance to set.
  metadata | See above.
  num_blocks | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_filename | ( | FLAC__FileEncoder * | encoder,
|  | const char * | value
| ) |

Set the output file name encode to.

Note:
  The filename is mandatory and must be set before initialization.

Note:
  Unlike the FLAC__FileDecoder, the filename does not interpret "-" for `stdout`; writing to `stdout` is not relevant in the file encoder.

Default Value:
  `NULL`

Parameters:

  encoder | A encoder instance to set.
  value | The output file name.

Assertions:

      encoder != NULL

      value != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, or there was a memory allocation error, else `true`.

FLAC__bool FLAC__file_encoder_set_progress_callback | ( | FLAC__FileEncoder * | encoder,
|  | FLAC__FileEncoderProgressCallback | value
| ) |

Set the progress callback. The supplied function will be called when the encoder has finished writing a frame. The `total_frames_estimate` argument to the callback will be based on the value from FLAC__file_encoder_set_total_samples_estimate().

Note:
  Unlike most other callbacks, the progress callback is not mandatory and need not be set before initialization.

Default Value:
  `NULL`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

      value != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__bool FLAC__file_encoder_set_client_data | ( | FLAC__FileEncoder * | encoder,
|  | void * | value
| ) |

Set the client data to be passed back to callbacks. This value will be supplied to callbacks in their client_data argument.

Default Value:
  `NULL`

Parameters:

  encoder | An encoder instance to set.
  value | See above.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | `false` if the encoder is already initialized, else `true`.

FLAC__FileEncoderState FLAC__file_encoder_get_state | ( | const FLAC__FileEncoder * | encoder | ) |

Get the current encoder state.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__FileEncoderState | The current encoder state.

FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state | ( | const FLAC__FileEncoder * | encoder | ) |

Get the state of the underlying seekable stream encoder. Useful when the file encoder state is `FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__SeekableStreamEncoderState | The seekable stream encoder state.

FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state | ( | const FLAC__FileEncoder * | encoder | ) |

Get the state of the underlying stream encoder. Useful when the file encoder state is `FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__StreamEncoderState | The seekable stream encoder state.

FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state | ( | const FLAC__FileEncoder * | encoder | ) |

Get the state of the underlying stream encoder's verify decoder. Useful when the file encoder state is `FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR` and the stream encoder state is `FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__StreamDecoderState | The stream encoder state.

const char* FLAC__file_encoder_get_resolved_state_string | ( | const FLAC__FileEncoder * | encoder | ) |

Get the current encoder state as a C string. This version automatically resolves `FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` by getting the seekable stream encoder's state.

Parameters:

  encoder | A encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  const | char * The encoder state as a C string. Do not modify the contents.

void FLAC__file_encoder_get_verify_decoder_error_stats | ( | const FLAC__FileEncoder * | encoder,
|  | FLAC__uint64 * | absolute_sample,
|  | unsigned * | frame_number,
|  | unsigned * | channel,
|  | unsigned * | sample,
|  | FLAC__int32 * | expected,
|  | FLAC__int32 * | got
| ) |

Get relevant values about the nature of a verify decoder error. Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(). Useful when the file encoder state is `FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR` and the stream encoder state is `FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.
  absolute_sample | The absolute sample number of the mismatch.
  frame_number | The number of the frame in which the mismatch occurred.
  channel | The channel in which the mismatch occurred.
  sample | The number of the sample (relative to the frame) in which the mismatch occurred.
  expected | The expected value for the sample in question.
  got | The actual value returned by the decoder.

Assertions:

      encoder != NULL

FLAC__bool FLAC__file_encoder_get_verify | ( | const FLAC__FileEncoder * | encoder | ) |

Get the "verify" flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_verify().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_verify().

FLAC__bool FLAC__file_encoder_get_streamable_subset | ( | const FLAC__FileEncoder * | encoder | ) |

Get the "streamable subset" flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_streamable_subset().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_streamable_subset().

FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo | ( | const FLAC__FileEncoder * | encoder | ) |

Get the "mid/side stereo coding" flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_do_mid_side_stereo().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_get_do_mid_side_stereo().

FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo | ( | const FLAC__FileEncoder * | encoder | ) |

Get the "adaptive mid/side switching" flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_loose_mid_side_stereo().

unsigned FLAC__file_encoder_get_channels | ( | const FLAC__FileEncoder * | encoder | ) |

Get the number of input channels being processed. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_channels().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_channels().

unsigned FLAC__file_encoder_get_bits_per_sample | ( | const FLAC__FileEncoder * | encoder | ) |

Get the input sample resolution setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_bits_per_sample().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_bits_per_sample().

unsigned FLAC__file_encoder_get_sample_rate | ( | const FLAC__FileEncoder * | encoder | ) |

Get the input sample rate setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_sample_rate().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_sample_rate().

unsigned FLAC__file_encoder_get_blocksize | ( | const FLAC__FileEncoder * | encoder | ) |

Get the blocksize setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_blocksize().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_blocksize().

unsigned FLAC__file_encoder_get_max_lpc_order | ( | const FLAC__FileEncoder * | encoder | ) |

Get the maximum LPC order setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_max_lpc_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_max_lpc_order().

unsigned FLAC__file_encoder_get_qlp_coeff_precision | ( | const FLAC__FileEncoder * | encoder | ) |

Get the quantized linear predictor coefficient precision setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_qlp_coeff_precision().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_qlp_coeff_precision().

FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search | ( | const FLAC__FileEncoder * | encoder | ) |

Get the qlp coefficient precision search flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_do_qlp_coeff_prec_search().

FLAC__bool FLAC__file_encoder_get_do_escape_coding | ( | const FLAC__FileEncoder * | encoder | ) |

Get the "escape coding" flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_do_escape_coding().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_do_escape_coding().

FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search | ( | const FLAC__FileEncoder * | encoder | ) |

Get the exhaustive model search flag. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__file_encoder_set_do_exhaustive_model_search().

unsigned FLAC__file_encoder_get_min_residual_partition_order | ( | const FLAC__FileEncoder * | encoder | ) |

Get the minimum residual partition order setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_min_residual_partition_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_min_residual_partition_order().

unsigned FLAC__file_encoder_get_max_residual_partition_order | ( | const FLAC__FileEncoder * | encoder | ) |

Get maximum residual partition order setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_max_residual_partition_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_max_residual_partition_order().

unsigned FLAC__file_encoder_get_rice_parameter_search_dist | ( | const FLAC__FileEncoder * | encoder | ) |

Get the Rice parameter search distance setting. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_rice_parameter_search_dist().

FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate | ( | const FLAC__FileEncoder * | encoder | ) |

Get the previously set estimate of the total samples to be encoded. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_get_total_samples_estimate().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__uint64 | See FLAC__file_encoder_set_total_samples_estimate().

FLAC__FileEncoderState FLAC__file_encoder_init | ( | FLAC__FileEncoder * | encoder | ) |

Initialize the encoder instance. Should be called after FLAC__file_encoder_new() and FLAC__file_encoder_set_*() but before FLAC__file_encoder_process() or FLAC__file_encoder_process_interleaved(). Will set and return the encoder state, which will be FLAC__FILE_ENCODER_OK if initialization succeeded.

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

Return values:

  FLAC__FileEncoderState | `FLAC__FILE_ENCODER_OK` if initialization was successful; see FLAC__FileEncoderState for the meanings of other return values.

void FLAC__file_encoder_finish | ( | FLAC__FileEncoder * | encoder | ) |

Finish the encoding process. Flushes the encoding buffer, releases resources, resets the encoder settings to their defaults, and returns the encoder state to FLAC__FILE_ENCODER_UNINITIALIZED.

In the event of a prematurely-terminated encode, it is not strictly necessary to call this immediately before FLAC__file_encoder_delete() but it is good practice to match every FLAC__file_encoder_init() with a FLAC__file_encoder_finish().

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

FLAC__bool FLAC__file_encoder_process | ( | FLAC__FileEncoder * | encoder,
|  | const FLAC__int32 *const | buffer[],
|  | unsigned | samples
| ) |

Submit data for encoding. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_process().

Parameters:

  encoder | An initialized encoder instance in the OK state.
  buffer | An array of pointers to each channel's signal.
  samples | The number of samples in one channel.

Assertions:

      encoder != NULL

      FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK

Return values:

  FLAC__bool | `true` if successful, else `false`; in this case, check the encoder state with FLAC__file_encoder_get_state() to see what went wrong.

FLAC__bool FLAC__file_encoder_process_interleaved | ( | FLAC__FileEncoder * | encoder,
|  | const FLAC__int32 | buffer[],
|  | unsigned | samples
| ) |

Submit data for encoding. This is inherited from FLAC__SeekableStreamEncoder; see FLAC__seekable_stream_encoder_process_interleaved().

Parameters:

  encoder | An initialized encoder instance in the OK state.
  buffer | An array of channel-interleaved data (see above).
  samples | The number of samples in one channel, the same as for FLAC__file_encoder_process(). For example, if encoding two channels, `1000` samples corresponds to a buffer of 2000 values.

Assertions:

      encoder != NULL

      FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK

Return values:

  FLAC__bool | `true` if successful, else `false`; in this case, check the encoder state with FLAC__file_encoder_get_state() to see what went wrong.

## Variable Documentation

const char* const FLAC__FileEncoderStateString[]

| Maps a FLAC__FileEncoderState to a C string. Using a FLAC__FileEncoderState as the index to this array will give the string equivalent. The contents should not be modified.