Experimental plugin: Wireless (Bluetooth & Airplay) Output Manager for Volumio 4

jhscann · August 11, 2026, 9:02pm

Updated 27 August 2026: the current experimental version includes Bluetooth and now AirPlay output. Installation instructions below now point to the latest tested branch. However, please read the latest post for updated and important information

I’ve been working on an experimental Volumio 4 plugin called Wireless Output Manager .

The first implemented output type is Bluetooth. It allows Volumio playback to be sent to an external Bluetooth speaker, with speaker discovery, pairing, reconnection, manual audio routing and diagnostics.

This is an early community-testing version. It has not been submitted to the Volumio plugin beta channel.

Tested configuration

The plugin has currently been tested with:

Raspberry Pi running Volumio 4 / Bookworm
Existing BlueZ and BlueALSA installation
JBL PartyBox 100 Bluetooth speaker
iFi USB DAC as the normal Volumio output
Switching in both directions between the Bluetooth speaker and the USB DAC
Reconnection, reset, reinstall and uninstall workflows

Other Bluetooth speakers, Volumio devices and audio configurations have not yet been tested.

Current features

Search for nearby Bluetooth speakers
Pair, trust, connect and save a speaker in one operation
Reconnect a saved speaker
Optional automatic reconnection
Manually choose between the Bluetooth speaker and Volumio’s default audio output
Bluetooth, ALSA, MPD and audio-stack diagnostics
Exportable diagnostic reports
Guarded BlueALSA output configuration with verification and rollback
Plugin-only reset that preserves system Bluetooth pairings
Conservative uninstall that preserves Bluetooth pairings and system packages

The plugin does not install or replace BlueALSA, PulseAudio or PipeWire. It also does not edit /etc/mpd.conf directly.

Important limitations

This version currently supports audio routing only when BlueALSA is already installed and configured on the Volumio device.

Switching audio destinations stops playback. After the switch completes, press Play again. The current track will restart from the beginning.

Switching can take several seconds while MPD releases one audio device and opens the other.

Some speakers that require a PIN or interactive confirmation may need to be paired manually using bluetoothctl .

Volume control

With Volumio’s Mixer Type set to Hardware , Bluetooth audio is effectively sent at 100%. Volumio’s volume control will continue to control the physical DAC rather than the Bluetooth output.

Select Software mixer mode in Volumio Playback Options if you want the Volumio volume control to affect Bluetooth playback.

Installation

SSH into the Volumio device and run:

cd /tmp

git clone \
  --branch feat/wireless-output-codecs \
  --single-branch \
  https://github.com/jhscann/volumio-plugins-sources-bookworm.git \
  wireless-output-manager-src

cd /tmp/wireless-output-manager-src/wireless_output_manager

git rev-parse --short HEAD
volumio plugin install

Accept the warning for installing an unverified plugin.

After installation:

Open the Volumio Plugins page.
Enable Wireless Output Manager .
Open the plugin settings.

The source checkout under /tmp may disappear after a reboot. This does not remove the installed plugin.

Adding a speaker

Put the Bluetooth speaker into pairing mode.
Open Plugins → Wireless Output Manager .
Select Search for speakers .
Wait approximately 12 seconds.
Choose the speaker under Available speakers .
Select Use selected speaker .
Under Choose where music plays , select Play on Bluetooth speaker .
Wait for the route change to complete, then press Play.

A speaker already paired with the Volumio device will not normally need to be placed into pairing mode again.

To return to the normal output selected in Volumio Playback Options:

Select Play on default audio output .
Wait for the switch to complete.
Press Play.

Updating the experimental version

First select Play on default audio output , then remove the existing plugin through Volumio’s Plugins page.

If the source checkout still exists:

cd /tmp/wireless-output-manager-src
git pull --ff-only

cd wireless_output_manager
volumio plugin install

If the checkout has disappeared, repeat the original installation commands.

Enable the plugin again after installation. Existing system Bluetooth pairings are preserved, so the speaker should not normally require pairing mode again.

Uninstalling

Before uninstalling, select Play on default audio output .

Remove the plugin through Volumio’s Plugins page. Uninstalling preserves:

System Bluetooth pairings
BlueZ and audio-stack packages
Volumio’s MPD configuration
Exported diagnostics under /data/INTERNAL

Diagnostics and reporting problems

Run Diagnostics → Run diagnostics , followed by Export debug log if needed.

Diagnostic reports are written to:

/data/INTERNAL/wireless-output-manager/

Before sharing a report, please review its contents for any information you do not want to post publicly.

When reporting results, please include:

Volumio version
Raspberry Pi or device model
Bluetooth speaker make and model
Whether BlueALSA, PulseAudio or PipeWire is installed
The action that failed
The exact error shown
Whether playback through the normal audio output still works

Source code and documentation

Feedback and test results from other Volumio 4 and Bluetooth speaker configurations would be very welcome.

jhscann · August 12, 2026, 10:52am

Update: improved support for multiple Bluetooth speakers

A new update is now available, with much better handling for people who have more than one Bluetooth speaker paired with Volumio.

The plugin now keeps only one Bluetooth audio speaker connected at a time. Other speakers remain safely paired, so you can switch between them without repeating the pairing process.

This fixes an issue where two connected speakers could interfere with BlueALSA. For example, switching off an inactive speaker could previously interrupt playback on the speaker that was actually in use.

The updated workflow is:

Search for speakers.
Select the speaker you want.
Choose Use selected speaker.
The plugin disconnects any other connected audio speaker while preserving its pairing.
Choose Play on Bluetooth speaker.
Wait for the route change, then press Play.

Speaker selection and audio routing remain separate, deliberate steps. This avoids unexpected output changes and keeps the manual-routing behaviour predictable.

Clearer speaker list

The speaker selector now shows useful state information:

selected — the speaker currently saved by the plugin
connected — an active Bluetooth connection exists
paired — the speaker remains paired with the system
audio — BlueZ has confirmed a supported audio profile
unidentified device — the device has not yet exposed enough information to confirm that it is a speaker

Devices positively identified as non-audio are hidden. Unidentified devices remain available because some speakers expose their audio capabilities only after pairing.

The UI also warns when multiple Bluetooth audio speakers are connected and explains what Use selected speaker will do.

Confirmed testing

The updated version has now been tested successfully with:

JBL PartyBox 100
Sony SRS-X7
iFi USB DAC as the default Volumio output

Switching was tested in both directions:

JBL → Sony
Sony → JBL

In each case:

only the selected speaker remained connected;
both speakers remained paired;
the default iFi output remained available;
unrelated Bluetooth devices were left untouched;
switching off the inactive speaker did not interrupt playback.

Please note that there is still no automatic fallback if the active Bluetooth speaker is switched off. Choose Play on default audio output manually, wait for the route change, then press Play.

Updating

First choose Play on default audio output, then uninstall the existing plugin from Volumio’s Plugins page.

SSH into the Volumio device and run:

cd /tmp

git clone --branch feat/wireless-output-manager --single-branch \
  https://github.com/jhscann/volumio-plugins-sources-bookworm.git \
  wireless-output-manager-latest

cd /tmp/wireless-output-manager-latest/wireless_output_manager

git rev-parse --short HEAD

The current tested revision is:

f4596e5e

Install it with:

volumio plugin install

Accept the unverified-plugin warning, then enable Wireless Output Manager from the Plugins page.

Existing system Bluetooth pairings are preserved, so previously paired speakers should not normally need pairing mode again.

Links

Thanks to everyone willing to try this experimental version. Reports from other Volumio 4 devices and Bluetooth speakers would be very welcome!

jhscann · August 12, 2026, 1:25pm

A quick update on Wireless Output Manager for Volumio 4:

Bluetooth speakers and headphones are now working reliably in testing, including JBL and Sony speakers and AirPods Pro.

Recent improvements include:

Clearer speaker status in the device list
Easier switching between paired speakers
Only the selected audio device is connected
Offline devices fail safely without disrupting the current output
Paired devices can be forgotten even when switched off
Improved setup guidance and troubleshooting messages

Audio routing remains deliberately manual: if a Bluetooth device becomes unavailable, select Play on default audio output . This avoids unpredictable automatic switching.

The plugin currently uses SBC. Experimental support for additional codecs such as aptX, aptX HD and LDAC is in the planning.

Installation instructions and current source are available here:

Wireless Output Manager on GitHub

This is still an experimental community preview, so feedback and results from different Volumio 4 systems and Bluetooth devices are very welcome.

balbuze · August 13, 2026, 4:54pm

Hello!
Thank you for your work.
I have a similar plugin, but in alpha state for month…
I tested your with a Bose speaker and it works, rather well!
Well done!
Sometimes the volume mixer is reset between tracks, but I can’t test deeply now!
Keep testing and when ready : GitHub - volumio/volumio-plugins-sources-bookworm · GitHub

tweed77 · August 13, 2026, 5:09pm

The plugin works - will it work with the standard or premium license Volumio ?

balbuze · August 13, 2026, 5:19pm

Using a plugin is not linked to a license!
So, yes, it may work

jhscann · August 13, 2026, 5:34pm

I am attempting to resolve a conflict between this plugin and the Surface Dial plugin. When the Surface Dial times out for power saving, it causes the BT audio to stutter and sometimes fail. Until that is resolved I won’t submit. At the moment it looks like they cannot run on the same adapter so I will test the Surface Dial plugin on a USB BT adapter to see if the conflict is resolved.

jhscann · August 14, 2026, 4:34pm

Update: multi-adapter Bluetooth support

A positive update on the Surface Dial conflict mentioned above.

Testing confirmed that Bluetooth audio and the Surface Dial can work reliably together when they use separate Bluetooth adapters:

Bluetooth speaker on the Raspberry Pi’s built-in adapter
Surface Dial on a USB Bluetooth adapter

Previously, Wireless Output Manager could try to reconnect the speaker through whichever adapter Linux considered the default. Because adapter numbering can change after a reboot, this could leave the speaker paired on one adapter while the plugin attempted to connect through another.

The plugin now finds the adapter that actually owns the speaker’s pairing and connects directly through it. It does not save unreliable names such as hci0 or hci1, change the default adapter, or interfere with unrelated Bluetooth devices.

The updated version has been tested successfully on a Raspberry Pi 5 with:

JBL PartyBox 100 on the built-in Bluetooth adapter
Microsoft Surface Dial on a TP-Link UB400
Both adapter numbers changing after reboot
Surface Dial sleep, disconnect and reconnection during continuous Bluetooth playback

Playback remained uninterrupted throughout the Dial sleep and wake cycle.

For ordinary installations with one Bluetooth adapter, there should be no visible change—the plugin simply resolves the correct adapter internally. This is general multi-adapter support and is not specific to the Surface Dial.

Please note that this does not make Bluetooth audio and an active Bluetooth remote reliable on the same radio. A second adapter is still recommended where the two interfere.

Installing this test update

First select Play on default audio output, then uninstall the existing plugin from Volumio’s Plugins page.

SSH into Volumio and run:

cd /tmp

git clone \
  --branch fix/wireless-output-adapter-selection \
  --single-branch \
  https://github.com/jhscann/volumio-plugins-sources-bookworm.git \
  wireless-output-manager-adapter-fix

cd /tmp/wireless-output-manager-adapter-fix/wireless_output_manager

git rev-parse --short HEAD

The tested revision is:

d9a0358d

Install it with:

volumio plugin install

Accept the unverified-plugin warning, then enable Wireless Output Manager from the Plugins page. Existing Bluetooth pairings should normally be preserved.

Source and change details:

Reports from other single- and multi-adapter Volumio 4 systems would be very welcome.

@balbuze - I will attempt to implement aptX before pushing to beta channel for review.

HeadGeek · August 18, 2026, 4:49pm

The installation was seamless and the options are quite clear. The plugin installed fine and found my JBL GO2 speaker nearby but couldn’t play music on it, giving this error.

I will keep trying to see if I can get it working.

Regards,

jhscann · August 19, 2026, 6:26pm

hi @HeadGeek … I was not ignoring you, I was readying the next version, see post coming next

jhscann · August 19, 2026, 6:41pm

Update: codec support, safer setup and more predictable switching

A larger Wireless Output Manager update is now available for testing. There have been a few twists and turns since the last post, particularly around multiple speakers, Bluetooth adapters, codec changes and volume behaviour, but the plugin is now in a much better state.

Thank you to @balbuze for testing with a Bose speaker and for flagging the volume mixer behaviour, and to @HeadGeek for testing the JBL GO2 and reporting the connection failure. Those reports helped expose an important difference between a device merely being paired and its Bluetooth audio stream actually being ready.

What has changed

The plugin now:

Supports SBC, aptX, aptX HD and LDAC where the receiving device supports them.
Offers Automatic codec selection or a manual codec choice.
Waits for the BlueALSA audio stream to become ready before presenting the device as playable.
Gives clearer messages when pairing succeeds but the audio connection does not.
Handles slow or awkward Bluetooth devices more patiently.
Keeps only the selected Bluetooth audio device connected.
Supports paired speakers across multiple Bluetooth adapters, even if Linux changes the hci0 and hci1 numbering after a reboot.
Allows any paired audio device to be forgotten, even when it is switched off.
Handles Bluetooth command failures without restarting or crashing Volumio.
Prevents direct live switching between Bluetooth devices, which proved unreliable.

AAC is not included because the BlueALSA build supplied on the test system does not contain AAC support. The plugin deliberately does not replace Volumio’s system Bluetooth packages.

aptX Adaptive is also not available, although some aptX Adaptive headphones may negotiate ordinary aptX or aptX HD.

Devices used during testing

Testing has included:

JBL PartyBox 100
JBL Clip 3
JBL GO2, currently awaiting a retest from @HeadGeek
Yamaha YH-E700A
KEF Porsche Design Space One Wireless
soundcore P31i
Sony WF-1000XM4
Beats Fit Pro
OpenRun by Shokz
AirPods Pro
Sony SRS-X7

Confirmed codec results include:

LDAC on the soundcore P31i
aptX HD on the Yamaha YH-E700A
aptX on the KEF Space One Wireless
SBC fallback on devices without another compatible codec

The Yamaha reported aptX HD at 24-bit, 48 kHz and sounded excellent during testing.

Adding a device

The revised workflow is:

Stop playback or return to the default audio output.
Put the speaker or headphones into pairing mode. The pairing light should normally be flashing.
Open Wireless Output Manager.
Select Search for speakers .
Choose the device from the list.
Select Select and connect .
Wait until the plugin confirms that the Bluetooth audio stream is ready.
Choose the codec and a cautious Bluetooth stream volume.
Select Play through selected Bluetooth device .
Press Play.

Some devices save the pairing but stop accepting the audio connection immediately afterwards. The JBL Clip 3 did this during testing. Pressing its Bluetooth button again until the pairing light flashed, followed by Reconnect selected device , allowed it to connect successfully.

The plugin now explains this rather than simply displaying a raw Bluetooth command error.

Switching devices

Switching remains deliberately manual. This gives the user maximum control and avoids music unexpectedly moving between outputs.

To change from one Bluetooth device to another:

Stop playback.
Select Return to default audio output .
Choose the next paired device.
Select Select and connect .
Select Play through selected Bluetooth device .
Press Play.

There is no automatic fallback if the active Bluetooth speaker is switched off. Return to the default audio output manually.

This is not seamless handover. Switching stops playback and, depending on the source, the track may restart. It is predictable, however, which I think is preferable for an experimental output plugin.

Important volume warning

There can be three separate volume controls:

Volumio software volume
Bluetooth stream volume , managed through BlueALSA
The physical volume on the speaker or headphones

These controls are not always synchronised. Starting an A2DP stream or changing codec can also cause Volumio’s displayed software volume to return to 100%, even when the Bluetooth stream itself remains at a safer level.

The plugin therefore uses a cautious Bluetooth stream level during setup and provides a separate control for it.

Please keep headphones off your head until setup is complete. Start with the Bluetooth stream volume and the headphones’ physical volume low, begin playback, then increase them gradually.

If Volumio is configured with a hardware mixer, its volume control normally applies to the regular DAC rather than the Bluetooth device. Use Software mixer mode if you want Volumio’s volume control to affect Bluetooth playback, but still check the other two levels carefully.

Forgetting a device

Open Device Management , select the paired device and choose Forget pairing .

This works even if the device is switched off. It removes the system Bluetooth pairing, so any other software using that pairing will also lose it. The device must be placed into pairing mode before it can be added again.

Reset plugin setup is different. It clears the plugin’s selected device, routing and codec preferences, but preserves system Bluetooth pairings.

Updating the experimental plugin

First select Return to default audio output , then remove the existing Wireless Output Manager installation from Volumio’s Plugins page. Existing Bluetooth pairings are preserved.

SSH into Volumio and run:

cd /tmp

git clone \
  --branch feat/wireless-output-codecs \
  --single-branch \
  https://github.com/jhscann/volumio-plugins-sources-bookworm.git \
  wom-codecs-20260819

cd /tmp/wom-codecs-20260819/wireless_output_manager

git rev-parse --short HEAD
volumio plugin install

Accept the unverified plugin warning, then enable Wireless Output Manager from the Plugins page.

The current tested revision is:

78ec9313

Source and documentation:

Wireless Output Manager on GitHub

Current tested commit

For now I will continue pushing experimental builds to the feat/wireless-output-codecs branch. If testing across more Volumio 4 systems is positive, I will prepare it for submission to the Volumio Bookworm plugin repository.

More testing would be very welcome, particularly with the JBL GO2, Bose speakers, different Raspberry Pi models and both single-adapter and multi-adapter installations. Please include the device model, codec selected, volume configuration and the exact message shown if something fails.

HeadGeek · August 19, 2026, 6:42pm

@jhscann - didn’t think you’re ignoring me at all. I was just giving you some feedback and I do feel it’s a great start on what would be a real nice plugin. Quite aware that all this is volunteer work that’s done ‘as and when’. looking forward to the next iteration.

Regards,

HeadGeek · August 20, 2026, 3:02pm

Hi @jhscann

Great job
Followed your instructions to uninstall and then install the latest plugin and everything works great now.

The JBL GO2 connected and started playback at 10% and I was able to control it perfectly using the plugin settings.

Going to install the plugin now on my other Volumio unit running on RPi4B.

Regards,

HeadGeek · August 20, 2026, 3:45pm

Hello @jhscann,

Installed the plugin on my second Volumio running RPi4B and everything went well. I tried to install using your last posting but of course that didn’t work so I installed from the source on GitHub and everything worked fine.

I am now listening to Volumio on my Srythm NC35 BT headphones and the codec and Volume control settings worked as they should:

Also confirm it works with my Vizio soundbar in Bluetooth mode.

Also tested successfully with Soundcore P30i earbuds.

Great job

Regards,

vmiguel · August 22, 2026, 10:54pm

Is it suposed to work on a Dell Wise 3040? Or maybe in the future?

For now, it installs, and when trying to pair with a Ikea Vapeby Gen3 speaker, nothing hapens.

EDIT: I should be clearer: the plugin opens, i click on “Search for speakers”, and after sometime I see a notification stating that it did not find any speaker.

jhscann · August 23, 2026, 4:23pm

I don’t think that device has native Bluetooth hardware. Do you have a USB adapter plugged in?

Try this and see what comes back:

bluetoothctl list

jhscann · August 23, 2026, 4:42pm

If you have the version with BT, I also read…

If you are running alternative operating systems like Linux or Android, be aware that some users report the internal M.2 slot lacks the required UART routing to make the Bluetooth portion of the internal M.2 card work, making a USB Bluetooth dongle the most reliable workaround

vmiguel · August 23, 2026, 9:20pm

Well, of course I looked for BT on the System Information plugin, and saw something about BT with a version number, so I was sure that I had BT… on a second look, it’s just the software capabilities

I’ll try tomorrow with a normal BT dongle and report back.

With a “special for audio” Creative BT dongle (not using your plugin) I got too much stutter if I change the volume.

jhscann · August 24, 2026, 5:21am

I look forward to you feedback @vmiguel
I have tested on RPi mostly so other hardware reports are interesting.

Jurgen_Werni · August 26, 2026, 8:36am

Hallo jhscann, Works perfectly with JBL TUNE 510BT headphones and Fresh 342200230n Rebel 1ARB5000 speakers. On a Mac Mini a1347 from 2010.Many thanks and best regards, Jürgen