{"id":31650510,"url":"https://github.com/web3dozie/btaudio","last_synced_at":"2025-10-07T08:30:16.709Z","repository":{"id":316153232,"uuid":"1062200447","full_name":"web3dozie/btaudio","owner":"web3dozie","description":"Powerful command-line tool for managing Bluetooth audio devices on Linux","archived":false,"fork":false,"pushed_at":"2025-09-23T00:23:58.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-23T02:37:14.864Z","etag":null,"topics":["audio","bash","bluetooth","cli","linux","pipewire","pulseaudio"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/web3dozie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T00:20:36.000Z","updated_at":"2025-09-23T00:24:01.000Z","dependencies_parsed_at":"2025-09-23T02:37:43.895Z","dependency_job_id":"99398bfc-3632-4d37-9691-f2f7aa602537","html_url":"https://github.com/web3dozie/btaudio","commit_stats":null,"previous_names":["web3dozie/btaudio"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/web3dozie/btaudio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dozie%2Fbtaudio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dozie%2Fbtaudio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dozie%2Fbtaudio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dozie%2Fbtaudio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/web3dozie","download_url":"https://codeload.github.com/web3dozie/btaudio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web3dozie%2Fbtaudio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278742889,"owners_count":26037915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","bash","bluetooth","cli","linux","pipewire","pulseaudio"],"created_at":"2025-10-07T08:30:07.090Z","updated_at":"2025-10-07T08:30:16.697Z","avatar_url":"https://github.com/web3dozie.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# btaudio 🎧\n\nA powerful and intuitive command-line tool for managing Bluetooth audio devices on Linux systems. Built with love by web3dozie for the Linux audio community.\n\n![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n![Shell](https://img.shields.io/badge/shell-bash-orange.svg)\n![Platform](https://img.shields.io/badge/platform-Linux-lightgrey.svg)\n\n## ✨ Features\n\n### Core Functionality\n- 🔍 **Smart Device Discovery** - List all paired Bluetooth devices with rich status information\n- 🔗 **Intelligent Connection Management** - Connect by name, alias, or fuzzy matching\n- 🎚️ **Advanced Volume Control** - Set, adjust, mute, boost with precision\n- 🎯 **Device Aliases** - Create shortcuts for your favorite devices\n- 📊 **Beautiful Status Display** - Dynamic, perfectly aligned status dashboard\n- 🎨 **Interactive Mode** - User-friendly TUI for non-technical users\n\n### Advanced Features\n- 🎤 **Microphone Management** - Full control over input devices\n- 🎵 **Volume Presets** - Save and load custom volume profiles\n- ⚖️ **Balance Control** - Adjust left/right audio balance\n- 🔄 **Auto-Connect** - Automatically connect to preferred devices\n- 🔧 **Troubleshooting Mode** - Built-in diagnostics with solutions\n- 🌈 **Smart Color Detection** - Works perfectly in kitty, xterm, and modern terminals\n\n## 📦 Installation\n\n### Quick Install\n```bash\n# Clone the repository\ngit clone https://github.com/web3dozie/btaudio.git\ncd btaudio\n\n# Install to ~/.local/bin\n./install.sh\n\n# Or manually\ninstall -Dm755 bin/btaudio ~/.local/bin/btaudio\n```\n\n### System-wide Install\n```bash\nsudo install -Dm755 bin/btaudio /usr/local/bin/btaudio\n```\n\n### Dependencies\nRequired:\n- `bluetoothctl` - Bluetooth device control\n- `wpctl` (PipeWire) or `pactl` (PulseAudio) - Audio management\n\nOptional:\n- `speaker-test` - Audio testing functionality\n- `arecord` / `aplay` - Microphone testing\n\n## 🚀 Quick Start\n\n### Basic Usage\n```bash\n# Launch interactive mode\nbtaudio\n\n# List all devices\nbtaudio list\n\n# Connect to a device\nbtaudio connect \"WH-1000XM6\"\nbtaudio sony              # Using alias\nbtaudio wh                # Fuzzy matching\n\n# Volume control\nbtaudio volume 70         # Set to 70%\nbtaudio volume +10        # Increase by 10%\nbtaudio volume -10        # Decrease by 10%\nbtaudio mute              # Toggle mute\nbtaudio max               # Set to 100%\nbtaudio boost             # Set to 150% (with warning)\n\n# Check status\nbtaudio status\n```\n\n### Microphone Control\n```bash\nbtaudio mic 80            # Set mic volume to 80%\nbtaudio mic mute          # Mute microphone\nbtaudio mic unmute        # Unmute microphone\nbtaudio mic +10           # Increase mic volume\n```\n\n### Volume Presets\n```bash\nbtaudio preset save work 30     # Save preset at 30%\nbtaudio preset save music 70    # Save preset at 70%\nbtaudio preset work             # Load work preset\nbtaudio preset music            # Load music preset\n```\n\n### Auto-Connect\n```bash\nbtaudio auto on                 # Enable auto-connect\nbtaudio auto add \"WH-1000XM6\"   # Add device to auto list\nbtaudio auto off                # Disable auto-connect\n```\n\n### Troubleshooting\n```bash\nbtaudio fix                     # Run diagnostics\n```\n\n## ⚙️ Configuration\n\nConfiguration file: `~/.config/btaudio/config.yaml`\n\n### Example Configuration\n```yaml\n# Default settings\nvolume_step: 10\nauto_connect: true\n\n# Device: Sony WH-1000XM6\nname: WH-1000XM6\nalias: sony\ndefault_volume: 80\n\n# Device: JBL Flip 5\nname: JBL Flip 5\nalias: speaker\ndefault_volume: 60\n\n# Volume presets\npreset_work: 30\npreset_music: 70\npreset_quiet: 20\n\n# Auto-connect devices\nauto_device: WH-1000XM6\nauto_device: JBL Flip 5\n```\n\n## 📊 Status Display\n\nThe status command shows a beautifully formatted, dynamically sized box:\n\n```\n╭──────── Audio Status ────────╮\n│ ─────────── Output ─────────── │\n│ Device: WH-1000XM6             │\n│ Volume: 80%                    │\n│ Battery: 69%                   │\n│ ─────────── Input ──────────── │\n│ Device: WH-1000XM6             │\n│ Volume: 100%                   │\n│ ─────────── System ─────────── │\n│ Backend: wpctl                 │\n╰──────────────────────────────╯\n```\n\n## 🎨 Interactive Mode\n\nRun `btaudio` without arguments to enter the interactive dashboard:\n\n```\n╭─────────────────────────────────╮\n│       🎵 Audio Control          │\n├─────────────────────────────────┤\n│ Current: WH-1000XM6 (80%)       │\n├─────────────────────────────────┤\n│ [1] 📱 Connect Device           │\n│ [2] 🔊 Volume Control           │\n│ [3] 🔄 Switch Output            │\n│ [4] 🎤 Toggle Mic Mute          │\n│ [5] ⚙️  Show Status              │\n│ [6] ❌ Disconnect All           │\n├─────────────────────────────────┤\n│ [Q] Quit                        │\n╰─────────────────────────────────╯\n```\n\n## 🛠️ Advanced Usage\n\n### Balance Control\n```bash\nbtaudio balance left 20     # Shift 20% to left\nbtaudio balance right 10    # Shift 10% to right\nbtaudio balance center       # Reset to center\n```\n\n### Audio Testing\n```bash\nbtaudio test                 # Test stereo\nbtaudio test left           # Test left channel\nbtaudio test right          # Test right channel\nbtaudio test mic            # Test microphone\n```\n\n### Device Switching\n```bash\nbtaudio switch speaker      # Disconnect others, connect speaker\nbtaudio disconnect          # Disconnect current device\nbtaudio -                   # Quick disconnect\n```\n\n## 🏗️ Architecture\n\nbtaudio is built with:\n- **Pure Bash** - No external language dependencies\n- **Modular Design** - Clean function separation\n- **Smart Detection** - Automatic audio system detection (PipeWire/PulseAudio)\n- **Error Handling** - Comprehensive error checking with helpful messages\n- **Color Support** - Intelligent terminal capability detection\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with passion by **web3dozie**\n- Inspired by the Linux audio community's needs\n- Special thanks to all contributors and testers\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**No devices found**\n- Ensure Bluetooth service is running: `systemctl status bluetooth`\n- Pair devices first: `bluetoothctl scan on`\n\n**Volume controls not working**\n- Check if PipeWire is running: `systemctl --user status pipewire`\n- Try PulseAudio fallback: `pactl list sinks`\n\n**Colors not displaying**\n- btaudio auto-detects terminal capabilities\n- Force disable with: `NO_COLOR=1 btaudio`\n\n**Mic not switching**\n- Ensure default source is set correctly\n- Use `btaudio fix` for diagnostics\n\n## 📚 Documentation\n\n- [Product Requirements Document](PRD_btaudio.md) - Original vision and specifications\n- [Configuration Guide](docs/CONFIG.md) - Detailed configuration options\n- [API Reference](docs/API.md) - Command reference\n\n## 🔄 Changelog\n\n### v0.1.0 (September 2025)\n- Initial release by web3dozie\n- Core Bluetooth audio management\n- Interactive mode\n- Volume presets and auto-connect\n- Microphone management\n- Balance control (PipeWire)\n- Troubleshooting mode\n- Dynamic status display\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ by \u003ca href=\"https://github.com/web3dozie\"\u003eweb3dozie\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dozie%2Fbtaudio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweb3dozie%2Fbtaudio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb3dozie%2Fbtaudio/lists"}