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 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

Build from Source

If you prefer to build from source, you'll also need: Rust toolchain, 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.