@echogarden/audio-io
v0.0.3Echogarden Audio I/O
A Node.js package that provides low-level audio outputs (audio inputs are not implemented yet) for common audio APIs, on various platforms:
- MME (Multimedia Extensions) (Wave Out) on Windows x64
- Core Audio (via low-latency Audio Units) on macOS for both Intel x64 and Apple Silicon (ARM64)
- ALSA (Advanced Linux Sound Architecture) on Linux x64
The code is very minimalistic and doesn't rely on any external libraries, only direct system calls.
For each platform, there's a single, independent cpp
source file, which uses the Node Addon API (C++) to produce a Node.js addon that integrates with the Node.js runtime for the given platform.
The addons are distributed as precompiled binaries only, which means the package doesn't require any build tools or build-time postprocessing to install. It also does not rely on node-gyp
or any other form of intermediate build tools, like MAKE or CMAKE.
Installation
npm install @echogarden/audio-io
Usage example
Notes:
- Only audio outputs are supported at this time. Audio inputs will be added in the future
- Only 16-bit, signed integer, little-endian, interleaved buffers are currently supported. Ensure the audio data is converted to this format before passing it to the handler
// Import module
import { initAudioOutput } from '@echogarden/audio-io'
// Define an audio output handler function
function audioOutputHandler(outputBuffer: Int16Array) {
// Write 16-bit signed integer little-endian samples to `outputBuffer`.
// If there are multiple channels, interleave them, like `LRLRLRLR..` for stereo.
}
// Initialize audio output, passing a configuration object and the handler
const audioOutput = await initAudioOutput({
sampleRate: 44100, // Sample rate in Hz, should be an integer like 44100, 22050, 8000
channelCount: 2, // Channel count, likely 1 (mono), or 2 (stereo)
bufferDuration: 100.0, // Target buffer duration, in milliseconds. Defaults to 100.0
}, audioOutputHandler)
// ...
// When done, call audioOutput.dispose(),
// which will close the audio output and free any associated memory or handles.
await audioOutput.dispose()
Notes on bufferDuration
:
- On MME (Windows) and ALSA (Linux)
bufferDuration
will be used to directly compute the buffer size - On Core Audio (macOS), it will be used to set the maximum buffer size, but the actual buffer size selected by the driver may be significantly smaller
Compiling the addons
The library uses precompiled binaries only.
If you want to compile yourself, for a modification or a fork, then:
addons/windows-mme
directory includes abuild.cmd
file that will build a.node
addon usingg++
on Windows, as well as itsnode_api.lib
prerequisiteaddons/macos-coreaudio
directory includes abuild.sh
file that will build.node
addons usingclang++
on macOS, for bothx86-64
andarm64
targetsaddons/linux-alsa
directory includes abuild.sh
file that will build a.node
addon usingg++
on Linux (requires the ALSA header files to be installed globally - on Ubuntu you can usesudo apt install libasound2-dev
)
Still experimental, feedback is needed
All code was written from scratch, meaning it hasn't been tested on a large variety of systems yet:
- Windows addon has only been tested on Windows 11
- Linux addon has only been tested in WSL2 (Ubuntu 24.04) and an Ubuntu 23.10 VM in VirtualBox
- macOS addon has only been tested in a macOS 13 VM in VMWare
If you encounter any crashes, unexpected errors, or audio problems, like distortions or artifacts, it's likely they can be solved relatively easily. Just open an issue and let me know about it.
Future
- Audio inputs would be implemented once audio outputs are sufficiently stabilized and tested
- Add option to select an audio output device other than the default one
- Add optional lower latency I/O on Windows via the WASAPI API (supported on Windows Vista or newer)
License
MIT