include/OggFLAC/file_encoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
   2  * Copyright (C) 2002,2003  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__FILE_ENCODER_H
  33 #define OggFLAC__FILE_ENCODER_H
  34
  35 #include "export.h"
  36 #include "seekable_stream_encoder.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42
  43 /** \file include/OggFLAC/file_encoder.h
  44  *
  45  *  \brief
  46  *  This module contains the functions which implement the file
  47  *  encoder.
  48  *
  49  *  See the detailed documentation in the
  50  *  \link oggflac_file_encoder file encoder \endlink module.
  51  */
  52
  53 /** \defgroup oggflac_file_encoder OggFLAC/file_encoder.h: file encoder interface
  54  *  \ingroup oggflac_encoder
  55  *
  56  *  \brief
  57  *  This module contains the functions which implement the file
  58  *  encoder.  Unlink the Ogg stream and seekable stream encoders, which
  59  *  derive from their FLAC counterparts, the Ogg file encoder is derived
  60  *  from the Ogg seekable stream encoder.
  61  *
  62  * The interface here is nearly identical to FLAC's file
  63  * encoder, including the callbacks, with the addition of
  64  * OggFLAC__file_encoder_set_serial_number().  See the
  65  * \link flac_file_encoder FLAC file encoder module \endlink
  66  * for full documentation.
  67  *
  68  * \{
  69  */
  70
  71
  72 /** State values for a OggFLAC__FileEncoder
  73  *
  74  *  The encoder's state can be obtained by calling OggFLAC__file_encoder_get_state().
  75  */
  76 typedef enum {
  77
  78         OggFLAC__FILE_ENCODER_OK = 0,
  79         /**< The encoder is in the normal OK state. */
  80
  81         OggFLAC__FILE_ENCODER_NO_FILENAME,
  82         /**< OggFLAC__file_encoder_init() was called without first calling
  83          * OggFLAC__file_encoder_set_filename().
  84          */
  85
  86         OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
  87         /**< An error occurred in the underlying seekable stream encoder;
  88          * check OggFLAC__file_encoder_get_seekable_stream_encoder_state().
  89          */
  90
  91         OggFLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
  92         /**< A fatal error occurred while writing to the encoded file. */
  93
  94         OggFLAC__FILE_ENCODER_ERROR_OPENING_FILE,
  95         /**< An error occurred opening the output file for writing. */
  96
  97         OggFLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
  98         /**< Memory allocation failed. */
  99
 100         OggFLAC__FILE_ENCODER_ALREADY_INITIALIZED,
 101         /**< OggFLAC__file_encoder_init() was called when the encoder was
 102          * already initialized, usually because
 103          * OggFLAC__file_encoder_finish() was not called.
 104          */
 105
 106         OggFLAC__FILE_ENCODER_UNINITIALIZED
 107         /**< The encoder is in the uninitialized state. */
 108
 109 } OggFLAC__FileEncoderState;
 110
 111 /** Maps a FLAC__FileEncoderState to a C string.
 112  *
 113  *  Using a FLAC__FileEncoderState as the index to this array
 114  *  will give the string equivalent.  The contents should not be modified.
 115  */
 116 extern OggFLAC_API const char * const OggFLAC__FileEncoderStateString[];
 117
 118
 119 /***********************************************************************
 120  *
 121  * class FLAC__FileEncoder
 122  *
 123  ***********************************************************************/
 124
 125 struct OggFLAC__FileEncoderProtected;
 126 struct OggFLAC__FileEncoderPrivate;
 127 /** The opaque structure definition for the file encoder type.
 128  *  See the \link oggflac_file_encoder file encoder module \endlink
 129  *  for a detailed description.
 130  */
 131 typedef struct {
 132         struct OggFLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 133         struct OggFLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 134 } OggFLAC__FileEncoder;
 135
 136 /** Signature for the progress callback.
 137  *  See OggFLAC__file_encoder_set_progress_callback()
 138  *  and FLAC__FileEncoderProgressCallback for more info.
 139  *
 140  * \param  encoder          The encoder instance calling the callback.
 141  * \param  bytes_written    Bytes written so far.
 142  * \param  samples_written  Samples written so far.
 143  * \param  frames_written   Frames written so far.
 144  * \param  total_frames_estimate  The estimate of the total number of
 145  *                                frames to be written.
 146  * \param  client_data      The callee's client data set through
 147  *                          OggFLAC__file_encoder_set_client_data().
 148  */
 149 typedef void (*OggFLAC__FileEncoderProgressCallback)(const OggFLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
 150
 151
 152 /***********************************************************************
 153  *
 154  * Class constructor/destructor
 155  *
 156  ***********************************************************************/
 157
 158 /** Create a new file encoder instance.  The instance is created with
 159  *  default settings; see the individual OggFLAC__file_encoder_set_*()
 160  *  functions for each setting's default.
 161  *
 162  * \retval OggFLAC__FileEncoder*
 163  *    \c NULL if there was an error allocating memory, else the new instance.
 164  */
 165 OggFLAC_API OggFLAC__FileEncoder *OggFLAC__file_encoder_new();
 166
 167 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 168  *
 169  * \param encoder  A pointer to an existing encoder.
 170  * \assert
 171  *    \code encoder != NULL \endcode
 172  */
 173 OggFLAC_API void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder);
 174
 175 /***********************************************************************
 176  *
 177  * Public class method prototypes
 178  *
 179  ***********************************************************************/
 180
 181 /** Set the serial number for the FLAC stream.
 182  *
 183  * \default \c NULL, 0
 184  * \param  encoder        An encoder instance to set.
 185  * \param  serial_number  See above.
 186  * \assert
 187  *    \code encoder != NULL \endcode
 188  * \retval FLAC__bool
 189  *    \c false if the encoder is already initialized, else \c true.
 190  */
 191 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_serial_number(OggFLAC__FileEncoder *encoder, long serial_number);
 192
 193 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 194  *  OggFLAC__seekable_stream_encoder_set_verify().
 195  *
 196  * \default \c true
 197  * \param  encoder  An encoder instance to set.
 198  * \param  value    See above.
 199  * \assert
 200  *    \code encoder != NULL \endcode
 201  * \retval FLAC__bool
 202  *    \c false if the encoder is already initialized, else \c true.
 203  */
 204 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_verify(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 205
 206 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 207  *  OggFLAC__seekable_stream_encoder_set_streamable_subset().
 208  *
 209  * \default \c true
 210  * \param  encoder  An encoder instance to set.
 211  * \param  value    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__file_encoder_set_streamable_subset(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 218
 219 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 220  *  OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo().
 221  *
 222  * \default \c false
 223  * \param  encoder  An encoder instance to set.
 224  * \param  value    See above.
 225  * \assert
 226  *    \code encoder != NULL \endcode
 227  * \retval FLAC__bool
 228  *    \c false if the encoder is already initialized, else \c true.
 229  */
 230 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 231
 232 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 233  *  OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
 234  *
 235  * \default \c false
 236  * \param  encoder  An encoder instance to set.
 237  * \param  value    See above.
 238  * \assert
 239  *    \code encoder != NULL \endcode
 240  * \retval FLAC__bool
 241  *    \c false if the encoder is already initialized, else \c true.
 242  */
 243 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 244
 245 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 246  *  OggFLAC__seekable_stream_encoder_set_channels().
 247  *
 248  * \default \c 2
 249  * \param  encoder  An encoder instance to set.
 250  * \param  value    See above.
 251  * \assert
 252  *    \code encoder != NULL \endcode
 253  * \retval FLAC__bool
 254  *    \c false if the encoder is already initialized, else \c true.
 255  */
 256 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_channels(OggFLAC__FileEncoder *encoder, unsigned value);
 257
 258 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 259  *  OggFLAC__seekable_stream_encoder_set_bits_per_sample().
 260  *
 261  * \warning
 262  * Do not feed the encoder data that is wider than the value you
 263  * set here or you will generate an invalid stream.
 264  *
 265  * \default \c 16
 266  * \param  encoder  An encoder instance to set.
 267  * \param  value    See above.
 268  * \assert
 269  *    \code encoder != NULL \endcode
 270  * \retval FLAC__bool
 271  *    \c false if the encoder is already initialized, else \c true.
 272  */
 273 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_bits_per_sample(OggFLAC__FileEncoder *encoder, unsigned value);
 274
 275 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 276  *  OggFLAC__seekable_stream_encoder_set_sample_rate().
 277  *
 278  * \default \c 44100
 279  * \param  encoder  An encoder instance to set.
 280  * \param  value    See above.
 281  * \assert
 282  *    \code encoder != NULL \endcode
 283  * \retval FLAC__bool
 284  *    \c false if the encoder is already initialized, else \c true.
 285  */
 286 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_sample_rate(OggFLAC__FileEncoder *encoder, unsigned value);
 287
 288 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 289  *  OggFLAC__seekable_stream_encoder_set_blocksize().
 290  *
 291  * \default \c 1152
 292  * \param  encoder  An encoder instance to set.
 293  * \param  value    See above.
 294  * \assert
 295  *    \code encoder != NULL \endcode
 296  * \retval FLAC__bool
 297  *    \c false if the encoder is already initialized, else \c true.
 298  */
 299 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, unsigned value);
 300
 301 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 302  *  OggFLAC__seekable_stream_encoder_set_max_lpc_order().
 303  *
 304  * \default \c 0
 305  * \param  encoder  An encoder instance to set.
 306  * \param  value    See above.
 307  * \assert
 308  *    \code encoder != NULL \endcode
 309  * \retval FLAC__bool
 310  *    \c false if the encoder is already initialized, else \c true.
 311  */
 312 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_max_lpc_order(OggFLAC__FileEncoder *encoder, unsigned value);
 313
 314 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 315  *  OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision().
 316  *
 317  * \note
 318  * In the current implementation, qlp_coeff_precision + bits_per_sample must
 319  * be less than 32.
 320  *
 321  * \default \c 0
 322  * \param  encoder  An encoder instance to set.
 323  * \param  value    See above.
 324  * \assert
 325  *    \code encoder != NULL \endcode
 326  * \retval FLAC__bool
 327  *    \c false if the encoder is already initialized, else \c true.
 328  */
 329 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision(OggFLAC__FileEncoder *encoder, unsigned value);
 330
 331 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 332  *  OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
 333  *
 334  * \default \c false
 335  * \param  encoder  An encoder instance to set.
 336  * \param  value    See above.
 337  * \assert
 338  *    \code encoder != NULL \endcode
 339  * \retval FLAC__bool
 340  *    \c false if the encoder is already initialized, else \c true.
 341  */
 342 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 343
 344 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 345  *  OggFLAC__seekable_stream_encoder_set_do_escape_coding().
 346  *
 347  * \default \c false
 348  * \param  encoder  An encoder instance to set.
 349  * \param  value    See above.
 350  * \assert
 351  *    \code encoder != NULL \endcode
 352  * \retval FLAC__bool
 353  *    \c false if the encoder is already initialized, else \c true.
 354  */
 355 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_escape_coding(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 356
 357 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 358  *  OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
 359  *
 360  * \default \c false
 361  * \param  encoder  An encoder instance to set.
 362  * \param  value    See above.
 363  * \assert
 364  *    \code encoder != NULL \endcode
 365  * \retval FLAC__bool
 366  *    \c false if the encoder is already initialized, else \c true.
 367  */
 368 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search(OggFLAC__FileEncoder *encoder, FLAC__bool value);
 369
 370 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 371  *  OggFLAC__seekable_stream_encoder_set_min_residual_partition_order().
 372  *
 373  * \default \c 0
 374  * \param  encoder  An encoder instance to set.
 375  * \param  value    See above.
 376  * \assert
 377  *    \code encoder != NULL \endcode
 378  * \retval FLAC__bool
 379  *    \c false if the encoder is already initialized, else \c true.
 380  */
 381 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value);
 382
 383 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 384  *  OggFLAC__seekable_stream_encoder_set_max_residual_partition_order().
 385  *
 386  * \default \c 0
 387  * \param  encoder  An encoder instance to set.
 388  * \param  value    See above.
 389  * \assert
 390  *    \code encoder != NULL \endcode
 391  * \retval FLAC__bool
 392  *    \c false if the encoder is already initialized, else \c true.
 393  */
 394 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value);
 395
 396 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 397  *  OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
 398  *
 399  * \default \c 0
 400  * \param  encoder  An encoder instance to set.
 401  * \param  value    See above.
 402  * \assert
 403  *    \code encoder != NULL \endcode
 404  * \retval FLAC__bool
 405  *    \c false if the encoder is already initialized, else \c true.
 406  */
 407 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist(OggFLAC__FileEncoder *encoder, unsigned value);
 408
 409 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 410  *  OggFLAC__seekable_stream_encoder_set_total_samples_estimate().
 411  *
 412  * \default \c 0
 413  * \param  encoder  An encoder instance to set.
 414  * \param  value    See above.
 415  * \assert
 416  *    \code encoder != NULL \endcode
 417  * \retval FLAC__bool
 418  *    \c false if the encoder is already initialized, else \c true.
 419  */
 420 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate(OggFLAC__FileEncoder *encoder, FLAC__uint64 value);
 421
 422 /** This is inherited from OggFLAC__SeekableStreamEncoder; see
 423  *  OggFLAC__seekable_stream_encoder_set_metadata().
 424  *
 425  * \default \c NULL, 0
 426  * \param  encoder     An encoder instance to set.
 427  * \param  metadata    See above.
 428  * \param  num_blocks  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__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 435
 436 /** Set the output file name encode to.
 437  *
 438  * \note
 439  * The filename is mandatory and must be set before initialization.
 440  *
 441  * \note
 442  * Unlike the OggFLAC__FileDecoder, the filename does not interpret "-" for
 443  * \c stdout; writing to \c stdout is not relevant in the file encoder.
 444  *
 445  * \default \c NULL
 446  * \param  encoder  A encoder instance to set.
 447  * \param  value    The output file name.
 448  * \assert
 449  *    \code encoder != NULL \endcode
 450  *    \code value != NULL \endcode
 451  * \retval FLAC__bool
 452  *    \c false if the encoder is already initialized, or there was a memory
 453  *    allocation error, else \c true.
 454  */
 455 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_filename(OggFLAC__FileEncoder *encoder, const char *value);
 456
 457 /** Set the progress callback.
 458  *  The supplied function will be called when the encoder has finished
 459  *  writing a frame.  The \c total_frames_estimate argument to the callback
 460  *  will be based on the value from
 461  *  OggFLAC__file_encoder_set_total_samples_estimate().
 462  *
 463  * \note
 464  * Unlike most other callbacks, the progress callback is \b not mandatory
 465  * and need not be set before initialization.
 466  *
 467  * \default \c NULL
 468  * \param  encoder  An encoder instance to set.
 469  * \param  value    See above.
 470  * \assert
 471  *    \code encoder != NULL \endcode
 472  *    \code value != NULL \endcode
 473  * \retval FLAC__bool
 474  *    \c false if the encoder is already initialized, else \c true.
 475  */
 476 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_progress_callback(OggFLAC__FileEncoder *encoder, OggFLAC__FileEncoderProgressCallback value);
 477
 478 /** Set the client data to be passed back to callbacks.
 479  *  This value will be supplied to callbacks in their \a client_data
 480  *  argument.
 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  * \retval FLAC__bool
 488  *    \c false if the encoder is already initialized, else \c true.
 489  */
 490 OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_client_data(OggFLAC__FileEncoder *encoder, void *value);
 491
 492 /** Get the current encoder state.
 493  *
 494  * \param  encoder  An encoder instance to query.
 495  * \assert
 496  *    \code encoder != NULL \endcode
 497  * \retval FLAC__FileEncoderState
 498  *    The current encoder state.
 499  */
 500 OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_get_state(const OggFLAC__FileEncoder *encoder);
 501
 502 /** Get the state of the underlying seekable stream encoder.
 503  *  Useful when the file encoder state is
 504  *  \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
 505  *
 506  * \param  encoder  An encoder instance to query.
 507  * \assert
 508  *    \code encoder != NULL \endcode
 509  * \retval OggFLAC__SeekableStreamEncoderState
 510  *    The seekable stream encoder state.
 511  */
 512 OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
 513
 514 /** Get the state of the underlying FLAC stream encoder.
 515  *  Useful when the file encoder state is
 516  *  \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR
 517  *  and the seekable stream encoder state is
 518  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
 519  *
 520  * \param  encoder  An encoder instance to query.
 521  * \assert
 522  *    \code encoder != NULL \endcode
 523  * \retval FLAC__StreamEncoderState
 524  *    The seekable stream encoder state.
 525  */
 526 OggFLAC_API FLAC__StreamEncoderState OggFLAC__file_encoder_get_FLAC_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
 527
 528 /** Get the state of the underlying stream encoder's verify decoder.
 529  *  Useful when the file encoder state is
 530  *  \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR
 531  *  and the seekable stream encoder state is
 532  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
 533  *  and the FLAC stream encoder state is
 534  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 535  *
 536  * \param  encoder  An encoder instance to query.
 537  * \assert
 538  *    \code encoder != NULL \endcode
 539  * \retval FLAC__StreamDecoderState
 540  *    The stream encoder state.
 541  */
 542 OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder);
 543
 544 /** Get the current encoder state as a C string.
 545  *  This version automatically resolves
 546  *  \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
 547  *  seekable stream encoder's state.
 548  *
 549  * \param  encoder  A encoder instance to query.
 550  * \assert
 551  *    \code encoder != NULL \endcode
 552  * \retval const char *
 553  *    The encoder state as a C string.  Do not modify the contents.
 554  */
 555 OggFLAC_API const char *OggFLAC__file_encoder_get_resolved_state_string(const OggFLAC__FileEncoder *encoder);
 556
 557 /** Get relevant values about the nature of a verify decoder error.
 558  *  Inherited from OggFLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
 559  *  Useful when the file encoder state is
 560  *  \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR
 561  *  and the seekable stream encoder state is
 562  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR
 563  *  and the FLAC seekable stream encoder state is
 564  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR
 565  *  and the FLAC stream encoder state is
 566  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 567  *
 568  * \param  encoder  An encoder instance to query.
 569  * \param  absolute_sample  The absolute sample number of the mismatch.
 570  * \param  frame_number  The number of the frame in which the mismatch occurred.
 571  * \param  channel       The channel in which the mismatch occurred.
 572  * \param  sample        The number of the sample (relative to the frame) in
 573  *                       which the mismatch occurred.
 574  * \param  expected      The expected value for the sample in question.
 575  * \param  got           The actual value returned by the decoder.
 576  * \assert
 577  *    \code encoder != NULL \endcode
 578  */
 579 OggFLAC_API void OggFLAC__file_encoder_get_verify_decoder_error_stats(const OggFLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 580
 581 /** Get the "verify" flag.
 582  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 583  *  OggFLAC__seekable_stream_encoder_get_verify().
 584  *
 585  * \param  encoder  An encoder instance to query.
 586  * \assert
 587  *    \code encoder != NULL \endcode
 588  * \retval FLAC__bool
 589  *    See OggFLAC__file_encoder_set_verify().
 590  */
 591 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_verify(const OggFLAC__FileEncoder *encoder);
 592
 593 /** Get the "streamable subset" flag.
 594  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 595  *  OggFLAC__seekable_stream_encoder_get_streamable_subset().
 596  *
 597  * \param  encoder  An encoder instance to query.
 598  * \assert
 599  *    \code encoder != NULL \endcode
 600  * \retval FLAC__bool
 601  *    See OggFLAC__file_encoder_set_streamable_subset().
 602  */
 603 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_streamable_subset(const OggFLAC__FileEncoder *encoder);
 604
 605 /** Get the "mid/side stereo coding" flag.
 606  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 607  *  OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo().
 608  *
 609  * \param  encoder  An encoder instance to query.
 610  * \assert
 611  *    \code encoder != NULL \endcode
 612  * \retval FLAC__bool
 613  *    See OggFLAC__file_encoder_get_do_mid_side_stereo().
 614  */
 615 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo(const OggFLAC__FileEncoder *encoder);
 616
 617 /** Get the "adaptive mid/side switching" flag.
 618  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 619  *  OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
 620  *
 621  * \param  encoder  An encoder instance to query.
 622  * \assert
 623  *    \code encoder != NULL \endcode
 624  * \retval FLAC__bool
 625  *    See OggFLAC__file_encoder_set_loose_mid_side_stereo().
 626  */
 627 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo(const OggFLAC__FileEncoder *encoder);
 628
 629 /** Get the number of input channels being processed.
 630  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 631  *  OggFLAC__seekable_stream_encoder_get_channels().
 632  *
 633  * \param  encoder  An encoder instance to query.
 634  * \assert
 635  *    \code encoder != NULL \endcode
 636  * \retval unsigned
 637  *    See FLAC__file_encoder_set_channels().
 638  */
 639 OggFLAC_API unsigned OggFLAC__file_encoder_get_channels(const OggFLAC__FileEncoder *encoder);
 640
 641 /** Get the input sample resolution setting.
 642  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 643  *  OggFLAC__seekable_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__file_encoder_set_bits_per_sample().
 650  */
 651 OggFLAC_API unsigned OggFLAC__file_encoder_get_bits_per_sample(const OggFLAC__FileEncoder *encoder);
 652
 653 /** Get the input sample rate setting.
 654  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 655  *  OggFLAC__seekable_stream_encoder_get_sample_rate().
 656  *
 657  * \param  encoder  An encoder instance to query.
 658  * \assert
 659  *    \code encoder != NULL \endcode
 660  * \retval unsigned
 661  *    See OggFLAC__file_encoder_set_sample_rate().
 662  */
 663 OggFLAC_API unsigned OggFLAC__file_encoder_get_sample_rate(const OggFLAC__FileEncoder *encoder);
 664
 665 /** Get the blocksize setting.
 666  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 667  *  OggFLAC__seekable_stream_encoder_get_blocksize().
 668  *
 669  * \param  encoder  An encoder instance to query.
 670  * \assert
 671  *    \code encoder != NULL \endcode
 672  * \retval unsigned
 673  *    See OggFLAC__file_encoder_set_blocksize().
 674  */
 675 OggFLAC_API unsigned OggFLAC__file_encoder_get_blocksize(const OggFLAC__FileEncoder *encoder);
 676
 677 /** Get the maximum LPC order setting.
 678  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 679  *  OggFLAC__seekable_stream_encoder_get_max_lpc_order().
 680  *
 681  * \param  encoder  An encoder instance to query.
 682  * \assert
 683  *    \code encoder != NULL \endcode
 684  * \retval unsigned
 685  *    See OggFLAC__file_encoder_set_max_lpc_order().
 686  */
 687 OggFLAC_API unsigned OggFLAC__file_encoder_get_max_lpc_order(const OggFLAC__FileEncoder *encoder);
 688
 689 /** Get the quantized linear predictor coefficient precision setting.
 690  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 691  *  OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision().
 692  *
 693  * \param  encoder  An encoder instance to query.
 694  * \assert
 695  *    \code encoder != NULL \endcode
 696  * \retval unsigned
 697  *    See OggFLAC__file_encoder_set_qlp_coeff_precision().
 698  */
 699 OggFLAC_API unsigned OggFLAC__file_encoder_get_qlp_coeff_precision(const OggFLAC__FileEncoder *encoder);
 700
 701 /** Get the qlp coefficient precision search flag.
 702  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 703  *  OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
 704  *
 705  * \param  encoder  An encoder instance to query.
 706  * \assert
 707  *    \code encoder != NULL \endcode
 708  * \retval FLAC__bool
 709  *    See OggFLAC__file_encoder_set_do_qlp_coeff_prec_search().
 710  */
 711 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__FileEncoder *encoder);
 712
 713 /** Get the "escape coding" flag.
 714  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 715  *  OggFLAC__seekable_stream_encoder_get_do_escape_coding().
 716  *
 717  * \param  encoder  An encoder instance to query.
 718  * \assert
 719  *    \code encoder != NULL \endcode
 720  * \retval FLAC__bool
 721  *    See OggFLAC__file_encoder_set_do_escape_coding().
 722  */
 723 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_escape_coding(const OggFLAC__FileEncoder *encoder);
 724
 725 /** Get the exhaustive model search flag.
 726  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 727  *  OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
 728  *
 729  * \param  encoder  An encoder instance to query.
 730  * \assert
 731  *    \code encoder != NULL \endcode
 732  * \retval FLAC__bool
 733  *    See OggFLAC__file_encoder_set_do_exhaustive_model_search().
 734  */
 735 OggFLAC_API FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search(const OggFLAC__FileEncoder *encoder);
 736
 737 /** Get the minimum residual partition order setting.
 738  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 739  *  OggFLAC__seekable_stream_encoder_get_min_residual_partition_order().
 740  *
 741  * \param  encoder  An encoder instance to query.
 742  * \assert
 743  *    \code encoder != NULL \endcode
 744  * \retval unsigned
 745  *    See OggFLAC__file_encoder_set_min_residual_partition_order().
 746  */
 747 OggFLAC_API unsigned OggFLAC__file_encoder_get_min_residual_partition_order(const OggFLAC__FileEncoder *encoder);
 748
 749 /** Get maximum residual partition order setting.
 750  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 751  *  OggFLAC__seekable_stream_encoder_get_max_residual_partition_order().
 752  *
 753  * \param  encoder  An encoder instance to query.
 754  * \assert
 755  *    \code encoder != NULL \endcode
 756  * \retval unsigned
 757  *    See OggFLAC__file_encoder_set_max_residual_partition_order().
 758  */
 759 OggFLAC_API unsigned OggFLAC__file_encoder_get_max_residual_partition_order(const OggFLAC__FileEncoder *encoder);
 760
 761 /** Get the Rice parameter search distance setting.
 762  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 763  *  OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
 764  *
 765  * \param  encoder  An encoder instance to query.
 766  * \assert
 767  *    \code encoder != NULL \endcode
 768  * \retval unsigned
 769  *    See OggFLAC__file_encoder_set_rice_parameter_search_dist().
 770  */
 771 OggFLAC_API unsigned OggFLAC__file_encoder_get_rice_parameter_search_dist(const OggFLAC__FileEncoder *encoder);
 772
 773 /** Get the previously set estimate of the total samples to be encoded.
 774  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 775  *  OggFLAC__seekable_stream_encoder_get_total_samples_estimate().
 776  *
 777  * \param  encoder  An encoder instance to query.
 778  * \assert
 779  *    \code encoder != NULL \endcode
 780  * \retval FLAC__uint64
 781  *    See OggFLAC__file_encoder_set_total_samples_estimate().
 782  */
 783 OggFLAC_API FLAC__uint64 OggFLAC__file_encoder_get_total_samples_estimate(const OggFLAC__FileEncoder *encoder);
 784
 785 /** Initialize the encoder instance.
 786  *  Should be called after OggFLAC__file_encoder_new() and
 787  *  OggFLAC__file_encoder_set_*() but before OggFLAC__file_encoder_process()
 788  *  or OggFLAC__file_encoder_process_interleaved().  Will set and return
 789  *  the encoder state, which will be OggFLAC__FILE_ENCODER_OK if
 790  *  initialization succeeded.
 791  *
 792  * \param  encoder  An uninitialized encoder instance.
 793  * \assert
 794  *    \code encoder != NULL \endcode
 795  * \retval OggFLAC__FileEncoderState
 796  *    \c OggFLAC__FILE_ENCODER_OK if initialization was successful; see
 797  *    OggFLAC__FileEncoderState for the meanings of other return values.
 798  */
 799 OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encoder);
 800
 801 /** Finish the encoding process.
 802  *  Flushes the encoding buffer, releases resources, resets the encoder
 803  *  settings to their defaults, and returns the encoder state to
 804  *  OggFLAC__FILE_ENCODER_UNINITIALIZED.
 805  *
 806  *  In the event of a prematurely-terminated encode, it is not strictly
 807  *  necessary to call this immediately before OggFLAC__file_encoder_delete()
 808  *  but it is good practice to match every OggFLAC__file_encoder_init()
 809  *  with a OggFLAC__file_encoder_finish().
 810  *
 811  * \param  encoder  An uninitialized encoder instance.
 812  * \assert
 813  *    \code encoder != NULL \endcode
 814  */
 815 OggFLAC_API void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder);
 816
 817 /** Submit data for encoding.
 818  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 819  *  OggFLAC__seekable_stream_encoder_process().
 820  *
 821  * \param  encoder  An initialized encoder instance in the OK state.
 822  * \param  buffer   An array of pointers to each channel's signal.
 823  * \param  samples  The number of samples in one channel.
 824  * \assert
 825  *    \code encoder != NULL \endcode
 826  *    \code OggFLAC__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK \endcode
 827  * \retval FLAC__bool
 828  *    \c true if successful, else \c false; in this case, check the
 829  *    encoder state with OggFLAC__file_encoder_get_state() to see what
 830  *    went wrong.
 831  */
 832 OggFLAC_API FLAC__bool OggFLAC__file_encoder_process(OggFLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 833
 834 /** Submit data for encoding.
 835  *  This is inherited from OggFLAC__SeekableStreamEncoder; see
 836  *  OggFLAC__seekable_stream_encoder_process_interleaved().
 837  *
 838  * \param  encoder  An initialized encoder instance in the OK state.
 839  * \param  buffer   An array of channel-interleaved data (see above).
 840  * \param  samples  The number of samples in one channel, the same as for
 841  *                  OggFLAC__file_encoder_process().  For example, if
 842  *                  encoding two channels, \c 1000 \a samples corresponds
 843  *                  to a \a buffer of 2000 values.
 844  * \assert
 845  *    \code encoder != NULL \endcode
 846  *    \code OggFLAC__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK \endcode
 847  * \retval FLAC__bool
 848  *    \c true if successful, else \c false; in this case, check the
 849  *    encoder state with OggFLAC__file_encoder_get_state() to see what
 850  *    went wrong.
 851  */
 852 OggFLAC_API FLAC__bool OggFLAC__file_encoder_process_interleaved(OggFLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 853
 854 /* \} */
 855
 856 #ifdef __cplusplus
 857 }
 858 #endif
 859
 860 #endif