# 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](https://github.com/jaidaken/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](https://git.sixfoisneuf.fr/termsonic/about/) 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](https://github.com/karlstav/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](docs/themes.md)
- **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](docs/keybindings.md)
- **Multi-disc album support** — Proper disc and track number display
## Screenshots
## Installation
### Dependencies
Ferrosonic requires the following at runtime:
| **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 |
### Quick Install
Supports Arch, Fedora, and Debian/Ubuntu. Installs runtime dependencies, downloads the latest precompiled binary, and installs to `/usr/local/bin/`:
```bash
### 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:
```bash
git clone https://github.com/Jamie098/ferrosonic-ng.git
cd ferrosonic-ng
cargo build --release
sudo cp target/release/ferrosonic /usr/local/bin/
```
## Usage
```bash
# 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).
```toml
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"]
```
| `BaseURL` | `string` | `""` | URL of your Subsonic-compatible server (Navidrome, Airsonic, Gonic, etc.) |
| `Username` | `string` | `""` | Your server username |
| `Password` | `string` | `""` | Your server password |
| `Theme` | `string` | `""` | Color theme name (e.g. `Default`, `Catppuccin`, `Tokyo Night`) |
| `Cava` | `bool` | `false` | Enable the audio visualizer |
| `CavaSize` | `u8` | `40` | Audio visualizer height percentage (range: `10`–`80`, step: `5`) |
| `Notifications` | `bool` | `false` | Enable desktop track-change notifications |
| `RandomSongsCount` | `usize` | `250` | Number of random songs to fetch |
| `Scrobble` | `bool` | `true` | Enable scrobbling (reporting played tracks to the server) |
| `SaveQueue` | `bool` | `true` | Save and restore the play queue and current position on launch |
| `VisibleTabs` | `string[]` | all tabs | Header tabs to show, in order. Valid values: `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:
| <img src="docs/screenshots/nord_theme.avif" alt="Nord theme" width="640" height="327" /> | <img src="docs/screenshots/gruvbox_theme.avif" alt="Gruvbox theme" width="640" height="327" /> |
To know more about themes, **visit the [themes documentation](docs/themes.md)**.
## Compatible Servers
Ferrosonic works with any server implementing the Subsonic API, including:
- [Navidrome](https://www.navidrome.org/)
- [Airsonic](https://airsonic.github.io/)
- [Airsonic-Advanced](https://github.com/airsonic-advanced/airsonic-advanced)
- [Gonic](https://github.com/sentriz/gonic)
- [Supysonic](https://github.com/spl0k/supysonic)
## Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request.
For local development:
```bash
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](LICENSE).
## Acknowledgements
Ferrosonic-ng began as a fork of [jaidaken/ferrosonic](https://github.com/jaidaken/ferrosonic) and remains grateful for that foundation. Both projects trace their lineage back to [Termsonic](https://git.sixfoisneuf.fr/termsonic/about/) by SixFoisNeuf, a terminal Subsonic client written in Go.