add 2005 to copyright notices
[flac.git] / include / FLAC / seekable_stream_encoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2002,2003,2004,2005  Josh Coalson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * - Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
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.
14  *
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.
18  *
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.
30  */
31
32 #ifndef FLAC__SEEKABLE_STREAM_ENCODER_H
33 #define FLAC__SEEKABLE_STREAM_ENCODER_H
34
35 #include "export.h"
36 #include "stream_encoder.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42
43 /** \file include/FLAC/seekable_stream_encoder.h
44  *
45  *  \brief
46  *  This module contains the functions which implement the seekable stream
47  *  encoder.
48  *
49  *  See the detailed documentation in the
50  *  \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
51  */
52
53 /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
54  *  \ingroup flac_encoder
55  *
56  *  \brief
57  *  This module contains the functions which implement the seekable stream
58  *  encoder.
59  *
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
70  *   to be written.
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().
77  *
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()).
86  *
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.
90  *
91  * \note
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
96  * there.
97  *
98  * \note
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.
104  *
105  * \note
106  * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
107  * defaults, including the callbacks.
108  *
109  * \{
110  */
111
112
113 /** State values for a FLAC__SeekableStreamEncoder
114  *
115  *  The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
116  */
117 typedef enum {
118
119         FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
120         /**< The encoder is in the normal OK state. */
121
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().
125          */
126
127         FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
128         /**< Memory allocation failed. */
129
130         FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
131         /**< The write callback returned an error. */
132
133         FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
134         /**< The read callback returned an error. */
135
136         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
137         /**< The seek callback returned an error. */
138
139         FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
140         /**< The tell callback returned an error. */
141
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.
146          */
147
148         FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
149         /**< FLAC__seekable_stream_encoder_init() was called without all
150          * callbacks being set.
151          */
152
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().
156          */
157
158         FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
159         /**< The encoder is in the uninitialized state. */
160
161 } FLAC__SeekableStreamEncoderState;
162
163 /** Maps a FLAC__SeekableStreamEncoderState to a C string.
164  *
165  *  Using a FLAC__SeekableStreamEncoderState as the index to this array
166  *  will give the string equivalent.  The contents should not be modified.
167  */
168 extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
169
170
171 /** Return values for the FLAC__SeekableStreamEncoder seek callback.
172  */
173 typedef enum {
174
175         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
176         /**< The seek was OK and encoding can continue. */
177
178         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
179         /**< An unrecoverable error occurred.  The encoder will return from the process call. */
180
181 } FLAC__SeekableStreamEncoderSeekStatus;
182
183 /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
184  *
185  *  Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
186  *  will give the string equivalent.  The contents should not be modified.
187  */
188 extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
189
190
191 /** Return values for the FLAC__SeekableStreamEncoder tell callback.
192  */
193 typedef enum {
194
195         FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK,
196         /**< The tell was OK and encoding can continue. */
197
198         FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR
199         /**< An unrecoverable error occurred.  The encoder will return from the process call. */
200
201 } FLAC__SeekableStreamEncoderTellStatus;
202
203 /** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string.
204  *
205  *  Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array
206  *  will give the string equivalent.  The contents should not be modified.
207  */
208 extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[];
209
210
211 /***********************************************************************
212  *
213  * class FLAC__SeekableStreamEncoder
214  *
215  ***********************************************************************/
216
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.
222  */
223 typedef struct {
224         struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
225         struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
226 } FLAC__SeekableStreamEncoder;
227
228 /** Signature for the seek callback.
229  *  See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
230  *
231  * \param  encoder  The encoder instance calling the callback.
232  * \param  absolute_byte_offset  The offset from the beginning of the stream
233  *                               to seek to.
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.
238  */
239 typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
240
241 /** Signature for the tell callback.
242  *  See FLAC__seekable_stream_encoder_set_tell_callback() for more info.
243  *
244  * \warning
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.
252  *
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.
260  */
261 typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
262
263 /** Signature for the write callback.
264  *  See FLAC__seekable_stream_encoder_set_write_callback()
265  *  and FLAC__StreamEncoderWriteCallback for more info.
266  *
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.
278  */
279 typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
280
281
282 /***********************************************************************
283  *
284  * Class constructor/destructor
285  *
286  ***********************************************************************/
287
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.
291  *
292  * \retval FLAC__SeekableStreamEncoder*
293  *    \c NULL if there was an error allocating memory, else the new instance.
294  */
295 FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
296
297 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
298  *
299  * \param encoder  A pointer to an existing encoder.
300  * \assert
301  *    \code encoder != NULL \endcode
302  */
303 FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
304
305 /***********************************************************************
306  *
307  * Public class method prototypes
308  *
309  ***********************************************************************/
310
311 /** This is inherited from FLAC__StreamEncoder; see
312  *  FLAC__stream_encoder_set_verify().
313  *
314  * \default \c true
315  * \param  encoder  An encoder instance to set.
316  * \param  value    See above.
317  * \assert
318  *    \code encoder != NULL \endcode
319  * \retval FLAC__bool
320  *    \c false if the encoder is already initialized, else \c true.
321  */
322 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
323
324 /** This is inherited from FLAC__StreamEncoder; see
325  *  FLAC__stream_encoder_set_streamable_subset().
326  *
327  * \default \c true
328  * \param  encoder  An encoder instance to set.
329  * \param  value    See above.
330  * \assert
331  *    \code encoder != NULL \endcode
332  * \retval FLAC__bool
333  *    \c false if the encoder is already initialized, else \c true.
334  */
335 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
336
337 /** This is inherited from FLAC__StreamEncoder; see
338  *  FLAC__stream_encoder_set_do_mid_side_stereo().
339  *
340  * \default \c false
341  * \param  encoder  An encoder instance to set.
342  * \param  value    See above.
343  * \assert
344  *    \code encoder != NULL \endcode
345  * \retval FLAC__bool
346  *    \c false if the encoder is already initialized, else \c true.
347  */
348 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
349
350 /** This is inherited from FLAC__StreamEncoder; see
351  *  FLAC__stream_encoder_set_loose_mid_side_stereo().
352  *
353  * \default \c false
354  * \param  encoder  An encoder instance to set.
355  * \param  value    See above.
356  * \assert
357  *    \code encoder != NULL \endcode
358  * \retval FLAC__bool
359  *    \c false if the encoder is already initialized, else \c true.
360  */
361 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
362
363 /** This is inherited from FLAC__StreamEncoder; see
364  *  FLAC__stream_encoder_set_channels().
365  *
366  * \default \c 2
367  * \param  encoder  An encoder instance to set.
368  * \param  value    See above.
369  * \assert
370  *    \code encoder != NULL \endcode
371  * \retval FLAC__bool
372  *    \c false if the encoder is already initialized, else \c true.
373  */
374 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
375
376 /** This is inherited from FLAC__StreamEncoder; see
377  *  FLAC__stream_encoder_set_bits_per_sample().
378  *
379  * \warning
380  * Do not feed the encoder data that is wider than the value you
381  * set here or you will generate an invalid stream.
382  *
383  * \default \c 16
384  * \param  encoder  An encoder instance to set.
385  * \param  value    See above.
386  * \assert
387  *    \code encoder != NULL \endcode
388  * \retval FLAC__bool
389  *    \c false if the encoder is already initialized, else \c true.
390  */
391 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
392
393 /** This is inherited from FLAC__StreamEncoder; see
394  *  FLAC__stream_encoder_set_sample_rate().
395  *
396  * \default \c 44100
397  * \param  encoder  An encoder instance to set.
398  * \param  value    See above.
399  * \assert
400  *    \code encoder != NULL \endcode
401  * \retval FLAC__bool
402  *    \c false if the encoder is already initialized, else \c true.
403  */
404 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
405
406 /** This is inherited from FLAC__StreamEncoder; see
407  *  FLAC__stream_encoder_set_blocksize().
408  *
409  * \default \c 1152
410  * \param  encoder  An encoder instance to set.
411  * \param  value    See above.
412  * \assert
413  *    \code encoder != NULL \endcode
414  * \retval FLAC__bool
415  *    \c false if the encoder is already initialized, else \c true.
416  */
417 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
418
419 /** This is inherited from FLAC__StreamEncoder; see
420  *  FLAC__stream_encoder_set_max_lpc_order().
421  *
422  * \default \c 0
423  * \param  encoder  An encoder instance to set.
424  * \param  value    See above.
425  * \assert
426  *    \code encoder != NULL \endcode
427  * \retval FLAC__bool
428  *    \c false if the encoder is already initialized, else \c true.
429  */
430 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
431
432 /** This is inherited from FLAC__StreamEncoder; see
433  *  FLAC__stream_encoder_set_qlp_coeff_precision().
434  *
435  * \note
436  * In the current implementation, qlp_coeff_precision + bits_per_sample must
437  * be less than 32.
438  *
439  * \default \c 0
440  * \param  encoder  An encoder instance to set.
441  * \param  value    See above.
442  * \assert
443  *    \code encoder != NULL \endcode
444  * \retval FLAC__bool
445  *    \c false if the encoder is already initialized, else \c true.
446  */
447 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
448
449 /** This is inherited from FLAC__StreamEncoder; see
450  *  FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
451  *
452  * \default \c false
453  * \param  encoder  An encoder instance to set.
454  * \param  value    See above.
455  * \assert
456  *    \code encoder != NULL \endcode
457  * \retval FLAC__bool
458  *    \c false if the encoder is already initialized, else \c true.
459  */
460 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
461
462 /** This is inherited from FLAC__StreamEncoder; see
463  *  FLAC__stream_encoder_set_do_escape_coding().
464  *
465  * \default \c false
466  * \param  encoder  An encoder instance to set.
467  * \param  value    See above.
468  * \assert
469  *    \code encoder != NULL \endcode
470  * \retval FLAC__bool
471  *    \c false if the encoder is already initialized, else \c true.
472  */
473 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
474
475 /** This is inherited from FLAC__StreamEncoder; see
476  *  FLAC__stream_encoder_set_do_exhaustive_model_search().
477  *
478  * \default \c false
479  * \param  encoder  An encoder instance to set.
480  * \param  value    See above.
481  * \assert
482  *    \code encoder != NULL \endcode
483  * \retval FLAC__bool
484  *    \c false if the encoder is already initialized, else \c true.
485  */
486 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
487
488 /** This is inherited from FLAC__StreamEncoder; see
489  *  FLAC__stream_encoder_set_min_residual_partition_order().
490  *
491  * \default \c 0
492  * \param  encoder  An encoder instance to set.
493  * \param  value    See above.
494  * \assert
495  *    \code encoder != NULL \endcode
496  * \retval FLAC__bool
497  *    \c false if the encoder is already initialized, else \c true.
498  */
499 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
500
501 /** This is inherited from FLAC__StreamEncoder; see
502  *  FLAC__stream_encoder_set_max_residual_partition_order().
503  *
504  * \default \c 0
505  * \param  encoder  An encoder instance to set.
506  * \param  value    See above.
507  * \assert
508  *    \code encoder != NULL \endcode
509  * \retval FLAC__bool
510  *    \c false if the encoder is already initialized, else \c true.
511  */
512 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
513
514 /** This is inherited from FLAC__StreamEncoder; see
515  *  FLAC__stream_encoder_set_rice_parameter_search_dist().
516  *
517  * \default \c 0
518  * \param  encoder  An encoder instance to set.
519  * \param  value    See above.
520  * \assert
521  *    \code encoder != NULL \endcode
522  * \retval FLAC__bool
523  *    \c false if the encoder is already initialized, else \c true.
524  */
525 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
526
527 /** This is inherited from FLAC__StreamEncoder; see
528  *  FLAC__stream_encoder_set_total_samples_estimate().
529  *
530  * \default \c 0
531  * \param  encoder  An encoder instance to set.
532  * \param  value    See above.
533  * \assert
534  *    \code encoder != NULL \endcode
535  * \retval FLAC__bool
536  *    \c false if the encoder is already initialized, else \c true.
537  */
538 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
539
540 /** This is inherited from FLAC__StreamEncoder; see
541  *  FLAC__stream_encoder_set_metadata().
542  *
543  * \note
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_*().
554  *
555  * \note
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
559  * encoding.
560  *
561  * \default \c NULL, 0
562  * \param  encoder     An encoder instance to set.
563  * \param  metadata    See above.
564  * \param  num_blocks  See above.
565  * \assert
566  *    \code encoder != NULL \endcode
567  * \retval FLAC__bool
568  *    \c false if the encoder is already initialized, else \c true.
569  */
570 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
571
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.
576  *
577  * \note
578  * The callback is mandatory and must be set before initialization.
579  *
580  * \default \c NULL
581  * \param  encoder  An encoder instance to set.
582  * \param  value    See above.
583  * \assert
584  *    \code encoder != NULL \endcode
585  *    \code value != NULL \endcode
586  * \retval FLAC__bool
587  *    \c false if the encoder is already initialized, else \c true.
588  */
589 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
590
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.
594  *
595  * \note
596  * The callback is mandatory and must be set before initialization.
597  *
598  * \default \c NULL
599  * \param  encoder  An encoder instance to set.
600  * \param  value    See above.
601  * \assert
602  *    \code encoder != NULL \endcode
603  *    \code value != NULL \endcode
604  * \retval FLAC__bool
605  *    \c false if the encoder is already initialized, else \c true.
606  */
607 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value);
608
609 /** Set the write callback.
610  *  This is inherited from FLAC__StreamEncoder; see
611  *  FLAC__stream_encoder_set_write_callback().
612  *
613  * \note
614  * The callback is mandatory and must be set before initialization.
615  *
616  * \default \c NULL
617  * \param  encoder  An encoder instance to set.
618  * \param  value    See above.
619  * \assert
620  *    \code encoder != NULL \endcode
621  *    \code value != NULL \endcode
622  * \retval FLAC__bool
623  *    \c false if the encoder is already initialized, else \c true.
624  */
625 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
626
627 /** Set the client data to be passed back to callbacks.
628  *  This value will be supplied to callbacks in their \a client_data
629  *  argument.
630  *
631  * \default \c NULL
632  * \param  encoder  An encoder instance to set.
633  * \param  value    See above.
634  * \assert
635  *    \code encoder != NULL \endcode
636  * \retval FLAC__bool
637  *    \c false if the encoder is already initialized, else \c true.
638  */
639 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
640
641 /** Get the current encoder state.
642  *
643  * \param  encoder  An encoder instance to query.
644  * \assert
645  *    \code encoder != NULL \endcode
646  * \retval FLAC__SeekableStreamEncoderState
647  *    The current encoder state.
648  */
649 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
650
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.
654  *
655  * \param  encoder  An encoder instance to query.
656  * \assert
657  *    \code encoder != NULL \endcode
658  * \retval FLAC__StreamEncoderState
659  *    The stream encoder state.
660  */
661 FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
662
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.
667  *
668  * \param  encoder  An encoder instance to query.
669  * \assert
670  *    \code encoder != NULL \endcode
671  * \retval FLAC__StreamDecoderState
672  *    The stream encoder state.
673  */
674 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
675
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.
680  *
681  * \param  encoder  A encoder instance to query.
682  * \assert
683  *    \code encoder != NULL \endcode
684  * \retval const char *
685  *    The encoder state as a C string.  Do not modify the contents.
686  */
687 FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
688
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.
695  *
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.
704  * \assert
705  *    \code encoder != NULL \endcode
706  */
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);
708
709 /** Get the "verify" flag.
710  *  This is inherited from FLAC__StreamEncoder; see
711  *  FLAC__stream_encoder_get_verify().
712  *
713  * \param  encoder  An encoder instance to query.
714  * \assert
715  *    \code encoder != NULL \endcode
716  * \retval FLAC__bool
717  *    See FLAC__seekable_stream_encoder_set_verify().
718  */
719 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
720
721 /** Get the "streamable subset" flag.
722  *  This is inherited from FLAC__StreamEncoder; see
723  *  FLAC__stream_encoder_get_streamable_subset().
724  *
725  * \param  encoder  An encoder instance to query.
726  * \assert
727  *    \code encoder != NULL \endcode
728  * \retval FLAC__bool
729  *    See FLAC__seekable_stream_encoder_set_streamable_subset().
730  */
731 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
732
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().
736  *
737  * \param  encoder  An encoder instance to query.
738  * \assert
739  *    \code encoder != NULL \endcode
740  * \retval FLAC__bool
741  *    See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
742  */
743 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
744
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().
748  *
749  * \param  encoder  An encoder instance to query.
750  * \assert
751  *    \code encoder != NULL \endcode
752  * \retval FLAC__bool
753  *    See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
754  */
755 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
756
757 /** Get the number of input channels being processed.
758  *  This is inherited from FLAC__StreamEncoder; see
759  *  FLAC__stream_encoder_get_channels().
760  *
761  * \param  encoder  An encoder instance to query.
762  * \assert
763  *    \code encoder != NULL \endcode
764  * \retval unsigned
765  *    See FLAC__seekable_stream_encoder_set_channels().
766  */
767 FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
768
769 /** Get the input sample resolution setting.
770  *  This is inherited from FLAC__StreamEncoder; see
771  *  FLAC__stream_encoder_get_bits_per_sample().
772  *
773  * \param  encoder  An encoder instance to query.
774  * \assert
775  *    \code encoder != NULL \endcode
776  * \retval unsigned
777  *    See FLAC__seekable_stream_encoder_set_bits_per_sample().
778  */
779 FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
780
781 /** Get the input sample rate setting.
782  *  This is inherited from FLAC__StreamEncoder; see
783  *  FLAC__stream_encoder_get_sample_rate().
784  *
785  * \param  encoder  An encoder instance to query.
786  * \assert
787  *    \code encoder != NULL \endcode
788  * \retval unsigned
789  *    See FLAC__seekable_stream_encoder_set_sample_rate().
790  */
791 FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
792
793 /** Get the blocksize setting.
794  *  This is inherited from FLAC__StreamEncoder; see
795  *  FLAC__stream_encoder_get_blocksize().
796  *
797  * \param  encoder  An encoder instance to query.
798  * \assert
799  *    \code encoder != NULL \endcode
800  * \retval unsigned
801  *    See FLAC__seekable_stream_encoder_set_blocksize().
802  */
803 FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
804
805 /** Get the maximum LPC order setting.
806  *  This is inherited from FLAC__StreamEncoder; see
807  *  FLAC__stream_encoder_get_max_lpc_order().
808  *
809  * \param  encoder  An encoder instance to query.
810  * \assert
811  *    \code encoder != NULL \endcode
812  * \retval unsigned
813  *    See FLAC__seekable_stream_encoder_set_max_lpc_order().
814  */
815 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
816
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().
820  *
821  * \param  encoder  An encoder instance to query.
822  * \assert
823  *    \code encoder != NULL \endcode
824  * \retval unsigned
825  *    See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
826  */
827 FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
828
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().
832  *
833  * \param  encoder  An encoder instance to query.
834  * \assert
835  *    \code encoder != NULL \endcode
836  * \retval FLAC__bool
837  *    See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
838  */
839 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
840
841 /** Get the "escape coding" flag.
842  *  This is inherited from FLAC__StreamEncoder; see
843  *  FLAC__stream_encoder_get_do_escape_coding().
844  *
845  * \param  encoder  An encoder instance to query.
846  * \assert
847  *    \code encoder != NULL \endcode
848  * \retval FLAC__bool
849  *    See FLAC__seekable_stream_encoder_set_do_escape_coding().
850  */
851 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
852
853 /** Get the exhaustive model search flag.
854  *  This is inherited from FLAC__StreamEncoder; see
855  *  FLAC__stream_encoder_get_do_exhaustive_model_search().
856  *
857  * \param  encoder  An encoder instance to query.
858  * \assert
859  *    \code encoder != NULL \endcode
860  * \retval FLAC__bool
861  *    See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
862  */
863 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
864
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().
868  *
869  * \param  encoder  An encoder instance to query.
870  * \assert
871  *    \code encoder != NULL \endcode
872  * \retval unsigned
873  *    See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
874  */
875 FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
876
877 /** Get maximum residual partition order setting.
878  *  This is inherited from FLAC__StreamEncoder; see
879  *  FLAC__stream_encoder_get_max_residual_partition_order().
880  *
881  * \param  encoder  An encoder instance to query.
882  * \assert
883  *    \code encoder != NULL \endcode
884  * \retval unsigned
885  *    See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
886  */
887 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
888
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().
892  *
893  * \param  encoder  An encoder instance to query.
894  * \assert
895  *    \code encoder != NULL \endcode
896  * \retval unsigned
897  *    See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
898  */
899 FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
900
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().
904  *
905  * \param  encoder  An encoder instance to query.
906  * \assert
907  *    \code encoder != NULL \endcode
908  * \retval FLAC__uint64
909  *    See FLAC__seekable_stream_encoder_set_total_samples_estimate().
910  */
911 FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
912
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.
919  *
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
922  *  metadata.
923  *
924  * \param  encoder  An uninitialized encoder instance.
925  * \assert
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.
930  */
931 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
932
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.
937  *
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().
942  *
943  * \param  encoder  An uninitialized encoder instance.
944  * \assert
945  *    \code encoder != NULL \endcode
946  */
947 FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
948
949 /** Submit data for encoding.
950  *  This is inherited from FLAC__StreamEncoder; see
951  *  FLAC__stream_encoder_process().
952  *
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.
956  * \assert
957  *    \code encoder != NULL \endcode
958  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
959  * \retval FLAC__bool
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
962  *    went wrong.
963  */
964 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
965
966 /** Submit data for encoding.
967  *  This is inherited from FLAC__StreamEncoder; see
968  *  FLAC__stream_encoder_process_interleaved().
969  *
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.
976  * \assert
977  *    \code encoder != NULL \endcode
978  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
979  * \retval FLAC__bool
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
982  *    went wrong.
983  */
984 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
985
986 /* \} */
987
988 #ifdef __cplusplus
989 }
990 #endif
991
992 #endif