Porting from FLAC 1.3.4 to 1.4.0

This module describes porting from FLAC 1.3.4 to FLAC 1.4.0.

Summary

Between FLAC 1.3.4 and FLAC 1.4.0, there have four breaking changes

• 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
• all functions resizing metadata blocks now return the object untouched if memory allocation fails, whereas previously the handling varied and was more or less undefined
• 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, FLAC__stream_encoder_get_limit_min_bitrate, FLAC::encoder::file::set_limit_min_bitrate() and FLAC::encoder::file::get_limit_min_bitrate() have been added
• Added FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA to the FLAC__StreamDecoderErrorStatus enum

Breaking changes

The function 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 as FLAC__stream_decoder_get_client_data

To accomodate encoding and decoding 32-bit int PCM, some data types in the FLAC__frame struct were changed. Specifically, warmup in both the FLAC__Subframe_Fixed struc and the FLAC__Subframe_LPC struct is changed from FLAC__int32 to FLAC__int64. Also, value in the FLAC__Subframe_Constant is changed from FLAC__int32 to FLAC__int64. Finally, in FLAC__Subframe_Verbatim struct data is changes from a FLAC__int32 array to a union containing a FLAC__int32 array and a FLAC__int64 array. Also, a new member is added, data_type, which clarifies whether the FLAC__int32 or FLAC__int64 array is in use.

Furthermore, the following functions now return the object untouched if memory allocation fails, whereas previously the handling varied and was more or less undefined

• FLAC__metadata_object_seektable_resize_points
• FLAC__metadata_object_vorbiscomment_resize_comments
• FLAC__metadata_object_cuesheet_track_resize_indices
• FLAC__metadata_object_cuesheet_resize_tracks

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.

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.