pianobar

pianobar is a free/open-source, console-based client for the personalized online radio Pandora.

Remote Pianobar — a fork of the original pianobar with remote control capabilities. See the Remote Pianobar Features section below for details. Original repository: https://github.com/PromyLOPh/pianobar

Features

• play and manage (create, add more music, delete, rename, …) stations
• rate songs and explain why they have been selected
• upcoming songs/song history
• customize keybindings and text output (see configuration example)
• remote control and eventcmd interface (send tracks to last.fm, for example)
• Remote API for building custom UIs (web, mobile, desktop)
• included modern web UI built with Lit components
• proxy support for listeners outside the USA

Install

Install from GitHub releases

Pre-built packages are available on the Releases page. If you have the original pianobar installed, remove it first to avoid conflicts.

Linux (Debian/Ubuntu .deb)

1. Remove existing pianobar if installed:

   sudo apt remove pianobar
   # or, if you installed a .deb named pianobar:
   # sudo dpkg --remove pianobar

2. Open https://github.com/mr-light-show/remote-pianobar/releases and download the .deb that matches your system:

   • Ubuntu 24.04 (Noble), amd64: remote-pianobar_noble_amd64.deb
   • Debian Bookworm or similar, arm64: remote-pianobar_bookworm_arm64.deb
   • Debian Trixie or similar, arm64: remote-pianobar_trixie_arm64.deb

3. Install (substitute your file name):

   sudo dpkg -i remote-pianobar_noble_amd64.deb
   # If you see dependency errors:
   sudo apt install -f

macOS (.dmg)

1. Remove existing pianobar if installed via Homebrew:

   brew uninstall pianobar

2. Open https://github.com/mr-light-show/remote-pianobar/releases and download remote-pianobar_macos14.dmg.

3. Open the DMG, then run the included install.sh (with sudo) or copy the app to your desired location (see INSTALL.txt in the DMG).

Build from source

You need the following software to build pianobar:

• GNU make
• pthreads
• libao
• libcurl ≥ 7.32.0
• gcrypt¹
• json-c
• ffmpeg ≤ 5.1²
• UTF-8 console/locale

Linux-specific:

• libasound2 (ALSA library for system volume control)

For WebSocket/Remote API builds (enabled by default):

• libwebsockets ≥ 4.0
• openssl
• Node.js and npm (for building the web UI)

Package installation examples:

On Debian/Ubuntu:

sudo apt-get install build-essential libao-dev libcurl4-openssl-dev \
  libgcrypt20-dev libjson-c-dev libavcodec-dev libavformat-dev \
  libavutil-dev libavfilter-dev libswresample-dev libasound2-dev

For WebSocket builds, also install:

sudo apt-get install libwebsockets-dev nodejs npm

On macOS (via Homebrew):

brew install libao curl libgcrypt json-c ffmpeg

For WebSocket builds, also install:

brew install libwebsockets node

Then type:

gmake clean && gmake

WebSocket/Remote API is included by default. To build without it:

make NOWEBSOCKET=1 clean && make NOWEBSOCKET=1

You can run the client directly from the source directory now:

./pianobar

Or install it to /usr/local by issuing:

gmake install

Remote Pianobar Features

Remote Pianobar enables real-time communication for custom user interfaces. Build web, mobile, or desktop UIs that control pianobar and receive live updates.

Features

• Real-time playback state updates
• Song metadata (title, artist, album, art URL)
• Station management (list, create, delete, switch)
• Playback control (play, pause, skip, volume)
• Song actions (love, ban, tired, create station)
• Two-way communication via Socket.IO protocol

Building Remote Pianobar

Audio Library: Remote Pianobar uses miniaudio for audio playback, which provides automatic device switching and cross-platform support. The library is included in the source tree (src/miniaudio.h) and requires no additional dependencies.

To build Remote Pianobar (WebSocket is enabled by default):

make clean && make

Or use the included build script for development:

./build.sh        # Standard build
./build.sh debug  # Debug build with crash capture

Configuration

Add these settings to your ~/.config/pianobar/config:

ui_mode = both
websocket_port = 8080
webui_path = ./dist/webui

UI mode options:

• cli: Command-line interface only, no remote API
• web: Web-only (daemonizes, runs in background)
• both: Both CLI and remote API (default, runs in foreground)

When using web mode, pianobar runs as a daemon and you should specify:

ui_mode = web
websocket_port = 8080
webui_path = ./dist/webui
pid_file = /tmp/pianobar.pid
log_file = /tmp/pianobar.log

Then start pianobar and it will run in the background. Open http://localhost:8080 in your browser.

Log file rotation

When using log_file in daemon mode, the log grows indefinitely. On Linux you can use logrotate to rotate it by size so the file stays small and rotation is automatic.

1. Confirm your log file path. In your pianobar config (~/.config/pianobar/config or ~/.pianobar/config), find the log_file setting. You need the absolute path for logrotate (e.g. /home/pi/.config/pianobar/pianobar.log). If you use ~, run echo ~/.config/pianobar/pianobar.log and use the output.

2. Install logrotate (if needed). On Debian/Ubuntu/Raspberry Pi OS it is often already installed. Check with which logrotate. If missing:

   sudo apt update && sudo apt install logrotate

3. Create the logrotate config. Create /etc/logrotate.d/pianobar:

   sudo nano /etc/logrotate.d/pianobar

   Paste the following. Replace /path/to/pianobar.log with your absolute log path from step 1. Replace USER and GROUP with the owner of the log file. The su directive is required when the log is in a world-writable directory (e.g. /tmp):

   /path/to/pianobar.log {
       su USER GROUP
       size 5M
       copytruncate
       rotate 3
       missingok
   }
   

   To find USER and GROUP: run ls -l /path/to/pianobar.log (third and fourth columns), or id -un and id -gn.

4. Set permissions. Logrotate ignores configs writable by group/others:

   sudo chmod 644 /etc/logrotate.d/pianobar

5. Test (dry-run). Check for errors without rotating:

   sudo logrotate -d /etc/logrotate.d/pianobar

   If the log file does not exist yet, that is fine (missingok allows that).

6. Optional: force one rotation. To confirm it works:

   sudo logrotate -f /etc/logrotate.d/pianobar

   The pianobar daemon keeps running without restart.

7. Automatic runs. logrotate is usually run daily by cron (e.g. /etc/cron.daily/logrotate). When your log reaches 5 MB (or on the daily run), it will be rotated automatically; up to 3 old files are kept.

Troubleshooting: If rotation never runs, check that the daily job exists (ls /etc/cron.daily/logrotate) and that the config is not ignored (permissions 0644; correct su when the log is in /tmp). Run sudo logrotate -f /etc/logrotate.d/pianobar to force a rotation.

Included Web UI

A modern, lightweight web interface is included:

• Built with Lit web components (5KB framework)
• Material Design styling with dark mode
• Real-time updates via remote API
• Mobile-responsive design
• Album art display
• Volume control and playback controls
• Station management

Example of the web UI in web mode (album art, track info, progress, volume, playback controls, station selector):

See webui/README.md for development and build instructions.

Building Custom UIs

The Remote API uses Socket.IO and provides events for:

Client → Server (Commands):

- play, pause, skip
- love_song, ban_song, tired_song
- set_volume
- list_stations, play_station
- create_station, delete_station

Server → Client (Events):

- state_update: Playback state changes
- song_update: New song metadata
- station_update: Station list changes
- volume_update: Volume changes

Connect to ws://localhost:8080 using any Socket.IO client library. Full protocol documentation available in WEBSOCKET_PROTOCOL.md.

For more information, see:

• Web UI development: webui/README.md
• API protocol: WEBSOCKET_PROTOCOL.md
• Original repository: https://github.com/PromyLOPh/pianobar

Localization (player and web UI)

User-visible strings for the C player, WebSocket error payloads, daemon, and bundled web UI are maintained in one canonical YAML file per language under locale/ (for example locale/en.yaml). Nested groups in YAML are flattened to dot-separated keys (for example web.ui.cancel, error.ws.network).

Regenerate build artifacts after editing YAML (requires Python 3 with PyYAML):

make locale-codegen

This updates, from every locale/<lang>.yaml:

• locale/<lang> — single-line key = value files consumed by the C locale loader (src/l10n.c)
• webui/src/locales/<lang>.json — flat JSON for the Lit app (webui/src/i18n.ts via t() / tf())
• src/l10n_defaults_gen.c — compiled-in fallback table when no external file is found

The root Makefile runs locale-codegen before linking the binary and tests. For web UI–only work, npm test / npm run build under webui/ run make -C .. locale-codegen first via pretest / prebuild.

Runtime lookup order for the C player: optional environment PIANOBAR_LOCALE_DIR/<lang>; then locale/<lang> under $XDG_CONFIG_HOME/pianobar or ~/.config/pianobar; then $PIANOBAR_INSTALL_PREFIX/share/pianobar/locale/<lang> (prefix defaults to /usr/local if unset); finally the embedded defaults from l10n_defaults_gen.c. Set the locale key in the pianobar config (for example locale = de) to choose a language id matching locale/<id>.yaml.

Adding a language: add locale/<id>.yaml (copy en.yaml as a template), run make locale-codegen, and install the generated locale/<id> file with the rest of the locale directory. Smoke test: copy locale/en to locale/de, change one string, set locale = de, and confirm that string appears in the CLI or web UI.

Cross-repo note: Home Assistant (remote-pianobar-ha) and the Lovelace card (remote_pianobar_card) keep their own translation files; when the same user-facing concept appears in more than one repo, align keys and English manually (see .cursor/rules/localization-user-facing.mdc).

FAQ

How can I have pianobar use port 80 on Ubuntu?

Port 80 is a privileged port (below 1024) and requires special permissions. Here are your options:

Option 1: Use setcap (Recommended for development/home use)

Grant pianobar permission to bind to privileged ports without running as root:

# Give pianobar capability to bind to privileged ports
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/pianobar

# Verify it worked
getcap /usr/local/bin/pianobar

Then configure ~/.config/pianobar/config:

websocket_port = 80
websocket_host = 0.0.0.0

Note: You'll need to reapply setcap after each pianobar upgrade/rebuild.

Option 2: Port forwarding with iptables

Keep pianobar on a high port and forward port 80 to it:

# Forward port 80 to port 8080
sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080

# Make persistent
sudo apt install iptables-persistent
sudo netfilter-persistent save

Configure ~/.config/pianobar/config:

websocket_port = 8080
websocket_host = 0.0.0.0

Access at http://your-ip/ (externally routes to port 8080 internally).

Option 3: Reverse proxy with nginx (Recommended for production)

Install and configure nginx:

sudo apt install nginx

Create /etc/nginx/sites-available/pianobar:

server {
    listen 80;
    server_name localhost;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

Use long timeouts (e.g. 3600s) for proxy_read_timeout and proxy_send_timeout so the proxy does not close idle WebSocket connections before the server or clients do.

Enable the site:

sudo ln -s /etc/nginx/sites-available/pianobar /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Configure ~/.config/pianobar/config:

websocket_port = 8080
websocket_host = 127.0.0.1

This provides better security, logging, and SSL support. Note that websocket_host is set to 127.0.0.1 so only nginx can access pianobar directly.

How can I run pianobar in web mode as a daemon on system startup?

You can use systemd to automatically start pianobar in daemon mode on boot. This works identically on both headless and GUI Ubuntu installations.

Step 1: Configure pianobar for daemon mode

Create or edit ~/.config/pianobar/config:

# Pandora credentials
user = [email protected]
password = your_password

# Daemon mode settings
ui_mode = web
websocket_port = 8080
websocket_host = 0.0.0.0

# Daemon-specific settings
pid_file = /tmp/pianobar.pid
log_file = ~/.config/pianobar/pianobar.log

Step 2: Create systemd user service

Create ~/.config/systemd/user/pianobar.service:

[Unit]
Description=Remote Pianobar Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
ExecStartPre=/bin/sleep 5
ExecStart=/usr/local/bin/pianobar
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Step 3: Enable and start the service

# Reload systemd configuration
systemctl --user daemon-reload

# Enable service to start on boot
systemctl --user enable pianobar

# Start service now
systemctl --user start pianobar

# Check status
systemctl --user status pianobar

Step 4: Enable lingering for headless systems

On headless systems (no GUI login), the user's systemd manager only starts after login, which never happens. Enable "lingering" to start the user manager at boot:

# Required for headless systems (e.g., Raspberry Pi without desktop)
loginctl enable-linger $USER

# Verify lingering is enabled
loginctl show-user $USER | grep Linger

Skip this step if you always log in via GUI or SSH before needing pianobar.

Managing the daemon:

# View logs in real-time
journalctl --user -u pianobar -f

# Stop the service
systemctl --user stop pianobar

# Restart the service
systemctl --user restart pianobar

# Disable autostart
systemctl --user disable pianobar

Access the web interface at http://localhost:8080/ (or use your server's IP if websocket_host is set to 0.0.0.0).

The audio output does not work as expected. What can I do?

pianobar uses libao and most problems are related to a broken libao configuration. Have a look at issue #167 for example.

Can I donate money? Do you have a Flattr/Bitcoin/… account?

No, money is not necessary to continue working on pianobar. There are many other ways to support pianobar: Reporting bugs, creating cool stuff based on pianobar, blogging about it and the most important one: Keeping Pandora alive.

External projects

Addons

• control-pianobar — Scripts that interact with pianobar entirely through notification bubbles and hotkeys
• pianobar.el — Emacs interface for pianobar
• pianobar-mediaplayer2 — Control pianobar like any other media player through DBUS/MPRIS.
• PianobarNowPlayable — Integrate pianobar with the Now Playing feature of macOS

Clients

• pithos — Python/GTK desktop client
• pianod — Pandora UNIX daemon, based on pianobar
• Hermes — Pandora Client for OS X
• Remote pianobar — Fork of pianobar, which includes a HTTP server and serves a Websocket-powered frontend for remote control.

Standalone devices

• PandoraBar — Beagleboard-based radio device running pianobar
• Pandora’s Box — Raspberry Pi-based standalone devices running pianobar

Footnotes

1. with blowfish cipher enabled ↩

2. required: demuxer mov, decoder aac, protocol http and filters volume, aformat, aresample ↩