1
/* libFLAC - Free Lossless Audio Codec library
2
* Copyright (C) 2002,2003 Josh Coalson
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.
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.
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.
20
#ifndef FLAC__FILE_ENCODER_H
21
#define FLAC__FILE_ENCODER_H
24
#include "seekable_stream_encoder.h"
31
/** \file include/FLAC/file_encoder.h
34
* This module contains the functions which implement the file
37
* See the detailed documentation in the
38
* \link flac_file_encoder file encoder \endlink module.
41
/** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
42
* \ingroup flac_encoder
45
* This module contains the functions which implement the file
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().
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.
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.
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.
82
* FLAC__file_encoder_finish() resets all settings to the constructor
89
/** State values for a FLAC__FileEncoder
91
* The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
95
FLAC__FILE_ENCODER_OK = 0,
96
/**< The encoder is in the normal OK state. */
98
FLAC__FILE_ENCODER_NO_FILENAME,
99
/**< FLAC__file_encoder_init() was called without first calling
100
* FLAC__file_encoder_set_filename().
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().
108
FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
109
/**< A fatal error occurred while writing to the encoded file. */
111
FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
112
/**< An error occurred opening the output file for writing. */
114
FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
115
/**< Memory allocation failed. */
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.
123
FLAC__FILE_ENCODER_UNINITIALIZED
124
/**< The encoder is in the uninitialized state. */
126
} FLAC__FileEncoderState;
128
/** Maps a FLAC__FileEncoderState to a C string.
130
* Using a FLAC__FileEncoderState as the index to this array
131
* will give the string equivalent. The contents should not be modified.
133
extern FLAC_API const char * const FLAC__FileEncoderStateString[];
136
/***********************************************************************
138
* class FLAC__FileEncoder
140
***********************************************************************/
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.
149
struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
150
struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
153
/** Signature for the progress callback.
154
* See FLAC__file_encoder_set_progress_callback() for more info.
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().
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);
168
/***********************************************************************
170
* Class constructor/destructor
172
***********************************************************************/
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.
178
* \retval FLAC__FileEncoder*
179
* \c NULL if there was an error allocating memory, else the new instance.
181
FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
183
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
185
* \param encoder A pointer to an existing encoder.
187
* \code encoder != NULL \endcode
189
FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
191
/***********************************************************************
193
* Public class method prototypes
195
***********************************************************************/
197
/** This is inherited from FLAC__SeekableStreamEncoder; see
198
* FLAC__seekable_stream_encoder_set_verify().
201
* \param encoder An encoder instance to set.
202
* \param value See above.
204
* \code encoder != NULL \endcode
206
* \c false if the encoder is already initialized, else \c true.
208
FLAC_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
210
/** This is inherited from FLAC__SeekableStreamEncoder; see
211
* FLAC__seekable_stream_encoder_set_streamable_subset().
214
* \param encoder An encoder instance to set.
215
* \param value See above.
217
* \code encoder != NULL \endcode
219
* \c false if the encoder is already initialized, else \c true.
221
FLAC_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
223
/** This is inherited from FLAC__SeekableStreamEncoder; see
224
* FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
227
* \param encoder An encoder instance to set.
228
* \param value See above.
230
* \code encoder != NULL \endcode
232
* \c false if the encoder is already initialized, else \c true.
234
FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
236
/** This is inherited from FLAC__SeekableStreamEncoder; see
237
* FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
240
* \param encoder An encoder instance to set.
241
* \param value See above.
243
* \code encoder != NULL \endcode
245
* \c false if the encoder is already initialized, else \c true.
247
FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
249
/** This is inherited from FLAC__SeekableStreamEncoder; see
250
* FLAC__seekable_stream_encoder_set_channels().
253
* \param encoder An encoder instance to set.
254
* \param value See above.
256
* \code encoder != NULL \endcode
258
* \c false if the encoder is already initialized, else \c true.
260
FLAC_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
262
/** This is inherited from FLAC__SeekableStreamEncoder; see
263
* FLAC__seekable_stream_encoder_set_bits_per_sample().
266
* Do not feed the encoder data that is wider than the value you
267
* set here or you will generate an invalid stream.
270
* \param encoder An encoder instance to set.
271
* \param value See above.
273
* \code encoder != NULL \endcode
275
* \c false if the encoder is already initialized, else \c true.
277
FLAC_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
279
/** This is inherited from FLAC__SeekableStreamEncoder; see
280
* FLAC__seekable_stream_encoder_set_sample_rate().
283
* \param encoder An encoder instance to set.
284
* \param value See above.
286
* \code encoder != NULL \endcode
288
* \c false if the encoder is already initialized, else \c true.
290
FLAC_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
292
/** This is inherited from FLAC__SeekableStreamEncoder; see
293
* FLAC__seekable_stream_encoder_set_blocksize().
296
* \param encoder An encoder instance to set.
297
* \param value See above.
299
* \code encoder != NULL \endcode
301
* \c false if the encoder is already initialized, else \c true.
303
FLAC_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
305
/** This is inherited from FLAC__SeekableStreamEncoder; see
306
* FLAC__seekable_stream_encoder_set_max_lpc_order().
309
* \param encoder An encoder instance to set.
310
* \param value See above.
312
* \code encoder != NULL \endcode
314
* \c false if the encoder is already initialized, else \c true.
316
FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
318
/** This is inherited from FLAC__SeekableStreamEncoder; see
319
* FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
322
* In the current implementation, qlp_coeff_precision + bits_per_sample must
326
* \param encoder An encoder instance to set.
327
* \param value See above.
329
* \code encoder != NULL \endcode
331
* \c false if the encoder is already initialized, else \c true.
333
FLAC_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
335
/** This is inherited from FLAC__SeekableStreamEncoder; see
336
* FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
339
* \param encoder An encoder instance to set.
340
* \param value See above.
342
* \code encoder != NULL \endcode
344
* \c false if the encoder is already initialized, else \c true.
346
FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
348
/** This is inherited from FLAC__SeekableStreamEncoder; see
349
* FLAC__seekable_stream_encoder_set_do_escape_coding().
352
* \param encoder An encoder instance to set.
353
* \param value See above.
355
* \code encoder != NULL \endcode
357
* \c false if the encoder is already initialized, else \c true.
359
FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
361
/** This is inherited from FLAC__SeekableStreamEncoder; see
362
* FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
365
* \param encoder An encoder instance to set.
366
* \param value See above.
368
* \code encoder != NULL \endcode
370
* \c false if the encoder is already initialized, else \c true.
372
FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
374
/** This is inherited from FLAC__SeekableStreamEncoder; see
375
* FLAC__seekable_stream_encoder_set_min_residual_partition_order().
378
* \param encoder An encoder instance to set.
379
* \param value See above.
381
* \code encoder != NULL \endcode
383
* \c false if the encoder is already initialized, else \c true.
385
FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
387
/** This is inherited from FLAC__SeekableStreamEncoder; see
388
* FLAC__seekable_stream_encoder_set_max_residual_partition_order().
391
* \param encoder An encoder instance to set.
392
* \param value See above.
394
* \code encoder != NULL \endcode
396
* \c false if the encoder is already initialized, else \c true.
398
FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
400
/** This is inherited from FLAC__SeekableStreamEncoder; see
401
* FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
404
* \param encoder An encoder instance to set.
405
* \param value See above.
407
* \code encoder != NULL \endcode
409
* \c false if the encoder is already initialized, else \c true.
411
FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
413
/** This is inherited from FLAC__SeekableStreamEncoder; see
414
* FLAC__seekable_stream_encoder_set_total_samples_estimate().
417
* \param encoder An encoder instance to set.
418
* \param value See above.
420
* \code encoder != NULL \endcode
422
* \c false if the encoder is already initialized, else \c true.
424
FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
426
/** This is inherited from FLAC__SeekableStreamEncoder; see
427
* FLAC__seekable_stream_encoder_set_metadata().
429
* \default \c NULL, 0
430
* \param encoder An encoder instance to set.
431
* \param metadata See above.
432
* \param num_blocks See above.
434
* \code encoder != NULL \endcode
436
* \c false if the encoder is already initialized, else \c true.
438
FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
440
/** Set the output file name encode to.
443
* The filename is mandatory and must be set before initialization.
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.
450
* \param encoder A encoder instance to set.
451
* \param value The output file name.
453
* \code encoder != NULL \endcode
454
* \code value != NULL \endcode
456
* \c false if the encoder is already initialized, or there was a memory
457
* allocation error, else \c true.
459
FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
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().
468
* Unlike most other callbacks, the progress callback is \b not mandatory
469
* and need not be set before initialization.
472
* \param encoder An encoder instance to set.
473
* \param value See above.
475
* \code encoder != NULL \endcode
476
* \code value != NULL \endcode
478
* \c false if the encoder is already initialized, else \c true.
480
FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
482
/** Set the client data to be passed back to callbacks.
483
* This value will be supplied to callbacks in their \a client_data
487
* \param encoder An encoder instance to set.
488
* \param value See above.
490
* \code encoder != NULL \endcode
492
* \c false if the encoder is already initialized, else \c true.
494
FLAC_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
496
/** Get the current encoder state.
498
* \param encoder An encoder instance to query.
500
* \code encoder != NULL \endcode
501
* \retval FLAC__FileEncoderState
502
* The current encoder state.
504
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
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.
510
* \param encoder An encoder instance to query.
512
* \code encoder != NULL \endcode
513
* \retval FLAC__SeekableStreamEncoderState
514
* The seekable stream encoder state.
516
FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
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.
523
* \param encoder An encoder instance to query.
525
* \code encoder != NULL \endcode
526
* \retval FLAC__StreamEncoderState
527
* The seekable stream encoder state.
529
FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
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.
537
* \param encoder An encoder instance to query.
539
* \code encoder != NULL \endcode
540
* \retval FLAC__StreamDecoderState
541
* The stream encoder state.
543
FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
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.
550
* \param encoder A encoder instance to query.
552
* \code encoder != NULL \endcode
553
* \retval const char *
554
* The encoder state as a C string. Do not modify the contents.
556
FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
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
563
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
564
* stream encoder state is
565
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
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.
576
* \code encoder != NULL \endcode
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);
580
/** Get the "verify" flag.
581
* This is inherited from FLAC__SeekableStreamEncoder; see
582
* FLAC__seekable_stream_encoder_get_verify().
584
* \param encoder An encoder instance to query.
586
* \code encoder != NULL \endcode
588
* See FLAC__file_encoder_set_verify().
590
FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
592
/** Get the "streamable subset" flag.
593
* This is inherited from FLAC__SeekableStreamEncoder; see
594
* FLAC__seekable_stream_encoder_get_streamable_subset().
596
* \param encoder An encoder instance to query.
598
* \code encoder != NULL \endcode
600
* See FLAC__file_encoder_set_streamable_subset().
602
FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
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().
608
* \param encoder An encoder instance to query.
610
* \code encoder != NULL \endcode
612
* See FLAC__file_encoder_get_do_mid_side_stereo().
614
FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
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().
620
* \param encoder An encoder instance to query.
622
* \code encoder != NULL \endcode
624
* See FLAC__file_encoder_set_loose_mid_side_stereo().
626
FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
628
/** Get the number of input channels being processed.
629
* This is inherited from FLAC__SeekableStreamEncoder; see
630
* FLAC__seekable_stream_encoder_get_channels().
632
* \param encoder An encoder instance to query.
634
* \code encoder != NULL \endcode
636
* See FLAC__file_encoder_set_channels().
638
FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
640
/** Get the input sample resolution setting.
641
* This is inherited from FLAC__SeekableStreamEncoder; see
642
* FLAC__seekable_stream_encoder_get_bits_per_sample().
644
* \param encoder An encoder instance to query.
646
* \code encoder != NULL \endcode
648
* See FLAC__file_encoder_set_bits_per_sample().
650
FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
652
/** Get the input sample rate setting.
653
* This is inherited from FLAC__SeekableStreamEncoder; see
654
* FLAC__seekable_stream_encoder_get_sample_rate().
656
* \param encoder An encoder instance to query.
658
* \code encoder != NULL \endcode
660
* See FLAC__file_encoder_set_sample_rate().
662
FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
664
/** Get the blocksize setting.
665
* This is inherited from FLAC__SeekableStreamEncoder; see
666
* FLAC__seekable_stream_encoder_get_blocksize().
668
* \param encoder An encoder instance to query.
670
* \code encoder != NULL \endcode
672
* See FLAC__file_encoder_set_blocksize().
674
FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
676
/** Get the maximum LPC order setting.
677
* This is inherited from FLAC__SeekableStreamEncoder; see
678
* FLAC__seekable_stream_encoder_get_max_lpc_order().
680
* \param encoder An encoder instance to query.
682
* \code encoder != NULL \endcode
684
* See FLAC__file_encoder_set_max_lpc_order().
686
FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
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().
692
* \param encoder An encoder instance to query.
694
* \code encoder != NULL \endcode
696
* See FLAC__file_encoder_set_qlp_coeff_precision().
698
FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
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().
704
* \param encoder An encoder instance to query.
706
* \code encoder != NULL \endcode
708
* See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
710
FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
712
/** Get the "escape coding" flag.
713
* This is inherited from FLAC__SeekableStreamEncoder; see
714
* FLAC__seekable_stream_encoder_get_do_escape_coding().
716
* \param encoder An encoder instance to query.
718
* \code encoder != NULL \endcode
720
* See FLAC__file_encoder_set_do_escape_coding().
722
FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
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().
728
* \param encoder An encoder instance to query.
730
* \code encoder != NULL \endcode
732
* See FLAC__file_encoder_set_do_exhaustive_model_search().
734
FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
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().
740
* \param encoder An encoder instance to query.
742
* \code encoder != NULL \endcode
744
* See FLAC__file_encoder_set_min_residual_partition_order().
746
FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
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().
752
* \param encoder An encoder instance to query.
754
* \code encoder != NULL \endcode
756
* See FLAC__file_encoder_set_max_residual_partition_order().
758
FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
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().
764
* \param encoder An encoder instance to query.
766
* \code encoder != NULL \endcode
768
* See FLAC__file_encoder_set_rice_parameter_search_dist().
770
FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
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().
776
* \param encoder An encoder instance to query.
778
* \code encoder != NULL \endcode
779
* \retval FLAC__uint64
780
* See FLAC__file_encoder_set_total_samples_estimate().
782
FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
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.
791
* \param encoder An uninitialized encoder instance.
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.
798
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
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.
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().
810
* \param encoder An uninitialized encoder instance.
812
* \code encoder != NULL \endcode
814
FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
816
/** Submit data for encoding.
817
* This is inherited from FLAC__SeekableStreamEncoder; see
818
* FLAC__seekable_stream_encoder_process().
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.
824
* \code encoder != NULL \endcode
825
* \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
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
831
FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
833
/** Submit data for encoding.
834
* This is inherited from FLAC__SeekableStreamEncoder; see
835
* FLAC__seekable_stream_encoder_process_interleaved().
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.
844
* \code encoder != NULL \endcode
845
* \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
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
851
FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);