include/FLAC/seekable_stream_encoder.h

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