🎮 Terminal Buzz

Make your terminal delightful again!

A fun CLI tool that plays nostalgic game sounds when your terminal commands finish. Turn boring command-line tasks into a gaming experience!

✨ Features

• 🔊 Nostalgic Game Sounds - Success and error sounds from your favorite retro games
• 🔔 Desktop Notifications - Get notified when long-running commands complete
• 🎨 Multiple Themes - Mario, Zelda, Pokemon, Sonic, and Retro arcade sounds
• ⚙️ Configurable - Set your default theme and preferences
• 🎲 Random Mode - Surprise yourself with a different theme each time
• 🤫 Silent Mode - Notifications only, no sound
• 🎯 Real-time Output - See command output as it happens
• 🛡️ Graceful Interruption - Ctrl+C works as expected

📦 Installation

Global Installation (Recommended)

npm install -g @aicronic/terminal-buzz

Local Installation

npm install @aicronic/terminal-buzz

🚀 Quick Start

# Run a command with Mario theme
terminal-buzz --theme mario "npm run build"

# Set your default theme
terminal-buzz config set-theme zelda

# Use your default theme
terminal-buzz "cargo build --release"

# Random theme each time
terminal-buzz --random "python train.py"

# Silent mode (notification only)
terminal-buzz --silent "npm test"

🎮 Available Themes

| Theme | Success Sound | Error Sound | Emoji | |-------|--------------|-------------|-------| | 🍄 Mario | Coin collect | Game over | 🍄 | | ⚔️ Zelda | Chest open | Error beep | ⚔️ | | ⚡ Pokemon | Level up | Pokemon faint | ⚡ | | 💨 Sonic | Ring collect | Death | 💨 | | 👾 Retro | Pac-Man eat | Pac-Man death | 👾 |

📖 Usage

Basic Command Execution

terminal-buzz [options] "<your-command>"

Options

| Option | Alias | Description | |--------|-------|-------------| | --theme <name> | -t | Override default theme (mario, zelda, pokemon, sonic, retro) | | --random | -r | Use a random theme | | --silent | -s | Notification only, no sound | | --version | -V | Show version number | | --help | -h | Display help |

Configuration Commands

# Set default theme
terminal-buzz config set-theme <theme>

# Get current default theme
terminal-buzz config get-theme

# List all available themes
terminal-buzz config list-themes

💡 Use Cases

Long-Running Builds

terminal-buzz "npm run build"
terminal-buzz "cargo build --release"
terminal-buzz "docker build -t myapp ."

Test Suites

terminal-buzz --theme pokemon "npm test"
terminal-buzz "pytest tests/"
terminal-buzz "go test ./..."

Deployment Scripts

terminal-buzz --theme sonic "npm run deploy"
terminal-buzz "./deploy.sh production"

Training ML Models

terminal-buzz --random "python train.py --epochs 100"

Database Operations

terminal-buzz "pg_dump mydb > backup.sql"
terminal-buzz "mongorestore --db mydb dump/"

🎯 Real-World Examples

# Frontend development
terminal-buzz --theme mario "npm run build && npm run deploy"

# Backend compilation
terminal-buzz --theme sonic "go build -o server cmd/main.go"

# Data processing
terminal-buzz --random "python process_data.py --input large_dataset.csv"

# System administration
terminal-buzz --silent "rsync -avz /source/ /backup/"

# Multiple commands
terminal-buzz "npm install && npm run build && npm test"

🌐 Global Shell Integration (Recommended)

Want sounds after every command without typing terminal-buzz? Let the setup wizard handle it!

terminal-buzz setup

This will automatically detect your shell (Bash or Zsh) and add the necessary hook to your config file.

Manual Integration

If the setup doesn't detect your shell, you can add these manually:

Bash (~/.bashrc):

PROMPT_COMMAND='terminal-buzz --notify $? &'

Zsh (~/.zshrc):

precmd() {
  terminal-buzz --notify $? &!
}

🔧 Configuration

Configuration is stored in ~/.config/terminal-buzz-config.json (or platform equivalent).

Default configuration:

{
  "theme": "mario"
}

🎨 Adding Custom Themes

Want to contribute a new theme? Here's how:

1. Create a new folder in sounds/ with your theme name
2. Add two MP3 files:
   • success.mp3 - Plays on successful command completion (exit code 0)
   • error.mp3 - Plays on command failure (non-zero exit code)
3. Keep files under 50KB each for fast loading
4. Update lib/index.js to include your theme in the THEMES object
5. Submit a pull request!

Sound Requirements

• Format: MP3
• Bitrate: 64kbps recommended
• Duration: 1-3 seconds
• Size: < 50KB per file
• License: Must be free to use (CC0, public domain, or similar)

🛠️ Development

# Clone the repository
git clone https://github.com/aicronic/terminal-buzz.git
cd terminal-buzz

# Install dependencies
npm install

# Make CLI executable
chmod +x bin/cli.js

# Test locally
node bin/cli.js --theme mario "echo 'Hello World'"

# Test error handling
node bin/cli.js --theme mario "exit 1"

🧪 Testing Checklist

• ✅ Success sound plays on exit code 0
• ✅ Error sound plays on non-zero exit code
• ✅ Desktop notification appears
• ✅ Config persists between runs
• ✅ Ctrl+C kills both tool and child process
• ✅ Command output streams in real-time
• ✅ Works on Mac/Linux/Windows
• ✅ Fallback to system beep if audio fails

🌍 Platform Support

| Platform | Status | Notes | |----------|--------|-------| | macOS | ✅ Full Support | Native audio and notifications | | Linux | ✅ Full Support | Requires alsa-utils or pulseaudio | | Windows | ✅ Full Support | Native audio via Windows Media Player |

Linux Audio Setup

If you encounter audio issues on Linux, install one of these:

# Ubuntu/Debian
sudo apt-get install alsa-utils

# Or use PulseAudio
sudo apt-get install pulseaudio

📝 License

MIT © aicronic

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Here are some ideas:

• 🎵 Add new game themes
• 🐛 Fix bugs or improve error handling
• 📚 Improve documentation
• ✨ Suggest new features

🙏 Credits

Sound effects sourced from:

• The Mushroom Kingdom - Mario sounds
• Zelda Dungeon - Zelda sounds
• Sounds Resource - Sonic sounds
• Mixkit - Free game sound effects
• Freesound - CC0 licensed sounds

⭐ Show Your Support

If you find this tool useful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing on social media
• 🐛 Reporting bugs
• 💡 Suggesting new features

📬 Contact

• GitHub: @aicronic
• Issues: GitHub Issues

Made with ❤️ and nostalgia by developers, for developers

Remember: Every successful build deserves a victory sound! 🎮