https://github.com/web3dozie/btaudio
Powerful command-line tool for managing Bluetooth audio devices on Linux
https://github.com/web3dozie/btaudio
audio bash bluetooth cli linux pipewire pulseaudio
Last synced: 9 months ago
JSON representation
Powerful command-line tool for managing Bluetooth audio devices on Linux
- Host: GitHub
- URL: https://github.com/web3dozie/btaudio
- Owner: web3dozie
- License: mit
- Created: 2025-09-23T00:20:36.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-09-23T00:23:58.000Z (9 months ago)
- Last Synced: 2025-09-23T02:37:14.864Z (9 months ago)
- Topics: audio, bash, bluetooth, cli, linux, pipewire, pulseaudio
- Language: Shell
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# btaudio 🎧
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.
## ✨ Features
### Core Functionality
- 🔍 **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
### Advanced Features
- 🎤 **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
## 📦 Installation
### Quick Install
```bash
# 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/btaudio
```
### System-wide Install
```bash
sudo install -Dm755 bin/btaudio /usr/local/bin/btaudio
```
### Dependencies
Required:
- `bluetoothctl` - Bluetooth device control
- `wpctl` (PipeWire) or `pactl` (PulseAudio) - Audio management
Optional:
- `speaker-test` - Audio testing functionality
- `arecord` / `aplay` - Microphone testing
## 🚀 Quick Start
### Basic Usage
```bash
# 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 status
```
### Microphone Control
```bash
btaudio mic 80 # Set mic volume to 80%
btaudio mic mute # Mute microphone
btaudio mic unmute # Unmute microphone
btaudio mic +10 # Increase mic volume
```
### Volume Presets
```bash
btaudio 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 preset
```
### Auto-Connect
```bash
btaudio auto on # Enable auto-connect
btaudio auto add "WH-1000XM6" # Add device to auto list
btaudio auto off # Disable auto-connect
```
### Troubleshooting
```bash
btaudio fix # Run diagnostics
```
## ⚙️ Configuration
Configuration file: `~/.config/btaudio/config.yaml`
### Example Configuration
```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 5
```
## 📊 Status Display
The 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 │
╰──────────────────────────────╯
```
## 🎨 Interactive Mode
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 │
╰─────────────────────────────────╯
```
## 🛠️ Advanced Usage
### Balance Control
```bash
btaudio balance left 20 # Shift 20% to left
btaudio balance right 10 # Shift 10% to right
btaudio balance center # Reset to center
```
### Audio Testing
```bash
btaudio test # Test stereo
btaudio test left # Test left channel
btaudio test right # Test right channel
btaudio test mic # Test microphone
```
### Device Switching
```bash
btaudio switch speaker # Disconnect others, connect speaker
btaudio disconnect # Disconnect current device
btaudio - # Quick disconnect
```
## 🏗️ Architecture
btaudio 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
## 🤝 Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with passion by **web3dozie**
- Inspired by the Linux audio community's needs
- Special thanks to all contributors and testers
## 🐛 Troubleshooting
### Common Issues
**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 fix` for diagnostics
## 📚 Documentation
- [Product Requirements Document](PRD_btaudio.md) - Original vision and specifications
- [Configuration Guide](docs/CONFIG.md) - Detailed configuration options
- [API Reference](docs/API.md) - Command reference
## 🔄 Changelog
### v0.1.0 (September 2025)
- 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
---