A lightweight, cross-platform keybind-based soundboard system built with Node.js. Map keyboard shortcuts to audio files for gaming, streaming, presentations, or just for fun.
🎵 Community-Driven: Contribute your sounds and configurations! Help build the ultimate soundboard collection.
Looking for an easy first contribution? You're in the right place! This project was specifically designed to welcome beginners and provide a meaningful contribution experience.
- ✅ Beginner-Friendly - No complex algorithms or deep technical knowledge required
- 🎵 Fun & Creative - Add your favorite sound effects and memes
- 📦 Real Impact - Your contribution becomes part of a published npm package used by real users
- 🚀 Learn Git & GitHub - Practice the full contribution workflow in a supportive environment
- 🏆 Build Your Portfolio - Get your name in the contributors list of a public package
- ⚡ Quick Approval - Most PRs reviewed and merged within 24 hours
- Add Sound Effects (5 minutes)
- Drop an MP3 file in
assets/sounds/with a kebab-case name
- Drop an MP3 file in
- Create or Update Configs (10 minutes)
- Share your custom keybind setup in
src/configs/
- Share your custom keybind setup in
- Improve Docs (15 minutes)
- Fix typos, add examples, or clarify instructions
- Share Ideas (5 minutes)
- Suggest new sounds, configs, or features
Your first PR gets you:
- 🎖️ Listed as a contributor
- 📦 Your contribution in the next npm release
- 🌟 Hacktoberfest credit (if participating)
👉 Ready to start? Check out our good first issues or read CONTRIBUTING.md for step-by-step instructions!
- 🎹 Global Hotkeys - Works even when the application isn't focused
- 🔊 MP3 Audio Support - Universal format for all platforms
- ⚡ Hot Reload - Automatically reloads configuration when files change
- 🛑 Stop Others - Stop all playing sounds before playing a new one
- 🖥️ Cross-Platform - Windows, macOS, and Linux support
- 📝 YAML Configuration - Human-readable configuration files
- 📊 File Logging - Optional file-based logging with daily rotation
# Install globally
npm install -g soundbind
# Or use with npx (no installation needed)
npx soundbind# Install as a dependency
npm install soundbind
# Or install from source
git clone https://github.com/UselessCo/soundbind.git
cd soundbind
npm installSoundbind comes with pre-configured setups and sounds:
# Install globally
npm install -g soundbind
# Copy example config to your directory
cp $(npm root -g)/soundbind/src/configs/default.yaml ./soundbind.yaml
# Run it!
soundbindIncluded configs:
default.yaml- Basic setup with example soundstemplate.yaml- Comprehensive template with all options
- Create a
soundbind.yamlconfiguration file in your project directory:
keybinds:
- key: '1'
sound: './node_modules/soundbind/assets/sounds/danca-gatinho.mp3'
description: 'Danca gatinho'
- key: '2'
sound: './node_modules/soundbind/assets/sounds/oloquinho.mp3'
description: 'Oloquinho'
# Or use your own sounds
- key: 'F1'
sound: './my-sounds/custom.mp3'
description: 'My custom sound'
audio:
player: 'play' # Recommended for Linux
maxConcurrent: 5
logging:
level: 'info'
fileEnabled: true
filePath: 'logs'-
Sounds are included in the package! Or add your own to a
my-sounds/directory -
Run Soundbind:
# If installed globally
soundbind
# With npx
npx soundbind
# With custom config path
soundbind ./my-config.yaml
# From source
npm startInstall SoX with MP3 support:
sudo apt install sox libsox-fmt-mp3 # Ubuntu/DebianAudio should work out of the box with the default system player.
You can also use Soundbind as a library in your Node.js projects:
import Soundbind from 'soundbind';
const soundbind = new Soundbind();
await soundbind.start('./soundbind.yaml');
// Play a sound manually
await soundbind.playSound('./sounds/beep.mp3');
// Stop all sounds
await soundbind.stop();See template.yaml in the repository for a complete configuration example with all available options and supported key combinations.
- Letters: a-z
- Numbers: 0-9
- Function Keys: F1-F12
- Numpad: numpad0-numpad9
- Modifiers: ctrl, shift, alt + any key
- Special: space, enter, escape, tab
stopOthers: true/false - Stop other sounds before playingdescription: Human-readable description
level: debug, info, warn, error - Log verbosityfileEnabled: true/false - Enable file loggingfilePath: Directory path for log files
Planned features for future releases:
- 🔄 Loop Support - Continuous sound playback
- 🎛️ Volume Control - Individual and master volume settings
- 🎶 Audio Fading - Fade in/out effects
- 🎯 Priority System - Sound priority management
- ⏱️ Delayed Playback - Schedule sounds with delay
- 🔊 Output Device Selection - Choose specific audio output
- 📡 System Tray - Minimize to system tray
- Node.js 14.0.0 or higher
- Linux: SoX with MP3 support (recommended)
🎵 We love contributions! Especially:
- New Sounds: Add your favorite sound effects to
assets/sounds/ - Configurations: Share your keybind setups in
src/configs/ - Bug Fixes: Help improve stability
- Features: Implement items from the Future Features list
See CONTRIBUTING.md for detailed guidelines.
- Fork the repository
- Add your sounds to
assets/sounds/or configs tosrc/configs/ - Test your changes
- Submit a Pull Request with description
Sound Guidelines:
- Format: MP3 only (for Windows compatibility)
- Size: Under 500KB preferred
- Quality: 128-192 kbps recommended
- Naming: descriptive-name.mp3
- License: Only submit sounds you have rights to use
This is an open-source project. Sound files and configurations are community-contributed and subject to the MIT License. Contributors represent that they have necessary rights to submit content. See DISCLAIMER.md for full details.
MIT License - see LICENSE for details.