Soundbind

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.

Why Contribute Here?

• ✅ 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

Easy Ways to Contribute

1. Add Sound Effects (5 minutes)
   • Drop an MP3 file in assets/sounds/ with a kebab-case name
2. Create or Update Configs (10 minutes)
   • Share your custom keybind setup in src/configs/
3. Improve Docs (15 minutes)
   • Fix typos, add examples, or clarify instructions
4. 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!

Features

• 🎹 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

Installation

Global Installation (Recommended)

# Install globally
npm install -g soundbind

# Or use with npx (no installation needed)
npx soundbind

Local Installation

# Install as a dependency
npm install soundbind

# Or install from source
git clone https://github.com/UselessCo/soundbind.git
cd soundbind
npm install

Quick Start

Option 1: Use Included Configs & Sounds

Soundbind 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!
soundbind

Included configs:

• default.yaml - Basic setup with example sounds
• template.yaml - Comprehensive template with all options

Option 2: Create Your Own Config

1. Create a soundbind.yaml configuration 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'

2. Sounds are included in the package! Or add your own to a my-sounds/ directory

3. Run Soundbind:

# If installed globally
soundbind

# With npx
npx soundbind

# With custom config path
soundbind ./my-config.yaml

# From source
npm start

Audio Setup

Linux (Recommended)

Install SoX with MP3 support:

sudo apt install sox libsox-fmt-mp3  # Ubuntu/Debian

Windows/macOS

Audio should work out of the box with the default system player.

Programmatic Usage

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();

Configuration

See template.yaml in the repository for a complete configuration example with all available options and supported key combinations.

Supported Keys

• Letters: a-z
• Numbers: 0-9
• Function Keys: F1-F12
• Numpad: numpad0-numpad9
• Modifiers: ctrl, shift, alt + any key
• Special: space, enter, escape, tab

Keybind Options

• stopOthers: true/false - Stop other sounds before playing
• description: Human-readable description

Logging Options

• level: debug, info, warn, error - Log verbosity
• fileEnabled: true/false - Enable file logging
• filePath: Directory path for log files

Future Features

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

Requirements

• Node.js 14.0.0 or higher
• Linux: SoX with MP3 support (recommended)

Contributing

🎵 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.

Quick Contribution Guide

1. Fork the repository
2. Add your sounds to assets/sounds/ or configs to src/configs/
3. Test your changes
4. 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

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Disclaimer

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.

License

MIT License - see LICENSE for details.

🙏 Thanks to all contributors

A big thank you to everyone who has contributed! Your contributions keep Soundbind alive and improving.