include/FLAC/file_encoder.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2002  Josh Coalson
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA  02111-1307, USA.
  18  */
  19
  20 #ifndef FLAC__FILE_ENCODER_H
  21 #define FLAC__FILE_ENCODER_H
  22
  23 #include "seekable_stream_encoder.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /** \file include/FLAC/file_encoder.h
  31  *
  32  *  \brief
  33  *  This module contains the functions which implement the file
  34  *  encoder.
  35  *
  36  *  See the detailed documentation in the
  37  *  \link flac_file_encoder file encoder \endlink module.
  38  */
  39
  40 /** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
  41  *  \ingroup flac_encoder
  42  *
  43  *  \brief
  44  *  This module contains the functions which implement the file
  45  *  encoder.
  46  *
  47  * The basic usage of this encoder is as follows:
  48  * - The program creates an instance of an encoder using
  49  *   FLAC__file_encoder_new().
  50  * - The program overrides the default settings using
  51  *   FLAC__file_encoder_set_*() functions.
  52  * - The program initializes the instance to validate the settings and
  53  *   prepare for encoding using FLAC__file_encoder_init().
  54  * - The program calls FLAC__file_encoder_process() or
  55  *   FLAC__file_encoder_process_interleaved() to encode data, which
  56  *   subsequently writes data to the output file.
  57  * - The program finishes the encoding with FLAC__file_encoder_finish(),
  58  *   which causes the encoder to encode any data still in its input pipe,
  59  *   rewind and write the STREAMINFO metadata to file, and finally reset
  60  *   the encoder to the uninitialized state.
  61  * - The instance may be used again or deleted with
  62  *   FLAC__file_encoder_delete().
  63  *
  64  * The file encoder is a wrapper around the
  65  * \link flac_seekable_stream_encoder seekable stream encoder \endlink which supplies all
  66  * callbacks internally; the user need specify only the filename.
  67  *
  68  * Make sure to read the detailed description of the
  69  * \link flac_seekable_stream_encoder seekable stream encoder module \endlink since the
  70  * \link flac_stream_encoder stream encoder module \endlink since the
  71  * file encoder inherits much of its behavior from them.
  72  *
  73  * \note
  74  * The "set" functions may only be called when the encoder is in the
  75  * state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
  76  * FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but
  77  * before FLAC__file_encoder_init().  If this is the case they will
  78  * return \c true, otherwise \c false.
  79  *
  80  * \note
  81  * FLAC__file_encoder_finish() resets all settings to the constructor
  82  * defaults.
  83  *
  84  * \{
  85  */
  86
  87
  88 /** State values for a FLAC__FileEncoder
  89  *
  90  *  The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
  91  */
  92 typedef enum {
  93
  94         FLAC__FILE_ENCODER_OK = 0,
  95         /**< The encoder is in the normal OK state. */
  96
  97         FLAC__FILE_ENCODER_NO_FILENAME,
  98         /**< FLAC__file_encoder_init() was called without first calling
  99          * FLAC__file_encoder_set_filename().
 100          */
 101
 102         FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
 103         /**< An error occurred in the underlying seekable stream encoder;
 104          * check FLAC__file_encoder_get_seekable_stream_encoder_state().
 105          */
 106
 107         FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
 108         /**< A fatal error occurred while writing to the encoded file. */
 109
 110         FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
 111         /**< An error occurred opening the output file for writing. */
 112
 113         FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
 114         /**< Memory allocation failed. */
 115
 116         FLAC__FILE_ENCODER_ALREADY_INITIALIZED,
 117         /**< FLAC__file_encoder_init() was called when the encoder was
 118          * already initialized, usually because
 119          * FLAC__file_encoder_finish() was not called.
 120          */
 121
 122         FLAC__FILE_ENCODER_UNINITIALIZED
 123         /**< The encoder is in the uninitialized state. */
 124
 125 } FLAC__FileEncoderState;
 126
 127 /** Maps a FLAC__FileEncoderState to a C string.
 128  *
 129  *  Using a FLAC__FileEncoderState as the index to this array
 130  *  will give the string equivalent.  The contents should not be modified.
 131  */
 132 extern const char * const FLAC__FileEncoderStateString[];
 133
 134
 135 /***********************************************************************
 136  *
 137  * class FLAC__FileEncoder
 138  *
 139  ***********************************************************************/
 140
 141 struct FLAC__FileEncoderProtected;
 142 struct FLAC__FileEncoderPrivate;
 143 /** The opaque structure definition for the file encoder type.
 144  *  See the \link flac_file_encoder file encoder module \endlink
 145  *  for a detailed description.
 146  */
 147 typedef struct {
 148         struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 149         struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 150 } FLAC__FileEncoder;
 151
 152 /** Signature for the progress callback.
 153  *  See FLAC__file_encoder_set_progress_callback() for more info.
 154  *
 155  * \param  encoder          The encoder instance calling the callback.
 156  * \param  bytes_written    Bytes written so far.
 157  * \param  samples_written  Samples written so far.
 158  * \param  frames_written   Frames written so far.
 159  * \param  total_frames_estimate  The estimate of the total number of
 160  *                                frames to be written.
 161  * \param  client_data      The callee's client data set through
 162  *                          FLAC__file_encoder_set_client_data().
 163  */
 164 typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
 165
 166
 167 /***********************************************************************
 168  *
 169  * Class constructor/destructor
 170  *
 171  ***********************************************************************/
 172
 173 /** Create a new file encoder instance.  The instance is created with
 174  *  default settings; see the individual FLAC__file_encoder_set_*()
 175  *  functions for each setting's default.
 176  *
 177  * \retval FLAC__FileEncoder*
 178  *    \c NULL if there was an error allocating memory, else the new instance.
 179  */
 180 FLAC__FileEncoder *FLAC__file_encoder_new();
 181
 182 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 183  *
 184  * \param encoder  A pointer to an existing encoder.
 185  * \assert
 186  *    \code encoder != NULL \endcode
 187  */
 188 void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
 189
 190 /***********************************************************************
 191  *
 192  * Public class method prototypes
 193  *
 194  ***********************************************************************/
 195
 196 /** This is inherited from FLAC__SeekableStreamEncoder; see
 197  *  FLAC__seekable_stream_encoder_set_verify().
 198  *
 199  * \default \c true
 200  * \param  encoder  An encoder instance to set.
 201  * \param  value    See above.
 202  * \assert
 203  *    \code encoder != NULL \endcode
 204  * \retval FLAC__bool
 205  *    \c false if the encoder is already initialized, else \c true.
 206  */
 207 FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
 208
 209 /** This is inherited from FLAC__SeekableStreamEncoder; see
 210  *  FLAC__seekable_stream_encoder_set_streamable_subset().
 211  *
 212  * \default \c true
 213  * \param  encoder  An encoder instance to set.
 214  * \param  value    See above.
 215  * \assert
 216  *    \code encoder != NULL \endcode
 217  * \retval FLAC__bool
 218  *    \c false if the encoder is already initialized, else \c true.
 219  */
 220 FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
 221
 222 /** This is inherited from FLAC__SeekableStreamEncoder; see
 223  *  FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
 224  *
 225  * \default \c false
 226  * \param  encoder  An encoder instance to set.
 227  * \param  value    See above.
 228  * \assert
 229  *    \code encoder != NULL \endcode
 230  * \retval FLAC__bool
 231  *    \c false if the encoder is already initialized, else \c true.
 232  */
 233 FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
 234
 235 /** This is inherited from FLAC__SeekableStreamEncoder; see
 236  *  FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
 237  *
 238  * \default \c false
 239  * \param  encoder  An encoder instance to set.
 240  * \param  value    See above.
 241  * \assert
 242  *    \code encoder != NULL \endcode
 243  * \retval FLAC__bool
 244  *    \c false if the encoder is already initialized, else \c true.
 245  */
 246 FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
 247
 248 /** This is inherited from FLAC__SeekableStreamEncoder; see
 249  *  FLAC__seekable_stream_encoder_set_channels().
 250  *
 251  * \default \c 2
 252  * \param  encoder  An encoder instance to set.
 253  * \param  value    See above.
 254  * \assert
 255  *    \code encoder != NULL \endcode
 256  * \retval FLAC__bool
 257  *    \c false if the encoder is already initialized, else \c true.
 258  */
 259 FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
 260
 261 /** This is inherited from FLAC__SeekableStreamEncoder; see
 262  *  FLAC__seekable_stream_encoder_set_bits_per_sample().
 263  *
 264  * \warning
 265  * Do not feed the encoder data that is wider than the value you
 266  * set here or you will generate an invalid stream.
 267  *
 268  * \default \c 16
 269  * \param  encoder  An encoder instance to set.
 270  * \param  value    See above.
 271  * \assert
 272  *    \code encoder != NULL \endcode
 273  * \retval FLAC__bool
 274  *    \c false if the encoder is already initialized, else \c true.
 275  */
 276 FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
 277
 278 /** This is inherited from FLAC__SeekableStreamEncoder; see
 279  *  FLAC__seekable_stream_encoder_set_sample_rate().
 280  *
 281  * \default \c 44100
 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 FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
 290
 291 /** This is inherited from FLAC__SeekableStreamEncoder; see
 292  *  FLAC__seekable_stream_encoder_set_blocksize().
 293  *
 294  * \default \c 1152
 295  * \param  encoder  An encoder instance to set.
 296  * \param  value    See above.
 297  * \assert
 298  *    \code encoder != NULL \endcode
 299  * \retval FLAC__bool
 300  *    \c false if the encoder is already initialized, else \c true.
 301  */
 302 FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
 303
 304 /** This is inherited from FLAC__SeekableStreamEncoder; see
 305  *  FLAC__seekable_stream_encoder_set_max_lpc_order().
 306  *
 307  * \default \c 0
 308  * \param  encoder  An encoder instance to set.
 309  * \param  value    See above.
 310  * \assert
 311  *    \code encoder != NULL \endcode
 312  * \retval FLAC__bool
 313  *    \c false if the encoder is already initialized, else \c true.
 314  */
 315 FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
 316
 317 /** This is inherited from FLAC__SeekableStreamEncoder; see
 318  *  FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
 319  *
 320  * \note
 321  * In the current implementation, qlp_coeff_precision + bits_per_sample must
 322  * be less than 32.
 323  *
 324  * \default \c 0
 325  * \param  encoder  An encoder instance to set.
 326  * \param  value    See above.
 327  * \assert
 328  *    \code encoder != NULL \endcode
 329  * \retval FLAC__bool
 330  *    \c false if the encoder is already initialized, else \c true.
 331  */
 332 FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
 333
 334 /** This is inherited from FLAC__SeekableStreamEncoder; see
 335  *  FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
 336  *
 337  * \default \c false
 338  * \param  encoder  An encoder instance to set.
 339  * \param  value    See above.
 340  * \assert
 341  *    \code encoder != NULL \endcode
 342  * \retval FLAC__bool
 343  *    \c false if the encoder is already initialized, else \c true.
 344  */
 345 FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
 346
 347 /** This is inherited from FLAC__SeekableStreamEncoder; see
 348  *  FLAC__seekable_stream_encoder_set_do_escape_coding().
 349  *
 350  * \default \c false
 351  * \param  encoder  An encoder instance to set.
 352  * \param  value    See above.
 353  * \assert
 354  *    \code encoder != NULL \endcode
 355  * \retval FLAC__bool
 356  *    \c false if the encoder is already initialized, else \c true.
 357  */
 358 FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
 359
 360 /** This is inherited from FLAC__SeekableStreamEncoder; see
 361  *  FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
 362  *
 363  * \default \c false
 364  * \param  encoder  An encoder instance to set.
 365  * \param  value    See above.
 366  * \assert
 367  *    \code encoder != NULL \endcode
 368  * \retval FLAC__bool
 369  *    \c false if the encoder is already initialized, else \c true.
 370  */
 371 FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
 372
 373 /** This is inherited from FLAC__SeekableStreamEncoder; see
 374  *  FLAC__seekable_stream_encoder_set_min_residual_partition_order().
 375  *
 376  * \default \c 0
 377  * \param  encoder  An encoder instance to set.
 378  * \param  value    See above.
 379  * \assert
 380  *    \code encoder != NULL \endcode
 381  * \retval FLAC__bool
 382  *    \c false if the encoder is already initialized, else \c true.
 383  */
 384 FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
 385
 386 /** This is inherited from FLAC__SeekableStreamEncoder; see
 387  *  FLAC__seekable_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 FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
 398
 399 /** This is inherited from FLAC__SeekableStreamEncoder; see
 400  *  FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
 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 FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
 411
 412 /** This is inherited from FLAC__SeekableStreamEncoder; see
 413  *  FLAC__seekable_stream_encoder_set_total_samples_estimate().
 414  *
 415  * \default \c 0
 416  * \param  encoder  An encoder instance to set.
 417  * \param  value    See above.
 418  * \assert
 419  *    \code encoder != NULL \endcode
 420  * \retval FLAC__bool
 421  *    \c false if the encoder is already initialized, else \c true.
 422  */
 423 FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
 424
 425 /** This is inherited from FLAC__SeekableStreamEncoder; see
 426  *  FLAC__seekable_stream_encoder_set_metadata().
 427  *
 428  * \default \c NULL, 0
 429  * \param  encoder     An encoder instance to set.
 430  * \param  metadata    See above.
 431  * \param  num_blocks  See above.
 432  * \assert
 433  *    \code encoder != NULL \endcode
 434  * \retval FLAC__bool
 435  *    \c false if the encoder is already initialized, else \c true.
 436  */
 437 FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 438
 439 /** Set the output file name encode to.
 440  *
 441  * \note
 442  * The filename is mandatory and must be set before initialization.
 443  *
 444  * \note
 445  * Unlike the FLAC__FileDecoder, the filename does not interpret "-" for
 446  * \c stdout; writing to \c stdout is not relevant in the file encoder.
 447  *
 448  * \default \c NULL
 449  * \param  encoder  A encoder instance to set.
 450  * \param  value    The output file name.
 451  * \assert
 452  *    \code encoder != NULL \endcode
 453  *    \code value != NULL \endcode
 454  * \retval FLAC__bool
 455  *    \c false if the encoder is already initialized, or there was a memory
 456  *    allocation error, else \c true.
 457  */
 458 FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
 459
 460 /** Set the progress callback.
 461  *  The supplied function will be called when the encoder has finished
 462  *  writing a frame.  The \c total_frames_estimate argument to the callback
 463  *  will be based on the value from
 464  *  FLAC__file_encoder_set_total_samples_estimate().
 465  *
 466  * \note
 467  * Unlike most other callbacks, the progress callback is \b not mandatory
 468  * and need not be set before initialization.
 469  *
 470  * \default \c NULL
 471  * \param  encoder  An encoder instance to set.
 472  * \param  value    See above.
 473  * \assert
 474  *    \code encoder != NULL \endcode
 475  *    \code value != NULL \endcode
 476  * \retval FLAC__bool
 477  *    \c false if the encoder is already initialized, else \c true.
 478  */
 479 FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
 480
 481 /** Set the client data to be passed back to callbacks.
 482  *  This value will be supplied to callbacks in their \a client_data
 483  *  argument.
 484  *
 485  * \default \c NULL
 486  * \param  encoder  An encoder instance to set.
 487  * \param  value    See above.
 488  * \assert
 489  *    \code encoder != NULL \endcode
 490  * \retval FLAC__bool
 491  *    \c false if the encoder is already initialized, else \c true.
 492  */
 493 FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
 494
 495 /** Get the current encoder state.
 496  *
 497  * \param  encoder  An encoder instance to query.
 498  * \assert
 499  *    \code encoder != NULL \endcode
 500  * \retval FLAC__FileEncoderState
 501  *    The current encoder state.
 502  */
 503 FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
 504
 505 /** Get the state of the underlying seekable stream encoder.
 506  *  Useful when the file encoder state is
 507  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
 508  *
 509  * \param  encoder  An encoder instance to query.
 510  * \assert
 511  *    \code encoder != NULL \endcode
 512  * \retval FLAC__SeekableStreamEncoderState
 513  *    The seekable stream encoder state.
 514  */
 515 FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
 516
 517 /** Get the state of the underlying stream encoder.
 518  *  Useful when the file encoder state is
 519  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
 520  *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
 521  *
 522  * \param  encoder  An encoder instance to query.
 523  * \assert
 524  *    \code encoder != NULL \endcode
 525  * \retval FLAC__StreamEncoderState
 526  *    The seekable stream encoder state.
 527  */
 528 FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
 529
 530 /** Get the state of the underlying stream encoder's verify decoder.
 531  *  Useful when the file encoder state is
 532  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
 533  *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and
 534  *  the stream encoder state is \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 FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
 543
 544 /** Get relevant values about the nature of a verify decoder error.
 545  *  Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
 546  *  Useful when the file encoder state is
 547  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
 548  *  encoder state is
 549  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
 550  *  stream encoder state is
 551  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 552  *
 553  * \param  encoder  An encoder instance to query.
 554  * \param  absolute_sample  The absolute sample number of the mismatch.
 555  * \param  frame_number  The number of the frame in which the mismatch occurred.
 556  * \param  channel       The channel in which the mismatch occurred.
 557  * \param  sample        The number of the sample (relative to the frame) in
 558  *                       which the mismatch occurred.
 559  * \param  expected      The expected value for the sample in question.
 560  * \param  got           The actual value returned by the decoder.
 561  * \assert
 562  *    \code encoder != NULL \endcode
 563  */
 564 void FLAC__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 565
 566 /** Get the "verify" flag.
 567  *  This is inherited from FLAC__SeekableStreamEncoder; see
 568  *  FLAC__seekable_stream_encoder_get_verify().
 569  *
 570  * \param  encoder  An encoder instance to query.
 571  * \assert
 572  *    \code encoder != NULL \endcode
 573  * \retval FLAC__bool
 574  *    See FLAC__file_encoder_set_verify().
 575  */
 576 FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
 577
 578 /** Get the "streamable subset" flag.
 579  *  This is inherited from FLAC__SeekableStreamEncoder; see
 580  *  FLAC__seekable_stream_encoder_get_streamable_subset().
 581  *
 582  * \param  encoder  An encoder instance to query.
 583  * \assert
 584  *    \code encoder != NULL \endcode
 585  * \retval FLAC__bool
 586  *    See FLAC__file_encoder_set_streamable_subset().
 587  */
 588 FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
 589
 590 /** Get the "mid/side stereo coding" flag.
 591  *  This is inherited from FLAC__SeekableStreamEncoder; see
 592  *  FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
 593  *
 594  * \param  encoder  An encoder instance to query.
 595  * \assert
 596  *    \code encoder != NULL \endcode
 597  * \retval FLAC__bool
 598  *    See FLAC__file_encoder_get_do_mid_side_stereo().
 599  */
 600 FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
 601
 602 /** Get the "adaptive mid/side switching" flag.
 603  *  This is inherited from FLAC__SeekableStreamEncoder; see
 604  *  FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
 605  *
 606  * \param  encoder  An encoder instance to query.
 607  * \assert
 608  *    \code encoder != NULL \endcode
 609  * \retval FLAC__bool
 610  *    See FLAC__file_encoder_set_loose_mid_side_stereo().
 611  */
 612 FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
 613
 614 /** Get the number of input channels being processed.
 615  *  This is inherited from FLAC__SeekableStreamEncoder; see
 616  *  FLAC__seekable_stream_encoder_get_channels().
 617  *
 618  * \param  encoder  An encoder instance to query.
 619  * \assert
 620  *    \code encoder != NULL \endcode
 621  * \retval unsigned
 622  *    See FLAC__file_encoder_set_channels().
 623  */
 624 unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
 625
 626 /** Get the input sample resolution setting.
 627  *  This is inherited from FLAC__SeekableStreamEncoder; see
 628  *  FLAC__seekable_stream_encoder_get_bits_per_sample().
 629  *
 630  * \param  encoder  An encoder instance to query.
 631  * \assert
 632  *    \code encoder != NULL \endcode
 633  * \retval unsigned
 634  *    See FLAC__file_encoder_set_bits_per_sample().
 635  */
 636 unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
 637
 638 /** Get the input sample rate setting.
 639  *  This is inherited from FLAC__SeekableStreamEncoder; see
 640  *  FLAC__seekable_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 FLAC__file_encoder_set_sample_rate().
 647  */
 648 unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
 649
 650 /** Get the blocksize setting.
 651  *  This is inherited from FLAC__SeekableStreamEncoder; see
 652  *  FLAC__seekable_stream_encoder_get_blocksize().
 653  *
 654  * \param  encoder  An encoder instance to query.
 655  * \assert
 656  *    \code encoder != NULL \endcode
 657  * \retval unsigned
 658  *    See FLAC__file_encoder_set_blocksize().
 659  */
 660 unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
 661
 662 /** Get the maximum LPC order setting.
 663  *  This is inherited from FLAC__SeekableStreamEncoder; see
 664  *  FLAC__seekable_stream_encoder_get_max_lpc_order().
 665  *
 666  * \param  encoder  An encoder instance to query.
 667  * \assert
 668  *    \code encoder != NULL \endcode
 669  * \retval unsigned
 670  *    See FLAC__file_encoder_set_max_lpc_order().
 671  */
 672 unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
 673
 674 /** Get the quantized linear predictor coefficient precision setting.
 675  *  This is inherited from FLAC__SeekableStreamEncoder; see
 676  *  FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
 677  *
 678  * \param  encoder  An encoder instance to query.
 679  * \assert
 680  *    \code encoder != NULL \endcode
 681  * \retval unsigned
 682  *    See FLAC__file_encoder_set_qlp_coeff_precision().
 683  */
 684 unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
 685
 686 /** Get the qlp coefficient precision search flag.
 687  *  This is inherited from FLAC__SeekableStreamEncoder; see
 688  *  FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
 689  *
 690  * \param  encoder  An encoder instance to query.
 691  * \assert
 692  *    \code encoder != NULL \endcode
 693  * \retval FLAC__bool
 694  *    See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
 695  */
 696 FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
 697
 698 /** Get the "escape coding" flag.
 699  *  This is inherited from FLAC__SeekableStreamEncoder; see
 700  *  FLAC__seekable_stream_encoder_get_do_escape_coding().
 701  *
 702  * \param  encoder  An encoder instance to query.
 703  * \assert
 704  *    \code encoder != NULL \endcode
 705  * \retval FLAC__bool
 706  *    See FLAC__file_encoder_set_do_escape_coding().
 707  */
 708 FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
 709
 710 /** Get the exhaustive model search flag.
 711  *  This is inherited from FLAC__SeekableStreamEncoder; see
 712  *  FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
 713  *
 714  * \param  encoder  An encoder instance to query.
 715  * \assert
 716  *    \code encoder != NULL \endcode
 717  * \retval FLAC__bool
 718  *    See FLAC__file_encoder_set_do_exhaustive_model_search().
 719  */
 720 FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
 721
 722 /** Get the minimum residual partition order setting.
 723  *  This is inherited from FLAC__SeekableStreamEncoder; see
 724  *  FLAC__seekable_stream_encoder_get_min_residual_partition_order().
 725  *
 726  * \param  encoder  An encoder instance to query.
 727  * \assert
 728  *    \code encoder != NULL \endcode
 729  * \retval unsigned
 730  *    See FLAC__file_encoder_set_min_residual_partition_order().
 731  */
 732 unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
 733
 734 /** Get maximum residual partition order setting.
 735  *  This is inherited from FLAC__SeekableStreamEncoder; see
 736  *  FLAC__seekable_stream_encoder_get_max_residual_partition_order().
 737  *
 738  * \param  encoder  An encoder instance to query.
 739  * \assert
 740  *    \code encoder != NULL \endcode
 741  * \retval unsigned
 742  *    See FLAC__file_encoder_set_max_residual_partition_order().
 743  */
 744 unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
 745
 746 /** Get the Rice parameter search distance setting.
 747  *  This is inherited from FLAC__SeekableStreamEncoder; see
 748  *  FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
 749  *
 750  * \param  encoder  An encoder instance to query.
 751  * \assert
 752  *    \code encoder != NULL \endcode
 753  * \retval unsigned
 754  *    See FLAC__file_encoder_set_rice_parameter_search_dist().
 755  */
 756 unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
 757
 758 /** Get the previously set estimate of the total samples to be encoded.
 759  *  This is inherited from FLAC__SeekableStreamEncoder; see
 760  *  FLAC__seekable_stream_encoder_get_total_samples_estimate().
 761  *
 762  * \param  encoder  An encoder instance to query.
 763  * \assert
 764  *    \code encoder != NULL \endcode
 765  * \retval FLAC__uint64
 766  *    See FLAC__file_encoder_set_total_samples_estimate().
 767  */
 768 FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
 769
 770 /** Initialize the encoder instance.
 771  *  Should be called after FLAC__file_encoder_new() and
 772  *  FLAC__file_encoder_set_*() but before FLAC__file_encoder_process()
 773  *  or FLAC__file_encoder_process_interleaved().  Will set and return
 774  *  the encoder state, which will be FLAC__FILE_ENCODER_OK if
 775  *  initialization succeeded.
 776  *
 777  * \param  encoder  An uninitialized encoder instance.
 778  * \assert
 779  *    \code encoder != NULL \endcode
 780  * \retval FLAC__FileEncoderState
 781  *    \c FLAC__FILE_ENCODER_OK if initialization was successful; see
 782  *    FLAC__FileEncoderState for the meanings of other return values.
 783  */
 784 FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
 785
 786 /** Finish the encoding process.
 787  *  Flushes the encoding buffer, releases resources, resets the encoder
 788  *  settings to their defaults, and returns the encoder state to
 789  *  FLAC__FILE_ENCODER_UNINITIALIZED.
 790  *
 791  *  In the event of a prematurely-terminated encode, it is not strictly
 792  *  necessary to call this immediately before FLAC__file_encoder_delete()
 793  *  but it is good practice to match every FLAC__file_encoder_init()
 794  *  with a FLAC__file_encoder_finish().
 795  *
 796  * \param  encoder  An uninitialized encoder instance.
 797  * \assert
 798  *    \code encoder != NULL \endcode
 799  */
 800 void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
 801
 802 /** Submit data for encoding.
 803  *  This is inherited from FLAC__SeekableStreamEncoder; see
 804  *  FLAC__seekable_stream_encoder_process().
 805  *
 806  * \param  encoder  An initialized encoder instance in the OK state.
 807  * \param  buffer   An array of pointers to each channel's signal.
 808  * \param  samples  The number of samples in one channel.
 809  * \assert
 810  *    \code encoder != NULL \endcode
 811  *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
 812  * \retval FLAC__bool
 813  *    \c true if successful, else \c false; in this case, check the
 814  *    encoder state with FLAC__file_encoder_get_state() to see what
 815  *    went wrong.
 816  */
 817 FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 818
 819 /** Submit data for encoding.
 820  *  This is inherited from FLAC__SeekableStreamEncoder; see
 821  *  FLAC__seekable_stream_encoder_process_interleaved().
 822  *
 823  * \param  encoder  An initialized encoder instance in the OK state.
 824  * \param  buffer   An array of channel-interleaved data (see above).
 825  * \param  samples  The number of samples in one channel, the same as for
 826  *                  FLAC__file_encoder_process().  For example, if
 827  *                  encoding two channels, \c 1000 \a samples corresponds
 828  *                  to a \a buffer of 2000 values.
 829  * \assert
 830  *    \code encoder != NULL \endcode
 831  *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
 832  * \retval FLAC__bool
 833  *    \c true if successful, else \c false; in this case, check the
 834  *    encoder state with FLAC__file_encoder_get_state() to see what
 835  *    went wrong.
 836  */
 837 FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 838
 839 /* \} */
 840
 841 #ifdef __cplusplus
 842 }
 843 #endif
 844
 845 #endif