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