seekable_stream_encoder.h - vx32 - Local 9vx git repository for patches.
(HTM) git clone git://r-36.net/vx32
(DIR) Log
(DIR) Files
(DIR) Refs
---
seekable_stream_encoder.h (39615B)
---
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__SEEKABLE_STREAM_ENCODER_H
33 #define FLAC__SEEKABLE_STREAM_ENCODER_H
34
35 #include "export.h"
36 #include "stream_encoder.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42
43 /** \file include/FLAC/seekable_stream_encoder.h
44 *
45 * \brief
46 * This module contains the functions which implement the seekable stream
47 * encoder.
48 *
49 * See the detailed documentation in the
50 * \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
51 */
52
53 /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
54 * \ingroup flac_encoder
55 *
56 * \brief
57 * This module contains the functions which implement the seekable stream
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__seekable_stream_encoder_new().
63 * - The program overrides the default settings and sets callbacks using
64 * FLAC__seekable_stream_encoder_set_*() functions.
65 * - The program initializes the instance to validate the settings and
66 * prepare for encoding using FLAC__seekable_stream_encoder_init().
67 * - The program calls FLAC__seekable_stream_encoder_process() or
68 * FLAC__seekable_stream_encoder_process_interleaved() to encode data, which
69 * subsequently calls the callbacks when there is encoder data ready
70 * to be written.
71 * - The program finishes the encoding with FLAC__seekable_stream_encoder_finish(),
72 * which causes the encoder to encode any data still in its input pipe,
73 * rewrite the metadata with the final encoding statistics, and finally
74 * reset the encoder to the uninitialized state.
75 * - The instance may be used again or deleted with
76 * FLAC__seekable_stream_encoder_delete().
77 *
78 * The seekable stream encoder is a wrapper around the
79 * \link flac_stream_encoder stream encoder \endlink with callbacks for
80 * seeking the output and reporting the output stream position. This
81 * allows the encoder to go back and rewrite some of the metadata after
82 * encoding if necessary, and provides the metadata callback of the stream
83 * encoder internally. However, you must provide seek and tell callbacks
84 * (see FLAC__seekable_stream_encoder_set_seek_callback() and
85 * FLAC__seekable_stream_encoder_set_tell_callback()).
86 *
87 * Make sure to read the detailed description of the
88 * \link flac_stream_encoder stream encoder module \endlink since the
89 * seekable stream encoder inherits much of its behavior.
90 *
91 * \note
92 * If you are writing the FLAC data to a file, make sure it is open
93 * for update (e.g. mode "w+" for stdio streams). This is because after
94 * the first encoding pass, the encoder will try to seek back to the
95 * beginning of the stream, to the STREAMINFO block, to write some data
96 * there.
97 *
98 * \note
99 * The "set" functions may only be called when the encoder is in the
100 * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
101 * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
102 * before FLAC__seekable_stream_encoder_init(). If this is the case they will
103 * return \c true, otherwise \c false.
104 *
105 * \note
106 * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
107 * defaults, including the callbacks.
108 *
109 * \{
110 */
111
112
113 /** State values for a FLAC__SeekableStreamEncoder
114 *
115 * The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
116 */
117 typedef enum {
118
119 FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
120 /**< The encoder is in the normal OK state. */
121
122 FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
123 /**< An error occurred in the underlying stream encoder;
124 * check FLAC__seekable_stream_encoder_get_stream_encoder_state().
125 */
126
127 FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
128 /**< Memory allocation failed. */
129
130 FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
131 /**< The write callback returned an error. */
132
133 FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
134 /**< The read callback returned an error. */
135
136 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
137 /**< The seek callback returned an error. */
138
139 FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
140 /**< The tell callback returned an error. */
141
142 FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
143 /**< FLAC__seekable_stream_encoder_init() was called when the encoder was
144 * already initialized, usually because
145 * FLAC__seekable_stream_encoder_finish() was not called.
146 */
147
148 FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
149 /**< FLAC__seekable_stream_encoder_init() was called without all
150 * callbacks being set.
151 */
152
153 FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
154 /**< An invalid seek table was passed is the metadata to
155 * FLAC__seekable_stream_encoder_set_metadata().
156 */
157
158 FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
159 /**< The encoder is in the uninitialized state. */
160
161 } FLAC__SeekableStreamEncoderState;
162
163 /** Maps a FLAC__SeekableStreamEncoderState to a C string.
164 *
165 * Using a FLAC__SeekableStreamEncoderState as the index to this array
166 * will give the string equivalent. The contents should not be modified.
167 */
168 extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
169
170
171 /** Return values for the FLAC__SeekableStreamEncoder seek callback.
172 */
173 typedef enum {
174
175 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
176 /**< The seek was OK and encoding can continue. */
177
178 FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
179 /**< An unrecoverable error occurred. The encoder will return from the process call. */
180
181 } FLAC__SeekableStreamEncoderSeekStatus;
182
183 /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
184 *
185 * Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
186 * will give the string equivalent. The contents should not be modified.
187 */
188 extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
189
190
191 /** Return values for the FLAC__SeekableStreamEncoder tell callback.
192 */
193 typedef enum {
194
195 FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK,
196 /**< The tell was OK and encoding can continue. */
197
198 FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR
199 /**< An unrecoverable error occurred. The encoder will return from the process call. */
200
201 } FLAC__SeekableStreamEncoderTellStatus;
202
203 /** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string.
204 *
205 * Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array
206 * will give the string equivalent. The contents should not be modified.
207 */
208 extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[];
209
210
211 /***********************************************************************
212 *
213 * class FLAC__SeekableStreamEncoder
214 *
215 ***********************************************************************/
216
217 struct FLAC__SeekableStreamEncoderProtected;
218 struct FLAC__SeekableStreamEncoderPrivate;
219 /** The opaque structure definition for the seekable stream encoder type.
220 * See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
221 * for a detailed description.
222 */
223 typedef struct {
224 struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
225 struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
226 } FLAC__SeekableStreamEncoder;
227
228 /** Signature for the seek callback.
229 * See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
230 *
231 * \param encoder The encoder instance calling the callback.
232 * \param absolute_byte_offset The offset from the beginning of the stream
233 * to seek to.
234 * \param client_data The callee's client data set through
235 * FLAC__seekable_stream_encoder_set_client_data().
236 * \retval FLAC__SeekableStreamEncoderSeekStatus
237 * The callee's return status.
238 */
239 typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
240
241 /** Signature for the tell callback.
242 * See FLAC__seekable_stream_encoder_set_tell_callback() for more info.
243 *
244 * \warning
245 * The callback must return the true current byte offset of the output to
246 * which the encoder is writing. If you are buffering the output, make
247 * sure and take this into account. If you are writing directly to a
248 * FILE* from your write callback, ftell() is sufficient. If you are
249 * writing directly to a file descriptor from your write callback, you
250 * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
251 * these points to rewrite metadata after encoding.
252 *
253 * \param encoder The encoder instance calling the callback.
254 * \param absolute_byte_offset The address at which to store the current
255 * position of the output.
256 * \param client_data The callee's client data set through
257 * FLAC__seekable_stream_encoder_set_client_data().
258 * \retval FLAC__SeekableStreamEncoderTellStatus
259 * The callee's return status.
260 */
261 typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
262
263 /** Signature for the write callback.
264 * See FLAC__seekable_stream_encoder_set_write_callback()
265 * and FLAC__StreamEncoderWriteCallback for more info.
266 *
267 * \param encoder The encoder instance calling the callback.
268 * \param buffer An array of encoded data of length \a bytes.
269 * \param bytes The byte length of \a buffer.
270 * \param samples The number of samples encoded by \a buffer.
271 * \c 0 has a special meaning; see
272 * FLAC__stream_encoder_set_write_callback().
273 * \param current_frame The number of current frame being encoded.
274 * \param client_data The callee's client data set through
275 * FLAC__seekable_stream_encoder_set_client_data().
276 * \retval FLAC__StreamEncoderWriteStatus
277 * The callee's return status.
278 */
279 typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
280
281
282 /***********************************************************************
283 *
284 * Class constructor/destructor
285 *
286 ***********************************************************************/
287
288 /** Create a new seekable stream encoder instance. The instance is created with
289 * default settings; see the individual FLAC__seekable_stream_encoder_set_*()
290 * functions for each setting's default.
291 *
292 * \retval FLAC__SeekableStreamEncoder*
293 * \c NULL if there was an error allocating memory, else the new instance.
294 */
295 FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
296
297 /** Free an encoder instance. Deletes the object pointed to by \a encoder.
298 *
299 * \param encoder A pointer to an existing encoder.
300 * \assert
301 * \code encoder != NULL \endcode
302 */
303 FLAC_API void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
304
305 /***********************************************************************
306 *
307 * Public class method prototypes
308 *
309 ***********************************************************************/
310
311 /** This is inherited from FLAC__StreamEncoder; see
312 * FLAC__stream_encoder_set_verify().
313 *
314 * \default \c true
315 * \param encoder An encoder instance to set.
316 * \param value See above.
317 * \assert
318 * \code encoder != NULL \endcode
319 * \retval FLAC__bool
320 * \c false if the encoder is already initialized, else \c true.
321 */
322 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
323
324 /** This is inherited from FLAC__StreamEncoder; see
325 * FLAC__stream_encoder_set_streamable_subset().
326 *
327 * \default \c true
328 * \param encoder An encoder instance to set.
329 * \param value See above.
330 * \assert
331 * \code encoder != NULL \endcode
332 * \retval FLAC__bool
333 * \c false if the encoder is already initialized, else \c true.
334 */
335 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
336
337 /** This is inherited from FLAC__StreamEncoder; see
338 * FLAC__stream_encoder_set_do_mid_side_stereo().
339 *
340 * \default \c false
341 * \param encoder An encoder instance to set.
342 * \param value See above.
343 * \assert
344 * \code encoder != NULL \endcode
345 * \retval FLAC__bool
346 * \c false if the encoder is already initialized, else \c true.
347 */
348 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
349
350 /** This is inherited from FLAC__StreamEncoder; see
351 * FLAC__stream_encoder_set_loose_mid_side_stereo().
352 *
353 * \default \c false
354 * \param encoder An encoder instance to set.
355 * \param value See above.
356 * \assert
357 * \code encoder != NULL \endcode
358 * \retval FLAC__bool
359 * \c false if the encoder is already initialized, else \c true.
360 */
361 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
362
363 /** This is inherited from FLAC__StreamEncoder; see
364 * FLAC__stream_encoder_set_channels().
365 *
366 * \default \c 2
367 * \param encoder An encoder instance to set.
368 * \param value See above.
369 * \assert
370 * \code encoder != NULL \endcode
371 * \retval FLAC__bool
372 * \c false if the encoder is already initialized, else \c true.
373 */
374 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
375
376 /** This is inherited from FLAC__StreamEncoder; see
377 * FLAC__stream_encoder_set_bits_per_sample().
378 *
379 * \warning
380 * Do not feed the encoder data that is wider than the value you
381 * set here or you will generate an invalid stream.
382 *
383 * \default \c 16
384 * \param encoder An encoder instance to set.
385 * \param value See above.
386 * \assert
387 * \code encoder != NULL \endcode
388 * \retval FLAC__bool
389 * \c false if the encoder is already initialized, else \c true.
390 */
391 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
392
393 /** This is inherited from FLAC__StreamEncoder; see
394 * FLAC__stream_encoder_set_sample_rate().
395 *
396 * \default \c 44100
397 * \param encoder An encoder instance to set.
398 * \param value See above.
399 * \assert
400 * \code encoder != NULL \endcode
401 * \retval FLAC__bool
402 * \c false if the encoder is already initialized, else \c true.
403 */
404 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
405
406 /** This is inherited from FLAC__StreamEncoder; see
407 * FLAC__stream_encoder_set_blocksize().
408 *
409 * \default \c 1152
410 * \param encoder An encoder instance to set.
411 * \param value See above.
412 * \assert
413 * \code encoder != NULL \endcode
414 * \retval FLAC__bool
415 * \c false if the encoder is already initialized, else \c true.
416 */
417 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
418
419 /** This is inherited from FLAC__StreamEncoder; see
420 * FLAC__stream_encoder_set_max_lpc_order().
421 *
422 * \default \c 0
423 * \param encoder An encoder instance to set.
424 * \param value See above.
425 * \assert
426 * \code encoder != NULL \endcode
427 * \retval FLAC__bool
428 * \c false if the encoder is already initialized, else \c true.
429 */
430 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
431
432 /** This is inherited from FLAC__StreamEncoder; see
433 * FLAC__stream_encoder_set_qlp_coeff_precision().
434 *
435 * \note
436 * In the current implementation, qlp_coeff_precision + bits_per_sample must
437 * be less than 32.
438 *
439 * \default \c 0
440 * \param encoder An encoder instance to set.
441 * \param value See above.
442 * \assert
443 * \code encoder != NULL \endcode
444 * \retval FLAC__bool
445 * \c false if the encoder is already initialized, else \c true.
446 */
447 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
448
449 /** This is inherited from FLAC__StreamEncoder; see
450 * FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
451 *
452 * \default \c false
453 * \param encoder An encoder instance to set.
454 * \param value See above.
455 * \assert
456 * \code encoder != NULL \endcode
457 * \retval FLAC__bool
458 * \c false if the encoder is already initialized, else \c true.
459 */
460 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
461
462 /** This is inherited from FLAC__StreamEncoder; see
463 * FLAC__stream_encoder_set_do_escape_coding().
464 *
465 * \default \c false
466 * \param encoder An encoder instance to set.
467 * \param value See above.
468 * \assert
469 * \code encoder != NULL \endcode
470 * \retval FLAC__bool
471 * \c false if the encoder is already initialized, else \c true.
472 */
473 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
474
475 /** This is inherited from FLAC__StreamEncoder; see
476 * FLAC__stream_encoder_set_do_exhaustive_model_search().
477 *
478 * \default \c false
479 * \param encoder An encoder instance to set.
480 * \param value See above.
481 * \assert
482 * \code encoder != NULL \endcode
483 * \retval FLAC__bool
484 * \c false if the encoder is already initialized, else \c true.
485 */
486 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
487
488 /** This is inherited from FLAC__StreamEncoder; see
489 * FLAC__stream_encoder_set_min_residual_partition_order().
490 *
491 * \default \c 0
492 * \param encoder An encoder instance to set.
493 * \param value See above.
494 * \assert
495 * \code encoder != NULL \endcode
496 * \retval FLAC__bool
497 * \c false if the encoder is already initialized, else \c true.
498 */
499 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
500
501 /** This is inherited from FLAC__StreamEncoder; see
502 * FLAC__stream_encoder_set_max_residual_partition_order().
503 *
504 * \default \c 0
505 * \param encoder An encoder instance to set.
506 * \param value See above.
507 * \assert
508 * \code encoder != NULL \endcode
509 * \retval FLAC__bool
510 * \c false if the encoder is already initialized, else \c true.
511 */
512 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
513
514 /** This is inherited from FLAC__StreamEncoder; see
515 * FLAC__stream_encoder_set_rice_parameter_search_dist().
516 *
517 * \default \c 0
518 * \param encoder An encoder instance to set.
519 * \param value See above.
520 * \assert
521 * \code encoder != NULL \endcode
522 * \retval FLAC__bool
523 * \c false if the encoder is already initialized, else \c true.
524 */
525 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
526
527 /** This is inherited from FLAC__StreamEncoder; see
528 * FLAC__stream_encoder_set_total_samples_estimate().
529 *
530 * \default \c 0
531 * \param encoder An encoder instance to set.
532 * \param value See above.
533 * \assert
534 * \code encoder != NULL \endcode
535 * \retval FLAC__bool
536 * \c false if the encoder is already initialized, else \c true.
537 */
538 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
539
540 /** This is inherited from FLAC__StreamEncoder; see
541 * FLAC__stream_encoder_set_metadata().
542 *
543 * \note
544 * SEEKTABLE blocks are handled specially. Since you will not know
545 * the values for the seek point stream offsets, you should pass in
546 * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
547 * required sample numbers (or placeholder points), with \c 0 for the
548 * \a frame_samples and \a stream_offset fields for each point. While
549 * encoding, the encoder will fill them in for you and when encoding
550 * is finished, it will seek back and write the real values into the
551 * SEEKTABLE block in the stream. There are helper routines for
552 * manipulating seektable template blocks; see metadata.h:
553 * FLAC__metadata_object_seektable_template_*().
554 *
555 * \note
556 * The encoder instance \b will modify the first \c SEEKTABLE block
557 * as it transforms the template to a valid seektable while encoding,
558 * but it is still up to the caller to free all metadata blocks after
559 * encoding.
560 *
561 * \default \c NULL, 0
562 * \param encoder An encoder instance to set.
563 * \param metadata See above.
564 * \param num_blocks See above.
565 * \assert
566 * \code encoder != NULL \endcode
567 * \retval FLAC__bool
568 * \c false if the encoder is already initialized, else \c true.
569 */
570 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
571
572 /** Set the seek callback.
573 * The supplied function will be called when the encoder needs to seek
574 * the output stream. The encoder will pass the absolute byte offset
575 * to seek to, 0 meaning the beginning of the stream.
576 *
577 * \note
578 * The callback is mandatory and must be set before initialization.
579 *
580 * \default \c NULL
581 * \param encoder An encoder instance to set.
582 * \param value See above.
583 * \assert
584 * \code encoder != NULL \endcode
585 * \code value != NULL \endcode
586 * \retval FLAC__bool
587 * \c false if the encoder is already initialized, else \c true.
588 */
589 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
590
591 /** Set the tell callback.
592 * The supplied function will be called when the encoder needs to know
593 * the current position of the output stream.
594 *
595 * \note
596 * The callback is mandatory and must be set before initialization.
597 *
598 * \default \c NULL
599 * \param encoder An encoder instance to set.
600 * \param value See above.
601 * \assert
602 * \code encoder != NULL \endcode
603 * \code value != NULL \endcode
604 * \retval FLAC__bool
605 * \c false if the encoder is already initialized, else \c true.
606 */
607 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value);
608
609 /** Set the write callback.
610 * This is inherited from FLAC__StreamEncoder; see
611 * FLAC__stream_encoder_set_write_callback().
612 *
613 * \note
614 * The callback is mandatory and must be set before initialization.
615 *
616 * \default \c NULL
617 * \param encoder An encoder instance to set.
618 * \param value See above.
619 * \assert
620 * \code encoder != NULL \endcode
621 * \code value != NULL \endcode
622 * \retval FLAC__bool
623 * \c false if the encoder is already initialized, else \c true.
624 */
625 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
626
627 /** Set the client data to be passed back to callbacks.
628 * This value will be supplied to callbacks in their \a client_data
629 * argument.
630 *
631 * \default \c NULL
632 * \param encoder An encoder instance to set.
633 * \param value See above.
634 * \assert
635 * \code encoder != NULL \endcode
636 * \retval FLAC__bool
637 * \c false if the encoder is already initialized, else \c true.
638 */
639 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
640
641 /** Get the current encoder state.
642 *
643 * \param encoder An encoder instance to query.
644 * \assert
645 * \code encoder != NULL \endcode
646 * \retval FLAC__SeekableStreamEncoderState
647 * The current encoder state.
648 */
649 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
650
651 /** Get the state of the underlying stream encoder.
652 * Useful when the seekable stream encoder state is
653 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
654 *
655 * \param encoder An encoder instance to query.
656 * \assert
657 * \code encoder != NULL \endcode
658 * \retval FLAC__StreamEncoderState
659 * The stream encoder state.
660 */
661 FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
662
663 /** Get the state of the underlying stream encoder's verify decoder.
664 * Useful when the seekable stream encoder state is
665 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
666 * stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
667 *
668 * \param encoder An encoder instance to query.
669 * \assert
670 * \code encoder != NULL \endcode
671 * \retval FLAC__StreamDecoderState
672 * The stream encoder state.
673 */
674 FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
675
676 /** Get the current encoder state as a C string.
677 * This version automatically resolves
678 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the
679 * stream encoder's state.
680 *
681 * \param encoder A encoder instance to query.
682 * \assert
683 * \code encoder != NULL \endcode
684 * \retval const char *
685 * The encoder state as a C string. Do not modify the contents.
686 */
687 FLAC_API const char *FLAC__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
688
689 /** Get relevant values about the nature of a verify decoder error.
690 * Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
691 * Useful when the seekable stream encoder state is
692 * \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
693 * stream encoder state is
694 * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
695 *
696 * \param encoder An encoder instance to query.
697 * \param absolute_sample The absolute sample number of the mismatch.
698 * \param frame_number The number of the frame in which the mismatch occurred.
699 * \param channel The channel in which the mismatch occurred.
700 * \param sample The number of the sample (relative to the frame) in
701 * which the mismatch occurred.
702 * \param expected The expected value for the sample in question.
703 * \param got The actual value returned by the decoder.
704 * \assert
705 * \code encoder != NULL \endcode
706 */
707 FLAC_API void FLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
708
709 /** Get the "verify" flag.
710 * This is inherited from FLAC__StreamEncoder; see
711 * FLAC__stream_encoder_get_verify().
712 *
713 * \param encoder An encoder instance to query.
714 * \assert
715 * \code encoder != NULL \endcode
716 * \retval FLAC__bool
717 * See FLAC__seekable_stream_encoder_set_verify().
718 */
719 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
720
721 /** Get the "streamable subset" flag.
722 * This is inherited from FLAC__StreamEncoder; see
723 * FLAC__stream_encoder_get_streamable_subset().
724 *
725 * \param encoder An encoder instance to query.
726 * \assert
727 * \code encoder != NULL \endcode
728 * \retval FLAC__bool
729 * See FLAC__seekable_stream_encoder_set_streamable_subset().
730 */
731 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
732
733 /** Get the "mid/side stereo coding" flag.
734 * This is inherited from FLAC__StreamEncoder; see
735 * FLAC__stream_encoder_get_do_mid_side_stereo().
736 *
737 * \param encoder An encoder instance to query.
738 * \assert
739 * \code encoder != NULL \endcode
740 * \retval FLAC__bool
741 * See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
742 */
743 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
744
745 /** Get the "adaptive mid/side switching" flag.
746 * This is inherited from FLAC__StreamEncoder; see
747 * FLAC__stream_encoder_get_loose_mid_side_stereo().
748 *
749 * \param encoder An encoder instance to query.
750 * \assert
751 * \code encoder != NULL \endcode
752 * \retval FLAC__bool
753 * See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
754 */
755 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
756
757 /** Get the number of input channels being processed.
758 * This is inherited from FLAC__StreamEncoder; see
759 * FLAC__stream_encoder_get_channels().
760 *
761 * \param encoder An encoder instance to query.
762 * \assert
763 * \code encoder != NULL \endcode
764 * \retval unsigned
765 * See FLAC__seekable_stream_encoder_set_channels().
766 */
767 FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
768
769 /** Get the input sample resolution setting.
770 * This is inherited from FLAC__StreamEncoder; see
771 * FLAC__stream_encoder_get_bits_per_sample().
772 *
773 * \param encoder An encoder instance to query.
774 * \assert
775 * \code encoder != NULL \endcode
776 * \retval unsigned
777 * See FLAC__seekable_stream_encoder_set_bits_per_sample().
778 */
779 FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
780
781 /** Get the input sample rate setting.
782 * This is inherited from FLAC__StreamEncoder; see
783 * FLAC__stream_encoder_get_sample_rate().
784 *
785 * \param encoder An encoder instance to query.
786 * \assert
787 * \code encoder != NULL \endcode
788 * \retval unsigned
789 * See FLAC__seekable_stream_encoder_set_sample_rate().
790 */
791 FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
792
793 /** Get the blocksize setting.
794 * This is inherited from FLAC__StreamEncoder; see
795 * FLAC__stream_encoder_get_blocksize().
796 *
797 * \param encoder An encoder instance to query.
798 * \assert
799 * \code encoder != NULL \endcode
800 * \retval unsigned
801 * See FLAC__seekable_stream_encoder_set_blocksize().
802 */
803 FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
804
805 /** Get the maximum LPC order setting.
806 * This is inherited from FLAC__StreamEncoder; see
807 * FLAC__stream_encoder_get_max_lpc_order().
808 *
809 * \param encoder An encoder instance to query.
810 * \assert
811 * \code encoder != NULL \endcode
812 * \retval unsigned
813 * See FLAC__seekable_stream_encoder_set_max_lpc_order().
814 */
815 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
816
817 /** Get the quantized linear predictor coefficient precision setting.
818 * This is inherited from FLAC__StreamEncoder; see
819 * FLAC__stream_encoder_get_qlp_coeff_precision().
820 *
821 * \param encoder An encoder instance to query.
822 * \assert
823 * \code encoder != NULL \endcode
824 * \retval unsigned
825 * See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
826 */
827 FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
828
829 /** Get the qlp coefficient precision search flag.
830 * This is inherited from FLAC__StreamEncoder; see
831 * FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
832 *
833 * \param encoder An encoder instance to query.
834 * \assert
835 * \code encoder != NULL \endcode
836 * \retval FLAC__bool
837 * See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
838 */
839 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
840
841 /** Get the "escape coding" flag.
842 * This is inherited from FLAC__StreamEncoder; see
843 * FLAC__stream_encoder_get_do_escape_coding().
844 *
845 * \param encoder An encoder instance to query.
846 * \assert
847 * \code encoder != NULL \endcode
848 * \retval FLAC__bool
849 * See FLAC__seekable_stream_encoder_set_do_escape_coding().
850 */
851 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
852
853 /** Get the exhaustive model search flag.
854 * This is inherited from FLAC__StreamEncoder; see
855 * FLAC__stream_encoder_get_do_exhaustive_model_search().
856 *
857 * \param encoder An encoder instance to query.
858 * \assert
859 * \code encoder != NULL \endcode
860 * \retval FLAC__bool
861 * See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
862 */
863 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
864
865 /** Get the minimum residual partition order setting.
866 * This is inherited from FLAC__StreamEncoder; see
867 * FLAC__stream_encoder_get_min_residual_partition_order().
868 *
869 * \param encoder An encoder instance to query.
870 * \assert
871 * \code encoder != NULL \endcode
872 * \retval unsigned
873 * See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
874 */
875 FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
876
877 /** Get maximum residual partition order setting.
878 * This is inherited from FLAC__StreamEncoder; see
879 * FLAC__stream_encoder_get_max_residual_partition_order().
880 *
881 * \param encoder An encoder instance to query.
882 * \assert
883 * \code encoder != NULL \endcode
884 * \retval unsigned
885 * See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
886 */
887 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
888
889 /** Get the Rice parameter search distance setting.
890 * This is inherited from FLAC__StreamEncoder; see
891 * FLAC__stream_encoder_get_rice_parameter_search_dist().
892 *
893 * \param encoder An encoder instance to query.
894 * \assert
895 * \code encoder != NULL \endcode
896 * \retval unsigned
897 * See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
898 */
899 FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
900
901 /** Get the previously set estimate of the total samples to be encoded.
902 * This is inherited from FLAC__StreamEncoder; see
903 * FLAC__stream_encoder_get_total_samples_estimate().
904 *
905 * \param encoder An encoder instance to query.
906 * \assert
907 * \code encoder != NULL \endcode
908 * \retval FLAC__uint64
909 * See FLAC__seekable_stream_encoder_set_total_samples_estimate().
910 */
911 FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
912
913 /** Initialize the encoder instance.
914 * Should be called after FLAC__seekable_stream_encoder_new() and
915 * FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
916 * or FLAC__seekable_stream_encoder_process_interleaved(). Will set and return
917 * the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
918 * initialization succeeded.
919 *
920 * The call to FLAC__seekable_stream_encoder_init() currently will also immediately
921 * call the write callback with the \c fLaC signature and all the encoded
922 * metadata.
923 *
924 * \param encoder An uninitialized encoder instance.
925 * \assert
926 * \code encoder != NULL \endcode
927 * \retval FLAC__SeekableStreamEncoderState
928 * \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
929 * FLAC__SeekableStreamEncoderState for the meanings of other return values.
930 */
931 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
932
933 /** Finish the encoding process.
934 * Flushes the encoding buffer, releases resources, resets the encoder
935 * settings to their defaults, and returns the encoder state to
936 * FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
937 *
938 * In the event of a prematurely-terminated encode, it is not strictly
939 * necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
940 * but it is good practice to match every FLAC__seekable_stream_encoder_init()
941 * with a FLAC__seekable_stream_encoder_finish().
942 *
943 * \param encoder An uninitialized encoder instance.
944 * \assert
945 * \code encoder != NULL \endcode
946 */
947 FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
948
949 /** Submit data for encoding.
950 * This is inherited from FLAC__StreamEncoder; see
951 * FLAC__stream_encoder_process().
952 *
953 * \param encoder An initialized encoder instance in the OK state.
954 * \param buffer An array of pointers to each channel's signal.
955 * \param samples The number of samples in one channel.
956 * \assert
957 * \code encoder != NULL \endcode
958 * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
959 * \retval FLAC__bool
960 * \c true if successful, else \c false; in this case, check the
961 * encoder state with FLAC__seekable_stream_encoder_get_state() to see what
962 * went wrong.
963 */
964 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
965
966 /** Submit data for encoding.
967 * This is inherited from FLAC__StreamEncoder; see
968 * FLAC__stream_encoder_process_interleaved().
969 *
970 * \param encoder An initialized encoder instance in the OK state.
971 * \param buffer An array of channel-interleaved data (see above).
972 * \param samples The number of samples in one channel, the same as for
973 * FLAC__seekable_stream_encoder_process(). For example, if
974 * encoding two channels, \c 1000 \a samples corresponds
975 * to a \a buffer of 2000 values.
976 * \assert
977 * \code encoder != NULL \endcode
978 * \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
979 * \retval FLAC__bool
980 * \c true if successful, else \c false; in this case, check the
981 * encoder state with FLAC__seekable_stream_encoder_get_state() to see what
982 * went wrong.
983 */
984 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
985
986 /* \} */
987
988 #ifdef __cplusplus
989 }
990 #endif
991
992 #endif