add callback.h
[flac.git] / include / FLAC / file_encoder.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2002,2003,2004  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__FILE_ENCODER_H
33 #define FLAC__FILE_ENCODER_H
34
35 #include "export.h"
36 #include "seekable_stream_encoder.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42
43 /** \file include/FLAC/file_encoder.h
44  *
45  *  \brief
46  *  This module contains the functions which implement the file
47  *  encoder.
48  *
49  *  See the detailed documentation in the
50  *  \link flac_file_encoder file encoder \endlink module.
51  */
52
53 /** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
54  *  \ingroup flac_encoder
55  *
56  *  \brief
57  *  This module contains the functions which implement the file
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__file_encoder_new().
63  * - The program overrides the default settings using
64  *   FLAC__file_encoder_set_*() functions.
65  * - The program initializes the instance to validate the settings and
66  *   prepare for encoding using FLAC__file_encoder_init().
67  * - The program calls FLAC__file_encoder_process() or
68  *   FLAC__file_encoder_process_interleaved() to encode data, which
69  *   subsequently writes data to the output file.
70  * - The program finishes the encoding with FLAC__file_encoder_finish(),
71  *   which causes the encoder to encode any data still in its input pipe,
72  *   rewind and write the STREAMINFO metadata to file, and finally reset
73  *   the encoder to the uninitialized state.
74  * - The instance may be used again or deleted with
75  *   FLAC__file_encoder_delete().
76  *
77  * The file encoder is a wrapper around the
78  * \link flac_seekable_stream_encoder seekable stream encoder \endlink which supplies all
79  * callbacks internally; the user need specify only the filename.
80  *
81  * Make sure to read the detailed description of the
82  * \link flac_seekable_stream_encoder seekable stream encoder module \endlink since the
83  * \link flac_stream_encoder stream encoder module \endlink since the
84  * file encoder inherits much of its behavior from them.
85  *
86  * \note
87  * The "set" functions may only be called when the encoder is in the
88  * state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
89  * FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but
90  * before FLAC__file_encoder_init().  If this is the case they will
91  * return \c true, otherwise \c false.
92  *
93  * \note
94  * FLAC__file_encoder_finish() resets all settings to the constructor
95  * defaults.
96  *
97  * \{
98  */
99
100
101 /** State values for a FLAC__FileEncoder
102  *
103  *  The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
104  */
105 typedef enum {
106
107         FLAC__FILE_ENCODER_OK = 0,
108         /**< The encoder is in the normal OK state. */
109
110         FLAC__FILE_ENCODER_NO_FILENAME,
111         /**< FLAC__file_encoder_init() was called without first calling
112          * FLAC__file_encoder_set_filename().
113          */
114
115         FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
116         /**< An error occurred in the underlying seekable stream encoder;
117          * check FLAC__file_encoder_get_seekable_stream_encoder_state().
118          */
119
120         FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
121         /**< A fatal error occurred while writing to the encoded file. */
122
123         FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
124         /**< An error occurred opening the output file for writing. */
125
126         FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
127         /**< Memory allocation failed. */
128
129         FLAC__FILE_ENCODER_ALREADY_INITIALIZED,
130         /**< FLAC__file_encoder_init() was called when the encoder was
131          * already initialized, usually because
132          * FLAC__file_encoder_finish() was not called.
133          */
134
135         FLAC__FILE_ENCODER_UNINITIALIZED
136         /**< The encoder is in the uninitialized state. */
137
138 } FLAC__FileEncoderState;
139
140 /** Maps a FLAC__FileEncoderState to a C string.
141  *
142  *  Using a FLAC__FileEncoderState as the index to this array
143  *  will give the string equivalent.  The contents should not be modified.
144  */
145 extern FLAC_API const char * const FLAC__FileEncoderStateString[];
146
147
148 /***********************************************************************
149  *
150  * class FLAC__FileEncoder
151  *
152  ***********************************************************************/
153
154 struct FLAC__FileEncoderProtected;
155 struct FLAC__FileEncoderPrivate;
156 /** The opaque structure definition for the file encoder type.
157  *  See the \link flac_file_encoder file encoder module \endlink
158  *  for a detailed description.
159  */
160 typedef struct {
161         struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
162         struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
163 } FLAC__FileEncoder;
164
165 /** Signature for the progress callback.
166  *  See FLAC__file_encoder_set_progress_callback() for more info.
167  *
168  * \param  encoder          The encoder instance calling the callback.
169  * \param  bytes_written    Bytes written so far.
170  * \param  samples_written  Samples written so far.
171  * \param  frames_written   Frames written so far.
172  * \param  total_frames_estimate  The estimate of the total number of
173  *                                frames to be written.
174  * \param  client_data      The callee's client data set through
175  *                          FLAC__file_encoder_set_client_data().
176  */
177 typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
178
179
180 /***********************************************************************
181  *
182  * Class constructor/destructor
183  *
184  ***********************************************************************/
185
186 /** Create a new file encoder instance.  The instance is created with
187  *  default settings; see the individual FLAC__file_encoder_set_*()
188  *  functions for each setting's default.
189  *
190  * \retval FLAC__FileEncoder*
191  *    \c NULL if there was an error allocating memory, else the new instance.
192  */
193 FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
194
195 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
196  *
197  * \param encoder  A pointer to an existing encoder.
198  * \assert
199  *    \code encoder != NULL \endcode
200  */
201 FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
202
203 /***********************************************************************
204  *
205  * Public class method prototypes
206  *
207  ***********************************************************************/
208
209 /** This is inherited from FLAC__SeekableStreamEncoder; see
210  *  FLAC__seekable_stream_encoder_set_verify().
211  *
212  * \default \c true
213  * \param  encoder  An encoder instance to set.
214  * \param  value    See above.
215  * \assert
216  *    \code encoder != NULL \endcode
217  * \retval FLAC__bool
218  *    \c false if the encoder is already initialized, else \c true.
219  */
220 FLAC_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
221
222 /** This is inherited from FLAC__SeekableStreamEncoder; see
223  *  FLAC__seekable_stream_encoder_set_streamable_subset().
224  *
225  * \default \c true
226  * \param  encoder  An encoder instance to set.
227  * \param  value    See above.
228  * \assert
229  *    \code encoder != NULL \endcode
230  * \retval FLAC__bool
231  *    \c false if the encoder is already initialized, else \c true.
232  */
233 FLAC_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
234
235 /** This is inherited from FLAC__SeekableStreamEncoder; see
236  *  FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
237  *
238  * \default \c false
239  * \param  encoder  An encoder instance to set.
240  * \param  value    See above.
241  * \assert
242  *    \code encoder != NULL \endcode
243  * \retval FLAC__bool
244  *    \c false if the encoder is already initialized, else \c true.
245  */
246 FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
247
248 /** This is inherited from FLAC__SeekableStreamEncoder; see
249  *  FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
250  *
251  * \default \c false
252  * \param  encoder  An encoder instance to set.
253  * \param  value    See above.
254  * \assert
255  *    \code encoder != NULL \endcode
256  * \retval FLAC__bool
257  *    \c false if the encoder is already initialized, else \c true.
258  */
259 FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
260
261 /** This is inherited from FLAC__SeekableStreamEncoder; see
262  *  FLAC__seekable_stream_encoder_set_channels().
263  *
264  * \default \c 2
265  * \param  encoder  An encoder instance to set.
266  * \param  value    See above.
267  * \assert
268  *    \code encoder != NULL \endcode
269  * \retval FLAC__bool
270  *    \c false if the encoder is already initialized, else \c true.
271  */
272 FLAC_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
273
274 /** This is inherited from FLAC__SeekableStreamEncoder; see
275  *  FLAC__seekable_stream_encoder_set_bits_per_sample().
276  *
277  * \warning
278  * Do not feed the encoder data that is wider than the value you
279  * set here or you will generate an invalid stream.
280  *
281  * \default \c 16
282  * \param  encoder  An encoder instance to set.
283  * \param  value    See above.
284  * \assert
285  *    \code encoder != NULL \endcode
286  * \retval FLAC__bool
287  *    \c false if the encoder is already initialized, else \c true.
288  */
289 FLAC_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
290
291 /** This is inherited from FLAC__SeekableStreamEncoder; see
292  *  FLAC__seekable_stream_encoder_set_sample_rate().
293  *
294  * \default \c 44100
295  * \param  encoder  An encoder instance to set.
296  * \param  value    See above.
297  * \assert
298  *    \code encoder != NULL \endcode
299  * \retval FLAC__bool
300  *    \c false if the encoder is already initialized, else \c true.
301  */
302 FLAC_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
303
304 /** This is inherited from FLAC__SeekableStreamEncoder; see
305  *  FLAC__seekable_stream_encoder_set_blocksize().
306  *
307  * \default \c 1152
308  * \param  encoder  An encoder instance to set.
309  * \param  value    See above.
310  * \assert
311  *    \code encoder != NULL \endcode
312  * \retval FLAC__bool
313  *    \c false if the encoder is already initialized, else \c true.
314  */
315 FLAC_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
316
317 /** This is inherited from FLAC__SeekableStreamEncoder; see
318  *  FLAC__seekable_stream_encoder_set_max_lpc_order().
319  *
320  * \default \c 0
321  * \param  encoder  An encoder instance to set.
322  * \param  value    See above.
323  * \assert
324  *    \code encoder != NULL \endcode
325  * \retval FLAC__bool
326  *    \c false if the encoder is already initialized, else \c true.
327  */
328 FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
329
330 /** This is inherited from FLAC__SeekableStreamEncoder; see
331  *  FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
332  *
333  * \note
334  * In the current implementation, qlp_coeff_precision + bits_per_sample must
335  * be less than 32.
336  *
337  * \default \c 0
338  * \param  encoder  An encoder instance to set.
339  * \param  value    See above.
340  * \assert
341  *    \code encoder != NULL \endcode
342  * \retval FLAC__bool
343  *    \c false if the encoder is already initialized, else \c true.
344  */
345 FLAC_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
346
347 /** This is inherited from FLAC__SeekableStreamEncoder; see
348  *  FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
349  *
350  * \default \c false
351  * \param  encoder  An encoder instance to set.
352  * \param  value    See above.
353  * \assert
354  *    \code encoder != NULL \endcode
355  * \retval FLAC__bool
356  *    \c false if the encoder is already initialized, else \c true.
357  */
358 FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
359
360 /** This is inherited from FLAC__SeekableStreamEncoder; see
361  *  FLAC__seekable_stream_encoder_set_do_escape_coding().
362  *
363  * \default \c false
364  * \param  encoder  An encoder instance to set.
365  * \param  value    See above.
366  * \assert
367  *    \code encoder != NULL \endcode
368  * \retval FLAC__bool
369  *    \c false if the encoder is already initialized, else \c true.
370  */
371 FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
372
373 /** This is inherited from FLAC__SeekableStreamEncoder; see
374  *  FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
375  *
376  * \default \c false
377  * \param  encoder  An encoder instance to set.
378  * \param  value    See above.
379  * \assert
380  *    \code encoder != NULL \endcode
381  * \retval FLAC__bool
382  *    \c false if the encoder is already initialized, else \c true.
383  */
384 FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
385
386 /** This is inherited from FLAC__SeekableStreamEncoder; see
387  *  FLAC__seekable_stream_encoder_set_min_residual_partition_order().
388  *
389  * \default \c 0
390  * \param  encoder  An encoder instance to set.
391  * \param  value    See above.
392  * \assert
393  *    \code encoder != NULL \endcode
394  * \retval FLAC__bool
395  *    \c false if the encoder is already initialized, else \c true.
396  */
397 FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
398
399 /** This is inherited from FLAC__SeekableStreamEncoder; see
400  *  FLAC__seekable_stream_encoder_set_max_residual_partition_order().
401  *
402  * \default \c 0
403  * \param  encoder  An encoder instance to set.
404  * \param  value    See above.
405  * \assert
406  *    \code encoder != NULL \endcode
407  * \retval FLAC__bool
408  *    \c false if the encoder is already initialized, else \c true.
409  */
410 FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
411
412 /** This is inherited from FLAC__SeekableStreamEncoder; see
413  *  FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
414  *
415  * \default \c 0
416  * \param  encoder  An encoder instance to set.
417  * \param  value    See above.
418  * \assert
419  *    \code encoder != NULL \endcode
420  * \retval FLAC__bool
421  *    \c false if the encoder is already initialized, else \c true.
422  */
423 FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
424
425 /** This is inherited from FLAC__SeekableStreamEncoder; see
426  *  FLAC__seekable_stream_encoder_set_total_samples_estimate().
427  *
428  * \default \c 0
429  * \param  encoder  An encoder instance to set.
430  * \param  value    See above.
431  * \assert
432  *    \code encoder != NULL \endcode
433  * \retval FLAC__bool
434  *    \c false if the encoder is already initialized, else \c true.
435  */
436 FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
437
438 /** This is inherited from FLAC__SeekableStreamEncoder; see
439  *  FLAC__seekable_stream_encoder_set_metadata().
440  *
441  * \default \c NULL, 0
442  * \param  encoder     An encoder instance to set.
443  * \param  metadata    See above.
444  * \param  num_blocks  See above.
445  * \assert
446  *    \code encoder != NULL \endcode
447  * \retval FLAC__bool
448  *    \c false if the encoder is already initialized, else \c true.
449  */
450 FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
451
452 /** Set the output file name encode to.
453  *
454  * \note
455  * The filename is mandatory and must be set before initialization.
456  *
457  * \note
458  * Unlike the FLAC__FileDecoder, the filename does not interpret "-" for
459  * \c stdout; writing to \c stdout is not relevant in the file encoder.
460  *
461  * \default \c NULL
462  * \param  encoder  A encoder instance to set.
463  * \param  value    The output file name.
464  * \assert
465  *    \code encoder != NULL \endcode
466  *    \code value != NULL \endcode
467  * \retval FLAC__bool
468  *    \c false if the encoder is already initialized, or there was a memory
469  *    allocation error, else \c true.
470  */
471 FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
472
473 /** Set the progress callback.
474  *  The supplied function will be called when the encoder has finished
475  *  writing a frame.  The \c total_frames_estimate argument to the callback
476  *  will be based on the value from
477  *  FLAC__file_encoder_set_total_samples_estimate().
478  *
479  * \note
480  * Unlike most other callbacks, the progress callback is \b not mandatory
481  * and need not be set before initialization.
482  *
483  * \default \c NULL
484  * \param  encoder  An encoder instance to set.
485  * \param  value    See above.
486  * \assert
487  *    \code encoder != NULL \endcode
488  *    \code value != NULL \endcode
489  * \retval FLAC__bool
490  *    \c false if the encoder is already initialized, else \c true.
491  */
492 FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
493
494 /** Set the client data to be passed back to callbacks.
495  *  This value will be supplied to callbacks in their \a client_data
496  *  argument.
497  *
498  * \default \c NULL
499  * \param  encoder  An encoder instance to set.
500  * \param  value    See above.
501  * \assert
502  *    \code encoder != NULL \endcode
503  * \retval FLAC__bool
504  *    \c false if the encoder is already initialized, else \c true.
505  */
506 FLAC_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
507
508 /** Get the current encoder state.
509  *
510  * \param  encoder  An encoder instance to query.
511  * \assert
512  *    \code encoder != NULL \endcode
513  * \retval FLAC__FileEncoderState
514  *    The current encoder state.
515  */
516 FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
517
518 /** Get the state of the underlying seekable stream encoder.
519  *  Useful when the file encoder state is
520  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
521  *
522  * \param  encoder  An encoder instance to query.
523  * \assert
524  *    \code encoder != NULL \endcode
525  * \retval FLAC__SeekableStreamEncoderState
526  *    The seekable stream encoder state.
527  */
528 FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
529
530 /** Get the state of the underlying stream encoder.
531  *  Useful when the file encoder state is
532  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
533  *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
534  *
535  * \param  encoder  An encoder instance to query.
536  * \assert
537  *    \code encoder != NULL \endcode
538  * \retval FLAC__StreamEncoderState
539  *    The seekable stream encoder state.
540  */
541 FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
542
543 /** Get the state of the underlying stream encoder's verify decoder.
544  *  Useful when the file encoder state is
545  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
546  *  encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and
547  *  the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
548  *
549  * \param  encoder  An encoder instance to query.
550  * \assert
551  *    \code encoder != NULL \endcode
552  * \retval FLAC__StreamDecoderState
553  *    The stream encoder state.
554  */
555 FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
556
557 /** Get the current encoder state as a C string.
558  *  This version automatically resolves
559  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
560  *  seekable stream encoder's state.
561  *
562  * \param  encoder  A encoder instance to query.
563  * \assert
564  *    \code encoder != NULL \endcode
565  * \retval const char *
566  *    The encoder state as a C string.  Do not modify the contents.
567  */
568 FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
569
570 /** Get relevant values about the nature of a verify decoder error.
571  *  Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
572  *  Useful when the file encoder state is
573  *  \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
574  *  encoder state is
575  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
576  *  stream encoder state is
577  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
578  *
579  * \param  encoder  An encoder instance to query.
580  * \param  absolute_sample  The absolute sample number of the mismatch.
581  * \param  frame_number  The number of the frame in which the mismatch occurred.
582  * \param  channel       The channel in which the mismatch occurred.
583  * \param  sample        The number of the sample (relative to the frame) in
584  *                       which the mismatch occurred.
585  * \param  expected      The expected value for the sample in question.
586  * \param  got           The actual value returned by the decoder.
587  * \assert
588  *    \code encoder != NULL \endcode
589  */
590 FLAC_API void FLAC__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
591
592 /** Get the "verify" flag.
593  *  This is inherited from FLAC__SeekableStreamEncoder; see
594  *  FLAC__seekable_stream_encoder_get_verify().
595  *
596  * \param  encoder  An encoder instance to query.
597  * \assert
598  *    \code encoder != NULL \endcode
599  * \retval FLAC__bool
600  *    See FLAC__file_encoder_set_verify().
601  */
602 FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
603
604 /** Get the "streamable subset" flag.
605  *  This is inherited from FLAC__SeekableStreamEncoder; see
606  *  FLAC__seekable_stream_encoder_get_streamable_subset().
607  *
608  * \param  encoder  An encoder instance to query.
609  * \assert
610  *    \code encoder != NULL \endcode
611  * \retval FLAC__bool
612  *    See FLAC__file_encoder_set_streamable_subset().
613  */
614 FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
615
616 /** Get the "mid/side stereo coding" flag.
617  *  This is inherited from FLAC__SeekableStreamEncoder; see
618  *  FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
619  *
620  * \param  encoder  An encoder instance to query.
621  * \assert
622  *    \code encoder != NULL \endcode
623  * \retval FLAC__bool
624  *    See FLAC__file_encoder_get_do_mid_side_stereo().
625  */
626 FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
627
628 /** Get the "adaptive mid/side switching" flag.
629  *  This is inherited from FLAC__SeekableStreamEncoder; see
630  *  FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
631  *
632  * \param  encoder  An encoder instance to query.
633  * \assert
634  *    \code encoder != NULL \endcode
635  * \retval FLAC__bool
636  *    See FLAC__file_encoder_set_loose_mid_side_stereo().
637  */
638 FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
639
640 /** Get the number of input channels being processed.
641  *  This is inherited from FLAC__SeekableStreamEncoder; see
642  *  FLAC__seekable_stream_encoder_get_channels().
643  *
644  * \param  encoder  An encoder instance to query.
645  * \assert
646  *    \code encoder != NULL \endcode
647  * \retval unsigned
648  *    See FLAC__file_encoder_set_channels().
649  */
650 FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
651
652 /** Get the input sample resolution setting.
653  *  This is inherited from FLAC__SeekableStreamEncoder; see
654  *  FLAC__seekable_stream_encoder_get_bits_per_sample().
655  *
656  * \param  encoder  An encoder instance to query.
657  * \assert
658  *    \code encoder != NULL \endcode
659  * \retval unsigned
660  *    See FLAC__file_encoder_set_bits_per_sample().
661  */
662 FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
663
664 /** Get the input sample rate setting.
665  *  This is inherited from FLAC__SeekableStreamEncoder; see
666  *  FLAC__seekable_stream_encoder_get_sample_rate().
667  *
668  * \param  encoder  An encoder instance to query.
669  * \assert
670  *    \code encoder != NULL \endcode
671  * \retval unsigned
672  *    See FLAC__file_encoder_set_sample_rate().
673  */
674 FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
675
676 /** Get the blocksize setting.
677  *  This is inherited from FLAC__SeekableStreamEncoder; see
678  *  FLAC__seekable_stream_encoder_get_blocksize().
679  *
680  * \param  encoder  An encoder instance to query.
681  * \assert
682  *    \code encoder != NULL \endcode
683  * \retval unsigned
684  *    See FLAC__file_encoder_set_blocksize().
685  */
686 FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
687
688 /** Get the maximum LPC order setting.
689  *  This is inherited from FLAC__SeekableStreamEncoder; see
690  *  FLAC__seekable_stream_encoder_get_max_lpc_order().
691  *
692  * \param  encoder  An encoder instance to query.
693  * \assert
694  *    \code encoder != NULL \endcode
695  * \retval unsigned
696  *    See FLAC__file_encoder_set_max_lpc_order().
697  */
698 FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
699
700 /** Get the quantized linear predictor coefficient precision setting.
701  *  This is inherited from FLAC__SeekableStreamEncoder; see
702  *  FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
703  *
704  * \param  encoder  An encoder instance to query.
705  * \assert
706  *    \code encoder != NULL \endcode
707  * \retval unsigned
708  *    See FLAC__file_encoder_set_qlp_coeff_precision().
709  */
710 FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
711
712 /** Get the qlp coefficient precision search flag.
713  *  This is inherited from FLAC__SeekableStreamEncoder; see
714  *  FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
715  *
716  * \param  encoder  An encoder instance to query.
717  * \assert
718  *    \code encoder != NULL \endcode
719  * \retval FLAC__bool
720  *    See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
721  */
722 FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
723
724 /** Get the "escape coding" flag.
725  *  This is inherited from FLAC__SeekableStreamEncoder; see
726  *  FLAC__seekable_stream_encoder_get_do_escape_coding().
727  *
728  * \param  encoder  An encoder instance to query.
729  * \assert
730  *    \code encoder != NULL \endcode
731  * \retval FLAC__bool
732  *    See FLAC__file_encoder_set_do_escape_coding().
733  */
734 FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
735
736 /** Get the exhaustive model search flag.
737  *  This is inherited from FLAC__SeekableStreamEncoder; see
738  *  FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
739  *
740  * \param  encoder  An encoder instance to query.
741  * \assert
742  *    \code encoder != NULL \endcode
743  * \retval FLAC__bool
744  *    See FLAC__file_encoder_set_do_exhaustive_model_search().
745  */
746 FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
747
748 /** Get the minimum residual partition order setting.
749  *  This is inherited from FLAC__SeekableStreamEncoder; see
750  *  FLAC__seekable_stream_encoder_get_min_residual_partition_order().
751  *
752  * \param  encoder  An encoder instance to query.
753  * \assert
754  *    \code encoder != NULL \endcode
755  * \retval unsigned
756  *    See FLAC__file_encoder_set_min_residual_partition_order().
757  */
758 FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
759
760 /** Get maximum residual partition order setting.
761  *  This is inherited from FLAC__SeekableStreamEncoder; see
762  *  FLAC__seekable_stream_encoder_get_max_residual_partition_order().
763  *
764  * \param  encoder  An encoder instance to query.
765  * \assert
766  *    \code encoder != NULL \endcode
767  * \retval unsigned
768  *    See FLAC__file_encoder_set_max_residual_partition_order().
769  */
770 FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
771
772 /** Get the Rice parameter search distance setting.
773  *  This is inherited from FLAC__SeekableStreamEncoder; see
774  *  FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
775  *
776  * \param  encoder  An encoder instance to query.
777  * \assert
778  *    \code encoder != NULL \endcode
779  * \retval unsigned
780  *    See FLAC__file_encoder_set_rice_parameter_search_dist().
781  */
782 FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
783
784 /** Get the previously set estimate of the total samples to be encoded.
785  *  This is inherited from FLAC__SeekableStreamEncoder; see
786  *  FLAC__seekable_stream_encoder_get_total_samples_estimate().
787  *
788  * \param  encoder  An encoder instance to query.
789  * \assert
790  *    \code encoder != NULL \endcode
791  * \retval FLAC__uint64
792  *    See FLAC__file_encoder_set_total_samples_estimate().
793  */
794 FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
795
796 /** Initialize the encoder instance.
797  *  Should be called after FLAC__file_encoder_new() and
798  *  FLAC__file_encoder_set_*() but before FLAC__file_encoder_process()
799  *  or FLAC__file_encoder_process_interleaved().  Will set and return
800  *  the encoder state, which will be FLAC__FILE_ENCODER_OK if
801  *  initialization succeeded.
802  *
803  * \param  encoder  An uninitialized encoder instance.
804  * \assert
805  *    \code encoder != NULL \endcode
806  * \retval FLAC__FileEncoderState
807  *    \c FLAC__FILE_ENCODER_OK if initialization was successful; see
808  *    FLAC__FileEncoderState for the meanings of other return values.
809  */
810 FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
811
812 /** Finish the encoding process.
813  *  Flushes the encoding buffer, releases resources, resets the encoder
814  *  settings to their defaults, and returns the encoder state to
815  *  FLAC__FILE_ENCODER_UNINITIALIZED.
816  *
817  *  In the event of a prematurely-terminated encode, it is not strictly
818  *  necessary to call this immediately before FLAC__file_encoder_delete()
819  *  but it is good practice to match every FLAC__file_encoder_init()
820  *  with a FLAC__file_encoder_finish().
821  *
822  * \param  encoder  An uninitialized encoder instance.
823  * \assert
824  *    \code encoder != NULL \endcode
825  */
826 FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
827
828 /** Submit data for encoding.
829  *  This is inherited from FLAC__SeekableStreamEncoder; see
830  *  FLAC__seekable_stream_encoder_process().
831  *
832  * \param  encoder  An initialized encoder instance in the OK state.
833  * \param  buffer   An array of pointers to each channel's signal.
834  * \param  samples  The number of samples in one channel.
835  * \assert
836  *    \code encoder != NULL \endcode
837  *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
838  * \retval FLAC__bool
839  *    \c true if successful, else \c false; in this case, check the
840  *    encoder state with FLAC__file_encoder_get_state() to see what
841  *    went wrong.
842  */
843 FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
844
845 /** Submit data for encoding.
846  *  This is inherited from FLAC__SeekableStreamEncoder; see
847  *  FLAC__seekable_stream_encoder_process_interleaved().
848  *
849  * \param  encoder  An initialized encoder instance in the OK state.
850  * \param  buffer   An array of channel-interleaved data (see above).
851  * \param  samples  The number of samples in one channel, the same as for
852  *                  FLAC__file_encoder_process().  For example, if
853  *                  encoding two channels, \c 1000 \a samples corresponds
854  *                  to a \a buffer of 2000 values.
855  * \assert
856  *    \code encoder != NULL \endcode
857  *    \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
858  * \retval FLAC__bool
859  *    \c true if successful, else \c false; in this case, check the
860  *    encoder state with FLAC__file_encoder_get_state() to see what
861  *    went wrong.
862  */
863 FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
864
865 /* \} */
866
867 #ifdef __cplusplus
868 }
869 #endif
870
871 #endif