1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002 Josh Coalson
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
20 #ifndef FLAC__STREAM_ENCODER_H
21 #define FLAC__STREAM_ENCODER_H
30 /** \file include/FLAC/stream_encoder.h
33 * This module contains the functions which implement the stream
36 * See the detailed documentation in the
37 * \link flac_stream_encoder stream encoder \endlink module.
40 /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
44 * This module contains the functions which implement the stream
47 * The basic usage of a libFLAC encoder is as follows:
48 * - The program creates an instance of an encoder using
49 * FLAC__stream_encoder_new().
50 * - The program overrides the default settings and sets callbacks for
51 * reading, writing, error reporting, and metadata reporting using
52 * FLAC__stream_encoder_set_*() functions.
53 * - The program initializes the instance to validate the settings and
54 * prepare for encoding using FLAC__stream_encoder_init().
55 * - The program calls FLAC__stream_encoder_process() or
56 * FLAC__stream_encoder_process_interleaved() to encode data, which
57 * subsequently calls the callbacks.
58 * - The program finishes the instance with FLAC__stream_encoder_finish(),
59 * which flushes the input and output and resets the encoder to the
61 * - The instance may be used again or deleted with
62 * FLAC__stream_encoder_delete().
65 * The "set" functions may only be called when the encoder is in the
66 * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
67 * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
68 * before FLAC__stream_encoder_init(). If this is the case they will
69 * return true, otherwise false.
72 * The "set" functions do not validate the values as many are
73 * interdependent. The FLAC__stream_encoder_init() function will do
74 * this, so make sure to pay attention to the state returned by
75 * FLAC__stream_encoder_init() to make sure that it is
76 * FLAC__STREAM_ENCODER_OK.
79 * Unlike the decoders, the stream encoder has many options that can
80 * affect the speed and compression ratio. When setting these parameters
81 * you should have some basic knowledge of the format (see the
82 * <A HREF="../documentation.html#format">user-level documentation</A>
83 * or the <A HREF="../format.html">formal description</A>).
86 * Any parameters that are not set before FLAC__stream_encoder_init()
87 * will take on the defaults from the constructor.
90 * FLAC__stream_encoder_finish() resets all settings to the constructor
91 * defaults, including the callbacks.
97 /** State values for a FLAC__StreamEncoder
99 * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
103 FLAC__STREAM_ENCODER_OK = 0,
104 /**< The encoder is in the normal OK state. */
106 FLAC__STREAM_ENCODER_INVALID_CALLBACK,
107 /**< The encoder was initialized before setting all the required callbacks. */
109 FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS,
110 /**< The encoder has an invalid setting for number of channels. */
112 FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE,
113 /**< The encoder has an invalid setting for bits-per-sample.
114 * FLAC supports 4-32 bps but the reference encoder currently supports
118 FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE,
119 /**< The encoder has an invalid setting for the input sample rate. */
121 FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,
122 /**< The encoder has an invalid setting for the block size. */
124 FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION,
125 /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
127 FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH,
128 /**< Mid/side coding was specified but the number of channels is not equal to 2. */
130 FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,
133 FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE,
134 /**< Loose mid/side coding was specified but mid/side coding was not. */
136 FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
137 /**< The specified block size is less than the maximum LPC order. */
139 FLAC__STREAM_ENCODER_NOT_STREAMABLE,
140 /**< The encoder is bound to the "streamable subset" but other settings violate it. */
142 FLAC__STREAM_ENCODER_FRAMING_ERROR,
143 /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
145 FLAC__STREAM_ENCODER_INVALID_METADATA,
146 /**< The metadata input to the encoder is invalid. */
148 FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING,
149 /**< An error occurred while writing the stream; usually, the write_callback returned an error. */
151 FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING,
152 /**< The write_callback returned an error. */
154 FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
155 /**< Memory allocation failed. */
157 FLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
158 /**< FLAC__stream_encoder_init() was called when the encoder was
159 * already initialized, usually because
160 * FLAC__stream_encoder_finish() was not called.
163 FLAC__STREAM_ENCODER_UNINITIALIZED
164 /**< The encoder is in the uninitialized state. */
166 } FLAC__StreamEncoderState;
168 /** Maps a FLAC__StreamEncoderState to a C string.
170 * Using a FLAC__StreamEncoderState as the index to this array
171 * will give the string equivalent. The contents should not be modified.
173 extern const char * const FLAC__StreamEncoderStateString[];
175 /** Return values for the FLAC__StreamEncoder write callback.
179 FLAC__STREAM_ENCODER_WRITE_OK = 0,
180 /**< The write was OK and encoding can continue. */
182 FLAC__STREAM_ENCODER_WRITE_FATAL_ERROR
183 /**< An unrecoverable error occurred. The encoder will return from the process call. */
185 } FLAC__StreamEncoderWriteStatus;
187 /** Maps a FLAC__StreamEncoderWriteStatus to a C string.
189 * Using a FLAC__StreamEncoderWriteStatus as the index to this array
190 * will give the string equivalent. The contents should not be modified.
192 extern const char * const FLAC__StreamEncoderWriteStatusString[];
195 /***********************************************************************
197 * class FLAC__StreamEncoder
199 ***********************************************************************/
201 struct FLAC__StreamEncoderProtected;
202 struct FLAC__StreamEncoderPrivate;
203 /** The opaque structure definition for the stream encoder type.
206 struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
207 struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
208 } FLAC__StreamEncoder;
211 /***********************************************************************
213 * Class constructor/destructor
215 ***********************************************************************/
217 /** Create a new stream encoder instance. The instance is created with
218 * default settings; see the individual FLAC__stream_encoder_set_*()
219 * functions for each setting's default.
221 * \retval FLAC__StreamEncoder*
222 * \c NULL if there was an error allocating memory, else the new instance.
224 FLAC__StreamEncoder *FLAC__stream_encoder_new();
226 /** Free an encoder instance. Deletes the object pointed to by \a encoder.
228 * \param encoder A pointer to an existing encoder.
230 * \code encoder != NULL \endcode
232 void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
234 /***********************************************************************
236 * Public class method prototypes
238 ***********************************************************************/
241 * FLAC__bool do_qlp_coeff_prec_search (DEFAULT: false ) false => use qlp_coeff_precision, true => search around qlp_coeff_precision, take best
242 * FLAC__bool do_escape_coding (DEFAULT: false ) true => search for escape codes in the entropy coding stage for slightly better compression
243 * FLAC__bool do_exhaustive_model_search (DEFAULT: false ) false => use estimated bits per residual for scoring, true => generate all, take shortest
244 * unsigned min_residual_partition_order (DEFAULT: 0 ) 0 => estimate Rice parameter based on residual variance; >0 => partition residual, use parameter
245 * unsigned max_residual_partition_order (DEFAULT: 0 ) for each based on mean; min_ and max_ specify the min and max Rice partition order
246 * unsigned rice_parameter_search_dist (DEFAULT: 0 ) 0 => try only calc'd parameter k; else try all [k-dist..k+dist] parameters, use best
247 * FLAC__uint64 total_samples_estimate (DEFAULT: 0 ) may be 0 if unknown. acts as a placeholder in the STREAMINFO until the actual total is calculated
248 * FLAC__StreamMetadata **metadata (DEFAULT: NULL,0) optional metadata blocks to prepend. STREAMINFO is not allowed since it is done internally.
249 * + unsigned num_blocks
250 * void* client_data (DEFAULT: NULL ) passed back through the callbacks
253 /** Set the "streamable subset" flag. If \c true, the encoder will comply
254 * with the subset (see the format specification) and will check the
255 * settings during FLAC__stream_encoder_init() to see if all settings
256 * comply. If \c false, the settings may take advantage of the full
257 * range that the format allows.
259 * Make sure you know what it entails before setting this to \c false.
262 * \param encoder An encoder instance to set.
263 * \param value Flag value (see above).
265 * \code encoder != NULL \endcode
267 * \c false if the encoder is already initialized, else \c true.
269 FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
271 /** Set to \c true to enable mid-side encoding on stereo input. The
272 * number of channels must be 2. Set to \c false to use only
273 * independent channel coding.
276 * \param encoder An encoder instance to set.
277 * \param value Flag value (see above).
279 * \code encoder != NULL \endcode
281 * \c false if the encoder is already initialized, else \c true.
283 FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
285 /** Set to \c true to enable adaptive switching between mid-side and
286 * left-right encoding on stereo input. The number of channels must
287 * be 2. Set to \c false to use exhaustive searching. In either
288 * case, the mid/side stereo setting must be \c true.
291 * \param encoder An encoder instance to set.
292 * \param value Flag value (see above).
294 * \code encoder != NULL \endcode
296 * \c false if the encoder is already initialized, else \c true.
298 FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
300 /** Set the number of channels to be encoded.
303 * \param encoder An encoder instance to set.
304 * \param value See above.
306 * \code encoder != NULL \endcode
308 * \c false if the encoder is already initialized, else \c true.
310 FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
312 /** Set the sample resolution of the input to be encoded.
315 * Do not feed the encoder data that is wider than the value you
316 * set here or you will generate an invalid stream.
319 * \param encoder An encoder instance to set.
320 * \param value See above.
322 * \code encoder != NULL \endcode
324 * \c false if the encoder is already initialized, else \c true.
326 FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
328 /** Set the sample rate (in Hz) of the input to be encoded.
331 * \param encoder An encoder instance to set.
332 * \param value See above.
334 * \code encoder != NULL \endcode
336 * \c false if the encoder is already initialized, else \c true.
338 FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
340 /** Set the blocksize to use while encoding.
343 * \param encoder An encoder instance to set.
344 * \param value See above.
346 * \code encoder != NULL \endcode
348 * \c false if the encoder is already initialized, else \c true.
350 FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
352 /** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
355 * \param encoder An encoder instance to set.
356 * \param value See above.
358 * \code encoder != NULL \endcode
360 * \c false if the encoder is already initialized, else \c true.
362 FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
364 /** Set the precision, in bits, of the quantized linear predictor
365 * coefficients, or \c 0 to let the encoder select it based on the
369 * In the current implementation, qlp_coeff_precision + bits_per_sample must
373 * \param encoder An encoder instance to set.
374 * \param value See above.
376 * \code encoder != NULL \endcode
378 * \c false if the encoder is already initialized, else \c true.
380 FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
382 /** Set the number of channels to be encoded.
385 * \param encoder An encoder instance to set.
386 * \param value See above.
388 * \code encoder != NULL \endcode
390 * \c false if the encoder is already initialized, else \c true.
392 FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
394 /** Set the number of channels to be encoded.
397 * \param encoder An encoder instance to set.
398 * \param value See above.
400 * \code encoder != NULL \endcode
402 * \c false if the encoder is already initialized, else \c true.
404 FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
406 /** Set the number of channels to be encoded.
409 * \param encoder An encoder instance to set.
410 * \param value See above.
412 * \code encoder != NULL \endcode
414 * \c false if the encoder is already initialized, else \c true.
416 FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
418 /** Set the number of channels to be encoded.
421 * \param encoder An encoder instance to set.
422 * \param value See above.
424 * \code encoder != NULL \endcode
426 * \c false if the encoder is already initialized, else \c true.
428 FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
430 /** Set the number of channels to be encoded.
433 * \param encoder An encoder instance to set.
434 * \param value See above.
436 * \code encoder != NULL \endcode
438 * \c false if the encoder is already initialized, else \c true.
440 FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
442 /** Set the number of channels to be encoded.
445 * \param encoder An encoder instance to set.
446 * \param value See above.
448 * \code encoder != NULL \endcode
450 * \c false if the encoder is already initialized, else \c true.
452 FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
454 /** Set the number of channels to be encoded.
457 * \param encoder An encoder instance to set.
458 * \param value See above.
460 * \code encoder != NULL \endcode
462 * \c false if the encoder is already initialized, else \c true.
464 FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
466 /** Set the number of channels to be encoded.
468 * \default \c NULL, 0
469 * \param encoder An encoder instance to set.
470 * \param value See above.
472 * \code encoder != NULL \endcode
474 * \c false if the encoder is already initialized, else \c true.
476 FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
478 /** Set the number of channels to be encoded.
480 * \default \c NULL; the callback is mandatory and must be set before initialization
481 * \param encoder An encoder instance to set.
482 * \param value See above.
484 * \code encoder != NULL \endcode
485 * \code value != NULL \endcode
487 * \c false if the encoder is already initialized, else \c true.
489 FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteStatus (*value)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data));
491 /** Set the number of channels to be encoded.
493 * \default \c NULL; the callback is mandatory and must be set before initialization
494 * \param encoder An encoder instance to set.
495 * \param value See above.
497 * \code encoder != NULL \endcode
498 * \code value != NULL \endcode
500 * \c false if the encoder is already initialized, else \c true.
502 FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, void (*value)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data));
504 /** Set the number of channels to be encoded.
507 * \param encoder An encoder instance to set.
508 * \param value See above.
510 * \code encoder != NULL \endcode
512 * \c false if the encoder is already initialized, else \c true.
514 FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value);
517 * Various "get" methods
519 FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
520 FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
521 FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
522 FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
523 unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
524 unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
525 unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
526 unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
527 unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
528 unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
529 FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
530 FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
531 FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
532 unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
533 unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
534 unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
537 * Initialize the instance; should be called after construction and
538 * 'set' calls but before any of the 'process' calls. Will set and
539 * return the encoder state, which will be FLAC__STREAM_ENCODER_OK
540 * if initialization succeeded.
542 FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder);
545 * Flush the encoding buffer, release resources, and return the encoder
546 * state to FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can
547 * generate one or more write_callback()s before returning.
549 void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
552 * Methods for encoding the data
554 FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
555 FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);