file_encoder.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
file_encoder.h (33083B)
---
1 /* libFLAC - Free Lossless Audio Codec library
2 * Copyright (C) 2002,2003,2004,2005 Josh Coalson
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * - Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * - Neither the name of the Xiph.org Foundation nor the names of its
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #ifndef FLAC__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