include/OggFLAC/stream_encoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
   2  * Copyright (C) 2002,2003,2004,2005  Josh Coalson
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  11  * - Redistributions in binary form must reproduce the above copyright
  12  * notice, this list of conditions and the following disclaimer in the
  13  * documentation and/or other materials provided with the distribution.
  14  *
  15  * - Neither the name of the Xiph.org Foundation nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef OggFLAC__STREAM_ENCODER_H
  33 #define OggFLAC__STREAM_ENCODER_H
  34
  35 #include "export.h"
  36
  37 #include "FLAC/stream_encoder.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43
  44 /** \file include/OggFLAC/stream_encoder.h
  45  *
  46  *  \brief
  47  *  This module contains the functions which implement the stream
  48  *  encoder.
  49  *
  50  *  See the detailed documentation in the
  51  *  \link oggflac_stream_encoder stream encoder \endlink module.
  52  */
  53
  54 /** \defgroup oggflac_encoder OggFLAC/ *_encoder.h: encoder interfaces
  55  *  \ingroup oggflac
  56  *
  57  *  \brief
  58  *  This module describes the three encoder layers provided by libOggFLAC.
  59  *
  60  * libOggFLAC currently provides the same three layers of access as libFLAC;
  61  * the interfaces are nearly identical, with the addition of a method for
  62  * specifying the Ogg serial number.  See the \link flac_encoder FLAC
  63  * encoder module \endlink for full documentation.
  64  */
  65
  66 /** \defgroup oggflac_stream_encoder OggFLAC/stream_encoder.h: stream encoder interface
  67  *  \ingroup oggflac_encoder
  68  *
  69  *  \brief
  70  *  This module contains the functions which implement the stream
  71  *  encoder.  The Ogg stream encoder is derived
  72  *  from the FLAC stream encoder.
  73  *
  74  * The interface here is nearly identical to FLAC's stream encoder,
  75  * including the callbacks, with the addition of
  76  * OggFLAC__stream_encoder_set_serial_number().  See the
  77  * \link flac_stream_encoder FLAC stream encoder module \endlink
  78  * for full documentation.
  79  *
  80  * \{
  81  */
  82
  83
  84 /** State values for an OggFLAC__StreamEncoder
  85  *
  86  *  The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
  87  */
  88 typedef enum {
  89
  90         OggFLAC__STREAM_ENCODER_OK = 0,
  91         /**< The encoder is in the normal OK state. */
  92
  93         OggFLAC__STREAM_ENCODER_OGG_ERROR,
  94         /**< An error occurred in the underlying Ogg layer.  */
  95
  96         OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
  97         /**< An error occurred in the underlying FLAC stream encoder;
  98          * check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
  99          */
 100
 101         OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
 102         /**< The encoder was initialized before setting all the required callbacks. */
 103
 104         OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
 105         /**< Memory allocation failed. */
 106
 107         OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
 108         /**< OggFLAC__stream_encoder_init() was called when the encoder was
 109          * already initialized, usually because
 110          * OggFLAC__stream_encoder_finish() was not called.
 111          */
 112
 113         OggFLAC__STREAM_ENCODER_UNINITIALIZED
 114         /**< The encoder is in the uninitialized state. */
 115
 116 } OggFLAC__StreamEncoderState;
 117
 118 /** Maps an OggFLAC__StreamEncoderState to a C string.
 119  *
 120  *  Using an OggFLAC__StreamEncoderState as the index to this array
 121  *  will give the string equivalent.  The contents should not be modified.
 122  */
 123 extern OggFLAC_API const char * const OggFLAC__StreamEncoderStateString[];
 124
 125
 126 /***********************************************************************
 127  *
 128  * class OggFLAC__StreamEncoder
 129  *
 130  ***********************************************************************/
 131
 132 struct OggFLAC__StreamEncoderProtected;
 133 struct OggFLAC__StreamEncoderPrivate;
 134 /** The opaque structure definition for the stream encoder type.
 135  *  See the \link oggflac_stream_encoder stream encoder module \endlink
 136  *  for a detailed description.
 137  */
 138 typedef struct {
 139         struct OggFLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 140         struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 141 } OggFLAC__StreamEncoder;
 142
 143 /** Signature for the write callback.
 144  *  See OggFLAC__stream_encoder_set_write_callback()
 145  *  and FLAC__StreamEncoderWriteCallback for more info.
 146  *
 147  * \param  encoder  The encoder instance calling the callback.
 148  * \param  buffer   An array of encoded data of length \a bytes.
 149  * \param  bytes    The byte length of \a buffer.
 150  * \param  samples  The number of samples encoded by \a buffer.
 151  *                  \c 0 has a special meaning; see
 152  *                  OggFLAC__stream_encoder_set_write_callback().
 153  * \param  current_frame  The number of current frame being encoded.
 154  * \param  client_data  The callee's client data set through
 155  *                      OggFLAC__stream_encoder_set_client_data().
 156  * \retval FLAC__StreamEncoderWriteStatus
 157  *    The callee's return status.
 158  */
 159 typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 160
 161 /** Signature for the metadata callback.
 162  *  See OggFLAC__stream_encoder_set_metadata_callback()
 163  *  and FLAC__stream_encoder_set_metadata_callback() for more info.
 164  *
 165  * \param  encoder      The encoder instance calling the callback.
 166  * \param  metadata     The final populated STREAMINFO block.
 167  * \param  client_data  The callee's client data set through
 168  *                      FLAC__stream_encoder_set_client_data().
 169  */
 170 typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
 171
 172
 173 /***********************************************************************
 174  *
 175  * Class constructor/destructor
 176  *
 177  ***********************************************************************/
 178
 179 /** Create a new stream encoder instance.  The instance is created with
 180  *  default settings; see the individual OggFLAC__stream_encoder_set_*()
 181  *  functions for each setting's default.
 182  *
 183  * \retval OggFLAC__StreamEncoder*
 184  *    \c NULL if there was an error allocating memory, else the new instance.
 185  */
 186 OggFLAC_API OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new();
 187
 188 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 189  *
 190  * \param encoder  A pointer to an existing encoder.
 191  * \assert
 192  *    \code encoder != NULL \endcode
 193  */
 194 OggFLAC_API void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder);
 195
 196
 197 /***********************************************************************
 198  *
 199  * Public class method prototypes
 200  *
 201  ***********************************************************************/
 202
 203 /** Set the serial number for the FLAC stream.
 204  *
 205  * \note
 206  * It is recommended to set a serial number explicitly as the default of '0'
 207  * may collide with other streams.
 208  *
 209  * \default \c 0
 210  * \param  encoder        An encoder instance to set.
 211  * \param  serial_number  See above.
 212  * \assert
 213  *    \code encoder != NULL \endcode
 214  * \retval FLAC__bool
 215  *    \c false if the encoder is already initialized, else \c true.
 216  */
 217 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_serial_number(OggFLAC__StreamEncoder *encoder, long serial_number);
 218
 219 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
 220  *
 221  * \default \c false
 222  * \param  encoder  An encoder instance to set.
 223  * \param  value    Flag value (see above).
 224  * \assert
 225  *    \code encoder != NULL \endcode
 226  * \retval FLAC__bool
 227  *    \c false if the encoder is already initialized, else \c true.
 228  */
 229 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 230
 231 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
 232  *
 233  * \default \c true
 234  * \param  encoder  An encoder instance to set.
 235  * \param  value    Flag value (see above).
 236  * \assert
 237  *    \code encoder != NULL \endcode
 238  * \retval FLAC__bool
 239  *    \c false if the encoder is already initialized, else \c true.
 240  */
 241 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 242
 243 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
 244  *
 245  * \default \c false
 246  * \param  encoder  An encoder instance to set.
 247  * \param  value    Flag value (see above).
 248  * \assert
 249  *    \code encoder != NULL \endcode
 250  * \retval FLAC__bool
 251  *    \c false if the encoder is already initialized, else \c true.
 252  */
 253 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 254
 255 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
 256  *
 257  * \default \c false
 258  * \param  encoder  An encoder instance to set.
 259  * \param  value    Flag value (see above).
 260  * \assert
 261  *    \code encoder != NULL \endcode
 262  * \retval FLAC__bool
 263  *    \c false if the encoder is already initialized, else \c true.
 264  */
 265 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 266
 267 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
 268  *
 269  * \default \c 2
 270  * \param  encoder  An encoder instance to set.
 271  * \param  value    See above.
 272  * \assert
 273  *    \code encoder != NULL \endcode
 274  * \retval FLAC__bool
 275  *    \c false if the encoder is already initialized, else \c true.
 276  */
 277 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value);
 278
 279 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
 280  *
 281  * \default \c 16
 282  * \param  encoder  An encoder instance to set.
 283  * \param  value    See above.
 284  * \assert
 285  *    \code encoder != NULL \endcode
 286  * \retval FLAC__bool
 287  *    \c false if the encoder is already initialized, else \c true.
 288  */
 289 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value);
 290
 291 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
 292  *
 293  * \default \c 44100
 294  * \param  encoder  An encoder instance to set.
 295  * \param  value    See above.
 296  * \assert
 297  *    \code encoder != NULL \endcode
 298  * \retval FLAC__bool
 299  *    \c false if the encoder is already initialized, else \c true.
 300  */
 301 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value);
 302
 303 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
 304  *
 305  * \default \c 1152
 306  * \param  encoder  An encoder instance to set.
 307  * \param  value    See above.
 308  * \assert
 309  *    \code encoder != NULL \endcode
 310  * \retval FLAC__bool
 311  *    \c false if the encoder is already initialized, else \c true.
 312  */
 313 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value);
 314
 315 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
 316  *
 317  * \default \c 0
 318  * \param  encoder  An encoder instance to set.
 319  * \param  value    See above.
 320  * \assert
 321  *    \code encoder != NULL \endcode
 322  * \retval FLAC__bool
 323  *    \c false if the encoder is already initialized, else \c true.
 324  */
 325 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 326
 327 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
 328  *
 329  * \default \c 0
 330  * \param  encoder  An encoder instance to set.
 331  * \param  value    See above.
 332  * \assert
 333  *    \code encoder != NULL \endcode
 334  * \retval FLAC__bool
 335  *    \c false if the encoder is already initialized, else \c true.
 336  */
 337 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
 338
 339 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
 340  *
 341  * \default \c false
 342  * \param  encoder  An encoder instance to set.
 343  * \param  value    See above.
 344  * \assert
 345  *    \code encoder != NULL \endcode
 346  * \retval FLAC__bool
 347  *    \c false if the encoder is already initialized, else \c true.
 348  */
 349 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 350
 351 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
 352  *
 353  * \default \c false
 354  * \param  encoder  An encoder instance to set.
 355  * \param  value    See above.
 356  * \assert
 357  *    \code encoder != NULL \endcode
 358  * \retval FLAC__bool
 359  *    \c false if the encoder is already initialized, else \c true.
 360  */
 361 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 362
 363 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
 364  *
 365  * \default \c false
 366  * \param  encoder  An encoder instance to set.
 367  * \param  value    See above.
 368  * \assert
 369  *    \code encoder != NULL \endcode
 370  * \retval FLAC__bool
 371  *    \c false if the encoder is already initialized, else \c true.
 372  */
 373 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 374
 375 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
 376  *
 377  * \default \c 0
 378  * \param  encoder  An encoder instance to set.
 379  * \param  value    See above.
 380  * \assert
 381  *    \code encoder != NULL \endcode
 382  * \retval FLAC__bool
 383  *    \c false if the encoder is already initialized, else \c true.
 384  */
 385 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 386
 387 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
 388  *
 389  * \default \c 0
 390  * \param  encoder  An encoder instance to set.
 391  * \param  value    See above.
 392  * \assert
 393  *    \code encoder != NULL \endcode
 394  * \retval FLAC__bool
 395  *    \c false if the encoder is already initialized, else \c true.
 396  */
 397 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 398
 399 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
 400  *
 401  * \default \c 0
 402  * \param  encoder  An encoder instance to set.
 403  * \param  value    See above.
 404  * \assert
 405  *    \code encoder != NULL \endcode
 406  * \retval FLAC__bool
 407  *    \c false if the encoder is already initialized, else \c true.
 408  */
 409 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
 410
 411 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
 412  *
 413  * \default \c 0
 414  * \param  encoder  An encoder instance to set.
 415  * \param  value    See above.
 416  * \assert
 417  *    \code encoder != NULL \endcode
 418  * \retval FLAC__bool
 419  *    \c false if the encoder is already initialized, else \c true.
 420  */
 421 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
 422
 423 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
 424  *
 425  * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
 426  * the second metadata block of the stream.  The encoder already supplies
 427  * the STREAMINFO block automatically.  If \a metadata does not contain a
 428  * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
 429  * \a metadata does contain a VORBIS_COMMENT block and it is not the
 430  * first, this function will reorder \a metadata by moving the
 431  * VORBIS_COMMENT block to the front; the relative ordering of the other
 432  * blocks will remain as they were.
 433  *
 434  * \note The Ogg FLAC mapping limits the number of metadata blocks per
 435  * stream to \c 65535.  If \a num_blocks exceeds this the function will
 436  * return \c false.
 437  *
 438  * \default \c NULL, 0
 439  * \param  encoder     An encoder instance to set.
 440  * \param  metadata    See above.
 441  * \param  num_blocks  See above.
 442  * \assert
 443  *    \code encoder != NULL \endcode
 444  * \retval FLAC__bool
 445  *    \c false if the encoder is already initialized, or if
 446  *    \a num_blocks > 65535, else \c true.
 447  */
 448 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 449
 450 /** Set the write callback.
 451  *  This is inherited from FLAC__StreamEncoder; see
 452  *  FLAC__stream_encoder_set_write_callback().
 453  *
 454  * \note
 455  * Unlike the FLAC stream encoder write callback, the Ogg stream
 456  * encoder write callback will be called twice when writing audio
 457  * frames; once for the page header, and once for the page body.
 458  * When writing the page header, the \a samples argument to the
 459  * write callback will be \c 0.
 460  *
 461  * \note
 462  * The callback is mandatory and must be set before initialization.
 463  *
 464  * \default \c NULL
 465  * \param  encoder  An encoder instance to set.
 466  * \param  value    See above.
 467  * \assert
 468  *    \code encoder != NULL \endcode
 469  *    \code value != NULL \endcode
 470  * \retval FLAC__bool
 471  *    \c false if the encoder is already initialized, else \c true.
 472  */
 473 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
 474
 475 /** Set the metadata callback.
 476  *  This is inherited from FLAC__StreamEncoder; see
 477  *  FLAC__stream_encoder_set_metadata_callback().
 478  *
 479  * \note
 480  * The callback is mandatory and must be set before initialization.
 481  *
 482  * \default \c NULL
 483  * \param  encoder  An encoder instance to set.
 484  * \param  value    See above.
 485  * \assert
 486  *    \code encoder != NULL \endcode
 487  *    \code value != NULL \endcode
 488  * \retval FLAC__bool
 489  *    \c false if the encoder is already initialized, else \c true.
 490  */
 491 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
 492
 493 /** Set the client data to be passed back to callbacks.
 494  *  This value will be supplied to callbacks in their \a client_data
 495  *  argument.
 496  *
 497  * \default \c NULL
 498  * \param  encoder  An encoder instance to set.
 499  * \param  value    See above.
 500  * \assert
 501  *    \code encoder != NULL \endcode
 502  * \retval FLAC__bool
 503  *    \c false if the encoder is already initialized, else \c true.
 504  */
 505 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
 506
 507 /** Get the current encoder state.
 508  *
 509  * \param  encoder  An encoder instance to query.
 510  * \assert
 511  *    \code encoder != NULL \endcode
 512  * \retval OggFLAC__StreamEncoderState
 513  *    The current encoder state.
 514  */
 515 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
 516
 517 /** Get the state of the underlying FLAC stream encoder.
 518  *  Useful when the stream encoder state is
 519  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
 520  *
 521  * \param  encoder  An encoder instance to query.
 522  * \assert
 523  *    \code encoder != NULL \endcode
 524  * \retval FLAC__StreamEncoderState
 525  *    The FLAC stream encoder state.
 526  */
 527 OggFLAC_API FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
 528
 529 /** Get the state of the underlying FLAC stream encoder's verify decoder.
 530  *  Useful when the stream encoder state is
 531  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 532  *  FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 533  *
 534  * \param  encoder  An encoder instance to query.
 535  * \assert
 536  *    \code encoder != NULL \endcode
 537  * \retval FLAC__StreamDecoderState
 538  *    The FLAC verify decoder state.
 539  */
 540 OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
 541
 542 /** Get the current encoder state as a C string.
 543  *  This version automatically resolves
 544  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR by getting the
 545  *  FLAC stream encoder's state.
 546  *
 547  * \param  encoder  A encoder instance to query.
 548  * \assert
 549  *    \code encoder != NULL \endcode
 550  * \retval const char *
 551  *    The encoder state as a C string.  Do not modify the contents.
 552  */
 553 OggFLAC_API const char *OggFLAC__stream_encoder_get_resolved_state_string(const OggFLAC__StreamEncoder *encoder);
 554
 555 /** Get relevant values about the nature of a verify decoder error.
 556  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
 557  *  Useful when the stream encoder state is
 558  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 559  *  FLAC stream encoder state is
 560  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 561  *
 562  * \param  encoder  An encoder instance to query.
 563  * \param  absolute_sample  The absolute sample number of the mismatch.
 564  * \param  frame_number  The number of the frame in which the mismatch occurred.
 565  * \param  channel       The channel in which the mismatch occurred.
 566  * \param  sample        The number of the sample (relative to the frame) in
 567  *                       which the mismatch occurred.
 568  * \param  expected      The expected value for the sample in question.
 569  * \param  got           The actual value returned by the decoder.
 570  * \assert
 571  *    \code encoder != NULL \endcode
 572  *    \code absolute_sample != NULL \endcode
 573  *    \code frame_number != NULL \endcode
 574  *    \code channel != NULL \endcode
 575  *    \code sample != NULL \endcode
 576  *    \code expected != NULL \endcode
 577  */
 578 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);
 579
 580 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
 581  *
 582  * \param  encoder  An encoder instance to query.
 583  * \assert
 584  *    \code encoder != NULL \endcode
 585  * \retval FLAC__bool
 586  *    See OggFLAC__stream_encoder_set_verify().
 587  */
 588 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
 589
 590 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
 591  *
 592  * \param  encoder  An encoder instance to query.
 593  * \assert
 594  *    \code encoder != NULL \endcode
 595  * \retval FLAC__bool
 596  *    See OggFLAC__stream_encoder_set_streamable_subset().
 597  */
 598 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
 599
 600 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
 601  *
 602  * \param  encoder  An encoder instance to query.
 603  * \assert
 604  *    \code encoder != NULL \endcode
 605  * \retval FLAC__bool
 606  *    See OggFLAC__stream_encoder_get_do_mid_side_stereo().
 607  */
 608 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 609
 610 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
 611  *
 612  * \param  encoder  An encoder instance to query.
 613  * \assert
 614  *    \code encoder != NULL \endcode
 615  * \retval FLAC__bool
 616  *    See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
 617  */
 618 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 619
 620 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
 621  *
 622  * \param  encoder  An encoder instance to query.
 623  * \assert
 624  *    \code encoder != NULL \endcode
 625  * \retval unsigned
 626  *    See OggFLAC__stream_encoder_set_channels().
 627  */
 628 OggFLAC_API unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
 629
 630 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
 631  *
 632  * \param  encoder  An encoder instance to query.
 633  * \assert
 634  *    \code encoder != NULL \endcode
 635  * \retval unsigned
 636  *    See OggFLAC__stream_encoder_set_bits_per_sample().
 637  */
 638 OggFLAC_API unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
 639
 640 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
 641  *
 642  * \param  encoder  An encoder instance to query.
 643  * \assert
 644  *    \code encoder != NULL \endcode
 645  * \retval unsigned
 646  *    See OggFLAC__stream_encoder_set_sample_rate().
 647  */
 648 OggFLAC_API unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
 649
 650 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
 651  *
 652  * \param  encoder  An encoder instance to query.
 653  * \assert
 654  *    \code encoder != NULL \endcode
 655  * \retval unsigned
 656  *    See OggFLAC__stream_encoder_set_blocksize().
 657  */
 658 OggFLAC_API unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
 659
 660 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
 661  *
 662  * \param  encoder  An encoder instance to query.
 663  * \assert
 664  *    \code encoder != NULL \endcode
 665  * \retval unsigned
 666  *    See OggFLAC__stream_encoder_set_max_lpc_order().
 667  */
 668 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
 669
 670 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
 671  *
 672  * \param  encoder  An encoder instance to query.
 673  * \assert
 674  *    \code encoder != NULL \endcode
 675  * \retval unsigned
 676  *    See OggFLAC__stream_encoder_set_qlp_coeff_precision().
 677  */
 678 OggFLAC_API unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
 679
 680 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
 681  *
 682  * \param  encoder  An encoder instance to query.
 683  * \assert
 684  *    \code encoder != NULL \endcode
 685  * \retval FLAC__bool
 686  *    See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
 687  */
 688 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
 689
 690 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
 691  *
 692  * \param  encoder  An encoder instance to query.
 693  * \assert
 694  *    \code encoder != NULL \endcode
 695  * \retval FLAC__bool
 696  *    See OggFLAC__stream_encoder_set_do_escape_coding().
 697  */
 698 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
 699
 700 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
 701  *
 702  * \param  encoder  An encoder instance to query.
 703  * \assert
 704  *    \code encoder != NULL \endcode
 705  * \retval FLAC__bool
 706  *    See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
 707  */
 708 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
 709
 710 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
 711  *
 712  * \param  encoder  An encoder instance to query.
 713  * \assert
 714  *    \code encoder != NULL \endcode
 715  * \retval unsigned
 716  *    See OggFLAC__stream_encoder_set_min_residual_partition_order().
 717  */
 718 OggFLAC_API unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 719
 720 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
 721  *
 722  * \param  encoder  An encoder instance to query.
 723  * \assert
 724  *    \code encoder != NULL \endcode
 725  * \retval unsigned
 726  *    See OggFLAC__stream_encoder_set_max_residual_partition_order().
 727  */
 728 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 729
 730 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
 731  *
 732  * \param  encoder  An encoder instance to query.
 733  * \assert
 734  *    \code encoder != NULL \endcode
 735  * \retval unsigned
 736  *    See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
 737  */
 738 OggFLAC_API unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
 739
 740 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
 741  *
 742  * \param  encoder  An encoder instance to set.
 743  * \assert
 744  *    \code encoder != NULL \endcode
 745  * \retval FLAC__uint64
 746  *    See OggFLAC__stream_encoder_get_total_samples_estimate().
 747  */
 748 OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
 749
 750 /** Initialize the encoder instance.
 751  *  Should be called after OggFLAC__stream_encoder_new() and
 752  *  OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
 753  *  or OggFLAC__stream_encoder_process_interleaved().  Will set and return
 754  *  the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
 755  *  initialization succeeded.
 756  *
 757  *  The call to OggFLAC__stream_encoder_init() currently will also immediately
 758  *  call the write callback several times, once with the \c fLaC signature,
 759  *  and once for each encoded metadata block.
 760  *
 761  * \param  encoder  An uninitialized encoder instance.
 762  * \assert
 763  *    \code encoder != NULL \endcode
 764  * \retval OggFLAC__StreamEncoderState
 765  *    \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
 766  *    OggFLAC__StreamEncoderState for the meanings of other return values.
 767  */
 768 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
 769
 770 /** Finish the encoding process.
 771  *  Flushes the encoding buffer, releases resources, resets the encoder
 772  *  settings to their defaults, and returns the encoder state to
 773  *  OggFLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
 774  *  one or more write callbacks before returning.
 775  *
 776  *  In the event of a prematurely-terminated encode, it is not strictly
 777  *  necessary to call this immediately before OggFLAC__stream_encoder_delete()
 778  *  but it is good practice to match every OggFLAC__stream_encoder_init()
 779  *  with an OggFLAC__stream_encoder_finish().
 780  *
 781  * \param  encoder  An uninitialized encoder instance.
 782  * \assert
 783  *    \code encoder != NULL \endcode
 784  */
 785 OggFLAC_API void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
 786
 787 /** Submit data for encoding.
 788  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
 789  *
 790  * \param  encoder  An initialized encoder instance in the OK state.
 791  * \param  buffer   An array of pointers to each channel's signal.
 792  * \param  samples  The number of samples in one channel.
 793  * \assert
 794  *    \code encoder != NULL \endcode
 795  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 796  * \retval FLAC__bool
 797  *    \c true if successful, else \c false; in this case, check the
 798  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 799  *    went wrong.
 800  */
 801 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 802
 803 /** Submit data for encoding.
 804  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
 805  *
 806  * \param  encoder  An initialized encoder instance in the OK state.
 807  * \param  buffer   An array of channel-interleaved data (see above).
 808  * \param  samples  The number of samples in one channel, the same as for
 809  *                  OggFLAC__stream_encoder_process().  For example, if
 810  *                  encoding two channels, \c 1000 \a samples corresponds
 811  *                  to a \a buffer of 2000 values.
 812  * \assert
 813  *    \code encoder != NULL \endcode
 814  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 815  * \retval FLAC__bool
 816  *    \c true if successful, else \c false; in this case, check the
 817  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 818  *    went wrong.
 819  */
 820 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 821
 822 /* \} */
 823
 824 #ifdef __cplusplus
 825 }
 826 #endif
 827
 828 #endif