Lightweight and fast Node.js addon for playing notification sounds, beeps, and alarms using MiniAudio.

Lightweight and fast Node.js addon for playing notification sounds, beeps, and alarms using MiniAudio.

Lightweight and fast Node.js addon for playing notification sounds, beeps, and alarms using MiniAudio.

• 🔊 Minimal and low-latency audio playback.
• 🎵 Supports common formats like WAV, MP3, and more.
• ⚙️ Native addon built with node-addon-api and MiniAudio.
• 🚀 Prebuilt binaries via node-pre-gyp.
• 🧱 Cross-platform compatible (tested on Windows 11).

npm install @thesusheer/node-miniaudio

If a prebuilt binary isn't available for your platform, it will automatically attempt to build from source.

• ✅ Node.js v20.18.2
• ✅ Electron v35.x.x
• ✅ Windows 11

❗ Not yet tested on macOS or Linux — contributions and compatibility reports welcome.

const { playAudio } = require('@thesusheer/node-miniaudio');

playAudio('./alert.wav', (message) => {
  console.log('Playback complete:', message);
});

Plays an audio file asynchronously.

• filePath – Path to the audio file (WAV, MP3, etc.).
• callback – Function called after playback ends with a message.

• A string indicating playback started.

Includes built-in .d.ts declarations for full autocompletion and type safety:

import { playAudio, AudioPlaybackCallback } from '@thesusheer/node-miniaudio';

const onDone: AudioPlaybackCallback = (msg) => console.log('Done:', msg);
playAudio('sound.mp3', onDone);

This addon uses Node-API (N-API) to provide ABI stability across Node.js versions. In most cases, you do not need to rebuild the module when upgrading Node.js or Electron.

• A prebuilt binary is not available for your platform or runtime.
• You upgrade to a new major version of Electron or Node that isn’t yet supported.
• You encounter unexpected runtime errors.

npm rebuild @thesusheer/node-miniaudio
# or
node-gyp rebuild

Rebuild is handled automatically by node-gyp during install if needed.

• Native binding: node_miniaudio.cpp
• Entry point: lib/index.js
• Type definitions: types/index.d.ts
• Build config: binding.gyp
• Prebuild handling: node-pre-gyp + node-pre-gyp-github

Contributions are welcome! Whether it’s:

• Improving support for macOS or Linux
• Adding features or playback options
• Reporting and fixing bugs
• Enhancing the documentation

You're encouraged to fork the repo and open a pull request.

👉 Open an Issue
👉 Submit a PR

BSD License

Sudheer Gupta
GitHub
📧 sudheergupta0508@gmail.com

• MiniAudio Library
• npm Package
• GitHub Repo