OggFLAC/stream_encoder.h: stream encoder interface

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

# OggFLAC/stream_encoder.h: stream encoder interface
[OggFLAC/_encoder.h: encoder interfaces]

This module contains the functions which implement the stream encoder. The Ogg stream encoder is derived from the FLAC stream encoder. More...

## Compounds

struct | OggFLAC__StreamEncoder

## Typedefs

typedef FLAC__StreamEncoderWriteStatus(* | OggFLAC__StreamEncoderWriteCallback )(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)
typedef void(* | OggFLAC__StreamEncoderMetadataCallback )(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data)

## Enumerations

enum

OggFLAC__StreamEncoderState {
OggFLAC__STREAM_ENCODER_OK = 0, OggFLAC__STREAM_ENCODER_OGG_ERROR, OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR, OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR, OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED, OggFLAC__STREAM_ENCODER_UNINITIALIZED
}

## Functions

OggFLAC_API OggFLAC__StreamEncoder * | OggFLAC__stream_encoder_new ()
OggFLAC_API void | OggFLAC__stream_encoder_delete (OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_serial_number (OggFLAC__StreamEncoder *encoder, long serial_number)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_verify (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_streamable_subset (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_do_mid_side_stereo (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_loose_mid_side_stereo (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_channels (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_bits_per_sample (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_sample_rate (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_blocksize (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_max_lpc_order (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_qlp_coeff_precision (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_do_escape_coding (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_do_exhaustive_model_search (OggFLAC__StreamEncoder *encoder, FLAC__bool value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_min_residual_partition_order (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_max_residual_partition_order (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_rice_parameter_search_dist (OggFLAC__StreamEncoder *encoder, unsigned value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_total_samples_estimate (OggFLAC__StreamEncoder *encoder, FLAC__uint64 value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_metadata (OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_write_callback (OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_metadata_callback (OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_set_client_data (OggFLAC__StreamEncoder *encoder, void *value)
OggFLAC_API OggFLAC__StreamEncoderState | OggFLAC__stream_encoder_get_state (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__StreamEncoderState | OggFLAC__stream_encoder_get_FLAC_stream_encoder_state (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__StreamDecoderState | OggFLAC__stream_encoder_get_verify_decoder_state (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API const char * | OggFLAC__stream_encoder_get_resolved_state_string (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API void | OggFLAC__stream_encoder_get_verify_decoder_error_stats (const OggFLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_verify (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_streamable_subset (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_do_mid_side_stereo (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_loose_mid_side_stereo (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_channels (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_bits_per_sample (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_sample_rate (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_blocksize (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_max_lpc_order (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_qlp_coeff_precision (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_do_escape_coding (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_get_do_exhaustive_model_search (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_min_residual_partition_order (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_max_residual_partition_order (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API unsigned | OggFLAC__stream_encoder_get_rice_parameter_search_dist (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__uint64 | OggFLAC__stream_encoder_get_total_samples_estimate (const OggFLAC__StreamEncoder *encoder)
OggFLAC_API OggFLAC__StreamEncoderState | OggFLAC__stream_encoder_init (OggFLAC__StreamEncoder *encoder)
OggFLAC_API void | OggFLAC__stream_encoder_finish (OggFLAC__StreamEncoder *encoder)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_process (OggFLAC__StreamEncoder *encoder, const FLAC__int32 *const buffer[], unsigned samples)
OggFLAC_API FLAC__bool | OggFLAC__stream_encoder_process_interleaved (OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples)

## Variables

OggFLAC_API const char *const | OggFLAC__StreamEncoderStateString []

## Detailed Description

This module contains the functions which implement the stream encoder. The Ogg stream encoder is derived from the FLAC stream encoder.

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

## Typedef Documentation

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

Signature for the write callback. See OggFLAC__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 OggFLAC__stream_encoder_set_write_callback().
  current_frame | The number of current frame being encoded.
  client_data | The callee's client data set through OggFLAC__stream_encoder_set_client_data().

Return values:

  FLAC__StreamEncoderWriteStatus | The callee's return status.

typedef void(* OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data)

Signature for the metadata callback. See OggFLAC__stream_encoder_set_metadata_callback() and FLAC__stream_encoder_set_metadata_callback() for more info.

Parameters:

  encoder | The encoder instance calling the callback.
  metadata | The final populated STREAMINFO block.
  client_data | The callee's client data set through FLAC__stream_encoder_set_client_data().

## Enumeration Type Documentation

enum OggFLAC__StreamEncoderState

State values for an OggFLAC__StreamEncoder

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

Enumeration values:

  OggFLAC__STREAM_ENCODER_OK | The encoder is in the normal OK state.
  OggFLAC__STREAM_ENCODER_OGG_ERROR | An error occurred in the underlying Ogg layer.
  OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR | An error occurred in the underlying FLAC stream encoder; check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
  OggFLAC__STREAM_ENCODER_INVALID_CALLBACK | The encoder was initialized before setting all the required callbacks.
  OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR | Memory allocation failed.
  OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED | OggFLAC__stream_encoder_init() was called when the encoder was already initialized, usually because OggFLAC__stream_encoder_finish() was not called.
  OggFLAC__STREAM_ENCODER_UNINITIALIZED | The encoder is in the uninitialized state.

## Function Documentation

OggFLAC_API OggFLAC__StreamEncoder* OggFLAC__stream_encoder_new | ( |  | ) |

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

Return values:

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

OggFLAC_API void OggFLAC__stream_encoder_delete | ( | OggFLAC__StreamEncoder * | 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__stream_encoder_set_serial_number | ( | OggFLAC__StreamEncoder * | encoder,
|  | long | serial_number
| ) |

Set the serial number for the FLAC stream.

Note:
  It is recommended to set a serial number explicitly as the default of '0' may collide with other streams.

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__stream_encoder_set_verify | ( | OggFLAC__StreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()

Default Value:
  `false`

Parameters:

  encoder | An encoder instance to set.
  value | Flag value (see above).

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_streamable_subset | ( | OggFLAC__StreamEncoder * | 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 | Flag value (see above).

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo | ( | OggFLAC__StreamEncoder * | 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 | Flag value (see above).

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo | ( | OggFLAC__StreamEncoder * | 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 | Flag value (see above).

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_channels | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample | ( | OggFLAC__StreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()

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__stream_encoder_set_sample_rate | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_blocksize | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision | ( | OggFLAC__StreamEncoder * | encoder,
|  | unsigned | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()

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__stream_encoder_set_do_qlp_coeff_prec_search | ( | OggFLAC__StreamEncoder * | encoder,
|  | FLAC__bool | value
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_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__stream_encoder_set_do_escape_coding | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate | ( | OggFLAC__StreamEncoder * | 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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata | ( | OggFLAC__StreamEncoder * | encoder,
|  | FLAC__StreamMetadata ** | metadata,
|  | unsigned | num_blocks
| ) |

This is inherited from FLAC__StreamEncoder; see FLAC__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__stream_encoder_set_write_callback | ( | OggFLAC__StreamEncoder * | encoder,
|  | OggFLAC__StreamEncoderWriteCallback | value
| ) |

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

Note:
  Unlike the FLAC stream encoder write callback, the Ogg stream encoder write callback will be called twice when writing audio frames; once for the page header, and once for the page body. When writing the page header, the samples argument to the write callback will be `0`.

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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback | ( | OggFLAC__StreamEncoder * | encoder,
|  | OggFLAC__StreamEncoderMetadataCallback | value
| ) |

Set the metadata callback. This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata_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`.

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data | ( | OggFLAC__StreamEncoder * | 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__StreamEncoderState OggFLAC__stream_encoder_get_state | ( | const OggFLAC__StreamEncoder * | encoder | ) |

Get the current encoder state.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  OggFLAC__StreamEncoderState | The current encoder state.

OggFLAC_API FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state | ( | const OggFLAC__StreamEncoder * | encoder | ) |

Get the state of the underlying FLAC stream encoder. Useful when the stream encoder state is `OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__StreamEncoderState | The FLAC stream encoder state.

OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state | ( | const OggFLAC__StreamEncoder * | encoder | ) |

Get the state of the underlying FLAC stream encoder's verify decoder. Useful when the stream encoder state is `OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR` and the FLAC encoder state is `FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR`.

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  FLAC__StreamDecoderState | The FLAC verify decoder state.

OggFLAC_API const char* OggFLAC__stream_encoder_get_resolved_state_string | ( | const OggFLAC__StreamEncoder * | encoder | ) |

Get the current encoder state as a C string. This version automatically resolves `OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR` by getting the FLAC 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__stream_encoder_get_verify_decoder_error_stats | ( | const OggFLAC__StreamEncoder * | 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 stream encoder state is `OggFLAC__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.
  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

      absolute_sample != NULL

      frame_number != NULL

      channel != NULL

      sample != NULL

      expected != NULL

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_verify | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_verify().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_streamable_subset | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_streamable_subset().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_get_do_mid_side_stereo().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_loose_mid_side_stereo().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_channels | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_channels().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_bits_per_sample | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_bits_per_sample().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_sample_rate | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_sample_rate().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_blocksize | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_blocksize().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_lpc_order | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_max_lpc_order().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_qlp_coeff_precision().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_do_escape_coding().

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_do_exhaustive_model_search().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_min_residual_partition_order | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_min_residual_partition_order().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_residual_partition_order | ( | const OggFLAC__StreamEncoder * | encoder | ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()

Parameters:

  encoder | An encoder instance to query.

Assertions:

      encoder != NULL

Return values:

  unsigned | See OggFLAC__stream_encoder_set_max_residual_partition_order().

OggFLAC_API unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist | ( | const OggFLAC__StreamEncoder * | encoder | ) |

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 OggFLAC__stream_encoder_set_rice_parameter_search_dist().

OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate | ( | const OggFLAC__StreamEncoder * | encoder | ) |

This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()

Parameters:

  encoder | An encoder instance to set.

Assertions:

      encoder != NULL

Return values:

  FLAC__uint64 | See OggFLAC__stream_encoder_get_total_samples_estimate().

OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init | ( | OggFLAC__StreamEncoder * | encoder | ) |

Initialize the encoder instance. Should be called after OggFLAC__stream_encoder_new() and OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process() or OggFLAC__stream_encoder_process_interleaved(). Will set and return the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if initialization succeeded.

The call to OggFLAC__stream_encoder_init() currently will also immediately call the write callback several times, once with the `fLaC` signature, and once for each encoded metadata block.

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

Return values:

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

OggFLAC_API void OggFLAC__stream_encoder_finish | ( | OggFLAC__StreamEncoder * | 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__STREAM_ENCODER_UNINITIALIZED. Note that this can generate one or more write callbacks before returning.

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

Parameters:

  encoder | An uninitialized encoder instance.

Assertions:

      encoder != NULL

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process | ( | OggFLAC__StreamEncoder * | 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

      OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK

Return values:

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

OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process_interleaved | ( | OggFLAC__StreamEncoder * | 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 OggFLAC__stream_encoder_process(). For example, if encoding two channels, `1000` samples corresponds to a buffer of 2000 values.

Assertions:

      encoder != NULL

      OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK

Return values:

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

## Variable Documentation

OggFLAC_API const char* const OggFLAC__StreamEncoderStateString[]

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