v3.1.0 - Maintenance release

What's Changed

• CMake will try to find the library itself, instead of using a js script for it. Preference will stay the same. To force compiling from sources, use USE_FLAC_SOURCES option.
• Drop support for node 14. 16 will stay for a while, even though has not official support anymore.
• Bring back support for CJS. Support may not work as expected from v2 series. Ensure to use require('flac-bindings'), no other path is supported. I won't properly support CJS as I don't use for anything, but this was requested from several people ... (see #43 )
• Update to libflac 1.4.3

Full Changelog: v3.0.1...v3.1.0

v3.0.1 - Updated bundled libflac

This release just contains an updated libflac for rebuild packages and cmake-js for those who need to build their own package from source (specially for Windows, which has some improvements).

Deprecation note: The v3.1.0 will drop support to node 14 series!

Full Changelog: v3.0.0...v3.0.1

v3.0.0 - ESM and Builder pattern

Breaking changes

Native encoder API split

The native encoder API is now split into EncoderBuilder and Encoder, following the builder pattern. To create an encoder, use new EncoderBuilder() and build using one of the build methods.

This change is to ensure that set methods can only be called before initialising the encoder, and to avoid using async methods when initialised with non-async version (or viceversa).

Native decoder API split

The native decoder API is now split into DecoderBuilder and Decoder, following the builder pattern. To create a decoder, use new DecoderBuilder() and build using one of the build methods.

This change is to ensure that set methods can only be called before initialising the decoder, and to avoid using async methods when initialised with non-async version (or viceversa).

ESM module

This module is now ESM only. See https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c.

Older node versions

Dropped support for node v10 and v12. N-API version is 8.

Technically, you can use this package in node 12, but no support will be given.

Updated install script

To remove outdated package prebuild, I made a custom script that does whatever I need in order to download the pre-built package from github or to build the package locally. It has been tested under certain scenarios on macOS/Linux, but Windows is not well tested.

Raise an issue if there are problems regarding this install script.

Pre built packages

• Removed packages for arm32v7 on Linux.
• Added arm64 package for macOS.
• Added x86 package for Windows.

Notable Changes

• Enabled LTO.
• Migrate to ESM.
• Split native Encoder into EncoderBuilder and Encoder.
• Split native Decoder into DecoderBuilder and Decoder.
• Replace prebuild with custom script (windows untested, it may not work).
• StreamDecoder and FileDecoder streams will not error when flac error is emitted.
• Update libFLAC to 1.4.1.

Full Changelog: v2.7.0...v3.0.0

StreamDecoder and FileDecoder fixes on error event emitted

This release includes a fix that prevents the StreamDecoder and FileDecoder to destroy themselves when the decoder emits an error. The errors are now emitted as flac-error event. The decoding process will continue unless the decoder finds it cannot continue (fatal error). Related issue #40 .

Update FLAC library with fixes

This version updates the bundled FLAC library in provided native add-on files to fix some crashes and mainly the UTF-8 path support for Windows (see #37).

Bug fixes, improvements and Node-API 8

Improvements

• Changed memory handling in C++ code (improves safety and could improve performance a bit).
• Moved audio transformation code to C++ to improve performance.
• Improved metadata types in functions and methods (TypeScript) so the right instance can be automatically casted with the right if condition.
• StreamDecoder and FileDecoder now emits format which tells some information about the audio format inside the stream/file. This information can be read from another stream when piped (like in speaker package) to automatically configure itself.
• StreamEncoder and FileEncoder now understands format event from source stream when piped. This information is used to configure the encoder automatically (if some of the values are provided already, they will be overridden by the event). Can be helpful when paired with a source stream like wav's Reader.
• Changes Node-API v7 to v8 (affects node 12 & 14 series).
• Supports node 16

Bug fixes

• Properly handle exceptions when resolving promises of async methods. Previously, if an exception was thrown when resolving the promise in C++, the promise left unresolved indefinitely and the exception was lost. Now is handled properly and the promise rejects.
• FileDecoder could retry a read if it failed, throwing two or more times the same error.
• Avoid garbage noise under some circumstances when using StreamEncoder or FileEncoder.
• Updated error handling in StreamDecoder, FileDecoder, StreamEncoder and FileEncoder so errors are not lost.

Possible breaking changes

• All init functions now throws instead of returning status. The migration path is not to check the returned value in the init function and use a try/catch block if error handling is required.
• Moved StreamDecoder and FileDecoder into a decoder module, and split implementations inside their own modules (decoder/stream-decoder and decoder/file-decoder).
• Moved StreamEncoder and FileEncoder into a encoder module, and split implementations inside their own modules (encoder/stream-encoder and encoder/file-encoder).
• StreamDecoder and FileDecoder now by default the outputAs32 will be always false (previously was set to true if the flac was 24 bit).
• StreamEncoder and FileEncoder now by default the inputAs32 will be always false (previously was set to true if the input was 24 bit).

Refactor buffer references (support for node.js 14.x)

• [Possible breaking change] Refactored Buffer usage from C++ to JS due to change in Node 14.0.0 release (see #25 ). If your code uses a Buffer from api.Encoder, api.Decoder or api.Chain IO Callbacks outside the callback instead of having some undefined data inside the buffer, will now get an empty buffer or even an exception (depends on node). These buffers have always been only valid inside the callback scope, but now this is enforced using detach on Buffers. This only affects recent node v12.x and v14.x and higher (napi v7).
• Added support for node v14.x and higher (see above for possible issues).
• Dropped napi v4 support. Ensure to have a recent node v10.x version.
• Added support to compilation for Android.
• Added getPosition() for StreamDecoder and FileDecoder. If the file has the total samples specified, this method will return an object with some properties that will help you getting a nice progress bar. Properties are:

  interface FlacDecoderPosition {
         /** Position where the decoding is at, in samples */
         position: number;
         /** Total samples (if flac provides it) */
         totalSamples: number;
         /** Value between 0 and 1 that represents the percentage of samples decoded (or NaN if there is no total samples) */
         percentage: number;
         /** Total seconds (if flac provides it) */
         totalSeconds: number;
         /** Current position in seconds */
         currentSeconds: number;
   }

• Added getOutputBitsPerSample() for StreamDecoder and FileDecoder. This property tells the output bits per sample, which can be different from getBitsPerSample() in some scenarios.
• Checkout the examples under examples folder !!

Internal improvements

This release contains several internal improvements to make the package be more stable and faster, as well as fixing one bug.

• 878fc50: Improve decoding speed by avoiding some memory copies and telling the size of arrays beforehand in Frame. These changes made decoding to be a bit faster (like 7% faster in local tests).
• 3d48b1e: If Ogg is not supported, constructors for the node.js streams will throw an exception (if ogg is requested).
• cf894ba: Removed internal async_context for several places and refactored mutex locks in encoder and decoder.
• 288b350: Move all internal constructors (C++ code) into NativeAddon instance.
• ce03102: If StreamEncoder, FileEncoder or StreamDecoder were finished without writing anything, an exception was thrown #22
• b8f26e2: Added debug logs for debugging.

New debug logs for investigating issues

There are new debug logs for the node.js streams that will help you (or me) track down issues in the stream implementations. The logs are enabled by filling the environment variable DEBUG with flac:* or more specific namespaces like flac:encoder:* or flac:decoder:stream (see readme for all namespaces). Uses debug package to achieve this.

These logs can be very helpful when filling issues :)

StreamDecoder fixes

This release includes a bug fix of the StreamDecoder ( see #18 ) that can abort a decoding process if the data needed to continue with the decoding is not enough. Also includes a fix for a crash when the decoder calls the error callback.

Fix prebuilt download

Previous version had an error while downloading the prebuilt node package, this should fix the issue.