---
title: Audio Control
description: 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:

```json
{
  "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"
```

<Aside type="tip">
Switch to HFP before a video call to enable the headset microphone, then back to A2DP for music.
</Aside>

## 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
```

<Aside type="caution">
Volume above 100% may cause distortion or hearing damage.
</Aside>

### 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

1. Check the device is connected: `bt_device_info adapter="hci0" address="..."`
2. Verify audio profile is connected: `bt_audio_list`
3. Ensure it's set as default: `bt_audio_set_default address="..."`
4. 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 |

<Aside type="note">
Codec selection is automatic based on device capabilities. mcbluetooth doesn't directly control codec selection — this is handled by BlueZ and PipeWire.
</Aside>