Bluetooth
The built-in Bluetooth extension enables high-quality audio streaming and device management for supported devices. It supports aptX, LDAC, and SBC XQ+ codecs, with metadata display when available. The extension can function as a Bluetooth receiver or transmitter, automatically switching based on the connected device, and Bluetooth devices can be scanned, connected, and managed via D-Bus.
WARNING
The Raspberry Pi may experience occasional random disconnects or connection issues when switching between devices. Once a connection is successfully established, streaming and metadata functionality should work reliably.
https://github.com/berry-audio/berryaudio/tree/master/bluetooth
Methods
adapter_get_state
adapter_get_state
Gets the current state of the Bluetooth adapter.
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.adapter_get_state",
"id": 3
}Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"powered": false,
"discoverable": false,
"pairable": true
}
}| Property | Type | Description |
|---|---|---|
| powered | boolean | Bluetooth power on off state |
| discoverable | boolean | Bluetooth discoverable |
| pairable | boolean | Bluetooth pairable |
adapter_set_state
adapter_set_state
Sets the current power state of the Bluetooth adapter. Also makes it discoverable and pairable.
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.adapter_set_state",
"params": {
"state": true
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| state | boolean | Yes | true | Powers on bluetooth adapter |
false | Powers off bluetooth adapter |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"powered": false,
"discoverable": false,
"pairable": true
}
}| Property | Type | Description |
|---|---|---|
| powered | boolean | Bluetooth power on off state |
| discoverable | boolean | Bluetooth discoverable |
| pairable | boolean | Bluetooth pairable |
devices
devices
Scans and gets list of available bluetooth devices
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.devices",
"params": {
"rescan": true
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| rescan | boolean | No | true | Rescans devices |
false | (Default) Gets cached devices |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": [
{
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": true,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
//...other devices
]
}| Property | Type | Description |
|---|---|---|
| address | string | The MAC address of the Bluetooth device |
| name | string | The name of the Bluetooth device |
| profile | string | null | The Bluetooth profile used by the device, if any |
| alias | string | The user-friendly alias of the device |
| icon | string | The icon type representing the device |
| paired | boolean | Whether the device is paired |
| trusted | boolean | Whether the device is trusted |
| connected | boolean | Whether the device is currently connected |
| soft_volume | boolean | Whether device supports software-controlled volume |
| volume | number | null | Volume level of the device, if available |
| channels | number | null | The number of audio channels, if applicable |
| audio_codec | string | null | The audio codec currently in use, if any |
| sample_rate | number | null | The audio sample rate in Hz, if available |
| bit_depth | number | null | The audio bit depth, if available |
| uuids | strings[] | List of service UUIDs supported by the device |
device
device
Gets current connected device information from mac address
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.device",
"params": {
"address": "14:4E:FD:88:AE:B1"
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | No | null | (Default) Gets connected device info |
| {macaddress} | Gets address specific device info |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": true,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
}| Property | Type | Description |
|---|---|---|
| address | string | The MAC address of the Bluetooth device |
| name | string | The name of the Bluetooth device |
| profile | string | null | The Bluetooth profile used by the device, if any |
| alias | string | The user-friendly alias of the device |
| icon | string | The icon type representing the device |
| paired | boolean | Whether the device is paired |
| trusted | boolean | Whether the device is trusted |
| connected | boolean | Whether the device is currently connected |
| soft_volume | boolean | Whether device supports software-controlled volume |
| volume | number | null | Volume level of the device, if available |
| channels | number | null | The number of audio channels, if applicable |
| audio_codec | string | null | The audio codec currently in use, if any |
| sample_rate | number | null | The audio sample rate in Hz, if available |
| bit_depth | number | null | The audio bit depth, if available |
| uuids | strings[] | List of service UUIDs supported by the device |
connect
connect
Connects to the bluetooth device with given mac-address
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.connect",
"params": {
"address": "14:4E:FD:88:AE:B1"
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | yes | {macaddress} | Mac-address |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": true
}Returns true if request was sent successfully.
disconnect
disconnect
Disconnects from the bluetooth device with given mac-address
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.disconnect",
"params": {
"address": "14:4E:FD:88:AE:B1"
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | yes | {macaddress} | Mac-address |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": true
}Returns true if request was sent successfully.
remove
remove
Removes and deletes the bluetooth device with given mac-address
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.remove",
"params": {
"address": "14:4E:FD:88:AE:B1"
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | yes | {macaddress} | Mac-address |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": true
}Returns true if request was sent successfully.
trust
trust
Trusts the bluetooth device with given mac-address.
NOTE
This is automatically done when the device is connected for the first time.
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.trust",
"params": {
"address": "14:4E:FD:88:AE:B1"
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | yes | {macaddress} | Mac-address |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": true
}Returns true if request was sent successfully.
set_volume
set_volume
Sets the volume of the bluetooth device with given mac-address.
NOTE
This only works if device (Raspberry Pi) is connected as the source
Request
json
{
"jsonrpc": "2.0",
"method": "bluetooth.set_volume",
"params": {
"address": "14:4E:FD:88:AE:B1",
"volume": 100,
"soft_volume": true,
"muted": false
},
"id": 3
}| Param | Type | Required | Value | Description |
|---|---|---|---|---|
| address | string | yes | {macaddress} | Mac-address |
| volume | number | yes | 100 | Supports 0-100 |
| soft_volume | boolean | yes | true | (Default) Use software volume |
false | Use hardware volume | |||
| muted | boolean | yes | false | (Default) Mute |
false | Un-Mute |
Response
json
{
"jsonrpc": "2.0",
"id": 3,
"result": true
}Returns true if request was sent successfully.
Events
bluetooth_device_connected
bluetooth_device_connected
Event triggered when a bluetooth device is connected
json
{
"event": "bluetooth_device_connected",
"device": {
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": true,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
}| Property | Type | Description |
|---|---|---|
| event | string | Event name |
| device | object | Check method device response result |
bluetooth_device_disconnected
bluetooth_device_disconnected
Event triggered when a bluetooth device is disconnected
json
{
"event": "bluetooth_device_disconnected",
"device": {
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": false,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
}| Property | Type | Description |
|---|---|---|
| event | string | Event name |
| device | object | Check method device response result |
bluetooth_device_updated
bluetooth_device_updated
Event triggered when a bluetooth device information is updated
json
{
"event": "bluetooth_device_updated",
"device": {
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": true,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
}| Property | Type | Description |
|---|---|---|
| event | string | Event name |
| device | object | Check method device response result |
bluetooth_device_removed
bluetooth_device_removed
Event triggered when a bluetooth device is removed or deleted
json
{
"event": "bluetooth_device_removed",
"device": {
"address": "14:4E:FD:88:AE:B1",
"name": "My Amp",
"profile": "A2DP-source",
"alias": "My Amp",
"icon": "audio-headset",
"paired": true,
"trusted": true,
"connected": false,
"soft_volume": true,
"volume": 100,
"channels": 2,
"audio_codec": "SBC",
"sample_rate": 48000,
"bit_depth": "S16_LE",
"uuids": [
"0000110a-0000-1000-8000-00805f9b34fb",
"0000110b-0000-1000-8000-00805f9b34fb",
"0000110c-0000-1000-8000-00805f9b34fb",
"0000110e-0000-1000-8000-00805f9b34fb",
"00001200-0000-1000-8000-00805f9b34fb",
"00006666-0000-1000-8000-00805f9b34fb"
]
}
}| Property | Type | Description |
|---|---|---|
| event | string | Event name |
| device | object | Check method device response result |
bluetooth_state_changed
bluetooth_state_changed
Event triggered when a bluetooth adapter state is updated
json
{
"event": "bluetooth_state_changed",
"state": {
"powered": false,
"discoverable": false,
"pairable": false
}
}| Property | Type | Description |
|---|---|---|
| event | string | Event name |
| state | object | Check method adapter_get_state response result |