FLAC/seekable_stream_encoder.h: seekable stream encoder interface

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

# FLAC/seekable_stream_encoder.h: seekable stream encoder interface
[FLAC/_encoder.h: encoder interfaces]

This module contains the functions which implement the seekable stream encoder. More...

## Compounds

struct | FLAC__SeekableStreamEncoder

## Typedefs

typedef FLAC__SeekableStreamEncoderSeekStatus(* | FLAC__SeekableStreamEncoderSeekCallback )(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
typedef FLAC__SeekableStreamEncoderTellStatus(* | FLAC__SeekableStreamEncoderTellCallback )(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
typedef FLAC__StreamEncoderWriteStatus(* | FLAC__SeekableStreamEncoderWriteCallback )(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)

## Enumerations

enum

FLAC__SeekableStreamEncoderState {
FLAC__SEEKABLE_STREAM_ENCODER_OK = 0, FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR, FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR, FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR, FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR, FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR, FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK, FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE, FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
}

enum | FLAC__SeekableStreamEncoderSeekStatus { FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK, FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR }
enum | FLAC__SeekableStreamEncoderTellStatus { FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK, FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR }

## Functions

FLAC__SeekableStreamEncoder * | FLAC__seekable_stream_encoder_new ()
void | FLAC__seekable_stream_encoder_delete (FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_set_verify (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_streamable_subset (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_do_mid_side_stereo (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_loose_mid_side_stereo (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_channels (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_bits_per_sample (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_sample_rate (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_blocksize (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_max_lpc_order (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_qlp_coeff_precision (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_do_escape_coding (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_do_exhaustive_model_search (FLAC__SeekableStreamEncoder *encoder, FLAC__bool value)
FLAC__bool | FLAC__seekable_stream_encoder_set_min_residual_partition_order (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_max_residual_partition_order (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_rice_parameter_search_dist (FLAC__SeekableStreamEncoder *encoder, unsigned value)
FLAC__bool | FLAC__seekable_stream_encoder_set_total_samples_estimate (FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value)
FLAC__bool | FLAC__seekable_stream_encoder_set_metadata (FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks)
FLAC__bool | FLAC__seekable_stream_encoder_set_seek_callback (FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value)
FLAC__bool | FLAC__seekable_stream_encoder_set_tell_callback (FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value)
FLAC__bool | FLAC__seekable_stream_encoder_set_write_callback (FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value)
FLAC__bool | FLAC__seekable_stream_encoder_set_client_data (FLAC__SeekableStreamEncoder *encoder, void *value)
FLAC__SeekableStreamEncoderState | FLAC__seekable_stream_encoder_get_state (const FLAC__SeekableStreamEncoder *encoder)
FLAC__StreamEncoderState | FLAC__seekable_stream_encoder_get_stream_encoder_state (const FLAC__SeekableStreamEncoder *encoder)
FLAC__StreamDecoderState | FLAC__seekable_stream_encoder_get_verify_decoder_state (const FLAC__SeekableStreamEncoder *encoder)
const char * | FLAC__seekable_stream_encoder_get_resolved_state_string (const FLAC__SeekableStreamEncoder *encoder)
void | FLAC__seekable_stream_encoder_get_verify_decoder_error_stats (const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got)
FLAC__bool | FLAC__seekable_stream_encoder_get_verify (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_streamable_subset (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_do_mid_side_stereo (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_loose_mid_side_stereo (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_channels (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_bits_per_sample (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_sample_rate (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_blocksize (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_max_lpc_order (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_qlp_coeff_precision (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_do_escape_coding (const FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_get_do_exhaustive_model_search (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_min_residual_partition_order (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_max_residual_partition_order (const FLAC__SeekableStreamEncoder *encoder)
unsigned | FLAC__seekable_stream_encoder_get_rice_parameter_search_dist (const FLAC__SeekableStreamEncoder *encoder)
FLAC__uint64 | FLAC__seekable_stream_encoder_get_total_samples_estimate (const FLAC__SeekableStreamEncoder *encoder)
FLAC__SeekableStreamEncoderState | FLAC__seekable_stream_encoder_init (FLAC__SeekableStreamEncoder *encoder)
void | FLAC__seekable_stream_encoder_finish (FLAC__SeekableStreamEncoder *encoder)
FLAC__bool | FLAC__seekable_stream_encoder_process (FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 *const buffer[], unsigned samples)
FLAC__bool | FLAC__seekable_stream_encoder_process_interleaved (FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples)

## Variables

const char *const | FLAC__SeekableStreamEncoderStateString []
const char *const | FLAC__SeekableStreamEncoderSeekStatusString []
const char *const | FLAC__SeekableStreamEncoderTellStatusString []

## Detailed Description

This module contains the functions which implement the seekable stream encoder.

The basic usage of this encoder is as follows:

- The program creates an instance of an encoder using FLAC__seekable_stream_encoder_new().
- The program overrides the default settings and sets callbacks using FLAC__seekable_stream_encoder_set_*() functions.
- The program initializes the instance to validate the settings and prepare for encoding using FLAC__seekable_stream_encoder_init().
- The program calls FLAC__seekable_stream_encoder_process() or FLAC__seekable_stream_encoder_process_interleaved() to encode data, which subsequently calls the callbacks when there is encoder data ready to be written.
- The program finishes the encoding with FLAC__seekable_stream_encoder_finish(), which causes the encoder to encode any data still in its input pipe, rewrite the metadata with the final encoding statistics, and finally reset the encoder to the uninitialized state.
- The instance may be used again or deleted with FLAC__seekable_stream_encoder_delete().

The seekable stream encoder is a wrapper around the stream encoder with callbacks for seeking the output and reporting the output stream position. This allows the encoder to go back and rewrite some of the metadata after encoding if necessary, and provides the metadata callback of the stream encoder internally. However, you must provide seek and tell callbacks (see FLAC__seekable_stream_encoder_set_seek_callback() and FLAC__seekable_stream_encoder_set_tell_callback()).

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

Note:
  If you are writing the FLAC data to a file, make sure it is open for update (e.g. mode "w+" for stdio streams). This is because after the first encoding pass, the encoder will try to seek back to the beginning of the stream, to the STREAMINFO block, to write some data there.

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

Note:
  FLAC__seekable_stream_encoder_finish() resets all settings to the constructor defaults, including the callbacks.

## Typedef Documentation

typedef FLAC__SeekableStreamEncoderSeekStatus(* FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)

Signature for the seek callback. See FLAC__seekable_stream_encoder_set_seek_callback() for more info.

Parameters:

  encoder | The encoder instance calling the callback.
  absolute_byte_offset | The offset from the beginning of the stream to seek to.
  client_data | The callee's client data set through FLAC__seekable_stream_encoder_set_client_data().

Return values:

  FLAC__SeekableStreamEncoderSeekStatus | The callee's return status.

typedef FLAC__SeekableStreamEncoderTellStatus(* FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)

Signature for the tell callback. See FLAC__seekable_stream_encoder_set_tell_callback() for more info.

Warning:
  The callback must return the true current byte offset of the output to which the encoder is writing. If you are buffering the output, make sure and take this into account. If you are writing directly to a FILE* from your write callback, ftell() is sufficient. If you are writing directly to a file descriptor from your write callback, you can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to these points to rewrite metadata after encoding.

Parameters:

  encoder | The encoder instance calling the callback.
  absolute_byte_offset | The address at which to store the current position of the output.
  client_data | The callee's client data set through FLAC__seekable_stream_encoder_set_client_data().

Return values:

  FLAC__SeekableStreamEncoderTellStatus | The callee's return status.

typedef FLAC__StreamEncoderWriteStatus(* FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)

Signature for the write callback. See FLAC__seekable_stream_encoder_set_write_callback() and FLAC__StreamEncoderWriteCallback for more info.

Parameters:

  encoder | The encoder instance calling the callback.
  buffer | An array of encoded data of length bytes.
  bytes | The byte length of buffer.
  samples | The number of samples encoded by buffer. `0` has a special meaning; see FLAC__stream_encoder_set_write_callback().
  current_frame | The number of current frame being encoded.
  client_data | The callee's client data set through FLAC__seekable_stream_encoder_set_client_data().

Return values:

  FLAC__StreamEncoderWriteStatus | The callee's return status.

## Enumeration Type Documentation

enum FLAC__SeekableStreamEncoderState

State values for a FLAC__SeekableStreamEncoder

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

Enumeration values:

  FLAC__SEEKABLE_STREAM_ENCODER_OK | The encoder is in the normal OK state.
  FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR | An error occurred in the underlying stream encoder; check FLAC__seekable_stream_encoder_get_stream_encoder_state().
  FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR | Memory allocation failed.
  FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR | The write callback returned an error.
  FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR | The read callback returned an error.
  FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR | The seek callback returned an error.
  FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR | The tell callback returned an error.
  FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED | FLAC__seekable_stream_encoder_init() was called when the encoder was already initialized, usually because FLAC__seekable_stream_encoder_finish() was not called.
  FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK | FLAC__seekable_stream_encoder_init() was called without all callbacks being set.
  FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE | An invalid seek table was passed is the metadata to FLAC__seekable_stream_encoder_set_metadata().
  FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED | The encoder is in the uninitialized state.

enum FLAC__SeekableStreamEncoderSeekStatus

Return values for the FLAC__SeekableStreamEncoder seek callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK | The seek was OK and encoding can continue.
  FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR | An unrecoverable error occurred. The encoder will return from the process call.

enum FLAC__SeekableStreamEncoderTellStatus

Return values for the FLAC__SeekableStreamEncoder tell callback.

Enumeration values:

  FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK | The tell was OK and encoding can continue.
  FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR | An unrecoverable error occurred. The encoder will return from the process call.

## Function Documentation

FLAC__SeekableStreamEncoder* FLAC__seekable_stream_encoder_new | ( |  | ) |

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

Return values:

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

void FLAC__seekable_stream_encoder_delete | ( | FLAC__SeekableStreamEncoder * | 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__seekable_stream_encoder_set_verify | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_streamable_subset | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_do_mid_side_stereo | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_loose_mid_side_stereo | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_channels | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_bits_per_sample | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_sample_rate | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_blocksize | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_max_lpc_order | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_qlp_coeff_precision | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_do_qlp_coeff_prec_search | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_do_escape_coding | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_do_exhaustive_model_search | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_min_residual_partition_order | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_max_residual_partition_order | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_rice_parameter_search_dist | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_total_samples_estimate | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__uint64 | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_set_metadata | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__StreamMetadata ** | metadata,
|  | unsigned | num_blocks
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata().

Note:
  SEEKTABLE blocks are handled specially. Since you will not know the values for the seek point stream offsets, you should pass in a SEEKTABLE 'template', that is, a SEEKTABLE object with the required sample numbers (or placeholder points), with `0` for the frame_samples and stream_offset fields for each point. While encoding, the encoder will fill them in for you and when encoding is finished, it will seek back and write the real values into the SEEKTABLE block in the stream. There are helper routines for manipulating seektable template blocks; see metadata.h: FLAC__metadata_object_seektable_template_*().

Note:
  The encoder instance will modify the first `SEEKTABLE` block as it transforms the template to a valid seektable while encoding, but it is still up to the caller to free all metadata blocks after encoding.

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__seekable_stream_encoder_set_seek_callback | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__SeekableStreamEncoderSeekCallback | value
| ) |

Set the seek callback. The supplied function will be called when the encoder needs to seek the output stream. The encoder will pass the absolute byte offset to seek to, 0 meaning the beginning of the stream.

Note:
  The callback is mandatory and must 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__seekable_stream_encoder_set_tell_callback | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__SeekableStreamEncoderTellCallback | value
| ) |

Set the tell callback. The supplied function will be called when the encoder needs to know the current position of the output stream.

Note:
  The callback is mandatory and must 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__seekable_stream_encoder_set_write_callback | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | FLAC__SeekableStreamEncoderWriteCallback | value
| ) |

Set the write callback. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_write_callback().

Note:
  The callback is mandatory and must 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__seekable_stream_encoder_set_client_data | ( | FLAC__SeekableStreamEncoder * | 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__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the current encoder state.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__SeekableStreamEncoderState | The current encoder state.

FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the state of the underlying stream encoder. Useful when 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 stream encoder state.

FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the state of the underlying stream encoder's verify decoder. Useful when 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__seekable_stream_encoder_get_resolved_state_string | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the current encoder state as a C string. This version automatically resolves `FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR` by getting the 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__seekable_stream_encoder_get_verify_decoder_error_stats | ( | const FLAC__SeekableStreamEncoder * | 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__stream_encoder_get_verify_decoder_error_stats(). Useful when 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__seekable_stream_encoder_get_verify | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the "verify" flag. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_verify().

FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the "streamable subset" flag. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_streamable_subset().

FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().

FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().

unsigned FLAC__seekable_stream_encoder_get_channels | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_channels().

unsigned FLAC__seekable_stream_encoder_get_bits_per_sample | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the input sample resolution setting. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_bits_per_sample().

unsigned FLAC__seekable_stream_encoder_get_sample_rate | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the input sample rate setting. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_sample_rate().

unsigned FLAC__seekable_stream_encoder_get_blocksize | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the blocksize setting. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_blocksize().

unsigned FLAC__seekable_stream_encoder_get_max_lpc_order | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the maximum LPC order setting. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_max_lpc_order().

unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().

FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().

FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the "escape coding" flag. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_do_escape_coding().

FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get the exhaustive model search flag. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__bool | See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().

unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_min_residual_partition_order().

unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

Get maximum residual partition order setting. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_residual_partition_order().

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_max_residual_partition_order().

unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().

FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate | ( | const FLAC__SeekableStreamEncoder * | encoder | ) |

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

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__uint64 | See FLAC__seekable_stream_encoder_set_total_samples_estimate().

FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init | ( | FLAC__SeekableStreamEncoder * | encoder | ) |

Initialize the encoder instance. Should be called after FLAC__seekable_stream_encoder_new() and FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process() or FLAC__seekable_stream_encoder_process_interleaved(). Will set and return the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization succeeded.

The call to FLAC__seekable_stream_encoder_init() currently will also immediately call the write callback with the `fLaC` signature and all the encoded metadata.

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

Return values:

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

void FLAC__seekable_stream_encoder_finish | ( | FLAC__SeekableStreamEncoder * | 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__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.

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

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

FLAC__bool FLAC__seekable_stream_encoder_process | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | const FLAC__int32 *const | buffer[],
|  | unsigned | samples
| ) |

Submit data for encoding. This is inherited from FLAC__StreamEncoder; see FLAC__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__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK

Return values:

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

FLAC__bool FLAC__seekable_stream_encoder_process_interleaved | ( | FLAC__SeekableStreamEncoder * | encoder,
|  | const FLAC__int32 | buffer[],
|  | unsigned | samples
| ) |

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

Assertions:

      encoder != NULL

      FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK

Return values:

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

## Variable Documentation

const char* const FLAC__SeekableStreamEncoderStateString[]

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

const char* const FLAC__SeekableStreamEncoderSeekStatusString[]

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

const char* const FLAC__SeekableStreamEncoderTellStatusString[]

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