A powerful and intuitive command-line tool for managing Bluetooth audio devices on Linux systems. Built with love by web3dozie for the Linux audio community.
- 🔍 Smart Device Discovery - List all paired Bluetooth devices with rich status information
- 🔗 Intelligent Connection Management - Connect by name, alias, or fuzzy matching
- 🎚️ Advanced Volume Control - Set, adjust, mute, boost with precision
- 🎯 Device Aliases - Create shortcuts for your favorite devices
- 📊 Beautiful Status Display - Dynamic, perfectly aligned status dashboard
- 🎨 Interactive Mode - User-friendly TUI for non-technical users
- 🎤 Microphone Management - Full control over input devices
- 🎵 Volume Presets - Save and load custom volume profiles
- ⚖️ Balance Control - Adjust left/right audio balance
- 🔄 Auto-Connect - Automatically connect to preferred devices
- 🔧 Troubleshooting Mode - Built-in diagnostics with solutions
- 🌈 Smart Color Detection - Works perfectly in kitty, xterm, and modern terminals
# Clone the repository
git clone https://github.com/web3dozie/btaudio.git
cd btaudio
# Install to ~/.local/bin
./install.sh
# Or manually
install -Dm755 bin/btaudio ~/.local/bin/btaudiosudo install -Dm755 bin/btaudio /usr/local/bin/btaudioRequired:
bluetoothctl- Bluetooth device controlwpctl(PipeWire) orpactl(PulseAudio) - Audio management
Optional:
speaker-test- Audio testing functionalityarecord/aplay- Microphone testing
# Launch interactive mode
btaudio
# List all devices
btaudio list
# Connect to a device
btaudio connect "WH-1000XM6"
btaudio sony # Using alias
btaudio wh # Fuzzy matching
# Volume control
btaudio volume 70 # Set to 70%
btaudio volume +10 # Increase by 10%
btaudio volume -10 # Decrease by 10%
btaudio mute # Toggle mute
btaudio max # Set to 100%
btaudio boost # Set to 150% (with warning)
# Check status
btaudio statusbtaudio mic 80 # Set mic volume to 80%
btaudio mic mute # Mute microphone
btaudio mic unmute # Unmute microphone
btaudio mic +10 # Increase mic volumebtaudio preset save work 30 # Save preset at 30%
btaudio preset save music 70 # Save preset at 70%
btaudio preset work # Load work preset
btaudio preset music # Load music presetbtaudio auto on # Enable auto-connect
btaudio auto add "WH-1000XM6" # Add device to auto list
btaudio auto off # Disable auto-connectbtaudio fix # Run diagnosticsConfiguration file: ~/.config/btaudio/config.yaml
# Default settings
volume_step: 10
auto_connect: true
# Device: Sony WH-1000XM6
name: WH-1000XM6
alias: sony
default_volume: 80
# Device: JBL Flip 5
name: JBL Flip 5
alias: speaker
default_volume: 60
# Volume presets
preset_work: 30
preset_music: 70
preset_quiet: 20
# Auto-connect devices
auto_device: WH-1000XM6
auto_device: JBL Flip 5The status command shows a beautifully formatted, dynamically sized box:
╭──────── Audio Status ────────╮
│ ─────────── Output ─────────── │
│ Device: WH-1000XM6 │
│ Volume: 80% │
│ Battery: 69% │
│ ─────────── Input ──────────── │
│ Device: WH-1000XM6 │
│ Volume: 100% │
│ ─────────── System ─────────── │
│ Backend: wpctl │
╰──────────────────────────────╯
Run btaudio without arguments to enter the interactive dashboard:
╭─────────────────────────────────╮
│ 🎵 Audio Control │
├─────────────────────────────────┤
│ Current: WH-1000XM6 (80%) │
├─────────────────────────────────┤
│ [1] 📱 Connect Device │
│ [2] 🔊 Volume Control │
│ [3] 🔄 Switch Output │
│ [4] 🎤 Toggle Mic Mute │
│ [5] ⚙️ Show Status │
│ [6] ❌ Disconnect All │
├─────────────────────────────────┤
│ [Q] Quit │
╰─────────────────────────────────╯
btaudio balance left 20 # Shift 20% to left
btaudio balance right 10 # Shift 10% to right
btaudio balance center # Reset to centerbtaudio test # Test stereo
btaudio test left # Test left channel
btaudio test right # Test right channel
btaudio test mic # Test microphonebtaudio switch speaker # Disconnect others, connect speaker
btaudio disconnect # Disconnect current device
btaudio - # Quick disconnectbtaudio is built with:
- Pure Bash - No external language dependencies
- Modular Design - Clean function separation
- Smart Detection - Automatic audio system detection (PipeWire/PulseAudio)
- Error Handling - Comprehensive error checking with helpful messages
- Color Support - Intelligent terminal capability detection
Contributions are welcome! Please feel free to submit pull requests or open issues.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with passion by web3dozie
- Inspired by the Linux audio community's needs
- Special thanks to all contributors and testers
No devices found
- Ensure Bluetooth service is running:
systemctl status bluetooth - Pair devices first:
bluetoothctl scan on
Volume controls not working
- Check if PipeWire is running:
systemctl --user status pipewire - Try PulseAudio fallback:
pactl list sinks
Colors not displaying
- btaudio auto-detects terminal capabilities
- Force disable with:
NO_COLOR=1 btaudio
Mic not switching
- Ensure default source is set correctly
- Use
btaudio fixfor diagnostics
- Product Requirements Document - Original vision and specifications
- Configuration Guide - Detailed configuration options
- API Reference - Command reference
- Initial release by web3dozie
- Core Bluetooth audio management
- Interactive mode
- Volume presets and auto-connect
- Microphone management
- Balance control (PipeWire)
- Troubleshooting mode
- Dynamic status display
Made with ❤️ by web3dozie