Home | History | Annotate | Download | only in FLAC
      1 /* libFLAC - Free Lossless Audio Codec library
      2  * Copyright (C) 2000-2009  Josh Coalson
      3  * Copyright (C) 2011-2014  Xiph.Org Foundation
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions
      7  * are met:
      8  *
      9  * - Redistributions of source code must retain the above copyright
     10  * notice, this list of conditions and the following disclaimer.
     11  *
     12  * - Redistributions in binary form must reproduce the above copyright
     13  * notice, this list of conditions and the following disclaimer in the
     14  * documentation and/or other materials provided with the distribution.
     15  *
     16  * - Neither the name of the Xiph.org Foundation nor the names of its
     17  * contributors may be used to endorse or promote products derived from
     18  * this software without specific prior written permission.
     19  *
     20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     21  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     23  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
     24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     27  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     28  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     29  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     31  */
     32 
     33 #ifndef FLAC__STREAM_ENCODER_H
     34 #define FLAC__STREAM_ENCODER_H
     35 
     36 #include <stdio.h> /* for FILE */
     37 #include "export.h"
     38 #include "format.h"
     39 #include "stream_decoder.h"
     40 
     41 #ifdef __cplusplus
     42 extern "C" {
     43 #endif
     44 
     45 
     46 /** \file include/FLAC/stream_encoder.h
     47  *
     48  *  \brief
     49  *  This module contains the functions which implement the stream
     50  *  encoder.
     51  *
     52  *  See the detailed documentation in the
     53  *  \link flac_stream_encoder stream encoder \endlink module.
     54  */
     55 
     56 /** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
     57  *  \ingroup flac
     58  *
     59  *  \brief
     60  *  This module describes the encoder layers provided by libFLAC.
     61  *
     62  * The stream encoder can be used to encode complete streams either to the
     63  * client via callbacks, or directly to a file, depending on how it is
     64  * initialized.  When encoding via callbacks, the client provides a write
     65  * callback which will be called whenever FLAC data is ready to be written.
     66  * If the client also supplies a seek callback, the encoder will also
     67  * automatically handle the writing back of metadata discovered while
     68  * encoding, like stream info, seek points offsets, etc.  When encoding to
     69  * a file, the client needs only supply a filename or open \c FILE* and an
     70  * optional progress callback for periodic notification of progress; the
     71  * write and seek callbacks are supplied internally.  For more info see the
     72  * \link flac_stream_encoder stream encoder \endlink module.
     73  */
     74 
     75 /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
     76  *  \ingroup flac_encoder
     77  *
     78  *  \brief
     79  *  This module contains the functions which implement the stream
     80  *  encoder.
     81  *
     82  * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
     83  * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
     84  *
     85  * The basic usage of this encoder is as follows:
     86  * - The program creates an instance of an encoder using
     87  *   FLAC__stream_encoder_new().
     88  * - The program overrides the default settings using
     89  *   FLAC__stream_encoder_set_*() functions.  At a minimum, the following
     90  *   functions should be called:
     91  *   - FLAC__stream_encoder_set_channels()
     92  *   - FLAC__stream_encoder_set_bits_per_sample()
     93  *   - FLAC__stream_encoder_set_sample_rate()
     94  *   - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
     95  *   - FLAC__stream_encoder_set_total_samples_estimate() (if known)
     96  * - If the application wants to control the compression level or set its own
     97  *   metadata, then the following should also be called:
     98  *   - FLAC__stream_encoder_set_compression_level()
     99  *   - FLAC__stream_encoder_set_verify()
    100  *   - FLAC__stream_encoder_set_metadata()
    101  * - The rest of the set functions should only be called if the client needs
    102  *   exact control over how the audio is compressed; thorough understanding
    103  *   of the FLAC format is necessary to achieve good results.
    104  * - The program initializes the instance to validate the settings and
    105  *   prepare for encoding using
    106  *   - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
    107  *     or FLAC__stream_encoder_init_file() for native FLAC
    108  *   - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
    109  *     or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
    110  * - The program calls FLAC__stream_encoder_process() or
    111  *   FLAC__stream_encoder_process_interleaved() to encode data, which
    112  *   subsequently calls the callbacks when there is encoder data ready
    113  *   to be written.
    114  * - The program finishes the encoding with FLAC__stream_encoder_finish(),
    115  *   which causes the encoder to encode any data still in its input pipe,
    116  *   update the metadata with the final encoding statistics if output
    117  *   seeking is possible, and finally reset the encoder to the
    118  *   uninitialized state.
    119  * - The instance may be used again or deleted with
    120  *   FLAC__stream_encoder_delete().
    121  *
    122  * In more detail, the stream encoder functions similarly to the
    123  * \link flac_stream_decoder stream decoder \endlink, but has fewer
    124  * callbacks and more options.  Typically the client will create a new
    125  * instance by calling FLAC__stream_encoder_new(), then set the necessary
    126  * parameters with FLAC__stream_encoder_set_*(), and initialize it by
    127  * calling one of the FLAC__stream_encoder_init_*() functions.
    128  *
    129  * Unlike the decoders, the stream encoder has many options that can
    130  * affect the speed and compression ratio.  When setting these parameters
    131  * you should have some basic knowledge of the format (see the
    132  * <A HREF="../documentation_format_overview.html">user-level documentation</A>
    133  * or the <A HREF="../format.html">formal description</A>).  The
    134  * FLAC__stream_encoder_set_*() functions themselves do not validate the
    135  * values as many are interdependent.  The FLAC__stream_encoder_init_*()
    136  * functions will do this, so make sure to pay attention to the state
    137  * returned by FLAC__stream_encoder_init_*() to make sure that it is
    138  * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
    139  * before FLAC__stream_encoder_init_*() will take on the defaults from
    140  * the constructor.
    141  *
    142  * There are three initialization functions for native FLAC, one for
    143  * setting up the encoder to encode FLAC data to the client via
    144  * callbacks, and two for encoding directly to a file.
    145  *
    146  * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
    147  * You must also supply a write callback which will be called anytime
    148  * there is raw encoded data to write.  If the client can seek the output
    149  * it is best to also supply seek and tell callbacks, as this allows the
    150  * encoder to go back after encoding is finished to write back
    151  * information that was collected while encoding, like seek point offsets,
    152  * frame sizes, etc.
    153  *
    154  * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
    155  * or FLAC__stream_encoder_init_file().  Then you must only supply a
    156  * filename or open \c FILE*; the encoder will handle all the callbacks
    157  * internally.  You may also supply a progress callback for periodic
    158  * notification of the encoding progress.
    159  *
    160  * There are three similarly-named init functions for encoding to Ogg
    161  * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
    162  * library has been built with Ogg support.
    163  *
    164  * The call to FLAC__stream_encoder_init_*() currently will also immediately
    165  * call the write callback several times, once with the \c fLaC signature,
    166  * and once for each encoded metadata block.  Note that for Ogg FLAC
    167  * encoding you will usually get at least twice the number of callbacks than
    168  * with native FLAC, one for the Ogg page header and one for the page body.
    169  *
    170  * After initializing the instance, the client may feed audio data to the
    171  * encoder in one of two ways:
    172  *
    173  * - Channel separate, through FLAC__stream_encoder_process() - The client
    174  *   will pass an array of pointers to buffers, one for each channel, to
    175  *   the encoder, each of the same length.  The samples need not be
    176  *   block-aligned, but each channel should have the same number of samples.
    177  * - Channel interleaved, through
    178  *   FLAC__stream_encoder_process_interleaved() - The client will pass a single
    179  *   pointer to data that is channel-interleaved (i.e. channel0_sample0,
    180  *   channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
    181  *   Again, the samples need not be block-aligned but they must be
    182  *   sample-aligned, i.e. the first value should be channel0_sample0 and
    183  *   the last value channelN_sampleM.
    184  *
    185  * Note that for either process call, each sample in the buffers should be a
    186  * signed integer, right-justified to the resolution set by
    187  * FLAC__stream_encoder_set_bits_per_sample().  For example, if the resolution
    188  * is 16 bits per sample, the samples should all be in the range [-32768,32767].
    189  *
    190  * When the client is finished encoding data, it calls
    191  * FLAC__stream_encoder_finish(), which causes the encoder to encode any
    192  * data still in its input pipe, and call the metadata callback with the
    193  * final encoding statistics.  Then the instance may be deleted with
    194  * FLAC__stream_encoder_delete() or initialized again to encode another
    195  * stream.
    196  *
    197  * For programs that write their own metadata, but that do not know the
    198  * actual metadata until after encoding, it is advantageous to instruct
    199  * the encoder to write a PADDING block of the correct size, so that
    200  * instead of rewriting the whole stream after encoding, the program can
    201  * just overwrite the PADDING block.  If only the maximum size of the
    202  * metadata is known, the program can write a slightly larger padding
    203  * block, then split it after encoding.
    204  *
    205  * Make sure you understand how lengths are calculated.  All FLAC metadata
    206  * blocks have a 4 byte header which contains the type and length.  This
    207  * length does not include the 4 bytes of the header.  See the format page
    208  * for the specification of metadata blocks and their lengths.
    209  *
    210  * \note
    211  * If you are writing the FLAC data to a file via callbacks, make sure it
    212  * is open for update (e.g. mode "w+" for stdio streams).  This is because
    213  * after the first encoding pass, the encoder will try to seek back to the
    214  * beginning of the stream, to the STREAMINFO block, to write some data
    215  * there.  (If using FLAC__stream_encoder_init*_file() or
    216  * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
    217  *
    218  * \note
    219  * The "set" functions may only be called when the encoder is in the
    220  * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
    221  * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
    222  * before FLAC__stream_encoder_init_*().  If this is the case they will
    223  * return \c true, otherwise \c false.
    224  *
    225  * \note
    226  * FLAC__stream_encoder_finish() resets all settings to the constructor
    227  * defaults.
    228  *
    229  * \{
    230  */
    231 
    232 
    233 /** State values for a FLAC__StreamEncoder.
    234  *
    235  * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
    236  *
    237  * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
    238  * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
    239  * must be deleted with FLAC__stream_encoder_delete().
    240  */
    241 typedef enum {
    242 
    243 	FLAC__STREAM_ENCODER_OK = 0,
    244 	/**< The encoder is in the normal OK state and samples can be processed. */
    245 
    246 	FLAC__STREAM_ENCODER_UNINITIALIZED,
    247 	/**< The encoder is in the uninitialized state; one of the
    248 	 * FLAC__stream_encoder_init_*() functions must be called before samples
    249 	 * can be processed.
    250 	 */
    251 
    252 	FLAC__STREAM_ENCODER_OGG_ERROR,
    253 	/**< An error occurred in the underlying Ogg layer.  */
    254 
    255 	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
    256 	/**< An error occurred in the underlying verify stream decoder;
    257 	 * check FLAC__stream_encoder_get_verify_decoder_state().
    258 	 */
    259 
    260 	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
    261 	/**< The verify decoder detected a mismatch between the original
    262 	 * audio signal and the decoded audio signal.
    263 	 */
    264 
    265 	FLAC__STREAM_ENCODER_CLIENT_ERROR,
    266 	/**< One of the callbacks returned a fatal error. */
    267 
    268 	FLAC__STREAM_ENCODER_IO_ERROR,
    269 	/**< An I/O error occurred while opening/reading/writing a file.
    270 	 * Check \c errno.
    271 	 */
    272 
    273 	FLAC__STREAM_ENCODER_FRAMING_ERROR,
    274 	/**< An error occurred while writing the stream; usually, the
    275 	 * write_callback returned an error.
    276 	 */
    277 
    278 	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
    279 	/**< Memory allocation failed. */
    280 
    281 } FLAC__StreamEncoderState;
    282 
    283 /** Maps a FLAC__StreamEncoderState to a C string.
    284  *
    285  *  Using a FLAC__StreamEncoderState as the index to this array
    286  *  will give the string equivalent.  The contents should not be modified.
    287  */
    288 extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
    289 
    290 
    291 /** Possible return values for the FLAC__stream_encoder_init_*() functions.
    292  */
    293 typedef enum {
    294 
    295 	FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
    296 	/**< Initialization was successful. */
    297 
    298 	FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
    299 	/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
    300 
    301 	FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
    302 	/**< The library was not compiled with support for the given container
    303 	 * format.
    304 	 */
    305 
    306 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
    307 	/**< A required callback was not supplied. */
    308 
    309 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
    310 	/**< The encoder has an invalid setting for number of channels. */
    311 
    312 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
    313 	/**< The encoder has an invalid setting for bits-per-sample.
    314 	 * FLAC supports 4-32 bps but the reference encoder currently supports
    315 	 * only up to 24 bps.
    316 	 */
    317 
    318 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
    319 	/**< The encoder has an invalid setting for the input sample rate. */
    320 
    321 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
    322 	/**< The encoder has an invalid setting for the block size. */
    323 
    324 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
    325 	/**< The encoder has an invalid setting for the maximum LPC order. */
    326 
    327 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
    328 	/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
    329 
    330 	FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
    331 	/**< The specified block size is less than the maximum LPC order. */
    332 
    333 	FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
    334 	/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
    335 
    336 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
    337 	/**< The metadata input to the encoder is invalid, in one of the following ways:
    338 	 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
    339 	 * - One of the metadata blocks contains an undefined type
    340 	 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
    341 	 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
    342 	 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
    343 	 */
    344 
    345 	FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
    346 	/**< FLAC__stream_encoder_init_*() was called when the encoder was
    347 	 * already initialized, usually because
    348 	 * FLAC__stream_encoder_finish() was not called.
    349 	 */
    350 
    351 } FLAC__StreamEncoderInitStatus;
    352 
    353 /** Maps a FLAC__StreamEncoderInitStatus to a C string.
    354  *
    355  *  Using a FLAC__StreamEncoderInitStatus as the index to this array
    356  *  will give the string equivalent.  The contents should not be modified.
    357  */
    358 extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
    359 
    360 
    361 /** Return values for the FLAC__StreamEncoder read callback.
    362  */
    363 typedef enum {
    364 
    365 	FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
    366 	/**< The read was OK and decoding can continue. */
    367 
    368 	FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
    369 	/**< The read was attempted at the end of the stream. */
    370 
    371 	FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
    372 	/**< An unrecoverable error occurred. */
    373 
    374 	FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
    375 	/**< Client does not support reading back from the output. */
    376 
    377 } FLAC__StreamEncoderReadStatus;
    378 
    379 /** Maps a FLAC__StreamEncoderReadStatus to a C string.
    380  *
    381  *  Using a FLAC__StreamEncoderReadStatus as the index to this array
    382  *  will give the string equivalent.  The contents should not be modified.
    383  */
    384 extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
    385 
    386 
    387 /** Return values for the FLAC__StreamEncoder write callback.
    388  */
    389 typedef enum {
    390 
    391 	FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
    392 	/**< The write was OK and encoding can continue. */
    393 
    394 	FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
    395 	/**< An unrecoverable error occurred.  The encoder will return from the process call. */
    396 
    397 } FLAC__StreamEncoderWriteStatus;
    398 
    399 /** Maps a FLAC__StreamEncoderWriteStatus to a C string.
    400  *
    401  *  Using a FLAC__StreamEncoderWriteStatus as the index to this array
    402  *  will give the string equivalent.  The contents should not be modified.
    403  */
    404 extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
    405 
    406 
    407 /** Return values for the FLAC__StreamEncoder seek callback.
    408  */
    409 typedef enum {
    410 
    411 	FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
    412 	/**< The seek was OK and encoding can continue. */
    413 
    414 	FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
    415 	/**< An unrecoverable error occurred. */
    416 
    417 	FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
    418 	/**< Client does not support seeking. */
    419 
    420 } FLAC__StreamEncoderSeekStatus;
    421 
    422 /** Maps a FLAC__StreamEncoderSeekStatus to a C string.
    423  *
    424  *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
    425  *  will give the string equivalent.  The contents should not be modified.
    426  */
    427 extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
    428 
    429 
    430 /** Return values for the FLAC__StreamEncoder tell callback.
    431  */
    432 typedef enum {
    433 
    434 	FLAC__STREAM_ENCODER_TELL_STATUS_OK,
    435 	/**< The tell was OK and encoding can continue. */
    436 
    437 	FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
    438 	/**< An unrecoverable error occurred. */
    439 
    440 	FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
    441 	/**< Client does not support seeking. */
    442 
    443 } FLAC__StreamEncoderTellStatus;
    444 
    445 /** Maps a FLAC__StreamEncoderTellStatus to a C string.
    446  *
    447  *  Using a FLAC__StreamEncoderTellStatus as the index to this array
    448  *  will give the string equivalent.  The contents should not be modified.
    449  */
    450 extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
    451 
    452 
    453 /***********************************************************************
    454  *
    455  * class FLAC__StreamEncoder
    456  *
    457  ***********************************************************************/
    458 
    459 struct FLAC__StreamEncoderProtected;
    460 struct FLAC__StreamEncoderPrivate;
    461 /** The opaque structure definition for the stream encoder type.
    462  *  See the \link flac_stream_encoder stream encoder module \endlink
    463  *  for a detailed description.
    464  */
    465 typedef struct {
    466 	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
    467 	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
    468 } FLAC__StreamEncoder;
    469 
    470 /** Signature for the read callback.
    471  *
    472  *  A function pointer matching this signature must be passed to
    473  *  FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
    474  *  The supplied function will be called when the encoder needs to read back
    475  *  encoded data.  This happens during the metadata callback, when the encoder
    476  *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
    477  *  while encoding.  The address of the buffer to be filled is supplied, along
    478  *  with the number of bytes the buffer can hold.  The callback may choose to
    479  *  supply less data and modify the byte count but must be careful not to
    480  *  overflow the buffer.  The callback then returns a status code chosen from
    481  *  FLAC__StreamEncoderReadStatus.
    482  *
    483  * Here is an example of a read callback for stdio streams:
    484  * \code
    485  * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
    486  * {
    487  *   FILE *file = ((MyClientData*)client_data)->file;
    488  *   if(*bytes > 0) {
    489  *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
    490  *     if(ferror(file))
    491  *       return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
    492  *     else if(*bytes == 0)
    493  *       return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
    494  *     else
    495  *       return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
    496  *   }
    497  *   else
    498  *     return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
    499  * }
    500  * \endcode
    501  *
    502  * \note In general, FLAC__StreamEncoder functions which change the
    503  * state should not be called on the \a encoder while in the callback.
    504  *
    505  * \param  encoder  The encoder instance calling the callback.
    506  * \param  buffer   A pointer to a location for the callee to store
    507  *                  data to be encoded.
    508  * \param  bytes    A pointer to the size of the buffer.  On entry
    509  *                  to the callback, it contains the maximum number
    510  *                  of bytes that may be stored in \a buffer.  The
    511  *                  callee must set it to the actual number of bytes
    512  *                  stored (0 in case of error or end-of-stream) before
    513  *                  returning.
    514  * \param  client_data  The callee's client data set through
    515  *                      FLAC__stream_encoder_set_client_data().
    516  * \retval FLAC__StreamEncoderReadStatus
    517  *    The callee's return status.
    518  */
    519 typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
    520 
    521 /** Signature for the write callback.
    522  *
    523  *  A function pointer matching this signature must be passed to
    524  *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
    525  *  by the encoder anytime there is raw encoded data ready to write.  It may
    526  *  include metadata mixed with encoded audio frames and the data is not
    527  *  guaranteed to be aligned on frame or metadata block boundaries.
    528  *
    529  *  The only duty of the callback is to write out the \a bytes worth of data
    530  *  in \a buffer to the current position in the output stream.  The arguments
    531  *  \a samples and \a current_frame are purely informational.  If \a samples
    532  *  is greater than \c 0, then \a current_frame will hold the current frame
    533  *  number that is being written; otherwise it indicates that the write
    534  *  callback is being called to write metadata.
    535  *
    536  * \note
    537  * Unlike when writing to native FLAC, when writing to Ogg FLAC the
    538  * write callback will be called twice when writing each audio
    539  * frame; once for the page header, and once for the page body.
    540  * When writing the page header, the \a samples argument to the
    541  * write callback will be \c 0.
    542  *
    543  * \note In general, FLAC__StreamEncoder functions which change the
    544  * state should not be called on the \a encoder while in the callback.
    545  *
    546  * \param  encoder  The encoder instance calling the callback.
    547  * \param  buffer   An array of encoded data of length \a bytes.
    548  * \param  bytes    The byte length of \a buffer.
    549  * \param  samples  The number of samples encoded by \a buffer.
    550  *                  \c 0 has a special meaning; see above.
    551  * \param  current_frame  The number of the current frame being encoded.
    552  * \param  client_data  The callee's client data set through
    553  *                      FLAC__stream_encoder_init_*().
    554  * \retval FLAC__StreamEncoderWriteStatus
    555  *    The callee's return status.
    556  */
    557 typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data);
    558 
    559 /** Signature for the seek callback.
    560  *
    561  *  A function pointer matching this signature may be passed to
    562  *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
    563  *  when the encoder needs to seek the output stream.  The encoder will pass
    564  *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
    565  *
    566  * Here is an example of a seek callback for stdio streams:
    567  * \code
    568  * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
    569  * {
    570  *   FILE *file = ((MyClientData*)client_data)->file;
    571  *   if(file == stdin)
    572  *     return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
    573  *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
    574  *     return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
    575  *   else
    576  *     return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
    577  * }
    578  * \endcode
    579  *
    580  * \note In general, FLAC__StreamEncoder functions which change the
    581  * state should not be called on the \a encoder while in the callback.
    582  *
    583  * \param  encoder  The encoder instance calling the callback.
    584  * \param  absolute_byte_offset  The offset from the beginning of the stream
    585  *                               to seek to.
    586  * \param  client_data  The callee's client data set through
    587  *                      FLAC__stream_encoder_init_*().
    588  * \retval FLAC__StreamEncoderSeekStatus
    589  *    The callee's return status.
    590  */
    591 typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
    592 
    593 /** Signature for the tell callback.
    594  *
    595  *  A function pointer matching this signature may be passed to
    596  *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
    597  *  when the encoder needs to know the current position of the output stream.
    598  *
    599  * \warning
    600  * The callback must return the true current byte offset of the output to
    601  * which the encoder is writing.  If you are buffering the output, make
    602  * sure and take this into account.  If you are writing directly to a
    603  * FILE* from your write callback, ftell() is sufficient.  If you are
    604  * writing directly to a file descriptor from your write callback, you
    605  * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
    606  * these points to rewrite metadata after encoding.
    607  *
    608  * Here is an example of a tell callback for stdio streams:
    609  * \code
    610  * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
    611  * {
    612  *   FILE *file = ((MyClientData*)client_data)->file;
    613  *   off_t pos;
    614  *   if(file == stdin)
    615  *     return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
    616  *   else if((pos = ftello(file)) < 0)
    617  *     return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
    618  *   else {
    619  *     *absolute_byte_offset = (FLAC__uint64)pos;
    620  *     return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
    621  *   }
    622  * }
    623  * \endcode
    624  *
    625  * \note In general, FLAC__StreamEncoder functions which change the
    626  * state should not be called on the \a encoder while in the callback.
    627  *
    628  * \param  encoder  The encoder instance calling the callback.
    629  * \param  absolute_byte_offset  The address at which to store the current
    630  *                               position of the output.
    631  * \param  client_data  The callee's client data set through
    632  *                      FLAC__stream_encoder_init_*().
    633  * \retval FLAC__StreamEncoderTellStatus
    634  *    The callee's return status.
    635  */
    636 typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
    637 
    638 /** Signature for the metadata callback.
    639  *
    640  *  A function pointer matching this signature may be passed to
    641  *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
    642  *  once at the end of encoding with the populated STREAMINFO structure.  This
    643  *  is so the client can seek back to the beginning of the file and write the
    644  *  STREAMINFO block with the correct statistics after encoding (like
    645  *  minimum/maximum frame size and total samples).
    646  *
    647  * \note In general, FLAC__StreamEncoder functions which change the
    648  * state should not be called on the \a encoder while in the callback.
    649  *
    650  * \param  encoder      The encoder instance calling the callback.
    651  * \param  metadata     The final populated STREAMINFO block.
    652  * \param  client_data  The callee's client data set through
    653  *                      FLAC__stream_encoder_init_*().
    654  */
    655 typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
    656 
    657 /** Signature for the progress callback.
    658  *
    659  *  A function pointer matching this signature may be passed to
    660  *  FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
    661  *  The supplied function will be called when the encoder has finished
    662  *  writing a frame.  The \c total_frames_estimate argument to the
    663  *  callback will be based on the value from
    664  *  FLAC__stream_encoder_set_total_samples_estimate().
    665  *
    666  * \note In general, FLAC__StreamEncoder functions which change the
    667  * state should not be called on the \a encoder while in the callback.
    668  *
    669  * \param  encoder          The encoder instance calling the callback.
    670  * \param  bytes_written    Bytes written so far.
    671  * \param  samples_written  Samples written so far.
    672  * \param  frames_written   Frames written so far.
    673  * \param  total_frames_estimate  The estimate of the total number of
    674  *                                frames to be written.
    675  * \param  client_data      The callee's client data set through
    676  *                          FLAC__stream_encoder_init_*().
    677  */
    678 typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
    679 
    680 
    681 /***********************************************************************
    682  *
    683  * Class constructor/destructor
    684  *
    685  ***********************************************************************/
    686 
    687 /** Create a new stream encoder instance.  The instance is created with
    688  *  default settings; see the individual FLAC__stream_encoder_set_*()
    689  *  functions for each setting's default.
    690  *
    691  * \retval FLAC__StreamEncoder*
    692  *    \c NULL if there was an error allocating memory, else the new instance.
    693  */
    694 FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
    695 
    696 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
    697  *
    698  * \param encoder  A pointer to an existing encoder.
    699  * \assert
    700  *    \code encoder != NULL \endcode
    701  */
    702 FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
    703 
    704 
    705 /***********************************************************************
    706  *
    707  * Public class method prototypes
    708  *
    709  ***********************************************************************/
    710 
    711 /** Set the serial number for the FLAC stream to use in the Ogg container.
    712  *
    713  * \note
    714  * This does not need to be set for native FLAC encoding.
    715  *
    716  * \note
    717  * It is recommended to set a serial number explicitly as the default of '0'
    718  * may collide with other streams.
    719  *
    720  * \default \c 0
    721  * \param  encoder        An encoder instance to set.
    722  * \param  serial_number  See above.
    723  * \assert
    724  *    \code encoder != NULL \endcode
    725  * \retval FLAC__bool
    726  *    \c false if the encoder is already initialized, else \c true.
    727  */
    728 FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
    729 
    730 /** Set the "verify" flag.  If \c true, the encoder will verify it's own
    731  *  encoded output by feeding it through an internal decoder and comparing
    732  *  the original signal against the decoded signal.  If a mismatch occurs,
    733  *  the process call will return \c false.  Note that this will slow the
    734  *  encoding process by the extra time required for decoding and comparison.
    735  *
    736  * \default \c false
    737  * \param  encoder  An encoder instance to set.
    738  * \param  value    Flag value (see above).
    739  * \assert
    740  *    \code encoder != NULL \endcode
    741  * \retval FLAC__bool
    742  *    \c false if the encoder is already initialized, else \c true.
    743  */
    744 FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
    745 
    746 /** Set the <A HREF="../format.html#subset">Subset</A> flag.  If \c true,
    747  *  the encoder will comply with the Subset and will check the
    748  *  settings during FLAC__stream_encoder_init_*() to see if all settings
    749  *  comply.  If \c false, the settings may take advantage of the full
    750  *  range that the format allows.
    751  *
    752  *  Make sure you know what it entails before setting this to \c false.
    753  *
    754  * \default \c true
    755  * \param  encoder  An encoder instance to set.
    756  * \param  value    Flag value (see above).
    757  * \assert
    758  *    \code encoder != NULL \endcode
    759  * \retval FLAC__bool
    760  *    \c false if the encoder is already initialized, else \c true.
    761  */
    762 FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
    763 
    764 /** Set the number of channels to be encoded.
    765  *
    766  * \default \c 2
    767  * \param  encoder  An encoder instance to set.
    768  * \param  value    See above.
    769  * \assert
    770  *    \code encoder != NULL \endcode
    771  * \retval FLAC__bool
    772  *    \c false if the encoder is already initialized, else \c true.
    773  */
    774 FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
    775 
    776 /** Set the sample resolution of the input to be encoded.
    777  *
    778  * \warning
    779  * Do not feed the encoder data that is wider than the value you
    780  * set here or you will generate an invalid stream.
    781  *
    782  * \default \c 16
    783  * \param  encoder  An encoder instance to set.
    784  * \param  value    See above.
    785  * \assert
    786  *    \code encoder != NULL \endcode
    787  * \retval FLAC__bool
    788  *    \c false if the encoder is already initialized, else \c true.
    789  */
    790 FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
    791 
    792 /** Set the sample rate (in Hz) of the input to be encoded.
    793  *
    794  * \default \c 44100
    795  * \param  encoder  An encoder instance to set.
    796  * \param  value    See above.
    797  * \assert
    798  *    \code encoder != NULL \endcode
    799  * \retval FLAC__bool
    800  *    \c false if the encoder is already initialized, else \c true.
    801  */
    802 FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
    803 
    804 /** Set the compression level
    805  *
    806  * The compression level is roughly proportional to the amount of effort
    807  * the encoder expends to compress the file.  A higher level usually
    808  * means more computation but higher compression.  The default level is
    809  * suitable for most applications.
    810  *
    811  * Currently the levels range from \c 0 (fastest, least compression) to
    812  * \c 8 (slowest, most compression).  A value larger than \c 8 will be
    813  * treated as \c 8.
    814  *
    815  * This function automatically calls the following other \c _set_
    816  * functions with appropriate values, so the client does not need to
    817  * unless it specifically wants to override them:
    818  * - FLAC__stream_encoder_set_do_mid_side_stereo()
    819  * - FLAC__stream_encoder_set_loose_mid_side_stereo()
    820  * - FLAC__stream_encoder_set_apodization()
    821  * - FLAC__stream_encoder_set_max_lpc_order()
    822  * - FLAC__stream_encoder_set_qlp_coeff_precision()
    823  * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
    824  * - FLAC__stream_encoder_set_do_escape_coding()
    825  * - FLAC__stream_encoder_set_do_exhaustive_model_search()
    826  * - FLAC__stream_encoder_set_min_residual_partition_order()
    827  * - FLAC__stream_encoder_set_max_residual_partition_order()
    828  * - FLAC__stream_encoder_set_rice_parameter_search_dist()
    829  *
    830  * The actual values set for each level are:
    831  * <table>
    832  * <tr>
    833  *  <td><b>level</b></td>
    834  *  <td>do mid-side stereo</td>
    835  *  <td>loose mid-side stereo</td>
    836  *  <td>apodization</td>
    837  *  <td>max lpc order</td>
    838  *  <td>qlp coeff precision</td>
    839  *  <td>qlp coeff prec search</td>
    840  *  <td>escape coding</td>
    841  *  <td>exhaustive model search</td>
    842  *  <td>min residual partition order</td>
    843  *  <td>max residual partition order</td>
    844  *  <td>rice parameter search dist</td>
    845  * </tr>
    846  * <tr>  <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
    847  * <tr>  <td><b>1</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
    848  * <tr>  <td><b>2</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
    849  * <tr>  <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td>                                     <td>6</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
    850  * <tr>  <td><b>4</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)<td>                                     <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
    851  * <tr>  <td><b>5</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)<td>                                     <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr>
    852  * <tr>  <td><b>6</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2)<td>                    <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
    853  * <tr>  <td><b>7</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2)<td>                    <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
    854  * <tr>  <td><b>8</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2);punchout_tukey(3)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
    855  * </table>
    856  *
    857  * \default \c 5
    858  * \param  encoder  An encoder instance to set.
    859  * \param  value    See above.
    860  * \assert
    861  *    \code encoder != NULL \endcode
    862  * \retval FLAC__bool
    863  *    \c false if the encoder is already initialized, else \c true.
    864  */
    865 FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
    866 
    867 /** Set the blocksize to use while encoding.
    868  *
    869  * The number of samples to use per frame.  Use \c 0 to let the encoder
    870  * estimate a blocksize; this is usually best.
    871  *
    872  * \default \c 0
    873  * \param  encoder  An encoder instance to set.
    874  * \param  value    See above.
    875  * \assert
    876  *    \code encoder != NULL \endcode
    877  * \retval FLAC__bool
    878  *    \c false if the encoder is already initialized, else \c true.
    879  */
    880 FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
    881 
    882 /** Set to \c true to enable mid-side encoding on stereo input.  The
    883  *  number of channels must be 2 for this to have any effect.  Set to
    884  *  \c false to use only independent channel coding.
    885  *
    886  * \default \c false
    887  * \param  encoder  An encoder instance to set.
    888  * \param  value    Flag value (see above).
    889  * \assert
    890  *    \code encoder != NULL \endcode
    891  * \retval FLAC__bool
    892  *    \c false if the encoder is already initialized, else \c true.
    893  */
    894 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
    895 
    896 /** Set to \c true to enable adaptive switching between mid-side and
    897  *  left-right encoding on stereo input.  Set to \c false to use
    898  *  exhaustive searching.  Setting this to \c true requires
    899  *  FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
    900  *  \c true in order to have any effect.
    901  *
    902  * \default \c false
    903  * \param  encoder  An encoder instance to set.
    904  * \param  value    Flag value (see above).
    905  * \assert
    906  *    \code encoder != NULL \endcode
    907  * \retval FLAC__bool
    908  *    \c false if the encoder is already initialized, else \c true.
    909  */
    910 FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
    911 
    912 /** Sets the apodization function(s) the encoder will use when windowing
    913  *  audio data for LPC analysis.
    914  *
    915  * The \a specification is a plain ASCII string which specifies exactly
    916  * which functions to use.  There may be more than one (up to 32),
    917  * separated by \c ';' characters.  Some functions take one or more
    918  * comma-separated arguments in parentheses.
    919  *
    920  * The available functions are \c bartlett, \c bartlett_hann,
    921  * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
    922  * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
    923  * \c rectangle, \c triangle, \c tukey(P), \c partial_tukey(n[/ov[/P]]),
    924  * \c punchout_tukey(n[/ov[/P]]), \c welch.
    925  *
    926  * For \c gauss(STDDEV), STDDEV specifies the standard deviation
    927  * (0<STDDEV<=0.5).
    928  *
    929  * For \c tukey(P), P specifies the fraction of the window that is
    930  * tapered (0<=P<=1).  P=0 corresponds to \c rectangle and P=1
    931  * corresponds to \c hann.
    932  *
    933  * Specifying \c partial_tukey or \c punchout_tukey works a little
    934  * different. These do not specify a single apodization function, but
    935  * a series of them with some overlap. partial_tukey specifies a series
    936  * of small windows (all treated separately) while punchout_tukey
    937  * specifies a series of windows that have a hole in them. In this way,
    938  * the predictor is constructed with only a part of the block, which
    939  * helps in case a block consists of dissimilar parts.
    940  *
    941  * The three parameters that can be specified for the functions are
    942  * n, ov and P. n is the number of functions to add, ov is the overlap
    943  * of the windows in case of partial_tukey and the overlap in the gaps
    944  * in case of punchout_tukey. P is the fraction of the window that is
    945  * tapered, like with a regular tukey window. The function can be
    946  * specified with only a number, a number and an overlap, or a number
    947  * an overlap and a P, for example, partial_tukey(3), partial_tukey(3/0.3)
    948  * and partial_tukey(3/0.3/0.5) are all valid. ov should be smaller than 1
    949  * and can be negative.
    950  *
    951  * Example specifications are \c "blackman" or
    952  * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
    953  *
    954  * Any function that is specified erroneously is silently dropped.  Up
    955  * to 32 functions are kept, the rest are dropped.  If the specification
    956  * is empty the encoder defaults to \c "tukey(0.5)".
    957  *
    958  * When more than one function is specified, then for every subframe the
    959  * encoder will try each of them separately and choose the window that
    960  * results in the smallest compressed subframe.
    961  *
    962  * Note that each function specified causes the encoder to occupy a
    963  * floating point array in which to store the window. Also note that the
    964  * values of P, STDDEV and ov are locale-specific, so if the comma
    965  * separator specified by the locale is a comma, a comma should be used.
    966  *
    967  * \default \c "tukey(0.5)"
    968  * \param  encoder        An encoder instance to set.
    969  * \param  specification  See above.
    970  * \assert
    971  *    \code encoder != NULL \endcode
    972  *    \code specification != NULL \endcode
    973  * \retval FLAC__bool
    974  *    \c false if the encoder is already initialized, else \c true.
    975  */
    976 FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
    977 
    978 /** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
    979  *
    980  * \default \c 0
    981  * \param  encoder  An encoder instance to set.
    982  * \param  value    See above.
    983  * \assert
    984  *    \code encoder != NULL \endcode
    985  * \retval FLAC__bool
    986  *    \c false if the encoder is already initialized, else \c true.
    987  */
    988 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
    989 
    990 /** Set the precision, in bits, of the quantized linear predictor
    991  *  coefficients, or \c 0 to let the encoder select it based on the
    992  *  blocksize.
    993  *
    994  * \note
    995  * In the current implementation, qlp_coeff_precision + bits_per_sample must
    996  * be less than 32.
    997  *
    998  * \default \c 0
    999  * \param  encoder  An encoder instance to set.
   1000  * \param  value    See above.
   1001  * \assert
   1002  *    \code encoder != NULL \endcode
   1003  * \retval FLAC__bool
   1004  *    \c false if the encoder is already initialized, else \c true.
   1005  */
   1006 FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
   1007 
   1008 /** Set to \c false to use only the specified quantized linear predictor
   1009  *  coefficient precision, or \c true to search neighboring precision
   1010  *  values and use the best one.
   1011  *
   1012  * \default \c false
   1013  * \param  encoder  An encoder instance to set.
   1014  * \param  value    See above.
   1015  * \assert
   1016  *    \code encoder != NULL \endcode
   1017  * \retval FLAC__bool
   1018  *    \c false if the encoder is already initialized, else \c true.
   1019  */
   1020 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1021 
   1022 /** Deprecated.  Setting this value has no effect.
   1023  *
   1024  * \default \c false
   1025  * \param  encoder  An encoder instance to set.
   1026  * \param  value    See above.
   1027  * \assert
   1028  *    \code encoder != NULL \endcode
   1029  * \retval FLAC__bool
   1030  *    \c false if the encoder is already initialized, else \c true.
   1031  */
   1032 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1033 
   1034 /** Set to \c false to let the encoder estimate the best model order
   1035  *  based on the residual signal energy, or \c true to force the
   1036  *  encoder to evaluate all order models and select the best.
   1037  *
   1038  * \default \c false
   1039  * \param  encoder  An encoder instance to set.
   1040  * \param  value    See above.
   1041  * \assert
   1042  *    \code encoder != NULL \endcode
   1043  * \retval FLAC__bool
   1044  *    \c false if the encoder is already initialized, else \c true.
   1045  */
   1046 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1047 
   1048 /** Set the minimum partition order to search when coding the residual.
   1049  *  This is used in tandem with
   1050  *  FLAC__stream_encoder_set_max_residual_partition_order().
   1051  *
   1052  *  The partition order determines the context size in the residual.
   1053  *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
   1054  *
   1055  *  Set both min and max values to \c 0 to force a single context,
   1056  *  whose Rice parameter is based on the residual signal variance.
   1057  *  Otherwise, set a min and max order, and the encoder will search
   1058  *  all orders, using the mean of each context for its Rice parameter,
   1059  *  and use the best.
   1060  *
   1061  * \default \c 0
   1062  * \param  encoder  An encoder instance to set.
   1063  * \param  value    See above.
   1064  * \assert
   1065  *    \code encoder != NULL \endcode
   1066  * \retval FLAC__bool
   1067  *    \c false if the encoder is already initialized, else \c true.
   1068  */
   1069 FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
   1070 
   1071 /** Set the maximum partition order to search when coding the residual.
   1072  *  This is used in tandem with
   1073  *  FLAC__stream_encoder_set_min_residual_partition_order().
   1074  *
   1075  *  The partition order determines the context size in the residual.
   1076  *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
   1077  *
   1078  *  Set both min and max values to \c 0 to force a single context,
   1079  *  whose Rice parameter is based on the residual signal variance.
   1080  *  Otherwise, set a min and max order, and the encoder will search
   1081  *  all orders, using the mean of each context for its Rice parameter,
   1082  *  and use the best.
   1083  *
   1084  * \default \c 0
   1085  * \param  encoder  An encoder instance to set.
   1086  * \param  value    See above.
   1087  * \assert
   1088  *    \code encoder != NULL \endcode
   1089  * \retval FLAC__bool
   1090  *    \c false if the encoder is already initialized, else \c true.
   1091  */
   1092 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
   1093 
   1094 /** Deprecated.  Setting this value has no effect.
   1095  *
   1096  * \default \c 0
   1097  * \param  encoder  An encoder instance to set.
   1098  * \param  value    See above.
   1099  * \assert
   1100  *    \code encoder != NULL \endcode
   1101  * \retval FLAC__bool
   1102  *    \c false if the encoder is already initialized, else \c true.
   1103  */
   1104 FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
   1105 
   1106 /** Set an estimate of the total samples that will be encoded.
   1107  *  This is merely an estimate and may be set to \c 0 if unknown.
   1108  *  This value will be written to the STREAMINFO block before encoding,
   1109  *  and can remove the need for the caller to rewrite the value later
   1110  *  if the value is known before encoding.
   1111  *
   1112  * \default \c 0
   1113  * \param  encoder  An encoder instance to set.
   1114  * \param  value    See above.
   1115  * \assert
   1116  *    \code encoder != NULL \endcode
   1117  * \retval FLAC__bool
   1118  *    \c false if the encoder is already initialized, else \c true.
   1119  */
   1120 FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
   1121 
   1122 /** Set the metadata blocks to be emitted to the stream before encoding.
   1123  *  A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
   1124  *  array of pointers to metadata blocks.  The array is non-const since
   1125  *  the encoder may need to change the \a is_last flag inside them, and
   1126  *  in some cases update seek point offsets.  Otherwise, the encoder will
   1127  *  not modify or free the blocks.  It is up to the caller to free the
   1128  *  metadata blocks after encoding finishes.
   1129  *
   1130  * \note
   1131  * The encoder stores only copies of the pointers in the \a metadata array;
   1132  * the metadata blocks themselves must survive at least until after
   1133  * FLAC__stream_encoder_finish() returns.  Do not free the blocks until then.
   1134  *
   1135  * \note
   1136  * The STREAMINFO block is always written and no STREAMINFO block may
   1137  * occur in the supplied array.
   1138  *
   1139  * \note
   1140  * By default the encoder does not create a SEEKTABLE.  If one is supplied
   1141  * in the \a metadata array, but the client has specified that it does not
   1142  * support seeking, then the SEEKTABLE will be written verbatim.  However
   1143  * by itself this is not very useful as the client will not know the stream
   1144  * offsets for the seekpoints ahead of time.  In order to get a proper
   1145  * seektable the client must support seeking.  See next note.
   1146  *
   1147  * \note
   1148  * SEEKTABLE blocks are handled specially.  Since you will not know
   1149  * the values for the seek point stream offsets, you should pass in
   1150  * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
   1151  * required sample numbers (or placeholder points), with \c 0 for the
   1152  * \a frame_samples and \a stream_offset fields for each point.  If the
   1153  * client has specified that it supports seeking by providing a seek
   1154  * callback to FLAC__stream_encoder_init_stream() or both seek AND read
   1155  * callback to FLAC__stream_encoder_init_ogg_stream() (or by using
   1156  * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()),
   1157  * then while it is encoding the encoder will fill the stream offsets in
   1158  * for you and when encoding is finished, it will seek back and write the
   1159  * real values into the SEEKTABLE block in the stream.  There are helper
   1160  * routines for manipulating seektable template blocks; see metadata.h:
   1161  * FLAC__metadata_object_seektable_template_*().  If the client does
   1162  * not support seeking, the SEEKTABLE will have inaccurate offsets which
   1163  * will slow down or remove the ability to seek in the FLAC stream.
   1164  *
   1165  * \note
   1166  * The encoder instance \b will modify the first \c SEEKTABLE block
   1167  * as it transforms the template to a valid seektable while encoding,
   1168  * but it is still up to the caller to free all metadata blocks after
   1169  * encoding.
   1170  *
   1171  * \note
   1172  * A VORBIS_COMMENT block may be supplied.  The vendor string in it
   1173  * will be ignored.  libFLAC will use it's own vendor string. libFLAC
   1174  * will not modify the passed-in VORBIS_COMMENT's vendor string, it
   1175  * will simply write it's own into the stream.  If no VORBIS_COMMENT
   1176  * block is present in the \a metadata array, libFLAC will write an
   1177  * empty one, containing only the vendor string.
   1178  *
   1179  * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
   1180  * the second metadata block of the stream.  The encoder already supplies
   1181  * the STREAMINFO block automatically.  If \a metadata does not contain a
   1182  * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
   1183  * \a metadata does contain a VORBIS_COMMENT block and it is not the
   1184  * first, the init function will reorder \a metadata by moving the
   1185  * VORBIS_COMMENT block to the front; the relative ordering of the other
   1186  * blocks will remain as they were.
   1187  *
   1188  * \note The Ogg FLAC mapping limits the number of metadata blocks per
   1189  * stream to \c 65535.  If \a num_blocks exceeds this the function will
   1190  * return \c false.
   1191  *
   1192  * \default \c NULL, 0
   1193  * \param  encoder     An encoder instance to set.
   1194  * \param  metadata    See above.
   1195  * \param  num_blocks  See above.
   1196  * \assert
   1197  *    \code encoder != NULL \endcode
   1198  * \retval FLAC__bool
   1199  *    \c false if the encoder is already initialized, else \c true.
   1200  *    \c false if the encoder is already initialized, or if
   1201  *    \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
   1202  */
   1203 FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
   1204 
   1205 /** Get the current encoder state.
   1206  *
   1207  * \param  encoder  An encoder instance to query.
   1208  * \assert
   1209  *    \code encoder != NULL \endcode
   1210  * \retval FLAC__StreamEncoderState
   1211  *    The current encoder state.
   1212  */
   1213 FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
   1214 
   1215 /** Get the state of the verify stream decoder.
   1216  *  Useful when the stream encoder state is
   1217  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
   1218  *
   1219  * \param  encoder  An encoder instance to query.
   1220  * \assert
   1221  *    \code encoder != NULL \endcode
   1222  * \retval FLAC__StreamDecoderState
   1223  *    The verify stream decoder state.
   1224  */
   1225 FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
   1226 
   1227 /** Get the current encoder state as a C string.
   1228  *  This version automatically resolves
   1229  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
   1230  *  verify decoder's state.
   1231  *
   1232  * \param  encoder  A encoder instance to query.
   1233  * \assert
   1234  *    \code encoder != NULL \endcode
   1235  * \retval const char *
   1236  *    The encoder state as a C string.  Do not modify the contents.
   1237  */
   1238 FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
   1239 
   1240 /** Get relevant values about the nature of a verify decoder error.
   1241  *  Useful when the stream encoder state is
   1242  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.  The arguments should
   1243  *  be addresses in which the stats will be returned, or NULL if value
   1244  *  is not desired.
   1245  *
   1246  * \param  encoder  An encoder instance to query.
   1247  * \param  absolute_sample  The absolute sample number of the mismatch.
   1248  * \param  frame_number  The number of the frame in which the mismatch occurred.
   1249  * \param  channel       The channel in which the mismatch occurred.
   1250  * \param  sample        The number of the sample (relative to the frame) in
   1251  *                       which the mismatch occurred.
   1252  * \param  expected      The expected value for the sample in question.
   1253  * \param  got           The actual value returned by the decoder.
   1254  * \assert
   1255  *    \code encoder != NULL \endcode
   1256  */
   1257 FLAC_API void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
   1258 
   1259 /** Get the "verify" flag.
   1260  *
   1261  * \param  encoder  An encoder instance to query.
   1262  * \assert
   1263  *    \code encoder != NULL \endcode
   1264  * \retval FLAC__bool
   1265  *    See FLAC__stream_encoder_set_verify().
   1266  */
   1267 FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
   1268 
   1269 /** Get the <A HREF="../format.html#subset>Subset</A> flag.
   1270  *
   1271  * \param  encoder  An encoder instance to query.
   1272  * \assert
   1273  *    \code encoder != NULL \endcode
   1274  * \retval FLAC__bool
   1275  *    See FLAC__stream_encoder_set_streamable_subset().
   1276  */
   1277 FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
   1278 
   1279 /** Get the number of input channels being processed.
   1280  *
   1281  * \param  encoder  An encoder instance to query.
   1282  * \assert
   1283  *    \code encoder != NULL \endcode
   1284  * \retval unsigned
   1285  *    See FLAC__stream_encoder_set_channels().
   1286  */
   1287 FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
   1288 
   1289 /** Get the input sample resolution setting.
   1290  *
   1291  * \param  encoder  An encoder instance to query.
   1292  * \assert
   1293  *    \code encoder != NULL \endcode
   1294  * \retval unsigned
   1295  *    See FLAC__stream_encoder_set_bits_per_sample().
   1296  */
   1297 FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
   1298 
   1299 /** Get the input sample rate setting.
   1300  *
   1301  * \param  encoder  An encoder instance to query.
   1302  * \assert
   1303  *    \code encoder != NULL \endcode
   1304  * \retval unsigned
   1305  *    See FLAC__stream_encoder_set_sample_rate().
   1306  */
   1307 FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
   1308 
   1309 /** Get the blocksize setting.
   1310  *
   1311  * \param  encoder  An encoder instance to query.
   1312  * \assert
   1313  *    \code encoder != NULL \endcode
   1314  * \retval unsigned
   1315  *    See FLAC__stream_encoder_set_blocksize().
   1316  */
   1317 FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
   1318 
   1319 /** Get the "mid/side stereo coding" flag.
   1320  *
   1321  * \param  encoder  An encoder instance to query.
   1322  * \assert
   1323  *    \code encoder != NULL \endcode
   1324  * \retval FLAC__bool
   1325  *    See FLAC__stream_encoder_get_do_mid_side_stereo().
   1326  */
   1327 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
   1328 
   1329 /** Get the "adaptive mid/side switching" flag.
   1330  *
   1331  * \param  encoder  An encoder instance to query.
   1332  * \assert
   1333  *    \code encoder != NULL \endcode
   1334  * \retval FLAC__bool
   1335  *    See FLAC__stream_encoder_set_loose_mid_side_stereo().
   1336  */
   1337 FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
   1338 
   1339 /** Get the maximum LPC order setting.
   1340  *
   1341  * \param  encoder  An encoder instance to query.
   1342  * \assert
   1343  *    \code encoder != NULL \endcode
   1344  * \retval unsigned
   1345  *    See FLAC__stream_encoder_set_max_lpc_order().
   1346  */
   1347 FLAC_API unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
   1348 
   1349 /** Get the quantized linear predictor coefficient precision setting.
   1350  *
   1351  * \param  encoder  An encoder instance to query.
   1352  * \assert
   1353  *    \code encoder != NULL \endcode
   1354  * \retval unsigned
   1355  *    See FLAC__stream_encoder_set_qlp_coeff_precision().
   1356  */
   1357 FLAC_API unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
   1358 
   1359 /** Get the qlp coefficient precision search flag.
   1360  *
   1361  * \param  encoder  An encoder instance to query.
   1362  * \assert
   1363  *    \code encoder != NULL \endcode
   1364  * \retval FLAC__bool
   1365  *    See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
   1366  */
   1367 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
   1368 
   1369 /** Get the "escape coding" flag.
   1370  *
   1371  * \param  encoder  An encoder instance to query.
   1372  * \assert
   1373  *    \code encoder != NULL \endcode
   1374  * \retval FLAC__bool
   1375  *    See FLAC__stream_encoder_set_do_escape_coding().
   1376  */
   1377 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
   1378 
   1379 /** Get the exhaustive model search flag.
   1380  *
   1381  * \param  encoder  An encoder instance to query.
   1382  * \assert
   1383  *    \code encoder != NULL \endcode
   1384  * \retval FLAC__bool
   1385  *    See FLAC__stream_encoder_set_do_exhaustive_model_search().
   1386  */
   1387 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
   1388 
   1389 /** Get the minimum residual partition order setting.
   1390  *
   1391  * \param  encoder  An encoder instance to query.
   1392  * \assert
   1393  *    \code encoder != NULL \endcode
   1394  * \retval unsigned
   1395  *    See FLAC__stream_encoder_set_min_residual_partition_order().
   1396  */
   1397 FLAC_API unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
   1398 
   1399 /** Get maximum residual partition order setting.
   1400  *
   1401  * \param  encoder  An encoder instance to query.
   1402  * \assert
   1403  *    \code encoder != NULL \endcode
   1404  * \retval unsigned
   1405  *    See FLAC__stream_encoder_set_max_residual_partition_order().
   1406  */
   1407 FLAC_API unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
   1408 
   1409 /** Get the Rice parameter search distance setting.
   1410  *
   1411  * \param  encoder  An encoder instance to query.
   1412  * \assert
   1413  *    \code encoder != NULL \endcode
   1414  * \retval unsigned
   1415  *    See FLAC__stream_encoder_set_rice_parameter_search_dist().
   1416  */
   1417 FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
   1418 
   1419 /** Get the previously set estimate of the total samples to be encoded.
   1420  *  The encoder merely mimics back the value given to
   1421  *  FLAC__stream_encoder_set_total_samples_estimate() since it has no
   1422  *  other way of knowing how many samples the client will encode.
   1423  *
   1424  * \param  encoder  An encoder instance to set.
   1425  * \assert
   1426  *    \code encoder != NULL \endcode
   1427  * \retval FLAC__uint64
   1428  *    See FLAC__stream_encoder_get_total_samples_estimate().
   1429  */
   1430 FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
   1431 
   1432 /** Initialize the encoder instance to encode native FLAC streams.
   1433  *
   1434  *  This flavor of initialization sets up the encoder to encode to a
   1435  *  native FLAC stream. I/O is performed via callbacks to the client.
   1436  *  For encoding to a plain file via filename or open \c FILE*,
   1437  *  FLAC__stream_encoder_init_file() and FLAC__stream_encoder_init_FILE()
   1438  *  provide a simpler interface.
   1439  *
   1440  *  This function should be called after FLAC__stream_encoder_new() and
   1441  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1442  *  or FLAC__stream_encoder_process_interleaved().
   1443  *  initialization succeeded.
   1444  *
   1445  *  The call to FLAC__stream_encoder_init_stream() currently will also
   1446  *  immediately call the write callback several times, once with the \c fLaC
   1447  *  signature, and once for each encoded metadata block.
   1448  *
   1449  * \param  encoder            An uninitialized encoder instance.
   1450  * \param  write_callback     See FLAC__StreamEncoderWriteCallback.  This
   1451  *                            pointer must not be \c NULL.
   1452  * \param  seek_callback      See FLAC__StreamEncoderSeekCallback.  This
   1453  *                            pointer may be \c NULL if seeking is not
   1454  *                            supported.  The encoder uses seeking to go back
   1455  *                            and write some some stream statistics to the
   1456  *                            STREAMINFO block; this is recommended but not
   1457  *                            necessary to create a valid FLAC stream.  If
   1458  *                            \a seek_callback is not \c NULL then a
   1459  *                            \a tell_callback must also be supplied.
   1460  *                            Alternatively, a dummy seek callback that just
   1461  *                            returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
   1462  *                            may also be supplied, all though this is slightly
   1463  *                            less efficient for the encoder.
   1464  * \param  tell_callback      See FLAC__StreamEncoderTellCallback.  This
   1465  *                            pointer may be \c NULL if seeking is not
   1466  *                            supported.  If \a seek_callback is \c NULL then
   1467  *                            this argument will be ignored.  If
   1468  *                            \a seek_callback is not \c NULL then a
   1469  *                            \a tell_callback must also be supplied.
   1470  *                            Alternatively, a dummy tell callback that just
   1471  *                            returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
   1472  *                            may also be supplied, all though this is slightly
   1473  *                            less efficient for the encoder.
   1474  * \param  metadata_callback  See FLAC__StreamEncoderMetadataCallback.  This
   1475  *                            pointer may be \c NULL if the callback is not
   1476  *                            desired.  If the client provides a seek callback,
   1477  *                            this function is not necessary as the encoder
   1478  *                            will automatically seek back and update the
   1479  *                            STREAMINFO block.  It may also be \c NULL if the
   1480  *                            client does not support seeking, since it will
   1481  *                            have no way of going back to update the
   1482  *                            STREAMINFO.  However the client can still supply
   1483  *                            a callback if it would like to know the details
   1484  *                            from the STREAMINFO.
   1485  * \param  client_data        This value will be supplied to callbacks in their
   1486  *                            \a client_data argument.
   1487  * \assert
   1488  *    \code encoder != NULL \endcode
   1489  * \retval FLAC__StreamEncoderInitStatus
   1490  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1491  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1492  */
   1493 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
   1494 
   1495 /** Initialize the encoder instance to encode Ogg FLAC streams.
   1496  *
   1497  *  This flavor of initialization sets up the encoder to encode to a FLAC
   1498  *  stream in an Ogg container.  I/O is performed via callbacks to the
   1499  *  client.  For encoding to a plain file via filename or open \c FILE*,
   1500  *  FLAC__stream_encoder_init_ogg_file() and FLAC__stream_encoder_init_ogg_FILE()
   1501  *  provide a simpler interface.
   1502  *
   1503  *  This function should be called after FLAC__stream_encoder_new() and
   1504  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1505  *  or FLAC__stream_encoder_process_interleaved().
   1506  *  initialization succeeded.
   1507  *
   1508  *  The call to FLAC__stream_encoder_init_ogg_stream() currently will also
   1509  *  immediately call the write callback several times to write the metadata
   1510  *  packets.
   1511  *
   1512  * \param  encoder            An uninitialized encoder instance.
   1513  * \param  read_callback      See FLAC__StreamEncoderReadCallback.  This
   1514  *                            pointer must not be \c NULL if \a seek_callback
   1515  *                            is non-NULL since they are both needed to be
   1516  *                            able to write data back to the Ogg FLAC stream
   1517  *                            in the post-encode phase.
   1518  * \param  write_callback     See FLAC__StreamEncoderWriteCallback.  This
   1519  *                            pointer must not be \c NULL.
   1520  * \param  seek_callback      See FLAC__StreamEncoderSeekCallback.  This
   1521  *                            pointer may be \c NULL if seeking is not
   1522  *                            supported.  The encoder uses seeking to go back
   1523  *                            and write some some stream statistics to the
   1524  *                            STREAMINFO block; this is recommended but not
   1525  *                            necessary to create a valid FLAC stream.  If
   1526  *                            \a seek_callback is not \c NULL then a
   1527  *                            \a tell_callback must also be supplied.
   1528  *                            Alternatively, a dummy seek callback that just
   1529  *                            returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
   1530  *                            may also be supplied, all though this is slightly
   1531  *                            less efficient for the encoder.
   1532  * \param  tell_callback      See FLAC__StreamEncoderTellCallback.  This
   1533  *                            pointer may be \c NULL if seeking is not
   1534  *                            supported.  If \a seek_callback is \c NULL then
   1535  *                            this argument will be ignored.  If
   1536  *                            \a seek_callback is not \c NULL then a
   1537  *                            \a tell_callback must also be supplied.
   1538  *                            Alternatively, a dummy tell callback that just
   1539  *                            returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
   1540  *                            may also be supplied, all though this is slightly
   1541  *                            less efficient for the encoder.
   1542  * \param  metadata_callback  See FLAC__StreamEncoderMetadataCallback.  This
   1543  *                            pointer may be \c NULL if the callback is not
   1544  *                            desired.  If the client provides a seek callback,
   1545  *                            this function is not necessary as the encoder
   1546  *                            will automatically seek back and update the
   1547  *                            STREAMINFO block.  It may also be \c NULL if the
   1548  *                            client does not support seeking, since it will
   1549  *                            have no way of going back to update the
   1550  *                            STREAMINFO.  However the client can still supply
   1551  *                            a callback if it would like to know the details
   1552  *                            from the STREAMINFO.
   1553  * \param  client_data        This value will be supplied to callbacks in their
   1554  *                            \a client_data argument.
   1555  * \assert
   1556  *    \code encoder != NULL \endcode
   1557  * \retval FLAC__StreamEncoderInitStatus
   1558  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1559  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1560  */
   1561 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderReadCallback read_callback, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
   1562 
   1563 /** Initialize the encoder instance to encode native FLAC files.
   1564  *
   1565  *  This flavor of initialization sets up the encoder to encode to a
   1566  *  plain native FLAC file.  For non-stdio streams, you must use
   1567  *  FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
   1568  *
   1569  *  This function should be called after FLAC__stream_encoder_new() and
   1570  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1571  *  or FLAC__stream_encoder_process_interleaved().
   1572  *  initialization succeeded.
   1573  *
   1574  * \param  encoder            An uninitialized encoder instance.
   1575  * \param  file               An open file.  The file should have been opened
   1576  *                            with mode \c "w+b" and rewound.  The file
   1577  *                            becomes owned by the encoder and should not be
   1578  *                            manipulated by the client while encoding.
   1579  *                            Unless \a file is \c stdout, it will be closed
   1580  *                            when FLAC__stream_encoder_finish() is called.
   1581  *                            Note however that a proper SEEKTABLE cannot be
   1582  *                            created when encoding to \c stdout since it is
   1583  *                            not seekable.
   1584  * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
   1585  *                            pointer may be \c NULL if the callback is not
   1586  *                            desired.
   1587  * \param  client_data        This value will be supplied to callbacks in their
   1588  *                            \a client_data argument.
   1589  * \assert
   1590  *    \code encoder != NULL \endcode
   1591  *    \code file != NULL \endcode
   1592  * \retval FLAC__StreamEncoderInitStatus
   1593  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1594  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1595  */
   1596 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
   1597 
   1598 /** Initialize the encoder instance to encode Ogg FLAC files.
   1599  *
   1600  *  This flavor of initialization sets up the encoder to encode to a
   1601  *  plain Ogg FLAC file.  For non-stdio streams, you must use
   1602  *  FLAC__stream_encoder_init_ogg_stream() and provide callbacks for the I/O.
   1603  *
   1604  *  This function should be called after FLAC__stream_encoder_new() and
   1605  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1606  *  or FLAC__stream_encoder_process_interleaved().
   1607  *  initialization succeeded.
   1608  *
   1609  * \param  encoder            An uninitialized encoder instance.
   1610  * \param  file               An open file.  The file should have been opened
   1611  *                            with mode \c "w+b" and rewound.  The file
   1612  *                            becomes owned by the encoder and should not be
   1613  *                            manipulated by the client while encoding.
   1614  *                            Unless \a file is \c stdout, it will be closed
   1615  *                            when FLAC__stream_encoder_finish() is called.
   1616  *                            Note however that a proper SEEKTABLE cannot be
   1617  *                            created when encoding to \c stdout since it is
   1618  *                            not seekable.
   1619  * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
   1620  *                            pointer may be \c NULL if the callback is not
   1621  *                            desired.
   1622  * \param  client_data        This value will be supplied to callbacks in their
   1623  *                            \a client_data argument.
   1624  * \assert
   1625  *    \code encoder != NULL \endcode
   1626  *    \code file != NULL \endcode
   1627  * \retval FLAC__StreamEncoderInitStatus
   1628  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1629  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1630  */
   1631 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
   1632 
   1633 /** Initialize the encoder instance to encode native FLAC files.
   1634  *
   1635  *  This flavor of initialization sets up the encoder to encode to a plain
   1636  *  FLAC file.  If POSIX fopen() semantics are not sufficient (for example,
   1637  *  with Unicode filenames on Windows), you must use
   1638  *  FLAC__stream_encoder_init_FILE(), or FLAC__stream_encoder_init_stream()
   1639  *  and provide callbacks for the I/O.
   1640  *
   1641  *  This function should be called after FLAC__stream_encoder_new() and
   1642  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1643  *  or FLAC__stream_encoder_process_interleaved().
   1644  *  initialization succeeded.
   1645  *
   1646  * \param  encoder            An uninitialized encoder instance.
   1647  * \param  filename           The name of the file to encode to.  The file will
   1648  *                            be opened with fopen().  Use \c NULL to encode to
   1649  *                            \c stdout.  Note however that a proper SEEKTABLE
   1650  *                            cannot be created when encoding to \c stdout since
   1651  *                            it is not seekable.
   1652  * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
   1653  *                            pointer may be \c NULL if the callback is not
   1654  *                            desired.
   1655  * \param  client_data        This value will be supplied to callbacks in their
   1656  *                            \a client_data argument.
   1657  * \assert
   1658  *    \code encoder != NULL \endcode
   1659  * \retval FLAC__StreamEncoderInitStatus
   1660  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1661  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1662  */
   1663 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
   1664 
   1665 /** Initialize the encoder instance to encode Ogg FLAC files.
   1666  *
   1667  *  This flavor of initialization sets up the encoder to encode to a plain
   1668  *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient (for example,
   1669  *  with Unicode filenames on Windows), you must use
   1670  *  FLAC__stream_encoder_init_ogg_FILE(), or FLAC__stream_encoder_init_ogg_stream()
   1671  *  and provide callbacks for the I/O.
   1672  *
   1673  *  This function should be called after FLAC__stream_encoder_new() and
   1674  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
   1675  *  or FLAC__stream_encoder_process_interleaved().
   1676  *  initialization succeeded.
   1677  *
   1678  * \param  encoder            An uninitialized encoder instance.
   1679  * \param  filename           The name of the file to encode to.  The file will
   1680  *                            be opened with fopen().  Use \c NULL to encode to
   1681  *                            \c stdout.  Note however that a proper SEEKTABLE
   1682  *                            cannot be created when encoding to \c stdout since
   1683  *                            it is not seekable.
   1684  * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
   1685  *                            pointer may be \c NULL if the callback is not
   1686  *                            desired.
   1687  * \param  client_data        This value will be supplied to callbacks in their
   1688  *                            \a client_data argument.
   1689  * \assert
   1690  *    \code encoder != NULL \endcode
   1691  * \retval FLAC__StreamEncoderInitStatus
   1692  *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
   1693  *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
   1694  */
   1695 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
   1696 
   1697 /** Finish the encoding process.
   1698  *  Flushes the encoding buffer, releases resources, resets the encoder
   1699  *  settings to their defaults, and returns the encoder state to
   1700  *  FLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
   1701  *  one or more write callbacks before returning, and will generate
   1702  *  a metadata callback.
   1703  *
   1704  *  Note that in the course of processing the last frame, errors can
   1705  *  occur, so the caller should be sure to check the return value to
   1706  *  ensure the file was encoded properly.
   1707  *
   1708  *  In the event of a prematurely-terminated encode, it is not strictly
   1709  *  necessary to call this immediately before FLAC__stream_encoder_delete()
   1710  *  but it is good practice to match every FLAC__stream_encoder_init_*()
   1711  *  with a FLAC__stream_encoder_finish().
   1712  *
   1713  * \param  encoder  An uninitialized encoder instance.
   1714  * \assert
   1715  *    \code encoder != NULL \endcode
   1716  * \retval FLAC__bool
   1717  *    \c false if an error occurred processing the last frame; or if verify
   1718  *    mode is set (see FLAC__stream_encoder_set_verify()), there was a
   1719  *    verify mismatch; else \c true.  If \c false, caller should check the
   1720  *    state with FLAC__stream_encoder_get_state() for more information
   1721  *    about the error.
   1722  */
   1723 FLAC_API FLAC__bool FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
   1724 
   1725 /** Submit data for encoding.
   1726  *  This version allows you to supply the input data via an array of
   1727  *  pointers, each pointer pointing to an array of \a samples samples
   1728  *  representing one channel.  The samples need not be block-aligned,
   1729  *  but each channel should have the same number of samples.  Each sample
   1730  *  should be a signed integer, right-justified to the resolution set by
   1731  *  FLAC__stream_encoder_set_bits_per_sample().  For example, if the
   1732  *  resolution is 16 bits per sample, the samples should all be in the
   1733  *  range [-32768,32767].
   1734  *
   1735  *  For applications where channel order is important, channels must
   1736  *  follow the order as described in the
   1737  *  <A HREF="../format.html#frame_header">frame header</A>.
   1738  *
   1739  * \param  encoder  An initialized encoder instance in the OK state.
   1740  * \param  buffer   An array of pointers to each channel's signal.
   1741  * \param  samples  The number of samples in one channel.
   1742  * \assert
   1743  *    \code encoder != NULL \endcode
   1744  *    \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
   1745  * \retval FLAC__bool
   1746  *    \c true if successful, else \c false; in this case, check the
   1747  *    encoder state with FLAC__stream_encoder_get_state() to see what
   1748  *    went wrong.
   1749  */
   1750 FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
   1751 
   1752 /** Submit data for encoding.
   1753  *  This version allows you to supply the input data where the channels
   1754  *  are interleaved into a single array (i.e. channel0_sample0,
   1755  *  channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
   1756  *  The samples need not be block-aligned but they must be
   1757  *  sample-aligned, i.e. the first value should be channel0_sample0
   1758  *  and the last value channelN_sampleM.  Each sample should be a signed
   1759  *  integer, right-justified to the resolution set by
   1760  *  FLAC__stream_encoder_set_bits_per_sample().  For example, if the
   1761  *  resolution is 16 bits per sample, the samples should all be in the
   1762  *  range [-32768,32767].
   1763  *
   1764  *  For applications where channel order is important, channels must
   1765  *  follow the order as described in the
   1766  *  <A HREF="../format.html#frame_header">frame header</A>.
   1767  *
   1768  * \param  encoder  An initialized encoder instance in the OK state.
   1769  * \param  buffer   An array of channel-interleaved data (see above).
   1770  * \param  samples  The number of samples in one channel, the same as for
   1771  *                  FLAC__stream_encoder_process().  For example, if
   1772  *                  encoding two channels, \c 1000 \a samples corresponds
   1773  *                  to a \a buffer of 2000 values.
   1774  * \assert
   1775  *    \code encoder != NULL \endcode
   1776  *    \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
   1777  * \retval FLAC__bool
   1778  *    \c true if successful, else \c false; in this case, check the
   1779  *    encoder state with FLAC__stream_encoder_get_state() to see what
   1780  *    went wrong.
   1781  */
   1782 FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
   1783 
   1784 /* \} */
   1785 
   1786 #ifdef __cplusplus
   1787 }
   1788 #endif
   1789 
   1790 #endif
   1791