diff options
Diffstat (limited to 'apps/codecs/libFLAC/include/FLAC/file_encoder.h')
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/file_encoder.h | 871 |
1 files changed, 871 insertions, 0 deletions
diff --git a/apps/codecs/libFLAC/include/FLAC/file_encoder.h b/apps/codecs/libFLAC/include/FLAC/file_encoder.h new file mode 100644 index 0000000000..fbbfadb303 --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/file_encoder.h | |||
@@ -0,0 +1,871 @@ | |||
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 | ||