MUC Soundboard 🎵🎮

Play audio files through your microphone in multiplayer games like CS, Battlefield, and COD using hotkeys. Built with Python and Rich for a beautiful CLI experience!

✨ Features

🎵 Play audio through your mic - Route sound to your virtual microphone
⌨️ Custom hotkeys - Bind any key combination to any sound (F1-F12, Ctrl+, Alt+, etc.)
🏷️ Tags & categories - Organize sounds with tags and filter by category
⭐ Favorites - Mark and quickly access your most-used sounds
🔊 Per-sound volume - Set individual volume levels (0-200%) for each sound
📋 Queue & playlists - Build queues and save them as reusable playlists
🎨 Beautiful CLI - Rich-click powered interface with colors and tables
📊 Progress bar - Visual playback progress with time display
🎛️ Multiple formats - Supports WAV, MP3, OGG, FLAC, M4A
🔍 Auto-detection - Finds VB-Cable and virtual audio devices automatically
🔎 Fuzzy search - Find sounds quickly with typo-tolerant search
📁 Organized library - Subdirectory support for sound organization
🔉 Global volume - Adjustable playback volume with persistent settings
🎲 Auto-play mode - Play all sounds randomly or sequentially
📥 YouTube download - Download audio directly from YouTube with yt-dlp
✂️ Audio trimming - Trim sounds with optional fade in/out
🔊 Audio normalization - Normalize levels for consistent volume
⚙️ Persistent config - Saves your settings to ~/.muc/
👤 Configuration profiles - Create and switch between different setups for different games
📤 Config export/import - Share configurations between machines or with friends
📂 Multiple sounds directories - Scan sounds from multiple folders with override support
⚡ Performance optimized - LRU audio cache for instant playback
🧠 Configurable cache - Adjustable cache size with automatic LRU eviction
🎮 Gaming ready - Perfect for CS, Battlefield, COD, and more!

📋 Prerequisites

1. Python Environment

Python 3.13 or higher
uv or pip for package management

2. Virtual Audio Cable

CRITICAL: You need a virtual audio device to route audio to your microphone.

Recommended: VB-Cable (Free)

Download from: https://vb-audio.com/Cable/
Install the driver with admin privilege
Restart your computer (required!)
This creates:
- CABLE Input - Where your soundboard outputs audio
- CABLE Output - What your game reads as a microphone

NOTE: This will switch your default audio and microphone devices to VB-Cable. Revert them back to your real devices.

🚀 Installation

Quick Start

Install via uv or pip:

uv add muc
# optional: with yt-dlp for downloading audio
uv add muc[yt-dlp]

Add your audio files:
- Place audio files (MP3, WAV, OGG, FLAC, M4A) in the sounds/ directory
- Organize in subdirectories if desired
- The app automatically scans and loads all audio files

⚙️ Setup

Step 1: Configure VB-Cable

In Windows Sound Settings:

Right-click speaker icon in taskbar → Sound settings
Under Input, select your real microphone (HyperX, Blue Yeti, etc.)
This is for your actual voice

In Your Game Settings:

Open game audio/voice settings
Set Input Device to: CABLE Output (VB-Audio Virtual Cable)
Your teammates will now hear audio from the soundboard + your voice (if using software mixing)

Step 2: Run Setup Wizard

muc setup

The setup wizard will:

📋 List all available audio devices in a beautiful table
🔍 Auto-detect VB-Cable or similar virtual devices
✓ Let you confirm or manually select the output device
💾 Save your configuration to your active profile

IMPORTANT: Select CABLE Input as the output device, not CABLE Output.

CABLE Input  ← Soundboard outputs HERE
     ↓
CABLE Output ← Game reads FROM here

🎮 Usage

CLI Commands

MUC provides a modern CLI with multiple commands:

# Setup and configuration
muc setup          # Run setup wizard
muc devices        # List all audio devices

# Sound management
muc sounds         # List available sounds in your library
muc sounds --tag meme        # Filter by tag
muc sounds --favorites       # Show only favorites
muc search [query] # Fuzzy search for sounds by name or tag
muc play [name]    # Play a specific sound (prompts if no name)
muc stop           # Stop currently playing sound
muc auto           # Play all sounds randomly (use --sequential for alphabetical order)
muc info [name]    # Show detailed info about a sound

# Tags & organization
muc tag airhorn meme loud    # Add tags to a sound
muc untag airhorn loud       # Remove tags from a sound
muc tags                     # List all tags with counts

# Favorites
muc favorite airhorn         # Toggle favorite status
muc favorite airhorn --on    # Add to favorites
muc favorites                # List all favorites

# Volume control
muc volume         # Show current global volume
muc volume 0.5     # Set global volume to 50% (0.0 to 1.0)
muc sound-volume airhorn 1.5   # Set per-sound volume to 150% (0.0 to 2.0)

# Custom hotkeys
muc bind f1 airhorn          # Bind F1 to play airhorn
muc bind "<ctrl>+a" applause # Bind Ctrl+A to applause
muc unbind f1                # Remove hotkey binding
muc unbind airhorn           # Remove all bindings for a sound
muc hotkeys                  # Show all hotkey bindings
muc hotkeys-reset            # Reset to default F1-F10 bindings
muc listen                   # Start hotkey listener (press ESC to stop)

# Queue management
muc queue add airhorn explosion  # Add sounds to queue
muc queue show               # Show current queue
muc queue play               # Play queue sequentially
muc queue skip               # Skip to next sound
muc queue shuffle            # Shuffle the queue
muc queue clear              # Clear the queue

# Playlists
muc playlist save mylist     # Save current queue as playlist
muc playlist load mylist     # Load playlist into queue
muc playlist list            # List all saved playlists
muc playlist show mylist     # Show playlist contents
muc playlist delete mylist   # Delete a playlist

# Configuration profiles
muc profile list             # List all profiles
muc profile show [name]      # Show profile details
muc profile create <name>    # Create a new profile
muc profile switch <name>    # Switch to a different profile
muc profile delete <name>    # Delete a profile
muc profile set-default <name>  # Set default profile

# Config export/import
muc config export <file>     # Export current profile to JSON
muc config import <file>     # Import profile from JSON
muc config export-all <file> # Export all profiles to ZIP archive

# Multiple sounds directories
muc dirs list                # List configured sounds directories
muc dirs add <path>          # Add a sounds directory
muc dirs remove <path>       # Remove a sounds directory
muc dirs conflicts           # Show sounds with name conflicts

# Download & audio tools
muc download <url>           # Download audio from YouTube
muc download <url> --name myfile --start 0:15 --end 0:30  # With trim
muc trim <sound> --start 0:00 --end 0:05   # Trim audio file
muc normalize <sound>        # Normalize audio levels
muc normalize --all          # Normalize all sounds
muc normalize --analyze      # Just analyze levels

# Cache management (performance)
muc cache stats              # Show cache statistics (hits, size, hit rate)
muc cache clear              # Clear the audio cache
muc cache preload --hotkeys  # Pre-load sounds bound to hotkeys
muc cache preload --favorites # Pre-load favorite sounds
muc cache preload --all      # Pre-load all sounds
muc cache enable             # Enable audio caching
muc cache disable            # Disable audio caching
muc cache size 200           # Set max cache size to 200 MB

# Interactive mode
muc interactive    # Launch full interactive menu

# Help
muc --help         # Show all commands

Quick Workflow

First time setup:
```
muc setup
```
Check your sounds:
```
muc sounds
```
Test a sound:
```
muc play rickroll
```
Start gaming with hotkeys:
```
muc listen
```
- Press F1-F10 to play sounds
- Press ESC to stop

Hotkey Bindings

By default, the first 10 sounds (alphabetically) are mapped to F1-F10.

Custom hotkeys let you bind any key combination:

muc bind f1 airhorn              # Simple key
muc bind "<ctrl>+<shift>+a" boom # Modifier keys
muc bind "<alt>+1" explosion     # Alt + number

Hotkey modes (set in config):

default - Only use auto-assigned F1-F10
custom - Only use your custom bindings
merged - Use both (default)

View bindings:

muc hotkeys

Reset to defaults:

muc hotkeys-reset

Interactive Menu Mode

For a full-featured visual menu:

muc interactive

Features a visual status header showing device, volume, and sound count, plus:

🎵 List & play sounds
🔍 Search sounds (fuzzy matching)
⌨️ View & manage hotkeys
🎧 Start hotkey listener
⏹️ Stop current sound
🔊 Adjust volume
⚙️ Change output device
🎲 Auto-play all sounds

🎵 Audio File Management

Supported Formats

WAV - Best quality, larger files
MP3 - Good quality, smaller files
OGG - Good quality, open format
FLAC - Lossless quality, large files
M4A - Apple format

Directory Organization

sounds/
├── music/
│   ├── song1.mp3
│   └── song2.mp3
├── effects/
│   ├── airhorn.wav
│   └── explosion.wav
├── memes/
│   └── rickroll.mp3
└── random_sound.mp3

The app recursively scans all subdirectories.

Recommendations

Sample Rate: 48000 Hz
Bit Depth: 16-bit (WAV)
Bitrate: 192-320 kbps (MP3)
Length: Under 30 seconds for best performance
Volume: Normalize audio to -3dB to prevent clipping
Naming: Use descriptive names without special characters

Getting Audio Files

Using built-in downloader (recommended):

# Download from YouTube directly to your sounds folder
muc download "https://youtube.com/watch?v=..." --name my-sound

# Download with time range extraction
muc download "https://youtube.com/..." --start 0:15 --end 0:45

# Choose output format
muc download "https://youtu.be/..." --format mp3

Requirements for download command:

yt-dlp: uv add muc[yt-dlp] or pip install yt-dlp
ffmpeg: Download from https://ffmpeg.org/download.html

Manual method:

# Download using yt-dlp directly
yt-dlp -x --audio-format wav "https://youtube.com/watch?v=..."

# Move file to sounds/
mv video.wav sounds/

Audio Processing

Trim sounds:

# Trim to specific time range
muc trim airhorn --start 0:00 --end 0:05

# Trim with fade effects
muc trim long_song --start 1:30 --end 2:00 --fade-in 0.5 --fade-out 0.5

# Save with custom name
muc trim intro --end 10 --output short_intro

Normalize audio levels:

# Normalize a single sound
muc normalize airhorn

# Analyze levels without changing
muc normalize --all --analyze

# Normalize all sounds to -6 dB
muc normalize --all --target -6

# Use RMS normalization (loudness-based)
muc normalize airhorn --mode rms

⚡ Performance Optimization

MUC includes built-in performance optimizations for low-latency playback:

Audio Caching

Frequently played sounds are cached in memory for instant playback:

# View cache statistics
muc cache stats

# Pre-load hotkey sounds for zero-latency playback
muc cache preload --hotkeys

# Pre-load all favorites
muc cache preload --favorites

# Adjust cache size (default: 100 MB)
muc cache size 200

Cache benefits:

First playback: ~100ms (loads from disk)
Cached playback: <20ms (from cache)
Hit rate: Typically >80% for repeated sounds
LRU eviction: Least recently used sounds are automatically removed when cache is full

🔧 Configuration

Configuration is stored in ~/.muc/ with support for multiple profiles:

~/.muc/
├── state.json           # Global state (active profile, default profile)
├── profiles/
│   ├── default.json     # Default profile
│   ├── csgo.json        # Game-specific profile
│   └── streaming.json   # Custom profile
├── metadata.json        # Sound tags, favorites, volumes, play counts
└── playlists.json       # Saved playlists

Profile Settings

Each profile contains:

{
  "name": "csgo",
  "display_name": "CS:GO Competitive",
  "description": "Settings for CS:GO matches",
  "settings": {
    "output_device_id": 6,
    "sounds_dir": "C:/path/to/sounds",
    "sounds_dirs": ["C:/sounds/main", "C:/sounds/memes"],
    "volume": 0.8,
    "hotkeys": {
      "<f1>": "airhorn",
      "<ctrl>+<shift>+a": "applause"
    },
    "hotkey_mode": "merged"
  }
}

Profile Workflow

# Create profiles for different games
muc profile create "CS:GO" --description "Counter-Strike settings"
muc profile create "Valorant" --copy-from csgo

# Switch between profiles
muc profile switch csgo
muc profile switch valorant

# Export/import for backup or sharing
muc config export csgo-settings.json
muc config import csgo-settings.json --name "imported-csgo"
muc config export-all full-backup.zip

Multiple Sounds Directories

You can configure multiple directories to scan for sounds:

# Add directories (later directories override earlier ones for same-named sounds)
muc dirs add "C:/sounds/main"
muc dirs add "C:/sounds/game-specific"
muc dirs add "D:/shared-sounds"

# View configured directories
muc dirs list

# Check for naming conflicts
muc dirs conflicts

This is useful for:

Keeping a base sound library + game-specific overrides
Sharing sounds across multiple profiles
Organizing sounds by category in different folders

🎯 Gaming Tips

Test First: Always test sounds before joining a match
```
muc play test-sound
```
Volume Control:
- Use muc volume 0.5 to set soundboard volume to 50%
- Use audio editing software to normalize clips
- Set in-game voice volume appropriately
Quick Access:
- Keep a terminal with muc listen running
- Alt-tab is instant with hotkeys
- Or use a second monitor
Push-to-Talk:
- If your game uses PTT, you'll need to hold it while playing sounds
- Or configure the game to use voice activation
Be Respectful:
- Don't spam sounds excessively
- Use appropriate audio in competitive matches
- Some communities have rules about soundboards

🐛 Troubleshooting

"No virtual audio cable detected"

Solution: Install VB-Cable and restart your computer

muc setup  # Run again after restart

"Teammates can't hear the audio"

Check:

Game microphone set to CABLE Output ✓
Soundboard output set to CABLE Input ✓
Test with: muc play test-sound

Fix:

muc devices  # Verify device IDs
muc setup    # Reconfigure if needed

"Audio plays on my speakers, not through mic"

Problem: Wrong output device selected

Solution:

muc devices  # Find CABLE Input ID
muc setup    # Select correct device

Remember: CABLE Input (not Output) for soundboard output!

"Hotkeys don't work"

Causes:

Windows blocking global hotkeys
Another app using same keys
Listener not started

Solutions:

# Run as administrator (Windows)
# Or try interactive mode
muc interactive  # Then select option 4

"Audio quality is poor"

Improve quality:

Use WAV or high-bitrate MP3 files
Match sample rate to your device (usually 48000 Hz)
Normalize audio levels
Check VB-Cable settings in Windows Sound Control Panel

"Configuration not saving"

Check: Permissions for ~/.muc/ directory

# Windows - check directory
ls ~\.muc

# If missing, create manually
mkdir ~\.muc

🏗️ Architecture

This project implements a clean software architecture:

┌─────────────────────────────────────────────────────┐
│                    CLI Layer                        │
│            Rich-click commands (cli.py)             │
└───────────────────────┬─────────────────────────────┘
                        │
        ┌───────────────┼───────────────┬─────────────┐
        │               │               │             │
┌───────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐ ┌───▼───────────┐
│Profile Manager│ │  Metadata │ │ Queue Manager │ │Config Transfer│
│  (profiles)   │ │(tags,favs)│ │ (playlists)   │ │(export/import)│
└───────┬───────┘ └─────┬─────┘ └───────┬───────┘ └───────────────┘
        │               │               │
        └───────────────┼───────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                   Soundboard                        │
│     (sound library, hotkey manager, playback)       │
│              + SoundsDirectoryManager               │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                  Audio Manager                      │
│           (devices, volume, playback)               │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│              Virtual Audio Device                   │
│              (VB-Cable, etc.)                       │
└─────────────────────────────────────────────────────┘

Flow:

User runs command → CLI parses → Profile loads settings
Soundboard scans sounds → Loads metadata (tags, volumes)
HotkeyManager sets up bindings (default + custom)
User presses hotkey → Handler triggered → Metadata volume applied
Audio Manager loads file (cached via LRU) → Outputs to virtual device
Game reads from virtual device → Teammates hear sound

📁 Project Structure

muc/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── cli.py               # Rich-click CLI commands
│   ├── profile_manager.py   # Configuration profiles
│   ├── config_transfer.py   # Export/import configurations
│   ├── sounds_directories.py # Multiple sounds directories
│   ├── audio_manager.py     # Audio device & playback
│   ├── cache.py             # LRU audio cache
│   ├── soundboard.py        # Sound library & hotkeys
│   ├── metadata.py          # Tags, favorites, per-sound volume
│   ├── hotkey_manager.py    # Custom hotkey bindings
│   ├── queue_manager.py     # Queue & playlist management
│   ├── audio_tools.py       # Audio trimming & normalization
│   ├── downloader.py        # YouTube download support
│   ├── search.py            # Fuzzy search
│   ├── interactive_menu.py  # Interactive TUI menu
│   ├── status_display.py    # Live status display
│   ├── validators.py        # Input validation
│   ├── exceptions.py        # Custom exceptions
│   └── logging_config.py    # Logging setup
├── sounds/                  # Audio files directory
│   └── README.md            # Sound library guide
├── tests/                   # Unit & integration tests
├── pyproject.toml           # Project metadata & dependencies
├── README.md                # This file
└── Makefile                 # Development commands

🤝 Contributing

This is a personal project, but contributions are welcome!

Ways to contribute:

🐛 Report bugs or issues
💡 Suggest new features
🎵 Share cool sound packs
📖 Improve documentation
🔧 Submit pull requests

⚖️ Legal & Ethics

Usage Guidelines:

✓ Personal use and education
✓ Private games with friends
✗ Harassment or abuse
✗ Circumventing game rules
✗ Competitive advantage in ranked games

Copyright:

Ensure you have rights to audio files
Respect copyright and fair use
Don't distribute copyrighted content

Game ToS:

Check your game's terms of service
Some games prohibit audio injection
Use responsibly to avoid bans

📄 License

This project is provided as-is for personal and educational use only. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
sounds		sounds
src		src
tests		tests
tools		tools
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

Harshal6927/muc

Folders and files

Latest commit

History

Repository files navigation