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