file_encoder.h (33083B)
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