1
/* libFLAC - Free Lossless Audio Codec library
2
* Copyright (C) 2002,2003,2004,2005 Josh Coalson
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions
8
* - Redistributions of source code must retain the above copyright
9
* notice, this list of conditions and the following disclaimer.
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.
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.
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.
32
#ifndef FLAC__FILE_ENCODER_H
33
#define FLAC__FILE_ENCODER_H
36
#include "seekable_stream_encoder.h"
43
/** \file include/FLAC/file_encoder.h
46
* This module contains the functions which implement the file
49
* See the detailed documentation in the
50
* \link flac_file_encoder file encoder \endlink module.
53
/** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
54
* \ingroup flac_encoder
57
* This module contains the functions which implement the file
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().
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.
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.
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.
94
* FLAC__file_encoder_finish() resets all settings to the constructor
101
/** State values for a FLAC__FileEncoder
103
* The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
107
FLAC__FILE_ENCODER_OK = 0,
108
/**< The encoder is in the normal OK state. */
110
FLAC__FILE_ENCODER_NO_FILENAME,
111
/**< FLAC__file_encoder_init() was called without first calling
112
* FLAC__file_encoder_set_filename().
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().
120
FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
121
/**< A fatal error occurred while writing to the encoded file. */
123
FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
124
/**< An error occurred opening the output file for writing. */
126
FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
127
/**< Memory allocation failed. */
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.
135
FLAC__FILE_ENCODER_UNINITIALIZED
136
/**< The encoder is in the uninitialized state. */
138
} FLAC__FileEncoderState;
140
/** Maps a FLAC__FileEncoderState to a C string.
142
* Using a FLAC__FileEncoderState as the index to this array
143
* will give the string equivalent. The contents should not be modified.
145
extern FLAC_API const char * const FLAC__FileEncoderStateString[];
148
/***********************************************************************
150
* class FLAC__FileEncoder
152
***********************************************************************/
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.
161
struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
162
struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
165
/** Signature for the progress callback.
166
* See FLAC__file_encoder_set_progress_callback() for more info.
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().
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);
180
/***********************************************************************
182
* Class constructor/destructor
184
***********************************************************************/
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.
190
* \retval FLAC__FileEncoder*
191
* \c NULL if there was an error allocating memory, else the new instance.
193
FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
195
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
197
* \param encoder A pointer to an existing encoder.
199
* \code encoder != NULL \endcode
201
FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
203
/***********************************************************************
205
* Public class method prototypes
207
***********************************************************************/
209
/** This is inherited from FLAC__SeekableStreamEncoder; see
210
* FLAC__seekable_stream_encoder_set_verify().
213
* \param encoder An encoder instance to set.
214
* \param value See above.
216
* \code encoder != NULL \endcode
218
* \c false if the encoder is already initialized, else \c true.
220
FLAC_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
222
/** This is inherited from FLAC__SeekableStreamEncoder; see
223
* FLAC__seekable_stream_encoder_set_streamable_subset().
226
* \param encoder An encoder instance to set.
227
* \param value See above.
229
* \code encoder != NULL \endcode
231
* \c false if the encoder is already initialized, else \c true.
233
FLAC_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
235
/** This is inherited from FLAC__SeekableStreamEncoder; see
236
* FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
239
* \param encoder An encoder instance to set.
240
* \param value See above.
242
* \code encoder != NULL \endcode
244
* \c false if the encoder is already initialized, else \c true.
246
FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
248
/** This is inherited from FLAC__SeekableStreamEncoder; see
249
* FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
252
* \param encoder An encoder instance to set.
253
* \param value See above.
255
* \code encoder != NULL \endcode
257
* \c false if the encoder is already initialized, else \c true.
259
FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
261
/** This is inherited from FLAC__SeekableStreamEncoder; see
262
* FLAC__seekable_stream_encoder_set_channels().
265
* \param encoder An encoder instance to set.
266
* \param value See above.
268
* \code encoder != NULL \endcode
270
* \c false if the encoder is already initialized, else \c true.
272
FLAC_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
274
/** This is inherited from FLAC__SeekableStreamEncoder; see
275
* FLAC__seekable_stream_encoder_set_bits_per_sample().
278
* Do not feed the encoder data that is wider than the value you
279
* set here or you will generate an invalid stream.
282
* \param encoder An encoder instance to set.
283
* \param value See above.
285
* \code encoder != NULL \endcode
287
* \c false if the encoder is already initialized, else \c true.
289
FLAC_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
291
/** This is inherited from FLAC__SeekableStreamEncoder; see
292
* FLAC__seekable_stream_encoder_set_sample_rate().
295
* \param encoder An encoder instance to set.
296
* \param value See above.
298
* \code encoder != NULL \endcode
300
* \c false if the encoder is already initialized, else \c true.
302
FLAC_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
304
/** This is inherited from FLAC__SeekableStreamEncoder; see
305
* FLAC__seekable_stream_encoder_set_blocksize().
308
* \param encoder An encoder instance to set.
309
* \param value See above.
311
* \code encoder != NULL \endcode
313
* \c false if the encoder is already initialized, else \c true.
315
FLAC_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
317
/** This is inherited from FLAC__SeekableStreamEncoder; see
318
* FLAC__seekable_stream_encoder_set_max_lpc_order().
321
* \param encoder An encoder instance to set.
322
* \param value See above.
324
* \code encoder != NULL \endcode
326
* \c false if the encoder is already initialized, else \c true.
328
FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
330
/** This is inherited from FLAC__SeekableStreamEncoder; see
331
* FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
334
* In the current implementation, qlp_coeff_precision + bits_per_sample must
338
* \param encoder An encoder instance to set.
339
* \param value See above.
341
* \code encoder != NULL \endcode
343
* \c false if the encoder is already initialized, else \c true.
345
FLAC_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
347
/** This is inherited from FLAC__SeekableStreamEncoder; see
348
* FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
351
* \param encoder An encoder instance to set.
352
* \param value See above.
354
* \code encoder != NULL \endcode
356
* \c false if the encoder is already initialized, else \c true.
358
FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
360
/** This is inherited from FLAC__SeekableStreamEncoder; see
361
* FLAC__seekable_stream_encoder_set_do_escape_coding().
364
* \param encoder An encoder instance to set.
365
* \param value See above.
367
* \code encoder != NULL \endcode
369
* \c false if the encoder is already initialized, else \c true.
371
FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
373
/** This is inherited from FLAC__SeekableStreamEncoder; see
374
* FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
377
* \param encoder An encoder instance to set.
378
* \param value See above.
380
* \code encoder != NULL \endcode
382
* \c false if the encoder is already initialized, else \c true.
384
FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
386
/** This is inherited from FLAC__SeekableStreamEncoder; see
387
* FLAC__seekable_stream_encoder_set_min_residual_partition_order().
390
* \param encoder An encoder instance to set.
391
* \param value See above.
393
* \code encoder != NULL \endcode
395
* \c false if the encoder is already initialized, else \c true.
397
FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
399
/** This is inherited from FLAC__SeekableStreamEncoder; see
400
* FLAC__seekable_stream_encoder_set_max_residual_partition_order().
403
* \param encoder An encoder instance to set.
404
* \param value See above.
406
* \code encoder != NULL \endcode
408
* \c false if the encoder is already initialized, else \c true.
410
FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
412
/** This is inherited from FLAC__SeekableStreamEncoder; see
413
* FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
416
* \param encoder An encoder instance to set.
417
* \param value See above.
419
* \code encoder != NULL \endcode
421
* \c false if the encoder is already initialized, else \c true.
423
FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
425
/** This is inherited from FLAC__SeekableStreamEncoder; see
426
* FLAC__seekable_stream_encoder_set_total_samples_estimate().
429
* \param encoder An encoder instance to set.
430
* \param value See above.
432
* \code encoder != NULL \endcode
434
* \c false if the encoder is already initialized, else \c true.
436
FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
438
/** This is inherited from FLAC__SeekableStreamEncoder; see
439
* FLAC__seekable_stream_encoder_set_metadata().
441
* \default \c NULL, 0
442
* \param encoder An encoder instance to set.
443
* \param metadata See above.
444
* \param num_blocks See above.
446
* \code encoder != NULL \endcode
448
* \c false if the encoder is already initialized, else \c true.
450
FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
452
/** Set the output file name encode to.
455
* The filename is mandatory and must be set before initialization.
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.
462
* \param encoder A encoder instance to set.
463
* \param value The output file name.
465
* \code encoder != NULL \endcode
466
* \code value != NULL \endcode
468
* \c false if the encoder is already initialized, or there was a memory
469
* allocation error, else \c true.
471
FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
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().
480
* Unlike most other callbacks, the progress callback is \b not mandatory
481
* and need not be set before initialization.
484
* \param encoder An encoder instance to set.
485
* \param value See above.
487
* \code encoder != NULL \endcode
488
* \code value != NULL \endcode
490
* \c false if the encoder is already initialized, else \c true.
492
FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
494
/** Set the client data to be passed back to callbacks.
495
* This value will be supplied to callbacks in their \a client_data
499
* \param encoder An encoder instance to set.
500
* \param value See above.
502
* \code encoder != NULL \endcode
504
* \c false if the encoder is already initialized, else \c true.
506
FLAC_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
508
/** Get the current encoder state.
510
* \param encoder An encoder instance to query.
512
* \code encoder != NULL \endcode
513
* \retval FLAC__FileEncoderState
514
* The current encoder state.
516
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
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.
522
* \param encoder An encoder instance to query.
524
* \code encoder != NULL \endcode
525
* \retval FLAC__SeekableStreamEncoderState
526
* The seekable stream encoder state.
528
FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
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.
535
* \param encoder An encoder instance to query.
537
* \code encoder != NULL \endcode
538
* \retval FLAC__StreamEncoderState
539
* The seekable stream encoder state.
541
FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
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.
549
* \param encoder An encoder instance to query.
551
* \code encoder != NULL \endcode
552
* \retval FLAC__StreamDecoderState
553
* The stream encoder state.
555
FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
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.
562
* \param encoder A encoder instance to query.
564
* \code encoder != NULL \endcode
565
* \retval const char *
566
* The encoder state as a C string. Do not modify the contents.
568
FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
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
575
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
576
* stream encoder state is
577
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
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.
588
* \code encoder != NULL \endcode
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);
592
/** Get the "verify" flag.
593
* This is inherited from FLAC__SeekableStreamEncoder; see
594
* FLAC__seekable_stream_encoder_get_verify().
596
* \param encoder An encoder instance to query.
598
* \code encoder != NULL \endcode
600
* See FLAC__file_encoder_set_verify().
602
FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
604
/** Get the "streamable subset" flag.
605
* This is inherited from FLAC__SeekableStreamEncoder; see
606
* FLAC__seekable_stream_encoder_get_streamable_subset().
608
* \param encoder An encoder instance to query.
610
* \code encoder != NULL \endcode
612
* See FLAC__file_encoder_set_streamable_subset().
614
FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
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().
620
* \param encoder An encoder instance to query.
622
* \code encoder != NULL \endcode
624
* See FLAC__file_encoder_get_do_mid_side_stereo().
626
FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
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().
632
* \param encoder An encoder instance to query.
634
* \code encoder != NULL \endcode
636
* See FLAC__file_encoder_set_loose_mid_side_stereo().
638
FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
640
/** Get the number of input channels being processed.
641
* This is inherited from FLAC__SeekableStreamEncoder; see
642
* FLAC__seekable_stream_encoder_get_channels().
644
* \param encoder An encoder instance to query.
646
* \code encoder != NULL \endcode
648
* See FLAC__file_encoder_set_channels().
650
FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
652
/** Get the input sample resolution setting.
653
* This is inherited from FLAC__SeekableStreamEncoder; see
654
* FLAC__seekable_stream_encoder_get_bits_per_sample().
656
* \param encoder An encoder instance to query.
658
* \code encoder != NULL \endcode
660
* See FLAC__file_encoder_set_bits_per_sample().
662
FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
664
/** Get the input sample rate setting.
665
* This is inherited from FLAC__SeekableStreamEncoder; see
666
* FLAC__seekable_stream_encoder_get_sample_rate().
668
* \param encoder An encoder instance to query.
670
* \code encoder != NULL \endcode
672
* See FLAC__file_encoder_set_sample_rate().
674
FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
676
/** Get the blocksize setting.
677
* This is inherited from FLAC__SeekableStreamEncoder; see
678
* FLAC__seekable_stream_encoder_get_blocksize().
680
* \param encoder An encoder instance to query.
682
* \code encoder != NULL \endcode
684
* See FLAC__file_encoder_set_blocksize().
686
FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
688
/** Get the maximum LPC order setting.
689
* This is inherited from FLAC__SeekableStreamEncoder; see
690
* FLAC__seekable_stream_encoder_get_max_lpc_order().
692
* \param encoder An encoder instance to query.
694
* \code encoder != NULL \endcode
696
* See FLAC__file_encoder_set_max_lpc_order().
698
FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
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().
704
* \param encoder An encoder instance to query.
706
* \code encoder != NULL \endcode
708
* See FLAC__file_encoder_set_qlp_coeff_precision().
710
FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
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().
716
* \param encoder An encoder instance to query.
718
* \code encoder != NULL \endcode
720
* See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
722
FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
724
/** Get the "escape coding" flag.
725
* This is inherited from FLAC__SeekableStreamEncoder; see
726
* FLAC__seekable_stream_encoder_get_do_escape_coding().
728
* \param encoder An encoder instance to query.
730
* \code encoder != NULL \endcode
732
* See FLAC__file_encoder_set_do_escape_coding().
734
FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
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().
740
* \param encoder An encoder instance to query.
742
* \code encoder != NULL \endcode
744
* See FLAC__file_encoder_set_do_exhaustive_model_search().
746
FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
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().
752
* \param encoder An encoder instance to query.
754
* \code encoder != NULL \endcode
756
* See FLAC__file_encoder_set_min_residual_partition_order().
758
FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
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().
764
* \param encoder An encoder instance to query.
766
* \code encoder != NULL \endcode
768
* See FLAC__file_encoder_set_max_residual_partition_order().
770
FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
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().
776
* \param encoder An encoder instance to query.
778
* \code encoder != NULL \endcode
780
* See FLAC__file_encoder_set_rice_parameter_search_dist().
782
FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
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().
788
* \param encoder An encoder instance to query.
790
* \code encoder != NULL \endcode
791
* \retval FLAC__uint64
792
* See FLAC__file_encoder_set_total_samples_estimate().
794
FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
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.
803
* \param encoder An uninitialized encoder instance.
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.
810
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
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.
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().
822
* \param encoder An uninitialized encoder instance.
824
* \code encoder != NULL \endcode
826
FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
828
/** Submit data for encoding.
829
* This is inherited from FLAC__SeekableStreamEncoder; see
830
* FLAC__seekable_stream_encoder_process().
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.
836
* \code encoder != NULL \endcode
837
* \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
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
843
FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
845
/** Submit data for encoding.
846
* This is inherited from FLAC__SeekableStreamEncoder; see
847
* FLAC__seekable_stream_encoder_process_interleaved().
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.
856
* \code encoder != NULL \endcode
857
* \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
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
863
FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
added
removed
include/FLAC/file_encoder.h
