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 relevant values about the nature of a verify decoder error.
 601  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
 602  *  Useful when the seekable stream encoder state is
 603  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
 604  *  stream encoder state is
 605  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 606  *
 607  * \param  encoder  An encoder instance to query.
 608  * \param  absolute_sample  The absolute sample number of the mismatch.
 609  * \param  frame_number  The number of the frame in which the mismatch occurred.
 610  * \param  channel       The channel in which the mismatch occurred.
 611  * \param  sample        The number of the sample (relative to the frame) in
 612  *                       which the mismatch occurred.
 613  * \param  expected      The expected value for the sample in question.
 614  * \param  got           The actual value returned by the decoder.
 615  * \assert
 616  *    \code encoder != NULL \endcode
 617  */
 618 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);
 619
 620 /** Get the "verify" flag.
 621  *  This is inherited from FLAC__StreamEncoder; see
 622  *  FLAC__stream_encoder_get_verify().
 623  *
 624  * \param  encoder  An encoder instance to query.
 625  * \assert
 626  *    \code encoder != NULL \endcode
 627  * \retval FLAC__bool
 628  *    See FLAC__seekable_stream_encoder_set_verify().
 629  */
 630 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
 631
 632 /** Get the "streamable subset" flag.
 633  *  This is inherited from FLAC__StreamEncoder; see
 634  *  FLAC__stream_encoder_get_streamable_subset().
 635  *
 636  * \param  encoder  An encoder instance to query.
 637  * \assert
 638  *    \code encoder != NULL \endcode
 639  * \retval FLAC__bool
 640  *    See FLAC__seekable_stream_encoder_set_streamable_subset().
 641  */
 642 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
 643
 644 /** Get the "mid/side stereo coding" flag.
 645  *  This is inherited from FLAC__StreamEncoder; see
 646  *  FLAC__stream_encoder_get_do_mid_side_stereo().
 647  *
 648  * \param  encoder  An encoder instance to query.
 649  * \assert
 650  *    \code encoder != NULL \endcode
 651  * \retval FLAC__bool
 652  *    See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
 653  */
 654 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
 655
 656 /** Get the "adaptive mid/side switching" flag.
 657  *  This is inherited from FLAC__StreamEncoder; see
 658  *  FLAC__stream_encoder_get_loose_mid_side_stereo().
 659  *
 660  * \param  encoder  An encoder instance to query.
 661  * \assert
 662  *    \code encoder != NULL \endcode
 663  * \retval FLAC__bool
 664  *    See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
 665  */
 666 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
 667
 668 /** Get the number of input channels being processed.
 669  *  This is inherited from FLAC__StreamEncoder; see
 670  *  FLAC__stream_encoder_get_channels().
 671  *
 672  * \param  encoder  An encoder instance to query.
 673  * \assert
 674  *    \code encoder != NULL \endcode
 675  * \retval unsigned
 676  *    See FLAC__seekable_stream_encoder_set_channels().
 677  */
 678 FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
 679
 680 /** Get the input sample resolution setting.
 681  *  This is inherited from FLAC__StreamEncoder; see
 682  *  FLAC__stream_encoder_get_bits_per_sample().
 683  *
 684  * \param  encoder  An encoder instance to query.
 685  * \assert
 686  *    \code encoder != NULL \endcode
 687  * \retval unsigned
 688  *    See FLAC__seekable_stream_encoder_set_bits_per_sample().
 689  */
 690 FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
 691
 692 /** Get the input sample rate setting.
 693  *  This is inherited from FLAC__StreamEncoder; see
 694  *  FLAC__stream_encoder_get_sample_rate().
 695  *
 696  * \param  encoder  An encoder instance to query.
 697  * \assert
 698  *    \code encoder != NULL \endcode
 699  * \retval unsigned
 700  *    See FLAC__seekable_stream_encoder_set_sample_rate().
 701  */
 702 FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
 703
 704 /** Get the blocksize setting.
 705  *  This is inherited from FLAC__StreamEncoder; see
 706  *  FLAC__stream_encoder_get_blocksize().
 707  *
 708  * \param  encoder  An encoder instance to query.
 709  * \assert
 710  *    \code encoder != NULL \endcode
 711  * \retval unsigned
 712  *    See FLAC__seekable_stream_encoder_set_blocksize().
 713  */
 714 FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
 715
 716 /** Get the maximum LPC order setting.
 717  *  This is inherited from FLAC__StreamEncoder; see
 718  *  FLAC__stream_encoder_get_max_lpc_order().
 719  *
 720  * \param  encoder  An encoder instance to query.
 721  * \assert
 722  *    \code encoder != NULL \endcode
 723  * \retval unsigned
 724  *    See FLAC__seekable_stream_encoder_set_max_lpc_order().
 725  */
 726 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
 727
 728 /** Get the quantized linear predictor coefficient precision setting.
 729  *  This is inherited from FLAC__StreamEncoder; see
 730  *  FLAC__stream_encoder_get_qlp_coeff_precision().
 731  *
 732  * \param  encoder  An encoder instance to query.
 733  * \assert
 734  *    \code encoder != NULL \endcode
 735  * \retval unsigned
 736  *    See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
 737  */
 738 FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
 739
 740 /** Get the qlp coefficient precision search flag.
 741  *  This is inherited from FLAC__StreamEncoder; see
 742  *  FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
 743  *
 744  * \param  encoder  An encoder instance to query.
 745  * \assert
 746  *    \code encoder != NULL \endcode
 747  * \retval FLAC__bool
 748  *    See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
 749  */
 750 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
 751
 752 /** Get the "escape coding" flag.
 753  *  This is inherited from FLAC__StreamEncoder; see
 754  *  FLAC__stream_encoder_get_do_escape_coding().
 755  *
 756  * \param  encoder  An encoder instance to query.
 757  * \assert
 758  *    \code encoder != NULL \endcode
 759  * \retval FLAC__bool
 760  *    See FLAC__seekable_stream_encoder_set_do_escape_coding().
 761  */
 762 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
 763
 764 /** Get the exhaustive model search flag.
 765  *  This is inherited from FLAC__StreamEncoder; see
 766  *  FLAC__stream_encoder_get_do_exhaustive_model_search().
 767  *
 768  * \param  encoder  An encoder instance to query.
 769  * \assert
 770  *    \code encoder != NULL \endcode
 771  * \retval FLAC__bool
 772  *    See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
 773  */
 774 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
 775
 776 /** Get the minimum residual partition order setting.
 777  *  This is inherited from FLAC__StreamEncoder; see
 778  *  FLAC__stream_encoder_get_min_residual_partition_order().
 779  *
 780  * \param  encoder  An encoder instance to query.
 781  * \assert
 782  *    \code encoder != NULL \endcode
 783  * \retval unsigned
 784  *    See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
 785  */
 786 FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
 787
 788 /** Get maximum residual partition order setting.
 789  *  This is inherited from FLAC__StreamEncoder; see
 790  *  FLAC__stream_encoder_get_max_residual_partition_order().
 791  *
 792  * \param  encoder  An encoder instance to query.
 793  * \assert
 794  *    \code encoder != NULL \endcode
 795  * \retval unsigned
 796  *    See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
 797  */
 798 FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
 799
 800 /** Get the Rice parameter search distance setting.
 801  *  This is inherited from FLAC__StreamEncoder; see
 802  *  FLAC__stream_encoder_get_rice_parameter_search_dist().
 803  *
 804  * \param  encoder  An encoder instance to query.
 805  * \assert
 806  *    \code encoder != NULL \endcode
 807  * \retval unsigned
 808  *    See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
 809  */
 810 FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
 811
 812 /** Get the previously set estimate of the total samples to be encoded.
 813  *  This is inherited from FLAC__StreamEncoder; see
 814  *  FLAC__stream_encoder_get_total_samples_estimate().
 815  *
 816  * \param  encoder  An encoder instance to query.
 817  * \assert
 818  *    \code encoder != NULL \endcode
 819  * \retval FLAC__uint64
 820  *    See FLAC__seekable_stream_encoder_set_total_samples_estimate().
 821  */
 822 FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
 823
 824 /** Initialize the encoder instance.
 825  *  Should be called after FLAC__seekable_stream_encoder_new() and
 826  *  FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
 827  *  or FLAC__seekable_stream_encoder_process_interleaved().  Will set and return
 828  *  the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
 829  *  initialization succeeded.
 830  *
 831  *  The call to FLAC__seekable_stream_encoder_init() currently will also immediately
 832  *  call the write callback with the \c fLaC signature and all the encoded
 833  *  metadata.
 834  *
 835  * \param  encoder  An uninitialized encoder instance.
 836  * \assert
 837  *    \code encoder != NULL \endcode
 838  * \retval FLAC__SeekableStreamEncoderState
 839  *    \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
 840  *    FLAC__SeekableStreamEncoderState for the meanings of other return values.
 841  */
 842 FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
 843
 844 /** Finish the encoding process.
 845  *  Flushes the encoding buffer, releases resources, resets the encoder
 846  *  settings to their defaults, and returns the encoder state to
 847  *  FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
 848  *
 849  *  In the event of a prematurely-terminated encode, it is not strictly
 850  *  necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
 851  *  but it is good practice to match every FLAC__seekable_stream_encoder_init()
 852  *  with a FLAC__seekable_stream_encoder_finish().
 853  *
 854  * \param  encoder  An uninitialized encoder instance.
 855  * \assert
 856  *    \code encoder != NULL \endcode
 857  */
 858 FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
 859
 860 /** Submit data for encoding.
 861  *  This is inherited from FLAC__StreamEncoder; see
 862  *  FLAC__stream_encoder_process().
 863  *
 864  * \param  encoder  An initialized encoder instance in the OK state.
 865  * \param  buffer   An array of pointers to each channel's signal.
 866  * \param  samples  The number of samples in one channel.
 867  * \assert
 868  *    \code encoder != NULL \endcode
 869  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
 870  * \retval FLAC__bool
 871  *    \c true if successful, else \c false; in this case, check the
 872  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
 873  *    went wrong.
 874  */
 875 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 876
 877 /** Submit data for encoding.
 878  *  This is inherited from FLAC__StreamEncoder; see
 879  *  FLAC__stream_encoder_process_interleaved().
 880  *
 881  * \param  encoder  An initialized encoder instance in the OK state.
 882  * \param  buffer   An array of channel-interleaved data (see above).
 883  * \param  samples  The number of samples in one channel, the same as for
 884  *                  FLAC__seekable_stream_encoder_process().  For example, if
 885  *                  encoding two channels, \c 1000 \a samples corresponds
 886  *                  to a \a buffer of 2000 values.
 887  * \assert
 888  *    \code encoder != NULL \endcode
 889  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
 890  * \retval FLAC__bool
 891  *    \c true if successful, else \c false; in this case, check the
 892  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
 893  *    went wrong.
 894  */
 895 FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 896
 897 /* \} */
 898
 899 #ifdef __cplusplus
 900 }
 901 #endif
 902
 903 #endif