Soundcheck

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

Installation 🚀

From Crates.io

cargo install soundcheck

From Homebrew

brew tap isfopo/homebrew-tap

brew install soundcheck

From Chocolatey (Windows)

choco install soundcheck

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

# List available audio devices (interactive selection)
soundcheck list

# Pipe device selection to detect
soundcheck list | xargs soundcheck detect --device

# Monitor max levels for 5 seconds
soundcheck max --seconds 5 --channels 0,1

# Monitor until Enter is pressed
soundcheck max --channels 0,1

# Calculate average levels over 5 seconds
soundcheck average --seconds 5 --channels 0,1

# Calculate average until Enter is pressed
soundcheck average --channels 0,1

# Get quiet output for scripting
soundcheck max --seconds 5 --quiet

Commands

• detect: Monitor audio levels and exit when threshold is exceeded
• list: List available audio input devices
• max: Monitor audio and report maximum levels detected
• average: Monitor audio and report average levels detected

Detect Command Options

Max Command Options

Average Command Options

List Command

soundcheck list  # Interactive device selection (navigate with arrow keys, press Enter)

Multi-Channel Monitoring

When monitoring multiple channels, the application displays separate gauges for each channel:

• Single Channel: Shows one gradient bar with dB labels
• Multiple Channels: Displays stacked gauges, one per channel
• Threshold Detection: Exits when ANY monitored channel exceeds the threshold

Command Chaining Examples

# Continue to next command only if threshold reached on any channel
soundcheck detect --channels 0,1 && echo "Audio detected!"

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

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

Requirements 📋

System Requirements

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

Dependencies

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

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 list to see available devices
• Use soundcheck detect --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
• Ensure selected channels are valid for the device
• Test with different threshold values

Debug Mode

# Run with verbose output
RUST_LOG=debug cargo run -- detect --threshold -20 --channels 0,1

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