Ferrosonic-ng

A terminal-based Subsonic music client written in Rust, featuring bit-perfect audio playback, gapless transitions, and full desktop integration.

Ferrosonic-ng is a community-driven fork of ferrosonic by jaidaken. While the upstream project is once again actively maintained, ferrosonic-ng continues on its own path with a different release cadence and feature focus: faster iteration, deeper desktop integration, and a broader set of discovery tools. Like the original, it is inspired by Termsonic by SixFoisNeuf, a terminal Subsonic client written in Go.

Features

• Bit-perfect audio — Automatic PipeWire sample rate switching to match source material (44.1kHz, 48kHz, 96kHz, 192kHz, etc.), with the original rate restored on exit
• Gapless playback — Next track is pre-loaded into mpv's internal playlist for seamless transitions
• MPRIS2 integration — Full desktop media controls (play, pause, stop, next, previous, seek)
• Artist/album browser — Tree-based navigation with expandable artists, album listings, and artist filtering
• Browse page — Browse and search all, starred and random songs/albums from your server
• Playlists & queue management — Browse server playlists, add/remove/reorder/shuffle queue, clear history
• Queue persistence — Automatically save and restore your play queue and current position on launch
• Internet radio — Browse and play Navidrome/Subsonic radio stations with live stream metadata when available
• Audio quality display — Real-time sample rate, bit depth, codec, and channel layout
• Audio visualizer — Integrated cava visualizer with theme-matched gradient colors
• 13 built-in themes + custom themes — Monokai, Dracula, Nord, Catppuccin, Tokyo Night, and more. Create your own as TOML files in ~/.config/ferrosonic/themes/. See the themes documentation
• Mouse support — Clickable tabs, playback controls, list items, and progress bar seeking
• Keyboard-driven — Vim-style navigation (j/k) alongside arrow keys. See the full keybindings reference
• Multi-disc album support — Proper disc and track number display

Screenshots

Installation

Dependencies

Ferrosonic requires the following at runtime:

Quick Install

Supports Arch, Fedora, and Debian/Ubuntu. Installs runtime dependencies, downloads the latest precompiled binary, and installs to /usr/local/bin/:

curl -sSf https://raw.githubusercontent.com/Jamie098/ferrosonic-ng/master/install.sh | sh

Install via Cargo

cargo install ferrosonic

Requirements

Ferrosonic requires Rust 1.70 or later. Check your version with rustup show and update with rustup update stable if needed.

Build from Source

If you prefer to build from source, you'll also need: Rust toolchain (≥ 1.70), pkg-config, OpenSSL dev headers, and D-Bus dev headers. Then:

git clone https://github.com/Jamie098/ferrosonic-ng.git
cd ferrosonic-ng
cargo build --release
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 (F6).

BaseURL = "https://your-subsonic-server.com"
Username = "your-username"
Password = "your-password"
Theme = "Default"
Cava = true
CavaSize = 40
Notifications = true
RandomSongsCount = 100
Scrobble = true
SaveQueue = true
# Valid tabs: Browse, Artists, Queue, Playlists, Radio, Server, Settings
VisibleTabs = ["Browse", "Artists", "Queue", "Playlists", "Radio", "Server", "Settings"]

Logs are written to ~/.config/ferrosonic/ferrosonic.log.

Themes

Ferrosonic ships multiple built-in themes, as well as support for custom themes. Here are two examples:

To know more about themes, visit the themes documentation.

Compatible Servers

Ferrosonic works with any server implementing the Subsonic API, including:

• Navidrome
• Airsonic
• Airsonic-Advanced
• Gonic
• Supysonic

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

For local development:

cargo build
cargo test

Bug reports are most useful when they include:

• Steps to reproduce the issue
• Expected behavior and actual behavior
• Version/commit and OS details
• Relevant logs from ~/.config/ferrosonic/ferrosonic.log (or /tmp/ferrosonic.log if a config directory is unavailable)

License

This project is licensed under the MIT License.

Acknowledgements

Ferrosonic-ng began as a fork of jaidaken/ferrosonic and remains grateful for that foundation. Both projects trace their lineage back to Termsonic by SixFoisNeuf, a terminal Subsonic client written in Go.