From 05ff5692660fb9c7907a1fa62b7def88e34a17be Mon Sep 17 00:00:00 2001 From: Martijn van Beurden Date: Tue, 19 Jul 2022 20:07:44 +0200 Subject: Finish porting guide --- include/FLAC/all.h | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) (limited to 'include/FLAC/all.h') diff --git a/include/FLAC/all.h b/include/FLAC/all.h index 71ddd3c6..ee6e132c 100644 --- a/include/FLAC/all.h +++ b/include/FLAC/all.h @@ -369,12 +369,8 @@ * - the function get_client_data_from_decoder has been renamed to * FLAC__get_decoder_client_data * - some data types in the FLAC__Frame struct have changed - * - the C functions FLAC__stream_encoder_init_file, - * FLAC__stream_encoder_init_ogg_file, FLAC__stream_decoder_init_file - * and FLAC__stream_decoder_init_ogg_file and the C++ ::init and - * ::init_ogg class member functions of both the encoder and decoder - * now take UTF-8 encoded filenames on Windows instead of filenames in - * the current codepage + * - all functions accepting a filename now take UTF-8 encoded filenames + * on Windows instead of filenames in the current codepage * * Furthermore, there have been the following additions * - the functions FLAC__stream_encoder_set_limit_min_bitrate, @@ -388,7 +384,8 @@ * * The function \b get_client_data_from_decoder was added in FLAC 1.3.3 * but did not follow the API naming convention and was not properly - * exported. The function is now renamed and properly integrated + * exported. The function is now renamed and properly integrated as + * FLAC__stream_decoder_get_client_data * * To accomodate encoding and decoding 32-bit int PCM, some data types * in the \b FLAC__frame struct were changed. Specifically, warmup @@ -401,9 +398,29 @@ * data_type, which clarifies whether the FLAC__int32 or FLAC__int64 * array is in use. * - * The last breaking change is that filenames in FLAC and FLAC++ encoder - * and decoder must now have the UTF-8 character encoding instead of - * using the current code page. + * The last breaking change is that all API functions taking a filename + * as an argument now, on Windows, must be supplied with that filename + * in the UTF-8 character encoding instead of using the current code + * page. libFLAC internally translates these UTF-8 encoded filenames to + * an appropriate representation to use with _wfopen. On all other + * systems, filename is passed to fopen without any translation, as it + * in libFLAC 1.3.4 and earlier. + * + * \section porting_1_3_4_to_1_4_0_additions Additions + * + * To aid in creating properly streamable FLAC files, a set of functions + * was added to make it possible to enfore a minimum bitrate to files + * created through libFLAC's stream_encoder.h interface. With this + * function enabled the resulting FLAC files have a minimum bitrate of + * 1bit/sample independent of the number of channels, i.e. 48kbit/s for + * 48kHz. This can be beneficial for streaming, as very low bitrates for + * silent sections compressed with 'constant' subframes can result in a + * bitrate of 1kbit/s, creating problems with clients that aren't aware + * of this possibility and buffer too much data. + * + * Finally, FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA was added to + * the FLAC__StreamDecoderErrorStatus enum to signal that the decoder + * encountered unreadable metadata. * */ -- cgit v1.2.1