include/OggFLAC/stream_encoder.h

   1 /* libOggFLAC - Free Lossless Audio Codec + Ogg 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 OggFLAC__STREAM_ENCODER_H
  21 #define OggFLAC__STREAM_ENCODER_H
  22
  23 #include "FLAC/stream_encoder.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /** \file include/OggFLAC/stream_encoder.h
  31  *
  32  *  \brief
  33  *  This module contains the functions which implement the stream
  34  *  encoder.
  35  *
  36  *  See the detailed documentation in the
  37  *  \link oggflac_stream_encoder stream encoder \endlink module.
  38  */
  39
  40 /** \defgroup oggflac_encoder OggFLAC/ *_encoder.h: encoder interfaces
  41  *  \ingroup oggflac
  42  *
  43  *  \brief
  44  *  This module describes the encoder layers provided by libOggFLAC.
  45  *
  46  * libOggFLAC currently provides the same stream layer access as libFLAC;
  47  * the interface is nearly identical.  See the \link flac_encoder FLAC
  48  * encoder module \endlink for full documentation.
  49  */
  50
  51 /** \defgroup oggflac_stream_encoder OggFLAC/stream_encoder.h: stream encoder interface
  52  *  \ingroup oggflac_encoder
  53  *
  54  *  \brief
  55  *  This module contains the functions which implement the stream
  56  *  encoder.
  57  *
  58  * The interface here is nearly identical to FLAC's stream encoder,
  59  * including the callbacks.  See the \link flac_stream_encoder
  60  * FLAC stream encoder module \endlink for full documentation.
  61  *
  62  * \{
  63  */
  64
  65
  66 /** State values for an OggFLAC__StreamEncoder
  67  *
  68  *  The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
  69  */
  70 typedef enum {
  71
  72         OggFLAC__STREAM_ENCODER_OK = 0,
  73         /**< The encoder is in the normal OK state. */
  74
  75         OggFLAC__STREAM_ENCODER_OGG_ERROR,
  76         /**< An error occurred in the underlying Ogg layer.  */
  77
  78         OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
  79         /**< An error occurred in the underlying FLAC stream encoder;
  80          * check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
  81          */
  82
  83         OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
  84         /**< The encoder was initialized before setting all the required callbacks. */
  85
  86         OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
  87         /**< Memory allocation failed. */
  88
  89         OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
  90         /**< OggFLAC__stream_encoder_init() was called when the encoder was
  91          * already initialized, usually because
  92          * OggFLAC__stream_encoder_finish() was not called.
  93          */
  94
  95         OggFLAC__STREAM_ENCODER_UNINITIALIZED
  96         /**< The encoder is in the uninitialized state. */
  97
  98 } OggFLAC__StreamEncoderState;
  99
 100 /** Maps an OggFLAC__StreamEncoderState to a C string.
 101  *
 102  *  Using an OggFLAC__StreamEncoderState as the index to this array
 103  *  will give the string equivalent.  The contents should not be modified.
 104  */
 105 extern const char * const OggFLAC__StreamEncoderStateString[];
 106
 107
 108 /***********************************************************************
 109  *
 110  * class OggFLAC__StreamEncoder
 111  *
 112  ***********************************************************************/
 113
 114 struct OggFLAC__StreamEncoderProtected;
 115 struct OggFLAC__StreamEncoderPrivate;
 116 /** The opaque structure definition for the stream encoder type.
 117  *  See the \link oggflac_stream_encoder stream encoder module \endlink
 118  *  for a detailed description.
 119  */
 120 typedef struct {
 121         struct OggFLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 122         struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 123 } OggFLAC__StreamEncoder;
 124
 125 /** Signature for the write callback.
 126  *  See OggFLAC__stream_encoder_set_write_callback()
 127  *  and FLAC__StreamEncoderWriteCallback for more info.
 128  *
 129  * \param  encoder  The encoder instance calling the callback.
 130  * \param  buffer   An array of encoded data of length \a bytes.
 131  * \param  bytes    The byte length of \a buffer.
 132  * \param  samples  The number of samples encoded by \a buffer.
 133  *                  \c 0 has a special meaning; see
 134  *                  OggFLAC__stream_encoder_set_write_callback().
 135  * \param  current_frame  The number of current frame being encoded.
 136  * \param  client_data  The callee's client data set through
 137  *                      OggFLAC__stream_encoder_set_client_data().
 138  * \retval FLAC__StreamEncoderWriteStatus
 139  *    The callee's return status.
 140  */
 141 typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
 142
 143
 144 /***********************************************************************
 145  *
 146  * Class constructor/destructor
 147  *
 148  ***********************************************************************/
 149
 150 /** Create a new stream encoder instance.  The instance is created with
 151  *  default settings; see the individual OggFLAC__stream_encoder_set_*()
 152  *  functions for each setting's default.
 153  *
 154  * \retval OggFLAC__StreamEncoder*
 155  *    \c NULL if there was an error allocating memory, else the new instance.
 156  */
 157 OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new();
 158
 159 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 160  *
 161  * \param encoder  A pointer to an existing encoder.
 162  * \assert
 163  *    \code encoder != NULL \endcode
 164  */
 165 void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder);
 166
 167
 168 /***********************************************************************
 169  *
 170  * Public class method prototypes
 171  *
 172  ***********************************************************************/
 173
 174 /** Set the serial number for the FLAC stream.
 175  *
 176  * \default \c NULL, 0
 177  * \param  encoder        An encoder instance to set.
 178  * \param  serial_number  See above.
 179  * \assert
 180  *    \code encoder != NULL \endcode
 181  * \retval FLAC__bool
 182  *    \c false if the encoder is already initialized, else \c true.
 183  */
 184 FLAC__bool OggFLAC__stream_encoder_set_serial_number(OggFLAC__StreamEncoder *encoder, long serial_number);
 185
 186 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
 187  *
 188  * \default \c false
 189  * \param  encoder  An encoder instance to set.
 190  * \param  value    Flag value (see above).
 191  * \assert
 192  *    \code encoder != NULL \endcode
 193  * \retval FLAC__bool
 194  *    \c false if the encoder is already initialized, else \c true.
 195  */
 196 FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 197
 198 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
 199  *
 200  * \default \c true
 201  * \param  encoder  An encoder instance to set.
 202  * \param  value    Flag value (see above).
 203  * \assert
 204  *    \code encoder != NULL \endcode
 205  * \retval FLAC__bool
 206  *    \c false if the encoder is already initialized, else \c true.
 207  */
 208 FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 209
 210 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
 211  *
 212  * \default \c false
 213  * \param  encoder  An encoder instance to set.
 214  * \param  value    Flag value (see above).
 215  * \assert
 216  *    \code encoder != NULL \endcode
 217  * \retval FLAC__bool
 218  *    \c false if the encoder is already initialized, else \c true.
 219  */
 220 FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 221
 222 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
 223  *
 224  * \default \c false
 225  * \param  encoder  An encoder instance to set.
 226  * \param  value    Flag value (see above).
 227  * \assert
 228  *    \code encoder != NULL \endcode
 229  * \retval FLAC__bool
 230  *    \c false if the encoder is already initialized, else \c true.
 231  */
 232 FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 233
 234 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
 235  *
 236  * \default \c 2
 237  * \param  encoder  An encoder instance to set.
 238  * \param  value    See above.
 239  * \assert
 240  *    \code encoder != NULL \endcode
 241  * \retval FLAC__bool
 242  *    \c false if the encoder is already initialized, else \c true.
 243  */
 244 FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value);
 245
 246 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
 247  *
 248  * \default \c 16
 249  * \param  encoder  An encoder instance to set.
 250  * \param  value    See above.
 251  * \assert
 252  *    \code encoder != NULL \endcode
 253  * \retval FLAC__bool
 254  *    \c false if the encoder is already initialized, else \c true.
 255  */
 256 FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value);
 257
 258 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
 259  *
 260  * \default \c 44100
 261  * \param  encoder  An encoder instance to set.
 262  * \param  value    See above.
 263  * \assert
 264  *    \code encoder != NULL \endcode
 265  * \retval FLAC__bool
 266  *    \c false if the encoder is already initialized, else \c true.
 267  */
 268 FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value);
 269
 270 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
 271  *
 272  * \default \c 1152
 273  * \param  encoder  An encoder instance to set.
 274  * \param  value    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 FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value);
 281
 282 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
 283  *
 284  * \default \c 0
 285  * \param  encoder  An encoder instance to set.
 286  * \param  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 FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 293
 294 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
 295  *
 296  * \default \c 0
 297  * \param  encoder  An encoder instance to set.
 298  * \param  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 FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
 305
 306 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
 307  *
 308  * \default \c false
 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__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 317
 318 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
 319  *
 320  * \default \c false
 321  * \param  encoder  An encoder instance to set.
 322  * \param  value    See above.
 323  * \assert
 324  *    \code encoder != NULL \endcode
 325  * \retval FLAC__bool
 326  *    \c false if the encoder is already initialized, else \c true.
 327  */
 328 FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 329
 330 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
 331  *
 332  * \default \c false
 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 FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
 341
 342 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
 343  *
 344  * \default \c 0
 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 FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 353
 354 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
 355  *
 356  * \default \c 0
 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 FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
 365
 366 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
 367  *
 368  * \default \c 0
 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 FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
 377
 378 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
 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 OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
 389
 390 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
 391  *
 392  * \default \c NULL, 0
 393  * \param  encoder     An encoder instance to set.
 394  * \param  metadata    See above.
 395  * \param  num_blocks  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 OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 402
 403 /** Set the write callback.
 404  *  This is inherited from FLAC__StreamEncoder; see
 405  *  FLAC__stream_encoder_set_write_callback().
 406  *
 407  * \note
 408  * Unlike the FLAC stream encoder write callback, the Ogg stream
 409  * encoder write callback will be called twice when writing audio
 410  * frames; once for the page header, and once for the page body.
 411  * When writing the page header, the \a samples argument to the
 412  * write callback will be \c 0.
 413  *
 414  * \note
 415  * The callback is mandatory and must be set before initialization.
 416  *
 417  * \default \c NULL
 418  * \param  encoder  An encoder instance to set.
 419  * \param  value    See above.
 420  * \assert
 421  *    \code encoder != NULL \endcode
 422  *    \code value != NULL \endcode
 423  * \retval FLAC__bool
 424  *    \c false if the encoder is already initialized, else \c true.
 425  */
 426 FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
 427
 428 /** Set the client data to be passed back to callbacks.
 429  *  This value will be supplied to callbacks in their \a client_data
 430  *  argument.
 431  *
 432  * \default \c NULL
 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 OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
 441
 442 /** Get the current encoder state.
 443  *
 444  * \param  encoder  An encoder instance to query.
 445  * \assert
 446  *    \code encoder != NULL \endcode
 447  * \retval OggFLAC__StreamEncoderState
 448  *    The current encoder state.
 449  */
 450 OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
 451
 452 /** Get the state of the underlying FLAC stream encoder.
 453  *  Useful when the stream encoder state is
 454  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
 455  *
 456  * \param  encoder  An encoder instance to query.
 457  * \assert
 458  *    \code encoder != NULL \endcode
 459  * \retval FLAC__StreamEncoderState
 460  *    The FLAC stream encoder state.
 461  */
 462 FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
 463
 464 /** Get the state of the underlying FLAC stream encoder's verify decoder.
 465  *  Useful when the stream encoder state is
 466  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 467  *  FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 468  *
 469  * \param  encoder  An encoder instance to query.
 470  * \assert
 471  *    \code encoder != NULL \endcode
 472  * \retval FLAC__StreamDecoderState
 473  *    The FLAC verify decoder state.
 474  */
 475 FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
 476
 477 /** Get relevant values about the nature of a verify decoder error.
 478  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
 479  *  Useful when the stream encoder state is
 480  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
 481  *  FLAC stream encoder state is
 482  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
 483  *
 484  * \param  encoder  An encoder instance to query.
 485  * \param  absolute_sample  The absolute sample number of the mismatch.
 486  * \param  frame_number  The number of the frame in which the mismatch occurred.
 487  * \param  channel       The channel in which the mismatch occurred.
 488  * \param  sample        The number of the sample (relative to the frame) in
 489  *                       which the mismatch occurred.
 490  * \param  expected      The expected value for the sample in question.
 491  * \param  got           The actual value returned by the decoder.
 492  * \assert
 493  *    \code encoder != NULL \endcode
 494  *    \code absolute_sample != NULL \endcode
 495  *    \code frame_number != NULL \endcode
 496  *    \code channel != NULL \endcode
 497  *    \code sample != NULL \endcode
 498  *    \code expected != NULL \endcode
 499  */
 500 void OggFLAC__stream_encoder_get_verify_decoder_error_stats(const OggFLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
 501
 502 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
 503  *
 504  * \param  encoder  An encoder instance to query.
 505  * \assert
 506  *    \code encoder != NULL \endcode
 507  * \retval FLAC__bool
 508  *    See OggFLAC__stream_encoder_set_verify().
 509  */
 510 FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
 511
 512 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
 513  *
 514  * \param  encoder  An encoder instance to query.
 515  * \assert
 516  *    \code encoder != NULL \endcode
 517  * \retval FLAC__bool
 518  *    See OggFLAC__stream_encoder_set_streamable_subset().
 519  */
 520 FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
 521
 522 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
 523  *
 524  * \param  encoder  An encoder instance to query.
 525  * \assert
 526  *    \code encoder != NULL \endcode
 527  * \retval FLAC__bool
 528  *    See OggFLAC__stream_encoder_get_do_mid_side_stereo().
 529  */
 530 FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 531
 532 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
 533  *
 534  * \param  encoder  An encoder instance to query.
 535  * \assert
 536  *    \code encoder != NULL \endcode
 537  * \retval FLAC__bool
 538  *    See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
 539  */
 540 FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
 541
 542 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
 543  *
 544  * \param  encoder  An encoder instance to query.
 545  * \assert
 546  *    \code encoder != NULL \endcode
 547  * \retval unsigned
 548  *    See OggFLAC__stream_encoder_set_channels().
 549  */
 550 unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
 551
 552 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
 553  *
 554  * \param  encoder  An encoder instance to query.
 555  * \assert
 556  *    \code encoder != NULL \endcode
 557  * \retval unsigned
 558  *    See OggFLAC__stream_encoder_set_bits_per_sample().
 559  */
 560 unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
 561
 562 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
 563  *
 564  * \param  encoder  An encoder instance to query.
 565  * \assert
 566  *    \code encoder != NULL \endcode
 567  * \retval unsigned
 568  *    See OggFLAC__stream_encoder_set_sample_rate().
 569  */
 570 unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
 571
 572 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
 573  *
 574  * \param  encoder  An encoder instance to query.
 575  * \assert
 576  *    \code encoder != NULL \endcode
 577  * \retval unsigned
 578  *    See OggFLAC__stream_encoder_set_blocksize().
 579  */
 580 unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
 581
 582 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
 583  *
 584  * \param  encoder  An encoder instance to query.
 585  * \assert
 586  *    \code encoder != NULL \endcode
 587  * \retval unsigned
 588  *    See OggFLAC__stream_encoder_set_max_lpc_order().
 589  */
 590 unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
 591
 592 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
 593  *
 594  * \param  encoder  An encoder instance to query.
 595  * \assert
 596  *    \code encoder != NULL \endcode
 597  * \retval unsigned
 598  *    See OggFLAC__stream_encoder_set_qlp_coeff_precision().
 599  */
 600 unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
 601
 602 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
 603  *
 604  * \param  encoder  An encoder instance to query.
 605  * \assert
 606  *    \code encoder != NULL \endcode
 607  * \retval FLAC__bool
 608  *    See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
 609  */
 610 FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
 611
 612 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
 613  *
 614  * \param  encoder  An encoder instance to query.
 615  * \assert
 616  *    \code encoder != NULL \endcode
 617  * \retval FLAC__bool
 618  *    See OggFLAC__stream_encoder_set_do_escape_coding().
 619  */
 620 FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
 621
 622 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
 623  *
 624  * \param  encoder  An encoder instance to query.
 625  * \assert
 626  *    \code encoder != NULL \endcode
 627  * \retval FLAC__bool
 628  *    See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
 629  */
 630 FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
 631
 632 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
 633  *
 634  * \param  encoder  An encoder instance to query.
 635  * \assert
 636  *    \code encoder != NULL \endcode
 637  * \retval unsigned
 638  *    See OggFLAC__stream_encoder_set_min_residual_partition_order().
 639  */
 640 unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 641
 642 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
 643  *
 644  * \param  encoder  An encoder instance to query.
 645  * \assert
 646  *    \code encoder != NULL \endcode
 647  * \retval unsigned
 648  *    See OggFLAC__stream_encoder_set_max_residual_partition_order().
 649  */
 650 unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
 651
 652 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
 653  *
 654  * \param  encoder  An encoder instance to query.
 655  * \assert
 656  *    \code encoder != NULL \endcode
 657  * \retval unsigned
 658  *    See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
 659  */
 660 unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
 661
 662 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
 663  *
 664  * \param  encoder  An encoder instance to set.
 665  * \assert
 666  *    \code encoder != NULL \endcode
 667  * \retval FLAC__uint64
 668  *    See OggFLAC__stream_encoder_get_total_samples_estimate().
 669  */
 670 FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
 671
 672 /** Initialize the encoder instance.
 673  *  Should be called after OggFLAC__stream_encoder_new() and
 674  *  OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
 675  *  or OggFLAC__stream_encoder_process_interleaved().  Will set and return
 676  *  the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
 677  *  initialization succeeded.
 678  *
 679  *  The call to OggFLAC__stream_encoder_init() currently will also immediately
 680  *  call the write callback several times, once with the \c fLaC signature,
 681  *  and once for each encoded metadata block.
 682  *
 683  * \param  encoder  An uninitialized encoder instance.
 684  * \assert
 685  *    \code encoder != NULL \endcode
 686  * \retval OggFLAC__StreamEncoderState
 687  *    \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
 688  *    OggFLAC__StreamEncoderState for the meanings of other return values.
 689  */
 690 OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
 691
 692 /** Finish the encoding process.
 693  *  Flushes the encoding buffer, releases resources, resets the encoder
 694  *  settings to their defaults, and returns the encoder state to
 695  *  OggFLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
 696  *  one or more write callbacks before returning.
 697  *
 698  *  In the event of a prematurely-terminated encode, it is not strictly
 699  *  necessary to call this immediately before OggFLAC__stream_encoder_delete()
 700  *  but it is good practice to match every OggFLAC__stream_encoder_init()
 701  *  with an OggFLAC__stream_encoder_finish().
 702  *
 703  * \param  encoder  An uninitialized encoder instance.
 704  * \assert
 705  *    \code encoder != NULL \endcode
 706  */
 707 void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
 708
 709 /** Submit data for encoding.
 710  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
 711  *
 712  * \param  encoder  An initialized encoder instance in the OK state.
 713  * \param  buffer   An array of pointers to each channel's signal.
 714  * \param  samples  The number of samples in one channel.
 715  * \assert
 716  *    \code encoder != NULL \endcode
 717  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 718  * \retval FLAC__bool
 719  *    \c true if successful, else \c false; in this case, check the
 720  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 721  *    went wrong.
 722  */
 723 FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 724
 725 /** Submit data for encoding.
 726  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
 727  *
 728  * \param  encoder  An initialized encoder instance in the OK state.
 729  * \param  buffer   An array of channel-interleaved data (see above).
 730  * \param  samples  The number of samples in one channel, the same as for
 731  *                  OggFLAC__stream_encoder_process().  For example, if
 732  *                  encoding two channels, \c 1000 \a samples corresponds
 733  *                  to a \a buffer of 2000 values.
 734  * \assert
 735  *    \code encoder != NULL \endcode
 736  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
 737  * \retval FLAC__bool
 738  *    \c true if successful, else \c false; in this case, check the
 739  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
 740  *    went wrong.
 741  */
 742 FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 743
 744 /* \} */
 745
 746 #ifdef __cplusplus
 747 }
 748 #endif
 749
 750 #endif