Polarity
February 16, 2026 ยท View on GitHub
A terminal interface to the Polaris music streaming server made for a raspberry pi zero device
Introduction
The Polarity project aims to capture track enqueueing features that were present in popular players like Winamp and combines that with music downloading through the Polaris music server. It has been developed on a raspberry pi zero 2 W with a 1.3in TFT bonnet from Adafruit.
Components
The software is divided into two executables - one that acts as the terminal and the other that plays the audio. The terminal has access to the Polaris server and downloads track info from it. The player also has Polaris access, using it to download songs and play them locally. The two components communicate with each other through a TCP connection. While both components can be placed in the same host and the command line options set to use the same host address, they can also be placed on separate hosts on a network. Although, placing them on different hosts is still an unstable feature.
Usage
The two executables need to be specified with an options file which contains the polaris hostname, a token to connect to the polaris server, the hostname / ip address of the host running the terminal (TUI) application and the hostname / ip address of the host running the player. Two certificates (.der files) were added in this repository and are required to be in the current working directory when running the programs.
# File name : options.file
--host=www.mypolarisserver.com
--token=abcdef1234567890
--player=192.168.1.1
--tui=192.168.1.2
From the root of the repository, launching the programs is in the following manner:
target/release/tui @options.file
player/target/release/player @options.file
Note that the binaries on the release page are compiled for the Raspberry Pi OS running on a Raspberry Pi Zero 2W.
Setup
Parts List
With a few parts and the release binaries, a simple remote-controlled music player for Polaris can be made. The setup on which the releases were tested consisted of:
System Overview
The raspberry pi runs both the player and terminal binaries. The line out from the audio DAC is connected to a speaker. The raspberrypi OS can be setup to receive IR commands from any standard remote control handset. The scan codes from the remote control are converted to key codes and the terminal app responds to the keys and controls the playlist and the playback.
Instead of running on the raspberry pi, the two binaries can be compiled for windows or linux and run on a PC. The application will respond to key presses of the keyboard. The keys to control the applcation are:
- Up - Scroll up
- Down - Scroll down
- Left - Dequeue a track
- Right - Enqueue a track
- Enter - OK / Autoplay tracks
- Tab - Move to next screen
Screenshots
Main Screen
Playback Screen
Shutdown Screen
Compatibility
This software is known to work with 0.14.0 version of Polaris but seems to be incompatible with one of the later versions.