Porting from FLAC 1.3.4 to 1.4.0
Porting Guide for New Versions

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.

Copyright (c) 2000-2009 Josh Coalson Copyright (c) 2011-2022 Xiph.Org Foundation