Home

Awesome

roon-tui

A Roon Remote for the terminal

About

Roon TUI screenshot

Roon TUI is a lightweight Roon Remote, providing quick access to the basic controls.

Roon TUI uses an own developed Rust port of the Roon API, instead of using the official Node.js Roon API provided by Roon Labs.

Installation

Building from Source Code

Updating

Downloading Release Binaries

Prebuilt binaries can be downloaded from the latests release page on GitHub. Binaries might have been created by other users for platforms I don't have access to myself.

Using Homebrew (macOS)

User Nepherte created a Homebrew tap from which you can install Roon TUI. Instructions can be found at https://github.com/Nepherte/homebrew-roon.

Using Arch User Repository (Arch Linux)

For Arch Linux users there is an entry in the AUR, provided by Noa Himesaka.

Authorizing Core Access

On first execution the outside border of the UI will be highlighted without any views active, this indicates that pairing with a Roon Core has to take place. Use your Roon Remote and select Settings→Extensions from the hamburger menu and then Enable Roon TUI.

Project Status

This is Beta stage software. Since its first Alpha release it has been picked up by a small group of Roon enthousiasts, who gave good feedback to bring it to this next level.

Usage Instructions

Command Line Options

There are command line options available to change from the default behavior, an overview is shown by requesting help:

roon-tui -h
Usage: roon-tui [OPTIONS]

Options:
  -c, --config <CONFIG>     Path to the config.json file [default: config.json]
  -i, --ip <IP>             IP address of the Server, disables server discovery
  -p, --port <PORT>         Port number of the Server [default: 9330]
  -l, --log <LOG>           Path to the log file [default: roon-tui.log]
  -v, --verbose             Enable verbose logging to file
  -u, --no-unicode-symbols  Disable the use of Unicode symbols
  -h, --help                Print help
  -V, --version             Print version

Specifying Configuration File

At startup the default location to get the config.json configuration file from is the current working directory. This is troublesome when the executable is placed in a system folder and accessed by using the PATH environment variable, because the user account might not have permissions to write to that location. This can be solved by placing the configuration file somewehere in the home folder and specifying its location at startup on the command line. In the below example the file is stored in the users .config folder:

roon-tui -c ~/.config/roon-tui/config.json

Specifying Server IP and Port

By default the server discovery functionality provided by the Roon API is used. If this doesn't work (e.g. due to the use of different subnets) the IP address and port number of the server can be specified at the command line.

Use your Roon Remote and select Settings→Displays from the hamburger menu to find the address and port in the Web display URL.

roon-tui -i 192.168.1.10 -p 9330

Specifying Log File

The default location of the roon-tui.log log file is the current working directory. This is troublesome when the executable is placed in a system folder and accessed by using the PATH environment variable, because the user account might not have permissions to write to that location. This can be solved by placing the log file somewehere in the home folder and specifying its location at startup on the command line. In the below example the log file is stored in the users .log folder:

roon-tui -l ~/.log/roon-tui/roon-tui.log

By default only warnings and errors (including panics) are written to the log file. More information can be stored in the log file by specifying the verbose option on the command line:

roon-tui -v

The verbose option is meant to track down any issues, might they occur. Normally it is not adviced to use it as it results in large log files.

Avoiding Unicode Symbols

Roon TUI uses some unicode symbols to improve on looks. If these symbols are not correctly displayed by the terminal they can be avoided by using the --no-unicode-symbols option.

Roon TUI unicode symbols

Zone Selection and Grouping

The Roon zone that is controlled by Roon TUI is shown in the lower right corner and can be selected via the Zone List (requested using Ctrl-z).

The grouping of zones can be viewed and changed by using Ctr-g. Ouputs are added or removed from the group by using Space, the grouping is activated by using Enter. A set grouping can be saved as a preset using s, and be restored at a later time. Presets appear in the Zone List and are surrounded by square brackets: [group-preset].

Save preset

The Zone list also lists the ouputs that make up a currently active grouping, these outputs are surrounded by angle brackets <output>.

A preset or output can be selected to either group or ungroup a zone.

Zone selection

An inactive preset can be deleted by selection it and using Delete.

Multi-character Jump in Browse View

After a list of Artists, Albums, etc. is selected, and it is known what to play, a name can be directly typed in the Browse View. The first item that matches the input will be selected. The currently matched characters are displayed in the lower left corner of the view. The Backspace key can be used to revert to previous selections, the Home keys clears the complete input.

Some important remarks:

Queue Modes

Queue Modes are used to add something new to the Queue when it runs out of music, toggle between Queue Modes by using Ctrl-q.

Every Roon user is familiar with these two modes:

Manual

In the Manual Queue Mode playback stops when the queue runs out. New music has to be added manually by browsing the library.

Roon Radio

In the Roon Radio Queue Mode Roon takes care of adding a track to the Queue based on the last track played and its algorithms.

Roon-TUI provides two additional Queue Modes:

Random Album

In the Random Album Queue Mode a random album from the library is added to the queue. This is for those who prefer to listen to whole albums and like to re-discover their library.

Random Track

In the Random Track Queue Mode a random track from the library is added to the queue. This is for those who like to re-discover their library.

Append before running out

In the Random Album and Random Track mode new entries can be added to the Queue by using Ctrl-a. This can be used to fill-up the queue in advance, or to get something else if the previous addition is not to your liking.

Remarks

Key Bindings

Global (useable in all views)

TabSwitch between views
Shift-TabReverse switch between views
Ctrl-zOpen zone selector
Ctrl-gOpen zone grouping
Ctrl-Space, Ctrl-pPlay / Pause
Ctrl-ePause at End of Track
Ctrl-↑Volume up
Ctrl-↓Volume down
Ctrl-→Next track
Ctrl-←Previous track
Ctrl-qToggle through Queue Modes
Ctrl-aAppend tracks according Queue Mode
Ctrl-hOpen help screen
Ctrl-cQuit

Common list controls

Move up
Move down
HomeMove to top
EndMove to bottom
Page UpMove page up
Page DownMove page down

Browse View

EnterSelect
EscMove level up
Ctrl-HomeMove to top level
F5Refresh
a...zMulti-character jump to item
BackspaceStep back in multi-character jump

Queue View

EnterPlay from here

Now Playing View

mMute
uUnmute
+Volume up
-Volume down
rToggle Repeat
sToggle Shuffle

Zone Select Popup

EnterSelect Zone
EscBack to previous view
DeleteDelete inactive preset

Zone Grouping Popup

SpaceAdd or remove output from group
EnterActivate Grouping
sSave as preset
EscBack to previous view

Text Input

EnterConfirm input
EscCancel input