FLAC: Porting from FLAC 1.3.4 to 1.4.0

FLAC 1.4.2 Free Lossless Audio Codec

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