diff options
author | Martijn van Beurden <mvanb1@gmail.com> | 2022-07-19 20:07:44 +0200 |
---|---|---|
committer | Martijn van Beurden <mvanb1@gmail.com> | 2022-07-27 22:16:04 +0200 |
commit | 05ff5692660fb9c7907a1fa62b7def88e34a17be (patch) | |
tree | 1ce4a440a6e594b594017f3bf38f9c9b54a7281d /include | |
parent | 42201ae5750273fea41ad30a3ddfadcef52fa103 (diff) | |
download | flac-05ff5692660fb9c7907a1fa62b7def88e34a17be.tar.gz |
Finish porting guide
Diffstat (limited to 'include')
-rw-r--r-- | include/FLAC/all.h | 37 | ||||
-rw-r--r-- | include/FLAC/metadata.h | 20 | ||||
-rw-r--r-- | include/FLAC/stream_decoder.h | 10 | ||||
-rw-r--r-- | include/FLAC/stream_encoder.h | 10 |
4 files changed, 59 insertions, 18 deletions
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. * */ diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index 265f336b..aa369054 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -134,6 +134,11 @@ extern "C" { * STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring * only a filename. * + * On Windows, filename must be a UTF-8 encoded filename, which libFLAC + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. + * * They try to skip any ID3v2 tag at the head of the file. * * \{ @@ -387,6 +392,11 @@ FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_stat /** Initialize the iterator to point to the first metadata block in the * given FLAC file. * + * On Windows, filename must be a UTF-8 encoded filename, which libFLAC + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. + * * \param iterator A pointer to an existing iterator. * \param filename The path to the FLAC file. * \param read_only If \c true, the FLAC file will be opened @@ -820,6 +830,11 @@ FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_C /** Read all metadata from a FLAC file into the chain. * + * On Windows, filename must be a UTF-8 encoded filename, which libFLAC + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. + * * \param chain A pointer to an existing chain. * \param filename The path to the FLAC file to read. * \assert @@ -834,6 +849,11 @@ FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const /** Read all metadata from an Ogg FLAC file into the chain. * + * On Windows, filename must be a UTF-8 encoded filename, which libFLAC + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. + * * \note Ogg FLAC metadata data writing is not supported yet and * FLAC__metadata_chain_write() will fail. * diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index 02779c4c..2d285aec 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -1285,8 +1285,9 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE( * and provide callbacks for the I/O. * * On Windows, filename must be a UTF-8 encoded filename, which libFLAC - * internally translates to a appropriate representation to use with - * _wfopen + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. * * This function should be called after FLAC__stream_decoder_new() and * FLAC__stream_decoder_set_*() but before any of the @@ -1330,8 +1331,9 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file( * and provide callbacks for the I/O. * * On Windows, filename must be a UTF-8 encoded filename, which libFLAC - * internally translates to a appropriate representation to use with - * _wfopen + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. * * This function should be called after FLAC__stream_decoder_new() and * FLAC__stream_decoder_set_*() but before any of the diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index d775d0c3..a39d0ed2 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -1662,8 +1662,9 @@ FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__ * and provide callbacks for the I/O. * * On Windows, filename must be a UTF-8 encoded filename, which libFLAC - * internally translates to a appropriate representation to use with - * _wfopen + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. * * This function should be called after FLAC__stream_encoder_new() and * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process() @@ -1697,8 +1698,9 @@ FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__Stre * and provide callbacks for the I/O. * * On Windows, filename must be a UTF-8 encoded filename, which libFLAC - * internally translates to a appropriate representation to use with - * _wfopen + * internally translates to an appropriate representation to use with + * _wfopen. On all other systems, filename is passed to fopen without + * any translation. * * This function should be called after FLAC__stream_encoder_new() and * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process() |