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_OGG_ERROR,
223 /**< An error occurred in the underlying Ogg layer. */
225 FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
226 /**< An error occurred in the underlying verify stream decoder;
227 * check FLAC__stream_encoder_get_verify_decoder_state().
230 FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
231 /**< The verify decoder detected a mismatch between the original
232 * audio signal and the decoded audio signal.
235 FLAC__STREAM_ENCODER_CLIENT_ERROR,
236 /**< One of the callbacks returned a fatal error. */
238 FLAC__STREAM_ENCODER_IO_ERROR,
239 /**< An I/O error occurred while opening/reading/writing a file.
243 FLAC__STREAM_ENCODER_FRAMING_ERROR,
244 /**< An error occurred while writing the stream; usually, the
245 * write_callback returned an error.
248 FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
249 /**< Memory allocation failed. */
251 } FLAC__StreamEncoderState;
253 /** Maps a FLAC__StreamEncoderState to a C string.
255 * Using a FLAC__StreamEncoderState as the index to this array
256 * will give the string equivalent. The contents should not be modified.
258 extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
261 /** Possible return values for the FLAC__stream_encoder_init_*() functions.
265 FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
266 /**< Initialization was successful. */
268 FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
269 /**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
271 FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
272 /**< The library was not compiled with support for the given container
276 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
277 /**< A required callback was not supplied. */
279 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
280 /**< The encoder has an invalid setting for number of channels. */
282 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
283 /**< The encoder has an invalid setting for bits-per-sample.
284 * FLAC supports 4-32 bps but the reference encoder currently supports
288 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
289 /**< The encoder has an invalid setting for the input sample rate. */
291 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
292 /**< The encoder has an invalid setting for the block size. */
294 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
295 /**< The encoder has an invalid setting for the maximum LPC order. */
297 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
298 /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
300 FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_CHANNELS_MISMATCH,
301 /**< Mid/side coding was specified but the number of channels is not equal to 2. */
303 FLAC__STREAM_ENCODER_INIT_STATUS_ILLEGAL_MID_SIDE_FORCE,
304 /**< Loose mid/side coding was specified but mid/side coding was not. */
306 FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
307 /**< The specified block size is less than the maximum LPC order. */
309 FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
310 /**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
312 FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
313 /**< The metadata input to the encoder is invalid, in one of the following ways:
314 * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
315 * - One of the metadata blocks contains an undefined type
316 * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
317 * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
318 * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
321 FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
322 /**< FLAC__stream_encoder_init_*() was called when the encoder was
323 * already initialized, usually because
324 * FLAC__stream_encoder_finish() was not called.
327 } FLAC__StreamEncoderInitStatus;
329 /** Maps a FLAC__StreamEncoderInitStatus to a C string.
331 * Using a FLAC__StreamEncoderInitStatus as the index to this array
332 * will give the string equivalent. The contents should not be modified.
334 extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
337 /** Return values for the FLAC__StreamEncoder read callback.
341 FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
342 /**< The read was OK and decoding can continue. */
344 FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
345 /**< The read was attempted at the end of the stream. */
347 FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
348 /**< An unrecoverable error occurred. */
350 FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
351 /**< Client does not support reading back from the output. */
353 } FLAC__StreamEncoderReadStatus;
355 /** Maps a FLAC__StreamEncoderReadStatus to a C string.
357 * Using a FLAC__StreamEncoderReadStatus as the index to this array
358 * will give the string equivalent. The contents should not be modified.
360 extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
363 /** Return values for the FLAC__StreamEncoder write callback.
367 FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
368 /**< The write was OK and encoding can continue. */
370 FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
371 /**< An unrecoverable error occurred. The encoder will return from the process call. */
373 } FLAC__StreamEncoderWriteStatus;
375 /** Maps a FLAC__StreamEncoderWriteStatus to a C string.
377 * Using a FLAC__StreamEncoderWriteStatus as the index to this array
378 * will give the string equivalent. The contents should not be modified.
380 extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
383 /** Return values for the FLAC__StreamEncoder seek callback.
387 FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
388 /**< The seek was OK and encoding can continue. */
390 FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
391 /**< An unrecoverable error occurred. */
393 FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
394 /**< Client does not support seeking. */
396 } FLAC__StreamEncoderSeekStatus;
398 /** Maps a FLAC__StreamEncoderSeekStatus to a C string.
400 * Using a FLAC__StreamEncoderSeekStatus as the index to this array
401 * will give the string equivalent. The contents should not be modified.
403 extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
406 /** Return values for the FLAC__StreamEncoder tell callback.
410 FLAC__STREAM_ENCODER_TELL_STATUS_OK,
411 /**< The tell was OK and encoding can continue. */
413 FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
414 /**< An unrecoverable error occurred. */
416 FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
417 /**< Client does not support seeking. */
419 } FLAC__StreamEncoderTellStatus;
421 /** Maps a FLAC__StreamEncoderTellStatus to a C string.
423 * Using a FLAC__StreamEncoderTellStatus as the index to this array
424 * will give the string equivalent. The contents should not be modified.
426 extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
429 /***********************************************************************
431 * class FLAC__StreamEncoder
433 ***********************************************************************/
435 struct FLAC__StreamEncoderProtected;
436 struct FLAC__StreamEncoderPrivate;
437 /** The opaque structure definition for the stream encoder type.
438 * See the \link flac_stream_encoder stream encoder module \endlink
439 * for a detailed description.
442 struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
443 struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
444 } FLAC__StreamEncoder;
446 /** Signature for the read callback.
448 * A function pointer matching this signature must be passed to
449 * FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
450 * The supplied function will be called when the encoder needs to read back
451 * encoded data. This happens during the metadata callback, when the encoder
452 * has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
453 * while encoding. The address of the buffer to be filled is supplied, along
454 * with the number of bytes the buffer can hold. The callback may choose to
455 * supply less data and modify the byte count but must be careful not to
456 * overflow the buffer. The callback then returns a status code chosen from
457 * FLAC__StreamEncoderReadStatus.
459 * \note In general, FLAC__StreamEncoder functions which change the
460 * state should not be called on the \a encoder while in the callback.
462 * \param encoder The encoder instance calling the callback.
463 * \param buffer A pointer to a location for the callee to store
464 * data to be encoded.
465 * \param bytes A pointer to the size of the buffer. On entry
466 * to the callback, it contains the maximum number
467 * of bytes that may be stored in \a buffer. The
468 * callee must set it to the actual number of bytes
469 * stored (0 in case of error or end-of-stream) before
471 * \param client_data The callee's client data set through
472 * FLAC__stream_encoder_set_client_data().
473 * \retval FLAC__StreamEncoderReadStatus
474 * The callee's return status.
476 typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
478 /** Signature for the write callback.
480 * A function pointer matching this signature must be passed to
481 * FLAC__stream_encoder_init_stream(). The supplied function will be called
482 * by the encoder anytime there is raw encoded data ready to write. It may
483 * include metadata mixed with encoded audio frames and the data is not
484 * guaranteed to be aligned on frame or metadata block boundaries.
486 * The only duty of the callback is to write out the \a bytes worth of data
487 * in \a buffer to the current position in the output stream. The arguments
488 * \a samples and \a current_frame are purely informational. If \a samples
489 * is greater than \c 0, then \a current_frame will hold the current frame
490 * number that is being written; otherwise it indicates that the write
491 * callback is being called to write metadata.
494 * Unlike when writing to native FLAC, when writing to Ogg FLAC the
495 * write callback will be called twice when writing each audio
496 * frame; once for the page header, and once for the page body.
497 * When writing the page header, the \a samples argument to the
498 * write callback will be \c 0.
500 * \note In general, FLAC__StreamEncoder functions which change the
501 * state should not be called on the \a encoder while in the callback.
503 * \param encoder The encoder instance calling the callback.
504 * \param buffer An array of encoded data of length \a bytes.
505 * \param bytes The byte length of \a buffer.
506 * \param samples The number of samples encoded by \a buffer.
507 * \c 0 has a special meaning; see above.
508 * \param current_frame The number of the current frame being encoded.
509 * \param client_data The callee's client data set through
510 * FLAC__stream_encoder_init_*().
511 * \retval FLAC__StreamEncoderWriteStatus
512 * The callee's return status.
514 typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
516 /** Signature for the seek callback.
518 * A function pointer matching this signature may be passed to
519 * FLAC__stream_encoder_init_stream(). The supplied function will be called
520 * when the encoder needs to seek the output stream. The encoder will pass
521 * the absolute byte offset to seek to, 0 meaning the beginning of the stream.
523 * \note In general, FLAC__StreamEncoder functions which change the
524 * state should not be called on the \a encoder while in the callback.
526 * \param encoder The encoder instance calling the callback.
527 * \param absolute_byte_offset The offset from the beginning of the stream
529 * \param client_data The callee's client data set through
530 * FLAC__stream_encoder_init_*().
531 * \retval FLAC__StreamEncoderSeekStatus
532 * The callee's return status.
534 typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
536 /** Signature for the tell callback.
538 * A function pointer matching this signature may be passed to
539 * FLAC__stream_encoder_init_stream(). The supplied function will be called
540 * when the encoder needs to know the current position of the output stream.
543 * The callback must return the true current byte offset of the output to
544 * which the encoder is writing. If you are buffering the output, make
545 * sure and take this into account. If you are writing directly to a
546 * FILE* from your write callback, ftell() is sufficient. If you are
547 * writing directly to a file descriptor from your write callback, you
548 * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
549 * these points to rewrite metadata after encoding.
551 * \note In general, FLAC__StreamEncoder functions which change the
552 * state should not be called on the \a encoder while in the callback.
554 * \param encoder The encoder instance calling the callback.
555 * \param absolute_byte_offset The address at which to store the current
556 * position of the output.
557 * \param client_data The callee's client data set through
558 * FLAC__stream_encoder_init_*().
559 * \retval FLAC__StreamEncoderTellStatus
560 * The callee's return status.
562 typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
564 /** Signature for the metadata callback.
566 * A function pointer matching this signature may be passed to
567 * FLAC__stream_encoder_init_stream(). The supplied function will be called
568 * once at the end of encoding with the populated STREAMINFO structure. This
569 * is so the client can seek back to the beginning of the file and write the
570 * STREAMINFO block with the correct statistics after encoding (like
571 * minimum/maximum frame size and total samples).
573 * \note In general, FLAC__StreamEncoder functions which change the
574 * state should not be called on the \a encoder while in the callback.
576 * \param encoder The encoder instance calling the callback.
577 * \param metadata The final populated STREAMINFO block.
578 * \param client_data The callee's client data set through
579 * FLAC__stream_encoder_init_*().
581 typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
583 /** Signature for the progress callback.
585 * A function pointer matching this signature may be passed to
586 * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
587 * The supplied function will be called when the encoder has finished
588 * writing a frame. The \c total_frames_estimate argument to the
589 * callback will be based on the value from
590 * FLAC__file_encoder_set_total_samples_estimate().
592 * \note In general, FLAC__StreamEncoder functions which change the
593 * state should not be called on the \a encoder while in the callback.
595 * \param encoder The encoder instance calling the callback.
596 * \param bytes_written Bytes written so far.
597 * \param samples_written Samples written so far.
598 * \param frames_written Frames written so far.
599 * \param total_frames_estimate The estimate of the total number of
600 * frames to be written.
601 * \param client_data The callee's client data set through
602 * FLAC__stream_encoder_init_*().
604 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);
607 /***********************************************************************
609 * Class constructor/destructor
611 ***********************************************************************/
613 /** Create a new stream encoder instance. The instance is created with
614 * default settings; see the individual FLAC__stream_encoder_set_*()
615 * functions for each setting's default.
617 * \retval FLAC__StreamEncoder*
618 * \c NULL if there was an error allocating memory, else the new instance.
620 FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new();
622 /** Free an encoder instance. Deletes the object pointed to by \a encoder.
624 * \param encoder A pointer to an existing encoder.
626 * \code encoder != NULL \endcode
628 FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
631 /***********************************************************************
633 * Public class method prototypes
635 ***********************************************************************/
637 /** Set the serial number for the FLAC stream to use in the Ogg container.
640 * This does not need to be set for native FLAC encoding.
643 * It is recommended to set a serial number explicitly as the default of '0'
644 * may collide with other streams.
647 * \param encoder An encoder instance to set.
648 * \param serial_number See above.
650 * \code encoder != NULL \endcode
652 * \c false if the encoder is already initialized, else \c true.
654 FLAC_API FLAC__bool FLAC__stream_encoder_set_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
656 /** Set the "verify" flag. If \c true, the encoder will verify it's own
657 * encoded output by feeding it through an internal decoder and comparing
658 * the original signal against the decoded signal. If a mismatch occurs,
659 * the process call will return \c false. Note that this will slow the
660 * encoding process by the extra time required for decoding and comparison.
663 * \param encoder An encoder instance to set.
664 * \param value Flag value (see above).
666 * \code encoder != NULL \endcode
668 * \c false if the encoder is already initialized, else \c true.
670 FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
672 /** Set the <A HREF="../format.html#subset">Subset</A> flag. If \c true,
673 * the encoder will comply with the Subset and will check the
674 * settings during FLAC__stream_encoder_init() to see if all settings
675 * comply. If \c false, the settings may take advantage of the full
676 * range that the format allows.
678 * Make sure you know what it entails before setting this to \c false.
681 * \param encoder An encoder instance to set.
682 * \param value Flag value (see above).
684 * \code encoder != NULL \endcode
686 * \c false if the encoder is already initialized, else \c true.
688 FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
690 /** Set to \c true to enable mid-side encoding on stereo input. The
691 * number of channels must be 2. Set to \c false to use only
692 * independent channel coding.
695 * \param encoder An encoder instance to set.
696 * \param value Flag value (see above).
698 * \code encoder != NULL \endcode
700 * \c false if the encoder is already initialized, else \c true.
702 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
704 /** Set to \c true to enable adaptive switching between mid-side and
705 * left-right encoding on stereo input. The number of channels must
706 * be 2. Set to \c false to use exhaustive searching. In either
707 * case, the mid/side stereo setting must be \c true.
710 * \param encoder An encoder instance to set.
711 * \param value Flag value (see above).
713 * \code encoder != NULL \endcode
715 * \c false if the encoder is already initialized, else \c true.
717 FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
719 /** Set the number of channels to be encoded.
722 * \param encoder An encoder instance to set.
723 * \param value See above.
725 * \code encoder != NULL \endcode
727 * \c false if the encoder is already initialized, else \c true.
729 FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value);
731 /** Set the sample resolution of the input to be encoded.
734 * Do not feed the encoder data that is wider than the value you
735 * set here or you will generate an invalid stream.
738 * \param encoder An encoder instance to set.
739 * \param value See above.
741 * \code encoder != NULL \endcode
743 * \c false if the encoder is already initialized, else \c true.
745 FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value);
747 /** Set the sample rate (in Hz) of the input to be encoded.
750 * \param encoder An encoder instance to set.
751 * \param value See above.
753 * \code encoder != NULL \endcode
755 * \c false if the encoder is already initialized, else \c true.
757 FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
759 /** Set the blocksize to use while encoding.
762 * \param encoder An encoder instance to set.
763 * \param value See above.
765 * \code encoder != NULL \endcode
767 * \c false if the encoder is already initialized, else \c true.
769 FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
771 /** Sets the apodization function(s) the encoder will use when windowing
772 * audio data for LPC analysis.
774 * The \a specification is a plain ASCII string which specifies exactly
775 * which functions to use. There may be more than one (up to 32),
776 * separated by \c ';' characters. Some functions take one or more
777 * comma-separated arguments in parentheses.
779 * The available functions are \c bartlett, \c bartlett_hann,
780 * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
781 * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
782 * \c rectangle, \c triangle, \c tukey(P), \c welch.
784 * For \c gauss(STDDEV), STDDEV specifies the standard deviation
787 * For \c tukey(P), P specifies the fraction of the window that is
788 * tapered (0<=P<=1). P=0 corresponds to \c rectangle and P=1
789 * corresponds to \c hann.
791 * Example specifications are \c "blackman" or
792 * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
794 * Any function that is specified erroneously is silently dropped. Up
795 * to 32 functions are kept, the rest are dropped. If the specification
796 * is empty the encoder defaults to \c "tukey(0.5)".
798 * When more than one function is specified, then for every subframe the
799 * encoder will try each of them separately and choose the window that
800 * results in the smallest compressed subframe.
802 * Note that each function specified causes the encoder to occupy a
803 * floating point array in which to store the window.
805 * \default \c "tukey(0.5)"
806 * \param encoder An encoder instance to set.
807 * \param specification See above.
809 * \code encoder != NULL \endcode
810 * \code specification != NULL \endcode
812 * \c false if the encoder is already initialized, else \c true.
814 /* @@@@add to unit tests*/
815 FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
817 /** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
820 * \param encoder An encoder instance to set.
821 * \param value See above.
823 * \code encoder != NULL \endcode
825 * \c false if the encoder is already initialized, else \c true.
827 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, unsigned value);
829 /** Set the precision, in bits, of the quantized linear predictor
830 * coefficients, or \c 0 to let the encoder select it based on the
834 * In the current implementation, qlp_coeff_precision + bits_per_sample must
838 * \param encoder An encoder instance to set.
839 * \param value See above.
841 * \code encoder != NULL \endcode
843 * \c false if the encoder is already initialized, else \c true.
845 FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value);
847 /** Set to \c false to use only the specified quantized linear predictor
848 * coefficient precision, or \c true to search neighboring precision
849 * values and use the best one.
852 * \param encoder An encoder instance to set.
853 * \param value See above.
855 * \code encoder != NULL \endcode
857 * \c false if the encoder is already initialized, else \c true.
859 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
861 /** Deprecated. Setting this value has no effect.
864 * \param encoder An encoder instance to set.
865 * \param value See above.
867 * \code encoder != NULL \endcode
869 * \c false if the encoder is already initialized, else \c true.
871 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
873 /** Set to \c false to let the encoder estimate the best model order
874 * based on the residual signal energy, or \c true to force the
875 * encoder to evaluate all order models and select the best.
878 * \param encoder An encoder instance to set.
879 * \param value See above.
881 * \code encoder != NULL \endcode
883 * \c false if the encoder is already initialized, else \c true.
885 FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
887 /** Set the minimum partition order to search when coding the residual.
888 * This is used in tandem with
889 * FLAC__stream_encoder_set_max_residual_partition_order().
891 * The partition order determines the context size in the residual.
892 * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
894 * Set both min and max values to \c 0 to force a single context,
895 * whose Rice parameter is based on the residual signal variance.
896 * Otherwise, set a min and max order, and the encoder will search
897 * all orders, using the mean of each context for its Rice parameter,
901 * \param encoder An encoder instance to set.
902 * \param value See above.
904 * \code encoder != NULL \endcode
906 * \c false if the encoder is already initialized, else \c true.
908 FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
910 /** Set the maximum partition order to search when coding the residual.
911 * This is used in tandem with
912 * FLAC__stream_encoder_set_min_residual_partition_order().
914 * The partition order determines the context size in the residual.
915 * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
917 * Set both min and max values to \c 0 to force a single context,
918 * whose Rice parameter is based on the residual signal variance.
919 * Otherwise, set a min and max order, and the encoder will search
920 * all orders, using the mean of each context for its Rice parameter,
924 * \param encoder An encoder instance to set.
925 * \param value 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_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value);
933 /** Deprecated. Setting this value has no effect.
936 * \param encoder An encoder instance to set.
937 * \param value See above.
939 * \code encoder != NULL \endcode
941 * \c false if the encoder is already initialized, else \c true.
943 FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value);
945 /** Set an estimate of the total samples that will be encoded.
946 * This is merely an estimate and may be set to \c 0 if unknown.
947 * This value will be written to the STREAMINFO block before encoding,
948 * and can remove the need for the caller to rewrite the value later
949 * if the value is known before encoding.
952 * \param encoder An encoder instance to set.
953 * \param value See above.
955 * \code encoder != NULL \endcode
957 * \c false if the encoder is already initialized, else \c true.
959 FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
961 /** Set the metadata blocks to be emitted to the stream before encoding.
962 * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
963 * array of pointers to metadata blocks. The array is non-const since
964 * the encoder may need to change the \a is_last flag inside them, and
965 * in some cases update seek point offsets. Otherwise, the encoder will
966 * not modify or free the blocks. It is up to the caller to free the
967 * metadata blocks after encoding.
970 * The encoder stores only the \a metadata pointer; the passed-in array
971 * must survive at least until after FLAC__stream_encoder_init() returns.
972 * Do not modify the array or free the blocks until then.
975 * The STREAMINFO block is always written and no STREAMINFO block may
976 * occur in the supplied array.
979 * By default the encoder does not create a SEEKTABLE. If one is supplied
980 * in the \a metadata array, but the client has specified that it does not
981 * support seeking, then the SEEKTABLE will be written verbatim. However
982 * by itself this is not very useful as the client will not know the stream
983 * offsets for the seekpoints ahead of time. In order to get a proper
984 * seektable the client must support seeking. See next note.
987 * SEEKTABLE blocks are handled specially. Since you will not know
988 * the values for the seek point stream offsets, you should pass in
989 * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
990 * required sample numbers (or placeholder points), with \c 0 for the
991 * \a frame_samples and \a stream_offset fields for each point. If the
992 * client has specified that it supports seeking by providing a seek
993 * callback to FLAC__stream_encoder_init_stream() (or by using
994 * FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE()),
995 * then while it is encoding the encoder will fill the stream offsets in
996 * for you and when encoding is finished, it will seek back and write the
997 * real values into the SEEKTABLE block in the stream. There are helper
998 * routines for manipulating seektable template blocks; see metadata.h:
999 * FLAC__metadata_object_seektable_template_*(). If the client does
1000 * not support seeking, the SEEKTABLE will have inaccurate offsets which
1001 * will slow down or remove the ability to seek in the FLAC stream.
1004 * The encoder instance \b will modify the first \c SEEKTABLE block
1005 * as it transforms the template to a valid seektable while encoding,
1006 * but it is still up to the caller to free all metadata blocks after
1010 * A VORBIS_COMMENT block may be supplied. The vendor string in it
1011 * will be ignored. libFLAC will use it's own vendor string. libFLAC
1012 * will not modify the passed-in VORBIS_COMMENT's vendor string, it
1013 * will simply write it's own into the stream. If no VORBIS_COMMENT
1014 * block is present in the \a metadata array, libFLAC will write an
1015 * empty one, containing only the vendor string.
1017 * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
1018 * the second metadata block of the stream. The encoder already supplies
1019 * the STREAMINFO block automatically. If \a metadata does not contain a
1020 * VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
1021 * \a metadata does contain a VORBIS_COMMENT block and it is not the
1022 * first, this function will reorder \a metadata by moving the
1023 * VORBIS_COMMENT block to the front; the relative ordering of the other
1024 * blocks will remain as they were.
1026 * \note The Ogg FLAC mapping limits the number of metadata blocks per
1027 * stream to \c 65535. If \a num_blocks exceeds this the function will
1030 * \default \c NULL, 0
1031 * \param encoder An encoder instance to set.
1032 * \param metadata See above.
1033 * \param num_blocks See above.
1035 * \code encoder != NULL \endcode
1036 * \retval FLAC__bool
1037 * \c false if the encoder is already initialized, else \c true.
1038 * \c false if the encoder is already initialized, or if
1039 * \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
1041 FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
1043 /** Get the current encoder state.
1045 * \param encoder An encoder instance to query.
1047 * \code encoder != NULL \endcode
1048 * \retval FLAC__StreamEncoderState
1049 * The current encoder state.
1051 FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
1053 /** Get the state of the verify stream decoder.
1054 * Useful when the stream encoder state is
1055 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
1057 * \param encoder An encoder instance to query.
1059 * \code encoder != NULL \endcode
1060 * \retval FLAC__StreamDecoderState
1061 * The verify stream decoder state.
1063 FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
1065 /** Get the current encoder state as a C string.
1066 * This version automatically resolves
1067 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
1068 * verify decoder's state.
1070 * \param encoder A encoder instance to query.
1072 * \code encoder != NULL \endcode
1073 * \retval const char *
1074 * The encoder state as a C string. Do not modify the contents.
1076 FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
1078 /** Get relevant values about the nature of a verify decoder error.
1079 * Useful when the stream encoder state is
1080 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should
1081 * be addresses in which the stats will be returned, or NULL if value
1084 * \param encoder An encoder instance to query.
1085 * \param absolute_sample The absolute sample number of the mismatch.
1086 * \param frame_number The number of the frame in which the mismatch occurred.
1087 * \param channel The channel in which the mismatch occurred.
1088 * \param sample The number of the sample (relative to the frame) in
1089 * which the mismatch occurred.
1090 * \param expected The expected value for the sample in question.
1091 * \param got The actual value returned by the decoder.
1093 * \code encoder != NULL \endcode
1095 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);
1097 /** Get the "verify" flag.
1099 * \param encoder An encoder instance to query.
1101 * \code encoder != NULL \endcode
1102 * \retval FLAC__bool
1103 * See FLAC__stream_encoder_set_verify().
1105 FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
1107 /** Get the <A HREF="../format.html#subset>Subset</A> flag.
1109 * \param encoder An encoder instance to query.
1111 * \code encoder != NULL \endcode
1112 * \retval FLAC__bool
1113 * See FLAC__stream_encoder_set_streamable_subset().
1115 FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
1117 /** Get the "mid/side stereo coding" flag.
1119 * \param encoder An encoder instance to query.
1121 * \code encoder != NULL \endcode
1122 * \retval FLAC__bool
1123 * See FLAC__stream_encoder_get_do_mid_side_stereo().
1125 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
1127 /** Get the "adaptive mid/side switching" flag.
1129 * \param encoder An encoder instance to query.
1131 * \code encoder != NULL \endcode
1132 * \retval FLAC__bool
1133 * See FLAC__stream_encoder_set_loose_mid_side_stereo().
1135 FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
1137 /** Get the number of input channels being processed.
1139 * \param encoder An encoder instance to query.
1141 * \code encoder != NULL \endcode
1143 * See FLAC__stream_encoder_set_channels().
1145 FLAC_API unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
1147 /** Get the input sample resolution setting.
1149 * \param encoder An encoder instance to query.
1151 * \code encoder != NULL \endcode
1153 * See FLAC__stream_encoder_set_bits_per_sample().
1155 FLAC_API unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
1157 /** Get the input sample rate setting.
1159 * \param encoder An encoder instance to query.
1161 * \code encoder != NULL \endcode
1163 * See FLAC__stream_encoder_set_sample_rate().
1165 FLAC_API unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
1167 /** Get the blocksize setting.
1169 * \param encoder An encoder instance to query.
1171 * \code encoder != NULL \endcode
1173 * See FLAC__stream_encoder_set_blocksize().
1175 FLAC_API unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
1177 /** Get the maximum LPC order setting.
1179 * \param encoder An encoder instance to query.
1181 * \code encoder != NULL \endcode
1183 * See FLAC__stream_encoder_set_max_lpc_order().
1185 FLAC_API unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
1187 /** Get the quantized linear predictor coefficient precision setting.
1189 * \param encoder An encoder instance to query.
1191 * \code encoder != NULL \endcode
1193 * See FLAC__stream_encoder_set_qlp_coeff_precision().
1195 FLAC_API unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
1197 /** Get the qlp coefficient precision search flag.
1199 * \param encoder An encoder instance to query.
1201 * \code encoder != NULL \endcode
1202 * \retval FLAC__bool
1203 * See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
1205 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
1207 /** Get the "escape coding" flag.
1209 * \param encoder An encoder instance to query.
1211 * \code encoder != NULL \endcode
1212 * \retval FLAC__bool
1213 * See FLAC__stream_encoder_set_do_escape_coding().
1215 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
1217 /** Get the exhaustive model search flag.
1219 * \param encoder An encoder instance to query.
1221 * \code encoder != NULL \endcode
1222 * \retval FLAC__bool
1223 * See FLAC__stream_encoder_set_do_exhaustive_model_search().
1225 FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
1227 /** Get the minimum residual partition order setting.
1229 * \param encoder An encoder instance to query.
1231 * \code encoder != NULL \endcode
1233 * See FLAC__stream_encoder_set_min_residual_partition_order().
1235 FLAC_API unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
1237 /** Get maximum residual partition order setting.
1239 * \param encoder An encoder instance to query.
1241 * \code encoder != NULL \endcode
1243 * See FLAC__stream_encoder_set_max_residual_partition_order().
1245 FLAC_API unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
1247 /** Get the Rice parameter search distance setting.
1249 * \param encoder An encoder instance to query.
1251 * \code encoder != NULL \endcode
1253 * See FLAC__stream_encoder_set_rice_parameter_search_dist().
1255 FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
1257 /** Get the previously set estimate of the total samples to be encoded.
1258 * The encoder merely mimics back the value given to
1259 * FLAC__stream_encoder_set_total_samples_estimate() since it has no
1260 * other way of knowing how many samples the user will encode.
1262 * \param encoder An encoder instance to set.
1264 * \code encoder != NULL \endcode
1265 * \retval FLAC__uint64
1266 * See FLAC__stream_encoder_get_total_samples_estimate().
1268 FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
1270 /** Initialize the encoder instance to encode native FLAC streams.
1272 * This flavor of initialization sets up the encoder to encode to a
1273 * native FLAC stream. I/O is performed via callbacks to the client.
1274 * For encoding to a plain file via filename or open \c FILE*,
1275 * FLAC__stream_encoder_init_file() and FLAC__stream_encoder_init_FILE()
1276 * provide a simpler interface.
1278 * This function should be called after FLAC__stream_encoder_new() and
1279 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1280 * or FLAC__stream_encoder_process_interleaved().
1281 * initialization succeeded.
1283 * The call to FLAC__stream_encoder_init_stream() currently will also immediately
1284 * call the write callback several times, once with the \c fLaC signature,
1285 * and once for each encoded metadata block.
1287 * \param encoder An uninitialized encoder instance.
1288 * \param write_callback See FLAC__StreamEncoderWriteCallback. This
1289 * pointer must not be \c NULL.
1290 * \param seek_callback See FLAC__StreamEncoderSeekCallback. This
1291 * pointer may be \c NULL if seeking is not
1292 * supported. The encoder uses seeking to go back
1293 * and write some some stream statistics to the
1294 * STREAMINFO block; this is recommended but not
1295 * necessary to create a valid FLAC stream. If
1296 * \a seek_callback is not \c NULL then a
1297 * \a tell_callback must also be supplied.
1298 * Alternatively, a dummy seek callback that just
1299 * returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
1300 * may also be supplied, all though this is slightly
1301 * less efficient for the decoder.
1302 * \param tell_callback See FLAC__StreamEncoderTellCallback. This
1303 * pointer may be \c NULL if seeking is not
1304 * supported. If \a seek_callback is \c NULL then
1305 * this argument will be ignored. If
1306 * \a seek_callback is not \c NULL then a
1307 * \a tell_callback must also be supplied.
1308 * Alternatively, a dummy tell callback that just
1309 * returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
1310 * may also be supplied, all though this is slightly
1311 * less efficient for the decoder.
1312 * \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
1313 * pointer may be \c NULL if the callback is not
1314 * desired. If the client provides a seek callback,
1315 * this function is not necessary as the encoder
1316 * will automatically seek back and update the
1317 * STREAMINFO block. It may also be \c NULL if the
1318 * client does not support seeking, since it will
1319 * have no way of going back to update the
1320 * STREAMINFO. However the client can still supply
1321 * a callback if it would like to know the details
1322 * from the STREAMINFO.
1323 * \param client_data This value will be supplied to callbacks in their
1324 * \a client_data argument.
1326 * \code encoder != NULL \endcode
1327 * \retval FLAC__StreamEncoderInitStatus
1328 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1329 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1331 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);
1333 /** Initialize the encoder instance to encode Ogg FLAC streams.
1335 * This flavor of initialization sets up the encoder to encode to a FLAC
1336 * stream in an Ogg container. I/O is performed via callbacks to the
1337 * client. For encoding to a plain file via filename or open \c FILE*,
1338 * FLAC__stream_encoder_init_ogg_file() and FLAC__stream_encoder_init_ogg_FILE()
1339 * provide a simpler interface.
1341 * This function should be called after FLAC__stream_encoder_new() and
1342 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1343 * or FLAC__stream_encoder_process_interleaved().
1344 * initialization succeeded.
1346 * The call to FLAC__stream_encoder_init_ogg_stream() currently will
1347 * also immediately call the write callback several times, once with
1348 * the \c fLaC signature, and once for each encoded metadata block.@@@@@@
1350 * \param encoder An uninitialized encoder instance.
1351 * \param read_callback See FLAC__StreamEncoderReadCallback. This
1352 * pointer must not be \c NULL if \a seek_callback
1353 * is non-NULL since they are both needed to be
1354 * able to write data back to the Ogg FLAC stream
1355 * in the post-encode phase.
1356 * \param write_callback See FLAC__StreamEncoderWriteCallback. This
1357 * pointer must not be \c NULL.
1358 * \param seek_callback See FLAC__StreamEncoderSeekCallback. This
1359 * pointer may be \c NULL if seeking is not
1360 * supported. The encoder uses seeking to go back
1361 * and write some some stream statistics to the
1362 * STREAMINFO block; this is recommended but not
1363 * necessary to create a valid FLAC stream. If
1364 * \a seek_callback is not \c NULL then a
1365 * \a tell_callback must also be supplied.
1366 * Alternatively, a dummy seek callback that just
1367 * returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
1368 * may also be supplied, all though this is slightly
1369 * less efficient for the decoder.
1370 * \param tell_callback See FLAC__StreamEncoderTellCallback. This
1371 * pointer may be \c NULL if seeking is not
1372 * supported. If \a seek_callback is \c NULL then
1373 * this argument will be ignored. If
1374 * \a seek_callback is not \c NULL then a
1375 * \a tell_callback must also be supplied.
1376 * Alternatively, a dummy tell callback that just
1377 * returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
1378 * may also be supplied, all though this is slightly
1379 * less efficient for the decoder.
1380 * \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
1381 * pointer may be \c NULL if the callback is not
1382 * desired. If the client provides a seek callback,
1383 * this function is not necessary as the encoder
1384 * will automatically seek back and update the
1385 * STREAMINFO block. It may also be \c NULL if the
1386 * client does not support seeking, since it will
1387 * have no way of going back to update the
1388 * STREAMINFO. However the client can still supply
1389 * a callback if it would like to know the details
1390 * from the STREAMINFO.
1391 * \param client_data This value will be supplied to callbacks in their
1392 * \a client_data argument.
1394 * \code encoder != NULL \endcode
1395 * \retval FLAC__StreamEncoderInitStatus
1396 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1397 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1399 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);
1401 /** Initialize the encoder instance to encode native FLAC files.
1403 * This flavor of initialization sets up the encoder to encode to a
1404 * plain native FLAC file. For non-stdio streams, you must use
1405 * FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
1407 * This function should be called after FLAC__stream_encoder_new() and
1408 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1409 * or FLAC__stream_encoder_process_interleaved().
1410 * initialization succeeded.
1412 * \param encoder An uninitialized encoder instance.
1413 * \param file An open file. The file should have been opened
1414 * with mode \c "w+b" and rewound. The file
1415 * becomes owned by the encoder and should not be
1416 * manipulated by the client while encoding.
1417 * Unless \a file is \c stdout, it will be closed
1418 * when FLAC__stream_encoder_finish() is called.
1419 * Note however that a proper SEEKTABLE cannot be
1420 * created when encoding to \c stdout since it is
1422 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1423 * pointer may be \c NULL if the callback is not
1425 * \param client_data This value will be supplied to callbacks in their
1426 * \a client_data argument.
1428 * \code encoder != NULL \endcode
1429 * \code file != NULL \endcode
1430 * \retval FLAC__StreamEncoderInitStatus
1431 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1432 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1434 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1436 /** Initialize the encoder instance to encode Ogg FLAC files.
1438 * This flavor of initialization sets up the encoder to encode to a
1439 * plain Ogg FLAC file. For non-stdio streams, you must use
1440 * FLAC__stream_encoder_init_ogg_stream() and provide callbacks for the I/O.
1442 * This function should be called after FLAC__stream_encoder_new() and
1443 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1444 * or FLAC__stream_encoder_process_interleaved().
1445 * initialization succeeded.
1447 * \param encoder An uninitialized encoder instance.
1448 * \param file An open file. The file should have been opened
1449 * with mode \c "w+b" and rewound. The file
1450 * becomes owned by the encoder and should not be
1451 * manipulated by the client while encoding.
1452 * Unless \a file is \c stdout, it will be closed
1453 * when FLAC__stream_encoder_finish() is called.
1454 * Note however that a proper SEEKTABLE cannot be
1455 * created when encoding to \c stdout since it is
1457 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1458 * pointer may be \c NULL if the callback is not
1460 * \param client_data This value will be supplied to callbacks in their
1461 * \a client_data argument.
1463 * \code encoder != NULL \endcode
1464 * \code file != NULL \endcode
1465 * \retval FLAC__StreamEncoderInitStatus
1466 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1467 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1469 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1471 /** Initialize the encoder instance to encode native FLAC files.
1473 * This flavor of initialization sets up the encoder to encode to a plain
1474 * FLAC file. If POSIX fopen() semantics are not sufficient (for example,
1475 * with Unicode filenames on Windows), you must use
1476 * FLAC__stream_encoder_init_FILE(), or FLAC__stream_encoder_init_stream()
1477 * and provide callbacks for the I/O.
1479 * This function should be called after FLAC__stream_encoder_new() and
1480 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1481 * or FLAC__stream_encoder_process_interleaved().
1482 * initialization succeeded.
1484 * \param encoder An uninitialized encoder instance.
1485 * \param filename The name of the file to encode to. The file will
1486 * be opened with fopen(). Use \c NULL to encode to
1487 * \c stdout. Note however that a proper SEEKTABLE
1488 * cannot be created when encoding to \c stdout since
1489 * it is not seekable.
1490 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1491 * pointer may be \c NULL if the callback is not
1493 * \param client_data This value will be supplied to callbacks in their
1494 * \a client_data argument.
1496 * \code encoder != NULL \endcode
1497 * \retval FLAC__StreamEncoderInitStatus
1498 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1499 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1501 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1503 /** Initialize the encoder instance to encode Ogg FLAC files.
1505 * This flavor of initialization sets up the encoder to encode to a plain
1506 * Ogg FLAC file. If POSIX fopen() semantics are not sufficient (for example,
1507 * with Unicode filenames on Windows), you must use
1508 * FLAC__stream_encoder_init_ogg_FILE(), or FLAC__stream_encoder_init_ogg_stream()
1509 * and provide callbacks for the I/O.
1511 * This function should be called after FLAC__stream_encoder_new() and
1512 * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1513 * or FLAC__stream_encoder_process_interleaved().
1514 * initialization succeeded.
1516 * \param encoder An uninitialized encoder instance.
1517 * \param filename The name of the file to encode to. The file will
1518 * be opened with fopen(). Use \c NULL to encode to
1519 * \c stdout. Note however that a proper SEEKTABLE
1520 * cannot be created when encoding to \c stdout since
1521 * it is not seekable.
1522 * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1523 * pointer may be \c NULL if the callback is not
1525 * \param client_data This value will be supplied to callbacks in their
1526 * \a client_data argument.
1528 * \code encoder != NULL \endcode
1529 * \retval FLAC__StreamEncoderInitStatus
1530 * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1531 * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1533 FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1535 /** Finish the encoding process.
1536 * Flushes the encoding buffer, releases resources, resets the encoder
1537 * settings to their defaults, and returns the encoder state to
1538 * FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
1539 * one or more write callbacks before returning, and will generate
1540 * a metadata callback.
1542 * In the event of a prematurely-terminated encode, it is not strictly
1543 * necessary to call this immediately before FLAC__stream_encoder_delete()
1544 * but it is good practice to match every FLAC__stream_encoder_init()
1545 * with a FLAC__stream_encoder_finish().
1547 * \param encoder An uninitialized encoder instance.
1549 * \code encoder != NULL \endcode
1551 FLAC_API void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
1553 /** Submit data for encoding.
1554 * This version allows you to supply the input data via an array of
1555 * pointers, each pointer pointing to an array of \a samples samples
1556 * representing one channel. The samples need not be block-aligned,
1557 * but each channel should have the same number of samples.
1559 * For applications where channel order is important, channels must
1560 * follow the order as described in the
1561 * <A HREF="../format.html#frame_header">frame header</A>.
1563 * \param encoder An initialized encoder instance in the OK state.
1564 * \param buffer An array of pointers to each channel's signal.
1565 * \param samples The number of samples in one channel.
1567 * \code encoder != NULL \endcode
1568 * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
1569 * \retval FLAC__bool
1570 * \c true if successful, else \c false; in this case, check the
1571 * encoder state with FLAC__stream_encoder_get_state() to see what
1574 FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
1576 /** Submit data for encoding.
1577 * This version allows you to supply the input data where the channels
1578 * are interleaved into a single array (i.e. channel0_sample0,
1579 * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
1580 * The samples need not be block-aligned but they must be
1581 * sample-aligned, i.e. the first value should be channel0_sample0
1582 * and the last value channelN_sampleM.
1584 * For applications where channel order is important, channels must
1585 * follow the order as described in the
1586 * <A HREF="../format.html#frame_header">frame header</A>.
1588 * \param encoder An initialized encoder instance in the OK state.
1589 * \param buffer An array of channel-interleaved data (see above).
1590 * \param samples The number of samples in one channel, the same as for
1591 * FLAC__stream_encoder_process(). For example, if
1592 * encoding two channels, \c 1000 \a samples corresponds
1593 * to a \a buffer of 2000 values.
1595 * \code encoder != NULL \endcode
1596 * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
1597 * \retval FLAC__bool
1598 * \c true if successful, else \c false; in this case, check the
1599 * encoder state with FLAC__stream_encoder_get_state() to see what
1602 FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);