v0.3.0

Highlights

New: a FLAC encoder. FLACEncoder turns interleaved 4-32 bit PCM in 1-8 channels into native FLAC. It never allocates and never buffers input: each encode() call turns one block into one frame, and all working memory is the ~2.1 KB object plus a few KB of stack.

• Fixed predictors and stereo decorrelation by default (21x realtime for 16-bit stereo on an ESP32-S3).
• Opt-in LPC for streams up to 24 bits, about 7-9% smaller on 16-bit music.
• Opt-in Rice partitioning and an LPC stereo search.
• LPC and Rice partitioning can be compiled out with Kconfig/CMake switches.
• Output is identical on host and ESP32.
• See the README's Encoder sections and examples/encode_benchmark. host_examples/wav_to_flac is a complete encoder program.

Decoder fixes:

• Error and resync paths: bytes_consumed is now set on frame-header errors, plus three frame-decoder fixes.
• Zero-length metadata blocks are skipped.
• uint8_t* output is little-endian on big-endian hosts.
• FLACDecoder is about 100 bytes smaller.

The ESP-IDF component package no longer ships the benchmarks' test audio: 0.2 MB instead of 13 MB.

Behaviour changes

• decode() returns the new FLAC_DECODER_ERROR_INVALID_ARGUMENT (-21) for a null input, even when input_len is 0. v0.2.0 returned FLAC_DECODER_NEED_MORE_DATA for that.
• decode() also returns -21 for a null output after HEADER_READY, where v0.2.0 returned FLAC_DECODER_ERROR_OUTPUT_TOO_SMALL (-17).
• Both decode() overloads are marked must-use ([[nodiscard]], or warn_unused_result before C++17), so callers that ignore the result now get a warning (an error under -Werror).

What's Changed

• Exclude the examples' files from the ESP-IDF component package (#59) @kahrendt
• Refresh the docs and benchmark numbers for v0.3.0 (#58) @kahrendt
• Settle the encoder API before v0.3.0 (#57) @kahrendt
• Pass the App token to release-drafter through its token input (#56) @kahrendt
• Bias 4-7 bit streams to unsigned in flac_to_wav's WAV output (#55) @kahrendt
• Keep packed PCM little-endian on big-endian hosts (#54) @kahrendt
• Split subframe coding and Rice partitioning out of flac_encoder.cpp (#53) @kahrendt
• Add 25-32 bit encoding with fixed predictors (#52) @kahrendt
• Harden the host examples' output handling and the decoder test's WAV reader (#48) @kahrendt
• Add the ESP32 encode benchmark (#46) @kahrendt
• Add the encoder's LPC stereo search (#45) @kahrendt
• Add opt-in LPC subframes to the encoder (#44) @kahrendt
• Add opt-in Rice partitioning to the encoder (#43) @kahrendt
• Add the wav_to_flac example and the encoder round-trip suite (#42) @kahrendt
• Add an MSB-first bit writer for the encoder (#40) @kahrendt
• Add a FLAC encoder with fixed predictors (#41) @kahrendt
• Gather the decoder's RFC 9639 constants in flac_format.h (#39) @kahrendt
• Pass the macOS SDK to clang-include-cleaner in check_includes.py (#38) @kahrendt
• Move the ESP-IDF examples' sources from src/ to main/ (#37) @kahrendt
• Use GitHub App client-id for release-drafter token minting (#35) @jesserockz
• IDF component packaging and host tool cleanup (#30) @kahrendt
• Skip zero-length metadata blocks during header parsing (#29) @kahrendt
• Ci/static analysis tooling (#28) @kahrendt
• Three small bugfixes to the frame decoder's error/resync paths (#27) @kahrendt
• Bump microOggDemuxer to v1.2.1 (#26) @kahrendt
• Guards against nullptr input and output buffers (#22) @kahrendt
• CI workflow hardening (#13) @kahrendt
• Add badge showing Espressif component registry status (#12) @kahrendt
• add libFuzzer harness for the FLAC decoder (#11) @kahrendt
• fix(decoder): set bytes_consumed on frame-header error returns (#10) @kahrendt
• Tidy up code comments (#9) @kahrendt
• perf(decoder): shrink FLACDecoder ~100 bytes (int16_t coefs + lazy metadata) (#8) @teancom, @claude

Dependencies

17 changes

• Bump release-drafter/release-drafter from 7.7.0 to 7.10.0 (#51) @dependabot[bot]
• Bump actions/download-artifact from 8.0.1 to 8.0.2 (#50) @dependabot[bot]
• Bump actions/upload-artifact from 7.0.1 to 7.0.2 (#49) @dependabot[bot]
• Bump actions/setup-python from 6.3.0 to 7.0.0 (#31) @dependabot[bot]
• Bump actions/checkout from 7.0.0 to 7.0.1 (#33) @dependabot[bot]
• Bump release-drafter/release-drafter from 7.5.1 to 7.7.0 (#34) @dependabot[bot]
• Bump release-drafter/release-drafter from 7.4.0 to 7.5.1 (#25) @dependabot[bot]
• Bump actions/setup-python from 6.2.0 to 6.3.0 (#23) @dependabot[bot]
• Bump actions/cache from 5.0.5 to 6.1.0 (#24) @dependabot[bot]
• Configure dependabot like sister projects (#21) @kahrendt
• Pin clang-tidy-18 in the CI (#20) @kahrendt
• Bump actions/checkout from 6.0.2 to 7.0.0 (#19) @dependabot[bot]
• Bump release-drafter/release-drafter from 7.0.0 to 7.4.0 (#15) @dependabot[bot]
• Bump actions/upload-artifact from 4.6.2 to 7.0.1 (#16) @dependabot[bot]
• Bump actions/create-github-app-token from 3.0.0 to 3.2.0 (#17) @dependabot[bot]
• Bump actions/download-artifact from 4.2.1 to 8.0.1 (#18) @dependabot[bot]
• Bump actions/cache from 5.0.3 to 5.0.5 (#14) @dependabot[bot]

Full Changelog: v0.2.0...v0.3.0