Files
furumi-tui/README.md
T

397 lines
17 KiB
Markdown

# furumi
![furumi](furumi.png)
**Your music. Your devices. Your network.**
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.
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.
Furumi runs on **Linux, macOS, and Windows**.
## 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. Visualizations are runtime-loadable Rhai
scripts executed in a resource-limited sandbox, so they can be added or edited
without rebuilding the player.
Optional similarity search calculates versioned embeddings for local tracks
in the background and keeps them in SQLite. It works offline; after a separate
privacy consent it can also ask a bounded set of federation peers for matches.
Compatible peers are selected through signed, anonymous LSH summaries in a
decentralized DHT; no central recommendation index or shared calibration file
is required.
The first selectable model is downloaded on demand and is licensed separately
by MTG under CC BY-NC-SA 4.0 (a proprietary license is also available from
MTG); Furumi itself remains WTFPL.
## Install
### macOS
On Apple Silicon Macs, install Furumi from the Homebrew tap:
```bash
brew install house-of-vanity/tap/furumi
```
Run it with:
```bash
furumi
```
### Linux, Windows, and other platforms
Download a prebuilt archive from the
[GitHub releases](https://github.com/house-of-vanity/furumi_tui/releases), or
build Furumi from source with Rust 1.97 or newer:
The repository selects the stable Rust toolchain. With rustup, run
`rustup update stable` to install or update it before building.
```bash
cargo build --release --locked
./target/release/furumi
```
On Debian or Ubuntu, install the Linux audio build dependencies first:
```bash
sudo apt install libasound2-dev pkg-config
```
Equivalent ALSA development packages are required on other Linux
distributions. macOS and Windows require no additional system packages.
Import a music directory from Furumi's command line:
```text
:import /path/to/music
```
Federation, trusted-device pairing, and key bindings are configured directly
inside the player.
### Manual updates
In **Settings → Additional settings → Updates**, select **Check for updates**, then **Install update**
when a newer stable GitHub release is available. Downloads run in the background.
After installation, restart `furumi` to use the new version; playback is not
restarted automatically. Wait for an active update operation to finish before
quitting.
Updates replace the running executable in its installation directory, which
must be writable by your user. Release archives must include a matching entry
in the release's `SHA256SUMS` asset. Older releases without it cannot be installed
through this feature. The updater checks SHA-256 and the executable's format
and architecture before replacing it. Checksums provide integrity checking,
not publisher signatures. Settings and the local library are preserved.
There are no automatic startup checks. Only the existing release asset naming
scheme is supported; missing or incompatible platform builds are rejected.
The **Additional settings** window also contains the music save directory and
visualization controls. Use Up/Down (or j/k) to navigate, Enter to select, and
Esc to return to Settings. Long lists scroll with the selection.
### Tabs and key bindings
The number keys open the tabs in the order they are shown, and Tab /
Shift+Tab cycle through them:
| Key | Tab |
| --- | --- |
| `1` | Library |
| `2` | Playlists |
| `3` | Queue |
| `4` | Podcasts |
| `5` | Settings |
| `6` | Logs |
On narrow terminals the tab bar shortens titles and then shows only the
numbers, keeping the active tab's full name. Press `?` for the full list of
bindings and commands.
Bindings can be overridden in `keymap.toml` in the platform config directory
(`~/.config/furumi/keymap.toml` on Linux,
`~/Library/Application Support/furumi/keymap.toml` on macOS); the bundled
`src/config/default_keymap.toml` documents the format. Start the file with
`version = 2`, the current format: its `GoToTab` indices are used exactly as
written (`0` Library … `5` Logs). `version` must come before the first
`[[keymaps]]` entry; written after one, TOML would attach it to that entry, so
Furumi rejects such a file with an error instead of guessing. Files without `version` were written for the
older tab order (Settings and Logs on `4`/`5`, Podcasts on `6` in the
prototype podcast build); Furumi adapts their tab shortcuts in memory so they
keep opening the same tabs, shows a short notice at startup, and never
rewrites the file. Add `version = 2` once the indices match the new order to
take them literally and silence the notice.
### Podcasts
The Podcasts tab (`4`) follows RSS and Atom podcast feeds. Furumi stores only
the feed's episode information; audio stays on the publisher's server and is
never imported into the music library or offered to other peers.
- **Add podcast** (`o`, or the first row) takes a feed URL; `feed://`,
`podcast://` and URLs without a scheme are accepted. Nothing is stored unless
the URL serves a feed. New subscriptions are private.
- The list shows each podcast's unplayed and total episode counts and its
check status; `!` marks a podcast whose last check failed, with the error in
the side panel (or below the list on narrow terminals).
- `Enter` opens a podcast. Podcasts with seasons show their seasons first
(plus "All episodes" and "Without a season"); `Esc` goes back.
- Episodes show the date, season/episode number, duration and listening
state: `●` not started, `◐` in progress with the saved position, `✓` played.
`/` searches titles and descriptions, `f` cycles all / unplayed / in
progress / played, `Shift+S` changes the order, `m` marks the selected
episode played or unplayed.
- `Shift+R` checks the selected podcast for new episodes, `Ctrl+R` checks all
of them. Feeds are also checked in the background about once an hour with
conditional requests; a failing feed is retried with growing pauses and its
known episodes stay available. A permanent redirect moves the subscription
to the new address.
- `Shift+U` (or `Shift+D`) unsubscribes after a confirmation. Listening
progress and history are kept, so subscribing again continues where you
left off.
Episodes play in the same queue as music:
- `Enter` on an episode plays it right after the current item and continues
from the saved position; a played episode starts from the beginning. `b`
("start over") plays it from the beginning even when it is in progress.
`a` / `Shift+A` queue episodes like tracks, and the queue can mix music and
episodes.
- Audio streams from the publisher's server through a bounded buffer (about
9 MB) and seeks with HTTP range requests. Nothing is downloaded ahead of
time and nothing is kept after playback. If the server cannot seek (no
file length), Furumi says that it cannot continue at the saved position
instead of starting from the wrong place; "start over" still works, and
seeking in such an episode is refused with a message. If the episode's
address no longer works, the feed is checked once for a new one.
- If the connection is lost during an episode (no data for 30 seconds, or
the address stops working), playback stops there: the position is saved,
the episode is not marked played and the queue does not move on; play
continues from that position. A pause pressed while an episode is still
connecting is kept when the audio arrives.
- Some servers send episodes without a file size. There a closed connection
looks like the end of the file, so Furumi compares the position with the
episode's duration: the one the audio file states, or else the
`itunes:duration` of the feed. Feed durations are often a little off, so
reaching 80 % of one is enough; an episode that stops earlier is treated as
a lost connection. Such servers do not allow seeking either, so play cannot
continue in the middle: start the episode over (`b`) or mark it played
(`m`).
- The position is saved every 20 seconds while playing and on pause, seek,
stop, track change and exit. An episode counts as played within the last
30 seconds (or 5 %) or when its stream reaches its end; a listen enters the episode's
history when it completed or lasted at least 30 seconds. Seeking back and
"start over" are real changes: an older save never moves the position
forward again.
- Likes, playlists, music history, similarity search and share links are for
music only and skip episodes; `Shift+J` on an episode opens its podcast.
Podcasts and your connected devices:
- **Private by default.** Subscriptions, episode progress and listening
history are personal. They are synchronized only between your trusted
devices (Connected Devices), never published to the federation: no DHT
record, public catalog or search result contains them. Publishing a
podcast for discovery is a separate, explicit choice that this version
does not offer yet.
- **Synchronized between trusted devices.** A podcast you subscribe to on
one device appears on the others without typing its URL again; each
device then checks the feed itself. Unsubscribing, "played", the saved
position and "start over" follow the same way, also through a device
that relays them and after a device was offline for a while. When two
devices played the same episode offline, they agree on one position and
keep both listening sessions.
- **Handoff.** A queue with episodes moves to another device like music:
the episode continues there at the handed-off position, paused or
playing, even if that device is not subscribed. Devices that run an older
Furumi (device sync before v4) cannot keep episodes: handing such a queue
to them is refused with "needs a Furumi update", their remote control is
ignored while the queue has episodes, and they get no podcast data: they
see such a queue with "Private item" in place of each episode, so they
keep seeing this device as the playing one. An older device still takes
over when you choose it as the output (Play on it), when it starts while
this device is paused (`take_paused_on_startup`), or by itself once this
device has been closed, asleep or offline for about two minutes. Its queue
then has an unplayable "Private item" music entry for each episode; this
device shows that queue without them (with a status message), and the
episodes' saved positions stay.
- **Audio from the publisher.** Every device streams the episode from the
publisher's server itself. Furumi peers never pass podcast audio to each
other, and nothing is kept after playback.
- **Jam.** Guests see the host's episodes as "Private item" (no title, feed
or address), cannot add episodes to the host's queue and cannot seek in a
private item. They can still reorder the queue and skip.
Podcast data lives in `podcasts.sqlite3` in the platform data directory (the
same file the earlier podcast test build used; it is upgraded in place). If
that file was written by a newer Furumi or is not a podcast database, the tab
explains why it is unavailable and the file is left unchanged; podcast
changes from other devices then wait in the device-sync log until it opens.
### Now playing in tmux
While Furumi is running, a second invocation can print a cheap, single-line
playback snapshot without opening the TUI or library:
```bash
furumi --status
# ▶ Artist — Track 1:23/4:05
```
For example, add this to `.tmux.conf`:
```tmux
set -g status-interval 1
set -g status-right '#(furumi --status) | %H:%M'
```
`furumi --status-json` returns the same snapshot as JSON, including playback
state, title, artist, album, position, duration, and volume. Both commands
print nothing when Furumi is stopped or no track is loaded. On Linux, Furumi
also exposes the existing MPRIS player `cy.hexor.furumi`, which can be queried
with tools such as `playerctl`.
## Architecture
Furumi is a Rust application built with:
- `ratatui` and `crossterm` for the cross-platform TUI;
- `rodio` for local audio playback;
- SQLite for the personal library and synchronization state;
- tract ONNX inference for optional local music embeddings;
- 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.
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
```
## Playback coordination
Connected Devices uses the shared `music_dht::playback` engine from frid.
Newly started players take an idle/paused output after discovery and become
controllers when another device is playing. Missing output reports trigger
automatic failover; concurrent claims converge to one owner. The web gateway
uses a passive server profile and reports actual browser activity.
Only one TUI process may use a device identity. Installed and locally built
binaries use the same user data directory: close the installed player before
starting a development build. An OS file lock prevents duplicate coordinators
and is released automatically on exit or a crash. Older builds do not take
this lock, so close those explicitly when upgrading.
Connected-device polling runs independently per peer, so an offline or stalled
device does not postpone updates to live players.
The existing device menu handles manual transfers. Advanced policy can be set
in `settings.toml` without changing the UI:
```toml
[playback]
claim_on_startup = true
automatic_failover = true
take_paused_on_startup = true
discovery_ms = 3000
owner_timeout_ms = 120000
```
All clients must support the new coordination envelope for eventual single
output ownership. frid's `PLAYBACK_PROTOCOL.md` describes the protocol, adapter
contract and rollout. Local Cargo patches are only for development; publish
frid and bump the client dependency versions before releasing these changes.
Run the local protocol checks from the TUI repository:
```bash
cargo test localhost_devices_exchange_state_and_handoff
cargo test localhost_devices_sync_podcasts
cargo test devices::podcast_sync_tests
python scripts/test_device_interop.py ../furumusic
```
The first test uses real iroh streams, isolated SQLite databases, ownership
handoff, and a stalled peer. The podcast tests sync subscriptions, progress
and "start over" between TUI device stores (over iroh streams and through
the JSON messages), check a handoff with an episode and simulate a device
sync v3 peer with the exact JSON types of furumi-tui 0.3.x. The second builds both player test binaries and
exchanges their actual JSON messages over `127.0.0.1`: queue metadata,
bidirectional handoff, pause/seek and duplicate command fencing. It exercises
the TUI command adapter and web player hub, but does not start a browser or
PostgreSQL and does not cover web database migrations. Both tests use temporary
identities and data; no running player or user library is used.
## License
Furumi is released under the
[Do What The Fuck You Want To Public License, Version 2](LICENSE).