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__SEEKABLE_STREAM_ENCODER_H
33
#define OggFLAC__SEEKABLE_STREAM_ENCODER_H
37
#include "FLAC/stream_encoder.h"
38
#include "FLAC/seekable_stream_encoder.h"
45
/** \file include/OggFLAC/seekable_stream_encoder.h
48
* This module contains the functions which implement the seekable
51
* See the detailed documentation in the
52
* \link oggflac_seekable_stream_encoder seekable stream encoder \endlink module.
55
/** \defgroup oggflac_seekable_stream_encoder OggFLAC/seekable_stream_encoder.h: seekable stream encoder interface
56
* \ingroup oggflac_encoder
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.
63
* The interface here is nearly identical to FLAC's seekable stream
64
* encoder, including the callbacks, with the addition of a new required
65
* read callback (needed when writing back STREAMINFO after encoding) and
66
* OggFLAC__seekable_stream_encoder_set_serial_number(). See the
67
* \link flac_seekable_stream_encoder FLAC seekable stream encoder module \endlink
68
* for full documentation.
74
/** State values for an OggFLAC__SeekableStreamEncoder
76
* The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
80
OggFLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
81
/**< The encoder is in the normal OK state. */
83
OggFLAC__SEEKABLE_STREAM_ENCODER_OGG_ERROR,
84
/**< An error occurred in the underlying Ogg layer. */
86
OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
87
/**< An error occurred in the underlying FLAC stream encoder;
88
* check OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state().
91
OggFLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
92
/**< Memory allocation failed. */
94
OggFLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
95
/**< The write callback returned an error. */
97
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
98
/**< The read callback returned an error. */
100
OggFLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
101
/**< The seek callback returned an error. */
103
OggFLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
104
/**< The tell callback returned an error. */
106
OggFLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
107
/**< OggFLAC__seekable_stream_encoder_init() was called when the encoder was
108
* already initialized, usually because
109
* OggFLAC__seekable_stream_encoder_finish() was not called.
112
OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
113
/**< OggFLAC__seekable_stream_encoder_init() was called without all
114
* callbacks being set.
117
OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
118
/**< An invalid seek table was passed is the metadata to
119
* OggFLAC__seekable_stream_encoder_set_metadata().
122
OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
123
/**< The encoder is in the uninitialized state. */
125
} OggFLAC__SeekableStreamEncoderState;
127
/** Maps an OggFLAC__StreamEncoderState to a C string.
129
* Using an OggFLAC__StreamEncoderState as the index to this array
130
* will give the string equivalent. The contents should not be modified.
132
extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderStateString[];
135
/** Return values for the OggFLAC__SeekableStreamEncoder read callback.
139
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_CONTINUE,
140
/**< The read was OK and decoding can continue. */
142
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
143
/**< The read was attempted at the end of the stream. */
145
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_ABORT
146
/**< An unrecoverable error occurred. */
148
} OggFLAC__SeekableStreamEncoderReadStatus;
150
/** Maps a OggFLAC__SeekableStreamEncoderReadStatus to a C string.
152
* Using a OggFLAC__SeekableStreamEncoderReadStatus as the index to this array
153
* will give the string equivalent. The contents should not be modified.
155
extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderReadStatusString[];
158
/***********************************************************************
160
* class OggFLAC__StreamEncoder
162
***********************************************************************/
164
struct OggFLAC__SeekableStreamEncoderProtected;
165
struct OggFLAC__SeekableStreamEncoderPrivate;
166
/** The opaque structure definition for the seekable stream encoder type.
167
* See the \link oggflac_seekable_stream_encoder seekable stream encoder module \endlink
168
* for a detailed description.
171
struct OggFLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
172
struct OggFLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
173
} OggFLAC__SeekableStreamEncoder;
175
/** Signature for the read callback.
176
* See OggFLAC__seekable_stream_encoder_set_read_callback() for more info.
178
* \param encoder The encoder instance calling the callback.
179
* \param buffer A pointer to a location for the callee to store
180
* data to be encoded.
181
* \param bytes A pointer to the size of the buffer. On entry
182
* to the callback, it contains the maximum number
183
* of bytes that may be stored in \a buffer. The
184
* callee must set it to the actual number of bytes
185
* stored (0 in case of error or end-of-stream) before
187
* \param client_data The callee's client data set through
188
* OggFLAC__seekable_stream_encoder_set_client_data().
189
* \retval OggFLAC__SeekableStreamEncoderReadStatus
190
* The callee's return status.
192
typedef OggFLAC__SeekableStreamEncoderReadStatus (*OggFLAC__SeekableStreamEncoderReadCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
194
/** Signature for the seek callback.
195
* See OggFLAC__seekable_stream_encoder_set_seek_callback()
196
* and FLAC__SeekableStreamEncoderSeekCallback for more info.
198
* \param encoder The encoder instance calling the callback.
199
* \param absolute_byte_offset The offset from the beginning of the stream
201
* \param client_data The callee's client data set through
202
* OggFLAC__seekable_stream_encoder_set_client_data().
203
* \retval FLAC__SeekableStreamEncoderSeekStatus
204
* The callee's return status.
206
typedef FLAC__SeekableStreamEncoderSeekStatus (*OggFLAC__SeekableStreamEncoderSeekCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
208
/** Signature for the tell callback.
209
* See OggFLAC__seekable_stream_encoder_set_tell_callback()
210
* and FLAC__SeekableStreamEncoderTellCallback for more info.
212
* \param encoder The encoder instance calling the callback.
213
* \param absolute_byte_offset The address at which to store the current
214
* position of the output.
215
* \param client_data The callee's client data set through
216
* OggFLAC__seekable_stream_encoder_set_client_data().
217
* \retval FLAC__SeekableStreamEncoderTellStatus
218
* The callee's return status.
220
typedef FLAC__SeekableStreamEncoderTellStatus (*OggFLAC__SeekableStreamEncoderTellCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
222
/** Signature for the write callback.
223
* See OggFLAC__seekable_stream_encoder_set_write_callback()
224
* and FLAC__SeekableStreamEncoderWriteCallback for more info.
226
* \param encoder The encoder instance calling the callback.
227
* \param buffer An array of encoded data of length \a bytes.
228
* \param bytes The byte length of \a buffer.
229
* \param samples The number of samples encoded by \a buffer.
230
* \c 0 has a special meaning; see
231
* OggFLAC__seekable_stream_encoder_set_write_callback().
232
* \param current_frame The number of current frame being encoded.
233
* \param client_data The callee's client data set through
234
* OggFLAC__seekable_stream_encoder_set_client_data().
235
* \retval FLAC__StreamEncoderWriteStatus
236
* The callee's return status.
238
typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__SeekableStreamEncoderWriteCallback)(const OggFLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
241
/***********************************************************************
243
* Class constructor/destructor
245
***********************************************************************/
247
/** Create a new seekable stream encoder instance. The instance is created with
248
* default settings; see the individual OggFLAC__seekable_stream_encoder_set_*()
249
* functions for each setting's default.
251
* \retval OggFLAC__SeekableStreamEncoder*
252
* \c NULL if there was an error allocating memory, else the new instance.
254
OggFLAC_API OggFLAC__SeekableStreamEncoder *OggFLAC__seekable_stream_encoder_new();
256
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
258
* \param encoder A pointer to an existing encoder.
260
* \code encoder != NULL \endcode
262
OggFLAC_API void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *encoder);
265
/***********************************************************************
267
* Public class method prototypes
269
***********************************************************************/
271
/** Set the serial number for the FLAC stream.
274
* \param encoder An encoder instance to set.
275
* \param serial_number See above.
277
* \code encoder != NULL \endcode
279
* \c false if the encoder is already initialized, else \c true.
281
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_serial_number(OggFLAC__SeekableStreamEncoder *encoder, long serial_number);
283
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
286
* \param encoder An encoder instance to set.
287
* \param value Flag value (see above).
289
* \code encoder != NULL \endcode
291
* \c false if the encoder is already initialized, else \c true.
293
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
295
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
298
* \param encoder An encoder instance to set.
299
* \param value Flag value (see above).
301
* \code encoder != NULL \endcode
303
* \c false if the encoder is already initialized, else \c true.
305
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
307
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
310
* \param encoder An encoder instance to set.
311
* \param value Flag value (see above).
313
* \code encoder != NULL \endcode
315
* \c false if the encoder is already initialized, else \c true.
317
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
319
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
322
* \param encoder An encoder instance to set.
323
* \param value Flag value (see above).
325
* \code encoder != NULL \endcode
327
* \c false if the encoder is already initialized, else \c true.
329
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
331
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
334
* \param encoder An encoder instance to set.
335
* \param value See above.
337
* \code encoder != NULL \endcode
339
* \c false if the encoder is already initialized, else \c true.
341
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
343
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
346
* \param encoder An encoder instance to set.
347
* \param value See above.
349
* \code encoder != NULL \endcode
351
* \c false if the encoder is already initialized, else \c true.
353
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
355
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
358
* \param encoder An encoder instance to set.
359
* \param value See above.
361
* \code encoder != NULL \endcode
363
* \c false if the encoder is already initialized, else \c true.
365
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
367
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
370
* \param encoder An encoder instance to set.
371
* \param value See above.
373
* \code encoder != NULL \endcode
375
* \c false if the encoder is already initialized, else \c true.
377
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
379
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
382
* \param encoder An encoder instance to set.
383
* \param value See above.
385
* \code encoder != NULL \endcode
387
* \c false if the encoder is already initialized, else \c true.
389
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
391
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
394
* \param encoder An encoder instance to set.
395
* \param value See above.
397
* \code encoder != NULL \endcode
399
* \c false if the encoder is already initialized, else \c true.
401
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
403
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
406
* \param encoder An encoder instance to set.
407
* \param value See above.
409
* \code encoder != NULL \endcode
411
* \c false if the encoder is already initialized, else \c true.
413
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
415
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
418
* \param encoder An encoder instance to set.
419
* \param value See above.
421
* \code encoder != NULL \endcode
423
* \c false if the encoder is already initialized, else \c true.
425
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
427
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
430
* \param encoder An encoder instance to set.
431
* \param value See above.
433
* \code encoder != NULL \endcode
435
* \c false if the encoder is already initialized, else \c true.
437
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
439
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
442
* \param encoder An encoder instance to set.
443
* \param value See above.
445
* \code encoder != NULL \endcode
447
* \c false if the encoder is already initialized, else \c true.
449
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
451
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
454
* \param encoder An encoder instance to set.
455
* \param value See above.
457
* \code encoder != NULL \endcode
459
* \c false if the encoder is already initialized, else \c true.
461
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
463
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
466
* \param encoder An encoder instance to set.
467
* \param value See above.
469
* \code encoder != NULL \endcode
471
* \c false if the encoder is already initialized, else \c true.
473
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
475
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
478
* \param encoder An encoder instance to set.
479
* \param value See above.
481
* \code encoder != NULL \endcode
483
* \c false if the encoder is already initialized, else \c true.
485
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_total_samples_estimate(OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
487
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
489
* \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
490
* the second metadata block of the stream. The encoder already supplies
491
* the STREAMINFO block automatically. If \a metadata does not contain a
492
* VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
493
* \a metadata does contain a VORBIS_COMMENT block and it is not the
494
* first, this function will reorder \a metadata by moving the
495
* VORBIS_COMMENT block to the front; the relative ordering of the other
496
* blocks will remain as they were.
498
* \note The Ogg FLAC mapping limits the number of metadata blocks per
499
* stream to \c 65535. If \a num_blocks exceeds this the function will
502
* \default \c NULL, 0
503
* \param encoder An encoder instance to set.
504
* \param metadata See above.
505
* \param num_blocks See above.
507
* \code encoder != NULL \endcode
509
* \c false if the encoder is already initialized, or if
510
* \a num_blocks > 65535, else \c true.
512
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_metadata(OggFLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
514
/** Set the read callback.
515
* The supplied function will be called when the encoder needs to read back
516
* encoded data. This happens during the metadata callback, when the encoder
517
* has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
518
* while encoding. The address of the buffer to be filled is supplied, along
519
* with the number of bytes the buffer can hold. The callback may choose to
520
* supply less data and modify the byte count but must be careful not to
521
* overflow the buffer. The callback then returns a status code chosen from
522
* OggFLAC__SeekableStreamEncoderReadStatus.
525
* The callback is mandatory and must be set before initialization.
528
* \param encoder A encoder instance to set.
529
* \param value See above.
531
* \code encoder != NULL \endcode
532
* \code value != NULL \endcode
534
* \c false if the encoder is already initialized, else \c true.
536
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_read_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderReadCallback value);
538
/** Set the seek callback.
539
* The supplied function will be called when the encoder needs to seek
540
* the output stream. The encoder will pass the absolute byte offset
541
* to seek to, 0 meaning the beginning of the stream.
544
* The callback is mandatory and must be set before initialization.
547
* \param encoder An encoder instance to set.
548
* \param value See above.
550
* \code encoder != NULL \endcode
551
* \code value != NULL \endcode
553
* \c false if the encoder is already initialized, else \c true.
555
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_seek_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderSeekCallback value);
557
/** Set the tell callback.
558
* The supplied function will be called when the encoder needs to know
559
* the current position of the output stream.
562
* The callback is mandatory and must be set before initialization.
565
* \param encoder An encoder instance to set.
566
* \param value See above.
568
* \code encoder != NULL \endcode
569
* \code value != NULL \endcode
571
* \c false if the encoder is already initialized, else \c true.
573
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_tell_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderTellCallback value);
575
/** Set the write callback.
576
* This is inherited from FLAC__StreamEncoder; see
577
* FLAC__stream_encoder_set_write_callback().
580
* Unlike the FLAC seekable stream encoder write callback, the Ogg
581
* seekable stream encoder write callback will be called twice when
582
* writing audio frames; once for the page header, and once for the page
583
* body. When writing the page header, the \a samples argument to the
584
* write callback will be \c 0.
587
* The callback is mandatory and must be set before initialization.
590
* \param encoder An encoder instance to set.
591
* \param value See above.
593
* \code encoder != NULL \endcode
594
* \code value != NULL \endcode
596
* \c false if the encoder is already initialized, else \c true.
598
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_write_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderWriteCallback value);
600
/** Set the client data to be passed back to callbacks.
601
* This value will be supplied to callbacks in their \a client_data
605
* \param encoder An encoder instance to set.
606
* \param value See above.
608
* \code encoder != NULL \endcode
610
* \c false if the encoder is already initialized, else \c true.
612
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_client_data(OggFLAC__SeekableStreamEncoder *encoder, void *value);
614
/** Get the current encoder state.
616
* \param encoder An encoder instance to query.
618
* \code encoder != NULL \endcode
619
* \retval OggFLAC__SeekableStreamEncoderState
620
* The current encoder state.
622
OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_state(const OggFLAC__SeekableStreamEncoder *encoder);
624
/** Get the state of the underlying FLAC stream encoder.
625
* Useful when the seekable stream encoder state is
626
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
628
* \param encoder An encoder instance to query.
630
* \code encoder != NULL \endcode
631
* \retval FLAC__StreamEncoderState
632
* The FLAC stream encoder state.
634
OggFLAC_API FLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
636
/** Get the state of the underlying FLAC encoder's verify decoder.
637
* Useful when the seekable stream encoder state is
638
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
639
* and the FLAC stream encoder state is
640
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
642
* \param encoder An encoder instance to query.
644
* \code encoder != NULL \endcode
645
* \retval FLAC__StreamDecoderState
646
* The FLAC verify decoder state.
648
OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
650
/** Get the current encoder state as a C string.
651
* This version automatically resolves
652
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
653
* by getting the FLAC stream encoder's resolved state.
655
* \param encoder A encoder instance to query.
657
* \code encoder != NULL \endcode
658
* \retval const char *
659
* The encoder state as a C string. Do not modify the contents.
661
OggFLAC_API const char *OggFLAC__seekable_stream_encoder_get_resolved_state_string(const OggFLAC__SeekableStreamEncoder *encoder);
663
/** Get relevant values about the nature of a verify decoder error.
664
* Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
665
* Useful when the seekable stream encoder state is
666
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
667
* and the FLAC stream encoder state is
668
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
670
* \param encoder An encoder instance to query.
671
* \param absolute_sample The absolute sample number of the mismatch.
672
* \param frame_number The number of the frame in which the mismatch occurred.
673
* \param channel The channel in which the mismatch occurred.
674
* \param sample The number of the sample (relative to the frame) in
675
* which the mismatch occurred.
676
* \param expected The expected value for the sample in question.
677
* \param got The actual value returned by the decoder.
679
* \code encoder != NULL \endcode
680
* \code absolute_sample != NULL \endcode
681
* \code frame_number != NULL \endcode
682
* \code channel != NULL \endcode
683
* \code sample != NULL \endcode
684
* \code expected != NULL \endcode
686
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);
688
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
690
* \param encoder An encoder instance to query.
692
* \code encoder != NULL \endcode
694
* See OggFLAC__seekable_stream_encoder_set_verify().
696
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableStreamEncoder *encoder);
698
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
700
* \param encoder An encoder instance to query.
702
* \code encoder != NULL \endcode
704
* See OggFLAC__seekable_stream_encoder_set_streamable_subset().
706
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC__SeekableStreamEncoder *encoder);
708
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
710
* \param encoder An encoder instance to query.
712
* \code encoder != NULL \endcode
714
* See OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo().
716
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
718
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
720
* \param encoder An encoder instance to query.
722
* \code encoder != NULL \endcode
724
* See OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
726
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
728
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
730
* \param encoder An encoder instance to query.
732
* \code encoder != NULL \endcode
734
* See OggFLAC__seekable_stream_encoder_set_channels().
736
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableStreamEncoder *encoder);
738
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
740
* \param encoder An encoder instance to query.
742
* \code encoder != NULL \endcode
744
* See OggFLAC__seekable_stream_encoder_set_bits_per_sample().
746
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__SeekableStreamEncoder *encoder);
748
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
750
* \param encoder An encoder instance to query.
752
* \code encoder != NULL \endcode
754
* See OggFLAC__seekable_stream_encoder_set_sample_rate().
756
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__SeekableStreamEncoder *encoder);
758
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
760
* \param encoder An encoder instance to query.
762
* \code encoder != NULL \endcode
764
* See OggFLAC__seekable_stream_encoder_set_blocksize().
766
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableStreamEncoder *encoder);
768
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
770
* \param encoder An encoder instance to query.
772
* \code encoder != NULL \endcode
774
* See OggFLAC__seekable_stream_encoder_set_max_lpc_order().
776
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__SeekableStreamEncoder *encoder);
778
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
780
* \param encoder An encoder instance to query.
782
* \code encoder != NULL \endcode
784
* See OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision().
786
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC__SeekableStreamEncoder *encoder);
788
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
790
* \param encoder An encoder instance to query.
792
* \code encoder != NULL \endcode
794
* See OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
796
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__SeekableStreamEncoder *encoder);
798
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
800
* \param encoder An encoder instance to query.
802
* \code encoder != NULL \endcode
804
* See OggFLAC__seekable_stream_encoder_set_do_escape_coding().
806
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__SeekableStreamEncoder *encoder);
808
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
810
* \param encoder An encoder instance to query.
812
* \code encoder != NULL \endcode
814
* See OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
816
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const OggFLAC__SeekableStreamEncoder *encoder);
818
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
820
* \param encoder An encoder instance to query.
822
* \code encoder != NULL \endcode
824
* See OggFLAC__seekable_stream_encoder_set_min_residual_partition_order().
826
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
828
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
830
* \param encoder An encoder instance to query.
832
* \code encoder != NULL \endcode
834
* See OggFLAC__seekable_stream_encoder_set_max_residual_partition_order().
836
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
838
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
840
* \param encoder An encoder instance to query.
842
* \code encoder != NULL \endcode
844
* See OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
846
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const OggFLAC__SeekableStreamEncoder *encoder);
848
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
850
* \param encoder An encoder instance to set.
852
* \code encoder != NULL \endcode
853
* \retval FLAC__uint64
854
* See OggFLAC__seekable_stream_encoder_get_total_samples_estimate().
856
OggFLAC_API FLAC__uint64 OggFLAC__seekable_stream_encoder_get_total_samples_estimate(const OggFLAC__SeekableStreamEncoder *encoder);
858
/** Initialize the encoder instance.
859
* Should be called after OggFLAC__seekable_stream_encoder_new() and
860
* OggFLAC__seekable_stream_encoder_set_*() but before OggFLAC__seekable_stream_encoder_process()
861
* or OggFLAC__seekable_stream_encoder_process_interleaved(). Will set and return
862
* the encoder state, which will be OggFLAC__SEEKABLE_STREAM_ENCODER_OK if
863
* initialization succeeded.
865
* The call to OggFLAC__seekable_stream_encoder_init() currently will also immediately
866
* call the write callback several times, once with the \c fLaC signature,
867
* and once for each encoded metadata block.
869
* \param encoder An uninitialized encoder instance.
871
* \code encoder != NULL \endcode
872
* \retval OggFLAC__SeekableStreamEncoderState
873
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
874
* OggFLAC__SeekableStreamEncoderState for the meanings of other return values.
876
OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLAC__SeekableStreamEncoder *encoder);
878
/** Finish the encoding process.
879
* Flushes the encoding buffer, releases resources, resets the encoder
880
* settings to their defaults, and returns the encoder state to
881
* OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED. Note that this can generate
882
* one or more write callbacks before returning.
884
* In the event of a prematurely-terminated encode, it is not strictly
885
* necessary to call this immediately before OggFLAC__seekable_stream_encoder_delete()
886
* but it is good practice to match every OggFLAC__seekable_stream_encoder_init()
887
* with an OggFLAC__seekable_stream_encoder_finish().
889
* \param encoder An uninitialized encoder instance.
891
* \code encoder != NULL \endcode
893
OggFLAC_API void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *encoder);
895
/** Submit data for encoding.
896
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
898
* \param encoder An initialized encoder instance in the OK state.
899
* \param buffer An array of pointers to each channel's signal.
900
* \param samples The number of samples in one channel.
902
* \code encoder != NULL \endcode
903
* \code OggFLAC__seekable_stream_encoder_get_state(encoder) == OggFLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
905
* \c true if successful, else \c false; in this case, check the
906
* encoder state with OggFLAC__seekable_stream_encoder_get_state() to see what
909
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_process(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
911
/** Submit data for encoding.
912
* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
914
* \param encoder An initialized encoder instance in the OK state.
915
* \param buffer An array of channel-interleaved data (see above).
916
* \param samples The number of samples in one channel, the same as for
917
* OggFLAC__seekable_stream_encoder_process(). For example, if
918
* encoding two channels, \c 1000 \a samples corresponds
919
* to a \a buffer of 2000 values.
921
* \code encoder != NULL \endcode
922
* \code OggFLAC__seekable_stream_encoder_get_state(encoder) == OggFLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
924
* \c true if successful, else \c false; in this case, check the
925
* encoder state with OggFLAC__seekable_stream_encoder_get_state() to see what
928
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_process_interleaved(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
added
removed
include/OggFLAC/seekable_stream_encoder.h
