First – What’s Volumio?

Briefly, Volumio is an open-source, software-based network audio player.
Like similar solutions such as RuneAudio, it is primarily designed to drive specific HiFi modules (DACs) stacked onto micro-computers like the Raspberry Pi to form a cheap, high-quality network based standalone audio player device. And even at the risk of causing shivers to audiophile readers: It’s of course possible to simply plug cheap active-powered loudspeakers or your headphones straight into a Raspberry’s headphone jack to enjoy music from Volumio.

Under the hood, Volumio is a JEOS based on Linux, featuring a set of specific software (mainly audio-related, obviously). The JEOS approach means that Volumio comes with its own operating system and doesn’t have to rely on the configuration and suitability of a users operating system. It’s also able to run on various hardware, ranging from popular silent, power-saving micro-Computers such as Raspberry PIs, Tinkerboxes or Odroids way up to PCs or Laptops.

Being designed specifically for audio only, Volumio doesn’t need a physical screen to display stuff.
In turn, Volumio thus is both very lean from the storage and memory footprint perspective, as well as snappy and stable with regards to controlling and using the underlying device’s hardware.
All in all, that makes it the ideal choice to turn a silent, no-fan, low-power, cheap, dusty old Raspberry into a standalone networked audio player.

Sure, there are ways to tweak Volumio into driving LCD/LED displays or even touch screens and being operated with hardware knobs like play/pause, volume and so on. But in general, it was designed to be headless, meaning it doesn’t require to drive a physical screen. Instead, everything is done via a web-based user interface. And it’s a nice one by the way:

Screenshot of the volumio web interface in desktop and mobile view

Volumio’s web interface in desktop (on the left) and mobile (on the right) view.

What’s the point?

So, to put it simple: Volumio is controlled from a web browser.
Usually, one would start the device (if not running 24h on a low-power Raspi anyway), browse to its interface and tell it to start playing something. Afterwards, just turn off the device or stop playback. And that is that. And it works great.

And it’s all you’ll need …in about 90% of the cases.

The missing 10% problem

You see, for me there are some situations where that “headless” thing has drawbacks.
I’m using Volumio as my work-from-home office music player: This means, that while I’m at my desk in front of the screen, there’s my previously unused Raspi2B, now driving USB-powered speakers to play web radio. Or my spotify “work” playlist. Great. Now imagine I quickly need to mute sound. Or the worst case: Having to skip a song I don’t like.

There’s no easy way of pushing a button. You’ll need its web interface, obviously.

As said above, Volumio is playing because I’m sitting in front of my desktop PC. In turn, I could of course simply have a dedicated browser window/tab open during that time, to access the web UI. But that still doesn’t mean I’ll be able to quickly tell Volumio to mute, skip, etc. And having to switch to a tab or window while reading or typing something means: Interruption. Distraction.

So – I wanted a different approach to control Volumio.

The idea

What I wanted to achieve is to have some keyboard hotkey on my desktop machine “triggering something” to that other Volumio machine to having it mute, change volume, stop, play… and so on. Because: Whenever that Volumio player is playing, I’m at my PC anyway. With the keyboard right at my fingertips. Easy, simple, no-fuzz. Next step thus is to see if there are options how to do that.

The options

From my past as a software tester, I know ways how to automate web interfaces. Sure, I could script something to robotically navigate the web UI and click the respective screen elements. However, that would involve quite some effort and certainly come with lots of overhead. Fortunately though, it’s not even necessary. Because the web interface isn’t the only way to tell Volumio what to do, thanks to its developers.

  1. First, Volumio has a command-line client one can use to send commands. Since that client, by its nature, runs on the very same machine as Volumio itself does, this approach would require me to somehow have to access that command-line client from a different machine. Sure, that’s feasible, but still involves quite some effort. And it “smells” like a brittle thing to construct, doesn’t it?
  2. Secondly, and this is where fun starts, there’s an API that features both a websocket and a REST flavour.

After playing around with the websocket thing for a while I became aware of 2 things: First, my limited understanding. Second, the sheer amount of stuff to handle besides the actual “functional payload” I was looking for: Sending some command somewhere. I thus turned to have a look at the REST API. And just five seconds later it became clear to me, that the easiest way to make use of the volumio API (for the non-developer kind of people) is via its REST API.

Solution: Volumio’s REST API

Basically, you just want to know what command to send from your machine to the Volumio device… and how to do that. Right?
Okay, the “how” part is simple – you’ll do that using curl.

  • On Linux, you’ll likely have curl already – else consult your apt-get, dnf, pacman, …
  • On Macs it should also already come installed, I think, not sure though
  • On Windows, I can’t tell. Should be there with latest 10-something it seems

Eventually, there’s always curl.haxx.se to the rescue.

Next, for the “what” part of the question, the aforementioned Documentation of the REST API is your friend. It has a good selection of useful examples which cover most if not all of the basic player control commands.

So, assuming you want Volumio to toggle between playback and pause… and your Volumio device has the IP of 192.168.1.22… it’ll lead to this command:

curl "http://192.168.1.22/api/v1/commands/?cmd=toggle"

While playing around with the available API commands, I noticed that the simple curl syntax mentioned in the documentation didn’t work in some cases. Enclosing the API command with double quotes fixed that for me. Also, your mileage may vary getting playlists to play via curl if their names include space characters. Not sure if that is a glitch in the software itself or the documentation needs updates.

And that’s your one-line command. Nice and snappy, isn’t it? Go check it out from your command-line (terminal, cmd window, …). And make sure to change the IP address according to your needs. Of course, instead of its IP address, you could also use host name of your volumio player (which is volumio.local unless you haven’t change it since setup).

Next steps

Now we basically have the blueprint for crafting all desired (and supported) commands.
The smartest way of using them (for me, using gnome) is to assign these to the desired keystroke by going over to Settings > Hotkeys.
Your mileage may vary here, depending on your distro, DisplayManager or platform.

That’s what it looks like on my Fedora system running Gnome:

Settings dialog in Fedora32, english, showing custom keyboard shortcuts

The settings dialog of Fedora32 showing custom keyboard shortcuts.

Screenshot of settings dialog to create a custom keyboard shortcut triggering a curl command

A custom keyboard shortcut definition for a curl command to Volumio

I’m happy with it. Especially with the responsiveness of that approach:
In my case, I get an audible reaction from Volumio in less than 1 second after I press the respective hotkeys.

There’s a whole lot of potential which is yet left to be used, but for the moment I have all my requirements fulfilled.
For everything more complex than play/fwd/rew/pause and volume control (since that happens only occasionally) I can still turn to Volumio’s excellent web interface.

Limitations

As I said above, the basic commands are available from the REST API.
There’s much more functionality available with the websocket API, such as setting up and querying playlists and all that.
Also, some features described in the REST API documentation do not work as specified. That could be software glitches, ongoing work-in-progress at Volumio developer’s side, outdated/wrong documentation or a combination of these. Or, that I simply didn’t get stuff right.

For instance, I wanted a hotkey to make Volumio load and play a specific web radio station, but kept getting error responses for the respective command.
As it turned out, that is (was) a broken feature at the time of the writing with an open bug ticket at Volumio’s side.
I worked around that by creating a playlist in Volumio’s web interface, consisting of my favourite web radio stations. Then, I used the command to load and play a playlist, specifying the respective playlist’s name.

I’d be happy to see this post being of help to someone, maybe just to inspire playing around with hotkeys or curl. Have fun!


Share this post:
Facebooktwitterlinkedinmail

Links and recommended further reading:

Copyright notice for artwork used on this page (in addition to these):