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