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