OggFLAC/file_encoder.h: file encoder interface

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

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

This module contains the functions which implement the file encoder. Unlink the Ogg stream and seekable stream encoders, which derive from their FLAC counterparts, the Ogg file encoder is derived from the Ogg seekable stream encoder. More...

## Compounds

struct | OggFLAC__FileEncoder

## Typedefs

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

## Enumerations

enum

OggFLAC__FileEncoderState {
OggFLAC__FILE_ENCODER_OK = 0, OggFLAC__FILE_ENCODER_NO_FILENAME, OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR, OggFLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
OggFLAC__FILE_ENCODER_ERROR_OPENING_FILE, OggFLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR, OggFLAC__FILE_ENCODER_ALREADY_INITIALIZED, OggFLAC__FILE_ENCODER_UNINITIALIZED
}

## Functions

OggFLAC_API OggFLAC__FileEncoder * | OggFLAC__file_encoder_new ()
OggFLAC_API void | OggFLAC__file_encoder_delete (OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_serial_number (OggFLAC__FileEncoder *encoder, long serial_number)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_verify (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_streamable_subset (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_do_mid_side_stereo (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_loose_mid_side_stereo (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_channels (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_bits_per_sample (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_sample_rate (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_blocksize (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_max_lpc_order (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_qlp_coeff_precision (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_do_qlp_coeff_prec_search (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_do_escape_coding (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_do_exhaustive_model_search (OggFLAC__FileEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_min_residual_partition_order (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_max_residual_partition_order (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_rice_parameter_search_dist (OggFLAC__FileEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_total_samples_estimate (OggFLAC__FileEncoder *encoder, FLAC__uint64 value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_metadata (OggFLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_filename (OggFLAC__FileEncoder *encoder, const char *value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_progress_callback (OggFLAC__FileEncoder *encoder, OggFLAC__FileEncoderProgressCallback value)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_set_client_data (OggFLAC__FileEncoder *encoder, void *value)
OggFLAC_API OggFLAC__FileEncoderState | OggFLAC__file_encoder_get_state (const OggFLAC__FileEncoder *encoder)
OggFLAC_API OggFLAC__SeekableStreamEncoderState | OggFLAC__file_encoder_get_seekable_stream_encoder_state (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__StreamEncoderState | OggFLAC__file_encoder_get_FLAC_stream_encoder_state (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__StreamDecoderState | OggFLAC__file_encoder_get_verify_decoder_state (const OggFLAC__FileEncoder *encoder)
OggFLAC_API const char * | OggFLAC__file_encoder_get_resolved_state_string (const OggFLAC__FileEncoder *encoder)
OggFLAC_API void | OggFLAC__file_encoder_get_verify_decoder_error_stats (const OggFLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_verify (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_streamable_subset (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_do_mid_side_stereo (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_loose_mid_side_stereo (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_channels (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_bits_per_sample (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_sample_rate (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_blocksize (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_max_lpc_order (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_qlp_coeff_precision (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_do_qlp_coeff_prec_search (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_do_escape_coding (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_get_do_exhaustive_model_search (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_min_residual_partition_order (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_max_residual_partition_order (const OggFLAC__FileEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__file_encoder_get_rice_parameter_search_dist (const OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__uint64 | OggFLAC__file_encoder_get_total_samples_estimate (const OggFLAC__FileEncoder *encoder)
OggFLAC_API OggFLAC__FileEncoderState | OggFLAC__file_encoder_init (OggFLAC__FileEncoder *encoder)
OggFLAC_API void | OggFLAC__file_encoder_finish (OggFLAC__FileEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_process (OggFLAC__FileEncoder *encoder, const FLAC__int32 *const buffer[], unsigned samples)
OggFLAC_API FLAC__bool | OggFLAC__file_encoder_process_interleaved (OggFLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples)

## Variables

OggFLAC_API const char *const | OggFLAC__FileEncoderStateString []

## Detailed Description

This module contains the functions which implement the file encoder. Unlink the Ogg stream and seekable stream encoders, which derive from their FLAC counterparts, the Ogg file encoder is derived from the Ogg seekable stream encoder.

The interface here is nearly identical to FLAC's file encoder, including the callbacks, with the addition of OggFLAC__file_encoder_set_serial_number(). See the FLAC file encoder module for full documentation.

## Typedef Documentation

typedef void(* OggFLAC__FileEncoderProgressCallback)(const OggFLAC__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 OggFLAC__file_encoder_set_progress_callback() and FLAC__FileEncoderProgressCallback 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 OggFLAC__file_encoder_set_client_data().

## Enumeration Type Documentation

enum OggFLAC__FileEncoderState

State values for a OggFLAC__FileEncoder

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

Enumeration values:

  OggFLAC__FILE_ENCODER_OK | The encoder is in the normal OK state.
  OggFLAC__FILE_ENCODER_NO_FILENAME | OggFLAC__file_encoder_init() was called without first calling OggFLAC__file_encoder_set_filename().
  OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR | An error occurred in the underlying seekable stream encoder; check OggFLAC__file_encoder_get_seekable_stream_encoder_state().
  OggFLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING | A fatal error occurred while writing to the encoded file.
  OggFLAC__FILE_ENCODER_ERROR_OPENING_FILE | An error occurred opening the output file for writing.
  OggFLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR | Memory allocation failed.
  OggFLAC__FILE_ENCODER_ALREADY_INITIALIZED | OggFLAC__file_encoder_init() was called when the encoder was already initialized, usually because OggFLAC__file_encoder_finish() was not called.
  OggFLAC__FILE_ENCODER_UNINITIALIZED | The encoder is in the uninitialized state.

## Function Documentation

OggFLAC_API OggFLAC__FileEncoder* OggFLAC__file_encoder_new | ( |  | ) |

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

Return values:

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

OggFLAC_API void OggFLAC__file_encoder_delete | ( | OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | A pointer to an existing encoder.

Assertions:

      encoder != NULL

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_serial_number | ( | OggFLAC__FileEncoder * | encoder,
|  | long | serial_number
| ) |

Set the serial number for the FLAC stream.

Default Value:
  `0`

Parameters:

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

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_verify | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_streamable_subset | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_channels | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_bits_per_sample | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_sample_rate | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_blocksize | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_max_lpc_order | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_escape_coding | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist | ( | OggFLAC__FileEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__uint64 | value
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_metadata | ( | OggFLAC__FileEncoder * | encoder,
|  | FLAC__StreamMetadata ** | metadata,
|  | unsigned | num_blocks
| ) |

This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_set_metadata().

Note:
  The Ogg FLAC mapping requires that the VORBIS_COMMENT block be the second metadata block of the stream. The encoder already supplies the STREAMINFO block automatically. If metadata does not contain a VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if metadata does contain a VORBIS_COMMENT block and it is not the first, this function will reorder metadata by moving the VORBIS_COMMENT block to the front; the relative ordering of the other blocks will remain as they were.

Note:
  The Ogg FLAC mapping limits the number of metadata blocks per stream to `65535`. If num_blocks exceeds this the function will return `false`.

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, or if num_blocks > 65535, else `true`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_filename | ( | OggFLAC__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 OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_progress_callback | ( | OggFLAC__FileEncoder * | encoder,
|  | OggFLAC__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 OggFLAC__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`.

OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_client_data | ( | OggFLAC__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`.

OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_get_state | ( | const OggFLAC__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.

OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_seekable_stream_encoder_state | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  OggFLAC__SeekableStreamEncoderState | The seekable stream encoder state.

OggFLAC_API FLAC__StreamEncoderState OggFLAC__file_encoder_get_FLAC_stream_encoder_state | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the state of the underlying FLAC stream encoder. Useful when the file encoder state is `OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__StreamEncoderState | The seekable stream encoder state.

OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the state of the underlying stream encoder's verify decoder. Useful when the file encoder state is `OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR` and the FLAC 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.

OggFLAC_API const char* OggFLAC__file_encoder_get_resolved_state_string | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the current encoder state as a C string. This version automatically resolves `OggFLAC__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.

OggFLAC_API void OggFLAC__file_encoder_get_verify_decoder_error_stats | ( | const OggFLAC__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 OggFLAC__seekable_stream_encoder_get_verify_decoder_error_stats(). Useful when the file encoder state is `OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR` and the seekable stream encoder state is `OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR` and the FLAC seekable stream encoder state is `FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR` and the FLAC 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

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_verify | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the "verify" flag. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_verify().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_verify().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_streamable_subset | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the "streamable subset" flag. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_streamable_subset().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_streamable_subset().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_get_do_mid_side_stereo().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_loose_mid_side_stereo().

OggFLAC_API unsigned OggFLAC__file_encoder_get_channels | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__file_encoder_set_channels().

OggFLAC_API unsigned OggFLAC__file_encoder_get_bits_per_sample | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the input sample resolution setting. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_bits_per_sample().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_bits_per_sample().

OggFLAC_API unsigned OggFLAC__file_encoder_get_sample_rate | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the input sample rate setting. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_sample_rate().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_sample_rate().

OggFLAC_API unsigned OggFLAC__file_encoder_get_blocksize | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the blocksize setting. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_blocksize().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_blocksize().

OggFLAC_API unsigned OggFLAC__file_encoder_get_max_lpc_order | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the maximum LPC order setting. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_max_lpc_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_max_lpc_order().

OggFLAC_API unsigned OggFLAC__file_encoder_get_qlp_coeff_precision | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_qlp_coeff_precision().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_do_qlp_coeff_prec_search().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_escape_coding | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the "escape coding" flag. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_do_escape_coding().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_do_escape_coding().

OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get the exhaustive model search flag. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See OggFLAC__file_encoder_set_do_exhaustive_model_search().

OggFLAC_API unsigned OggFLAC__file_encoder_get_min_residual_partition_order | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_min_residual_partition_order().

OggFLAC_API unsigned OggFLAC__file_encoder_get_max_residual_partition_order | ( | const OggFLAC__FileEncoder * | encoder | ) |

Get maximum residual partition order setting. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__seekable_stream_encoder_get_max_residual_partition_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_max_residual_partition_order().

OggFLAC_API unsigned OggFLAC__file_encoder_get_rice_parameter_search_dist | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__file_encoder_set_rice_parameter_search_dist().

OggFLAC_API FLAC__uint64 OggFLAC__file_encoder_get_total_samples_estimate | ( | const OggFLAC__FileEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__uint64 | See OggFLAC__file_encoder_set_total_samples_estimate().

OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_init | ( | OggFLAC__FileEncoder * | encoder | ) |

Initialize the encoder instance. Should be called after OggFLAC__file_encoder_new() and OggFLAC__file_encoder_set_*() but before OggFLAC__file_encoder_process() or OggFLAC__file_encoder_process_interleaved(). Will set and return the encoder state, which will be OggFLAC__FILE_ENCODER_OK if initialization succeeded.

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API void OggFLAC__file_encoder_finish | ( | OggFLAC__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 OggFLAC__FILE_ENCODER_UNINITIALIZED.

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

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

OggFLAC_API FLAC__bool OggFLAC__file_encoder_process | ( | OggFLAC__FileEncoder * | encoder,
|  | const FLAC__int32 *const | buffer[],
|  | unsigned | samples
| ) |

Submit data for encoding. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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

      OggFLAC__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__file_encoder_process_interleaved | ( | OggFLAC__FileEncoder * | encoder,
|  | const FLAC__int32 | buffer[],
|  | unsigned | samples
| ) |

Submit data for encoding. This is inherited from OggFLAC__SeekableStreamEncoder; see OggFLAC__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 OggFLAC__file_encoder_process(). For example, if encoding two channels, `1000` samples corresponds to a buffer of 2000 values.

Assertions:

      encoder != NULL

      OggFLAC__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK

Return values:

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

## Variable Documentation

OggFLAC_API const char* const OggFLAC__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.