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 continuation of the original ferrosonic by jaidaken, which is no longer actively maintained. Originally a ground-up rewrite of Termsonic in Rust, it features 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 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
• Songs page — Browse and search all, starred and random songs from your server
• Playlists & queue management — Browse server playlists, add/remove/reorder/shuffle queue, clear history
• 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 (F5).

BaseURL = "https://your-subsonic-server.com"
Username = "your-username"
Password = "your-password"
Theme = "Default"
Cava = true
CavaSize = 40
Notifications = true
RandomSongsCount = 100
Scrobble = true

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

This is a fork from jaidaken/ferrosonic, with the intent of keeping the project alive.

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.