Playing Audio over Bluetooth From a Raspberry Pi (Command Line)

The following instructions demonstrate how to play audio files on the command line over bluetooth from a Raspberry Pi to an external bluetooth speaker.

Using bluetooth on the Raspberry Pi can be somewhat of a frustrating experience as the method tends to vary between the operating system releases and exactly what you want to achieve. These instructions relate specifically to the "bookworm" version of the Raspberry Pi OS which was released on March 12th 2024. See here to find out about your raspberry pi OS release.

Connecting to a Bluetooth Speaker

• Firstly install the package "bluez-alsa-utils":

sudo apt-get install bluez-alsa-utils

• Now reboot

• Start "bluetoothctl"

pi@testpi:~ $ bluetoothctl

• Next you need the bluetooth address for the device. Place the bluetooth speaker or headphones into pairing or discoverable mode.

Type "scan on" at the bluetoothctl prompt

[bluetooth]# scan on

After some time the device you require should pop-up. Patience will be required as it may take several minutes to appear. Hopefully the device will have a recognisable name. Here we are looking for an Amazon Echo:

[NEW] Device 00:F3:61:9A:5F:4C Echo Dot-MWF

Once you have seen the device you require you can disable scanning with:

[bluetooth]# scan off

• The series of hex digits separated by colons is the bluetooth address for the device. Now type "pair" at the bluetooth prompt followed by the bluetooth address:

[bluetooth]# pair 00:F3:61:9A:5F:4C

• You should see some indication on your device that pairing has been successful and in the terminal you should see:

Pairing successful

The device should now also be connected, which is shown by the prompt changing to the name of the device.

[Echo Dot-MWF]#

• However I have often found I need to disconnect and then reconnect before it works for some reason and so would recommend this is done. Disconnect like this:

[Echo Dot-MWF]# disconnect

Then reconnect using the bluetooth address for the device:

[bluetooth]# connect 00:F3:61:9A:5F:4C

• Now exit bluetoothctl.

[Echo Dot-MWF]# exit

Playing Audio Over Bluetooth

• Now you can use 'aplay', which should be installed by default, to send a WAV file. Note aplay only supports WAV and does not support mp3 or any other audio codecs. If you try and play anything but a wav file you'll get a nasty sound through the speaker.

aplay -D bluealsa my_audio_file.wav

If you are connected to more than one speaker, you can specify the exact device to send the audio to like this:

aplay -D bluealsa:DEV=00:F3:61:9A:5F:4C my_audio_file.wav

If you'd like a more sophisticated player that supports more codecs like mp3 or other common file types, then try installing mplayer:

sudo apt-get install mplayer

mplayer -ao alsa:device=bluealsa my_audio_file.mp3

Auto Connecting At Boot

• When the Raspberry Pi is rebooted, the bluetooth device will be disconnected. You can auto connect on reboot by "trusting" the device like this in bluetoothctl:

[Echo Dot-MWF]# trust 00:F3:61:9A:5F:4C

[CHG] Device 00:F3:61:9A:5F:4C Trusted: yes
Changing 00:F3:61:9A:5F:4C trust succeeded

Error Messages

The following error messages can indicate "bluez-alsa-utils" package is not installed (reboot after installation):

pi@testpi:~ $ aplay -D bluealsa:DEV=00:F3:61:9A:5F:4C,PROFILE=a2dp audio_file.wav
ALSA lib pcm.c:2666:(snd_pcm_open_noupdate) Unknown PCM bluealsa:DEV=00:F3:61:9A:5F:4C,PROFILE=a2dp
aplay: main:831: audio open error: No such file or directory

pi@testpi:~ $ aplay -D bluealsa:DEV=00:F3:61:9A:5F:4C,PROFILE=a2dp audio_file.wav 
D: bluealsa-pcm.c:1309: Getting BlueALSA PCM: PLAYBACK 00:F3:61:9A:5F:4C a2dp
ALSA lib bluealsa-pcm.c:1313:(_snd_pcm_bluealsa_open) Couldn't get BlueALSA PCM: The name org.bluealsa was not provided by any .service files
aplay: main:831: audio open error: No such device

The following error message can indicate that the Raspberry Pi is not connected to the bluetooth device. Go into the bluetoothctl utility and connect to the device (see above).

pi@testpi:~ $ aplay -D bluealsa:DEV=00:F3:61:9A:5F:4C,PROFILE=a2dp audio_file.wav 
D: bluealsa-pcm.c:1309: Getting BlueALSA PCM: PLAYBACK 00:F3:61:9A:5F:4C a2dp
ALSA lib bluealsa-pcm.c:1313:(_snd_pcm_bluealsa_open) Couldn't get BlueALSA PCM: PCM not found
aplay: main:831: audio open error: No such device