Soundcheck 🎵

A terminal-based audio monitoring application that displays real-time audio levels and exits when sound exceeds a specified threshold.

Features ✨

• Real-time Audio Monitoring: Visual bar graph showing current dB levels
• Threshold Detection: Automatically exits when audio exceeds specified dB threshold
• Multiple Exit Methods: Ctrl+C, Escape key, or threshold trigger
• Smooth Visual Updates: 10ms refresh rate with exponential smoothing
• Cross-platform: Works on macOS, Linux, and Windows
• Terminal UI: Beautiful text-based interface using Ratatui

Installation 🚀

From Crates.io

cargo install soundcheck

From Homebrew

brew tap isfopo/Tap

brew install soundcheck

From Scoop (Windows)

scoop bucket add username-scoop-bucket https://github.com/username/soundcheck-scoop-bucket

scoop install soundcheck

From Chocolatey (Windows)

choco install soundcheck

From AUR (Arch Linux)

# Using yay
yay -S soundcheck

From Debian/Ubuntu Packages

# Download .deb from releases
sudo dpkg -i soundcheck_*.deb
sudo apt install -f  # Install dependencies if needed

AppImage (Universal Linux)

# Download AppImage from releases
chmod +x soundcheck-*.AppImage
./soundcheck-*.AppImage --help

From Source

git clone <repository-url>
cd soundcheck
cargo build --release
# Binary will be at target/release/soundcheck

Contributing & Development 🤝

Release Process

For detailed information about creating and publishing releases, see RELEASE.md.

Usage 📖

Basic Usage

# Monitor with default settings (-20 dB threshold)
soundcheck

# Set custom threshold
soundcheck --threshold -30

# Specify audio device
soundcheck --device "MacBook Pro Microphone"

# Combine options
soundcheck --threshold -25 --device "External USB Audio"

Command Line Options

Command Chaining Examples

# Continue to next command only if threshold reached
soundcheck && echo "Audio detected!"

# Run fallback command if user exits
soundcheck || echo "Monitoring cancelled by user"

# Error handling
soundcheck || echo "Failed to start monitoring"

Requirements 📋

System Requirements

• macOS: 10.15 or later
• Linux: Kernel 3.16+ with ALSA
• Windows: Windows 10+ with WASAPI

Audio Hardware

• Audio input device (microphone, line-in, etc.)
• Proper audio permissions (especially on macOS)

Dependencies

• Rust: 1.70+ (for edition 2021)
• Audio Libraries: System audio frameworks
  • macOS: CoreAudio
  • Linux: ALSA
  • Windows: WASAPI

Configuration ⚙️

Audio Device Selection

# List available devices (if supported by your audio library)
# Then specify the device name
standby --device "External Microphone (USB)"

Threshold Tuning

• Quiet environments: -30 to -40 dB
• Normal conversation: -20 to -25 dB
• Loud music/events: -10 to -15 dB

Development 🛠️

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Check code quality
cargo clippy
cargo fmt

Troubleshooting 🔍

Common Issues

"No default input device"

• Ensure your microphone/audio input is connected and enabled
• Check system audio settings

"Device not found"

• Use soundcheck --help to see available options
• Verify the device name spelling

Blank screen on startup

• Ensure terminal supports Unicode characters
• Try a different terminal emulator

Audio levels not updating

• Check that the correct audio device is selected
• Verify audio input permissions
• Test with different threshold values

Debug Mode

# Run with verbose output
RUST_LOG=debug cargo run -- --threshold -20

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments 🙏

• CPAL - Cross-platform audio library
• Ratatui - Terminal UI framework
• Tokio - Async runtime
• Clap - Command line parsing

Made with ❤️ using Rust README.md