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