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_apodization()
 316  *
 317  * \default \c 0
 318  * \param  encoder        An encoder instance to set.
 319  * \param  specification  See above.
 320  * \assert
 321  *    \code encoder != NULL \endcode
 322  *    \code specification != NULL \endcode
 323  * \retval FLAC__bool
 324  *    \c false if the encoder is already initialized, else \c true.
 325  */
 326 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_apodization(OggFLAC__StreamEncoder *encoder, const char *specification);
 327
 328 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
 329  *
 330  * \default \c 0
 331  * \param  encoder  An encoder instance to set.
 332  * \param  value    See above.
 333  * \assert
 334  *    \code encoder != NULL \endcode
 335  * \retval FLAC__bool
 336  *    \c false if the encoder is already initialized, else \c true.
 337  */
 338 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 339
 340 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
 341  *
 342  * \default \c 0
 343  * \param  encoder  An encoder instance to set.
 344  * \param  value    See above.
 345  * \assert
 346  *    \code encoder != NULL \endcode
 347  * \retval FLAC__bool
 348  *    \c false if the encoder is already initialized, else \c true.
 349  */
 350 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
 351
 352 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
 353  *
 354  * \default \c false
 355  * \param  encoder  An encoder instance to set.
 356  * \param  value    See above.
 357  * \assert
 358  *    \code encoder != NULL \endcode
 359  * \retval FLAC__bool
 360  *    \c false if the encoder is already initialized, else \c true.
 361  */
 362 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 363
 364 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
 365  *
 366  * \default \c false
 367  * \param  encoder  An encoder instance to set.
 368  * \param  value    See above.
 369  * \assert
 370  *    \code encoder != NULL \endcode
 371  * \retval FLAC__bool
 372  *    \c false if the encoder is already initialized, else \c true.
 373  */
 374 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 375
 376 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
 377  *
 378  * \default \c false
 379  * \param  encoder  An encoder instance to set.
 380  * \param  value    See above.
 381  * \assert
 382  *    \code encoder != NULL \endcode
 383  * \retval FLAC__bool
 384  *    \c false if the encoder is already initialized, else \c true.
 385  */
 386 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 387
 388 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
 389  *
 390  * \default \c 0
 391  * \param  encoder  An encoder instance to set.
 392  * \param  value    See above.
 393  * \assert
 394  *    \code encoder != NULL \endcode
 395  * \retval FLAC__bool
 396  *    \c false if the encoder is already initialized, else \c true.
 397  */
 398 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 399
 400 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
 401  *
 402  * \default \c 0
 403  * \param  encoder  An encoder instance to set.
 404  * \param  value    See above.
 405  * \assert
 406  *    \code encoder != NULL \endcode
 407  * \retval FLAC__bool
 408  *    \c false if the encoder is already initialized, else \c true.
 409  */
 410 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 411
 412 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
 413  *
 414  * \default \c 0
 415  * \param  encoder  An encoder instance to set.
 416  * \param  value    See above.
 417  * \assert
 418  *    \code encoder != NULL \endcode
 419  * \retval FLAC__bool
 420  *    \c false if the encoder is already initialized, else \c true.
 421  */
 422 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
 423
 424 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
 425  *
 426  * \default \c 0
 427  * \param  encoder  An encoder instance to set.
 428  * \param  value    See above.
 429  * \assert
 430  *    \code encoder != NULL \endcode
 431  * \retval FLAC__bool
 432  *    \c false if the encoder is already initialized, else \c true.
 433  */
 434 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
 435
 436 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
 437  *
 438  * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
 439  * the second metadata block of the stream.  The encoder already supplies
 440  * the STREAMINFO block automatically.  If \a metadata does not contain a
 441  * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
 442  * \a metadata does contain a VORBIS_COMMENT block and it is not the
 443  * first, this function will reorder \a metadata by moving the
 444  * VORBIS_COMMENT block to the front; the relative ordering of the other
 445  * blocks will remain as they were.
 446  *
 447  * \note The Ogg FLAC mapping limits the number of metadata blocks per
 448  * stream to \c 65535.  If \a num_blocks exceeds this the function will
 449  * return \c false.
 450  *
 451  * \default \c NULL, 0
 452  * \param  encoder     An encoder instance to set.
 453  * \param  metadata    See above.
 454  * \param  num_blocks  See above.
 455  * \assert
 456  *    \code encoder != NULL \endcode
 457  * \retval FLAC__bool
 458  *    \c false if the encoder is already initialized, or if
 459  *    \a num_blocks > 65535, else \c true.
 460  */
 461 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 462
 463 /** Set the write callback.
 464  *  This is inherited from FLAC__StreamEncoder; see
 465  *  FLAC__stream_encoder_set_write_callback().
 466  *
 467  * \note
 468  * Unlike the FLAC stream encoder write callback, the Ogg stream
 469  * encoder write callback will be called twice when writing audio
 470  * frames; once for the page header, and once for the page body.
 471  * When writing the page header, the \a samples argument to the
 472  * write callback will be \c 0.
 473  *
 474  * \note
 475  * The callback is mandatory and must be set before initialization.
 476  *
 477  * \default \c NULL
 478  * \param  encoder  An encoder instance to set.
 479  * \param  value    See above.
 480  * \assert
 481  *    \code encoder != NULL \endcode
 482  *    \code value != NULL \endcode
 483  * \retval FLAC__bool
 484  *    \c false if the encoder is already initialized, else \c true.
 485  */
 486 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
 487
 488 /** Set the metadata callback.
 489  *  This is inherited from FLAC__StreamEncoder; see
 490  *  FLAC__stream_encoder_set_metadata_callback().
 491  *
 492  * \note
 493  * The callback is mandatory and must be set before initialization.
 494  *
 495  * \default \c NULL
 496  * \param  encoder  An encoder instance to set.
 497  * \param  value    See above.
 498  * \assert
 499  *    \code encoder != NULL \endcode
 500  *    \code value != NULL \endcode
 501  * \retval FLAC__bool
 502  *    \c false if the encoder is already initialized, else \c true.
 503  */
 504 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
 505
 506 /** Set the client data to be passed back to callbacks.
 507  *  This value will be supplied to callbacks in their \a client_data
 508  *  argument.
 509  *
 510  * \default \c NULL
 511  * \param  encoder  An encoder instance to set.
 512  * \param  value    See above.
 513  * \assert
 514  *    \code encoder != NULL \endcode
 515  * \retval FLAC__bool
 516  *    \c false if the encoder is already initialized, else \c true.
 517  */
 518 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
 519
 520 /** Get the current encoder state.
 521  *
 522  * \param  encoder  An encoder instance to query.
 523  * \assert
 524  *    \code encoder != NULL \endcode
 525  * \retval OggFLAC__StreamEncoderState
 526  *    The current encoder state.
 527  */
 528 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
 529
 530 /** Get the state of the underlying FLAC stream encoder.
 531  *  Useful when the stream encoder state is
 532  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
 533  *
 534  * \param  encoder  An encoder instance to query.
 535  * \assert
 536  *    \code encoder != NULL \endcode
 537  * \retval FLAC__StreamEncoderState
 538  *    The FLAC stream encoder state.
 539  */
 540 OggFLAC_API FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
 541
 542 /** Get the state of the underlying FLAC stream encoder's verify decoder.
 543  *  Useful when the stream encoder state is
 544  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 545  *  FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 546  *
 547  * \param  encoder  An encoder instance to query.
 548  * \assert
 549  *    \code encoder != NULL \endcode
 550  * \retval FLAC__StreamDecoderState
 551  *    The FLAC verify decoder state.
 552  */
 553 OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
 554
 555 /** Get the current encoder state as a C string.
 556  *  This version automatically resolves
 557  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR by getting the
 558  *  FLAC stream encoder's state.
 559  *
 560  * \param  encoder  A encoder instance to query.
 561  * \assert
 562  *    \code encoder != NULL \endcode
 563  * \retval const char *
 564  *    The encoder state as a C string.  Do not modify the contents.
 565  */
 566 OggFLAC_API const char *OggFLAC__stream_encoder_get_resolved_state_string(const OggFLAC__StreamEncoder *encoder);
 567
 568 /** Get relevant values about the nature of a verify decoder error.
 569  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
 570  *  Useful when the stream encoder state is
 571  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 572  *  FLAC stream encoder state is
 573  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 574  *
 575  * \param  encoder  An encoder instance to query.
 576  * \param  absolute_sample  The absolute sample number of the mismatch.
 577  * \param  frame_number  The number of the frame in which the mismatch occurred.
 578  * \param  channel       The channel in which the mismatch occurred.
 579  * \param  sample        The number of the sample (relative to the frame) in
 580  *                       which the mismatch occurred.
 581  * \param  expected      The expected value for the sample in question.
 582  * \param  got           The actual value returned by the decoder.
 583  * \assert
 584  *    \code encoder != NULL \endcode
 585  *    \code absolute_sample != NULL \endcode
 586  *    \code frame_number != NULL \endcode
 587  *    \code channel != NULL \endcode
 588  *    \code sample != NULL \endcode
 589  *    \code expected != NULL \endcode
 590  */
 591 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);
 592
 593 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
 594  *
 595  * \param  encoder  An encoder instance to query.
 596  * \assert
 597  *    \code encoder != NULL \endcode
 598  * \retval FLAC__bool
 599  *    See OggFLAC__stream_encoder_set_verify().
 600  */
 601 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
 602
 603 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
 604  *
 605  * \param  encoder  An encoder instance to query.
 606  * \assert
 607  *    \code encoder != NULL \endcode
 608  * \retval FLAC__bool
 609  *    See OggFLAC__stream_encoder_set_streamable_subset().
 610  */
 611 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
 612
 613 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
 614  *
 615  * \param  encoder  An encoder instance to query.
 616  * \assert
 617  *    \code encoder != NULL \endcode
 618  * \retval FLAC__bool
 619  *    See OggFLAC__stream_encoder_get_do_mid_side_stereo().
 620  */
 621 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 622
 623 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
 624  *
 625  * \param  encoder  An encoder instance to query.
 626  * \assert
 627  *    \code encoder != NULL \endcode
 628  * \retval FLAC__bool
 629  *    See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
 630  */
 631 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 632
 633 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
 634  *
 635  * \param  encoder  An encoder instance to query.
 636  * \assert
 637  *    \code encoder != NULL \endcode
 638  * \retval unsigned
 639  *    See OggFLAC__stream_encoder_set_channels().
 640  */
 641 OggFLAC_API unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
 642
 643 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
 644  *
 645  * \param  encoder  An encoder instance to query.
 646  * \assert
 647  *    \code encoder != NULL \endcode
 648  * \retval unsigned
 649  *    See OggFLAC__stream_encoder_set_bits_per_sample().
 650  */
 651 OggFLAC_API unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
 652
 653 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
 654  *
 655  * \param  encoder  An encoder instance to query.
 656  * \assert
 657  *    \code encoder != NULL \endcode
 658  * \retval unsigned
 659  *    See OggFLAC__stream_encoder_set_sample_rate().
 660  */
 661 OggFLAC_API unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
 662
 663 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
 664  *
 665  * \param  encoder  An encoder instance to query.
 666  * \assert
 667  *    \code encoder != NULL \endcode
 668  * \retval unsigned
 669  *    See OggFLAC__stream_encoder_set_blocksize().
 670  */
 671 OggFLAC_API unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
 672
 673 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
 674  *
 675  * \param  encoder  An encoder instance to query.
 676  * \assert
 677  *    \code encoder != NULL \endcode
 678  * \retval unsigned
 679  *    See OggFLAC__stream_encoder_set_max_lpc_order().
 680  */
 681 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
 682
 683 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
 684  *
 685  * \param  encoder  An encoder instance to query.
 686  * \assert
 687  *    \code encoder != NULL \endcode
 688  * \retval unsigned
 689  *    See OggFLAC__stream_encoder_set_qlp_coeff_precision().
 690  */
 691 OggFLAC_API unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
 692
 693 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
 694  *
 695  * \param  encoder  An encoder instance to query.
 696  * \assert
 697  *    \code encoder != NULL \endcode
 698  * \retval FLAC__bool
 699  *    See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
 700  */
 701 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
 702
 703 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
 704  *
 705  * \param  encoder  An encoder instance to query.
 706  * \assert
 707  *    \code encoder != NULL \endcode
 708  * \retval FLAC__bool
 709  *    See OggFLAC__stream_encoder_set_do_escape_coding().
 710  */
 711 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
 712
 713 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
 714  *
 715  * \param  encoder  An encoder instance to query.
 716  * \assert
 717  *    \code encoder != NULL \endcode
 718  * \retval FLAC__bool
 719  *    See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
 720  */
 721 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
 722
 723 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
 724  *
 725  * \param  encoder  An encoder instance to query.
 726  * \assert
 727  *    \code encoder != NULL \endcode
 728  * \retval unsigned
 729  *    See OggFLAC__stream_encoder_set_min_residual_partition_order().
 730  */
 731 OggFLAC_API unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 732
 733 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
 734  *
 735  * \param  encoder  An encoder instance to query.
 736  * \assert
 737  *    \code encoder != NULL \endcode
 738  * \retval unsigned
 739  *    See OggFLAC__stream_encoder_set_max_residual_partition_order().
 740  */
 741 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 742
 743 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
 744  *
 745  * \param  encoder  An encoder instance to query.
 746  * \assert
 747  *    \code encoder != NULL \endcode
 748  * \retval unsigned
 749  *    See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
 750  */
 751 OggFLAC_API unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
 752
 753 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
 754  *
 755  * \param  encoder  An encoder instance to set.
 756  * \assert
 757  *    \code encoder != NULL \endcode
 758  * \retval FLAC__uint64
 759  *    See OggFLAC__stream_encoder_get_total_samples_estimate().
 760  */
 761 OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
 762
 763 /** Initialize the encoder instance.
 764  *  Should be called after OggFLAC__stream_encoder_new() and
 765  *  OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
 766  *  or OggFLAC__stream_encoder_process_interleaved().  Will set and return
 767  *  the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
 768  *  initialization succeeded.
 769  *
 770  *  The call to OggFLAC__stream_encoder_init() currently will also immediately
 771  *  call the write callback several times, once with the \c fLaC signature,
 772  *  and once for each encoded metadata block.
 773  *
 774  * \param  encoder  An uninitialized encoder instance.
 775  * \assert
 776  *    \code encoder != NULL \endcode
 777  * \retval OggFLAC__StreamEncoderState
 778  *    \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
 779  *    OggFLAC__StreamEncoderState for the meanings of other return values.
 780  */
 781 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
 782
 783 /** Finish the encoding process.
 784  *  Flushes the encoding buffer, releases resources, resets the encoder
 785  *  settings to their defaults, and returns the encoder state to
 786  *  OggFLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
 787  *  one or more write callbacks before returning.
 788  *
 789  *  In the event of a prematurely-terminated encode, it is not strictly
 790  *  necessary to call this immediately before OggFLAC__stream_encoder_delete()
 791  *  but it is good practice to match every OggFLAC__stream_encoder_init()
 792  *  with an OggFLAC__stream_encoder_finish().
 793  *
 794  * \param  encoder  An uninitialized encoder instance.
 795  * \assert
 796  *    \code encoder != NULL \endcode
 797  */
 798 OggFLAC_API void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
 799
 800 /** Submit data for encoding.
 801  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
 802  *
 803  * \param  encoder  An initialized encoder instance in the OK state.
 804  * \param  buffer   An array of pointers to each channel's signal.
 805  * \param  samples  The number of samples in one channel.
 806  * \assert
 807  *    \code encoder != NULL \endcode
 808  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 809  * \retval FLAC__bool
 810  *    \c true if successful, else \c false; in this case, check the
 811  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 812  *    went wrong.
 813  */
 814 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 815
 816 /** Submit data for encoding.
 817  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
 818  *
 819  * \param  encoder  An initialized encoder instance in the OK state.
 820  * \param  buffer   An array of channel-interleaved data (see above).
 821  * \param  samples  The number of samples in one channel, the same as for
 822  *                  OggFLAC__stream_encoder_process().  For example, if
 823  *                  encoding two channels, \c 1000 \a samples corresponds
 824  *                  to a \a buffer of 2000 values.
 825  * \assert
 826  *    \code encoder != NULL \endcode
 827  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 828  * \retval FLAC__bool
 829  *    \c true if successful, else \c false; in this case, check the
 830  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 831  *    went wrong.
 832  */
 833 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 834
 835 /* \} */
 836
 837 #ifdef __cplusplus
 838 }
 839 #endif
 840
 841 #endif