soundcheck

Crates.iosoundcheck
lib.rssoundcheck
version1.0.0
created_at2025-11-30 06:43:31.921724+00
updated_at2025-12-07 02:42:07.481832+00
descriptionA terminal-based audio monitoring application that displays real-time audio levels and exits when sound exceeds a specified threshold.
homepage
repositoryhttps://github.com/isfopo/soundcheck
max_upload_size
id1957959
size124,184
Isaac Poole (isfopo)

documentation

README

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

Option Description Default Example
--threshold Audio threshold in dB (-60 to 0) 0 --threshold -30
--min-db Minimum dB level for display (-100 to 0) -60 --min-db -80
--channels Audio channels to monitor (comma-separated) [0] --channels 0,1
--device Audio input device name Default device --device "USB Microphone"

Max Command Options

Option Description Default Example
--seconds Monitoring duration in seconds Until Enter --seconds 10
--min-db Minimum dB level for display (-100 to 0) -60 --min-db -80
--channels Audio channels to monitor (comma-separated) [0] --channels 0,1
--device Audio input device name Default device --device "USB Microphone"
--quiet Output only integer values without labels false --quiet

Average Command Options

Option Description Default Example
--seconds Monitoring duration in seconds Until Enter --seconds 10
--min-db Minimum dB level for display (-100 to 0) -60 --min-db -80
--channels Audio channels to monitor (comma-separated) [0] --channels 0,1
--device Audio input device name Default device --device "USB Microphone"
--quiet Output only integer values without labels false --quiet

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
Commit count: 0

cargo fmt