Add 2003 to copyright notice
[flac.git] / include / FLAC / seekable_stream_encoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2002,2003  Josh Coalson
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA  02111-1307, USA.
18  */
19
20 #ifndef FLAC__SEEKABLE_STREAM_ENCODER_H
21 #define FLAC__SEEKABLE_STREAM_ENCODER_H
22
23 #include "export.h"
24 #include "stream_encoder.h"
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30
31 /** \file include/FLAC/seekable_stream_encoder.h
32  *
33  *  \brief
34  *  This module contains the functions which implement the seekable stream
35  *  encoder.
36  *
37  *  See the detailed documentation in the
38  *  \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
39  */
40
41 /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
42  *  \ingroup flac_encoder
43  *
44  *  \brief
45  *  This module contains the functions which implement the seekable stream
46  *  encoder.
47  *
48  * The basic usage of this encoder is as follows:
49  * - The program creates an instance of an encoder using
50  *   FLAC__seekable_stream_encoder_new().
51  * - The program overrides the default settings and sets callbacks using
52  *   FLAC__seekable_stream_encoder_set_*() functions.
53  * - The program initializes the instance to validate the settings and
54  *   prepare for encoding using FLAC__seekable_stream_encoder_init().
55  * - The program calls FLAC__seekable_stream_encoder_process() or
56  *   FLAC__seekable_stream_encoder_process_interleaved() to encode data, which
57  *   subsequently calls the callbacks when there is encoder data ready
58  *   to be written.
59  * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(),
60  *   which causes the encoder to encode any data still in its input pipe,
61  *   rewrite the metadata with the final encoding statistics, and finally
62  *   reset the encoder to the uninitialized state.
63  * - The instance may be used again or deleted with
64  *   FLAC__seekable_stream_encoder_delete().
65  *
66  * The seekable stream encoder is a wrapper around the
67  * \link flac_stream_encoder stream encoder \endlink with callbacks for
68  * seeking the output.  This allows the encoder to go back and rewrite
69  * some of the metadata after encoding if necessary, and provides the
70  * metadata callback of the stream encoder internally.  However, you
71  * must provide a seek callback (see
72  * FLAC__seekable_stream_encoder_set_seek_callback()).
73  *
74  * Make sure to read the detailed description of the
75  * \link flac_stream_encoder stream encoder module \endlink since the
76  * seekable stream encoder inherits much of its behavior.
77  *
78  * \note
79  * If you are writing the FLAC data to a file, make sure it is open
80  * for update (e.g. mode "w+" for stdio streams).  This is because after
81  * the first encoding pass, the encoder will try to seek back to the
82  * beginning of the stream, to the STREAMINFO block, to write some data
83  * there.
84  *
85  * \note
86  * The "set" functions may only be called when the encoder is in the
87  * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
88  * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
89  * before FLAC__seekable_stream_encoder_init().  If this is the case they will
90  * return \c true, otherwise \c false.
91  *
92  * \note
93  * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
94  * defaults, including the callbacks.
95  *
96  * \{
97  */
98
99
100 /** State values for a FLAC__SeekableStreamEncoder
101  *
102  *  The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
103  */
104 typedef enum {
105
106         FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
107         /**< The encoder is in the normal OK state. */
108
109         FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
110         /**< An error occurred in the underlying stream encoder;
111          * check FLAC__seekable_stream_encoder_get_stream_encoder_state().
112          */
113
114         FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
115         /**< Memory allocation failed. */
116
117         FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
118         /**< The write callback returned an error. */
119
120         FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
121         /**< The read callback returned an error. */
122
123         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
124         /**< The seek callback returned an error. */
125
126         FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
127         /**< FLAC__seekable_stream_encoder_init() was called when the encoder was
128          * already initialized, usually because
129          * FLAC__seekable_stream_encoder_finish() was not called.
130          */
131
132         FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
133         /**< FLAC__seekable_stream_encoder_init() was called without all
134          * callbacks being set.
135          */
136
137         FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
138         /**< An invalid seek table was passed is the metadata to
139          * FLAC__seekable_stream_encoder_set_metadata().
140          */
141
142         FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
143         /**< The encoder is in the uninitialized state. */
144
145 } FLAC__SeekableStreamEncoderState;
146
147 /** Maps a FLAC__SeekableStreamEncoderState to a C string.
148  *
149  *  Using a FLAC__SeekableStreamEncoderState as the index to this array
150  *  will give the string equivalent.  The contents should not be modified.
151  */
152 extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
153
154
155 /** Return values for the FLAC__SeekableStreamEncoder seek callback.
156  */
157 typedef enum {
158
159         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
160         /**< The seek was OK and encoding can continue. */
161
162         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
163         /**< An unrecoverable error occurred.  The encoder will return from the process call. */
164
165 } FLAC__SeekableStreamEncoderSeekStatus;
166
167 /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
168  *
169  *  Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
170  *  will give the string equivalent.  The contents should not be modified.
171  */
172 extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
173
174
175 /***********************************************************************
176  *
177  * class FLAC__SeekableStreamEncoder
178  *
179  ***********************************************************************/
180
181 struct FLAC__SeekableStreamEncoderProtected;
182 struct FLAC__SeekableStreamEncoderPrivate;
183 /** The opaque structure definition for the seekable stream encoder type.
184  *  See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
185  *  for a detailed description.
186  */
187 typedef struct {
188         struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
189         struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
190 } FLAC__SeekableStreamEncoder;
191
192 /** Signature for the seek callback.
193  *  See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
194  *
195  * \param  encoder  The encoder instance calling the callback.
196  * \param  absolute_byte_offset  The offset from the beginning of the stream
197  *                               to seek to.
198  * \param  client_data  The callee's client data set through
199  *                      FLAC__seekable_stream_encoder_set_client_data().
200  * \retval FLAC__SeekableStreamEncoderSeekStatus
201  *    The callee's return status.
202  */
203 typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
204
205 /** Signature for the write callback.
206  *  See FLAC__seekable_stream_encoder_set_write_callback()
207  *  and FLAC__StreamEncoderWriteCallback for more info.
208  *
209  * \param  encoder  The encoder instance calling the callback.
210  * \param  buffer   An array of encoded data of length \a bytes.
211  * \param  bytes    The byte length of \a buffer.
212  * \param  samples  The number of samples encoded by \a buffer.
213  *                  \c 0 has a special meaning; see
214  *                  FLAC__stream_encoder_set_write_callback().
215  * \param  current_frame  The number of current frame being encoded.
216  * \param  client_data  The callee's client data set through
217  *                      FLAC__seekable_stream_encoder_set_client_data().
218  * \retval FLAC__StreamEncoderWriteStatus
219  *    The callee's return status.
220  */
221 typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
222
223
224 /***********************************************************************
225  *
226  * Class constructor/destructor
227  *
228  ***********************************************************************/
229
230 /** Create a new seekable stream encoder instance.  The instance is created with
231  *  default settings; see the individual FLAC__seekable_stream_encoder_set_*()
232  *  functions for each setting's default.
233  *
234  * \retval FLAC__SeekableStreamEncoder*
235  *    \c NULL if there was an error allocating memory, else the new instance.
236  */
237 FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
238
239 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
240  *
241  * \param encoder  A pointer to an existing encoder.
242  * \assert
243  *    \code encoder != NULL \endcode
244  */
245 FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
246
247 /***********************************************************************
248  *
249  * Public class method prototypes
250  *
251  ***********************************************************************/
252
253 /** This is inherited from FLAC__StreamEncoder; see
254  *  FLAC__stream_encoder_set_verify().
255  *
256  * \default \c true
257  * \param  encoder  An encoder instance to set.
258  * \param  value    See above.
259  * \assert
260  *    \code encoder != NULL \endcode
261  * \retval FLAC__bool
262  *    \c false if the encoder is already initialized, else \c true.
263  */
264 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
265
266 /** This is inherited from FLAC__StreamEncoder; see
267  *  FLAC__stream_encoder_set_streamable_subset().
268  *
269  * \default \c true
270  * \param  encoder  An encoder instance to set.
271  * \param  value    See above.
272  * \assert
273  *    \code encoder != NULL \endcode
274  * \retval FLAC__bool
275  *    \c false if the encoder is already initialized, else \c true.
276  */
277 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
278
279 /** This is inherited from FLAC__StreamEncoder; see
280  *  FLAC__stream_encoder_set_do_mid_side_stereo().
281  *
282  * \default \c false
283  * \param  encoder  An encoder instance to set.
284  * \param  value    See above.
285  * \assert
286  *    \code encoder != NULL \endcode
287  * \retval FLAC__bool
288  *    \c false if the encoder is already initialized, else \c true.
289  */
290 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
291
292 /** This is inherited from FLAC__StreamEncoder; see
293  *  FLAC__stream_encoder_set_loose_mid_side_stereo().
294  *
295  * \default \c false
296  * \param  encoder  An encoder instance to set.
297  * \param  value    See above.
298  * \assert
299  *    \code encoder != NULL \endcode
300  * \retval FLAC__bool
301  *    \c false if the encoder is already initialized, else \c true.
302  */
303 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
304
305 /** This is inherited from FLAC__StreamEncoder; see
306  *  FLAC__stream_encoder_set_channels().
307  *
308  * \default \c 2
309  * \param  encoder  An encoder instance to set.
310  * \param  value    See above.
311  * \assert
312  *    \code encoder != NULL \endcode
313  * \retval FLAC__bool
314  *    \c false if the encoder is already initialized, else \c true.
315  */
316 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
317
318 /** This is inherited from FLAC__StreamEncoder; see
319  *  FLAC__stream_encoder_set_bits_per_sample().
320  *
321  * \warning
322  * Do not feed the encoder data that is wider than the value you
323  * set here or you will generate an invalid stream.
324  *
325  * \default \c 16
326  * \param  encoder  An encoder instance to set.
327  * \param  value    See above.
328  * \assert
329  *    \code encoder != NULL \endcode
330  * \retval FLAC__bool
331  *    \c false if the encoder is already initialized, else \c true.
332  */
333 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
334
335 /** This is inherited from FLAC__StreamEncoder; see
336  *  FLAC__stream_encoder_set_sample_rate().
337  *
338  * \default \c 44100
339  * \param  encoder  An encoder instance to set.
340  * \param  value    See above.
341  * \assert
342  *    \code encoder != NULL \endcode
343  * \retval FLAC__bool
344  *    \c false if the encoder is already initialized, else \c true.
345  */
346 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
347
348 /** This is inherited from FLAC__StreamEncoder; see
349  *  FLAC__stream_encoder_set_blocksize().
350  *
351  * \default \c 1152
352  * \param  encoder  An encoder instance to set.
353  * \param  value    See above.
354  * \assert
355  *    \code encoder != NULL \endcode
356  * \retval FLAC__bool
357  *    \c false if the encoder is already initialized, else \c true.
358  */
359 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
360
361 /** This is inherited from FLAC__StreamEncoder; see
362  *  FLAC__stream_encoder_set_max_lpc_order().
363  *
364  * \default \c 0
365  * \param  encoder  An encoder instance to set.
366  * \param  value    See above.
367  * \assert
368  *    \code encoder != NULL \endcode
369  * \retval FLAC__bool
370  *    \c false if the encoder is already initialized, else \c true.
371  */
372 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
373
374 /** This is inherited from FLAC__StreamEncoder; see
375  *  FLAC__stream_encoder_set_qlp_coeff_precision().
376  *
377  * \note
378  * In the current implementation, qlp_coeff_precision + bits_per_sample must
379  * be less than 32.
380  *
381  * \default \c 0
382  * \param  encoder  An encoder instance to set.
383  * \param  value    See above.
384  * \assert
385  *    \code encoder != NULL \endcode
386  * \retval FLAC__bool
387  *    \c false if the encoder is already initialized, else \c true.
388  */
389 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
390
391 /** This is inherited from FLAC__StreamEncoder; see
392  *  FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
393  *
394  * \default \c false
395  * \param  encoder  An encoder instance to set.
396  * \param  value    See above.
397  * \assert
398  *    \code encoder != NULL \endcode
399  * \retval FLAC__bool
400  *    \c false if the encoder is already initialized, else \c true.
401  */
402 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
403
404 /** This is inherited from FLAC__StreamEncoder; see
405  *  FLAC__stream_encoder_set_do_escape_coding().
406  *
407  * \default \c false
408  * \param  encoder  An encoder instance to set.
409  * \param  value    See above.
410  * \assert
411  *    \code encoder != NULL \endcode
412  * \retval FLAC__bool
413  *    \c false if the encoder is already initialized, else \c true.
414  */
415 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
416
417 /** This is inherited from FLAC__StreamEncoder; see
418  *  FLAC__stream_encoder_set_do_exhaustive_model_search().
419  *
420  * \default \c false
421  * \param  encoder  An encoder instance to set.
422  * \param  value    See above.
423  * \assert
424  *    \code encoder != NULL \endcode
425  * \retval FLAC__bool
426  *    \c false if the encoder is already initialized, else \c true.
427  */
428 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
429
430 /** This is inherited from FLAC__StreamEncoder; see
431  *  FLAC__stream_encoder_set_min_residual_partition_order().
432  *
433  * \default \c 0
434  * \param  encoder  An encoder instance to set.
435  * \param  value    See above.
436  * \assert
437  *    \code encoder != NULL \endcode
438  * \retval FLAC__bool
439  *    \c false if the encoder is already initialized, else \c true.
440  */
441 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
442
443 /** This is inherited from FLAC__StreamEncoder; see
444  *  FLAC__stream_encoder_set_max_residual_partition_order().
445  *
446  * \default \c 0
447  * \param  encoder  An encoder instance to set.
448  * \param  value    See above.
449  * \assert
450  *    \code encoder != NULL \endcode
451  * \retval FLAC__bool
452  *    \c false if the encoder is already initialized, else \c true.
453  */
454 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
455
456 /** This is inherited from FLAC__StreamEncoder; see
457  *  FLAC__stream_encoder_set_rice_parameter_search_dist().
458  *
459  * \default \c 0
460  * \param  encoder  An encoder instance to set.
461  * \param  value    See above.
462  * \assert
463  *    \code encoder != NULL \endcode
464  * \retval FLAC__bool
465  *    \c false if the encoder is already initialized, else \c true.
466  */
467 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
468
469 /** This is inherited from FLAC__StreamEncoder; see
470  *  FLAC__stream_encoder_set_total_samples_estimate().
471  *
472  * \default \c 0
473  * \param  encoder  An encoder instance to set.
474  * \param  value    See above.
475  * \assert
476  *    \code encoder != NULL \endcode
477  * \retval FLAC__bool
478  *    \c false if the encoder is already initialized, else \c true.
479  */
480 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
481
482 /** This is inherited from FLAC__StreamEncoder; see
483  *  FLAC__stream_encoder_set_metadata().
484  *
485  * \note
486  * SEEKTABLE blocks are handled specially.  Since you will not know
487  * the values for the seek point stream offsets, you should pass in
488  * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
489  * required sample numbers (or placeholder points), with \c 0 for the
490  * \a frame_samples and \a stream_offset fields for each point.  While
491  * encoding, the encoder will fill them in for you and when encoding
492  * is finished, it will seek back and write the real values into the
493  * SEEKTABLE block in the stream.  There are helper routines for
494  * manipulating seektable template blocks; see metadata.h:
495  * FLAC__metadata_object_seektable_template_*().
496  *
497  * \note
498  * The encoder instance \b will modify the first \c SEEKTABLE block
499  * as it transforms the template to a valid seektable while encoding,
500  * but it is still up to the caller to free all metadata blocks after
501  * encoding.
502  *
503  * \default \c NULL, 0
504  * \param  encoder     An encoder instance to set.
505  * \param  metadata    See above.
506  * \param  num_blocks  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_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
513
514 /** Set the seek callback.
515  *  The supplied function will be called when the encoder needs to seek
516  *  the output stream.  The encoder will pass the absolute byte offset
517  *  to seek to, 0 meaning the beginning of the stream.
518  *
519  * \note
520  * The callback is mandatory and must be set before initialization.
521  *
522  * \default \c NULL
523  * \param  encoder  An encoder instance to set.
524  * \param  value    See above.
525  * \assert
526  *    \code encoder != NULL \endcode
527  *    \code value != NULL \endcode
528  * \retval FLAC__bool
529  *    \c false if the encoder is already initialized, else \c true.
530  */
531 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
532
533 /** Set the write callback.
534  *  This is inherited from FLAC__StreamEncoder; see
535  *  FLAC__stream_encoder_set_write_callback().
536  *
537  * \note
538  * The callback is mandatory and must be set before initialization.
539  *
540  * \default \c NULL
541  * \param  encoder  An encoder instance to set.
542  * \param  value    See above.
543  * \assert
544  *    \code encoder != NULL \endcode
545  *    \code value != NULL \endcode
546  * \retval FLAC__bool
547  *    \c false if the encoder is already initialized, else \c true.
548  */
549 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
550
551 /** Set the client data to be passed back to callbacks.
552  *  This value will be supplied to callbacks in their \a client_data
553  *  argument.
554  *
555  * \default \c NULL
556  * \param  encoder  An encoder instance to set.
557  * \param  value    See above.
558  * \assert
559  *    \code encoder != NULL \endcode
560  * \retval FLAC__bool
561  *    \c false if the encoder is already initialized, else \c true.
562  */
563 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
564
565 /** Get the current encoder state.
566  *
567  * \param  encoder  An encoder instance to query.
568  * \assert
569  *    \code encoder != NULL \endcode
570  * \retval FLAC__SeekableStreamEncoderState
571  *    The current encoder state.
572  */
573 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
574
575 /** Get the state of the underlying stream encoder.
576  *  Useful when the seekable stream encoder state is
577  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
578  *
579  * \param  encoder  An encoder instance to query.
580  * \assert
581  *    \code encoder != NULL \endcode
582  * \retval FLAC__StreamEncoderState
583  *    The stream encoder state.
584  */
585 FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
586
587 /** Get the state of the underlying stream encoder's verify decoder.
588  *  Useful when the seekable stream encoder state is
589  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
590  *  stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
591  *
592  * \param  encoder  An encoder instance to query.
593  * \assert
594  *    \code encoder != NULL \endcode
595  * \retval FLAC__StreamDecoderState
596  *    The stream encoder state.
597  */
598 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
599
600 /** Get the current encoder state as a C string.
601  *  This version automatically resolves
602  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the
603  *  stream encoder's state.
604  *
605  * \param  encoder  A encoder instance to query.
606  * \assert
607  *    \code encoder != NULL \endcode
608  * \retval const char *
609  *    The encoder state as a C string.  Do not modify the contents.
610  */
611 FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
612
613 /** Get relevant values about the nature of a verify decoder error.
614  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
615  *  Useful when the seekable stream encoder state is
616  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
617  *  stream encoder state is
618  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
619  *
620  * \param  encoder  An encoder instance to query.
621  * \param  absolute_sample  The absolute sample number of the mismatch.
622  * \param  frame_number  The number of the frame in which the mismatch occurred.
623  * \param  channel       The channel in which the mismatch occurred.
624  * \param  sample        The number of the sample (relative to the frame) in
625  *                       which the mismatch occurred.
626  * \param  expected      The expected value for the sample in question.
627  * \param  got           The actual value returned by the decoder.
628  * \assert
629  *    \code encoder != NULL \endcode
630  */
631 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);
632
633 /** Get the "verify" flag.
634  *  This is inherited from FLAC__StreamEncoder; see
635  *  FLAC__stream_encoder_get_verify().
636  *
637  * \param  encoder  An encoder instance to query.
638  * \assert
639  *    \code encoder != NULL \endcode
640  * \retval FLAC__bool
641  *    See FLAC__seekable_stream_encoder_set_verify().
642  */
643 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
644
645 /** Get the "streamable subset" flag.
646  *  This is inherited from FLAC__StreamEncoder; see
647  *  FLAC__stream_encoder_get_streamable_subset().
648  *
649  * \param  encoder  An encoder instance to query.
650  * \assert
651  *    \code encoder != NULL \endcode
652  * \retval FLAC__bool
653  *    See FLAC__seekable_stream_encoder_set_streamable_subset().
654  */
655 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
656
657 /** Get the "mid/side stereo coding" flag.
658  *  This is inherited from FLAC__StreamEncoder; see
659  *  FLAC__stream_encoder_get_do_mid_side_stereo().
660  *
661  * \param  encoder  An encoder instance to query.
662  * \assert
663  *    \code encoder != NULL \endcode
664  * \retval FLAC__bool
665  *    See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
666  */
667 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
668
669 /** Get the "adaptive mid/side switching" flag.
670  *  This is inherited from FLAC__StreamEncoder; see
671  *  FLAC__stream_encoder_get_loose_mid_side_stereo().
672  *
673  * \param  encoder  An encoder instance to query.
674  * \assert
675  *    \code encoder != NULL \endcode
676  * \retval FLAC__bool
677  *    See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
678  */
679 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
680
681 /** Get the number of input channels being processed.
682  *  This is inherited from FLAC__StreamEncoder; see
683  *  FLAC__stream_encoder_get_channels().
684  *
685  * \param  encoder  An encoder instance to query.
686  * \assert
687  *    \code encoder != NULL \endcode
688  * \retval unsigned
689  *    See FLAC__seekable_stream_encoder_set_channels().
690  */
691 FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
692
693 /** Get the input sample resolution setting.
694  *  This is inherited from FLAC__StreamEncoder; see
695  *  FLAC__stream_encoder_get_bits_per_sample().
696  *
697  * \param  encoder  An encoder instance to query.
698  * \assert
699  *    \code encoder != NULL \endcode
700  * \retval unsigned
701  *    See FLAC__seekable_stream_encoder_set_bits_per_sample().
702  */
703 FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
704
705 /** Get the input sample rate setting.
706  *  This is inherited from FLAC__StreamEncoder; see
707  *  FLAC__stream_encoder_get_sample_rate().
708  *
709  * \param  encoder  An encoder instance to query.
710  * \assert
711  *    \code encoder != NULL \endcode
712  * \retval unsigned
713  *    See FLAC__seekable_stream_encoder_set_sample_rate().
714  */
715 FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
716
717 /** Get the blocksize setting.
718  *  This is inherited from FLAC__StreamEncoder; see
719  *  FLAC__stream_encoder_get_blocksize().
720  *
721  * \param  encoder  An encoder instance to query.
722  * \assert
723  *    \code encoder != NULL \endcode
724  * \retval unsigned
725  *    See FLAC__seekable_stream_encoder_set_blocksize().
726  */
727 FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
728
729 /** Get the maximum LPC order setting.
730  *  This is inherited from FLAC__StreamEncoder; see
731  *  FLAC__stream_encoder_get_max_lpc_order().
732  *
733  * \param  encoder  An encoder instance to query.
734  * \assert
735  *    \code encoder != NULL \endcode
736  * \retval unsigned
737  *    See FLAC__seekable_stream_encoder_set_max_lpc_order().
738  */
739 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
740
741 /** Get the quantized linear predictor coefficient precision setting.
742  *  This is inherited from FLAC__StreamEncoder; see
743  *  FLAC__stream_encoder_get_qlp_coeff_precision().
744  *
745  * \param  encoder  An encoder instance to query.
746  * \assert
747  *    \code encoder != NULL \endcode
748  * \retval unsigned
749  *    See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
750  */
751 FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
752
753 /** Get the qlp coefficient precision search flag.
754  *  This is inherited from FLAC__StreamEncoder; see
755  *  FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
756  *
757  * \param  encoder  An encoder instance to query.
758  * \assert
759  *    \code encoder != NULL \endcode
760  * \retval FLAC__bool
761  *    See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
762  */
763 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
764
765 /** Get the "escape coding" flag.
766  *  This is inherited from FLAC__StreamEncoder; see
767  *  FLAC__stream_encoder_get_do_escape_coding().
768  *
769  * \param  encoder  An encoder instance to query.
770  * \assert
771  *    \code encoder != NULL \endcode
772  * \retval FLAC__bool
773  *    See FLAC__seekable_stream_encoder_set_do_escape_coding().
774  */
775 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
776
777 /** Get the exhaustive model search flag.
778  *  This is inherited from FLAC__StreamEncoder; see
779  *  FLAC__stream_encoder_get_do_exhaustive_model_search().
780  *
781  * \param  encoder  An encoder instance to query.
782  * \assert
783  *    \code encoder != NULL \endcode
784  * \retval FLAC__bool
785  *    See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
786  */
787 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
788
789 /** Get the minimum residual partition order setting.
790  *  This is inherited from FLAC__StreamEncoder; see
791  *  FLAC__stream_encoder_get_min_residual_partition_order().
792  *
793  * \param  encoder  An encoder instance to query.
794  * \assert
795  *    \code encoder != NULL \endcode
796  * \retval unsigned
797  *    See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
798  */
799 FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
800
801 /** Get maximum residual partition order setting.
802  *  This is inherited from FLAC__StreamEncoder; see
803  *  FLAC__stream_encoder_get_max_residual_partition_order().
804  *
805  * \param  encoder  An encoder instance to query.
806  * \assert
807  *    \code encoder != NULL \endcode
808  * \retval unsigned
809  *    See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
810  */
811 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
812
813 /** Get the Rice parameter search distance setting.
814  *  This is inherited from FLAC__StreamEncoder; see
815  *  FLAC__stream_encoder_get_rice_parameter_search_dist().
816  *
817  * \param  encoder  An encoder instance to query.
818  * \assert
819  *    \code encoder != NULL \endcode
820  * \retval unsigned
821  *    See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
822  */
823 FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
824
825 /** Get the previously set estimate of the total samples to be encoded.
826  *  This is inherited from FLAC__StreamEncoder; see
827  *  FLAC__stream_encoder_get_total_samples_estimate().
828  *
829  * \param  encoder  An encoder instance to query.
830  * \assert
831  *    \code encoder != NULL \endcode
832  * \retval FLAC__uint64
833  *    See FLAC__seekable_stream_encoder_set_total_samples_estimate().
834  */
835 FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
836
837 /** Initialize the encoder instance.
838  *  Should be called after FLAC__seekable_stream_encoder_new() and
839  *  FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
840  *  or FLAC__seekable_stream_encoder_process_interleaved().  Will set and return
841  *  the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
842  *  initialization succeeded.
843  *
844  *  The call to FLAC__seekable_stream_encoder_init() currently will also immediately
845  *  call the write callback with the \c fLaC signature and all the encoded
846  *  metadata.
847  *
848  * \param  encoder  An uninitialized encoder instance.
849  * \assert
850  *    \code encoder != NULL \endcode
851  * \retval FLAC__SeekableStreamEncoderState
852  *    \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
853  *    FLAC__SeekableStreamEncoderState for the meanings of other return values.
854  */
855 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
856
857 /** Finish the encoding process.
858  *  Flushes the encoding buffer, releases resources, resets the encoder
859  *  settings to their defaults, and returns the encoder state to
860  *  FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
861  *
862  *  In the event of a prematurely-terminated encode, it is not strictly
863  *  necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
864  *  but it is good practice to match every FLAC__seekable_stream_encoder_init()
865  *  with a FLAC__seekable_stream_encoder_finish().
866  *
867  * \param  encoder  An uninitialized encoder instance.
868  * \assert
869  *    \code encoder != NULL \endcode
870  */
871 FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
872
873 /** Submit data for encoding.
874  *  This is inherited from FLAC__StreamEncoder; see
875  *  FLAC__stream_encoder_process().
876  *
877  * \param  encoder  An initialized encoder instance in the OK state.
878  * \param  buffer   An array of pointers to each channel's signal.
879  * \param  samples  The number of samples in one channel.
880  * \assert
881  *    \code encoder != NULL \endcode
882  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
883  * \retval FLAC__bool
884  *    \c true if successful, else \c false; in this case, check the
885  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
886  *    went wrong.
887  */
888 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
889
890 /** Submit data for encoding.
891  *  This is inherited from FLAC__StreamEncoder; see
892  *  FLAC__stream_encoder_process_interleaved().
893  *
894  * \param  encoder  An initialized encoder instance in the OK state.
895  * \param  buffer   An array of channel-interleaved data (see above).
896  * \param  samples  The number of samples in one channel, the same as for
897  *                  FLAC__seekable_stream_encoder_process().  For example, if
898  *                  encoding two channels, \c 1000 \a samples corresponds
899  *                  to a \a buffer of 2000 values.
900  * \assert
901  *    \code encoder != NULL \endcode
902  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
903  * \retval FLAC__bool
904  *    \c true if successful, else \c false; in this case, check the
905  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
906  *    went wrong.
907  */
908 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
909
910 /* \} */
911
912 #ifdef __cplusplus
913 }
914 #endif
915
916 #endif