Ryan Malloy
9d1c0f3e0f
23-page docs site following diataxis principles with guides, reference, and explanation sections covering all 61 MCP tools. Bluetooth-themed design with Pagefind search.
4.6 KiB
4.6 KiB
| title | description |
|---|---|
| Audio Control | Manage Bluetooth audio devices with PipeWire/PulseAudio integration |
import { Aside } from '@astrojs/starlight/components';
mcbluetooth integrates with PipeWire and PulseAudio to provide seamless Bluetooth audio control.
List Audio Devices
bt_audio_list
Returns all audio devices including Bluetooth:
{
"sinks": [
{
"name": "bluez_sink.C8_7B_23_55_68_E8.a2dp_sink",
"description": "Bombay",
"bluetooth_address": "C8:7B:23:55:68:E8",
"volume": 65536,
"volume_percent": 75,
"muted": false,
"state": "running"
}
],
"sources": [...],
"cards": [...]
}
Connect Audio
After pairing a device, connect its audio profiles:
bt_audio_connect adapter="hci0" address="C8:7B:23:55:68:E8"
This connects A2DP (high-quality audio) and/or HFP (hands-free) profiles.
Audio Profiles
Bluetooth audio devices support different profiles:
| Profile | Quality | Microphone | Use Case |
|---|---|---|---|
| A2DP | High (stereo) | No | Music, videos |
| HFP | Low (mono) | Yes | Phone calls |
| HSP | Low (mono) | Yes | Legacy headsets |
Switch Profiles
# High-quality stereo for music
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="a2dp"
# Hands-free for calls (enables microphone)
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="hfp"
# Disable audio (but stay connected for other profiles)
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="off"
Set Default Output
Make a Bluetooth device the default audio output:
bt_audio_set_default address="C8:7B:23:55:68:E8"
Volume Control
Set Volume
# Set to 75%
bt_audio_volume address="C8:7B:23:55:68:E8" volume=75
# Boost to 120% (use carefully)
bt_audio_volume address="C8:7B:23:55:68:E8" volume=120
Mute/Unmute
# Mute
bt_audio_mute address="C8:7B:23:55:68:E8" muted=true
# Unmute
bt_audio_mute address="C8:7B:23:55:68:E8" muted=false
Disconnect Audio
bt_audio_disconnect adapter="hci0" address="C8:7B:23:55:68:E8"
This disconnects audio profiles but keeps the device connected for other services.
Common Workflows
Connect Headphones for Music
# Connect and set up for music
bt_connect adapter="hci0" address="C8:7B:23:55:68:E8"
bt_audio_connect adapter="hci0" address="C8:7B:23:55:68:E8"
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="a2dp"
bt_audio_set_default address="C8:7B:23:55:68:E8"
bt_audio_volume address="C8:7B:23:55:68:E8" volume=70
Prepare for Video Call
# Switch to HFP for microphone support
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="hfp"
Return to Music After Call
# Switch back to A2DP for high-quality audio
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="a2dp"
Troubleshooting
No Sound from Device
- Check the device is connected:
bt_device_info adapter="hci0" address="..." - Verify audio profile is connected:
bt_audio_list - Ensure it's set as default:
bt_audio_set_default address="..." - Check volume isn't zero:
bt_audio_volume address="..." volume=70
Audio Cuts Out
- Interference: Move away from WiFi routers, microwaves
- Distance: Stay within 10 meters of the adapter
- Battery: Low battery can cause audio issues
- Profile: Try switching profiles and back
Poor Audio Quality
# Ensure A2DP (not HFP) is active
bt_audio_set_profile address="..." profile="a2dp"
HFP is mono and lower quality — it's for calls, not music.
Microphone Not Working
# Switch to HFP or HSP
bt_audio_set_profile address="..." profile="hfp"
A2DP doesn't support microphone input.
Device Shows "Off" Profile
The device may need reconnection:
bt_audio_disconnect adapter="hci0" address="..."
bt_audio_connect adapter="hci0" address="..."
Audio Codecs
Audio quality depends on the codec negotiated between devices:
| Codec | Quality | Latency | Notes |
|---|---|---|---|
| SBC | Good | Medium | Universal, default |
| AAC | Better | Medium | Apple devices |
| aptX | Better | Low | Qualcomm devices |
| aptX HD | Best | Low | High-res audio |
| LDAC | Best | Medium | Sony devices |