$ npm install @qvac/decoder-audioThis decoder library leverages FFmpeg for efficient audio decoding. It simplifies processing of input audio, particularly as a preprocessing step for other addons.
| Platform | Architecture | Min Version | Status | GPU Support |
|---|---|---|---|---|
| macOS | arm64, x64 | 14.0+ | ✅ Tier 1 | N/A (CPU only) |
| iOS | arm64 | 17.0+ | ✅ Tier 1 | N/A (CPU only) |
| Linux | arm64, x64 | Ubuntu-22+ | ✅ Tier 1 | N/A (CPU only) |
| Android | arm64 | 12+ | ✅ Tier 1 | N/A (CPU only) |
| Windows | x64 | 10+ | ✅ Tier 1 | N/A (CPU only) |
Dependencies:
Ensure that the Bare Runtime is installed globally on your system. If it's not already installed, you can add it using:
npm install -g bare@latest
Install the latest version of the decoder addon with the following command:
npm install @qvac/decoder-audio@latest
This library provides a simple workflow for decoding audio streams.
To get started, import the decoder and create an instance:
const { FFmpegDecoder } = require('@qvac/decoder-audio')
const decoder = new FFmpegDecoder({
config: {
audioFormat: 's16le', // 's16le' | 'f32le'; default is 's16le'
sampleRate: 16000 // in Hz; default is 16000
}
})
The config object accepts the following parameters:
audioFormat: Specifies the output format of the decoded audio. Supported values:
's16le': Signed 16-bit little-endian PCM — a widely used raw format.'f32le': 32-bit floating-point little-endian PCM — ideal for high-precision audio processing.Default: 's16le'.
sampleRate: Sample rate of the output audio in Hertz (Hz).
Default: 16000 (16 kHz), commonly used for speech processing.
Initializes and activates the decoder with the provided or default configuration. This method must be called before decoding any audio input.
try {
await decoder.load()
} catch (err) {
console.error('Failed to load decoder:', err)
}
In order to decode audio, we must create an audio stream and pass it to the run() method. This method returns a QVACResponse object.
const fs = require('bare-fs')
const audioFilePath = './sample.ogg'
const audioStream = fs.createReadStream(audioFilePath)
const response = await decoder.run(audioStream)
The response supports real-time updates via .onUpdate(). Each update delivers a chunk of decoded audio data, which can be processed or saved as needed:
await response
.onUpdate(output => {
// `output.outputArray` is a Uint8Array
console.log('Decoded chunk:', new Uint8Array(output.outputArray))
})
.await() // wait for the stream to finish
You can append or otherwise process these frames as needed.
Always unload the decoder when done to free memory:
try {
await decoder.unload()
} catch (err) {
console.error('Failed to unload decoder:', err)
}
The following example demonstrates how to use the decoder to decode a sample OGG file into a raw audio file. Follow these steps, to run the example:
mkdir decoder-example
cd decoder-example
npm init -y
npm install bare-fs @qvac/decoder-audio
example.js and paste the following code:'use strict'
const fs = require('bare-fs')
const { FFmpegDecoder } = require('@qvac/decoder-audio')
const audioFilePath = './path/to/audio/file.ogg'
const outputFilePath = './path/to/output/file.raw'
async function main () {
const decoder = new FFmpegDecoder({
config: {
audioFormat: 's16le',
sampleRate: 16000
}
})
try {
await decoder.load()
const audioStream = fs.createReadStream(audioFilePath)
const response = await decoder.run(audioStream)
const decodedFileBuffer = []
await response
.onUpdate(output => {
const bytes = new Uint8Array(output.outputArray)
decodedFileBuffer.push(bytes)
})
.onFinish(() => {
fs.writeFileSync(outputFilePath, Buffer.concat(decodedFileBuffer))
console.log('Decoded file saved to', outputFilePath)
})
.await()
} finally {
await decoder.unload()
}
}
main().catch(console.error)
Make sure to set the correct audioFilePath and outputFilePath before running the example with the following command:
bare example.js
To run unit tests (using the 'brittle-bare' runner):
npm run test:unit
To generate a unit test coverage report (using 'brittle' and 'istanbul'):
npm run coverage:unit
Or simply:
npm run coverage
Coverage reports are generated in the 'coverage/unit/' directory. Open the corresponding index.html file in your browser to view the detailed report.
This project is licensed under the Apache-2.0 License – see the LICENSE file for details.
For questions or issues, please open an issue on the GitHub repository.