Updated readme
This commit is contained in:
Ultradesu
@@ -1,188 +1,126 @@
|
||||
# furumi
|
||||
|
||||
|
||||
|
||||
|
||||
`furumi` is a cross-platform terminal client for a furumusic server. It
|
||||
provides a fast TUI for browsing the library, playing music, managing the
|
||||
queue and playlists, controlling devices, and inspecting logs without leaving
|
||||
the terminal.
|
||||
**Your music. Your devices. Your network.**
|
||||
|
||||
## Features
|
||||
Furumi is a federated P2P player for your personal music library. Every
|
||||
running player is a complete, self-sufficient music library: it can import,
|
||||
organize, search, and play your collection without an account, a cloud
|
||||
backend, or a central service.
|
||||
|
||||
- Browse the full artist library in tile or table view.
|
||||
- Open artist pages, releases, and track lists from inside the TUI.
|
||||
- Search artists, releases, and tracks with `/`.
|
||||
- Play local audio with seek, volume, shuffle, repeat, and like controls.
|
||||
- Add tracks next in queue, append them to the queue, or clear the queue.
|
||||
- Browse playlists, liked tracks, and add tracks to playlists.
|
||||
- Pick the active playback device and control remote devices.
|
||||
- Use OS media keys through MPRIS/system media controls.
|
||||
- Inspect live in-app logs and a persistent log file.
|
||||
- Customize key bindings with a TOML keymap.
|
||||
Connect Furumi on your desktop, laptop, or another device and they become one
|
||||
personal music network. Playback, likes, playlists, and library state can move
|
||||
between your devices, while missing tracks can be requested directly from
|
||||
another player.
|
||||
|
||||
## Installation
|
||||
Furumi runs on **Linux, macOS, and Windows**.
|
||||
|
||||
Requires Rust 1.88+.
|
||||
## Why Furumi?
|
||||
|
||||
Music you own should not disappear because a subscription ended, a catalog
|
||||
changed, a service was censored, or a server went offline.
|
||||
|
||||
Furumi is built around a different model:
|
||||
|
||||
- your library remains under your control;
|
||||
- every player works independently;
|
||||
- there is no central account or single point of failure;
|
||||
- connecting more players improves availability instead of creating a new
|
||||
dependency;
|
||||
- federation is optional and simple to configure.
|
||||
|
||||
A single Furumi instance is already useful. A group of instances becomes a
|
||||
resilient network for your music.
|
||||
|
||||
## How it works
|
||||
|
||||
Each player maintains its own local library and publishes a searchable view of
|
||||
it into Furumi's DHT network. Discovery does not depend on a central index.
|
||||
|
||||
Clients connect directly over P2P transport built on
|
||||
[iroh](https://www.iroh.computer/). Furumi adds a synchronization protocol on
|
||||
top of that transport to keep trusted devices consistent even when they are
|
||||
not always online.
|
||||
|
||||
In practice:
|
||||
|
||||
1. Import music into any Furumi player.
|
||||
2. Pair your other players or join a federation network.
|
||||
3. Devices discover available libraries through the DHT.
|
||||
4. Likes, playlists, playback state, and library metadata synchronize between
|
||||
trusted clients.
|
||||
5. If a track is missing locally, Furumi can fetch it directly from another
|
||||
client.
|
||||
|
||||
There is no coordination server in the middle. Local players remain usable
|
||||
when peers are offline, and the network becomes more capable as peers appear.
|
||||
|
||||
## The player
|
||||
|
||||
Furumi includes a full-featured terminal interface for browsing artists and
|
||||
releases, searching, managing playlists and the queue, controlling playback,
|
||||
inspecting connected devices, and configuring federation.
|
||||
|
||||
The interface supports keyboard-driven navigation, multi-key combinations,
|
||||
context-aware bindings, and user-defined rebinding through TOML. Built-in
|
||||
audio visualizations, OS media controls, gapless queue playback, and local
|
||||
library management are included.
|
||||
|
||||
## Install
|
||||
|
||||
Download a prebuilt archive from the project releases, or build Furumi from
|
||||
source with Rust 1.88 or newer:
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
cargo build --release --locked
|
||||
./target/release/furumi
|
||||
```
|
||||
|
||||
The release binary is named `furumi`:
|
||||
On Debian or Ubuntu, install the Linux audio build dependencies first:
|
||||
|
||||
```bash
|
||||
cargo run --release --bin furumi
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Audio output needs the system ALSA library. PipeWire and PulseAudio are used
|
||||
through the ALSA compatibility layer at runtime.
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt install libasound2-dev pkg-config
|
||||
|
||||
# Fedora
|
||||
sudo dnf install alsa-lib-devel pkgconf-pkg-config
|
||||
|
||||
# Arch
|
||||
sudo pacman -S alsa-lib pkgconf
|
||||
```
|
||||
|
||||
Everything else is handled by Rust dependencies: TLS uses `rustls`, MPRIS uses
|
||||
`zbus`, and image/audio decoding is provided by Rust crates.
|
||||
Equivalent ALSA development packages are required on other Linux
|
||||
distributions. macOS and Windows require no additional system packages.
|
||||
|
||||
### macOS and Windows
|
||||
|
||||
No extra system packages are required.
|
||||
|
||||
## First Run
|
||||
|
||||
On startup, `furumi` opens the login screen:
|
||||
|
||||
1. Enter your furumusic server URL.
|
||||
2. Sign in with username/password or SSO.
|
||||
3. After a successful login, the session is saved locally.
|
||||
|
||||
The SSO flow opens your browser automatically. If the loopback callback is not
|
||||
available, `furumi` shows the URL and accepts either a pasted `furumi://...`
|
||||
callback link or the short `furu_mx_...` code.
|
||||
|
||||
## Controls
|
||||
|
||||
Common key bindings:
|
||||
|
||||
| Key | Action |
|
||||
| --- | --- |
|
||||
| `?` | Show key binding help |
|
||||
| `q`, `Ctrl-C` | Quit |
|
||||
| `Tab`, `Shift-Tab` | Next / previous tab |
|
||||
| `1`...`4` | Jump to a tab |
|
||||
| `j` / `k`, arrows | Move down / up |
|
||||
| `h` / `l`, arrows | Move left / right |
|
||||
| `Enter` | Open or select item |
|
||||
| `Esc`, `Backspace` | Go back |
|
||||
| `Space` | Play / pause |
|
||||
| `n`, `p` | Next / previous track |
|
||||
| `.`, `,` | Seek 10 seconds forward / backward |
|
||||
| `+`, `-` | Volume up / down |
|
||||
| `s` | Toggle shuffle |
|
||||
| `r` | Cycle repeat mode |
|
||||
| `Shift-L` | Toggle fullscreen visualizer |
|
||||
| `x` | Like / unlike |
|
||||
| `a` | Add track next |
|
||||
| `Shift-A` | Add track to the end of the queue |
|
||||
| `Shift-P` | Add selected/current track(s) to a playlist |
|
||||
| `i`, `Shift-I` | Track info / current track info |
|
||||
| `Shift-D` | Delete selected item |
|
||||
| `v` | Toggle tile/table view |
|
||||
| `/` | Search |
|
||||
| `:` | Open command line |
|
||||
|
||||
Command line examples:
|
||||
Import a music directory from Furumi's command line:
|
||||
|
||||
```text
|
||||
:q
|
||||
:logout
|
||||
:volume 40
|
||||
:seek +30
|
||||
:seek -10
|
||||
:seek 1:30
|
||||
:shuffle
|
||||
:repeat off
|
||||
:repeat one
|
||||
:repeat all
|
||||
:clear
|
||||
:next
|
||||
:prev
|
||||
:play
|
||||
:pause
|
||||
:devices
|
||||
:logs debug
|
||||
:import /path/to/music
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
`furumi` stores configuration in the platform app config directory:
|
||||
|
||||
- Linux: `~/.config/furumi`
|
||||
- macOS: `~/Library/Application Support/furumi`
|
||||
- Windows: `%APPDATA%\furumi`
|
||||
|
||||
Important files:
|
||||
|
||||
- `credentials.json` - saved login session. On Unix it is written with `0600`
|
||||
permissions.
|
||||
- `device_id` - stable identifier for this TUI client during device sync.
|
||||
- `keymap.toml` - user key binding overrides.
|
||||
|
||||
See [`src/config/default_keymap.toml`](src/config/default_keymap.toml) for the
|
||||
default format. Example:
|
||||
|
||||
```toml
|
||||
[[keymaps]]
|
||||
key_sequence = "ctrl-n"
|
||||
command = "NextTrack"
|
||||
|
||||
[[keymaps]]
|
||||
key_sequence = "ctrl-f"
|
||||
command = { SeekForward = { seconds = 30 } }
|
||||
```
|
||||
|
||||
A user binding replaces the default binding with the same key sequence and
|
||||
context.
|
||||
|
||||
## Logs
|
||||
|
||||
The Logs tab shows a live in-memory ring buffer inside the TUI. You can jump
|
||||
to it and set the level filter with:
|
||||
|
||||
```text
|
||||
:logs error
|
||||
:logs warn
|
||||
:logs info
|
||||
:logs debug
|
||||
:logs trace
|
||||
```
|
||||
|
||||
The persistent log file is written to the platform cache directory as
|
||||
`furumi-cli.log`. File logging is filtered by `RUST_LOG`:
|
||||
|
||||
```bash
|
||||
RUST_LOG=furumi_tui=debug cargo run --release --bin furumi
|
||||
```
|
||||
Federation, trusted-device pairing, and key bindings are configured directly
|
||||
inside the player.
|
||||
|
||||
## Architecture
|
||||
|
||||
At a glance:
|
||||
Furumi is a Rust application built with:
|
||||
|
||||
- UI: `ratatui` + `crossterm`.
|
||||
- Runtime: `tokio`.
|
||||
- HTTP: `reqwest` + `rustls`.
|
||||
- Audio: `rodio` + `stream-download`.
|
||||
- Keymap config: `crokey` + TOML.
|
||||
- State model: one `AppState`, events, and an update loop.
|
||||
- `ratatui` and `crossterm` for the cross-platform TUI;
|
||||
- `rodio` for local audio playback;
|
||||
- SQLite for the personal library and synchronization state;
|
||||
- a dedicated DHT for decentralized discovery;
|
||||
- iroh-based P2P streams for client-to-client communication;
|
||||
- an offline-tolerant operation log for trusted-device synchronization;
|
||||
- Rhai for programmable audio visualizations.
|
||||
|
||||
See [`ARCHITECTURE.md`](ARCHITECTURE.md) for more detail.
|
||||
More detail is available in [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
Bug reports, design discussions, and patches are welcome. Before submitting a
|
||||
change, run:
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --all-targets
|
||||
cargo test --all-targets
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Furumi is released under the
|
||||
[Do What The Fuck You Want To Public License, Version 2](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user