Audio Tools

Tools for managing Bluetooth audio with PipeWire/PulseAudio integration.

bt_audio_list

List all audio devices including Bluetooth.

Parameters: None

Returns:

{
  "sinks": [
    {
      "name": "bluez_sink.C8_7B_23_55_68_E8.a2dp_sink",
      "description": "Bose Headphones",
      "bluetooth_address": "C8:7B:23:55:68:E8",
      "volume": 65536,
      "volume_percent": 75,
      "muted": false,
      "state": "running"
    }
  ],
  "sources": [
    {
      "name": "bluez_source.C8_7B_23_55_68_E8.hfp_ag",
      "description": "Bose Headphones (Microphone)",
      "bluetooth_address": "C8:7B:23:55:68:E8",
      "volume": 65536,
      "volume_percent": 100,
      "muted": false,
      "state": "idle"
    }
  ],
  "cards": [
    {
      "name": "bluez_card.C8_7B_23_55_68_E8",
      "bluetooth_address": "C8:7B:23:55:68:E8",
      "active_profile": "a2dp-sink",
      "profiles": ["a2dp-sink", "hfp-hf", "off"]
    }
  ]
}

Example:

bt_audio_list

---

bt_audio_connect

Connect audio profiles to a Bluetooth device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns:

{
  "status": "connected",
  "address": "C8:7B:23:55:68:E8",
  "profiles": ["a2dp-sink", "hfp-hf"]
}

Example:

bt_audio_connect adapter="hci0" address="C8:7B:23:55:68:E8"

Notes:

• Connects A2DP (high-quality audio) and/or HFP (hands-free) profiles
• Device must be paired first
• Automatically registers with PipeWire/PulseAudio

---

bt_audio_disconnect

Disconnect audio profiles from a Bluetooth device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns:

{
  "status": "disconnected",
  "address": "C8:7B:23:55:68:E8"
}

Example:

bt_audio_disconnect adapter="hci0" address="C8:7B:23:55:68:E8"

Notes:

• Disconnects audio profiles only
• Device remains connected for other services

---

bt_audio_set_profile

Switch audio profile for a Bluetooth device.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
profile	string	Yes	Profile: “a2dp”, “hfp”, or “off”

Profiles:

Profile	Quality	Microphone	Use Case
a2dp	High (stereo)	No	Music, videos
hfp	Low (mono)	Yes	Phone calls
off	-	-	Disable audio

Returns:

{
  "status": "profile_changed",
  "address": "C8:7B:23:55:68:E8",
  "profile": "a2dp"
}

Example:

# High-quality for music
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="a2dp"

# Enable microphone for calls
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="hfp"

# Disable audio (stay connected for other profiles)
bt_audio_set_profile address="C8:7B:23:55:68:E8" profile="off"

---

bt_audio_set_default

Set a Bluetooth device as the default audio output.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address

Returns:

{
  "status": "default_set",
  "address": "C8:7B:23:55:68:E8",
  "sink": "bluez_sink.C8_7B_23_55_68_E8.a2dp_sink"
}

Example:

bt_audio_set_default address="C8:7B:23:55:68:E8"

Notes:

• All system audio routes to this device
• Persists until changed or device disconnects

---

bt_audio_volume

Set volume for a Bluetooth audio device.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
volume	integer	Yes	Volume level (0-100, can go up to 150)

Returns:

{
  "status": "volume_set",
  "address": "C8:7B:23:55:68:E8",
  "volume": 75
}

Example:

# Normal volume
bt_audio_volume address="C8:7B:23:55:68:E8" volume=75

# Boost (may distort)
bt_audio_volume address="C8:7B:23:55:68:E8" volume=120

Notes:

• 0-100 is standard range
• 100-150 provides software amplification (may cause distortion)

---

bt_audio_mute

Mute or unmute a Bluetooth audio device.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
muted	boolean	Yes	true to mute, false to unmute

Returns:

{
  "status": "mute_changed",
  "address": "C8:7B:23:55:68:E8",
  "muted": true
}

Example:

# 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

Notes:

• Preserves volume level
• Faster than setting volume to 0