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

The following instructions demonstrate how to play a WAV file 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.

  • 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 (possibly a couple of minutes) the device you require should pop-up. Hopefully it will have a recognisable name. Here we are looking for an Amazon Echo:

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

  • 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

  • Now you can use ‘aplay’ to send a WAV file. Note aplay only supports WAV and does not support mp3 or any other audio codecs. Substitute in the bluetooth address where shown:

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

  • When the Raspberry Pi is rebooted, the bluetooth 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:

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

Credit for raspberry pi image: Michael H. (“Laserlicht”) / Wikimedia Commons / CC BY-SA 4.0