1
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
2
* Copyright (C) 2002,2003,2004,2005 Josh Coalson
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions
8
* - Redistributions of source code must retain the above copyright
9
* notice, this list of conditions and the following disclaimer.
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.
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.
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.
32
#ifndef OggFLAC__STREAM_ENCODER_H
33
#define OggFLAC__STREAM_ENCODER_H
37
#include "FLAC/stream_encoder.h"
44
/** \file include/OggFLAC/stream_encoder.h
47
* This module contains the functions which implement the stream
50
* See the detailed documentation in the
51
* \link oggflac_stream_encoder stream encoder \endlink module.
54
/** \defgroup oggflac_encoder OggFLAC/ *_encoder.h: encoder interfaces
58
* This module describes the three encoder layers provided by libOggFLAC.
60
* libOggFLAC currently provides the same three layers of access as libFLAC;
61
* the interfaces are nearly identical, with the addition of a method for
62
* specifying the Ogg serial number. See the \link flac_encoder FLAC
63
* encoder module \endlink for full documentation.
66
/** \defgroup oggflac_stream_encoder OggFLAC/stream_encoder.h: stream encoder interface
67
* \ingroup oggflac_encoder
70
* This module contains the functions which implement the stream
71
* encoder. The Ogg stream encoder is derived
72
* from the FLAC stream encoder.
74
* The interface here is nearly identical to FLAC's stream encoder,
75
* including the callbacks, with the addition of
76
* OggFLAC__stream_encoder_set_serial_number(). See the
77
* \link flac_stream_encoder FLAC stream encoder module \endlink
78
* for full documentation.
84
/** State values for an OggFLAC__StreamEncoder
86
* The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
90
OggFLAC__STREAM_ENCODER_OK = 0,
91
/**< The encoder is in the normal OK state. */
93
OggFLAC__STREAM_ENCODER_OGG_ERROR,
94
/**< An error occurred in the underlying Ogg layer. */
96
OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
97
/**< An error occurred in the underlying FLAC stream encoder;
98
* check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
101
OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
102
/**< The encoder was initialized before setting all the required callbacks. */
104
OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
105
/**< Memory allocation failed. */
107
OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
108
/**< OggFLAC__stream_encoder_init() was called when the encoder was
109
* already initialized, usually because
110
* OggFLAC__stream_encoder_finish() was not called.
113
OggFLAC__STREAM_ENCODER_UNINITIALIZED
114
/**< The encoder is in the uninitialized state. */
116
} OggFLAC__StreamEncoderState;
118
/** Maps an OggFLAC__StreamEncoderState to a C string.
120
* Using an OggFLAC__StreamEncoderState as the index to this array
121
* will give the string equivalent. The contents should not be modified.
123
extern OggFLAC_API const char * const OggFLAC__StreamEncoderStateString[];
126
/***********************************************************************
128
* class OggFLAC__StreamEncoder
130
***********************************************************************/
132
struct OggFLAC__StreamEncoderProtected;
133
struct OggFLAC__StreamEncoderPrivate;
134
/** The opaque structure definition for the stream encoder type.
135
* See the \link oggflac_stream_encoder stream encoder module \endlink
136
* for a detailed description.
139
struct OggFLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
140
struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
141
} OggFLAC__StreamEncoder;
143
/** Signature for the write callback.
144
* See OggFLAC__stream_encoder_set_write_callback()
145
* and FLAC__StreamEncoderWriteCallback for more info.
147
* \param encoder The encoder instance calling the callback.
148
* \param buffer An array of encoded data of length \a bytes.
149
* \param bytes The byte length of \a buffer.
150
* \param samples The number of samples encoded by \a buffer.
151
* \c 0 has a special meaning; see
152
* OggFLAC__stream_encoder_set_write_callback().
153
* \param current_frame The number of current frame being encoded.
154
* \param client_data The callee's client data set through
155
* OggFLAC__stream_encoder_set_client_data().
156
* \retval FLAC__StreamEncoderWriteStatus
157
* The callee's return status.
159
typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
161
/** Signature for the metadata callback.
162
* See OggFLAC__stream_encoder_set_metadata_callback()
163
* and FLAC__stream_encoder_set_metadata_callback() for more info.
165
* \param encoder The encoder instance calling the callback.
166
* \param metadata The final populated STREAMINFO block.
167
* \param client_data The callee's client data set through
168
* FLAC__stream_encoder_set_client_data().
170
typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
173
/***********************************************************************
175
* Class constructor/destructor
177
***********************************************************************/
179
/** Create a new stream encoder instance. The instance is created with
180
* default settings; see the individual OggFLAC__stream_encoder_set_*()
181
* functions for each setting's default.
183
* \retval OggFLAC__StreamEncoder*
184
* \c NULL if there was an error allocating memory, else the new instance.
186
OggFLAC_API OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new();
188
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
190
* \param encoder A pointer to an existing encoder.
192
* \code encoder != NULL \endcode
194
OggFLAC_API void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder);
197
/***********************************************************************
199
* Public class method prototypes
201
***********************************************************************/
203
/** Set the serial number for the FLAC stream.
206
* It is recommended to set a serial number explicitly as the default of '0'
207
* may collide with other streams.
210
* \param encoder An encoder instance to set.
211
* \param serial_number See above.
213
* \code encoder != NULL \endcode
215
* \c false if the encoder is already initialized, else \c true.
217
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_serial_number(OggFLAC__StreamEncoder *encoder, long serial_number);
219
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
222
* \param encoder An encoder instance to set.
223
* \param value Flag value (see above).
225
* \code encoder != NULL \endcode
227
* \c false if the encoder is already initialized, else \c true.
229
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
231
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
234
* \param encoder An encoder instance to set.
235
* \param value Flag value (see above).
237
* \code encoder != NULL \endcode
239
* \c false if the encoder is already initialized, else \c true.
241
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
243
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
246
* \param encoder An encoder instance to set.
247
* \param value Flag value (see above).
249
* \code encoder != NULL \endcode
251
* \c false if the encoder is already initialized, else \c true.
253
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
255
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
258
* \param encoder An encoder instance to set.
259
* \param value Flag value (see above).
261
* \code encoder != NULL \endcode
263
* \c false if the encoder is already initialized, else \c true.
265
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
267
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
270
* \param encoder An encoder instance to set.
271
* \param value See above.
273
* \code encoder != NULL \endcode
275
* \c false if the encoder is already initialized, else \c true.
277
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value);
279
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
282
* \param encoder An encoder instance to set.
283
* \param value See above.
285
* \code encoder != NULL \endcode
287
* \c false if the encoder is already initialized, else \c true.
289
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value);
291
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
294
* \param encoder An encoder instance to set.
295
* \param value See above.
297
* \code encoder != NULL \endcode
299
* \c false if the encoder is already initialized, else \c true.
301
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value);
303
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
306
* \param encoder An encoder instance to set.
307
* \param value See above.
309
* \code encoder != NULL \endcode
311
* \c false if the encoder is already initialized, else \c true.
313
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value);
315
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
318
* \param encoder An encoder instance to set.
319
* \param value See above.
321
* \code encoder != NULL \endcode
323
* \c false if the encoder is already initialized, else \c true.
325
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
327
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
330
* \param encoder An encoder instance to set.
331
* \param value See above.
333
* \code encoder != NULL \endcode
335
* \c false if the encoder is already initialized, else \c true.
337
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
339
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
342
* \param encoder An encoder instance to set.
343
* \param value See above.
345
* \code encoder != NULL \endcode
347
* \c false if the encoder is already initialized, else \c true.
349
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
351
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
354
* \param encoder An encoder instance to set.
355
* \param value See above.
357
* \code encoder != NULL \endcode
359
* \c false if the encoder is already initialized, else \c true.
361
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
363
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
366
* \param encoder An encoder instance to set.
367
* \param value See above.
369
* \code encoder != NULL \endcode
371
* \c false if the encoder is already initialized, else \c true.
373
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
375
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
378
* \param encoder An encoder instance to set.
379
* \param value See above.
381
* \code encoder != NULL \endcode
383
* \c false if the encoder is already initialized, else \c true.
385
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
387
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
390
* \param encoder An encoder instance to set.
391
* \param value See above.
393
* \code encoder != NULL \endcode
395
* \c false if the encoder is already initialized, else \c true.
397
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
399
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
402
* \param encoder An encoder instance to set.
403
* \param value See above.
405
* \code encoder != NULL \endcode
407
* \c false if the encoder is already initialized, else \c true.
409
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
411
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
414
* \param encoder An encoder instance to set.
415
* \param value See above.
417
* \code encoder != NULL \endcode
419
* \c false if the encoder is already initialized, else \c true.
421
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
423
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
425
* \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
426
* the second metadata block of the stream. The encoder already supplies
427
* the STREAMINFO block automatically. If \a metadata does not contain a
428
* VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
429
* \a metadata does contain a VORBIS_COMMENT block and it is not the
430
* first, this function will reorder \a metadata by moving the
431
* VORBIS_COMMENT block to the front; the relative ordering of the other
432
* blocks will remain as they were.
434
* \note The Ogg FLAC mapping limits the number of metadata blocks per
435
* stream to \c 65535. If \a num_blocks exceeds this the function will
438
* \default \c NULL, 0
439
* \param encoder An encoder instance to set.
440
* \param metadata See above.
441
* \param num_blocks See above.
443
* \code encoder != NULL \endcode
445
* \c false if the encoder is already initialized, or if
446
* \a num_blocks > 65535, else \c true.
448
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
450
/** Set the write callback.
451
* This is inherited from FLAC__StreamEncoder; see
452
* FLAC__stream_encoder_set_write_callback().
455
* Unlike the FLAC stream encoder write callback, the Ogg stream
456
* encoder write callback will be called twice when writing audio
457
* frames; once for the page header, and once for the page body.
458
* When writing the page header, the \a samples argument to the
459
* write callback will be \c 0.
462
* The callback is mandatory and must be set before initialization.
465
* \param encoder An encoder instance to set.
466
* \param value See above.
468
* \code encoder != NULL \endcode
469
* \code value != NULL \endcode
471
* \c false if the encoder is already initialized, else \c true.
473
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
475
/** Set the metadata callback.
476
* This is inherited from FLAC__StreamEncoder; see
477
* FLAC__stream_encoder_set_metadata_callback().
480
* The callback is mandatory and must be set before initialization.
483
* \param encoder An encoder instance to set.
484
* \param value See above.
486
* \code encoder != NULL \endcode
487
* \code value != NULL \endcode
489
* \c false if the encoder is already initialized, else \c true.
491
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
493
/** Set the client data to be passed back to callbacks.
494
* This value will be supplied to callbacks in their \a client_data
498
* \param encoder An encoder instance to set.
499
* \param value See above.
501
* \code encoder != NULL \endcode
503
* \c false if the encoder is already initialized, else \c true.
505
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
507
/** Get the current encoder state.
509
* \param encoder An encoder instance to query.
511
* \code encoder != NULL \endcode
512
* \retval OggFLAC__StreamEncoderState
513
* The current encoder state.
515
OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
517
/** Get the state of the underlying FLAC stream encoder.
518
* Useful when the stream encoder state is
519
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
521
* \param encoder An encoder instance to query.
523
* \code encoder != NULL \endcode
524
* \retval FLAC__StreamEncoderState
525
* The FLAC stream encoder state.
527
OggFLAC_API FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
529
/** Get the state of the underlying FLAC stream encoder's verify decoder.
530
* Useful when the stream encoder state is
531
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
532
* FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
534
* \param encoder An encoder instance to query.
536
* \code encoder != NULL \endcode
537
* \retval FLAC__StreamDecoderState
538
* The FLAC verify decoder state.
540
OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
542
/** Get the current encoder state as a C string.
543
* This version automatically resolves
544
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR by getting the
545
* FLAC stream encoder's state.
547
* \param encoder A encoder instance to query.
549
* \code encoder != NULL \endcode
550
* \retval const char *
551
* The encoder state as a C string. Do not modify the contents.
553
OggFLAC_API const char *OggFLAC__stream_encoder_get_resolved_state_string(const OggFLAC__StreamEncoder *encoder);
555
/** Get relevant values about the nature of a verify decoder error.
556
* Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
557
* Useful when the stream encoder state is
558
* \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
559
* FLAC stream encoder state is
560
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
562
* \param encoder An encoder instance to query.
563
* \param absolute_sample The absolute sample number of the mismatch.
564
* \param frame_number The number of the frame in which the mismatch occurred.
565
* \param channel The channel in which the mismatch occurred.
566
* \param sample The number of the sample (relative to the frame) in
567
* which the mismatch occurred.
568
* \param expected The expected value for the sample in question.
569
* \param got The actual value returned by the decoder.
571
* \code encoder != NULL \endcode
572
* \code absolute_sample != NULL \endcode
573
* \code frame_number != NULL \endcode
574
* \code channel != NULL \endcode
575
* \code sample != NULL \endcode
576
* \code expected != NULL \endcode
578
OggFLAC_API 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);
580
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
582
* \param encoder An encoder instance to query.
584
* \code encoder != NULL \endcode
586
* See OggFLAC__stream_encoder_set_verify().
588
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
590
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
592
* \param encoder An encoder instance to query.
594
* \code encoder != NULL \endcode
596
* See OggFLAC__stream_encoder_set_streamable_subset().
598
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
600
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
602
* \param encoder An encoder instance to query.
604
* \code encoder != NULL \endcode
606
* See OggFLAC__stream_encoder_get_do_mid_side_stereo().
608
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
610
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
612
* \param encoder An encoder instance to query.
614
* \code encoder != NULL \endcode
616
* See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
618
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
620
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
622
* \param encoder An encoder instance to query.
624
* \code encoder != NULL \endcode
626
* See OggFLAC__stream_encoder_set_channels().
628
OggFLAC_API unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
630
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
632
* \param encoder An encoder instance to query.
634
* \code encoder != NULL \endcode
636
* See OggFLAC__stream_encoder_set_bits_per_sample().
638
OggFLAC_API unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
640
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
642
* \param encoder An encoder instance to query.
644
* \code encoder != NULL \endcode
646
* See OggFLAC__stream_encoder_set_sample_rate().
648
OggFLAC_API unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
650
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
652
* \param encoder An encoder instance to query.
654
* \code encoder != NULL \endcode
656
* See OggFLAC__stream_encoder_set_blocksize().
658
OggFLAC_API unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
660
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
662
* \param encoder An encoder instance to query.
664
* \code encoder != NULL \endcode
666
* See OggFLAC__stream_encoder_set_max_lpc_order().
668
OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
670
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
672
* \param encoder An encoder instance to query.
674
* \code encoder != NULL \endcode
676
* See OggFLAC__stream_encoder_set_qlp_coeff_precision().
678
OggFLAC_API unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
680
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
682
* \param encoder An encoder instance to query.
684
* \code encoder != NULL \endcode
686
* See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
688
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
690
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
692
* \param encoder An encoder instance to query.
694
* \code encoder != NULL \endcode
696
* See OggFLAC__stream_encoder_set_do_escape_coding().
698
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
700
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
702
* \param encoder An encoder instance to query.
704
* \code encoder != NULL \endcode
706
* See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
708
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
710
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
712
* \param encoder An encoder instance to query.
714
* \code encoder != NULL \endcode
716
* See OggFLAC__stream_encoder_set_min_residual_partition_order().
718
OggFLAC_API unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
720
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
722
* \param encoder An encoder instance to query.
724
* \code encoder != NULL \endcode
726
* See OggFLAC__stream_encoder_set_max_residual_partition_order().
728
OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
730
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
732
* \param encoder An encoder instance to query.
734
* \code encoder != NULL \endcode
736
* See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
738
OggFLAC_API unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
740
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
742
* \param encoder An encoder instance to set.
744
* \code encoder != NULL \endcode
745
* \retval FLAC__uint64
746
* See OggFLAC__stream_encoder_get_total_samples_estimate().
748
OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
750
/** Initialize the encoder instance.
751
* Should be called after OggFLAC__stream_encoder_new() and
752
* OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
753
* or OggFLAC__stream_encoder_process_interleaved(). Will set and return
754
* the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
755
* initialization succeeded.
757
* The call to OggFLAC__stream_encoder_init() currently will also immediately
758
* call the write callback several times, once with the \c fLaC signature,
759
* and once for each encoded metadata block.
761
* \param encoder An uninitialized encoder instance.
763
* \code encoder != NULL \endcode
764
* \retval OggFLAC__StreamEncoderState
765
* \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
766
* OggFLAC__StreamEncoderState for the meanings of other return values.
768
OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
770
/** Finish the encoding process.
771
* Flushes the encoding buffer, releases resources, resets the encoder
772
* settings to their defaults, and returns the encoder state to
773
* OggFLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
774
* one or more write callbacks before returning.
776
* In the event of a prematurely-terminated encode, it is not strictly
777
* necessary to call this immediately before OggFLAC__stream_encoder_delete()
778
* but it is good practice to match every OggFLAC__stream_encoder_init()
779
* with an OggFLAC__stream_encoder_finish().
781
* \param encoder An uninitialized encoder instance.
783
* \code encoder != NULL \endcode
785
OggFLAC_API void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
787
/** Submit data for encoding.
788
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
790
* \param encoder An initialized encoder instance in the OK state.
791
* \param buffer An array of pointers to each channel's signal.
792
* \param samples The number of samples in one channel.
794
* \code encoder != NULL \endcode
795
* \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
797
* \c true if successful, else \c false; in this case, check the
798
* encoder state with OggFLAC__stream_encoder_get_state() to see what
801
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
803
/** Submit data for encoding.
804
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
806
* \param encoder An initialized encoder instance in the OK state.
807
* \param buffer An array of channel-interleaved data (see above).
808
* \param samples The number of samples in one channel, the same as for
809
* OggFLAC__stream_encoder_process(). For example, if
810
* encoding two channels, \c 1000 \a samples corresponds
811
* to a \a buffer of 2000 values.
813
* \code encoder != NULL \endcode
814
* \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
816
* \c true if successful, else \c false; in this case, check the
817
* encoder state with OggFLAC__stream_encoder_get_state() to see what
820
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
added
removed
include/OggFLAC/stream_encoder.h
