1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2002,2003 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__SEEKABLE_STREAM_ENCODER_H
33 #define FLAC__SEEKABLE_STREAM_ENCODER_H
36 #include "stream_encoder.h"
43 /** \file include/FLAC/seekable_stream_encoder.h
46 * This module contains the functions which implement the seekable stream
49 * See the detailed documentation in the
50 * \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
53 /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
54 * \ingroup flac_encoder
57 * This module contains the functions which implement the seekable stream
60 * The basic usage of this encoder is as follows:
61 * - The program creates an instance of an encoder using
62 * FLAC__seekable_stream_encoder_new().
63 * - The program overrides the default settings and sets callbacks using
64 * FLAC__seekable_stream_encoder_set_*() functions.
65 * - The program initializes the instance to validate the settings and
66 * prepare for encoding using FLAC__seekable_stream_encoder_init().
67 * - The program calls FLAC__seekable_stream_encoder_process() or
68 * FLAC__seekable_stream_encoder_process_interleaved() to encode data, which
69 * subsequently calls the callbacks when there is encoder data ready
71 * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(),
72 * which causes the encoder to encode any data still in its input pipe,
73 * rewrite the metadata with the final encoding statistics, and finally
74 * reset the encoder to the uninitialized state.
75 * - The instance may be used again or deleted with
76 * FLAC__seekable_stream_encoder_delete().
78 * The seekable stream encoder is a wrapper around the
79 * \link flac_stream_encoder stream encoder \endlink with callbacks for
80 * seeking the output and reporting the output stream position. This
81 * allows the encoder to go back and rewrite some of the metadata after
82 * encoding if necessary, and provides the metadata callback of the stream
83 * encoder internally. However, you must provide seek and tell callbacks
84 * (see FLAC__seekable_stream_encoder_set_seek_callback() and
85 * FLAC__seekable_stream_encoder_set_tell_callback()).
87 * Make sure to read the detailed description of the
88 * \link flac_stream_encoder stream encoder module \endlink since the
89 * seekable stream encoder inherits much of its behavior.
92 * If you are writing the FLAC data to a file, make sure it is open
93 * for update (e.g. mode "w+" for stdio streams). This is because after
94 * the first encoding pass, the encoder will try to seek back to the
95 * beginning of the stream, to the STREAMINFO block, to write some data
99 * The "set" functions may only be called when the encoder is in the
100 * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
101 * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
102 * before FLAC__seekable_stream_encoder_init(). If this is the case they will
103 * return \c true, otherwise \c false.
106 * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
107 * defaults, including the callbacks.
113 /** State values for a FLAC__SeekableStreamEncoder
115 * The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
119 FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
120 /**< The encoder is in the normal OK state. */
122 FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
123 /**< An error occurred in the underlying stream encoder;
124 * check FLAC__seekable_stream_encoder_get_stream_encoder_state().
127 FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
128 /**< Memory allocation failed. */
130 FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
131 /**< The write callback returned an error. */
133 FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
134 /**< The read callback returned an error. */
136 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
137 /**< The seek callback returned an error. */
139 FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
140 /**< The tell callback returned an error. */
142 FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
143 /**< FLAC__seekable_stream_encoder_init() was called when the encoder was
144 * already initialized, usually because
145 * FLAC__seekable_stream_encoder_finish() was not called.
148 FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
149 /**< FLAC__seekable_stream_encoder_init() was called without all
150 * callbacks being set.
153 FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
154 /**< An invalid seek table was passed is the metadata to
155 * FLAC__seekable_stream_encoder_set_metadata().
158 FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
159 /**< The encoder is in the uninitialized state. */
161 } FLAC__SeekableStreamEncoderState;
163 /** Maps a FLAC__SeekableStreamEncoderState to a C string.
165 * Using a FLAC__SeekableStreamEncoderState as the index to this array
166 * will give the string equivalent. The contents should not be modified.
168 extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
171 /** Return values for the FLAC__SeekableStreamEncoder seek callback.
175 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
176 /**< The seek was OK and encoding can continue. */
178 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
179 /**< An unrecoverable error occurred. The encoder will return from the process call. */
181 } FLAC__SeekableStreamEncoderSeekStatus;
183 /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
185 * Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
186 * will give the string equivalent. The contents should not be modified.
188 extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
191 /** Return values for the FLAC__SeekableStreamEncoder tell callback.
195 FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK,
196 /**< The tell was OK and encoding can continue. */
198 FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR
199 /**< An unrecoverable error occurred. The encoder will return from the process call. */
201 } FLAC__SeekableStreamEncoderTellStatus;
203 /** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string.
205 * Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array
206 * will give the string equivalent. The contents should not be modified.
208 extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[];
211 /***********************************************************************
213 * class FLAC__SeekableStreamEncoder
215 ***********************************************************************/
217 struct FLAC__SeekableStreamEncoderProtected;
218 struct FLAC__SeekableStreamEncoderPrivate;
219 /** The opaque structure definition for the seekable stream encoder type.
220 * See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
221 * for a detailed description.
224 struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
225 struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
226 } FLAC__SeekableStreamEncoder;
228 /** Signature for the seek callback.
229 * See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
231 * \param encoder The encoder instance calling the callback.
232 * \param absolute_byte_offset The offset from the beginning of the stream
234 * \param client_data The callee's client data set through
235 * FLAC__seekable_stream_encoder_set_client_data().
236 * \retval FLAC__SeekableStreamEncoderSeekStatus
237 * The callee's return status.
239 typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
241 /** Signature for the tell callback.
242 * See FLAC__seekable_stream_encoder_set_tell_callback() for more info.
245 * The callback must return the true current byte offset of the output to
246 * which the encoder is writing. If you are buffering the output, make
247 * sure and take this into account. If you are writing directly to a
248 * FILE* from your write callback, ftell() is sufficient. If you are
249 * writing directly to a file descriptor from your write callback, you
250 * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
251 * these points to rewrite metadata after encoding.
253 * \param encoder The encoder instance calling the callback.
254 * \param absolute_byte_offset The address at which to store the current
255 * position of the output.
256 * \param client_data The callee's client data set through
257 * FLAC__seekable_stream_encoder_set_client_data().
258 * \retval FLAC__SeekableStreamEncoderTellStatus
259 * The callee's return status.
261 typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
263 /** Signature for the write callback.
264 * See FLAC__seekable_stream_encoder_set_write_callback()
265 * and FLAC__StreamEncoderWriteCallback for more info.
267 * \param encoder The encoder instance calling the callback.
268 * \param buffer An array of encoded data of length \a bytes.
269 * \param bytes The byte length of \a buffer.
270 * \param samples The number of samples encoded by \a buffer.
271 * \c 0 has a special meaning; see
272 * FLAC__stream_encoder_set_write_callback().
273 * \param current_frame The number of current frame being encoded.
274 * \param client_data The callee's client data set through
275 * FLAC__seekable_stream_encoder_set_client_data().
276 * \retval FLAC__StreamEncoderWriteStatus
277 * The callee's return status.
279 typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
282 /***********************************************************************
284 * Class constructor/destructor
286 ***********************************************************************/
288 /** Create a new seekable stream encoder instance. The instance is created with
289 * default settings; see the individual FLAC__seekable_stream_encoder_set_*()
290 * functions for each setting's default.
292 * \retval FLAC__SeekableStreamEncoder*
293 * \c NULL if there was an error allocating memory, else the new instance.
295 FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
297 /** Free an encoder instance. Deletes the object pointed to by \a encoder.
299 * \param encoder A pointer to an existing encoder.
301 * \code encoder != NULL \endcode
303 FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
305 /***********************************************************************
307 * Public class method prototypes
309 ***********************************************************************/
311 /** This is inherited from FLAC__StreamEncoder; see
312 * FLAC__stream_encoder_set_verify().
315 * \param encoder An encoder instance to set.
316 * \param value See above.
318 * \code encoder != NULL \endcode
320 * \c false if the encoder is already initialized, else \c true.
322 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
324 /** This is inherited from FLAC__StreamEncoder; see
325 * FLAC__stream_encoder_set_streamable_subset().
328 * \param encoder An encoder instance to set.
329 * \param value See above.
331 * \code encoder != NULL \endcode
333 * \c false if the encoder is already initialized, else \c true.
335 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
337 /** This is inherited from FLAC__StreamEncoder; see
338 * FLAC__stream_encoder_set_do_mid_side_stereo().
341 * \param encoder An encoder instance to set.
342 * \param value See above.
344 * \code encoder != NULL \endcode
346 * \c false if the encoder is already initialized, else \c true.
348 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
350 /** This is inherited from FLAC__StreamEncoder; see
351 * FLAC__stream_encoder_set_loose_mid_side_stereo().
354 * \param encoder An encoder instance to set.
355 * \param value See above.
357 * \code encoder != NULL \endcode
359 * \c false if the encoder is already initialized, else \c true.
361 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
363 /** This is inherited from FLAC__StreamEncoder; see
364 * FLAC__stream_encoder_set_channels().
367 * \param encoder An encoder instance to set.
368 * \param value See above.
370 * \code encoder != NULL \endcode
372 * \c false if the encoder is already initialized, else \c true.
374 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
376 /** This is inherited from FLAC__StreamEncoder; see
377 * FLAC__stream_encoder_set_bits_per_sample().
380 * Do not feed the encoder data that is wider than the value you
381 * set here or you will generate an invalid stream.
384 * \param encoder An encoder instance to set.
385 * \param value See above.
387 * \code encoder != NULL \endcode
389 * \c false if the encoder is already initialized, else \c true.
391 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
393 /** This is inherited from FLAC__StreamEncoder; see
394 * FLAC__stream_encoder_set_sample_rate().
397 * \param encoder An encoder instance to set.
398 * \param value See above.
400 * \code encoder != NULL \endcode
402 * \c false if the encoder is already initialized, else \c true.
404 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
406 /** This is inherited from FLAC__StreamEncoder; see
407 * FLAC__stream_encoder_set_blocksize().
410 * \param encoder An encoder instance to set.
411 * \param value See above.
413 * \code encoder != NULL \endcode
415 * \c false if the encoder is already initialized, else \c true.
417 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
419 /** This is inherited from FLAC__StreamEncoder; see
420 * FLAC__stream_encoder_set_max_lpc_order().
423 * \param encoder An encoder instance to set.
424 * \param value See above.
426 * \code encoder != NULL \endcode
428 * \c false if the encoder is already initialized, else \c true.
430 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
432 /** This is inherited from FLAC__StreamEncoder; see
433 * FLAC__stream_encoder_set_qlp_coeff_precision().
436 * In the current implementation, qlp_coeff_precision + bits_per_sample must
440 * \param encoder An encoder instance to set.
441 * \param value See above.
443 * \code encoder != NULL \endcode
445 * \c false if the encoder is already initialized, else \c true.
447 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
449 /** This is inherited from FLAC__StreamEncoder; see
450 * FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
453 * \param encoder An encoder instance to set.
454 * \param value See above.
456 * \code encoder != NULL \endcode
458 * \c false if the encoder is already initialized, else \c true.
460 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
462 /** This is inherited from FLAC__StreamEncoder; see
463 * FLAC__stream_encoder_set_do_escape_coding().
466 * \param encoder An encoder instance to set.
467 * \param value See above.
469 * \code encoder != NULL \endcode
471 * \c false if the encoder is already initialized, else \c true.
473 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
475 /** This is inherited from FLAC__StreamEncoder; see
476 * FLAC__stream_encoder_set_do_exhaustive_model_search().
479 * \param encoder An encoder instance to set.
480 * \param value See above.
482 * \code encoder != NULL \endcode
484 * \c false if the encoder is already initialized, else \c true.
486 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
488 /** This is inherited from FLAC__StreamEncoder; see
489 * FLAC__stream_encoder_set_min_residual_partition_order().
492 * \param encoder An encoder instance to set.
493 * \param value See above.
495 * \code encoder != NULL \endcode
497 * \c false if the encoder is already initialized, else \c true.
499 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
501 /** This is inherited from FLAC__StreamEncoder; see
502 * FLAC__stream_encoder_set_max_residual_partition_order().
505 * \param encoder An encoder instance to set.
506 * \param value See above.
508 * \code encoder != NULL \endcode
510 * \c false if the encoder is already initialized, else \c true.
512 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
514 /** This is inherited from FLAC__StreamEncoder; see
515 * FLAC__stream_encoder_set_rice_parameter_search_dist().
518 * \param encoder An encoder instance to set.
519 * \param value See above.
521 * \code encoder != NULL \endcode
523 * \c false if the encoder is already initialized, else \c true.
525 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
527 /** This is inherited from FLAC__StreamEncoder; see
528 * FLAC__stream_encoder_set_total_samples_estimate().
531 * \param encoder An encoder instance to set.
532 * \param value See above.
534 * \code encoder != NULL \endcode
536 * \c false if the encoder is already initialized, else \c true.
538 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
540 /** This is inherited from FLAC__StreamEncoder; see
541 * FLAC__stream_encoder_set_metadata().
544 * SEEKTABLE blocks are handled specially. Since you will not know
545 * the values for the seek point stream offsets, you should pass in
546 * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
547 * required sample numbers (or placeholder points), with \c 0 for the
548 * \a frame_samples and \a stream_offset fields for each point. While
549 * encoding, the encoder will fill them in for you and when encoding
550 * is finished, it will seek back and write the real values into the
551 * SEEKTABLE block in the stream. There are helper routines for
552 * manipulating seektable template blocks; see metadata.h:
553 * FLAC__metadata_object_seektable_template_*().
556 * The encoder instance \b will modify the first \c SEEKTABLE block
557 * as it transforms the template to a valid seektable while encoding,
558 * but it is still up to the caller to free all metadata blocks after
561 * \default \c NULL, 0
562 * \param encoder An encoder instance to set.
563 * \param metadata See above.
564 * \param num_blocks See above.
566 * \code encoder != NULL \endcode
568 * \c false if the encoder is already initialized, else \c true.
570 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
572 /** Set the seek callback.
573 * The supplied function will be called when the encoder needs to seek
574 * the output stream. The encoder will pass the absolute byte offset
575 * to seek to, 0 meaning the beginning of the stream.
578 * The callback is mandatory and must be set before initialization.
581 * \param encoder An encoder instance to set.
582 * \param value See above.
584 * \code encoder != NULL \endcode
585 * \code value != NULL \endcode
587 * \c false if the encoder is already initialized, else \c true.
589 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
591 /** Set the tell callback.
592 * The supplied function will be called when the encoder needs to know
593 * the current position of the output stream.
596 * The callback is mandatory and must be set before initialization.
599 * \param encoder An encoder instance to set.
600 * \param value See above.
602 * \code encoder != NULL \endcode
603 * \code value != NULL \endcode
605 * \c false if the encoder is already initialized, else \c true.
607 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value);
609 /** Set the write callback.
610 * This is inherited from FLAC__StreamEncoder; see
611 * FLAC__stream_encoder_set_write_callback().
614 * The callback is mandatory and must be set before initialization.
617 * \param encoder An encoder instance to set.
618 * \param value See above.
620 * \code encoder != NULL \endcode
621 * \code value != NULL \endcode
623 * \c false if the encoder is already initialized, else \c true.
625 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
627 /** Set the client data to be passed back to callbacks.
628 * This value will be supplied to callbacks in their \a client_data
632 * \param encoder An encoder instance to set.
633 * \param value See above.
635 * \code encoder != NULL \endcode
637 * \c false if the encoder is already initialized, else \c true.
639 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
641 /** Get the current encoder state.
643 * \param encoder An encoder instance to query.
645 * \code encoder != NULL \endcode
646 * \retval FLAC__SeekableStreamEncoderState
647 * The current encoder state.
649 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
651 /** Get the state of the underlying stream encoder.
652 * Useful when the seekable stream encoder state is
653 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
655 * \param encoder An encoder instance to query.
657 * \code encoder != NULL \endcode
658 * \retval FLAC__StreamEncoderState
659 * The stream encoder state.
661 FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
663 /** Get the state of the underlying stream encoder's verify decoder.
664 * Useful when the seekable stream encoder state is
665 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
666 * stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
668 * \param encoder An encoder instance to query.
670 * \code encoder != NULL \endcode
671 * \retval FLAC__StreamDecoderState
672 * The stream encoder state.
674 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
676 /** Get the current encoder state as a C string.
677 * This version automatically resolves
678 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the
679 * stream encoder's state.
681 * \param encoder A encoder instance to query.
683 * \code encoder != NULL \endcode
684 * \retval const char *
685 * The encoder state as a C string. Do not modify the contents.
687 FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
689 /** Get relevant values about the nature of a verify decoder error.
690 * Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
691 * Useful when the seekable stream encoder state is
692 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
693 * stream encoder state is
694 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
696 * \param encoder An encoder instance to query.
697 * \param absolute_sample The absolute sample number of the mismatch.
698 * \param frame_number The number of the frame in which the mismatch occurred.
699 * \param channel The channel in which the mismatch occurred.
700 * \param sample The number of the sample (relative to the frame) in
701 * which the mismatch occurred.
702 * \param expected The expected value for the sample in question.
703 * \param got The actual value returned by the decoder.
705 * \code encoder != NULL \endcode
707 FLAC_API void FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
709 /** Get the "verify" flag.
710 * This is inherited from FLAC__StreamEncoder; see
711 * FLAC__stream_encoder_get_verify().
713 * \param encoder An encoder instance to query.
715 * \code encoder != NULL \endcode
717 * See FLAC__seekable_stream_encoder_set_verify().
719 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
721 /** Get the "streamable subset" flag.
722 * This is inherited from FLAC__StreamEncoder; see
723 * FLAC__stream_encoder_get_streamable_subset().
725 * \param encoder An encoder instance to query.
727 * \code encoder != NULL \endcode
729 * See FLAC__seekable_stream_encoder_set_streamable_subset().
731 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
733 /** Get the "mid/side stereo coding" flag.
734 * This is inherited from FLAC__StreamEncoder; see
735 * FLAC__stream_encoder_get_do_mid_side_stereo().
737 * \param encoder An encoder instance to query.
739 * \code encoder != NULL \endcode
741 * See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
743 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
745 /** Get the "adaptive mid/side switching" flag.
746 * This is inherited from FLAC__StreamEncoder; see
747 * FLAC__stream_encoder_get_loose_mid_side_stereo().
749 * \param encoder An encoder instance to query.
751 * \code encoder != NULL \endcode
753 * See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
755 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
757 /** Get the number of input channels being processed.
758 * This is inherited from FLAC__StreamEncoder; see
759 * FLAC__stream_encoder_get_channels().
761 * \param encoder An encoder instance to query.
763 * \code encoder != NULL \endcode
765 * See FLAC__seekable_stream_encoder_set_channels().
767 FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
769 /** Get the input sample resolution setting.
770 * This is inherited from FLAC__StreamEncoder; see
771 * FLAC__stream_encoder_get_bits_per_sample().
773 * \param encoder An encoder instance to query.
775 * \code encoder != NULL \endcode
777 * See FLAC__seekable_stream_encoder_set_bits_per_sample().
779 FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
781 /** Get the input sample rate setting.
782 * This is inherited from FLAC__StreamEncoder; see
783 * FLAC__stream_encoder_get_sample_rate().
785 * \param encoder An encoder instance to query.
787 * \code encoder != NULL \endcode
789 * See FLAC__seekable_stream_encoder_set_sample_rate().
791 FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
793 /** Get the blocksize setting.
794 * This is inherited from FLAC__StreamEncoder; see
795 * FLAC__stream_encoder_get_blocksize().
797 * \param encoder An encoder instance to query.
799 * \code encoder != NULL \endcode
801 * See FLAC__seekable_stream_encoder_set_blocksize().
803 FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
805 /** Get the maximum LPC order setting.
806 * This is inherited from FLAC__StreamEncoder; see
807 * FLAC__stream_encoder_get_max_lpc_order().
809 * \param encoder An encoder instance to query.
811 * \code encoder != NULL \endcode
813 * See FLAC__seekable_stream_encoder_set_max_lpc_order().
815 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
817 /** Get the quantized linear predictor coefficient precision setting.
818 * This is inherited from FLAC__StreamEncoder; see
819 * FLAC__stream_encoder_get_qlp_coeff_precision().
821 * \param encoder An encoder instance to query.
823 * \code encoder != NULL \endcode
825 * See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
827 FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
829 /** Get the qlp coefficient precision search flag.
830 * This is inherited from FLAC__StreamEncoder; see
831 * FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
833 * \param encoder An encoder instance to query.
835 * \code encoder != NULL \endcode
837 * See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
839 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
841 /** Get the "escape coding" flag.
842 * This is inherited from FLAC__StreamEncoder; see
843 * FLAC__stream_encoder_get_do_escape_coding().
845 * \param encoder An encoder instance to query.
847 * \code encoder != NULL \endcode
849 * See FLAC__seekable_stream_encoder_set_do_escape_coding().
851 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
853 /** Get the exhaustive model search flag.
854 * This is inherited from FLAC__StreamEncoder; see
855 * FLAC__stream_encoder_get_do_exhaustive_model_search().
857 * \param encoder An encoder instance to query.
859 * \code encoder != NULL \endcode
861 * See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
863 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
865 /** Get the minimum residual partition order setting.
866 * This is inherited from FLAC__StreamEncoder; see
867 * FLAC__stream_encoder_get_min_residual_partition_order().
869 * \param encoder An encoder instance to query.
871 * \code encoder != NULL \endcode
873 * See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
875 FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
877 /** Get maximum residual partition order setting.
878 * This is inherited from FLAC__StreamEncoder; see
879 * FLAC__stream_encoder_get_max_residual_partition_order().
881 * \param encoder An encoder instance to query.
883 * \code encoder != NULL \endcode
885 * See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
887 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
889 /** Get the Rice parameter search distance setting.
890 * This is inherited from FLAC__StreamEncoder; see
891 * FLAC__stream_encoder_get_rice_parameter_search_dist().
893 * \param encoder An encoder instance to query.
895 * \code encoder != NULL \endcode
897 * See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
899 FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
901 /** Get the previously set estimate of the total samples to be encoded.
902 * This is inherited from FLAC__StreamEncoder; see
903 * FLAC__stream_encoder_get_total_samples_estimate().
905 * \param encoder An encoder instance to query.
907 * \code encoder != NULL \endcode
908 * \retval FLAC__uint64
909 * See FLAC__seekable_stream_encoder_set_total_samples_estimate().
911 FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
913 /** Initialize the encoder instance.
914 * Should be called after FLAC__seekable_stream_encoder_new() and
915 * FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
916 * or FLAC__seekable_stream_encoder_process_interleaved(). Will set and return
917 * the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
918 * initialization succeeded.
920 * The call to FLAC__seekable_stream_encoder_init() currently will also immediately
921 * call the write callback with the \c fLaC signature and all the encoded
924 * \param encoder An uninitialized encoder instance.
926 * \code encoder != NULL \endcode
927 * \retval FLAC__SeekableStreamEncoderState
928 * \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
929 * FLAC__SeekableStreamEncoderState for the meanings of other return values.
931 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
933 /** Finish the encoding process.
934 * Flushes the encoding buffer, releases resources, resets the encoder
935 * settings to their defaults, and returns the encoder state to
936 * FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
938 * In the event of a prematurely-terminated encode, it is not strictly
939 * necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
940 * but it is good practice to match every FLAC__seekable_stream_encoder_init()
941 * with a FLAC__seekable_stream_encoder_finish().
943 * \param encoder An uninitialized encoder instance.
945 * \code encoder != NULL \endcode
947 FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
949 /** Submit data for encoding.
950 * This is inherited from FLAC__StreamEncoder; see
951 * FLAC__stream_encoder_process().
953 * \param encoder An initialized encoder instance in the OK state.
954 * \param buffer An array of pointers to each channel's signal.
955 * \param samples The number of samples in one channel.
957 * \code encoder != NULL \endcode
958 * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
960 * \c true if successful, else \c false; in this case, check the
961 * encoder state with FLAC__seekable_stream_encoder_get_state() to see what
964 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
966 /** Submit data for encoding.
967 * This is inherited from FLAC__StreamEncoder; see
968 * FLAC__stream_encoder_process_interleaved().
970 * \param encoder An initialized encoder instance in the OK state.
971 * \param buffer An array of channel-interleaved data (see above).
972 * \param samples The number of samples in one channel, the same as for
973 * FLAC__seekable_stream_encoder_process(). For example, if
974 * encoding two channels, \c 1000 \a samples corresponds
975 * to a \a buffer of 2000 values.
977 * \code encoder != NULL \endcode
978 * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
980 * \c true if successful, else \c false; in this case, check the
981 * encoder state with FLAC__seekable_stream_encoder_get_state() to see what
984 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);