BlueALSA

bluealsactl is a command-line interface for the BlueALSA D-Bus API (org.bluealsa.Manager1 and org.bluealsa.PCM1). It allows you to inspect the service status, list available Bluetooth services and PCMs, and control PCM properties like volume, mute, and codecs while they are running.

Key Workflow:

1. Use list-services to find running BlueALSA services.
2. Use list-pcms to find valid PCM_PATH values.
3. Use info <PCM_PATH> to inspect a specific PCM's properties (channels, volume, codecs).
4. Use specific commands (codec, volume, mute, etc.) to modify the PCM state.

bluealsactl list-pcms

The ClientDelay property (measured in 1/10 of a millisecond) allows a client to account for its own processing latency.

• For PCM sources: Set this to a value reported by your playback subsystem to account for playback delay.
• For PCM sinks: Use this to adjust the Delay property to compensate for Bluetooth devices that do not report accurate delay values.

The Volume property is an array of bytes, where each byte corresponds to a channel defined by the ChannelMap.

Muting: The highest bit of each byte determines whether that specific channel is muted.

Volume Ranges:

• A2DP: 0-127
• ASHA: 0-127
• SCO: 0-15

BlueALSA provides a consistent interface for volume control via D-Bus or ALSA plugins. It supports two modes:

1. Native Volume Control (Default): Links PCM volume to Bluetooth AVRCP (for A2DP) or HFP/HSP volume control. Local clients and remote devices can both modify it. Local clients are notified of changes made by the remote device.
2. Soft-Volume: Scales PCM samples locally before encoding/after decoding. It does not interact with Bluetooth volume properties. Only local clients can modify it.

Volume Initialization Priority: When a device connects, volume is set in this order:

1. Saved value from previous connection.
2. Value set by --initial-volume.
3. 100%.

Note: For reliable native A2DP volume control, BlueZ version 5.65 or later is recommended.

The daemon supports several Bluetooth profiles. Note that some profiles (like asha-source, hfp-ofono, and midi) require specific compilation support.

Available Profile Names:

• a2dp-source: Advanced Audio Source (streaming audio to connected device)
• a2dp-sink: Advanced Audio Sink (receiving audio from connected device)
• asha-source: Audio Streaming for Hearing Aids Source
• asha-sink: Audio Streaming for Hearing Aids Sink
• hfp-ofono: Hands-Free AG/HF handled by oFono
• hfp-ag: Hands-Free Audio Gateway
• hfp-hf: Hands-Free
• hsp-ag: Headset Audio Gateway
• hsp-hs: Headset
• midi: Bluetooth LE MIDI

Important Notes:

• Enabling hfp-ofono automatically disables hfp-hf and hfp-ag.
• Only one service can register the HFP profile per BlueZ instance; it is automatically registered with every HCI device.

Running BlueALSA simultaneously with PulseAudio or PipeWire (with their Bluetooth modules enabled) is not recommended and can cause conflicts.

Symptoms: BlueALSA may log warnings about UUIDs already being registered in BlueZ: bluealsad: W: UUID already registered in BlueZ [hci0]: ...

Recommendation: For a deterministic setup, disable Bluetooth in PulseAudio or PipeWire. If integration is required, refer to the PulseAudio integration wiki.

The ALSA dmix plugin may ignore requested period and buffer times, which can cause rounding errors when used with the ALSA rate plugin. To ensure stability, explicitly define the hardware period size and buffer size in your ALSA configuration.

Example: Global dmix configuration

To set a period time of 50000 µs and 4 periods for an Intel 'PCH' card, add this to your ALSA configuration:

defaults.dmix.PCH.period_time 50000
defaults.dmix.PCH.periods 4

Example: Custom PCM definition

Alternatively, define a specific PCM (e.g., dmix_rate_fix) that uses dmix with fixed parameters:

pcm.dmix_rate_fix {
    type plug
    slave.pcm {
        type dmix
        ipc_key 12345
        slave {
            pcm "hw:0,0"
            period_time 50000
            periods 4
        }
    }
}

The bluealsa-aplay utility simplifies forwarding audio from a Bluetooth device (capture PCM) to a local playback device (e.g., a built-in sound card).

Play audio from a specific device

bluealsa-aplay XX:XX:XX:XX:XX:XX

List available BlueALSA PCMs

To see a list of all connected Bluetooth devices with audio capabilities:

bluealsa-aplay -L

If you are not using systemd or did not use the --enable-systemd flag, you must manually create the persistent state storage directory.

1. Create a directory named bluealsa under the system local state directory (typically /var/lib).
2. Set the owner to the user account running the bluealsad daemon.
3. Set permissions to rwx------ (0700) to prevent corruption.

Example for a daemon running as user bluealsa:

sudo mkdir /var/lib/bluealsa
sudo chown bluealsa /var/lib/bluealsa
sudo chmod 0700 /var/lib/bluealsa