87
78
* This module contains the functions which implement the stream
81
* The stream encoder can encode to native FLAC, and optionally Ogg FLAC
82
* (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
90
84
* The basic usage of this encoder is as follows:
91
85
* - The program creates an instance of an encoder using
92
86
* FLAC__stream_encoder_new().
93
* - The program overrides the default settings and sets callbacks using
94
* FLAC__stream_encoder_set_*() functions.
87
* - The program overrides the default settings using
88
* FLAC__stream_encoder_set_*() functions. At a minimum, the following
89
* functions should be called:
90
* - FLAC__stream_encoder_set_channels()
91
* - FLAC__stream_encoder_set_bits_per_sample()
92
* - FLAC__stream_encoder_set_sample_rate()
93
* - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
94
* - FLAC__stream_encoder_set_total_samples_estimate() (if known)
95
* - If the application wants to control the compression level or set its own
96
* metadata, then the following should also be called:
97
* - FLAC__stream_encoder_set_compression_level()
98
* - FLAC__stream_encoder_set_verify()
99
* - FLAC__stream_encoder_set_metadata()
100
* - The rest of the set functions should only be called if the client needs
101
* exact control over how the audio is compressed; thorough understanding
102
* of the FLAC format is necessary to achieve good results.
95
103
* - The program initializes the instance to validate the settings and
96
* prepare for encoding using FLAC__stream_encoder_init().
104
* prepare for encoding using
105
* - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
106
* or FLAC__stream_encoder_init_file() for native FLAC
107
* - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
108
* or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
97
109
* - The program calls FLAC__stream_encoder_process() or
98
110
* FLAC__stream_encoder_process_interleaved() to encode data, which
99
111
* subsequently calls the callbacks when there is encoder data ready
101
113
* - The program finishes the encoding with FLAC__stream_encoder_finish(),
102
114
* which causes the encoder to encode any data still in its input pipe,
103
* call the metadata callback with the final encoding statistics, and
104
* finally reset the encoder to the uninitialized state.
115
* update the metadata with the final encoding statistics if output
116
* seeking is possible, and finally reset the encoder to the
117
* uninitialized state.
105
118
* - The instance may be used again or deleted with
106
119
* FLAC__stream_encoder_delete().
108
121
* In more detail, the stream encoder functions similarly to the
109
122
* \link flac_stream_decoder stream decoder \endlink, but has fewer
110
* callbacks and more options. Typically the user will create a new
123
* callbacks and more options. Typically the client will create a new
111
124
* instance by calling FLAC__stream_encoder_new(), then set the necessary
112
* parameters and callbacks with FLAC__stream_encoder_set_*(), and
113
* initialize it by calling FLAC__stream_encoder_init().
125
* parameters with FLAC__stream_encoder_set_*(), and initialize it by
126
* calling one of the FLAC__stream_encoder_init_*() functions.
115
128
* Unlike the decoders, the stream encoder has many options that can
116
129
* affect the speed and compression ratio. When setting these parameters
118
131
* <A HREF="../documentation.html#format">user-level documentation</A>
119
132
* or the <A HREF="../format.html">formal description</A>). The
120
133
* FLAC__stream_encoder_set_*() functions themselves do not validate the
121
* values as many are interdependent. The FLAC__stream_encoder_init()
122
* function will do this, so make sure to pay attention to the state
123
* returned by FLAC__stream_encoder_init() to make sure that it is
124
* FLAC__STREAM_ENCODER_OK. Any parameters that are not set before
125
* FLAC__stream_encoder_init() will take on the defaults from the
128
* The user must provide function pointers for the following callbacks:
130
* - Write callback - This function is called by the encoder anytime there
131
* is raw encoded data to write. It may include metadata mixed with
132
* encoded audio frames and the data is not guaranteed to be aligned on
133
* frame or metadata block boundaries.
134
* - Metadata callback - This function is called once at the end of
135
* encoding with the populated STREAMINFO structure. This is so file
136
* encoders can seek back to the beginning of the file and write the
137
* STREAMINFO block with the correct statistics after encoding (like
138
* minimum/maximum frame size).
140
* The call to FLAC__stream_encoder_init() currently will also immediately
134
* values as many are interdependent. The FLAC__stream_encoder_init_*()
135
* functions will do this, so make sure to pay attention to the state
136
* returned by FLAC__stream_encoder_init_*() to make sure that it is
137
* FLAC__STREAM_ENCODER_INIT_STATUS_OK. Any parameters that are not set
138
* before FLAC__stream_encoder_init_*() will take on the defaults from
141
* There are three initialization functions for native FLAC, one for
142
* setting up the encoder to encode FLAC data to the client via
143
* callbacks, and two for encoding directly to a file.
145
* For encoding via callbacks, use FLAC__stream_encoder_init_stream().
146
* You must also supply a write callback which will be called anytime
147
* there is raw encoded data to write. If the client can seek the output
148
* it is best to also supply seek and tell callbacks, as this allows the
149
* encoder to go back after encoding is finished to write back
150
* information that was collected while encoding, like seek point offsets,
153
* For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
154
* or FLAC__stream_encoder_init_file(). Then you must only supply a
155
* filename or open \c FILE*; the encoder will handle all the callbacks
156
* internally. You may also supply a progress callback for periodic
157
* notification of the encoding progress.
159
* There are three similarly-named init functions for encoding to Ogg
160
* FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
161
* library has been built with Ogg support.
163
* The call to FLAC__stream_encoder_init_*() currently will also immediately
141
164
* call the write callback several times, once with the \c fLaC signature,
142
* and once for each encoded metadata block.
165
* and once for each encoded metadata block. Note that for Ogg FLAC
166
* encoding you will usually get at least twice the number of callbacks than
167
* with native FLAC, one for the Ogg page header and one for the page body.
144
* After initializing the instance, the user may feed audio data to the
169
* After initializing the instance, the client may feed audio data to the
145
170
* encoder in one of two ways:
147
* - Channel separate, through FLAC__stream_encoder_process() - The user
172
* - Channel separate, through FLAC__stream_encoder_process() - The client
148
173
* will pass an array of pointers to buffers, one for each channel, to
149
174
* the encoder, each of the same length. The samples need not be
175
* block-aligned, but each channel should have the same number of samples.
151
176
* - Channel interleaved, through
152
* FLAC__stream_encoder_process_interleaved() - The user will pass a single
177
* FLAC__stream_encoder_process_interleaved() - The client will pass a single
153
178
* pointer to data that is channel-interleaved (i.e. channel0_sample0,
154
179
* channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
155
180
* Again, the samples need not be block-aligned but they must be
156
181
* sample-aligned, i.e. the first value should be channel0_sample0 and
157
182
* the last value channelN_sampleM.
159
* When the user is finished encoding data, it calls
184
* Note that for either process call, each sample in the buffers should be a
185
* signed integer, right-justified to the resolution set by
186
* FLAC__stream_encoder_set_bits_per_sample(). For example, if the resolution
187
* is 16 bits per sample, the samples should all be in the range [-32768,32767].
189
* When the client is finished encoding data, it calls
160
190
* FLAC__stream_encoder_finish(), which causes the encoder to encode any
161
191
* data still in its input pipe, and call the metadata callback with the
162
192
* final encoding statistics. Then the instance may be deleted with
210
261
* audio signal and the decoded audio signal.
213
FLAC__STREAM_ENCODER_INVALID_CALLBACK,
214
/**< The encoder was initialized before setting all the required callbacks. */
216
FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS,
264
FLAC__STREAM_ENCODER_CLIENT_ERROR,
265
/**< One of the callbacks returned a fatal error. */
267
FLAC__STREAM_ENCODER_IO_ERROR,
268
/**< An I/O error occurred while opening/reading/writing a file.
272
FLAC__STREAM_ENCODER_FRAMING_ERROR,
273
/**< An error occurred while writing the stream; usually, the
274
* write_callback returned an error.
277
FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
278
/**< Memory allocation failed. */
280
} FLAC__StreamEncoderState;
282
/** Maps a FLAC__StreamEncoderState to a C string.
284
* Using a FLAC__StreamEncoderState as the index to this array
285
* will give the string equivalent. The contents should not be modified.
287
extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
290
/** Possible return values for the FLAC__stream_encoder_init_*() functions.
294
FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
295
/**< Initialization was successful. */
297
FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
298
/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
300
FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
301
/**< The library was not compiled with support for the given container
305
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
306
/**< A required callback was not supplied. */
308
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
217
309
/**< The encoder has an invalid setting for number of channels. */
219
FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE,
311
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
220
312
/**< The encoder has an invalid setting for bits-per-sample.
221
313
* FLAC supports 4-32 bps but the reference encoder currently supports
222
314
* only up to 24 bps.
225
FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE,
317
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
226
318
/**< The encoder has an invalid setting for the input sample rate. */
228
FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,
320
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
229
321
/**< The encoder has an invalid setting for the block size. */
231
FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER,
323
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
232
324
/**< The encoder has an invalid setting for the maximum LPC order. */
234
FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION,
326
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
235
327
/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
237
FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH,
238
/**< Mid/side coding was specified but the number of channels is not equal to 2. */
240
FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,
243
FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE,
244
/**< Loose mid/side coding was specified but mid/side coding was not. */
246
FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
329
FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
247
330
/**< The specified block size is less than the maximum LPC order. */
249
FLAC__STREAM_ENCODER_NOT_STREAMABLE,
250
/**< The encoder is bound to the "streamable subset" but other settings violate it. */
252
FLAC__STREAM_ENCODER_FRAMING_ERROR,
253
/**< An error occurred while writing the stream; usually, the write_callback returned an error. */
255
FLAC__STREAM_ENCODER_INVALID_METADATA,
332
FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
333
/**< The encoder is bound to the <A HREF="../format.html#subset">Subset</A> but other settings violate it. */
335
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
256
336
/**< The metadata input to the encoder is invalid, in one of the following ways:
257
337
* - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
258
338
* - One of the metadata blocks contains an undefined type
325
466
struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
326
467
} FLAC__StreamEncoder;
469
/** Signature for the read callback.
471
* A function pointer matching this signature must be passed to
472
* FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
473
* The supplied function will be called when the encoder needs to read back
474
* encoded data. This happens during the metadata callback, when the encoder
475
* has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
476
* while encoding. The address of the buffer to be filled is supplied, along
477
* with the number of bytes the buffer can hold. The callback may choose to
478
* supply less data and modify the byte count but must be careful not to
479
* overflow the buffer. The callback then returns a status code chosen from
480
* FLAC__StreamEncoderReadStatus.
482
* Here is an example of a read callback for stdio streams:
484
* FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
486
* FILE *file = ((MyClientData*)client_data)->file;
488
* *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
490
* return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
491
* else if(*bytes == 0)
492
* return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
494
* return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
497
* return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
501
* \note In general, FLAC__StreamEncoder functions which change the
502
* state should not be called on the \a encoder while in the callback.
504
* \param encoder The encoder instance calling the callback.
505
* \param buffer A pointer to a location for the callee to store
506
* data to be encoded.
507
* \param bytes A pointer to the size of the buffer. On entry
508
* to the callback, it contains the maximum number
509
* of bytes that may be stored in \a buffer. The
510
* callee must set it to the actual number of bytes
511
* stored (0 in case of error or end-of-stream) before
513
* \param client_data The callee's client data set through
514
* FLAC__stream_encoder_set_client_data().
515
* \retval FLAC__StreamEncoderReadStatus
516
* The callee's return status.
518
typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
328
520
/** Signature for the write callback.
329
* See FLAC__stream_encoder_set_write_callback() for more info.
522
* A function pointer matching this signature must be passed to
523
* FLAC__stream_encoder_init*_stream(). The supplied function will be called
524
* by the encoder anytime there is raw encoded data ready to write. It may
525
* include metadata mixed with encoded audio frames and the data is not
526
* guaranteed to be aligned on frame or metadata block boundaries.
528
* The only duty of the callback is to write out the \a bytes worth of data
529
* in \a buffer to the current position in the output stream. The arguments
530
* \a samples and \a current_frame are purely informational. If \a samples
531
* is greater than \c 0, then \a current_frame will hold the current frame
532
* number that is being written; otherwise it indicates that the write
533
* callback is being called to write metadata.
536
* Unlike when writing to native FLAC, when writing to Ogg FLAC the
537
* write callback will be called twice when writing each audio
538
* frame; once for the page header, and once for the page body.
539
* When writing the page header, the \a samples argument to the
540
* write callback will be \c 0.
542
* \note In general, FLAC__StreamEncoder functions which change the
543
* state should not be called on the \a encoder while in the callback.
331
545
* \param encoder The encoder instance calling the callback.
332
546
* \param buffer An array of encoded data of length \a bytes.
333
547
* \param bytes The byte length of \a buffer.
334
548
* \param samples The number of samples encoded by \a buffer.
335
* \c 0 has a special meaning; see
336
* FLAC__stream_encoder_set_write_callback().
549
* \c 0 has a special meaning; see above.
337
550
* \param current_frame The number of the current frame being encoded.
338
551
* \param client_data The callee's client data set through
339
* FLAC__stream_encoder_set_client_data().
552
* FLAC__stream_encoder_init_*().
340
553
* \retval FLAC__StreamEncoderWriteStatus
341
554
* The callee's return status.
343
typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
556
typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data);
558
/** Signature for the seek callback.
560
* A function pointer matching this signature may be passed to
561
* FLAC__stream_encoder_init*_stream(). The supplied function will be called
562
* when the encoder needs to seek the output stream. The encoder will pass
563
* the absolute byte offset to seek to, 0 meaning the beginning of the stream.
565
* Here is an example of a seek callback for stdio streams:
567
* FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
569
* FILE *file = ((MyClientData*)client_data)->file;
571
* return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
572
* else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
573
* return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
575
* return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
579
* \note In general, FLAC__StreamEncoder functions which change the
580
* state should not be called on the \a encoder while in the callback.
582
* \param encoder The encoder instance calling the callback.
583
* \param absolute_byte_offset The offset from the beginning of the stream
585
* \param client_data The callee's client data set through
586
* FLAC__stream_encoder_init_*().
587
* \retval FLAC__StreamEncoderSeekStatus
588
* The callee's return status.
590
typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
592
/** Signature for the tell callback.
594
* A function pointer matching this signature may be passed to
595
* FLAC__stream_encoder_init*_stream(). The supplied function will be called
596
* when the encoder needs to know the current position of the output stream.
599
* The callback must return the true current byte offset of the output to
600
* which the encoder is writing. If you are buffering the output, make
601
* sure and take this into account. If you are writing directly to a
602
* FILE* from your write callback, ftell() is sufficient. If you are
603
* writing directly to a file descriptor from your write callback, you
604
* can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
605
* these points to rewrite metadata after encoding.
607
* Here is an example of a tell callback for stdio streams:
609
* FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
611
* FILE *file = ((MyClientData*)client_data)->file;
614
* return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
615
* else if((pos = ftello(file)) < 0)
616
* return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
618
* *absolute_byte_offset = (FLAC__uint64)pos;
619
* return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
624
* \note In general, FLAC__StreamEncoder functions which change the
625
* state should not be called on the \a encoder while in the callback.
627
* \param encoder The encoder instance calling the callback.
628
* \param absolute_byte_offset The address at which to store the current
629
* position of the output.
630
* \param client_data The callee's client data set through
631
* FLAC__stream_encoder_init_*().
632
* \retval FLAC__StreamEncoderTellStatus
633
* The callee's return status.
635
typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
345
637
/** Signature for the metadata callback.
346
* See FLAC__stream_encoder_set_metadata_callback() for more info.
639
* A function pointer matching this signature may be passed to
640
* FLAC__stream_encoder_init*_stream(). The supplied function will be called
641
* once at the end of encoding with the populated STREAMINFO structure. This
642
* is so the client can seek back to the beginning of the file and write the
643
* STREAMINFO block with the correct statistics after encoding (like
644
* minimum/maximum frame size and total samples).
646
* \note In general, FLAC__StreamEncoder functions which change the
647
* state should not be called on the \a encoder while in the callback.
348
649
* \param encoder The encoder instance calling the callback.
349
650
* \param metadata The final populated STREAMINFO block.
350
651
* \param client_data The callee's client data set through
351
* FLAC__stream_encoder_set_client_data().
652
* FLAC__stream_encoder_init_*().
353
654
typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
656
/** Signature for the progress callback.
658
* A function pointer matching this signature may be passed to
659
* FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
660
* The supplied function will be called when the encoder has finished
661
* writing a frame. The \c total_frames_estimate argument to the
662
* callback will be based on the value from
663
* FLAC__stream_encoder_set_total_samples_estimate().
665
* \note In general, FLAC__StreamEncoder functions which change the
666
* state should not be called on the \a encoder while in the callback.
668
* \param encoder The encoder instance calling the callback.
669
* \param bytes_written Bytes written so far.
670
* \param samples_written Samples written so far.
671
* \param frames_written Frames written so far.
672
* \param total_frames_estimate The estimate of the total number of
673
* frames to be written.
674
* \param client_data The callee's client data set through
675
* FLAC__stream_encoder_init_*().
677
typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
356
680
/***********************************************************************
487
801
FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value);
803
/** Set the compression level
805
* The compression level is roughly proportional to the amount of effort
806
* the encoder expends to compress the file. A higher level usually
807
* means more computation but higher compression. The default level is
808
* suitable for most applications.
810
* Currently the levels range from \c 0 (fastest, least compression) to
811
* \c 8 (slowest, most compression). A value larger than \c 8 will be
814
* This function automatically calls the following other \c _set_
815
* functions with appropriate values, so the client does not need to
816
* unless it specifically wants to override them:
817
* - FLAC__stream_encoder_set_do_mid_side_stereo()
818
* - FLAC__stream_encoder_set_loose_mid_side_stereo()
819
* - FLAC__stream_encoder_set_apodization()
820
* - FLAC__stream_encoder_set_max_lpc_order()
821
* - FLAC__stream_encoder_set_qlp_coeff_precision()
822
* - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
823
* - FLAC__stream_encoder_set_do_escape_coding()
824
* - FLAC__stream_encoder_set_do_exhaustive_model_search()
825
* - FLAC__stream_encoder_set_min_residual_partition_order()
826
* - FLAC__stream_encoder_set_max_residual_partition_order()
827
* - FLAC__stream_encoder_set_rice_parameter_search_dist()
829
* The actual values set for each level are:
832
* <td><b>level</b><td>
833
* <td>do mid-side stereo<td>
834
* <td>loose mid-side stereo<td>
835
* <td>apodization<td>
836
* <td>max lpc order<td>
837
* <td>qlp coeff precision<td>
838
* <td>qlp coeff prec search<td>
839
* <td>escape coding<td>
840
* <td>exhaustive model search<td>
841
* <td>min residual partition order<td>
842
* <td>max residual partition order<td>
843
* <td>rice parameter search dist<td>
845
* <tr> <td><b>0</b><td> <td>false<td> <td>false<td> <td>tukey(0.5)<td> <td>0<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>3<td> <td>0<td> </tr>
846
* <tr> <td><b>1</b><td> <td>true<td> <td>true<td> <td>tukey(0.5)<td> <td>0<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>3<td> <td>0<td> </tr>
847
* <tr> <td><b>2</b><td> <td>true<td> <td>false<td> <td>tukey(0.5)<td> <td>0<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>3<td> <td>0<td> </tr>
848
* <tr> <td><b>3</b><td> <td>false<td> <td>false<td> <td>tukey(0.5)<td> <td>6<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>4<td> <td>0<td> </tr>
849
* <tr> <td><b>4</b><td> <td>true<td> <td>true<td> <td>tukey(0.5)<td> <td>8<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>4<td> <td>0<td> </tr>
850
* <tr> <td><b>5</b><td> <td>true<td> <td>false<td> <td>tukey(0.5)<td> <td>8<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>5<td> <td>0<td> </tr>
851
* <tr> <td><b>6</b><td> <td>true<td> <td>false<td> <td>tukey(0.5)<td> <td>8<td> <td>0<td> <td>false<td> <td>false<td> <td>false<td> <td>0<td> <td>6<td> <td>0<td> </tr>
852
* <tr> <td><b>7</b><td> <td>true<td> <td>false<td> <td>tukey(0.5)<td> <td>8<td> <td>0<td> <td>false<td> <td>false<td> <td>true<td> <td>0<td> <td>6<td> <td>0<td> </tr>
853
* <tr> <td><b>8</b><td> <td>true<td> <td>false<td> <td>tukey(0.5)<td> <td>12<td> <td>0<td> <td>false<td> <td>false<td> <td>true<td> <td>0<td> <td>6<td> <td>0<td> </tr>
857
* \param encoder An encoder instance to set.
858
* \param value See above.
860
* \code encoder != NULL \endcode
862
* \c false if the encoder is already initialized, else \c true.
864
FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value);
489
866
/** Set the blocksize to use while encoding.
868
* The number of samples to use per frame. Use \c 0 to let the encoder
869
* estimate a blocksize; this is usually best.
492
872
* \param encoder An encoder instance to set.
493
873
* \param value See above.
499
879
FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value);
881
/** Set to \c true to enable mid-side encoding on stereo input. The
882
* number of channels must be 2 for this to have any effect. Set to
883
* \c false to use only independent channel coding.
886
* \param encoder An encoder instance to set.
887
* \param value Flag value (see above).
889
* \code encoder != NULL \endcode
891
* \c false if the encoder is already initialized, else \c true.
893
FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
895
/** Set to \c true to enable adaptive switching between mid-side and
896
* left-right encoding on stereo input. Set to \c false to use
897
* exhaustive searching. Setting this to \c true requires
898
* FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
899
* \c true in order to have any effect.
902
* \param encoder An encoder instance to set.
903
* \param value Flag value (see above).
905
* \code encoder != NULL \endcode
907
* \c false if the encoder is already initialized, else \c true.
909
FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
911
/* @@@@add to unit tests*/
912
/** Sets the apodization function(s) the encoder will use when windowing
913
* audio data for LPC analysis.
915
* The \a specification is a plain ASCII string which specifies exactly
916
* which functions to use. There may be more than one (up to 32),
917
* separated by \c ';' characters. Some functions take one or more
918
* comma-separated arguments in parentheses.
920
* The available functions are \c bartlett, \c bartlett_hann,
921
* \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
922
* \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
923
* \c rectangle, \c triangle, \c tukey(P), \c welch.
925
* For \c gauss(STDDEV), STDDEV specifies the standard deviation
928
* For \c tukey(P), P specifies the fraction of the window that is
929
* tapered (0<=P<=1). P=0 corresponds to \c rectangle and P=1
930
* corresponds to \c hann.
932
* Example specifications are \c "blackman" or
933
* \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
935
* Any function that is specified erroneously is silently dropped. Up
936
* to 32 functions are kept, the rest are dropped. If the specification
937
* is empty the encoder defaults to \c "tukey(0.5)".
939
* When more than one function is specified, then for every subframe the
940
* encoder will try each of them separately and choose the window that
941
* results in the smallest compressed subframe.
943
* Note that each function specified causes the encoder to occupy a
944
* floating point array in which to store the window.
946
* \default \c "tukey(0.5)"
947
* \param encoder An encoder instance to set.
948
* \param specification See above.
950
* \code encoder != NULL \endcode
951
* \code specification != NULL \endcode
953
* \c false if the encoder is already initialized, else \c true.
955
FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
501
957
/** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
682
1176
* \code encoder != NULL \endcode
683
1177
* \retval FLAC__bool
684
1178
* \c false if the encoder is already initialized, else \c true.
1179
* \c false if the encoder is already initialized, or if
1180
* \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
686
1182
FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
688
/** Set the write callback.
689
* The supplied function will be called by the encoder anytime there is raw
690
* encoded data ready to write. It may include metadata mixed with encoded
691
* audio frames and the data is not guaranteed to be aligned on frame or
692
* metadata block boundaries.
694
* The only duty of the callback is to write out the \a bytes worth of data
695
* in \a buffer to the current position in the output stream. The arguments
696
* \a samples and \a current_frame are purely informational. If \a samples
697
* is greater than \c 0, then \a current_frame will hold the current frame
698
* number that is being written; otherwise, the write callback is being called
702
* The callback is mandatory and must be set before initialization.
705
* \param encoder An encoder instance to set.
706
* \param value See above.
708
* \code encoder != NULL \endcode
709
* \code value != NULL \endcode
711
* \c false if the encoder is already initialized, else \c true.
713
FLAC_API FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value);
715
/** Set the metadata callback.
716
* The supplied function will be called once at the end of encoding with
717
* the populated STREAMINFO structure. This is so file encoders can seek
718
* back to the beginning of the file and write the STREAMINFO block with
719
* the correct statistics after encoding (like minimum/maximum frame size
720
* and total samples).
723
* The callback is mandatory and must be set before initialization.
726
* \param encoder An encoder instance to set.
727
* \param value See above.
729
* \code encoder != NULL \endcode
730
* \code value != NULL \endcode
732
* \c false if the encoder is already initialized, else \c true.
734
FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value);
736
/** Set the client data to be passed back to callbacks.
737
* This value will be supplied to callbacks in their \a client_data
741
* \param encoder An encoder instance to set.
742
* \param value See above.
744
* \code encoder != NULL \endcode
746
* \c false if the encoder is already initialized, else \c true.
748
FLAC_API FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value);
750
1184
/** Get the current encoder state.
752
1186
* \param encoder An encoder instance to query.
975
1409
FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
977
/** Initialize the encoder instance.
978
* Should be called after FLAC__stream_encoder_new() and
979
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
980
* or FLAC__stream_encoder_process_interleaved(). Will set and return
981
* the encoder state, which will be FLAC__STREAM_ENCODER_OK if
982
* initialization succeeded.
984
* The call to FLAC__stream_encoder_init() currently will also immediately
985
* call the write callback several times, once with the \c fLaC signature,
986
* and once for each encoded metadata block.
988
* \param encoder An uninitialized encoder instance.
990
* \code encoder != NULL \endcode
991
* \retval FLAC__StreamEncoderState
992
* \c FLAC__STREAM_ENCODER_OK if initialization was successful; see
993
* FLAC__StreamEncoderState for the meanings of other return values.
995
FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder);
1411
/** Initialize the encoder instance to encode native FLAC streams.
1413
* This flavor of initialization sets up the encoder to encode to a
1414
* native FLAC stream. I/O is performed via callbacks to the client.
1415
* For encoding to a plain file via filename or open \c FILE*,
1416
* FLAC__stream_encoder_init_file() and FLAC__stream_encoder_init_FILE()
1417
* provide a simpler interface.
1419
* This function should be called after FLAC__stream_encoder_new() and
1420
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1421
* or FLAC__stream_encoder_process_interleaved().
1422
* initialization succeeded.
1424
* The call to FLAC__stream_encoder_init_stream() currently will also
1425
* immediately call the write callback several times, once with the \c fLaC
1426
* signature, and once for each encoded metadata block.
1428
* \param encoder An uninitialized encoder instance.
1429
* \param write_callback See FLAC__StreamEncoderWriteCallback. This
1430
* pointer must not be \c NULL.
1431
* \param seek_callback See FLAC__StreamEncoderSeekCallback. This
1432
* pointer may be \c NULL if seeking is not
1433
* supported. The encoder uses seeking to go back
1434
* and write some some stream statistics to the
1435
* STREAMINFO block; this is recommended but not
1436
* necessary to create a valid FLAC stream. If
1437
* \a seek_callback is not \c NULL then a
1438
* \a tell_callback must also be supplied.
1439
* Alternatively, a dummy seek callback that just
1440
* returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
1441
* may also be supplied, all though this is slightly
1442
* less efficient for the encoder.
1443
* \param tell_callback See FLAC__StreamEncoderTellCallback. This
1444
* pointer may be \c NULL if seeking is not
1445
* supported. If \a seek_callback is \c NULL then
1446
* this argument will be ignored. If
1447
* \a seek_callback is not \c NULL then a
1448
* \a tell_callback must also be supplied.
1449
* Alternatively, a dummy tell callback that just
1450
* returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
1451
* may also be supplied, all though this is slightly
1452
* less efficient for the encoder.
1453
* \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
1454
* pointer may be \c NULL if the callback is not
1455
* desired. If the client provides a seek callback,
1456
* this function is not necessary as the encoder
1457
* will automatically seek back and update the
1458
* STREAMINFO block. It may also be \c NULL if the
1459
* client does not support seeking, since it will
1460
* have no way of going back to update the
1461
* STREAMINFO. However the client can still supply
1462
* a callback if it would like to know the details
1463
* from the STREAMINFO.
1464
* \param client_data This value will be supplied to callbacks in their
1465
* \a client_data argument.
1467
* \code encoder != NULL \endcode
1468
* \retval FLAC__StreamEncoderInitStatus
1469
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1470
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1472
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
1474
/** Initialize the encoder instance to encode Ogg FLAC streams.
1476
* This flavor of initialization sets up the encoder to encode to a FLAC
1477
* stream in an Ogg container. I/O is performed via callbacks to the
1478
* client. For encoding to a plain file via filename or open \c FILE*,
1479
* FLAC__stream_encoder_init_ogg_file() and FLAC__stream_encoder_init_ogg_FILE()
1480
* provide a simpler interface.
1482
* This function should be called after FLAC__stream_encoder_new() and
1483
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1484
* or FLAC__stream_encoder_process_interleaved().
1485
* initialization succeeded.
1487
* The call to FLAC__stream_encoder_init_ogg_stream() currently will also
1488
* immediately call the write callback several times to write the metadata
1491
* \param encoder An uninitialized encoder instance.
1492
* \param read_callback See FLAC__StreamEncoderReadCallback. This
1493
* pointer must not be \c NULL if \a seek_callback
1494
* is non-NULL since they are both needed to be
1495
* able to write data back to the Ogg FLAC stream
1496
* in the post-encode phase.
1497
* \param write_callback See FLAC__StreamEncoderWriteCallback. This
1498
* pointer must not be \c NULL.
1499
* \param seek_callback See FLAC__StreamEncoderSeekCallback. This
1500
* pointer may be \c NULL if seeking is not
1501
* supported. The encoder uses seeking to go back
1502
* and write some some stream statistics to the
1503
* STREAMINFO block; this is recommended but not
1504
* necessary to create a valid FLAC stream. If
1505
* \a seek_callback is not \c NULL then a
1506
* \a tell_callback must also be supplied.
1507
* Alternatively, a dummy seek callback that just
1508
* returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
1509
* may also be supplied, all though this is slightly
1510
* less efficient for the encoder.
1511
* \param tell_callback See FLAC__StreamEncoderTellCallback. This
1512
* pointer may be \c NULL if seeking is not
1513
* supported. If \a seek_callback is \c NULL then
1514
* this argument will be ignored. If
1515
* \a seek_callback is not \c NULL then a
1516
* \a tell_callback must also be supplied.
1517
* Alternatively, a dummy tell callback that just
1518
* returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
1519
* may also be supplied, all though this is slightly
1520
* less efficient for the encoder.
1521
* \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
1522
* pointer may be \c NULL if the callback is not
1523
* desired. If the client provides a seek callback,
1524
* this function is not necessary as the encoder
1525
* will automatically seek back and update the
1526
* STREAMINFO block. It may also be \c NULL if the
1527
* client does not support seeking, since it will
1528
* have no way of going back to update the
1529
* STREAMINFO. However the client can still supply
1530
* a callback if it would like to know the details
1531
* from the STREAMINFO.
1532
* \param client_data This value will be supplied to callbacks in their
1533
* \a client_data argument.
1535
* \code encoder != NULL \endcode
1536
* \retval FLAC__StreamEncoderInitStatus
1537
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1538
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1540
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderReadCallback read_callback, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
1542
/** Initialize the encoder instance to encode native FLAC files.
1544
* This flavor of initialization sets up the encoder to encode to a
1545
* plain native FLAC file. For non-stdio streams, you must use
1546
* FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
1548
* This function should be called after FLAC__stream_encoder_new() and
1549
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1550
* or FLAC__stream_encoder_process_interleaved().
1551
* initialization succeeded.
1553
* \param encoder An uninitialized encoder instance.
1554
* \param file An open file. The file should have been opened
1555
* with mode \c "w+b" and rewound. The file
1556
* becomes owned by the encoder and should not be
1557
* manipulated by the client while encoding.
1558
* Unless \a file is \c stdout, it will be closed
1559
* when FLAC__stream_encoder_finish() is called.
1560
* Note however that a proper SEEKTABLE cannot be
1561
* created when encoding to \c stdout since it is
1563
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1564
* pointer may be \c NULL if the callback is not
1566
* \param client_data This value will be supplied to callbacks in their
1567
* \a client_data argument.
1569
* \code encoder != NULL \endcode
1570
* \code file != NULL \endcode
1571
* \retval FLAC__StreamEncoderInitStatus
1572
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1573
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1575
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1577
/** Initialize the encoder instance to encode Ogg FLAC files.
1579
* This flavor of initialization sets up the encoder to encode to a
1580
* plain Ogg FLAC file. For non-stdio streams, you must use
1581
* FLAC__stream_encoder_init_ogg_stream() and provide callbacks for the I/O.
1583
* This function should be called after FLAC__stream_encoder_new() and
1584
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1585
* or FLAC__stream_encoder_process_interleaved().
1586
* initialization succeeded.
1588
* \param encoder An uninitialized encoder instance.
1589
* \param file An open file. The file should have been opened
1590
* with mode \c "w+b" and rewound. The file
1591
* becomes owned by the encoder and should not be
1592
* manipulated by the client while encoding.
1593
* Unless \a file is \c stdout, it will be closed
1594
* when FLAC__stream_encoder_finish() is called.
1595
* Note however that a proper SEEKTABLE cannot be
1596
* created when encoding to \c stdout since it is
1598
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1599
* pointer may be \c NULL if the callback is not
1601
* \param client_data This value will be supplied to callbacks in their
1602
* \a client_data argument.
1604
* \code encoder != NULL \endcode
1605
* \code file != NULL \endcode
1606
* \retval FLAC__StreamEncoderInitStatus
1607
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1608
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1610
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1612
/** Initialize the encoder instance to encode native FLAC files.
1614
* This flavor of initialization sets up the encoder to encode to a plain
1615
* FLAC file. If POSIX fopen() semantics are not sufficient (for example,
1616
* with Unicode filenames on Windows), you must use
1617
* FLAC__stream_encoder_init_FILE(), or FLAC__stream_encoder_init_stream()
1618
* and provide callbacks for the I/O.
1620
* This function should be called after FLAC__stream_encoder_new() and
1621
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1622
* or FLAC__stream_encoder_process_interleaved().
1623
* initialization succeeded.
1625
* \param encoder An uninitialized encoder instance.
1626
* \param filename The name of the file to encode to. The file will
1627
* be opened with fopen(). Use \c NULL to encode to
1628
* \c stdout. Note however that a proper SEEKTABLE
1629
* cannot be created when encoding to \c stdout since
1630
* it is not seekable.
1631
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1632
* pointer may be \c NULL if the callback is not
1634
* \param client_data This value will be supplied to callbacks in their
1635
* \a client_data argument.
1637
* \code encoder != NULL \endcode
1638
* \retval FLAC__StreamEncoderInitStatus
1639
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1640
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1642
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
1644
/** Initialize the encoder instance to encode Ogg FLAC files.
1646
* This flavor of initialization sets up the encoder to encode to a plain
1647
* Ogg FLAC file. If POSIX fopen() semantics are not sufficient (for example,
1648
* with Unicode filenames on Windows), you must use
1649
* FLAC__stream_encoder_init_ogg_FILE(), or FLAC__stream_encoder_init_ogg_stream()
1650
* and provide callbacks for the I/O.
1652
* This function should be called after FLAC__stream_encoder_new() and
1653
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
1654
* or FLAC__stream_encoder_process_interleaved().
1655
* initialization succeeded.
1657
* \param encoder An uninitialized encoder instance.
1658
* \param filename The name of the file to encode to. The file will
1659
* be opened with fopen(). Use \c NULL to encode to
1660
* \c stdout. Note however that a proper SEEKTABLE
1661
* cannot be created when encoding to \c stdout since
1662
* it is not seekable.
1663
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
1664
* pointer may be \c NULL if the callback is not
1666
* \param client_data This value will be supplied to callbacks in their
1667
* \a client_data argument.
1669
* \code encoder != NULL \endcode
1670
* \retval FLAC__StreamEncoderInitStatus
1671
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
1672
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
1674
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
997
1676
/** Finish the encoding process.
998
1677
* Flushes the encoding buffer, releases resources, resets the encoder
added
removed
include/FLAC/stream_encoder.h
