Audio Control

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