Ferrosonic
A terminal-based Subsonic music client written in Rust, featuring bit-perfect audio playback, gapless transitions, and full desktop integration.
Ferrosonic is inspired by Termsonic, the original terminal Subsonic client written in Go by SixFoisNeuf. Ferrosonic is a ground-up rewrite in Rust with additional features including PipeWire sample rate switching for bit-perfect audio, MPRIS2 media controls, multiple color themes, and mouse support.
Features
- Bit-perfect audio - Automatic PipeWire sample rate switching to match the source material (44.1kHz, 48kHz, 96kHz, 192kHz, etc.)
- Gapless playback - Seamless transitions between tracks with pre-buffered next track
- MPRIS2 integration - Full desktop media control support (play, pause, stop, next, previous, seek)
- Artist/album browser - Tree-based navigation with expandable artists and album listings
- Playlist support - Browse and play server playlists with shuffle capability
- Play queue management - Add, remove, reorder, shuffle, and clear queue history
- Audio quality display - Real-time display of sample rate, bit depth, codec format, and channel layout
- Audio visualizer - Integrated cava audio visualizer with theme-matched gradient colors
- 13 built-in themes - Default, Monokai, Dracula, Nord, Gruvbox, Catppuccin, Solarized, Tokyo Night, Rosé Pine, Everforest, Kanagawa, One Dark, and Ayu Dark
- Custom themes - Create your own themes as TOML files in
~/.config/ferrosonic/themes/ - Mouse support - Clickable buttons, tabs, lists, and progress bar seeking
- Artist filtering - Real-time search/filter on the artist list
- Multi-disc album support - Proper disc and track number display
- Keyboard-driven - Vim-style navigation (j/k) alongside arrow keys
Screenshots
Installation
Dependencies
Ferrosonic requires the following at runtime:
| Dependency | Purpose | Required |
|---|---|---|
| mpv | Audio playback engine (via JSON IPC) | Yes |
| PipeWire | Automatic sample rate switching for bit-perfect audio | Recommended |
| WirePlumber | PipeWire session manager | Recommended |
| D-Bus | MPRIS2 desktop media controls | Recommended |
| cava | Audio visualizer | Optional |
Build dependencies (needed to compile from source):
| Dependency | Package (Arch) | Package (Fedora) | Package (Debian/Ubuntu) |
|---|---|---|---|
| Rust toolchain | rustup |
via rustup.rs | via rustup.rs |
| pkg-config | pkgconf |
pkgconf-pkg-config |
pkg-config |
| D-Bus dev headers | dbus |
dbus-devel |
libdbus-1-dev |
Arch Linux
# Install runtime dependencies
sudo pacman -S mpv pipewire wireplumber
# Install build dependencies
sudo pacman -S base-devel pkgconf dbus
# Build from source
git clone https://github.com/jaidaken/ferrosonic.git
cd ferrosonic
cargo build --release
# Binary is at target/release/ferrosonic
sudo cp target/release/ferrosonic /usr/local/bin/
Fedora
# Install runtime dependencies
sudo dnf install mpv pipewire wireplumber
# Install build dependencies
sudo dnf install gcc pkgconf-pkg-config dbus-devel
# Install Rust toolchain if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build from source
git clone https://github.com/jaidaken/ferrosonic.git
cd ferrosonic
cargo build --release
sudo cp target/release/ferrosonic /usr/local/bin/
Ubuntu / Debian
# Install runtime dependencies
sudo apt install mpv pipewire wireplumber
# Install build dependencies
sudo apt install build-essential pkg-config libdbus-1-dev
# Install Rust toolchain if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build from source
git clone https://github.com/jaidaken/ferrosonic.git
cd ferrosonic
cargo build --release
sudo cp target/release/ferrosonic /usr/local/bin/
Generic (any Linux distribution)
Ensure mpv is installed and available in your PATH. PipeWire is optional but required for automatic sample rate switching.
# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build
git clone https://github.com/jaidaken/ferrosonic.git
cd ferrosonic
cargo build --release
# Install
sudo cp target/release/ferrosonic /usr/local/bin/
Usage
# Run with default config (~/.config/ferrosonic/config.toml)
ferrosonic
# Run with a custom config file
ferrosonic -c /path/to/config.toml
# Enable verbose/debug logging
ferrosonic -v
Configuration
Configuration is stored at ~/.config/ferrosonic/config.toml. You can edit it manually or configure the server connection through the application's Server page (F4).
BaseURL = "https://your-subsonic-server.com"
Username = "your-username"
Password = "your-password"
Theme = "Default"
| Field | Description |
|---|---|
BaseURL |
URL of your Subsonic-compatible server (Navidrome, Airsonic, Gonic, etc.) |
Username |
Your server username |
Password |
Your server password |
Theme |
Color theme name (e.g. Default, Catppuccin, Tokyo Night) |
Logs are written to ~/.config/ferrosonic/ferrosonic.log.
Keyboard Shortcuts
Global
| Key | Action |
|---|---|
q |
Quit |
p / Space |
Toggle play/pause |
l |
Next track |
h |
Previous track |
Ctrl+R |
Refresh data from server |
t |
Cycle to next theme |
F1 |
Artists page |
F2 |
Queue page |
F3 |
Playlists page |
F4 |
Server configuration page |
F5 |
Settings page |
Artists Page (F1)
| Key | Action |
|---|---|
/ |
Filter artists by name |
Esc |
Clear filter |
Up / k |
Move selection up |
Down / j |
Move selection down |
Left / Right |
Switch focus between tree and song list |
Enter |
Expand/collapse artist, or play album/song |
Backspace |
Return to tree from song list |
e |
Add selected item to end of queue |
n |
Add selected item as next in queue |
Queue Page (F2)
| Key | Action |
|---|---|
Up / k |
Move selection up |
Down / j |
Move selection down |
Enter |
Play selected song |
d |
Remove selected song from queue |
J (Shift+J) |
Move selected song down |
K (Shift+K) |
Move selected song up |
r |
Shuffle queue (current song stays in place) |
c |
Clear played history (remove songs before current) |
Playlists Page (F3)
| Key | Action |
|---|---|
Tab / Left / Right |
Switch focus between playlists and songs |
Up / k |
Move selection up |
Down / j |
Move selection down |
Enter |
Load playlist songs or play selected song |
e |
Add selected item to end of queue |
n |
Add selected song as next in queue |
r |
Shuffle play all songs in selected playlist |
Server Page (F4)
| Key | Action |
|---|---|
Tab |
Move between fields |
Enter |
Test connection or Save configuration |
Backspace |
Delete character in text field |
Settings Page (F5)
| Key | Action |
|---|---|
Up / Down |
Move between settings |
Left |
Previous option |
Right / Enter |
Next option |
Settings include theme selection and cava visualizer toggle. Changes are saved automatically.
Mouse Support
- Click page tabs in the header to switch pages
- Click playback control buttons (Previous, Play, Pause, Stop, Next) in the header
- Click items in lists to select them
- Click the progress bar in the Now Playing widget to seek
Audio Features
Bit-Perfect Playback
Ferrosonic uses PipeWire's pw-metadata to automatically switch the system sample rate to match the source material. When a track at 96kHz starts playing, PipeWire is instructed to output at 96kHz, avoiding unnecessary resampling. The original sample rate is restored when the application exits.
Gapless Playback
The next track in the queue is pre-loaded into MPV's internal playlist before the current track finishes, allowing seamless transitions with no gap or click between songs.
Now Playing Display
The Now Playing widget shows:
- Artist, album, and track title
- Audio quality: format/codec, bit depth, sample rate, and channel layout
- Visual progress bar with elapsed/total time
Themes
Ferrosonic ships with 13 themes. On first run, the built-in themes are written as TOML files to ~/.config/ferrosonic/themes/.
| Theme | Description |
|---|---|
| Default | Cyan/yellow on dark background (hardcoded) |
| Monokai | Classic Monokai syntax highlighting palette |
| Dracula | Purple/pink Dracula color scheme |
| Nord | Arctic blue Nord palette |
| Gruvbox | Warm retro Gruvbox colors |
| Catppuccin | Soothing pastel Catppuccin Mocha palette |
| Solarized | Ethan Schoonover's Solarized Dark |
| Tokyo Night | Dark Tokyo Night color scheme |
| Rosé Pine | Soho vibes Rosé Pine palette |
| Everforest | Comfortable green Everforest Dark |
| Kanagawa | Dark Kanagawa wave palette |
| One Dark | Atom One Dark color scheme |
| Ayu Dark | Ayu Dark color scheme |
Change themes with t from any page, from the Settings page (F5), or by editing the Theme field in config.toml.
Custom Themes
Create a .toml file in ~/.config/ferrosonic/themes/ and it will appear in the theme list. The filename becomes the display name (e.g. my-theme.toml becomes "My Theme").
[colors]
primary = "#89b4fa"
secondary = "#585b70"
accent = "#f9e2af"
artist = "#a6e3a1"
album = "#f5c2e7"
song = "#94e2d5"
muted = "#6c7086"
highlight_bg = "#45475a"
highlight_fg = "#cdd6f4"
success = "#a6e3a1"
error = "#f38ba8"
playing = "#f9e2af"
played = "#6c7086"
border_focused = "#89b4fa"
border_unfocused = "#45475a"
[cava]
gradient = ["#a6e3a1", "#94e2d5", "#89dceb", "#74c7ec", "#cba6f7", "#f5c2e7", "#f38ba8", "#f38ba8"]
horizontal_gradient = ["#f38ba8", "#eba0ac", "#fab387", "#f9e2af", "#a6e3a1", "#94e2d5", "#89b4fa", "#cba6f7"]
You can also edit the built-in theme files to customize them. They will not be overwritten unless deleted.
Compatible Servers
Ferrosonic works with any server implementing the Subsonic API, including:
Acknowledgements
Ferrosonic is inspired by Termsonic by SixFoisNeuf, a terminal Subsonic client written in Go. Ferrosonic builds on that concept with a Rust implementation, bit-perfect audio via PipeWire, and additional features.
License
MIT