include/OggFLAC/seekable_stream_encoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
   2  * Copyright (C) 2002,2003  Josh Coalson
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  11  * - Redistributions in binary form must reproduce the above copyright
  12  * notice, this list of conditions and the following disclaimer in the
  13  * documentation and/or other materials provided with the distribution.
  14  *
  15  * - Neither the name of the Xiph.org Foundation nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef OggFLAC__SEEKABLE_STREAM_ENCODER_H
  33 #define OggFLAC__SEEKABLE_STREAM_ENCODER_H
  34
  35 #include "export.h"
  36
  37 #include "FLAC/stream_encoder.h"
  38 #include "FLAC/seekable_stream_encoder.h"
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44
  45 /** \file include/OggFLAC/seekable_stream_encoder.h
  46  *
  47  *  \brief
  48  *  This module contains the functions which implement the seekable
  49  *  stream encoder.
  50  *
  51  *  See the detailed documentation in the
  52  *  \link oggflac_seekable_stream_encoder seekable stream encoder \endlink module.
  53  */
  54
  55 /** \defgroup oggflac_seekable_stream_encoder OggFLAC/seekable_stream_encoder.h: seekable stream encoder interface
  56  *  \ingroup oggflac_encoder
  57  *
  58  *  \brief
  59  *  This module contains the functions which implement the seekable
  60  *  stream encoder.  The Ogg seekable stream encoder is derived
  61  *  from the FLAC seekable stream encoder.
  62  *
  63  * The interface here is nearly identical to FLAC's seekable stream
  64  * encoder, including the callback(@@@@@@new read callback and why@@@), with the addition of
  65  * OggFLAC__seekable_stream_encoder_set_serial_number().  See the
  66  * \link flac_seekable_stream_encoder FLAC seekable stream encoder module \endlink
  67  * for full documentation.
  68  *
  69  * \{
  70  */
  71
  72
  73 /** State values for an OggFLAC__SeekableStreamEncoder
  74  *
  75  *  The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
  76  */
  77 typedef enum {
  78
  79         OggFLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
  80         /**< The encoder is in the normal OK state. */
  81
  82         OggFLAC__SEEKABLE_STREAM_ENCODER_OGG_ERROR,
  83         /**< An error occurred in the underlying Ogg layer.  */
  84
  85         OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
  86         /**< An error occurred in the underlying FLAC stream encoder;
  87          * check OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state().
  88          */
  89
  90         OggFLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
  91         /**< Memory allocation failed. */
  92
  93         OggFLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
  94         /**< The write callback returned an error. */
  95
  96         OggFLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
  97         /**< The read callback returned an error. */
  98
  99         OggFLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
 100         /**< The seek callback returned an error. */
 101
 102         OggFLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
 103         /**< The tell callback returned an error. */
 104
 105         OggFLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
 106         /**< OggFLAC__seekable_stream_encoder_init() was called when the encoder was
 107          * already initialized, usually because
 108          * OggFLAC__seekable_stream_encoder_finish() was not called.
 109          */
 110
 111         OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
 112         /**< OggFLAC__seekable_stream_encoder_init() was called without all
 113          * callbacks being set.
 114          */
 115
 116         OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
 117         /**< An invalid seek table was passed is the metadata to
 118          * OggFLAC__seekable_stream_encoder_set_metadata().
 119          */
 120
 121         OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
 122         /**< The encoder is in the uninitialized state. */
 123
 124 } OggFLAC__SeekableStreamEncoderState;
 125
 126 /** Maps an OggFLAC__StreamEncoderState to a C string.
 127  *
 128  *  Using an OggFLAC__StreamEncoderState as the index to this array
 129  *  will give the string equivalent.  The contents should not be modified.
 130  */
 131 extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderStateString[];
 132
 133
 134 /** Return values for the OggFLAC__SeekableStreamEncoder read callback.
 135  */
 136 typedef enum {
 137
 138         OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_CONTINUE,
 139         /**< The read was OK and decoding can continue. */
 140
 141         OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
 142         /**< The read was attempted at the end of the stream. */
 143
 144         OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_ABORT
 145         /**< An unrecoverable error occurred. */
 146
 147 } OggFLAC__SeekableStreamEncoderReadStatus;
 148
 149 /** Maps a OggFLAC__SeekableStreamEncoderReadStatus to a C string.
 150  *
 151  *  Using a OggFLAC__SeekableStreamEncoderReadStatus as the index to this array
 152  *  will give the string equivalent.  The contents should not be modified.
 153  */
 154 extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderReadStatusString[];
 155
 156
 157 /***********************************************************************
 158  *
 159  * class OggFLAC__StreamEncoder
 160  *
 161  ***********************************************************************/
 162
 163 struct OggFLAC__SeekableStreamEncoderProtected;
 164 struct OggFLAC__SeekableStreamEncoderPrivate;
 165 /** The opaque structure definition for the seekable stream encoder type.
 166  *  See the \link oggflac_seekable_stream_encoder seekable stream encoder module \endlink
 167  *  for a detailed description.
 168  */
 169 typedef struct {
 170         struct OggFLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 171         struct OggFLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 172 } OggFLAC__SeekableStreamEncoder;
 173
 174 /** Signature for the read callback.
 175  *  See OggFLAC__seekable_stream_encoder_set_read_callback() for more info.
 176  *
 177  * \param  encoder  The encoder instance calling the callback.
 178  * \param  buffer   A pointer to a location for the callee to store
 179  *                  data to be encoded.
 180  * \param  bytes    A pointer to the size of the buffer.  On entry
 181  *                  to the callback, it contains the maximum number
 182  *                  of bytes that may be stored in \a buffer.  The
 183  *                  callee must set it to the actual number of bytes
 184  *                  stored (0 in case of error or end-of-stream) before
 185  *                  returning.
 186  * \param  client_data  The callee's client data set through
 187  *                      OggFLAC__seekable_stream_encoder_set_client_data().
 188  * \retval OggFLAC__SeekableStreamEncoderReadStatus
 189  *    The callee's return status.
 190  */
 191 typedef OggFLAC__SeekableStreamEncoderReadStatus (*OggFLAC__SeekableStreamEncoderReadCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
 192
 193 /** Signature for the seek callback.
 194  *  See OggFLAC__seekable_stream_encoder_set_seek_callback()
 195  *  and FLAC__SeekableStreamEncoderSeekCallback for more info.
 196  *
 197  * \param  encoder  The encoder instance calling the callback.
 198  * \param  absolute_byte_offset  The offset from the beginning of the stream
 199  *                               to seek to.
 200  * \param  client_data  The callee's client data set through
 201  *                      OggFLAC__seekable_stream_encoder_set_client_data().
 202  * \retval FLAC__SeekableStreamEncoderSeekStatus
 203  *    The callee's return status.
 204  */
 205 typedef FLAC__SeekableStreamEncoderSeekStatus (*OggFLAC__SeekableStreamEncoderSeekCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
 206
 207 /** Signature for the tell callback.
 208  *  See OggFLAC__seekable_stream_encoder_set_tell_callback()
 209  *  and FLAC__SeekableStreamEncoderTellCallback for more info.
 210  *
 211  * \param  encoder  The encoder instance calling the callback.
 212  * \param  absolute_byte_offset  The address at which to store the current
 213  *                               position of the output.
 214  * \param  client_data  The callee's client data set through
 215  *                      OggFLAC__seekable_stream_encoder_set_client_data().
 216  * \retval FLAC__SeekableStreamEncoderTellStatus
 217  *    The callee's return status.
 218  */
 219 typedef FLAC__SeekableStreamEncoderTellStatus (*OggFLAC__SeekableStreamEncoderTellCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
 220
 221 /** Signature for the write callback.
 222  *  See OggFLAC__seekable_stream_encoder_set_write_callback()
 223  *  and FLAC__SeekableStreamEncoderWriteCallback for more info.
 224  *
 225  * \param  encoder  The encoder instance calling the callback.
 226  * \param  buffer   An array of encoded data of length \a bytes.
 227  * \param  bytes    The byte length of \a buffer.
 228  * \param  samples  The number of samples encoded by \a buffer.
 229  *                  \c 0 has a special meaning; see
 230  *                  OggFLAC__seekable_stream_encoder_set_write_callback().
 231  * \param  current_frame  The number of current frame being encoded.
 232  * \param  client_data  The callee's client data set through
 233  *                      OggFLAC__seekable_stream_encoder_set_client_data().
 234  * \retval FLAC__StreamEncoderWriteStatus
 235  *    The callee's return status.
 236  */
 237 typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__SeekableStreamEncoderWriteCallback)(const OggFLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 238
 239
 240 /***********************************************************************
 241  *
 242  * Class constructor/destructor
 243  *
 244  ***********************************************************************/
 245
 246 /** Create a new seekable stream encoder instance.  The instance is created with
 247  *  default settings; see the individual OggFLAC__seekable_stream_encoder_set_*()
 248  *  functions for each setting's default.
 249  *
 250  * \retval OggFLAC__SeekableStreamEncoder*
 251  *    \c NULL if there was an error allocating memory, else the new instance.
 252  */
 253 OggFLAC_API OggFLAC__SeekableStreamEncoder *OggFLAC__seekable_stream_encoder_new();
 254
 255 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 256  *
 257  * \param encoder  A pointer to an existing encoder.
 258  * \assert
 259  *    \code encoder != NULL \endcode
 260  */
 261 OggFLAC_API void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *encoder);
 262
 263
 264 /***********************************************************************
 265  *
 266  * Public class method prototypes
 267  *
 268  ***********************************************************************/
 269
 270 /** Set the serial number for the FLAC stream.
 271  *
 272  * \default \c NULL, 0
 273  * \param  encoder        An encoder instance to set.
 274  * \param  serial_number  See above.
 275  * \assert
 276  *    \code encoder != NULL \endcode
 277  * \retval FLAC__bool
 278  *    \c false if the encoder is already initialized, else \c true.
 279  */
 280 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_serial_number(OggFLAC__SeekableStreamEncoder *encoder, long serial_number);
 281
 282 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
 283  *
 284  * \default \c false
 285  * \param  encoder  An encoder instance to set.
 286  * \param  value    Flag value (see above).
 287  * \assert
 288  *    \code encoder != NULL \endcode
 289  * \retval FLAC__bool
 290  *    \c false if the encoder is already initialized, else \c true.
 291  */
 292 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 293
 294 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
 295  *
 296  * \default \c true
 297  * \param  encoder  An encoder instance to set.
 298  * \param  value    Flag value (see above).
 299  * \assert
 300  *    \code encoder != NULL \endcode
 301  * \retval FLAC__bool
 302  *    \c false if the encoder is already initialized, else \c true.
 303  */
 304 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 305
 306 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
 307  *
 308  * \default \c false
 309  * \param  encoder  An encoder instance to set.
 310  * \param  value    Flag 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 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 317
 318 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
 319  *
 320  * \default \c false
 321  * \param  encoder  An encoder instance to set.
 322  * \param  value    Flag value (see above).
 323  * \assert
 324  *    \code encoder != NULL \endcode
 325  * \retval FLAC__bool
 326  *    \c false if the encoder is already initialized, else \c true.
 327  */
 328 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 329
 330 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
 331  *
 332  * \default \c 2
 333  * \param  encoder  An encoder instance to set.
 334  * \param  value    See above.
 335  * \assert
 336  *    \code encoder != NULL \endcode
 337  * \retval FLAC__bool
 338  *    \c false if the encoder is already initialized, else \c true.
 339  */
 340 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 341
 342 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
 343  *
 344  * \default \c 16
 345  * \param  encoder  An encoder instance to set.
 346  * \param  value    See above.
 347  * \assert
 348  *    \code encoder != NULL \endcode
 349  * \retval FLAC__bool
 350  *    \c false if the encoder is already initialized, else \c true.
 351  */
 352 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 353
 354 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
 355  *
 356  * \default \c 44100
 357  * \param  encoder  An encoder instance to set.
 358  * \param  value    See above.
 359  * \assert
 360  *    \code encoder != NULL \endcode
 361  * \retval FLAC__bool
 362  *    \c false if the encoder is already initialized, else \c true.
 363  */
 364 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 365
 366 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
 367  *
 368  * \default \c 1152
 369  * \param  encoder  An encoder instance to set.
 370  * \param  value    See above.
 371  * \assert
 372  *    \code encoder != NULL \endcode
 373  * \retval FLAC__bool
 374  *    \c false if the encoder is already initialized, else \c true.
 375  */
 376 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 377
 378 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
 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 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 389
 390 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
 391  *
 392  * \default \c 0
 393  * \param  encoder  An encoder instance to set.
 394  * \param  value    See above.
 395  * \assert
 396  *    \code encoder != NULL \endcode
 397  * \retval FLAC__bool
 398  *    \c false if the encoder is already initialized, else \c true.
 399  */
 400 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 401
 402 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
 403  *
 404  * \default \c false
 405  * \param  encoder  An encoder instance to set.
 406  * \param  value    See above.
 407  * \assert
 408  *    \code encoder != NULL \endcode
 409  * \retval FLAC__bool
 410  *    \c false if the encoder is already initialized, else \c true.
 411  */
 412 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 413
 414 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
 415  *
 416  * \default \c false
 417  * \param  encoder  An encoder instance to set.
 418  * \param  value    See above.
 419  * \assert
 420  *    \code encoder != NULL \endcode
 421  * \retval FLAC__bool
 422  *    \c false if the encoder is already initialized, else \c true.
 423  */
 424 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 425
 426 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
 427  *
 428  * \default \c false
 429  * \param  encoder  An encoder instance to set.
 430  * \param  value    See above.
 431  * \assert
 432  *    \code encoder != NULL \endcode
 433  * \retval FLAC__bool
 434  *    \c false if the encoder is already initialized, else \c true.
 435  */
 436 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 437
 438 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
 439  *
 440  * \default \c 0
 441  * \param  encoder  An encoder instance to set.
 442  * \param  value    See above.
 443  * \assert
 444  *    \code encoder != NULL \endcode
 445  * \retval FLAC__bool
 446  *    \c false if the encoder is already initialized, else \c true.
 447  */
 448 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 449
 450 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
 451  *
 452  * \default \c 0
 453  * \param  encoder  An encoder instance to set.
 454  * \param  value    See above.
 455  * \assert
 456  *    \code encoder != NULL \endcode
 457  * \retval FLAC__bool
 458  *    \c false if the encoder is already initialized, else \c true.
 459  */
 460 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 461
 462 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
 463  *
 464  * \default \c 0
 465  * \param  encoder  An encoder instance to set.
 466  * \param  value    See above.
 467  * \assert
 468  *    \code encoder != NULL \endcode
 469  * \retval FLAC__bool
 470  *    \c false if the encoder is already initialized, else \c true.
 471  */
 472 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
 473
 474 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
 475  *
 476  * \default \c 0
 477  * \param  encoder  An encoder instance to set.
 478  * \param  value    See above.
 479  * \assert
 480  *    \code encoder != NULL \endcode
 481  * \retval FLAC__bool
 482  *    \c false if the encoder is already initialized, else \c true.
 483  */
 484 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_total_samples_estimate(OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
 485
 486 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
 487  *
 488  * \default \c NULL, 0
 489  * \param  encoder     An encoder instance to set.
 490  * \param  metadata    See above.
 491  * \param  num_blocks  See above.
 492  * \assert
 493  *    \code encoder != NULL \endcode
 494  * \retval FLAC__bool
 495  *    \c false if the encoder is already initialized, else \c true.
 496  */
 497 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_metadata(OggFLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 498
 499 /** Set the read callback.
 500  *  The supplied function will be called when the encoder needs to read back
 501  *  encoded data.  This happens during the metadata callback, when the encoder
 502  *  has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
 503  *  while encoding.  The address of the buffer to be filled is supplied, along
 504  *  with the number of bytes the buffer can hold.  The callback may choose to
 505  *  supply less data and modify the byte count but must be careful not to
 506  *  overflow the buffer.  The callback then returns a status code chosen from
 507  *  OggFLAC__SeekableStreamEncoderReadStatus.
 508  *
 509  * \note
 510  * The callback is mandatory and must be set before initialization.
 511  *
 512  * \default \c NULL
 513  * \param  encoder  A encoder instance to set.
 514  * \param  value    See above.
 515  * \assert
 516  *    \code encoder != NULL \endcode
 517  *    \code value != NULL \endcode
 518  * \retval FLAC__bool
 519  *    \c false if the encoder is already initialized, else \c true.
 520  */
 521 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_read_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderReadCallback value);
 522
 523 /** Set the seek callback.
 524  *  The supplied function will be called when the encoder needs to seek
 525  *  the output stream.  The encoder will pass the absolute byte offset
 526  *  to seek to, 0 meaning the beginning of the stream.
 527  *
 528  * \note
 529  * The callback is mandatory and must be set before initialization.
 530  *
 531  * \default \c NULL
 532  * \param  encoder  An encoder instance to set.
 533  * \param  value    See above.
 534  * \assert
 535  *    \code encoder != NULL \endcode
 536  *    \code value != NULL \endcode
 537  * \retval FLAC__bool
 538  *    \c false if the encoder is already initialized, else \c true.
 539  */
 540 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_seek_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderSeekCallback value);
 541
 542 /** Set the tell callback.
 543  *  The supplied function will be called when the encoder needs to know
 544  *  the current position of the output stream.
 545  *
 546  * \note
 547  * The callback is mandatory and must be set before initialization.
 548  *
 549  * \default \c NULL
 550  * \param  encoder  An encoder instance to set.
 551  * \param  value    See above.
 552  * \assert
 553  *    \code encoder != NULL \endcode
 554  *    \code value != NULL \endcode
 555  * \retval FLAC__bool
 556  *    \c false if the encoder is already initialized, else \c true.
 557  */
 558 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_tell_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderTellCallback value);
 559
 560 /** Set the write callback.
 561  *  This is inherited from FLAC__StreamEncoder; see
 562  *  FLAC__stream_encoder_set_write_callback().
 563  *
 564  * \note
 565  * Unlike the FLAC seekable stream encoder write callback, the Ogg
 566  * seekable stream encoder write callback will be called twice when
 567  * writing audio frames; once for the page header, and once for the page
 568  * body.  When writing the page header, the \a samples argument to the
 569  * write callback will be \c 0.
 570  *
 571  * \note
 572  * The callback is mandatory and must be set before initialization.
 573  *
 574  * \default \c NULL
 575  * \param  encoder  An encoder instance to set.
 576  * \param  value    See above.
 577  * \assert
 578  *    \code encoder != NULL \endcode
 579  *    \code value != NULL \endcode
 580  * \retval FLAC__bool
 581  *    \c false if the encoder is already initialized, else \c true.
 582  */
 583 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_write_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderWriteCallback value);
 584
 585 /** Set the client data to be passed back to callbacks.
 586  *  This value will be supplied to callbacks in their \a client_data
 587  *  argument.
 588  *
 589  * \default \c NULL
 590  * \param  encoder  An encoder instance to set.
 591  * \param  value    See above.
 592  * \assert
 593  *    \code encoder != NULL \endcode
 594  * \retval FLAC__bool
 595  *    \c false if the encoder is already initialized, else \c true.
 596  */
 597 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_client_data(OggFLAC__SeekableStreamEncoder *encoder, void *value);
 598
 599 /** Get the current encoder state.
 600  *
 601  * \param  encoder  An encoder instance to query.
 602  * \assert
 603  *    \code encoder != NULL \endcode
 604  * \retval OggFLAC__SeekableStreamEncoderState
 605  *    The current encoder state.
 606  */
 607 OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_state(const OggFLAC__SeekableStreamEncoder *encoder);
 608
 609 /** Get the state of the underlying FLAC stream encoder.
 610  *  Useful when the seekable stream encoder state is
 611  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
 612  *
 613  * \param  encoder  An encoder instance to query.
 614  * \assert
 615  *    \code encoder != NULL \endcode
 616  * \retval FLAC__StreamEncoderState
 617  *    The FLAC stream encoder state.
 618  */
 619 OggFLAC_API FLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
 620
 621 /** Get the state of the underlying FLAC encoder's verify decoder.
 622  *  Useful when the seekable stream encoder state is
 623  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
 624  *  and the FLAC stream encoder state is
 625  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 626  *
 627  * \param  encoder  An encoder instance to query.
 628  * \assert
 629  *    \code encoder != NULL \endcode
 630  * \retval FLAC__StreamDecoderState
 631  *    The FLAC verify decoder state.
 632  */
 633 OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
 634
 635 /** Get the current encoder state as a C string.
 636  *  This version automatically resolves
 637  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
 638  *  by getting the FLAC stream encoder's resolved state.
 639  *
 640  * \param  encoder  A encoder instance to query.
 641  * \assert
 642  *    \code encoder != NULL \endcode
 643  * \retval const char *
 644  *    The encoder state as a C string.  Do not modify the contents.
 645  */
 646 OggFLAC_API const char *OggFLAC__seekable_stream_encoder_get_resolved_state_string(const OggFLAC__SeekableStreamEncoder *encoder);
 647
 648 /** Get relevant values about the nature of a verify decoder error.
 649  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
 650  *  Useful when the seekable stream encoder state is
 651  *  \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
 652  *  and the FLAC stream encoder state is
 653  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 654  *
 655  * \param  encoder  An encoder instance to query.
 656  * \param  absolute_sample  The absolute sample number of the mismatch.
 657  * \param  frame_number  The number of the frame in which the mismatch occurred.
 658  * \param  channel       The channel in which the mismatch occurred.
 659  * \param  sample        The number of the sample (relative to the frame) in
 660  *                       which the mismatch occurred.
 661  * \param  expected      The expected value for the sample in question.
 662  * \param  got           The actual value returned by the decoder.
 663  * \assert
 664  *    \code encoder != NULL \endcode
 665  *    \code absolute_sample != NULL \endcode
 666  *    \code frame_number != NULL \endcode
 667  *    \code channel != NULL \endcode
 668  *    \code sample != NULL \endcode
 669  *    \code expected != NULL \endcode
 670  */
 671 OggFLAC_API void OggFLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 672
 673 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
 674  *
 675  * \param  encoder  An encoder instance to query.
 676  * \assert
 677  *    \code encoder != NULL \endcode
 678  * \retval FLAC__bool
 679  *    See OggFLAC__seekable_stream_encoder_set_verify().
 680  */
 681 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableStreamEncoder *encoder);
 682
 683 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
 684  *
 685  * \param  encoder  An encoder instance to query.
 686  * \assert
 687  *    \code encoder != NULL \endcode
 688  * \retval FLAC__bool
 689  *    See OggFLAC__seekable_stream_encoder_set_streamable_subset().
 690  */
 691 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC__SeekableStreamEncoder *encoder);
 692
 693 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
 694  *
 695  * \param  encoder  An encoder instance to query.
 696  * \assert
 697  *    \code encoder != NULL \endcode
 698  * \retval FLAC__bool
 699  *    See OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo().
 700  */
 701 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
 702
 703 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
 704  *
 705  * \param  encoder  An encoder instance to query.
 706  * \assert
 707  *    \code encoder != NULL \endcode
 708  * \retval FLAC__bool
 709  *    See OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
 710  */
 711 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
 712
 713 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
 714  *
 715  * \param  encoder  An encoder instance to query.
 716  * \assert
 717  *    \code encoder != NULL \endcode
 718  * \retval unsigned
 719  *    See OggFLAC__seekable_stream_encoder_set_channels().
 720  */
 721 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableStreamEncoder *encoder);
 722
 723 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
 724  *
 725  * \param  encoder  An encoder instance to query.
 726  * \assert
 727  *    \code encoder != NULL \endcode
 728  * \retval unsigned
 729  *    See OggFLAC__seekable_stream_encoder_set_bits_per_sample().
 730  */
 731 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__SeekableStreamEncoder *encoder);
 732
 733 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
 734  *
 735  * \param  encoder  An encoder instance to query.
 736  * \assert
 737  *    \code encoder != NULL \endcode
 738  * \retval unsigned
 739  *    See OggFLAC__seekable_stream_encoder_set_sample_rate().
 740  */
 741 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__SeekableStreamEncoder *encoder);
 742
 743 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
 744  *
 745  * \param  encoder  An encoder instance to query.
 746  * \assert
 747  *    \code encoder != NULL \endcode
 748  * \retval unsigned
 749  *    See OggFLAC__seekable_stream_encoder_set_blocksize().
 750  */
 751 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableStreamEncoder *encoder);
 752
 753 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
 754  *
 755  * \param  encoder  An encoder instance to query.
 756  * \assert
 757  *    \code encoder != NULL \endcode
 758  * \retval unsigned
 759  *    See OggFLAC__seekable_stream_encoder_set_max_lpc_order().
 760  */
 761 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__SeekableStreamEncoder *encoder);
 762
 763 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
 764  *
 765  * \param  encoder  An encoder instance to query.
 766  * \assert
 767  *    \code encoder != NULL \endcode
 768  * \retval unsigned
 769  *    See OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision().
 770  */
 771 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC__SeekableStreamEncoder *encoder);
 772
 773 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
 774  *
 775  * \param  encoder  An encoder instance to query.
 776  * \assert
 777  *    \code encoder != NULL \endcode
 778  * \retval FLAC__bool
 779  *    See OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
 780  */
 781 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__SeekableStreamEncoder *encoder);
 782
 783 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
 784  *
 785  * \param  encoder  An encoder instance to query.
 786  * \assert
 787  *    \code encoder != NULL \endcode
 788  * \retval FLAC__bool
 789  *    See OggFLAC__seekable_stream_encoder_set_do_escape_coding().
 790  */
 791 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__SeekableStreamEncoder *encoder);
 792
 793 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
 794  *
 795  * \param  encoder  An encoder instance to query.
 796  * \assert
 797  *    \code encoder != NULL \endcode
 798  * \retval FLAC__bool
 799  *    See OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
 800  */
 801 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const OggFLAC__SeekableStreamEncoder *encoder);
 802
 803 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
 804  *
 805  * \param  encoder  An encoder instance to query.
 806  * \assert
 807  *    \code encoder != NULL \endcode
 808  * \retval unsigned
 809  *    See OggFLAC__seekable_stream_encoder_set_min_residual_partition_order().
 810  */
 811 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
 812
 813 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
 814  *
 815  * \param  encoder  An encoder instance to query.
 816  * \assert
 817  *    \code encoder != NULL \endcode
 818  * \retval unsigned
 819  *    See OggFLAC__seekable_stream_encoder_set_max_residual_partition_order().
 820  */
 821 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
 822
 823 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
 824  *
 825  * \param  encoder  An encoder instance to query.
 826  * \assert
 827  *    \code encoder != NULL \endcode
 828  * \retval unsigned
 829  *    See OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
 830  */
 831 OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const OggFLAC__SeekableStreamEncoder *encoder);
 832
 833 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
 834  *
 835  * \param  encoder  An encoder instance to set.
 836  * \assert
 837  *    \code encoder != NULL \endcode
 838  * \retval FLAC__uint64
 839  *    See OggFLAC__seekable_stream_encoder_get_total_samples_estimate().
 840  */
 841 OggFLAC_API FLAC__uint64 OggFLAC__seekable_stream_encoder_get_total_samples_estimate(const OggFLAC__SeekableStreamEncoder *encoder);
 842
 843 /** Initialize the encoder instance.
 844  *  Should be called after OggFLAC__seekable_stream_encoder_new() and
 845  *  OggFLAC__seekable_stream_encoder_set_*() but before OggFLAC__seekable_stream_encoder_process()
 846  *  or OggFLAC__seekable_stream_encoder_process_interleaved().  Will set and return
 847  *  the encoder state, which will be OggFLAC__SEEKABLE_STREAM_ENCODER_OK if
 848  *  initialization succeeded.
 849  *
 850  *  The call to OggFLAC__seekable_stream_encoder_init() currently will also immediately
 851  *  call the write callback several times, once with the \c fLaC signature,
 852  *  and once for each encoded metadata block.
 853  *
 854  * \param  encoder  An uninitialized encoder instance.
 855  * \assert
 856  *    \code encoder != NULL \endcode
 857  * \retval OggFLAC__SeekableStreamEncoderState
 858  *    \c OggFLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
 859  *    OggFLAC__SeekableStreamEncoderState for the meanings of other return values.
 860  */
 861 OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLAC__SeekableStreamEncoder *encoder);
 862
 863 /** Finish the encoding process.
 864  *  Flushes the encoding buffer, releases resources, resets the encoder
 865  *  settings to their defaults, and returns the encoder state to
 866  *  OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
 867  *  one or more write callbacks before returning.
 868  *
 869  *  In the event of a prematurely-terminated encode, it is not strictly
 870  *  necessary to call this immediately before OggFLAC__seekable_stream_encoder_delete()
 871  *  but it is good practice to match every OggFLAC__seekable_stream_encoder_init()
 872  *  with an OggFLAC__seekable_stream_encoder_finish().
 873  *
 874  * \param  encoder  An uninitialized encoder instance.
 875  * \assert
 876  *    \code encoder != NULL \endcode
 877  */
 878 OggFLAC_API void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *encoder);
 879
 880 /** Submit data for encoding.
 881  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
 882  *
 883  * \param  encoder  An initialized encoder instance in the OK state.
 884  * \param  buffer   An array of pointers to each channel's signal.
 885  * \param  samples  The number of samples in one channel.
 886  * \assert
 887  *    \code encoder != NULL \endcode
 888  *    \code OggFLAC__seekable_stream_encoder_get_state(encoder) == OggFLAC__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 OggFLAC__seekable_stream_encoder_get_state() to see what
 892  *    went wrong.
 893  */
 894 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_process(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 895
 896 /** Submit data for encoding.
 897  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
 898  *
 899  * \param  encoder  An initialized encoder instance in the OK state.
 900  * \param  buffer   An array of channel-interleaved data (see above).
 901  * \param  samples  The number of samples in one channel, the same as for
 902  *                  OggFLAC__seekable_stream_encoder_process().  For example, if
 903  *                  encoding two channels, \c 1000 \a samples corresponds
 904  *                  to a \a buffer of 2000 values.
 905  * \assert
 906  *    \code encoder != NULL \endcode
 907  *    \code OggFLAC__seekable_stream_encoder_get_state(encoder) == OggFLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
 908  * \retval FLAC__bool
 909  *    \c true if successful, else \c false; in this case, check the
 910  *    encoder state with OggFLAC__seekable_stream_encoder_get_state() to see what
 911  *    went wrong.
 912  */
 913 OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_process_interleaved(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 914
 915 /* \} */
 916
 917 #ifdef __cplusplus
 918 }
 919 #endif
 920
 921 #endif