1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * - Neither the name of the Xiph.org Foundation nor the names of its
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 #ifndef FLAC__STREAM_ENCODER_H
33 #define FLAC__STREAM_ENCODER_H
35 #include <stdio.h> /* for FILE */
38 #include "stream_decoder.h"
45 /** \file include/FLAC/stream_encoder.h
48 * This module contains the functions which implement the stream
51 * See the detailed documentation in the
52 * \link flac_stream_encoder stream encoder \endlink module.
55 /** \defgroup flac_encoder FLAC/ *_encoder.h: encoder interfaces
59 * This module describes the encoder layers provided by libFLAC.
61 * The stream encoder can be used encode complete streams either to the
62 * client via callbacks, or directly to a file, depending on how it is
63 * initialized. When encoding via callbacks, the client provides a write
64 * callback which will be called whenever FLAC data is ready to be written.
65 * If the client also supplies a seek callback, the encoder will also
66 * automatically handle the writing back of metadata discovered while
67 * encoding, like stream info, seek points offsets, etc. When encoding to
68 * a file, the client needs only supply a filename or open \c FILE* and an
69 * optional progress callback for periodic notification of progress; the
70 * write and seek callbacks are supplied internally. For more info see the
71 * \link flac_stream_encoder stream encoder \endlink module.
74 /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
75 * \ingroup flac_encoder
78 * This module contains the functions which implement the stream
81 * The basic usage of this encoder is as follows:
82 * - The program creates an instance of an encoder using
83 * FLAC__stream_encoder_new().
84 * - The program overrides the default settings using
85 * FLAC__stream_encoder_set_*() functions.
86 * - The program initializes the instance to validate the settings and
87 * prepare for encoding using FLAC__stream_encoder_init_stream() or
88 * FLAC__stream_encoder_init_FILE() or FLAC__stream_encoder_init_file(),
89 * depending on the nature of the output.
90 * - The program calls FLAC__stream_encoder_process() or
91 * FLAC__stream_encoder_process_interleaved() to encode data, which
92 * subsequently calls the callbacks when there is encoder data ready
94 * - The program finishes the encoding with FLAC__stream_encoder_finish(),
95 * which causes the encoder to encode any data still in its input pipe,
96 * update the metadata with the final encoding statistics if output
97 * seeking is possible, and finally reset the encoder to the
98 * uninitialized state.
99 * - The instance may be used again or deleted with
100 * FLAC__stream_encoder_delete().
102 * In more detail, the stream encoder functions similarly to the
103 * \link flac_stream_decoder stream decoder \endlink, but has fewer
104 * callbacks and more options. Typically the user will create a new
105 * instance by calling FLAC__stream_encoder_new(), then set the necessary
106 * parameters with FLAC__stream_encoder_set_*(), and initialize it by
107 * calling FLAC__stream_encoder_init_stream() or
108 * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
110 * Unlike the decoders, the stream encoder has many options that can
111 * affect the speed and compression ratio. When setting these parameters
112 * you should have some basic knowledge of the format (see the
113 * <A HREF="../documentation.html#format">user-level documentation</A>
114 * or the <A HREF="../format.html">formal description</A>). The
115 * FLAC__stream_encoder_set_*() functions themselves do not validate the
116 * values as many are interdependent. The FLAC__stream_encoder_init_*()
117 * functions will do this, so make sure to pay attention to the state
118 * returned by FLAC__stream_encoder_init_*() to make sure that it is
119 * FLAC__STREAM_ENCODER_INIT_STATUS_OK. Any parameters that are not set
120 * before FLAC__stream_encoder_init_*() will take on the defaults from
123 * There are three initialization functions, one for setting up the encoder
124 * to encode FLAC data to the client via callbacks, and two for encoding
125 * directly to a file.
127 * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
128 * You must also supply a write callback which will be called anytime
129 * there is raw encoded data to write. If the client can seek the output
130 * it is best to also supply seek and tell callbacks, as this allows the
131 * encoder to go back after encoding is finished to write back
132 * information that was collected while encoding, like seek point offsets,
135 * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
136 * or FLAC__stream_encoder_init_file(). Then you must only supply a
137 * filename or open \c FILE*; the encoder will handle all the callbacks
138 * internally. You may also supply a progress callback for periodic
139 * notification of the encoding progress.
141 * The call to FLAC__stream_encoder_init_*() currently will also immediately
142 * call the write callback several times, once with the \c fLaC signature,
143 * and once for each encoded metadata block.
145 * After initializing the instance, the user may feed audio data to the
146 * encoder in one of two ways:
148 * - Channel separate, through FLAC__stream_encoder_process() - The user
149 * will pass an array of pointers to buffers, one for each channel, to
150 * the encoder, each of the same length. The samples need not be
152 * - Channel interleaved, through
153 * FLAC__stream_encoder_process_interleaved() - The user will pass a single
154 * pointer to data that is channel-interleaved (i.e. channel0_sample0,
155 * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
156 * Again, the samples need not be block-aligned but they must be
157 * sample-aligned, i.e. the first value should be channel0_sample0 and
158 * the last value channelN_sampleM.
160 * When the user is finished encoding data, it calls
161 * FLAC__stream_encoder_finish(), which causes the encoder to encode any
162 * data still in its input pipe, and call the metadata callback with the
163 * final encoding statistics. Then the instance may be deleted with
164 * FLAC__stream_encoder_delete() or initialized again to encode another
167 * For programs that write their own metadata, but that do not know the
168 * actual metadata until after encoding, it is advantageous to instruct
169 * the encoder to write a PADDING block of the correct size, so that
170 * instead of rewriting the whole stream after encoding, the program can
171 * just overwrite the PADDING block. If only the maximum size of the
172 * metadata is known, the program can write a slightly larger padding
173 * block, then split it after encoding.
175 * Make sure you understand how lengths are calculated. All FLAC metadata
176 * blocks have a 4 byte header which contains the type and length. This
177 * length does not include the 4 bytes of the header. See the format page
178 * for the specification of metadata blocks and their lengths.
181 * If you are writing the FLAC data to a file via callbacks, make sure it
182 * is open for update (e.g. mode "w+" for stdio streams). This is because
183 * after the first encoding pass, the encoder will try to seek back to the
184 * beginning of the stream, to the STREAMINFO block, to write some data
185 * there. (If using FLAC__stream_encoder_init_file() or
186 * FLAC__stream_encoder_init_FILE(), the file is managed internally.)
189 * The "set" functions may only be called when the encoder is in the
190 * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
191 * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
192 * before FLAC__stream_encoder_init(). If this is the case they will
193 * return \c true, otherwise \c false.
196 * FLAC__stream_encoder_finish() resets all settings to the constructor
203 /** State values for a FLAC__StreamEncoder.
205 * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
207 * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
208 * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
209 * must be deleted with FLAC__stream_encoder_delete().
213 FLAC__STREAM_ENCODER_OK = 0,
214 /**< The encoder is in the normal OK state and samples can be processed. */
216 FLAC__STREAM_ENCODER_UNINITIALIZED,
217 /**< The encoder is in the uninitialized state; one of the
218 * FLAC__stream_encoder_init_*() functions must be called before samples
222 FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
223 /**< An error occurred in the underlying verify stream decoder;
224 * check FLAC__stream_encoder_get_verify_decoder_state().
227 FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
228 /**< The verify decoder detected a mismatch between the original
229 * audio signal and the decoded audio signal.
232 FLAC__STREAM_ENCODER_CLIENT_ERROR,
233 /**< One of the callbacks returned a fatal error. */
235 FLAC__STREAM_ENCODER_IO_ERROR,
236 /**< An I/O error occurred while opening/reading/writing a file.
240 FLAC__STREAM_ENCODER_FRAMING_ERROR,
241 /**< An error occurred while writing the stream; usually, the
242 * write_callback returned an error.
245 FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
246 /**< Memory allocation failed. */
248 } FLAC__StreamEncoderState;
250 /** Maps a FLAC__StreamEncoderState to a C string.
252 * Using a FLAC__StreamEncoderState as the index to this array
253 * will give the string equivalent. The contents should not be modified.
255 extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
257 /** Possible return values for the FLAC__stream_encoder_init_*() functions.
261 FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
262 /**< Initialization was successful. */
264 FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
265 /**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
267 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
268 /**< A required callback was not supplied. */
270 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
271 /**< The encoder has an invalid setting for number of channels. */
273 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
274 /**< The encoder has an invalid setting for bits-per-sample.
275 * FLAC supports 4-32 bps but the reference encoder currently supports
279 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
280 /**< The encoder has an invalid setting for the input sample rate. */
282 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
283 /**< The encoder has an invalid setting for the block size. */
285 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
286 /**< The encoder has an invalid setting for the maximum LPC order. */
288 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
289 /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
291 FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_CHANNELS_MISMATCH,
292 /**< Mid/side coding was specified but the number of channels is not equal to 2. */
294 FLAC__STREAM_ENCODER_INIT_STATUS_ILLEGAL_MID_SIDE_FORCE,
295 /**< Loose mid/side coding was specified but mid/side coding was not. */
297 FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
298 /**< The specified block size is less than the maximum LPC order. */
300 FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
301 /**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
303 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
304 /**< The metadata input to the encoder is invalid, in one of the following ways:
305 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
306 * - One of the metadata blocks contains an undefined type
307 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
308 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
309 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
312 FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
313 /**< FLAC__stream_encoder_init_*() was called when the encoder was
314 * already initialized, usually because
315 * FLAC__stream_encoder_finish() was not called.
318 } FLAC__StreamEncoderInitStatus;
320 /** Maps a FLAC__StreamEncoderInitStatus to a C string.
322 * Using a FLAC__StreamEncoderInitStatus as the index to this array
323 * will give the string equivalent. The contents should not be modified.
325 extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
327 /** Return values for the FLAC__StreamEncoder write callback.
331 FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
332 /**< The write was OK and encoding can continue. */
334 FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
335 /**< An unrecoverable error occurred. The encoder will return from the process call. */
337 } FLAC__StreamEncoderWriteStatus;
339 /** Maps a FLAC__StreamEncoderWriteStatus to a C string.
341 * Using a FLAC__StreamEncoderWriteStatus as the index to this array
342 * will give the string equivalent. The contents should not be modified.
344 extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
346 /** Return values for the FLAC__StreamEncoder seek callback.
350 FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
351 /**< The seek was OK and encoding can continue. */
353 FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
354 /**< An unrecoverable error occurred. */
356 FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
357 /**< Client does not support seeking. */
359 } FLAC__StreamEncoderSeekStatus;
361 /** Maps a FLAC__StreamEncoderSeekStatus to a C string.
363 * Using a FLAC__StreamEncoderSeekStatus as the index to this array
364 * will give the string equivalent. The contents should not be modified.
366 extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
369 /** Return values for the FLAC__StreamEncoder tell callback.
373 FLAC__STREAM_ENCODER_TELL_STATUS_OK,
374 /**< The tell was OK and encoding can continue. */
376 FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
377 /**< An unrecoverable error occurred. */
379 FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
380 /**< Client does not support seeking. */
382 } FLAC__StreamEncoderTellStatus;
384 /** Maps a FLAC__StreamEncoderTellStatus to a C string.
386 * Using a FLAC__StreamEncoderTellStatus as the index to this array
387 * will give the string equivalent. The contents should not be modified.
389 extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
392 /***********************************************************************
394 * class FLAC__StreamEncoder
396 ***********************************************************************/
398 struct FLAC__StreamEncoderProtected;
399 struct FLAC__StreamEncoderPrivate;
400 /** The opaque structure definition for the stream encoder type.
401 * See the \link flac_stream_encoder stream encoder module \endlink
402 * for a detailed description.
405 struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
406 struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
407 } FLAC__StreamEncoder;
409 /** Signature for the write callback.
411 * A function pointer matching this signature must be passed to
412 * FLAC__stream_encoder_init_stream(). The supplied function will be called
413 * by the encoder anytime there is raw encoded data ready to write. It may
414 * include metadata mixed with encoded audio frames and the data is not
415 * guaranteed to be aligned on frame or metadata block boundaries.
417 * The only duty of the callback is to write out the \a bytes worth of data
418 * in \a buffer to the current position in the output stream. The arguments
419 * \a samples and \a current_frame are purely informational. If \a samples
420 * is greater than \c 0, then \a current_frame will hold the current frame
421 * number that is being written; otherwise it indicates that the write
422 * callback is being called to write metadata.
424 * \note In general, FLAC__StreamEncoder functions which change the
425 * state should not be called on the \a encoder while in the callback.
427 * \param encoder The encoder instance calling the callback.
428 * \param buffer An array of encoded data of length \a bytes.
429 * \param bytes The byte length of \a buffer.
430 * \param samples The number of samples encoded by \a buffer.
431 * \c 0 has a special meaning; see above.
432 * \param current_frame The number of the current frame being encoded.
433 * \param client_data The callee's client data set through
434 * FLAC__stream_encoder_init_*().
435 * \retval FLAC__StreamEncoderWriteStatus
436 * The callee's return status.
438 typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
440 /** Signature for the seek callback.
442 * A function pointer matching this signature may be passed to
443 * FLAC__stream_encoder_init_stream(). The supplied function will be called
444 * when the encoder needs to seek the output stream. The encoder will pass
445 * the absolute byte offset to seek to, 0 meaning the beginning of the stream.
447 * \note In general, FLAC__StreamEncoder functions which change the
448 * state should not be called on the \a encoder while in the callback.
450 * \param encoder The encoder instance calling the callback.
451 * \param absolute_byte_offset The offset from the beginning of the stream
453 * \param client_data The callee's client data set through
454 * FLAC__stream_encoder_init_*().
455 * \retval FLAC__StreamEncoderSeekStatus
456 * The callee's return status.
458 typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
460 /** Signature for the tell callback.
462 * A function pointer matching this signature may be passed to
463 * FLAC__stream_encoder_init_stream(). The supplied function will be called
464 * when the encoder needs to know the current position of the output stream.
467 * The callback must return the true current byte offset of the output to
468 * which the encoder is writing. If you are buffering the output, make
469 * sure and take this into account. If you are writing directly to a
470 * FILE* from your write callback, ftell() is sufficient. If you are
471 * writing directly to a file descriptor from your write callback, you
472 * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
473 * these points to rewrite metadata after encoding.
475 * \note In general, FLAC__StreamEncoder functions which change the
476 * state should not be called on the \a encoder while in the callback.
478 * \param encoder The encoder instance calling the callback.
479 * \param absolute_byte_offset The address at which to store the current
480 * position of the output.
481 * \param client_data The callee's client data set through
482 * FLAC__stream_encoder_init_*().
483 * \retval FLAC__StreamEncoderTellStatus
484 * The callee's return status.
486 typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
488 /** Signature for the metadata callback.
490 * A function pointer matching this signature may be passed to
491 * FLAC__stream_encoder_init_stream(). The supplied function will be called
492 * once at the end of encoding with the populated STREAMINFO structure. This
493 * is so the client can seek back to the beginning of the file and write the
494 * STREAMINFO block with the correct statistics after encoding (like
495 * minimum/maximum frame size and total samples).
497 * \note In general, FLAC__StreamEncoder functions which change the
498 * state should not be called on the \a encoder while in the callback.
500 * \param encoder The encoder instance calling the callback.
501 * \param metadata The final populated STREAMINFO block.
502 * \param client_data The callee's client data set through
503 * FLAC__stream_encoder_init_*().
505 typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
507 /** Signature for the progress callback.
509 * A function pointer matching this signature may be passed to
510 * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
511 * The supplied function will be called when the encoder has finished
512 * writing a frame. The \c total_frames_estimate argument to the
513 * callback will be based on the value from
514 * FLAC__file_encoder_set_total_samples_estimate().
516 * \note In general, FLAC__StreamEncoder functions which change the
517 * state should not be called on the \a encoder while in the callback.
519 * \param encoder The encoder instance calling the callback.
520 * \param bytes_written Bytes written so far.
521 * \param samples_written Samples written so far.
522 * \param frames_written Frames written so far.
523 * \param total_frames_estimate The estimate of the total number of
524 * frames to be written.
525 * \param client_data The callee's client data set through
526 * FLAC__stream_encoder_init_*().
528 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);
531 /***********************************************************************
533 * Class constructor/destructor
535 ***********************************************************************/
537 /** Create a new stream encoder instance. The instance is created with
538 * default settings; see the individual FLAC__stream_encoder_set_*()
539 * functions for each setting's default.
541 * \retval FLAC__StreamEncoder*
542 * \c NULL if there was an error allocating memory, else the new instance.
544 FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new();
546 /** Free an encoder instance. Deletes the object pointed to by \a encoder.
548 * \param encoder A pointer to an existing encoder.
550 * \code encoder != NULL \endcode
552 FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
555 /***********************************************************************
557 * Public class method prototypes
559 ***********************************************************************/
561 /** Set the "verify" flag. If \c true, the encoder will verify it's own
562 * encoded output by feeding it through an internal decoder and comparing
563 * the original signal against the decoded signal. If a mismatch occurs,
564 * the process call will return \c false. Note that this will slow the
565 * encoding process by the extra time required for decoding and comparison.
568 * \param encoder An encoder instance to set.
569 * \param value Flag value (see above).
571 * \code encoder != NULL \endcode
573 * \c false if the encoder is already initialized, else \c true.
575 FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
577 /** Set the <A HREF="../format.html#subset">Subset</A> flag. If \c true,
578 * the encoder will comply with the Subset and will check the
579 * settings during FLAC__stream_encoder_init() to see if all settings
580 * comply. If \c false, the settings may take advantage of the full
581 * range that the format allows.
583 * Make sure you know what it entails before setting this to \c false.
586 * \param encoder An encoder instance to set.
587 * \param value Flag value (see above).
589 * \code encoder != NULL \endcode
591 * \c false if the encoder is already initialized, else \c true.
593 FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
595 /** Set to \c true to enable mid-side encoding on stereo input. The
596 * number of channels must be 2. Set to \c false to use only
597 * independent channel coding.
600 * \param encoder An encoder instance to set.
601 * \param value Flag value (see above).
603 * \code encoder != NULL \endcode
605 * \c false if the encoder is already initialized, else \c true.
607 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
609 /** Set to \c true to enable adaptive switching between mid-side and
610 * left-right encoding on stereo input. The number of channels must
611 * be 2. Set to \c false to use exhaustive searching. In either
612 * case, the mid/side stereo setting must be \c true.
615 * \param encoder An encoder instance to set.
616 * \param value Flag value (see above).
618 * \code encoder != NULL \endcode
620 * \c false if the encoder is already initialized, else \c true.
622 FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
624 /** Set the number of channels to be encoded.
627 * \param encoder An encoder instance to set.
628 * \param value See above.
630 * \code encoder != NULL \endcode
632 * \c false if the encoder is already initialized, else \c true.
634 FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
636 /** Set the sample resolution of the input to be encoded.
639 * Do not feed the encoder data that is wider than the value you
640 * set here or you will generate an invalid stream.
643 * \param encoder An encoder instance to set.
644 * \param value See above.
646 * \code encoder != NULL \endcode
648 * \c false if the encoder is already initialized, else \c true.
650 FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
652 /** Set the sample rate (in Hz) of the input to be encoded.
655 * \param encoder An encoder instance to set.
656 * \param value See above.
658 * \code encoder != NULL \endcode
660 * \c false if the encoder is already initialized, else \c true.
662 FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
664 /** Set the blocksize to use while encoding.
667 * \param encoder An encoder instance to set.
668 * \param value See above.
670 * \code encoder != NULL \endcode
672 * \c false if the encoder is already initialized, else \c true.
674 FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
676 /** Sets the apodization function(s) the encoder will use when windowing
677 * audio data for LPC analysis.
679 * The \a specification is a plain ASCII string which specifies exactly
680 * which functions to use. There may be more than one (up to 32),
681 * separated by \c ';' characters. Some functions take one or more
682 * comma-separated arguments in parentheses.
684 * The available functions are \c bartlett, \c bartlett_hann,
685 * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
686 * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
687 * \c rectangle, \c triangle, \c tukey(P), \c welch.
689 * For \c gauss(STDDEV), STDDEV specifies the standard deviation
692 * For \c tukey(P), P specifies the fraction of the window that is
693 * tapered (0<=P<=1). P=0 corresponds to \c rectangle and P=1
694 * corresponds to \c hann.
696 * Example specifications are \c "blackman" or
697 * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
699 * Any function that is specified erroneously is silently dropped. Up
700 * to 32 functions are kept, the rest are dropped. If the specification
701 * is empty the encoder defaults to \c "tukey(0.5)".
703 * When more than one function is specified, then for every subframe the
704 * encoder will try each of them separately and choose the window that
705 * results in the smallest compressed subframe.
707 * Note that each function specified causes the encoder to occupy a
708 * floating point array in which to store the window.
710 * \default \c "tukey(0.5)"
711 * \param encoder An encoder instance to set.
712 * \param specification See above.
714 * \code encoder != NULL \endcode
715 * \code specification != NULL \endcode
717 * \c false if the encoder is already initialized, else \c true.
719 /* @@@@add to unit tests*/
720 FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
722 /** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
725 * \param encoder An encoder instance to set.
726 * \param value See above.
728 * \code encoder != NULL \endcode
730 * \c false if the encoder is already initialized, else \c true.
732 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
734 /** Set the precision, in bits, of the quantized linear predictor
735 * coefficients, or \c 0 to let the encoder select it based on the
739 * In the current implementation, qlp_coeff_precision + bits_per_sample must
743 * \param encoder An encoder instance to set.
744 * \param value See above.
746 * \code encoder != NULL \endcode
748 * \c false if the encoder is already initialized, else \c true.
750 FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
752 /** Set to \c false to use only the specified quantized linear predictor
753 * coefficient precision, or \c true to search neighboring precision
754 * values and use the best one.
757 * \param encoder An encoder instance to set.
758 * \param value See above.
760 * \code encoder != NULL \endcode
762 * \c false if the encoder is already initialized, else \c true.
764 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
766 /** Deprecated. Setting this value has no effect.
769 * \param encoder An encoder instance to set.
770 * \param value See above.
772 * \code encoder != NULL \endcode
774 * \c false if the encoder is already initialized, else \c true.
776 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
778 /** Set to \c false to let the encoder estimate the best model order
779 * based on the residual signal energy, or \c true to force the
780 * encoder to evaluate all order models and select the best.
783 * \param encoder An encoder instance to set.
784 * \param value See above.
786 * \code encoder != NULL \endcode
788 * \c false if the encoder is already initialized, else \c true.
790 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
792 /** Set the minimum partition order to search when coding the residual.
793 * This is used in tandem with
794 * FLAC__stream_encoder_set_max_residual_partition_order().
796 * The partition order determines the context size in the residual.
797 * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
799 * Set both min and max values to \c 0 to force a single context,
800 * whose Rice parameter is based on the residual signal variance.
801 * Otherwise, set a min and max order, and the encoder will search
802 * all orders, using the mean of each context for its Rice parameter,
806 * \param encoder An encoder instance to set.
807 * \param value See above.
809 * \code encoder != NULL \endcode
811 * \c false if the encoder is already initialized, else \c true.
813 FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
815 /** Set the maximum partition order to search when coding the residual.
816 * This is used in tandem with
817 * FLAC__stream_encoder_set_min_residual_partition_order().
819 * The partition order determines the context size in the residual.
820 * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
822 * Set both min and max values to \c 0 to force a single context,
823 * whose Rice parameter is based on the residual signal variance.
824 * Otherwise, set a min and max order, and the encoder will search
825 * all orders, using the mean of each context for its Rice parameter,
829 * \param encoder An encoder instance to set.
830 * \param value See above.
832 * \code encoder != NULL \endcode
834 * \c false if the encoder is already initialized, else \c true.
836 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
838 /** Deprecated. Setting this value has no effect.
841 * \param encoder An encoder instance to set.
842 * \param value See above.
844 * \code encoder != NULL \endcode
846 * \c false if the encoder is already initialized, else \c true.
848 FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
850 /** Set an estimate of the total samples that will be encoded.
851 * This is merely an estimate and may be set to \c 0 if unknown.
852 * This value will be written to the STREAMINFO block before encoding,
853 * and can remove the need for the caller to rewrite the value later
854 * if the value is known before encoding.
857 * \param encoder An encoder instance to set.
858 * \param value See above.
860 * \code encoder != NULL \endcode
862 * \c false if the encoder is already initialized, else \c true.
864 FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
866 /** Set the metadata blocks to be emitted to the stream before encoding.
867 * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
868 * array of pointers to metadata blocks. The array is non-const since
869 * the encoder may need to change the \a is_last flag inside them, and
870 * in some cases update seek point offsets. Otherwise, the encoder will
871 * not modify or free the blocks. It is up to the caller to free the
872 * metadata blocks after encoding.
875 * The encoder stores only the \a metadata pointer; the passed-in array
876 * must survive at least until after FLAC__stream_encoder_init() returns.
877 * Do not modify the array or free the blocks until then.
880 * The STREAMINFO block is always written and no STREAMINFO block may
881 * occur in the supplied array.
884 * By default the encoder does not create a SEEKTABLE. If one is supplied
885 * in the \a metadata array, but the client has specified that it does not
886 * support seeking, then the SEEKTABLE will be written verbatim. However
887 * by itself this is not very useful as the client will not know the stream
888 * offsets for the seekpoints ahead of time. In order to get a proper
889 * seektable the client must support seeking. See next note.
892 * SEEKTABLE blocks are handled specially. Since you will not know
893 * the values for the seek point stream offsets, you should pass in
894 * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
895 * required sample numbers (or placeholder points), with \c 0 for the
896 * \a frame_samples and \a stream_offset fields for each point. If the
897 * client has specified that it supports seeking by providing a seek
898 * callback to FLAC__stream_encoder_init_stream() (or by using
899 * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE()),
900 * then while it is encoding the encoder will fill the stream offsets in
901 * for you and when encoding is finished, it will seek back and write the
902 * real values into the SEEKTABLE block in the stream. There are helper
903 * routines for manipulating seektable template blocks; see metadata.h:
904 * FLAC__metadata_object_seektable_template_*(). If the client does
905 * not support seeking, the SEEKTABLE will have inaccurate offsets which
906 * will slow down or remove the ability to seek in the FLAC stream.
909 * The encoder instance \b will modify the first \c SEEKTABLE block
910 * as it transforms the template to a valid seektable while encoding,
911 * but it is still up to the caller to free all metadata blocks after
915 * A VORBIS_COMMENT block may be supplied. The vendor string in it
916 * will be ignored. libFLAC will use it's own vendor string. libFLAC
917 * will not modify the passed-in VORBIS_COMMENT's vendor string, it
918 * will simply write it's own into the stream. If no VORBIS_COMMENT
919 * block is present in the \a metadata array, libFLAC will write an
920 * empty one, containing only the vendor string.
922 * \default \c NULL, 0
923 * \param encoder An encoder instance to set.
924 * \param metadata See above.
925 * \param num_blocks See above.
927 * \code encoder != NULL \endcode
929 * \c false if the encoder is already initialized, else \c true.
931 FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
933 /** Get the current encoder state.
935 * \param encoder An encoder instance to query.
937 * \code encoder != NULL \endcode
938 * \retval FLAC__StreamEncoderState
939 * The current encoder state.
941 FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
943 /** Get the state of the verify stream decoder.
944 * Useful when the stream encoder state is
945 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
947 * \param encoder An encoder instance to query.
949 * \code encoder != NULL \endcode
950 * \retval FLAC__StreamDecoderState
951 * The verify stream decoder state.
953 FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
955 /** Get the current encoder state as a C string.
956 * This version automatically resolves
957 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
958 * verify decoder's state.
960 * \param encoder A encoder instance to query.
962 * \code encoder != NULL \endcode
963 * \retval const char *
964 * The encoder state as a C string. Do not modify the contents.
966 FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
968 /** Get relevant values about the nature of a verify decoder error.
969 * Useful when the stream encoder state is
970 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should
971 * be addresses in which the stats will be returned, or NULL if value
974 * \param encoder An encoder instance to query.
975 * \param absolute_sample The absolute sample number of the mismatch.
976 * \param frame_number The number of the frame in which the mismatch occurred.
977 * \param channel The channel in which the mismatch occurred.
978 * \param sample The number of the sample (relative to the frame) in
979 * which the mismatch occurred.
980 * \param expected The expected value for the sample in question.
981 * \param got The actual value returned by the decoder.
983 * \code encoder != NULL \endcode
985 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);
987 /** Get the "verify" flag.
989 * \param encoder An encoder instance to query.
991 * \code encoder != NULL \endcode
993 * See FLAC__stream_encoder_set_verify().
995 FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
997 /** Get the <A HREF="../format.html#subset>Subset</A> flag.
999 * \param encoder An encoder instance to query.
1001 * \code encoder != NULL \endcode
1002 * \retval FLAC__bool
1003 * See FLAC__stream_encoder_set_streamable_subset().
1005 FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
1007 /** Get the "mid/side stereo coding" flag.
1009 * \param encoder An encoder instance to query.
1011 * \code encoder != NULL \endcode
1012 * \retval FLAC__bool
1013 * See FLAC__stream_encoder_get_do_mid_side_stereo().
1015 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
1017 /** Get the "adaptive mid/side switching" flag.
1019 * \param encoder An encoder instance to query.
1021 * \code encoder != NULL \endcode
1022 * \retval FLAC__bool
1023 * See FLAC__stream_encoder_set_loose_mid_side_stereo().
1025 FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
1027 /** Get the number of input channels being processed.
1029 * \param encoder An encoder instance to query.
1031 * \code encoder != NULL \endcode
1033 * See FLAC__stream_encoder_set_channels().
1035 FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
1037 /** Get the input sample resolution setting.
1039 * \param encoder An encoder instance to query.
1041 * \code encoder != NULL \endcode
1043 * See FLAC__stream_encoder_set_bits_per_sample().
1045 FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
1047 /** Get the input sample rate setting.
1049 * \param encoder An encoder instance to query.
1051 * \code encoder != NULL \endcode
1053 * See FLAC__stream_encoder_set_sample_rate().
1055 FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
1057 /** Get the blocksize setting.
1059 * \param encoder An encoder instance to query.
1061 * \code encoder != NULL \endcode
1063 * See FLAC__stream_encoder_set_blocksize().
1065 FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
1067 /** Get the maximum LPC order setting.
1069 * \param encoder An encoder instance to query.
1071 * \code encoder != NULL \endcode
1073 * See FLAC__stream_encoder_set_max_lpc_order().
1075 FLAC_API unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
1077 /** Get the quantized linear predictor coefficient precision setting.
1079 * \param encoder An encoder instance to query.
1081 * \code encoder != NULL \endcode
1083 * See FLAC__stream_encoder_set_qlp_coeff_precision().
1085 FLAC_API unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
1087 /** Get the qlp coefficient precision search flag.
1089 * \param encoder An encoder instance to query.
1091 * \code encoder != NULL \endcode
1092 * \retval FLAC__bool
1093 * See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
1095 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
1097 /** Get the "escape coding" flag.
1099 * \param encoder An encoder instance to query.
1101 * \code encoder != NULL \endcode
1102 * \retval FLAC__bool
1103 * See FLAC__stream_encoder_set_do_escape_coding().
1105 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
1107 /** Get the exhaustive model search flag.
1109 * \param encoder An encoder instance to query.
1111 * \code encoder != NULL \endcode
1112 * \retval FLAC__bool
1113 * See FLAC__stream_encoder_set_do_exhaustive_model_search().
1115 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
1117 /** Get the minimum residual partition order setting.
1119 * \param encoder An encoder instance to query.
1121 * \code encoder != NULL \endcode
1123 * See FLAC__stream_encoder_set_min_residual_partition_order().
1125 FLAC_API unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
1127 /** Get maximum residual partition order setting.
1129 * \param encoder An encoder instance to query.
1131 * \code encoder != NULL \endcode
1133 * See FLAC__stream_encoder_set_max_residual_partition_order().
1135 FLAC_API unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
1137 /** Get the Rice parameter search distance setting.
1139 * \param encoder An encoder instance to query.
1141 * \code encoder != NULL \endcode
1143 * See FLAC__stream_encoder_set_rice_parameter_search_dist().
1145 FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
1147 /** Get the previously set estimate of the total samples to be encoded.
1148 * The encoder merely mimics back the value given to
1149 * FLAC__stream_encoder_set_total_samples_estimate() since it has no
1150 * other way of knowing how many samples the user will encode.
1152 * \param encoder An encoder instance to set.
1154 * \code encoder != NULL \endcode
1155 * \retval FLAC__uint64
1156 * See FLAC__stream_encoder_get_total_samples_estimate().
1158 FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
1160 /** Initialize the encoder instance.
1162 * This flavor of initialization sets up the encoder to encode to a stream.
1163 * I/O is performed via callbacks to the client. For encoding to a plain file
1164 * via filename or open \c FILE*, FLAC__stream_encoder_init_file() and
1165 * FLAC__stream_encoder_init_FILE() provide a simpler interface.
1167 * This function should be called after FLAC__stream_encoder_new() and
1168 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1169 * or FLAC__stream_encoder_process_interleaved().
1170 * initialization succeeded.
1172 * The call to FLAC__stream_encoder_init_stream() currently will also immediately
1173 * call the write callback several times, once with the \c fLaC signature,
1174 * and once for each encoded metadata block.
1176 * \param encoder An uninitialized encoder instance.
1177 * \param write_callback See FLAC__StreamEncoderWriteCallback. This
1178 * pointer must not be \c NULL.
1179 * \param seek_callback See FLAC__StreamEncoderSeekCallback. This
1180 * pointer may be \c NULL if seeking is not
1181 * supported. The encoder uses seeking to go back
1182 * and write some some stream statistics to the
1183 * STREAMINFO block; this is recommended but not
1184 * necessary to create a valid FLAC stream. If
1185 * \a seek_callback is not \c NULL then a
1186 * \a tell_callback must also be supplied.
1187 * Alternatively, a dummy seek callback that just
1188 * returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
1189 * may also be supplied, all though this is slightly
1190 * less efficient for the decoder.
1191 * \param tell_callback See FLAC__StreamEncoderTellCallback. This
1192 * pointer may be \c NULL if seeking is not
1193 * supported. If \a seek_callback is \c NULL then
1194 * this argument will be ignored. If
1195 * \a seek_callback is not \c NULL then a
1196 * \a tell_callback must also be supplied.
1197 * Alternatively, a dummy tell callback that just
1198 * returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
1199 * may also be supplied, all though this is slightly
1200 * less efficient for the decoder.
1201 * \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
1202 * pointer may be \c NULL if the callback is not
1203 * desired. If the client provides a seek callback,
1204 * this function is not necessary as the encoder
1205 * will automatically seek back and update the
1206 * STREAMINFO block. It may also be \c NULL if the
1207 * client does not support seeking, since it will
1208 * have no way of going back to update the
1209 * STREAMINFO. However the client can still supply
1210 * a callback if it would like to know the details
1211 * from the STREAMINFO.
1212 * \param client_data This value will be supplied to callbacks in their
1213 * \a client_data argument.
1215 * \code encoder != NULL \endcode
1216 * \retval FLAC__StreamEncoderInitStatus
1217 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1218 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1220 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);
1222 /** Initialize the encoder instance.
1224 * This flavor of initialization sets up the encoder to encode to a plain
1225 * file. For non-stdio streams, you must use
1226 * FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
1228 * This function should be called after FLAC__stream_encoder_new() and
1229 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1230 * or FLAC__stream_encoder_process_interleaved().
1231 * initialization succeeded.
1233 * The call to FLAC__stream_encoder_init_stream() currently will also immediately
1234 * call the write callback several times, once with the \c fLaC signature,
1235 * and once for each encoded metadata block.
1237 * \param encoder An uninitialized encoder instance.
1238 * \param file An open file. The file should have been opened
1239 * with mode \c "w+b" and rewound. The file
1240 * becomes owned by the encoder and should not be
1241 * manipulated by the client while encoding.
1242 * Unless \a file is \c stdout, it will be closed
1243 * when FLAC__stream_encoder_finish() is called.
1244 * Note however that a proper SEEKTABLE cannot be
1245 * created when encoding to \c stdout since it is
1247 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1248 * pointer may be \c NULL if the callback is not
1250 * \param client_data This value will be supplied to callbacks in their
1251 * \a client_data argument.
1253 * \code encoder != NULL \endcode
1254 * \code file != NULL \endcode
1255 * \retval FLAC__StreamEncoderInitStatus
1256 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1257 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1259 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1261 /** Initialize the encoder instance.
1263 * This flavor of initialization sets up the encoder to encode to a plain
1264 * file. If POSIX fopen() semantics are not sufficient (for example,
1265 * with Unicode filenames on Windows), you must use
1266 * FLAC__stream_encodeR_init_FILE(), or FLAC__stream_encoder_init_stream()
1267 * and provide callbacks for the I/O.
1269 * This function should be called after FLAC__stream_encoder_new() and
1270 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1271 * or FLAC__stream_encoder_process_interleaved().
1272 * initialization succeeded.
1274 * The call to FLAC__stream_encoder_init_stream() currently will also immediately
1275 * call the write callback several times, once with the \c fLaC signature,
1276 * and once for each encoded metadata block.
1278 * \param encoder An uninitialized encoder instance.
1279 * \param filename The name of the file to encode to. The file will
1280 * be opened with fopen(). Use \c NULL to encode to
1281 * \c stdout. Note however that a proper SEEKTABLE
1282 * cannot be created when encoding to \c stdout since
1283 * it is not seekable.
1284 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1285 * pointer may be \c NULL if the callback is not
1287 * \param client_data This value will be supplied to callbacks in their
1288 * \a client_data argument.
1290 * \code encoder != NULL \endcode
1291 * \retval FLAC__StreamEncoderInitStatus
1292 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1293 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1295 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1297 /** Finish the encoding process.
1298 * Flushes the encoding buffer, releases resources, resets the encoder
1299 * settings to their defaults, and returns the encoder state to
1300 * FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
1301 * one or more write callbacks before returning, and will generate
1302 * a metadata callback.
1304 * In the event of a prematurely-terminated encode, it is not strictly
1305 * necessary to call this immediately before FLAC__stream_encoder_delete()
1306 * but it is good practice to match every FLAC__stream_encoder_init()
1307 * with a FLAC__stream_encoder_finish().
1309 * \param encoder An uninitialized encoder instance.
1311 * \code encoder != NULL \endcode
1313 FLAC_API void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
1315 /** Submit data for encoding.
1316 * This version allows you to supply the input data via an array of
1317 * pointers, each pointer pointing to an array of \a samples samples
1318 * representing one channel. The samples need not be block-aligned,
1319 * but each channel should have the same number of samples.
1321 * For applications where channel order is important, channels must
1322 * follow the order as described in the
1323 * <A HREF="../format.html#frame_header">frame header</A>.
1325 * \param encoder An initialized encoder instance in the OK state.
1326 * \param buffer An array of pointers to each channel's signal.
1327 * \param samples The number of samples in one channel.
1329 * \code encoder != NULL \endcode
1330 * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
1331 * \retval FLAC__bool
1332 * \c true if successful, else \c false; in this case, check the
1333 * encoder state with FLAC__stream_encoder_get_state() to see what
1336 FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
1338 /** Submit data for encoding.
1339 * This version allows you to supply the input data where the channels
1340 * are interleaved into a single array (i.e. channel0_sample0,
1341 * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
1342 * The samples need not be block-aligned but they must be
1343 * sample-aligned, i.e. the first value should be channel0_sample0
1344 * and the last value channelN_sampleM.
1346 * For applications where channel order is important, channels must
1347 * follow the order as described in the
1348 * <A HREF="../format.html#frame_header">frame header</A>.
1350 * \param encoder An initialized encoder instance in the OK state.
1351 * \param buffer An array of channel-interleaved data (see above).
1352 * \param samples The number of samples in one channel, the same as for
1353 * FLAC__stream_encoder_process(). For example, if
1354 * encoding two channels, \c 1000 \a samples corresponds
1355 * to a \a buffer of 2000 values.
1357 * \code encoder != NULL \endcode
1358 * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
1359 * \retval FLAC__bool
1360 * \c true if successful, else \c false; in this case, check the
1361 * encoder state with FLAC__stream_encoder_get_state() to see what
1364 FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);