RoonCommandLine provides command line tools to control a Roon Core audio streaming system
Table of contents
Click here to expand/collapse
Overview
The Roon Command Line project provides Bash and Python scripts to enable command line control of the Roon audio system over a local network.
Note: No modifications are made to the Roon Core. The RoonCommandLine package resides entirely on other systems within your local area network.
Currently the command line Roon control scripts provide support for:
- Play album by album name
- Play artist name
- Play genre
- Play playlist by playlist name
- Play tag
- Play Roon Radio
- Play named album by specified artist
- Play named track by specified artist
- Play composer
- Play named album by specified composer
- Play named album in specified genre
- Play named artist in specified genre
- Issue one of the following commands in the specified zone
- group
- ungroup
- play
- play_all
- pause
- pause_all
- playpause
- stop
- stop_all
- next
- previous
- mute (toggle muted/unmuted in selected zone or zone grouping)
- mute_all (toggle muted/unmuted in all zones)
- shuffle (toggle shuffle/unshuffle zone playback)
- repeat (toggle loop/unlooped zone playback)
- Get zone information and settings
- Get track/artist/album now playing in specified zone or all zones
- List albums, artists, albums by artist, tracks by artist, albums by composer, composers, albums by genre, artists by genre, genres, playlists, live radio stations, tags, and Roon zones
- Set the default Roon output zone
- Set the volume level in a specified Roon zone or zone grouping
- Select Roon audio zone or zone grouping
- Enable/disable track fade out and fade in
In addition, search capabilities have been added to the scripts with partial matching facilities. Thus a substring can be supplied to use as a search term with partial matching returning albums, artists, playlists, genres, or tags which contain the specified substring (case sensitive). The special search term __all__ indicates match all albums, artists, playlists, genres, or tags.
All commands and playback can target a specified Roon output zone.
Additional detail and info can be found in the RoonCommandLine Wiki.
Command line control of Roon may be of particular interest to Roon users running a Roon Bridge or Roon Server where there is no Roon client present on that system to control Roon. However, command line control of Roon can provide significant benefit to Roon users in any environment or deployment. See the section below, Why would I need or want command line control of Roon, for a closer look at possible motivation for command line control of Roon.
Requirements
RoonCommandLine can be installed on either Linux or Mac OS X systems. It requires a Roon Core System reachable on the local network, Bash, Python 3, and the Python Roon API. The Python Roon API will be installed as part of the RoonCommandLine installation process.
Ensure that a Roon Core System is running on the local area network and Python 3 is installed on the Linux or Mac on which you wish to install the RoonCommandLine package. Most modern Linux systems will have Python 3 already installed. A good guide for installing Python 3 on Mac OS X can be found at https://docs.python-guide.org/starting/install3/osx/ and on Linux at https://docs.python-guide.org/starting/install3/linux/
Installation
See the RoonCommandLine Install section for details on installing RoonCommandLine.Upgrades
See RoonCommandLine UpgradesRemote deployment
See RoonCommandLine Remote DeploymentRoonCommandLine Light deployment
See RoonCommandLine Light DeploymentRemoval
See RoonCommandLine RemovalDocumentation
See the RoonCommandLine Documentation section for RoonCommandLine documentation.Usage
See the RoonCommandLine Usage section for RoonCommandLine usage details.Screenshots
Roon_List_Artist_Tracks.png: 1354 x 409 Roon_Play_Artist_Track.png: 1349 x 488 Roon_Set_Zone.png: 800 x 585 Roon_UI.png: 800 x 557
List tracks containing “Satin” by Artists containing “Moody”
Play first track containing “Satin” by Artists containing “Moody”
Interactive menus when invoked with no arguments
Troubleshooting
The most common difficulty encountered during initial setup of the Roon Command Line package is the configuration of public key authentication in SSH. This allows the “roon” command on your systems to execute Roon Command Line commands remotely without the need to enter credentials. There are many guides available on the Internet that provide instructions on configuring public key SSH authentication. For instance, see https://www.ssh.com/academy/ssh/command#configuring-public-key-authentication or https://serverpilot.io/docs/how-to-use-ssh-public-key-authentication/
Also, make sure the SSH service is running on the Python Roon API system. Alternatively, install both the roon command and the Python Roon API on the same system and run the roon commands locally, avoiding the need for SSH. To enable local execution of the roon command line tools, issue the command:
`roon -L`In some cases the initial installation may fail to configure the system properly. The Roon Command Line install creates two configuration files:
`/usr/local/Roon/etc/pyroonconf`and
`/usr/local/Roon/etc/roon_api.ini`These two configuration files are the first place to look when you encounter an issue. The /usr/local/Roon/etc/pyroonconf file contains 3 settings:
- The path to the Python User Base folder where the Python Roon API dist-packages
directory is located
- A variable used to determine if the Python Roon API patch has been applied
- The currently active Roon Zone name used by the Roon Commmand LineThe /usr/local/Roon/etc/roon_api.ini file contains default values for album name, artist, genre, playlist, tag, and zone as well as the name of a file that contains a token used to authenticate with the Roon Core and the Roon Core IP address. Verify the settings in roon_api.ini are valid and correct. The most common issue will be an incorrect Roon Core IP address setting. You can verify this address is correct by comparing it to the value displayed in your Roon Remote window at
`Settings -> General`under “ROON CORE”.
Much of the Roon Command Line setup is automatically configured during the execution of the ./Install script. If you have some expertise in Bash scripting you can examine this script to see what commands were issued.
Another area that may be causing problems is the installation of the Python Roon API package and its ability to communicate with your Roon Core. To debug problems I have found it useful to SSH in to the system running the Python Roon API package and run commands by hand there. For example, rather than running “roon -l zones” command which remotely runs the list_zones command, SSH in as the configured user and run:
cd /usr/local/Roon/api
python
list_zones.py -z allThis eliminates SSH and remote execution as well as the intermediate shell script used to execute the python script. Similar python commands can be issued directly on the Python Roon API system in the /usr/local/Roon/api directory.
Verify that the “roon” frontend command shell script has been configured properly. Open the roon shell script in an editor and find the two lines near the top of the file that set the “server” and “user” shell variables. Verify that the “server” variable is set to the correct IP address of the Python Roon API server and that the “user” variable is set to the username used in the SSH commands to execute the Python commands on the Python Roon API server. These should have been set for you automatically during the installation process but may have been misconfigured.
Motivation
Why would I need or want command line control of Roon
One might reasonably ask “Why would I need or want command line control of my Roon audio system”? Truth be told, most Roon users do not need or want command line control of Roon or any other software. They are happy with the graphical user interfaces they use and never ever see a command line prompt. So the answer to that question is almost always “You don’t”.
However, some users (mostly old propeller head codgers) are comfortable at the command line and prefer to use it over the tedious mouse clicks required to get anything done in a graphical user interface. Different lanes for different brains.
I would say the most significant use case for command line control of anything is automation. For example, if I want to schedule playback of specified music in specific zones triggered by some event, then command line control can be used to implement this. That can be done via Cron jobs, play something in some zone at scheduled times. Or playback of specified songs in selected zones could be triggered by some event like when a particular face is recognized by my smart mirror or when my smart lights are turned to a particular profile. I use command line control of Roon coupled with Apple Siri voice commands that trigger an SSH shortcut to run the command. There are many use cases for automation using command line utilities.
The other main use case for command line control is simple convenience. If you spend a lot of time in a Shell environment then it is just easier to type a command that plays what you would like to hear where you want to hear it than it is to switch windows, bring up a GUI, click a few times to find what you want, and click to play it, then go back to your terminal window and Shell env. Most people do not live in a Shell environment like I do so this use case is not that significant.
Finally, the command line interface and the associated Roon API can provide capabilities not available in the Roon GUI. Searching, listing, and filtering can be augmented by the plethora of tools available in a typical Shell environment. You can pipe the output of a Roon command to grep, sed, awk, and other standard utilities to produce results unavailable in the GUI. That is, command line control along with the API and Shell utilities/builtins can extend the capabilities of the Roon audio system. The RoonCommandLine package also enables some features not easily available in the Roon GUI. One of these, preconfigured Zone Grouping, allows the RoonCommandLine user to easily and quickly switch between any of the preconfigured zone groupings in /usr/local/Roon/etc/roon_api.ini. Yes, you can change the zone grouping in Roon but it takes quite a few actions on the user’s part to accomplish this. In my household I find it frequently desirable to be able to switch zone groupings easily and quickly and I can do so by configuring these presets to my typical use cases. Another feature of RoonCommandLine not easily found in the Roon GUI is the ability to search the Roon Database for tracks by an artist and other combinations of search filters. While the Roon GUI has an exceptional filtering mechanism, try doing a search for all tracks containing the string “Love” by the artists with name containg the string “Beatles”. It’s quick and easy to do with a single RoonCommandLine command.
Applications
Stream Spotify from a Raspberry Pi into Roon
Roon Community Moderator, René, describes how to stream Spotify from a Raspberry Pi into Roon as a Live Radio station in a Roon Community Forum Post. The setup integrates the HQPlayer up-sampling media player with the Roon Entrypoints extension, RoonCommandLine, and Apple Shortcuts turning a spare Pi into an audio web stream that Roon can take in as a Live Radio station. Pretty incredible and fairly easy.
Note that the expensive component in this setup is HQPlayer which is only needed for its up-sampling and not required.
History
This project began as an attempt to control Roon with Siri voice commands. Several users had posted in the Roon forums various ways to use Siri to control Roon. These usually took the form of a fake device in HomeBridge that then communicates with HomeKit and Siri. This seemed cool but maybe overkill. I was able to get Siri voice control of Roon working with simple SSH shortcuts that execute Python scripts which utilize the Roon API to control Roon.
Apple SSH shortcuts can be used to execute commands on systems that allow SSH access. I used an Ubuntu 20.10 system recently installed to install the Python Roon API project (pip install roonapi) and quickly cobbled together a Python script based on one of the examples in that project. The Python script accepts an argument specifying an artist name in my Roon library. It then uses the Roon API to play music from my library by that artist in the specified zone.
On my iPhone I then created shortcuts which use the “Run script over SSH” option for Apple Scripting shortcuts. The shortcuts execute a Bash command which is a shell script that executes the Python script with appropriate arguments. It all seems to work. I did run into a few gotchas. It seems with current Python/Pip installs you need to specify an environment variable telling Python where the Pip modules are located. So I needed a login shell to pick that up but I could not figure out how to tell the Apple shortcut to give me an SSH login shell. The Python env variable is set in the shell script the SSH session executes.
Currently this project has morphed primarily into a set of command line tools to control various aspects of Roon remotely. There is still the capability to augment this command line control with Siri voice commands that trigger an Apple Shortcut which executes a command via SSH. But what we have here in the repository are the command line tools.
RoonCommandLine v2.0.0 introduced Debian and RPM format package installation accompanied with extensive automated configuration. In most environments, deployment of this package will require little to no manual configuration.