muc 0.2.0

Play audio through your microphone in games using hotkeys

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
• ⌨️ Hotkey support - F1-F10 keys for instant sound playback
• 🎨 Beautiful CLI - Rich-click powered interface with colors and tables
• 🎛️ Multiple formats - Supports WAV, MP3, OGG, FLAC, M4A
• 🔊 Auto-detection - Finds VB-Cable and virtual audio devices automatically
• 📁 Organized library - Subdirectory support for sound organization
• 🔉 Volume control - Adjustable playback volume with persistent settings
• 🎲 Auto-play mode - Play all sounds randomly or sequentially
• ⚙️ Persistent config - Saves your settings to ~/.muc/config.json
• 🎮 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)

1. Download from: https://vb-audio.com/Cable/
2. Install the driver with admin privilege
3. Restart your computer (required!)
4. 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

1. Install via uv or pip:

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

2. 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:

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

In Your Game Settings:

1. Open game audio/voice settings
2. Set Input Device to: CABLE Output (VB-Audio Virtual Cable)
3. 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:

1. 📋 List all available audio devices in a beautiful table
2. 🔍 Auto-detect VB-Cable or similar virtual devices
3. ✓ Let you confirm or manually select the output device
4. 💾 Save your configuration to ~/.muc/config.json

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

# Volume control
muc volume         # Show current volume
muc volume 0.5     # Set volume to 50% (0.0 to 1.0)

# Hotkey control
muc hotkeys        # Show hotkey bindings (F1-F10)
muc listen         # Start hotkey listener (press ESC to stop)

# Interactive mode
muc interactive    # Launch full interactive menu

# Help
muc --help         # Show all commands

Quick Workflow

1. First time setup:

   muc setup
   

2. Check your sounds:

   muc sounds
   

3. Test a sound:

   muc play rickroll
   

4. Start gaming with hotkeys:

   muc listen
   

   • Press F1-F10 to play sounds
   • Press ESC to stop

Hotkey Bindings

The first 10 sounds (alphabetically) are automatically mapped to:

• F1 → First sound
• F2 → Second sound
• F3 → Third sound
• ... through F10

View bindings:

muc hotkeys

Interactive Menu Mode

For a full-featured text menu:

muc interactive

Menu options:

1. List all sounds
2. Play sound by name
3. View hotkey bindings
4. Start hotkey listener
5. Stop current sound
6. List audio devices
7. Change output device
8. Adjust volume
9. Auto-play all sounds
10. Exit

🎵 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

# Download from YouTube (uses yt-dlp if installed)
yt-dlp -x --audio-format wav "https://youtube.com/watch?v=..."

# The file will be saved in your current directory
# Then move it to sounds/

🔧 Configuration

Configuration is automatically saved to ~/.muc/config.json:

{
  "output_device_id": 6,
  "sounds_dir": "C:/path/to/muc/sounds",
  "volume": 1.0
}

You can manually edit this file or reconfigure using:

muc setup

🎯 Gaming Tips

1. Test First: Always test sounds before joining a match

   muc play test-sound
   

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

3. Quick Access:

   • Keep a terminal with muc listen running
   • Alt-tab is instant with hotkeys
   • Or use a second monitor

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

5. 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:

1. Game microphone set to CABLE Output ✓
2. Soundboard output set to CABLE Input ✓
3. 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:

1. Use WAV or high-bitrate MP3 files
2. Match sample rate to your device (usually 48000 Hz)
3. Normalize audio levels
4. 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)
└──────┬──────┘
       │
┌──────▼──────┐
│   Config    │  ← Settings management (config.py)
└──────┬──────┘
       │
┌──────▼──────────────┬──────────────┐
│   Soundboard        │ Audio Manager│
│  (hotkeys, sounds)  │ (devices, io)│
└─────────────────────┴──────────────┘
          │                    │
          └──────┬─────────────┘
                 ▼
        ┌────────────────┐
        │  Audio Drivers │
        │ (sounddevice)  │
        └───────┬────────┘
                ▼
        Virtual Audio Device
        (VB-Cable, etc.)

Flow:

1. User runs command → CLI parses → Config loads settings
2. Soundboard scans sounds → Sets up hotkeys
3. User presses F1 → Hotkey handler triggered
4. Audio Manager loads file → Outputs to virtual device
5. Game reads from virtual device → Teammates hear sound

📁 Project Structure

muc/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── cli.py               # Rich-click CLI commands
│   ├── config.py            # Configuration management
│   ├── audio_manager.py     # Audio device & playback
│   ├── soundboard.py        # Sound library & hotkeys
│   └── main.py              # Entry point
├── sounds/                  # Audio files directory
│   └── README.md            # Sound library guide
├── pyproject.toml           # Project metadata & dependencies
├── README.md                # This file
└── idea.md                  # Original design document

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