VisualC/external/include/FLAC/stream_encoder.h
changeset 556 2686e67b59fd
parent 532 b8e8ae4852b2
child 748 5515b36f95ed
child 937 3797c39725bf
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/VisualC/external/include/FLAC/stream_encoder.h	Mon Jan 09 04:20:54 2012 -0500
     1.3 @@ -0,0 +1,1768 @@
     1.4 +/* libFLAC - Free Lossless Audio Codec library
     1.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     1.6 + *
     1.7 + * Redistribution and use in source and binary forms, with or without
     1.8 + * modification, are permitted provided that the following conditions
     1.9 + * are met:
    1.10 + *
    1.11 + * - Redistributions of source code must retain the above copyright
    1.12 + * notice, this list of conditions and the following disclaimer.
    1.13 + *
    1.14 + * - Redistributions in binary form must reproduce the above copyright
    1.15 + * notice, this list of conditions and the following disclaimer in the
    1.16 + * documentation and/or other materials provided with the distribution.
    1.17 + *
    1.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    1.19 + * contributors may be used to endorse or promote products derived from
    1.20 + * this software without specific prior written permission.
    1.21 + *
    1.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    1.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    1.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    1.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    1.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    1.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    1.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    1.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    1.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    1.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    1.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    1.33 + */
    1.34 +
    1.35 +#ifndef FLAC__STREAM_ENCODER_H
    1.36 +#define FLAC__STREAM_ENCODER_H
    1.37 +
    1.38 +#include <stdio.h> /* for FILE */
    1.39 +#include "export.h"
    1.40 +#include "format.h"
    1.41 +#include "stream_decoder.h"
    1.42 +
    1.43 +#ifdef __cplusplus
    1.44 +extern "C" {
    1.45 +#endif
    1.46 +
    1.47 +
    1.48 +/** \file include/FLAC/stream_encoder.h
    1.49 + *
    1.50 + *  \brief
    1.51 + *  This module contains the functions which implement the stream
    1.52 + *  encoder.
    1.53 + *
    1.54 + *  See the detailed documentation in the
    1.55 + *  \link flac_stream_encoder stream encoder \endlink module.
    1.56 + */
    1.57 +
    1.58 +/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
    1.59 + *  \ingroup flac
    1.60 + *
    1.61 + *  \brief
    1.62 + *  This module describes the encoder layers provided by libFLAC.
    1.63 + *
    1.64 + * The stream encoder can be used to encode complete streams either to the
    1.65 + * client via callbacks, or directly to a file, depending on how it is
    1.66 + * initialized.  When encoding via callbacks, the client provides a write
    1.67 + * callback which will be called whenever FLAC data is ready to be written.
    1.68 + * If the client also supplies a seek callback, the encoder will also
    1.69 + * automatically handle the writing back of metadata discovered while
    1.70 + * encoding, like stream info, seek points offsets, etc.  When encoding to
    1.71 + * a file, the client needs only supply a filename or open \c FILE* and an
    1.72 + * optional progress callback for periodic notification of progress; the
    1.73 + * write and seek callbacks are supplied internally.  For more info see the
    1.74 + * \link flac_stream_encoder stream encoder \endlink module.
    1.75 + */
    1.76 +
    1.77 +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
    1.78 + *  \ingroup flac_encoder
    1.79 + *
    1.80 + *  \brief
    1.81 + *  This module contains the functions which implement the stream
    1.82 + *  encoder.
    1.83 + *
    1.84 + * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
    1.85 + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
    1.86 + *
    1.87 + * The basic usage of this encoder is as follows:
    1.88 + * - The program creates an instance of an encoder using
    1.89 + *   FLAC__stream_encoder_new().
    1.90 + * - The program overrides the default settings using
    1.91 + *   FLAC__stream_encoder_set_*() functions.  At a minimum, the following
    1.92 + *   functions should be called:
    1.93 + *   - FLAC__stream_encoder_set_channels()
    1.94 + *   - FLAC__stream_encoder_set_bits_per_sample()
    1.95 + *   - FLAC__stream_encoder_set_sample_rate()
    1.96 + *   - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
    1.97 + *   - FLAC__stream_encoder_set_total_samples_estimate() (if known)
    1.98 + * - If the application wants to control the compression level or set its own
    1.99 + *   metadata, then the following should also be called:
   1.100 + *   - FLAC__stream_encoder_set_compression_level()
   1.101 + *   - FLAC__stream_encoder_set_verify()
   1.102 + *   - FLAC__stream_encoder_set_metadata()
   1.103 + * - The rest of the set functions should only be called if the client needs
   1.104 + *   exact control over how the audio is compressed; thorough understanding
   1.105 + *   of the FLAC format is necessary to achieve good results.
   1.106 + * - The program initializes the instance to validate the settings and
   1.107 + *   prepare for encoding using
   1.108 + *   - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
   1.109 + *     or FLAC__stream_encoder_init_file() for native FLAC
   1.110 + *   - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
   1.111 + *     or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
   1.112 + * - The program calls FLAC__stream_encoder_process() or
   1.113 + *   FLAC__stream_encoder_process_interleaved() to encode data, which
   1.114 + *   subsequently calls the callbacks when there is encoder data ready
   1.115 + *   to be written.
   1.116 + * - The program finishes the encoding with FLAC__stream_encoder_finish(),
   1.117 + *   which causes the encoder to encode any data still in its input pipe,
   1.118 + *   update the metadata with the final encoding statistics if output
   1.119 + *   seeking is possible, and finally reset the encoder to the
   1.120 + *   uninitialized state.
   1.121 + * - The instance may be used again or deleted with
   1.122 + *   FLAC__stream_encoder_delete().
   1.123 + *
   1.124 + * In more detail, the stream encoder functions similarly to the
   1.125 + * \link flac_stream_decoder stream decoder \endlink, but has fewer
   1.126 + * callbacks and more options.  Typically the client will create a new
   1.127 + * instance by calling FLAC__stream_encoder_new(), then set the necessary
   1.128 + * parameters with FLAC__stream_encoder_set_*(), and initialize it by
   1.129 + * calling one of the FLAC__stream_encoder_init_*() functions.
   1.130 + *
   1.131 + * Unlike the decoders, the stream encoder has many options that can
   1.132 + * affect the speed and compression ratio.  When setting these parameters
   1.133 + * you should have some basic knowledge of the format (see the
   1.134 + * <A HREF="../documentation.html#format">user-level documentation</A>
   1.135 + * or the <A HREF="../format.html">formal description</A>).  The
   1.136 + * FLAC__stream_encoder_set_*() functions themselves do not validate the
   1.137 + * values as many are interdependent.  The FLAC__stream_encoder_init_*()
   1.138 + * functions will do this, so make sure to pay attention to the state
   1.139 + * returned by FLAC__stream_encoder_init_*() to make sure that it is
   1.140 + * FLAC__STREAM_ENCODER_INIT_STATUS_OK.  Any parameters that are not set
   1.141 + * before FLAC__stream_encoder_init_*() will take on the defaults from
   1.142 + * the constructor.
   1.143 + *
   1.144 + * There are three initialization functions for native FLAC, one for
   1.145 + * setting up the encoder to encode FLAC data to the client via
   1.146 + * callbacks, and two for encoding directly to a file.
   1.147 + *
   1.148 + * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
   1.149 + * You must also supply a write callback which will be called anytime
   1.150 + * there is raw encoded data to write.  If the client can seek the output
   1.151 + * it is best to also supply seek and tell callbacks, as this allows the
   1.152 + * encoder to go back after encoding is finished to write back
   1.153 + * information that was collected while encoding, like seek point offsets,
   1.154 + * frame sizes, etc.
   1.155 + *
   1.156 + * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
   1.157 + * or FLAC__stream_encoder_init_file().  Then you must only supply a
   1.158 + * filename or open \c FILE*; the encoder will handle all the callbacks
   1.159 + * internally.  You may also supply a progress callback for periodic
   1.160 + * notification of the encoding progress.
   1.161 + *
   1.162 + * There are three similarly-named init functions for encoding to Ogg
   1.163 + * FLAC streams.  Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
   1.164 + * library has been built with Ogg support.
   1.165 + *
   1.166 + * The call to FLAC__stream_encoder_init_*() currently will also immediately
   1.167 + * call the write callback several times, once with the \c fLaC signature,
   1.168 + * and once for each encoded metadata block.  Note that for Ogg FLAC
   1.169 + * encoding you will usually get at least twice the number of callbacks than
   1.170 + * with native FLAC, one for the Ogg page header and one for the page body.
   1.171 + *
   1.172 + * After initializing the instance, the client may feed audio data to the
   1.173 + * encoder in one of two ways:
   1.174 + *
   1.175 + * - Channel separate, through FLAC__stream_encoder_process() - The client
   1.176 + *   will pass an array of pointers to buffers, one for each channel, to
   1.177 + *   the encoder, each of the same length.  The samples need not be
   1.178 + *   block-aligned, but each channel should have the same number of samples.
   1.179 + * - Channel interleaved, through
   1.180 + *   FLAC__stream_encoder_process_interleaved() - The client will pass a single
   1.181 + *   pointer to data that is channel-interleaved (i.e. channel0_sample0,
   1.182 + *   channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
   1.183 + *   Again, the samples need not be block-aligned but they must be
   1.184 + *   sample-aligned, i.e. the first value should be channel0_sample0 and
   1.185 + *   the last value channelN_sampleM.
   1.186 + *
   1.187 + * Note that for either process call, each sample in the buffers should be a
   1.188 + * signed integer, right-justified to the resolution set by
   1.189 + * FLAC__stream_encoder_set_bits_per_sample().  For example, if the resolution
   1.190 + * is 16 bits per sample, the samples should all be in the range [-32768,32767].
   1.191 + *
   1.192 + * When the client is finished encoding data, it calls
   1.193 + * FLAC__stream_encoder_finish(), which causes the encoder to encode any
   1.194 + * data still in its input pipe, and call the metadata callback with the
   1.195 + * final encoding statistics.  Then the instance may be deleted with
   1.196 + * FLAC__stream_encoder_delete() or initialized again to encode another
   1.197 + * stream.
   1.198 + *
   1.199 + * For programs that write their own metadata, but that do not know the
   1.200 + * actual metadata until after encoding, it is advantageous to instruct
   1.201 + * the encoder to write a PADDING block of the correct size, so that
   1.202 + * instead of rewriting the whole stream after encoding, the program can
   1.203 + * just overwrite the PADDING block.  If only the maximum size of the
   1.204 + * metadata is known, the program can write a slightly larger padding
   1.205 + * block, then split it after encoding.
   1.206 + *
   1.207 + * Make sure you understand how lengths are calculated.  All FLAC metadata
   1.208 + * blocks have a 4 byte header which contains the type and length.  This
   1.209 + * length does not include the 4 bytes of the header.  See the format page
   1.210 + * for the specification of metadata blocks and their lengths.
   1.211 + *
   1.212 + * \note
   1.213 + * If you are writing the FLAC data to a file via callbacks, make sure it
   1.214 + * is open for update (e.g. mode "w+" for stdio streams).  This is because
   1.215 + * after the first encoding pass, the encoder will try to seek back to the
   1.216 + * beginning of the stream, to the STREAMINFO block, to write some data
   1.217 + * there.  (If using FLAC__stream_encoder_init*_file() or
   1.218 + * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
   1.219 + *
   1.220 + * \note
   1.221 + * The "set" functions may only be called when the encoder is in the
   1.222 + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
   1.223 + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
   1.224 + * before FLAC__stream_encoder_init_*().  If this is the case they will
   1.225 + * return \c true, otherwise \c false.
   1.226 + *
   1.227 + * \note
   1.228 + * FLAC__stream_encoder_finish() resets all settings to the constructor
   1.229 + * defaults.
   1.230 + *
   1.231 + * \{
   1.232 + */
   1.233 +
   1.234 +
   1.235 +/** State values for a FLAC__StreamEncoder.
   1.236 + *
   1.237 + * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
   1.238 + *
   1.239 + * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
   1.240 + * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
   1.241 + * must be deleted with FLAC__stream_encoder_delete().
   1.242 + */
   1.243 +typedef enum {
   1.244 +
   1.245 +	FLAC__STREAM_ENCODER_OK = 0,
   1.246 +	/**< The encoder is in the normal OK state and samples can be processed. */
   1.247 +
   1.248 +	FLAC__STREAM_ENCODER_UNINITIALIZED,
   1.249 +	/**< The encoder is in the uninitialized state; one of the
   1.250 +	 * FLAC__stream_encoder_init_*() functions must be called before samples
   1.251 +	 * can be processed.
   1.252 +	 */
   1.253 +
   1.254 +	FLAC__STREAM_ENCODER_OGG_ERROR,
   1.255 +	/**< An error occurred in the underlying Ogg layer.  */
   1.256 +
   1.257 +	FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
   1.258 +	/**< An error occurred in the underlying verify stream decoder;
   1.259 +	 * check FLAC__stream_encoder_get_verify_decoder_state().
   1.260 +	 */
   1.261 +
   1.262 +	FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
   1.263 +	/**< The verify decoder detected a mismatch between the original
   1.264 +	 * audio signal and the decoded audio signal.
   1.265 +	 */
   1.266 +
   1.267 +	FLAC__STREAM_ENCODER_CLIENT_ERROR,
   1.268 +	/**< One of the callbacks returned a fatal error. */
   1.269 +
   1.270 +	FLAC__STREAM_ENCODER_IO_ERROR,
   1.271 +	/**< An I/O error occurred while opening/reading/writing a file.
   1.272 +	 * Check \c errno.
   1.273 +	 */
   1.274 +
   1.275 +	FLAC__STREAM_ENCODER_FRAMING_ERROR,
   1.276 +	/**< An error occurred while writing the stream; usually, the
   1.277 +	 * write_callback returned an error.
   1.278 +	 */
   1.279 +
   1.280 +	FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
   1.281 +	/**< Memory allocation failed. */
   1.282 +
   1.283 +} FLAC__StreamEncoderState;
   1.284 +
   1.285 +/** Maps a FLAC__StreamEncoderState to a C string.
   1.286 + *
   1.287 + *  Using a FLAC__StreamEncoderState as the index to this array
   1.288 + *  will give the string equivalent.  The contents should not be modified.
   1.289 + */
   1.290 +extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
   1.291 +
   1.292 +
   1.293 +/** Possible return values for the FLAC__stream_encoder_init_*() functions.
   1.294 + */
   1.295 +typedef enum {
   1.296 +
   1.297 +	FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
   1.298 +	/**< Initialization was successful. */
   1.299 +
   1.300 +	FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
   1.301 +	/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
   1.302 +
   1.303 +	FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
   1.304 +	/**< The library was not compiled with support for the given container
   1.305 +	 * format.
   1.306 +	 */
   1.307 +
   1.308 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
   1.309 +	/**< A required callback was not supplied. */
   1.310 +
   1.311 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
   1.312 +	/**< The encoder has an invalid setting for number of channels. */
   1.313 +
   1.314 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
   1.315 +	/**< The encoder has an invalid setting for bits-per-sample.
   1.316 +	 * FLAC supports 4-32 bps but the reference encoder currently supports
   1.317 +	 * only up to 24 bps.
   1.318 +	 */
   1.319 +
   1.320 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
   1.321 +	/**< The encoder has an invalid setting for the input sample rate. */
   1.322 +
   1.323 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
   1.324 +	/**< The encoder has an invalid setting for the block size. */
   1.325 +
   1.326 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
   1.327 +	/**< The encoder has an invalid setting for the maximum LPC order. */
   1.328 +
   1.329 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
   1.330 +	/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
   1.331 +
   1.332 +	FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
   1.333 +	/**< The specified block size is less than the maximum LPC order. */
   1.334 +
   1.335 +	FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
   1.336 +	/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
   1.337 +
   1.338 +	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
   1.339 +	/**< The metadata input to the encoder is invalid, in one of the following ways:
   1.340 +	 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
   1.341 +	 * - One of the metadata blocks contains an undefined type
   1.342 +	 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
   1.343 +	 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
   1.344 +	 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
   1.345 +	 */
   1.346 +
   1.347 +	FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
   1.348 +	/**< FLAC__stream_encoder_init_*() was called when the encoder was
   1.349 +	 * already initialized, usually because
   1.350 +	 * FLAC__stream_encoder_finish() was not called.
   1.351 +	 */
   1.352 +
   1.353 +} FLAC__StreamEncoderInitStatus;
   1.354 +
   1.355 +/** Maps a FLAC__StreamEncoderInitStatus to a C string.
   1.356 + *
   1.357 + *  Using a FLAC__StreamEncoderInitStatus as the index to this array
   1.358 + *  will give the string equivalent.  The contents should not be modified.
   1.359 + */
   1.360 +extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
   1.361 +
   1.362 +
   1.363 +/** Return values for the FLAC__StreamEncoder read callback.
   1.364 + */
   1.365 +typedef enum {
   1.366 +
   1.367 +	FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
   1.368 +	/**< The read was OK and decoding can continue. */
   1.369 +
   1.370 +	FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
   1.371 +	/**< The read was attempted at the end of the stream. */
   1.372 +
   1.373 +	FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
   1.374 +	/**< An unrecoverable error occurred. */
   1.375 +
   1.376 +	FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
   1.377 +	/**< Client does not support reading back from the output. */
   1.378 +
   1.379 +} FLAC__StreamEncoderReadStatus;
   1.380 +
   1.381 +/** Maps a FLAC__StreamEncoderReadStatus to a C string.
   1.382 + *
   1.383 + *  Using a FLAC__StreamEncoderReadStatus as the index to this array
   1.384 + *  will give the string equivalent.  The contents should not be modified.
   1.385 + */
   1.386 +extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
   1.387 +
   1.388 +
   1.389 +/** Return values for the FLAC__StreamEncoder write callback.
   1.390 + */
   1.391 +typedef enum {
   1.392 +
   1.393 +	FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
   1.394 +	/**< The write was OK and encoding can continue. */
   1.395 +
   1.396 +	FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
   1.397 +	/**< An unrecoverable error occurred.  The encoder will return from the process call. */
   1.398 +
   1.399 +} FLAC__StreamEncoderWriteStatus;
   1.400 +
   1.401 +/** Maps a FLAC__StreamEncoderWriteStatus to a C string.
   1.402 + *
   1.403 + *  Using a FLAC__StreamEncoderWriteStatus as the index to this array
   1.404 + *  will give the string equivalent.  The contents should not be modified.
   1.405 + */
   1.406 +extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
   1.407 +
   1.408 +
   1.409 +/** Return values for the FLAC__StreamEncoder seek callback.
   1.410 + */
   1.411 +typedef enum {
   1.412 +
   1.413 +	FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
   1.414 +	/**< The seek was OK and encoding can continue. */
   1.415 +
   1.416 +	FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
   1.417 +	/**< An unrecoverable error occurred. */
   1.418 +
   1.419 +	FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
   1.420 +	/**< Client does not support seeking. */
   1.421 +
   1.422 +} FLAC__StreamEncoderSeekStatus;
   1.423 +
   1.424 +/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
   1.425 + *
   1.426 + *  Using a FLAC__StreamEncoderSeekStatus as the index to this array
   1.427 + *  will give the string equivalent.  The contents should not be modified.
   1.428 + */
   1.429 +extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
   1.430 +
   1.431 +
   1.432 +/** Return values for the FLAC__StreamEncoder tell callback.
   1.433 + */
   1.434 +typedef enum {
   1.435 +
   1.436 +	FLAC__STREAM_ENCODER_TELL_STATUS_OK,
   1.437 +	/**< The tell was OK and encoding can continue. */
   1.438 +
   1.439 +	FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
   1.440 +	/**< An unrecoverable error occurred. */
   1.441 +
   1.442 +	FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
   1.443 +	/**< Client does not support seeking. */
   1.444 +
   1.445 +} FLAC__StreamEncoderTellStatus;
   1.446 +
   1.447 +/** Maps a FLAC__StreamEncoderTellStatus to a C string.
   1.448 + *
   1.449 + *  Using a FLAC__StreamEncoderTellStatus as the index to this array
   1.450 + *  will give the string equivalent.  The contents should not be modified.
   1.451 + */
   1.452 +extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
   1.453 +
   1.454 +
   1.455 +/***********************************************************************
   1.456 + *
   1.457 + * class FLAC__StreamEncoder
   1.458 + *
   1.459 + ***********************************************************************/
   1.460 +
   1.461 +struct FLAC__StreamEncoderProtected;
   1.462 +struct FLAC__StreamEncoderPrivate;
   1.463 +/** The opaque structure definition for the stream encoder type.
   1.464 + *  See the \link flac_stream_encoder stream encoder module \endlink
   1.465 + *  for a detailed description.
   1.466 + */
   1.467 +typedef struct {
   1.468 +	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
   1.469 +	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
   1.470 +} FLAC__StreamEncoder;
   1.471 +
   1.472 +/** Signature for the read callback.
   1.473 + *
   1.474 + *  A function pointer matching this signature must be passed to
   1.475 + *  FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
   1.476 + *  The supplied function will be called when the encoder needs to read back
   1.477 + *  encoded data.  This happens during the metadata callback, when the encoder
   1.478 + *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
   1.479 + *  while encoding.  The address of the buffer to be filled is supplied, along
   1.480 + *  with the number of bytes the buffer can hold.  The callback may choose to
   1.481 + *  supply less data and modify the byte count but must be careful not to
   1.482 + *  overflow the buffer.  The callback then returns a status code chosen from
   1.483 + *  FLAC__StreamEncoderReadStatus.
   1.484 + *
   1.485 + * Here is an example of a read callback for stdio streams:
   1.486 + * \code
   1.487 + * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
   1.488 + * {
   1.489 + *   FILE *file = ((MyClientData*)client_data)->file;
   1.490 + *   if(*bytes > 0) {
   1.491 + *     *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
   1.492 + *     if(ferror(file))
   1.493 + *       return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
   1.494 + *     else if(*bytes == 0)
   1.495 + *       return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
   1.496 + *     else
   1.497 + *       return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
   1.498 + *   }
   1.499 + *   else
   1.500 + *     return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
   1.501 + * }
   1.502 + * \endcode
   1.503 + *
   1.504 + * \note In general, FLAC__StreamEncoder functions which change the
   1.505 + * state should not be called on the \a encoder while in the callback.
   1.506 + *
   1.507 + * \param  encoder  The encoder instance calling the callback.
   1.508 + * \param  buffer   A pointer to a location for the callee to store
   1.509 + *                  data to be encoded.
   1.510 + * \param  bytes    A pointer to the size of the buffer.  On entry
   1.511 + *                  to the callback, it contains the maximum number
   1.512 + *                  of bytes that may be stored in \a buffer.  The
   1.513 + *                  callee must set it to the actual number of bytes
   1.514 + *                  stored (0 in case of error or end-of-stream) before
   1.515 + *                  returning.
   1.516 + * \param  client_data  The callee's client data set through
   1.517 + *                      FLAC__stream_encoder_set_client_data().
   1.518 + * \retval FLAC__StreamEncoderReadStatus
   1.519 + *    The callee's return status.
   1.520 + */
   1.521 +typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
   1.522 +
   1.523 +/** Signature for the write callback.
   1.524 + *
   1.525 + *  A function pointer matching this signature must be passed to
   1.526 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
   1.527 + *  by the encoder anytime there is raw encoded data ready to write.  It may
   1.528 + *  include metadata mixed with encoded audio frames and the data is not
   1.529 + *  guaranteed to be aligned on frame or metadata block boundaries.
   1.530 + *
   1.531 + *  The only duty of the callback is to write out the \a bytes worth of data
   1.532 + *  in \a buffer to the current position in the output stream.  The arguments
   1.533 + *  \a samples and \a current_frame are purely informational.  If \a samples
   1.534 + *  is greater than \c 0, then \a current_frame will hold the current frame
   1.535 + *  number that is being written; otherwise it indicates that the write
   1.536 + *  callback is being called to write metadata.
   1.537 + *
   1.538 + * \note
   1.539 + * Unlike when writing to native FLAC, when writing to Ogg FLAC the
   1.540 + * write callback will be called twice when writing each audio
   1.541 + * frame; once for the page header, and once for the page body.
   1.542 + * When writing the page header, the \a samples argument to the
   1.543 + * write callback will be \c 0.
   1.544 + *
   1.545 + * \note In general, FLAC__StreamEncoder functions which change the
   1.546 + * state should not be called on the \a encoder while in the callback.
   1.547 + *
   1.548 + * \param  encoder  The encoder instance calling the callback.
   1.549 + * \param  buffer   An array of encoded data of length \a bytes.
   1.550 + * \param  bytes    The byte length of \a buffer.
   1.551 + * \param  samples  The number of samples encoded by \a buffer.
   1.552 + *                  \c 0 has a special meaning; see above.
   1.553 + * \param  current_frame  The number of the current frame being encoded.
   1.554 + * \param  client_data  The callee's client data set through
   1.555 + *                      FLAC__stream_encoder_init_*().
   1.556 + * \retval FLAC__StreamEncoderWriteStatus
   1.557 + *    The callee's return status.
   1.558 + */
   1.559 +typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data);
   1.560 +
   1.561 +/** Signature for the seek callback.
   1.562 + *
   1.563 + *  A function pointer matching this signature may be passed to
   1.564 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
   1.565 + *  when the encoder needs to seek the output stream.  The encoder will pass
   1.566 + *  the absolute byte offset to seek to, 0 meaning the beginning of the stream.
   1.567 + *
   1.568 + * Here is an example of a seek callback for stdio streams:
   1.569 + * \code
   1.570 + * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
   1.571 + * {
   1.572 + *   FILE *file = ((MyClientData*)client_data)->file;
   1.573 + *   if(file == stdin)
   1.574 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
   1.575 + *   else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
   1.576 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
   1.577 + *   else
   1.578 + *     return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
   1.579 + * }
   1.580 + * \endcode
   1.581 + *
   1.582 + * \note In general, FLAC__StreamEncoder functions which change the
   1.583 + * state should not be called on the \a encoder while in the callback.
   1.584 + *
   1.585 + * \param  encoder  The encoder instance calling the callback.
   1.586 + * \param  absolute_byte_offset  The offset from the beginning of the stream
   1.587 + *                               to seek to.
   1.588 + * \param  client_data  The callee's client data set through
   1.589 + *                      FLAC__stream_encoder_init_*().
   1.590 + * \retval FLAC__StreamEncoderSeekStatus
   1.591 + *    The callee's return status.
   1.592 + */
   1.593 +typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
   1.594 +
   1.595 +/** Signature for the tell callback.
   1.596 + *
   1.597 + *  A function pointer matching this signature may be passed to
   1.598 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
   1.599 + *  when the encoder needs to know the current position of the output stream.
   1.600 + *
   1.601 + * \warning
   1.602 + * The callback must return the true current byte offset of the output to
   1.603 + * which the encoder is writing.  If you are buffering the output, make
   1.604 + * sure and take this into account.  If you are writing directly to a
   1.605 + * FILE* from your write callback, ftell() is sufficient.  If you are
   1.606 + * writing directly to a file descriptor from your write callback, you
   1.607 + * can use lseek(fd, SEEK_CUR, 0).  The encoder may later seek back to
   1.608 + * these points to rewrite metadata after encoding.
   1.609 + *
   1.610 + * Here is an example of a tell callback for stdio streams:
   1.611 + * \code
   1.612 + * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
   1.613 + * {
   1.614 + *   FILE *file = ((MyClientData*)client_data)->file;
   1.615 + *   off_t pos;
   1.616 + *   if(file == stdin)
   1.617 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
   1.618 + *   else if((pos = ftello(file)) < 0)
   1.619 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
   1.620 + *   else {
   1.621 + *     *absolute_byte_offset = (FLAC__uint64)pos;
   1.622 + *     return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
   1.623 + *   }
   1.624 + * }
   1.625 + * \endcode
   1.626 + *
   1.627 + * \note In general, FLAC__StreamEncoder functions which change the
   1.628 + * state should not be called on the \a encoder while in the callback.
   1.629 + *
   1.630 + * \param  encoder  The encoder instance calling the callback.
   1.631 + * \param  absolute_byte_offset  The address at which to store the current
   1.632 + *                               position of the output.
   1.633 + * \param  client_data  The callee's client data set through
   1.634 + *                      FLAC__stream_encoder_init_*().
   1.635 + * \retval FLAC__StreamEncoderTellStatus
   1.636 + *    The callee's return status.
   1.637 + */
   1.638 +typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
   1.639 +
   1.640 +/** Signature for the metadata callback.
   1.641 + *
   1.642 + *  A function pointer matching this signature may be passed to
   1.643 + *  FLAC__stream_encoder_init*_stream().  The supplied function will be called
   1.644 + *  once at the end of encoding with the populated STREAMINFO structure.  This
   1.645 + *  is so the client can seek back to the beginning of the file and write the
   1.646 + *  STREAMINFO block with the correct statistics after encoding (like
   1.647 + *  minimum/maximum frame size and total samples).
   1.648 + *
   1.649 + * \note In general, FLAC__StreamEncoder functions which change the
   1.650 + * state should not be called on the \a encoder while in the callback.
   1.651 + *
   1.652 + * \param  encoder      The encoder instance calling the callback.
   1.653 + * \param  metadata     The final populated STREAMINFO block.
   1.654 + * \param  client_data  The callee's client data set through
   1.655 + *                      FLAC__stream_encoder_init_*().
   1.656 + */
   1.657 +typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
   1.658 +
   1.659 +/** Signature for the progress callback.
   1.660 + *
   1.661 + *  A function pointer matching this signature may be passed to
   1.662 + *  FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
   1.663 + *  The supplied function will be called when the encoder has finished
   1.664 + *  writing a frame.  The \c total_frames_estimate argument to the
   1.665 + *  callback will be based on the value from
   1.666 + *  FLAC__stream_encoder_set_total_samples_estimate().
   1.667 + *
   1.668 + * \note In general, FLAC__StreamEncoder functions which change the
   1.669 + * state should not be called on the \a encoder while in the callback.
   1.670 + *
   1.671 + * \param  encoder          The encoder instance calling the callback.
   1.672 + * \param  bytes_written    Bytes written so far.
   1.673 + * \param  samples_written  Samples written so far.
   1.674 + * \param  frames_written   Frames written so far.
   1.675 + * \param  total_frames_estimate  The estimate of the total number of
   1.676 + *                                frames to be written.
   1.677 + * \param  client_data      The callee's client data set through
   1.678 + *                          FLAC__stream_encoder_init_*().
   1.679 + */
   1.680 +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);
   1.681 +
   1.682 +
   1.683 +/***********************************************************************
   1.684 + *
   1.685 + * Class constructor/destructor
   1.686 + *
   1.687 + ***********************************************************************/
   1.688 +
   1.689 +/** Create a new stream encoder instance.  The instance is created with
   1.690 + *  default settings; see the individual FLAC__stream_encoder_set_*()
   1.691 + *  functions for each setting's default.
   1.692 + *
   1.693 + * \retval FLAC__StreamEncoder*
   1.694 + *    \c NULL if there was an error allocating memory, else the new instance.
   1.695 + */
   1.696 +FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
   1.697 +
   1.698 +/** Free an encoder instance.  Deletes the object pointed to by \a encoder.
   1.699 + *
   1.700 + * \param encoder  A pointer to an existing encoder.
   1.701 + * \assert
   1.702 + *    \code encoder != NULL \endcode
   1.703 + */
   1.704 +FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
   1.705 +
   1.706 +
   1.707 +/***********************************************************************
   1.708 + *
   1.709 + * Public class method prototypes
   1.710 + *
   1.711 + ***********************************************************************/
   1.712 +
   1.713 +/** Set the serial number for the FLAC stream to use in the Ogg container.
   1.714 + *
   1.715 + * \note
   1.716 + * This does not need to be set for native FLAC encoding.
   1.717 + *
   1.718 + * \note
   1.719 + * It is recommended to set a serial number explicitly as the default of '0'
   1.720 + * may collide with other streams.
   1.721 + *
   1.722 + * \default \c 0
   1.723 + * \param  encoder        An encoder instance to set.
   1.724 + * \param  serial_number  See above.
   1.725 + * \assert
   1.726 + *    \code encoder != NULL \endcode
   1.727 + * \retval FLAC__bool
   1.728 + *    \c false if the encoder is already initialized, else \c true.
   1.729 + */
   1.730 +FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
   1.731 +
   1.732 +/** Set the "verify" flag.  If \c true, the encoder will verify it's own
   1.733 + *  encoded output by feeding it through an internal decoder and comparing
   1.734 + *  the original signal against the decoded signal.  If a mismatch occurs,
   1.735 + *  the process call will return \c false.  Note that this will slow the
   1.736 + *  encoding process by the extra time required for decoding and comparison.
   1.737 + *
   1.738 + * \default \c false
   1.739 + * \param  encoder  An encoder instance to set.
   1.740 + * \param  value    Flag value (see above).
   1.741 + * \assert
   1.742 + *    \code encoder != NULL \endcode
   1.743 + * \retval FLAC__bool
   1.744 + *    \c false if the encoder is already initialized, else \c true.
   1.745 + */
   1.746 +FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1.747 +
   1.748 +/** Set the <A HREF="../format.html#subset">Subset</A> flag.  If \c true,
   1.749 + *  the encoder will comply with the Subset and will check the
   1.750 + *  settings during FLAC__stream_encoder_init_*() to see if all settings
   1.751 + *  comply.  If \c false, the settings may take advantage of the full
   1.752 + *  range that the format allows.
   1.753 + *
   1.754 + *  Make sure you know what it entails before setting this to \c false.
   1.755 + *
   1.756 + * \default \c true
   1.757 + * \param  encoder  An encoder instance to set.
   1.758 + * \param  value    Flag value (see above).
   1.759 + * \assert
   1.760 + *    \code encoder != NULL \endcode
   1.761 + * \retval FLAC__bool
   1.762 + *    \c false if the encoder is already initialized, else \c true.
   1.763 + */
   1.764 +FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1.765 +
   1.766 +/** Set the number of channels to be encoded.
   1.767 + *
   1.768 + * \default \c 2
   1.769 + * \param  encoder  An encoder instance to set.
   1.770 + * \param  value    See above.
   1.771 + * \assert
   1.772 + *    \code encoder != NULL \endcode
   1.773 + * \retval FLAC__bool
   1.774 + *    \c false if the encoder is already initialized, else \c true.
   1.775 + */
   1.776 +FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
   1.777 +
   1.778 +/** Set the sample resolution of the input to be encoded.
   1.779 + *
   1.780 + * \warning
   1.781 + * Do not feed the encoder data that is wider than the value you
   1.782 + * set here or you will generate an invalid stream.
   1.783 + *
   1.784 + * \default \c 16
   1.785 + * \param  encoder  An encoder instance to set.
   1.786 + * \param  value    See above.
   1.787 + * \assert
   1.788 + *    \code encoder != NULL \endcode
   1.789 + * \retval FLAC__bool
   1.790 + *    \c false if the encoder is already initialized, else \c true.
   1.791 + */
   1.792 +FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
   1.793 +
   1.794 +/** Set the sample rate (in Hz) of the input to be encoded.
   1.795 + *
   1.796 + * \default \c 44100
   1.797 + * \param  encoder  An encoder instance to set.
   1.798 + * \param  value    See above.
   1.799 + * \assert
   1.800 + *    \code encoder != NULL \endcode
   1.801 + * \retval FLAC__bool
   1.802 + *    \c false if the encoder is already initialized, else \c true.
   1.803 + */
   1.804 +FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
   1.805 +
   1.806 +/** Set the compression level
   1.807 + *
   1.808 + * The compression level is roughly proportional to the amount of effort
   1.809 + * the encoder expends to compress the file.  A higher level usually
   1.810 + * means more computation but higher compression.  The default level is
   1.811 + * suitable for most applications.
   1.812 + *
   1.813 + * Currently the levels range from \c 0 (fastest, least compression) to
   1.814 + * \c 8 (slowest, most compression).  A value larger than \c 8 will be
   1.815 + * treated as \c 8.
   1.816 + *
   1.817 + * This function automatically calls the following other \c _set_
   1.818 + * functions with appropriate values, so the client does not need to
   1.819 + * unless it specifically wants to override them:
   1.820 + * - FLAC__stream_encoder_set_do_mid_side_stereo()
   1.821 + * - FLAC__stream_encoder_set_loose_mid_side_stereo()
   1.822 + * - FLAC__stream_encoder_set_apodization()
   1.823 + * - FLAC__stream_encoder_set_max_lpc_order()
   1.824 + * - FLAC__stream_encoder_set_qlp_coeff_precision()
   1.825 + * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
   1.826 + * - FLAC__stream_encoder_set_do_escape_coding()
   1.827 + * - FLAC__stream_encoder_set_do_exhaustive_model_search()
   1.828 + * - FLAC__stream_encoder_set_min_residual_partition_order()
   1.829 + * - FLAC__stream_encoder_set_max_residual_partition_order()
   1.830 + * - FLAC__stream_encoder_set_rice_parameter_search_dist()
   1.831 + *
   1.832 + * The actual values set for each level are:
   1.833 + * <table>
   1.834 + * <tr>
   1.835 + *  <td><b>level</b><td>
   1.836 + *  <td>do mid-side stereo<td>
   1.837 + *  <td>loose mid-side stereo<td>
   1.838 + *  <td>apodization<td>
   1.839 + *  <td>max lpc order<td>
   1.840 + *  <td>qlp coeff precision<td>
   1.841 + *  <td>qlp coeff prec search<td>
   1.842 + *  <td>escape coding<td>
   1.843 + *  <td>exhaustive model search<td>
   1.844 + *  <td>min residual partition order<td>
   1.845 + *  <td>max residual partition order<td>
   1.846 + *  <td>rice parameter search dist<td>
   1.847 + * </tr>
   1.848 + * <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>
   1.849 + * <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>
   1.850 + * <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>
   1.851 + * <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>
   1.852 + * <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>
   1.853 + * <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>
   1.854 + * <tr>  <td><b>6</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>6<td>  <td>0<td>  </tr>
   1.855 + * <tr>  <td><b>7</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>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
   1.856 + * <tr>  <td><b>8</b><td>  <td>true<td>   <td>false<td>  <td>tukey(0.5)<td>  <td>12<td>  <td>0<td>  <td>false<td>  <td>false<td>  <td>true<td>   <td>0<td>  <td>6<td>  <td>0<td>  </tr>
   1.857 + * </table>
   1.858 + *
   1.859 + * \default \c 5
   1.860 + * \param  encoder  An encoder instance to set.
   1.861 + * \param  value    See above.
   1.862 + * \assert
   1.863 + *    \code encoder != NULL \endcode
   1.864 + * \retval FLAC__bool
   1.865 + *    \c false if the encoder is already initialized, else \c true.
   1.866 + */
   1.867 +FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
   1.868 +
   1.869 +/** Set the blocksize to use while encoding.
   1.870 + *
   1.871 + * The number of samples to use per frame.  Use \c 0 to let the encoder
   1.872 + * estimate a blocksize; this is usually best.
   1.873 + *
   1.874 + * \default \c 0
   1.875 + * \param  encoder  An encoder instance to set.
   1.876 + * \param  value    See above.
   1.877 + * \assert
   1.878 + *    \code encoder != NULL \endcode
   1.879 + * \retval FLAC__bool
   1.880 + *    \c false if the encoder is already initialized, else \c true.
   1.881 + */
   1.882 +FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
   1.883 +
   1.884 +/** Set to \c true to enable mid-side encoding on stereo input.  The
   1.885 + *  number of channels must be 2 for this to have any effect.  Set to
   1.886 + *  \c false to use only independent channel coding.
   1.887 + *
   1.888 + * \default \c false
   1.889 + * \param  encoder  An encoder instance to set.
   1.890 + * \param  value    Flag value (see above).
   1.891 + * \assert
   1.892 + *    \code encoder != NULL \endcode
   1.893 + * \retval FLAC__bool
   1.894 + *    \c false if the encoder is already initialized, else \c true.
   1.895 + */
   1.896 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1.897 +
   1.898 +/** Set to \c true to enable adaptive switching between mid-side and
   1.899 + *  left-right encoding on stereo input.  Set to \c false to use
   1.900 + *  exhaustive searching.  Setting this to \c true requires
   1.901 + *  FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
   1.902 + *  \c true in order to have any effect.
   1.903 + *
   1.904 + * \default \c false
   1.905 + * \param  encoder  An encoder instance to set.
   1.906 + * \param  value    Flag value (see above).
   1.907 + * \assert
   1.908 + *    \code encoder != NULL \endcode
   1.909 + * \retval FLAC__bool
   1.910 + *    \c false if the encoder is already initialized, else \c true.
   1.911 + */
   1.912 +FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
   1.913 +
   1.914 +/** Sets the apodization function(s) the encoder will use when windowing
   1.915 + *  audio data for LPC analysis.
   1.916 + *
   1.917 + * The \a specification is a plain ASCII string which specifies exactly
   1.918 + * which functions to use.  There may be more than one (up to 32),
   1.919 + * separated by \c ';' characters.  Some functions take one or more
   1.920 + * comma-separated arguments in parentheses.
   1.921 + *
   1.922 + * The available functions are \c bartlett, \c bartlett_hann,
   1.923 + * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
   1.924 + * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
   1.925 + * \c rectangle, \c triangle, \c tukey(P), \c welch.
   1.926 + *
   1.927 + * For \c gauss(STDDEV), STDDEV specifies the standard deviation
   1.928 + * (0<STDDEV<=0.5).
   1.929 + *
   1.930 + * For \c tukey(P), P specifies the fraction of the window that is
   1.931 + * tapered (0<=P<=1).  P=0 corresponds to \c rectangle and P=1
   1.932 + * corresponds to \c hann.
   1.933 + *
   1.934 + * Example specifications are \c "blackman" or
   1.935 + * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
   1.936 + *
   1.937 + * Any function that is specified erroneously is silently dropped.  Up
   1.938 + * to 32 functions are kept, the rest are dropped.  If the specification
   1.939 + * is empty the encoder defaults to \c "tukey(0.5)".
   1.940 + *
   1.941 + * When more than one function is specified, then for every subframe the
   1.942 + * encoder will try each of them separately and choose the window that
   1.943 + * results in the smallest compressed subframe.
   1.944 + *
   1.945 + * Note that each function specified causes the encoder to occupy a
   1.946 + * floating point array in which to store the window.
   1.947 + *
   1.948 + * \default \c "tukey(0.5)"
   1.949 + * \param  encoder        An encoder instance to set.
   1.950 + * \param  specification  See above.
   1.951 + * \assert
   1.952 + *    \code encoder != NULL \endcode
   1.953 + *    \code specification != NULL \endcode
   1.954 + * \retval FLAC__bool
   1.955 + *    \c false if the encoder is already initialized, else \c true.
   1.956 + */
   1.957 +FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
   1.958 +
   1.959 +/** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
   1.960 + *
   1.961 + * \default \c 0
   1.962 + * \param  encoder  An encoder instance to set.
   1.963 + * \param  value    See above.
   1.964 + * \assert
   1.965 + *    \code encoder != NULL \endcode
   1.966 + * \retval FLAC__bool
   1.967 + *    \c false if the encoder is already initialized, else \c true.
   1.968 + */
   1.969 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
   1.970 +
   1.971 +/** Set the precision, in bits, of the quantized linear predictor
   1.972 + *  coefficients, or \c 0 to let the encoder select it based on the
   1.973 + *  blocksize.
   1.974 + *
   1.975 + * \note
   1.976 + * In the current implementation, qlp_coeff_precision + bits_per_sample must
   1.977 + * be less than 32.
   1.978 + *
   1.979 + * \default \c 0
   1.980 + * \param  encoder  An encoder instance to set.
   1.981 + * \param  value    See above.
   1.982 + * \assert
   1.983 + *    \code encoder != NULL \endcode
   1.984 + * \retval FLAC__bool
   1.985 + *    \c false if the encoder is already initialized, else \c true.
   1.986 + */
   1.987 +FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
   1.988 +
   1.989 +/** Set to \c false to use only the specified quantized linear predictor
   1.990 + *  coefficient precision, or \c true to search neighboring precision
   1.991 + *  values and use the best one.
   1.992 + *
   1.993 + * \default \c false
   1.994 + * \param  encoder  An encoder instance to set.
   1.995 + * \param  value    See above.
   1.996 + * \assert
   1.997 + *    \code encoder != NULL \endcode
   1.998 + * \retval FLAC__bool
   1.999 + *    \c false if the encoder is already initialized, else \c true.
  1.1000 + */
  1.1001 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
  1.1002 +
  1.1003 +/** Deprecated.  Setting this value has no effect.
  1.1004 + *
  1.1005 + * \default \c false
  1.1006 + * \param  encoder  An encoder instance to set.
  1.1007 + * \param  value    See above.
  1.1008 + * \assert
  1.1009 + *    \code encoder != NULL \endcode
  1.1010 + * \retval FLAC__bool
  1.1011 + *    \c false if the encoder is already initialized, else \c true.
  1.1012 + */
  1.1013 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
  1.1014 +
  1.1015 +/** Set to \c false to let the encoder estimate the best model order
  1.1016 + *  based on the residual signal energy, or \c true to force the
  1.1017 + *  encoder to evaluate all order models and select the best.
  1.1018 + *
  1.1019 + * \default \c false
  1.1020 + * \param  encoder  An encoder instance to set.
  1.1021 + * \param  value    See above.
  1.1022 + * \assert
  1.1023 + *    \code encoder != NULL \endcode
  1.1024 + * \retval FLAC__bool
  1.1025 + *    \c false if the encoder is already initialized, else \c true.
  1.1026 + */
  1.1027 +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
  1.1028 +
  1.1029 +/** Set the minimum partition order to search when coding the residual.
  1.1030 + *  This is used in tandem with
  1.1031 + *  FLAC__stream_encoder_set_max_residual_partition_order().
  1.1032 + *
  1.1033 + *  The partition order determines the context size in the residual.
  1.1034 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
  1.1035 + *
  1.1036 + *  Set both min and max values to \c 0 to force a single context,
  1.1037 + *  whose Rice parameter is based on the residual signal variance.
  1.1038 + *  Otherwise, set a min and max order, and the encoder will search
  1.1039 + *  all orders, using the mean of each context for its Rice parameter,
  1.1040 + *  and use the best.
  1.1041 + *
  1.1042 + * \default \c 0
  1.1043 + * \param  encoder  An encoder instance to set.
  1.1044 + * \param  value    See above.
  1.1045 + * \assert
  1.1046 + *    \code encoder != NULL \endcode
  1.1047 + * \retval FLAC__bool
  1.1048 + *    \c false if the encoder is already initialized, else \c true.
  1.1049 + */
  1.1050 +FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
  1.1051 +
  1.1052 +/** Set the maximum partition order to search when coding the residual.
  1.1053 + *  This is used in tandem with
  1.1054 + *  FLAC__stream_encoder_set_min_residual_partition_order().
  1.1055 + *
  1.1056 + *  The partition order determines the context size in the residual.
  1.1057 + *  The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
  1.1058 + *
  1.1059 + *  Set both min and max values to \c 0 to force a single context,
  1.1060 + *  whose Rice parameter is based on the residual signal variance.
  1.1061 + *  Otherwise, set a min and max order, and the encoder will search
  1.1062 + *  all orders, using the mean of each context for its Rice parameter,
  1.1063 + *  and use the best.
  1.1064 + *
  1.1065 + * \default \c 0
  1.1066 + * \param  encoder  An encoder instance to set.
  1.1067 + * \param  value    See above.
  1.1068 + * \assert
  1.1069 + *    \code encoder != NULL \endcode
  1.1070 + * \retval FLAC__bool
  1.1071 + *    \c false if the encoder is already initialized, else \c true.
  1.1072 + */
  1.1073 +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
  1.1074 +
  1.1075 +/** Deprecated.  Setting this value has no effect.
  1.1076 + *
  1.1077 + * \default \c 0
  1.1078 + * \param  encoder  An encoder instance to set.
  1.1079 + * \param  value    See above.
  1.1080 + * \assert
  1.1081 + *    \code encoder != NULL \endcode
  1.1082 + * \retval FLAC__bool
  1.1083 + *    \c false if the encoder is already initialized, else \c true.
  1.1084 + */
  1.1085 +FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
  1.1086 +
  1.1087 +/** Set an estimate of the total samples that will be encoded.
  1.1088 + *  This is merely an estimate and may be set to \c 0 if unknown.
  1.1089 + *  This value will be written to the STREAMINFO block before encoding,
  1.1090 + *  and can remove the need for the caller to rewrite the value later
  1.1091 + *  if the value is known before encoding.
  1.1092 + *
  1.1093 + * \default \c 0
  1.1094 + * \param  encoder  An encoder instance to set.
  1.1095 + * \param  value    See above.
  1.1096 + * \assert
  1.1097 + *    \code encoder != NULL \endcode
  1.1098 + * \retval FLAC__bool
  1.1099 + *    \c false if the encoder is already initialized, else \c true.
  1.1100 + */
  1.1101 +FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
  1.1102 +
  1.1103 +/** Set the metadata blocks to be emitted to the stream before encoding.
  1.1104 + *  A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
  1.1105 + *  array of pointers to metadata blocks.  The array is non-const since
  1.1106 + *  the encoder may need to change the \a is_last flag inside them, and
  1.1107 + *  in some cases update seek point offsets.  Otherwise, the encoder will
  1.1108 + *  not modify or free the blocks.  It is up to the caller to free the
  1.1109 + *  metadata blocks after encoding finishes.
  1.1110 + *
  1.1111 + * \note
  1.1112 + * The encoder stores only copies of the pointers in the \a metadata array;
  1.1113 + * the metadata blocks themselves must survive at least until after
  1.1114 + * FLAC__stream_encoder_finish() returns.  Do not free the blocks until then.
  1.1115 + *
  1.1116 + * \note
  1.1117 + * The STREAMINFO block is always written and no STREAMINFO block may
  1.1118 + * occur in the supplied array.
  1.1119 + *
  1.1120 + * \note
  1.1121 + * By default the encoder does not create a SEEKTABLE.  If one is supplied
  1.1122 + * in the \a metadata array, but the client has specified that it does not
  1.1123 + * support seeking, then the SEEKTABLE will be written verbatim.  However
  1.1124 + * by itself this is not very useful as the client will not know the stream
  1.1125 + * offsets for the seekpoints ahead of time.  In order to get a proper
  1.1126 + * seektable the client must support seeking.  See next note.
  1.1127 + *
  1.1128 + * \note
  1.1129 + * SEEKTABLE blocks are handled specially.  Since you will not know
  1.1130 + * the values for the seek point stream offsets, you should pass in
  1.1131 + * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
  1.1132 + * required sample numbers (or placeholder points), with \c 0 for the
  1.1133 + * \a frame_samples and \a stream_offset fields for each point.  If the
  1.1134 + * client has specified that it supports seeking by providing a seek
  1.1135 + * callback to FLAC__stream_encoder_init_stream() or both seek AND read
  1.1136 + * callback to FLAC__stream_encoder_init_ogg_stream() (or by using
  1.1137 + * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()),
  1.1138 + * then while it is encoding the encoder will fill the stream offsets in
  1.1139 + * for you and when encoding is finished, it will seek back and write the
  1.1140 + * real values into the SEEKTABLE block in the stream.  There are helper
  1.1141 + * routines for manipulating seektable template blocks; see metadata.h:
  1.1142 + * FLAC__metadata_object_seektable_template_*().  If the client does
  1.1143 + * not support seeking, the SEEKTABLE will have inaccurate offsets which
  1.1144 + * will slow down or remove the ability to seek in the FLAC stream.
  1.1145 + *
  1.1146 + * \note
  1.1147 + * The encoder instance \b will modify the first \c SEEKTABLE block
  1.1148 + * as it transforms the template to a valid seektable while encoding,
  1.1149 + * but it is still up to the caller to free all metadata blocks after
  1.1150 + * encoding.
  1.1151 + *
  1.1152 + * \note
  1.1153 + * A VORBIS_COMMENT block may be supplied.  The vendor string in it
  1.1154 + * will be ignored.  libFLAC will use it's own vendor string. libFLAC
  1.1155 + * will not modify the passed-in VORBIS_COMMENT's vendor string, it
  1.1156 + * will simply write it's own into the stream.  If no VORBIS_COMMENT
  1.1157 + * block is present in the \a metadata array, libFLAC will write an
  1.1158 + * empty one, containing only the vendor string.
  1.1159 + *
  1.1160 + * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
  1.1161 + * the second metadata block of the stream.  The encoder already supplies
  1.1162 + * the STREAMINFO block automatically.  If \a metadata does not contain a
  1.1163 + * VORBIS_COMMENT block, the encoder will supply that too.  Otherwise, if
  1.1164 + * \a metadata does contain a VORBIS_COMMENT block and it is not the
  1.1165 + * first, the init function will reorder \a metadata by moving the
  1.1166 + * VORBIS_COMMENT block to the front; the relative ordering of the other
  1.1167 + * blocks will remain as they were.
  1.1168 + *
  1.1169 + * \note The Ogg FLAC mapping limits the number of metadata blocks per
  1.1170 + * stream to \c 65535.  If \a num_blocks exceeds this the function will
  1.1171 + * return \c false.
  1.1172 + *
  1.1173 + * \default \c NULL, 0
  1.1174 + * \param  encoder     An encoder instance to set.
  1.1175 + * \param  metadata    See above.
  1.1176 + * \param  num_blocks  See above.
  1.1177 + * \assert
  1.1178 + *    \code encoder != NULL \endcode
  1.1179 + * \retval FLAC__bool
  1.1180 + *    \c false if the encoder is already initialized, else \c true.
  1.1181 + *    \c false if the encoder is already initialized, or if
  1.1182 + *    \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
  1.1183 + */
  1.1184 +FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
  1.1185 +
  1.1186 +/** Get the current encoder state.
  1.1187 + *
  1.1188 + * \param  encoder  An encoder instance to query.
  1.1189 + * \assert
  1.1190 + *    \code encoder != NULL \endcode
  1.1191 + * \retval FLAC__StreamEncoderState
  1.1192 + *    The current encoder state.
  1.1193 + */
  1.1194 +FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
  1.1195 +
  1.1196 +/** Get the state of the verify stream decoder.
  1.1197 + *  Useful when the stream encoder state is
  1.1198 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
  1.1199 + *
  1.1200 + * \param  encoder  An encoder instance to query.
  1.1201 + * \assert
  1.1202 + *    \code encoder != NULL \endcode
  1.1203 + * \retval FLAC__StreamDecoderState
  1.1204 + *    The verify stream decoder state.
  1.1205 + */
  1.1206 +FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
  1.1207 +
  1.1208 +/** Get the current encoder state as a C string.
  1.1209 + *  This version automatically resolves
  1.1210 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
  1.1211 + *  verify decoder's state.
  1.1212 + *
  1.1213 + * \param  encoder  A encoder instance to query.
  1.1214 + * \assert
  1.1215 + *    \code encoder != NULL \endcode
  1.1216 + * \retval const char *
  1.1217 + *    The encoder state as a C string.  Do not modify the contents.
  1.1218 + */
  1.1219 +FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
  1.1220 +
  1.1221 +/** Get relevant values about the nature of a verify decoder error.
  1.1222 + *  Useful when the stream encoder state is
  1.1223 + *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.  The arguments should
  1.1224 + *  be addresses in which the stats will be returned, or NULL if value
  1.1225 + *  is not desired.
  1.1226 + *
  1.1227 + * \param  encoder  An encoder instance to query.
  1.1228 + * \param  absolute_sample  The absolute sample number of the mismatch.
  1.1229 + * \param  frame_number  The number of the frame in which the mismatch occurred.
  1.1230 + * \param  channel       The channel in which the mismatch occurred.
  1.1231 + * \param  sample        The number of the sample (relative to the frame) in
  1.1232 + *                       which the mismatch occurred.
  1.1233 + * \param  expected      The expected value for the sample in question.
  1.1234 + * \param  got           The actual value returned by the decoder.
  1.1235 + * \assert
  1.1236 + *    \code encoder != NULL \endcode
  1.1237 + */
  1.1238 +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);
  1.1239 +
  1.1240 +/** Get the "verify" flag.
  1.1241 + *
  1.1242 + * \param  encoder  An encoder instance to query.
  1.1243 + * \assert
  1.1244 + *    \code encoder != NULL \endcode
  1.1245 + * \retval FLAC__bool
  1.1246 + *    See FLAC__stream_encoder_set_verify().
  1.1247 + */
  1.1248 +FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
  1.1249 +
  1.1250 +/** Get the <A HREF="../format.html#subset>Subset</A> flag.
  1.1251 + *
  1.1252 + * \param  encoder  An encoder instance to query.
  1.1253 + * \assert
  1.1254 + *    \code encoder != NULL \endcode
  1.1255 + * \retval FLAC__bool
  1.1256 + *    See FLAC__stream_encoder_set_streamable_subset().
  1.1257 + */
  1.1258 +FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
  1.1259 +
  1.1260 +/** Get the number of input channels being processed.
  1.1261 + *
  1.1262 + * \param  encoder  An encoder instance to query.
  1.1263 + * \assert
  1.1264 + *    \code encoder != NULL \endcode
  1.1265 + * \retval unsigned
  1.1266 + *    See FLAC__stream_encoder_set_channels().
  1.1267 + */
  1.1268 +FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
  1.1269 +
  1.1270 +/** Get the input sample resolution setting.
  1.1271 + *
  1.1272 + * \param  encoder  An encoder instance to query.
  1.1273 + * \assert
  1.1274 + *    \code encoder != NULL \endcode
  1.1275 + * \retval unsigned
  1.1276 + *    See FLAC__stream_encoder_set_bits_per_sample().
  1.1277 + */
  1.1278 +FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
  1.1279 +
  1.1280 +/** Get the input sample rate setting.
  1.1281 + *
  1.1282 + * \param  encoder  An encoder instance to query.
  1.1283 + * \assert
  1.1284 + *    \code encoder != NULL \endcode
  1.1285 + * \retval unsigned
  1.1286 + *    See FLAC__stream_encoder_set_sample_rate().
  1.1287 + */
  1.1288 +FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
  1.1289 +
  1.1290 +/** Get the blocksize setting.
  1.1291 + *
  1.1292 + * \param  encoder  An encoder instance to query.
  1.1293 + * \assert
  1.1294 + *    \code encoder != NULL \endcode
  1.1295 + * \retval unsigned
  1.1296 + *    See FLAC__stream_encoder_set_blocksize().
  1.1297 + */
  1.1298 +FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
  1.1299 +
  1.1300 +/** Get the "mid/side stereo coding" flag.
  1.1301 + *
  1.1302 + * \param  encoder  An encoder instance to query.
  1.1303 + * \assert
  1.1304 + *    \code encoder != NULL \endcode
  1.1305 + * \retval FLAC__bool
  1.1306 + *    See FLAC__stream_encoder_get_do_mid_side_stereo().
  1.1307 + */
  1.1308 +FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
  1.1309 +
  1.1310 +/** Get the "adaptive mid/side switching" flag.
  1.1311 + *
  1.1312 + * \param  encoder  An encoder instance to query.
  1.1313 + * \assert
  1.1314 + *    \code encoder != NULL \endcode
  1.1315 + * \retval FLAC__bool
  1.1316 + *    See FLAC__stream_encoder_set_loose_mid_side_stereo().
  1.1317 + */
  1.1318 +FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
  1.1319 +
  1.1320 +/** Get the maximum LPC order setting.
  1.1321 + *
  1.1322 + * \param  encoder  An encoder instance to query.
  1.1323 + * \assert
  1.1324 + *    \code encoder != NULL \endcode
  1.1325 + * \retval unsigned
  1.1326 + *    See FLAC__stream_encoder_set_max_lpc_order().
  1.1327 + */
  1.1328 +FLAC_API unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
  1.1329 +
  1.1330 +/** Get the quantized linear predictor coefficient precision setting.
  1.1331 + *
  1.1332 + * \param  encoder  An encoder instance to query.
  1.1333 + * \assert
  1.1334 + *    \code encoder != NULL \endcode
  1.1335 + * \retval unsigned
  1.1336 + *    See FLAC__stream_encoder_set_qlp_coeff_precision().
  1.1337 + */
  1.1338 +FLAC_API unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
  1.1339 +
  1.1340 +/** Get the qlp coefficient precision search flag.
  1.1341 + *
  1.1342 + * \param  encoder  An encoder instance to query.
  1.1343 + * \assert
  1.1344 + *    \code encoder != NULL \endcode
  1.1345 + * \retval FLAC__bool
  1.1346 + *    See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
  1.1347 + */
  1.1348 +FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
  1.1349 +
  1.1350 +/** Get the "escape coding" flag.
  1.1351 + *
  1.1352 + * \param  encoder  An encoder instance to query.
  1.1353 + * \assert
  1.1354 + *    \code encoder != NULL \endcode
  1.1355 + * \retval FLAC__bool
  1.1356 + *    See FLAC__stream_encoder_set_do_escape_coding().
  1.1357 + */
  1.1358 +FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
  1.1359 +
  1.1360 +/** Get the exhaustive model search flag.
  1.1361 + *
  1.1362 + * \param  encoder  An encoder instance to query.
  1.1363 + * \assert
  1.1364 + *    \code encoder != NULL \endcode
  1.1365 + * \retval FLAC__bool
  1.1366 + *    See FLAC__stream_encoder_set_do_exhaustive_model_search().
  1.1367 + */
  1.1368 +FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
  1.1369 +
  1.1370 +/** Get the minimum residual partition order setting.
  1.1371 + *
  1.1372 + * \param  encoder  An encoder instance to query.
  1.1373 + * \assert
  1.1374 + *    \code encoder != NULL \endcode
  1.1375 + * \retval unsigned
  1.1376 + *    See FLAC__stream_encoder_set_min_residual_partition_order().
  1.1377 + */
  1.1378 +FLAC_API unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
  1.1379 +
  1.1380 +/** Get maximum residual partition order setting.
  1.1381 + *
  1.1382 + * \param  encoder  An encoder instance to query.
  1.1383 + * \assert
  1.1384 + *    \code encoder != NULL \endcode
  1.1385 + * \retval unsigned
  1.1386 + *    See FLAC__stream_encoder_set_max_residual_partition_order().
  1.1387 + */
  1.1388 +FLAC_API unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
  1.1389 +
  1.1390 +/** Get the Rice parameter search distance setting.
  1.1391 + *
  1.1392 + * \param  encoder  An encoder instance to query.
  1.1393 + * \assert
  1.1394 + *    \code encoder != NULL \endcode
  1.1395 + * \retval unsigned
  1.1396 + *    See FLAC__stream_encoder_set_rice_parameter_search_dist().
  1.1397 + */
  1.1398 +FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
  1.1399 +
  1.1400 +/** Get the previously set estimate of the total samples to be encoded.
  1.1401 + *  The encoder merely mimics back the value given to
  1.1402 + *  FLAC__stream_encoder_set_total_samples_estimate() since it has no
  1.1403 + *  other way of knowing how many samples the client will encode.
  1.1404 + *
  1.1405 + * \param  encoder  An encoder instance to set.
  1.1406 + * \assert
  1.1407 + *    \code encoder != NULL \endcode
  1.1408 + * \retval FLAC__uint64
  1.1409 + *    See FLAC__stream_encoder_get_total_samples_estimate().
  1.1410 + */
  1.1411 +FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
  1.1412 +
  1.1413 +/** Initialize the encoder instance to encode native FLAC streams.
  1.1414 + *
  1.1415 + *  This flavor of initialization sets up the encoder to encode to a
  1.1416 + *  native FLAC stream. I/O is performed via callbacks to the client.
  1.1417 + *  For encoding to a plain file via filename or open \c FILE*,
  1.1418 + *  FLAC__stream_encoder_init_file() and FLAC__stream_encoder_init_FILE()
  1.1419 + *  provide a simpler interface.
  1.1420 + *
  1.1421 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1422 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1423 + *  or FLAC__stream_encoder_process_interleaved().
  1.1424 + *  initialization succeeded.
  1.1425 + *
  1.1426 + *  The call to FLAC__stream_encoder_init_stream() currently will also
  1.1427 + *  immediately call the write callback several times, once with the \c fLaC
  1.1428 + *  signature, and once for each encoded metadata block.
  1.1429 + *
  1.1430 + * \param  encoder            An uninitialized encoder instance.
  1.1431 + * \param  write_callback     See FLAC__StreamEncoderWriteCallback.  This
  1.1432 + *                            pointer must not be \c NULL.
  1.1433 + * \param  seek_callback      See FLAC__StreamEncoderSeekCallback.  This
  1.1434 + *                            pointer may be \c NULL if seeking is not
  1.1435 + *                            supported.  The encoder uses seeking to go back
  1.1436 + *                            and write some some stream statistics to the
  1.1437 + *                            STREAMINFO block; this is recommended but not
  1.1438 + *                            necessary to create a valid FLAC stream.  If
  1.1439 + *                            \a seek_callback is not \c NULL then a
  1.1440 + *                            \a tell_callback must also be supplied.
  1.1441 + *                            Alternatively, a dummy seek callback that just
  1.1442 + *                            returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  1.1443 + *                            may also be supplied, all though this is slightly
  1.1444 + *                            less efficient for the encoder.
  1.1445 + * \param  tell_callback      See FLAC__StreamEncoderTellCallback.  This
  1.1446 + *                            pointer may be \c NULL if seeking is not
  1.1447 + *                            supported.  If \a seek_callback is \c NULL then
  1.1448 + *                            this argument will be ignored.  If
  1.1449 + *                            \a seek_callback is not \c NULL then a
  1.1450 + *                            \a tell_callback must also be supplied.
  1.1451 + *                            Alternatively, a dummy tell callback that just
  1.1452 + *                            returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  1.1453 + *                            may also be supplied, all though this is slightly
  1.1454 + *                            less efficient for the encoder.
  1.1455 + * \param  metadata_callback  See FLAC__StreamEncoderMetadataCallback.  This
  1.1456 + *                            pointer may be \c NULL if the callback is not
  1.1457 + *                            desired.  If the client provides a seek callback,
  1.1458 + *                            this function is not necessary as the encoder
  1.1459 + *                            will automatically seek back and update the
  1.1460 + *                            STREAMINFO block.  It may also be \c NULL if the
  1.1461 + *                            client does not support seeking, since it will
  1.1462 + *                            have no way of going back to update the
  1.1463 + *                            STREAMINFO.  However the client can still supply
  1.1464 + *                            a callback if it would like to know the details
  1.1465 + *                            from the STREAMINFO.
  1.1466 + * \param  client_data        This value will be supplied to callbacks in their
  1.1467 + *                            \a client_data argument.
  1.1468 + * \assert
  1.1469 + *    \code encoder != NULL \endcode
  1.1470 + * \retval FLAC__StreamEncoderInitStatus
  1.1471 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1472 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1473 + */
  1.1474 +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);
  1.1475 +
  1.1476 +/** Initialize the encoder instance to encode Ogg FLAC streams.
  1.1477 + *
  1.1478 + *  This flavor of initialization sets up the encoder to encode to a FLAC
  1.1479 + *  stream in an Ogg container.  I/O is performed via callbacks to the
  1.1480 + *  client.  For encoding to a plain file via filename or open \c FILE*,
  1.1481 + *  FLAC__stream_encoder_init_ogg_file() and FLAC__stream_encoder_init_ogg_FILE()
  1.1482 + *  provide a simpler interface.
  1.1483 + *
  1.1484 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1485 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1486 + *  or FLAC__stream_encoder_process_interleaved().
  1.1487 + *  initialization succeeded.
  1.1488 + *
  1.1489 + *  The call to FLAC__stream_encoder_init_ogg_stream() currently will also
  1.1490 + *  immediately call the write callback several times to write the metadata
  1.1491 + *  packets.
  1.1492 + *
  1.1493 + * \param  encoder            An uninitialized encoder instance.
  1.1494 + * \param  read_callback      See FLAC__StreamEncoderReadCallback.  This
  1.1495 + *                            pointer must not be \c NULL if \a seek_callback
  1.1496 + *                            is non-NULL since they are both needed to be
  1.1497 + *                            able to write data back to the Ogg FLAC stream
  1.1498 + *                            in the post-encode phase.
  1.1499 + * \param  write_callback     See FLAC__StreamEncoderWriteCallback.  This
  1.1500 + *                            pointer must not be \c NULL.
  1.1501 + * \param  seek_callback      See FLAC__StreamEncoderSeekCallback.  This
  1.1502 + *                            pointer may be \c NULL if seeking is not
  1.1503 + *                            supported.  The encoder uses seeking to go back
  1.1504 + *                            and write some some stream statistics to the
  1.1505 + *                            STREAMINFO block; this is recommended but not
  1.1506 + *                            necessary to create a valid FLAC stream.  If
  1.1507 + *                            \a seek_callback is not \c NULL then a
  1.1508 + *                            \a tell_callback must also be supplied.
  1.1509 + *                            Alternatively, a dummy seek callback that just
  1.1510 + *                            returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  1.1511 + *                            may also be supplied, all though this is slightly
  1.1512 + *                            less efficient for the encoder.
  1.1513 + * \param  tell_callback      See FLAC__StreamEncoderTellCallback.  This
  1.1514 + *                            pointer may be \c NULL if seeking is not
  1.1515 + *                            supported.  If \a seek_callback is \c NULL then
  1.1516 + *                            this argument will be ignored.  If
  1.1517 + *                            \a seek_callback is not \c NULL then a
  1.1518 + *                            \a tell_callback must also be supplied.
  1.1519 + *                            Alternatively, a dummy tell callback that just
  1.1520 + *                            returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  1.1521 + *                            may also be supplied, all though this is slightly
  1.1522 + *                            less efficient for the encoder.
  1.1523 + * \param  metadata_callback  See FLAC__StreamEncoderMetadataCallback.  This
  1.1524 + *                            pointer may be \c NULL if the callback is not
  1.1525 + *                            desired.  If the client provides a seek callback,
  1.1526 + *                            this function is not necessary as the encoder
  1.1527 + *                            will automatically seek back and update the
  1.1528 + *                            STREAMINFO block.  It may also be \c NULL if the
  1.1529 + *                            client does not support seeking, since it will
  1.1530 + *                            have no way of going back to update the
  1.1531 + *                            STREAMINFO.  However the client can still supply
  1.1532 + *                            a callback if it would like to know the details
  1.1533 + *                            from the STREAMINFO.
  1.1534 + * \param  client_data        This value will be supplied to callbacks in their
  1.1535 + *                            \a client_data argument.
  1.1536 + * \assert
  1.1537 + *    \code encoder != NULL \endcode
  1.1538 + * \retval FLAC__StreamEncoderInitStatus
  1.1539 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1540 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1541 + */
  1.1542 +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);
  1.1543 +
  1.1544 +/** Initialize the encoder instance to encode native FLAC files.
  1.1545 + *
  1.1546 + *  This flavor of initialization sets up the encoder to encode to a
  1.1547 + *  plain native FLAC file.  For non-stdio streams, you must use
  1.1548 + *  FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
  1.1549 + *
  1.1550 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1551 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1552 + *  or FLAC__stream_encoder_process_interleaved().
  1.1553 + *  initialization succeeded.
  1.1554 + *
  1.1555 + * \param  encoder            An uninitialized encoder instance.
  1.1556 + * \param  file               An open file.  The file should have been opened
  1.1557 + *                            with mode \c "w+b" and rewound.  The file
  1.1558 + *                            becomes owned by the encoder and should not be
  1.1559 + *                            manipulated by the client while encoding.
  1.1560 + *                            Unless \a file is \c stdout, it will be closed
  1.1561 + *                            when FLAC__stream_encoder_finish() is called.
  1.1562 + *                            Note however that a proper SEEKTABLE cannot be
  1.1563 + *                            created when encoding to \c stdout since it is
  1.1564 + *                            not seekable.
  1.1565 + * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
  1.1566 + *                            pointer may be \c NULL if the callback is not
  1.1567 + *                            desired.
  1.1568 + * \param  client_data        This value will be supplied to callbacks in their
  1.1569 + *                            \a client_data argument.
  1.1570 + * \assert
  1.1571 + *    \code encoder != NULL \endcode
  1.1572 + *    \code file != NULL \endcode
  1.1573 + * \retval FLAC__StreamEncoderInitStatus
  1.1574 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1575 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1576 + */
  1.1577 +FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1.1578 +
  1.1579 +/** Initialize the encoder instance to encode Ogg FLAC files.
  1.1580 + *
  1.1581 + *  This flavor of initialization sets up the encoder to encode to a
  1.1582 + *  plain Ogg FLAC file.  For non-stdio streams, you must use
  1.1583 + *  FLAC__stream_encoder_init_ogg_stream() and provide callbacks for the I/O.
  1.1584 + *
  1.1585 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1586 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1587 + *  or FLAC__stream_encoder_process_interleaved().
  1.1588 + *  initialization succeeded.
  1.1589 + *
  1.1590 + * \param  encoder            An uninitialized encoder instance.
  1.1591 + * \param  file               An open file.  The file should have been opened
  1.1592 + *                            with mode \c "w+b" and rewound.  The file
  1.1593 + *                            becomes owned by the encoder and should not be
  1.1594 + *                            manipulated by the client while encoding.
  1.1595 + *                            Unless \a file is \c stdout, it will be closed
  1.1596 + *                            when FLAC__stream_encoder_finish() is called.
  1.1597 + *                            Note however that a proper SEEKTABLE cannot be
  1.1598 + *                            created when encoding to \c stdout since it is
  1.1599 + *                            not seekable.
  1.1600 + * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
  1.1601 + *                            pointer may be \c NULL if the callback is not
  1.1602 + *                            desired.
  1.1603 + * \param  client_data        This value will be supplied to callbacks in their
  1.1604 + *                            \a client_data argument.
  1.1605 + * \assert
  1.1606 + *    \code encoder != NULL \endcode
  1.1607 + *    \code file != NULL \endcode
  1.1608 + * \retval FLAC__StreamEncoderInitStatus
  1.1609 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1610 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1611 + */
  1.1612 +FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1.1613 +
  1.1614 +/** Initialize the encoder instance to encode native FLAC files.
  1.1615 + *
  1.1616 + *  This flavor of initialization sets up the encoder to encode to a plain
  1.1617 + *  FLAC file.  If POSIX fopen() semantics are not sufficient (for example,
  1.1618 + *  with Unicode filenames on Windows), you must use
  1.1619 + *  FLAC__stream_encoder_init_FILE(), or FLAC__stream_encoder_init_stream()
  1.1620 + *  and provide callbacks for the I/O.
  1.1621 + *
  1.1622 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1623 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1624 + *  or FLAC__stream_encoder_process_interleaved().
  1.1625 + *  initialization succeeded.
  1.1626 + *
  1.1627 + * \param  encoder            An uninitialized encoder instance.
  1.1628 + * \param  filename           The name of the file to encode to.  The file will
  1.1629 + *                            be opened with fopen().  Use \c NULL to encode to
  1.1630 + *                            \c stdout.  Note however that a proper SEEKTABLE
  1.1631 + *                            cannot be created when encoding to \c stdout since
  1.1632 + *                            it is not seekable.
  1.1633 + * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
  1.1634 + *                            pointer may be \c NULL if the callback is not
  1.1635 + *                            desired.
  1.1636 + * \param  client_data        This value will be supplied to callbacks in their
  1.1637 + *                            \a client_data argument.
  1.1638 + * \assert
  1.1639 + *    \code encoder != NULL \endcode
  1.1640 + * \retval FLAC__StreamEncoderInitStatus
  1.1641 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1642 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1643 + */
  1.1644 +FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1.1645 +
  1.1646 +/** Initialize the encoder instance to encode Ogg FLAC files.
  1.1647 + *
  1.1648 + *  This flavor of initialization sets up the encoder to encode to a plain
  1.1649 + *  Ogg FLAC file.  If POSIX fopen() semantics are not sufficient (for example,
  1.1650 + *  with Unicode filenames on Windows), you must use
  1.1651 + *  FLAC__stream_encoder_init_ogg_FILE(), or FLAC__stream_encoder_init_ogg_stream()
  1.1652 + *  and provide callbacks for the I/O.
  1.1653 + *
  1.1654 + *  This function should be called after FLAC__stream_encoder_new() and
  1.1655 + *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1.1656 + *  or FLAC__stream_encoder_process_interleaved().
  1.1657 + *  initialization succeeded.
  1.1658 + *
  1.1659 + * \param  encoder            An uninitialized encoder instance.
  1.1660 + * \param  filename           The name of the file to encode to.  The file will
  1.1661 + *                            be opened with fopen().  Use \c NULL to encode to
  1.1662 + *                            \c stdout.  Note however that a proper SEEKTABLE
  1.1663 + *                            cannot be created when encoding to \c stdout since
  1.1664 + *                            it is not seekable.
  1.1665 + * \param  progress_callback  See FLAC__StreamEncoderProgressCallback.  This
  1.1666 + *                            pointer may be \c NULL if the callback is not
  1.1667 + *                            desired.
  1.1668 + * \param  client_data        This value will be supplied to callbacks in their
  1.1669 + *                            \a client_data argument.
  1.1670 + * \assert
  1.1671 + *    \code encoder != NULL \endcode
  1.1672 + * \retval FLAC__StreamEncoderInitStatus
  1.1673 + *    \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1.1674 + *    see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1.1675 + */
  1.1676 +FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1.1677 +
  1.1678 +/** Finish the encoding process.
  1.1679 + *  Flushes the encoding buffer, releases resources, resets the encoder
  1.1680 + *  settings to their defaults, and returns the encoder state to
  1.1681 + *  FLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
  1.1682 + *  one or more write callbacks before returning, and will generate
  1.1683 + *  a metadata callback.
  1.1684 + *
  1.1685 + *  Note that in the course of processing the last frame, errors can
  1.1686 + *  occur, so the caller should be sure to check the return value to
  1.1687 + *  ensure the file was encoded properly.
  1.1688 + *
  1.1689 + *  In the event of a prematurely-terminated encode, it is not strictly
  1.1690 + *  necessary to call this immediately before FLAC__stream_encoder_delete()
  1.1691 + *  but it is good practice to match every FLAC__stream_encoder_init_*()
  1.1692 + *  with a FLAC__stream_encoder_finish().
  1.1693 + *
  1.1694 + * \param  encoder  An uninitialized encoder instance.
  1.1695 + * \assert
  1.1696 + *    \code encoder != NULL \endcode
  1.1697 + * \retval FLAC__bool
  1.1698 + *    \c false if an error occurred processing the last frame; or if verify
  1.1699 + *    mode is set (see FLAC__stream_encoder_set_verify()), there was a
  1.1700 + *    verify mismatch; else \c true.  If \c false, caller should check the
  1.1701 + *    state with FLAC__stream_encoder_get_state() for more information
  1.1702 + *    about the error.
  1.1703 + */
  1.1704 +FLAC_API FLAC__bool FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
  1.1705 +
  1.1706 +/** Submit data for encoding.
  1.1707 + *  This version allows you to supply the input data via an array of
  1.1708 + *  pointers, each pointer pointing to an array of \a samples samples
  1.1709 + *  representing one channel.  The samples need not be block-aligned,
  1.1710 + *  but each channel should have the same number of samples.  Each sample
  1.1711 + *  should be a signed integer, right-justified to the resolution set by
  1.1712 + *  FLAC__stream_encoder_set_bits_per_sample().  For example, if the
  1.1713 + *  resolution is 16 bits per sample, the samples should all be in the
  1.1714 + *  range [-32768,32767].
  1.1715 + *
  1.1716 + *  For applications where channel order is important, channels must
  1.1717 + *  follow the order as described in the
  1.1718 + *  <A HREF="../format.html#frame_header">frame header</A>.
  1.1719 + *
  1.1720 + * \param  encoder  An initialized encoder instance in the OK state.
  1.1721 + * \param  buffer   An array of pointers to each channel's signal.
  1.1722 + * \param  samples  The number of samples in one channel.
  1.1723 + * \assert
  1.1724 + *    \code encoder != NULL \endcode
  1.1725 + *    \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
  1.1726 + * \retval FLAC__bool
  1.1727 + *    \c true if successful, else \c false; in this case, check the
  1.1728 + *    encoder state with FLAC__stream_encoder_get_state() to see what
  1.1729 + *    went wrong.
  1.1730 + */
  1.1731 +FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
  1.1732 +
  1.1733 +/** Submit data for encoding.
  1.1734 + *  This version allows you to supply the input data where the channels
  1.1735 + *  are interleaved into a single array (i.e. channel0_sample0,
  1.1736 + *  channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  1.1737 + *  The samples need not be block-aligned but they must be
  1.1738 + *  sample-aligned, i.e. the first value should be channel0_sample0
  1.1739 + *  and the last value channelN_sampleM.  Each sample should be a signed
  1.1740 + *  integer, right-justified to the resolution set by
  1.1741 + *  FLAC__stream_encoder_set_bits_per_sample().  For example, if the
  1.1742 + *  resolution is 16 bits per sample, the samples should all be in the
  1.1743 + *  range [-32768,32767].
  1.1744 + *
  1.1745 + *  For applications where channel order is important, channels must
  1.1746 + *  follow the order as described in the
  1.1747 + *  <A HREF="../format.html#frame_header">frame header</A>.
  1.1748 + *
  1.1749 + * \param  encoder  An initialized encoder instance in the OK state.
  1.1750 + * \param  buffer   An array of channel-interleaved data (see above).
  1.1751 + * \param  samples  The number of samples in one channel, the same as for
  1.1752 + *                  FLAC__stream_encoder_process().  For example, if
  1.1753 + *                  encoding two channels, \c 1000 \a samples corresponds
  1.1754 + *                  to a \a buffer of 2000 values.
  1.1755 + * \assert
  1.1756 + *    \code encoder != NULL \endcode
  1.1757 + *    \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
  1.1758 + * \retval FLAC__bool
  1.1759 + *    \c true if successful, else \c false; in this case, check the
  1.1760 + *    encoder state with FLAC__stream_encoder_get_state() to see what
  1.1761 + *    went wrong.
  1.1762 + */
  1.1763 +FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
  1.1764 +
  1.1765 +/* \} */
  1.1766 +
  1.1767 +#ifdef __cplusplus
  1.1768 +}
  1.1769 +#endif
  1.1770 +
  1.1771 +#endif