609 lines
32 KiB
Markdown
609 lines
32 KiB
Markdown
# Furumi architecture
|
|
|
|
Furumi is an autonomous music player that can cooperate with other Furumi
|
|
players. The architecture starts from one constraint: **a node must remain a
|
|
complete and useful player when every other node is unavailable**.
|
|
|
|
Networking therefore extends a local player instead of becoming a prerequisite
|
|
for it. There is no control plane, account service, canonical catalog, or
|
|
server-owned source of truth.
|
|
|
|
## Architectural goals
|
|
|
|
The design optimizes for five properties:
|
|
|
|
1. **Local autonomy** — importing, browsing, playback, playlists, likes, and
|
|
history work entirely on one device.
|
|
2. **No central failure domain** — discovery, catalog exchange, streaming, and
|
|
synchronization do not depend on a Furumi-operated service.
|
|
3. **Offline tolerance** — trusted devices may change state independently and
|
|
reconcile after reconnecting.
|
|
4. **Incremental federation** — one node is complete; every additional node
|
|
increases availability and the amount of discoverable music.
|
|
5. **Explicit trust boundaries** — personal-device replication and wider
|
|
music federation are different protocols with different authority.
|
|
|
|
These goals are more important than maintaining a globally identical view of
|
|
the network. Furumi prefers useful local progress and eventual reconciliation
|
|
over distributed consensus.
|
|
|
|
## The node model
|
|
|
|
Every running Furumi instance contains the same four capabilities:
|
|
|
|
```text
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Furumi node │
|
|
│ │
|
|
│ Local library ── Playback engine ── TUI / media keys │
|
|
│ │ │ │
|
|
│ ├── Trusted-device replication │
|
|
│ │ │
|
|
│ └── Federation: discovery, catalog, audio │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
The local SQLite library is authoritative for that node. Network data is
|
|
merged into local views or materialized as pending remote content; it does not
|
|
replace the local database with a remote database abstraction.
|
|
|
|
This keeps the core behavior predictable:
|
|
|
|
- disconnecting never makes the local collection unavailable;
|
|
- downloaded content can become ordinary local content;
|
|
- a peer disappearing reduces availability but does not invalidate local
|
|
state;
|
|
- nodes may join and leave without electing a leader.
|
|
|
|
## Two network layers
|
|
|
|
Furumi deliberately separates **trusted-device synchronization** from
|
|
**federated music exchange**.
|
|
|
|
### Trusted-device synchronization
|
|
|
|
This layer connects devices owned or trusted by the same user. It carries
|
|
personal state such as:
|
|
|
|
- likes and playlist operations;
|
|
- podcast subscriptions, episode progress and listening sessions;
|
|
- device membership and revocation;
|
|
- acknowledgements and synchronization progress;
|
|
- playback state, commands, and handoff information.
|
|
|
|
Pairing establishes the trust relationship. After that, changes are replicated
|
|
through an append-only operation log and applied to materialized local tables.
|
|
The wire types are the shared `music_dht::device_sync` definitions (protocol
|
|
v4); golden tests keep the v3 JSON of furumi-tui 0.3.x byte for byte.
|
|
|
|
Each device stores the protocol version that the other devices report
|
|
themselves (their hello and pairing profiles, the sender's own entry of a
|
|
`devices` list, their own profile announcements). A relayed profile only
|
|
raises a stored version, because older relays list every device with their
|
|
own constant; this build never stores its own version for another device.
|
|
Everything a peer cannot parse is gated by that version: podcast operations,
|
|
podcast snapshot sections and playback state that contains podcast items
|
|
reach only v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`,
|
|
`playback_allowed_for_peer`). An older client would reject a whole message
|
|
over one unknown operation kind, or silently drop an episode it does not
|
|
understand.
|
|
|
|
### Music federation
|
|
|
|
Federation connects independent libraries. It provides:
|
|
|
|
- decentralized discovery through the DHT;
|
|
- automatic publication of searchable local catalog metadata;
|
|
- richer artist and release catalogs fetched from peers;
|
|
- direct audio transfer when a selected track is not available locally.
|
|
|
|
Federation does not grant another peer authority over personal playlists,
|
|
likes, or device membership. A node may participate in federation without
|
|
joining another user's trusted-device group.
|
|
|
|
Keeping these layers separate prevents discovery convenience from silently
|
|
becoming a synchronization trust decision.
|
|
|
|
### Federation Jam control
|
|
|
|
Jam is a third, deliberately narrow authority boundary. A host creates an
|
|
opaque `frid://j/...` runtime capability and remains the only node producing
|
|
audio. Other TUI peers use a dedicated Jam ALPN to submit the same portable
|
|
playback commands used by connected-device control and receive the host's
|
|
playback snapshot. They receive queue metadata, not audio.
|
|
|
|
Jam never exchanges trusted membership, likes, playlists, listening history
|
|
or podcast state. The host's podcast episodes are private: the published
|
|
snapshot replaces them with opaque placeholders (`redact_for_jam`), guest
|
|
commands that add episodes are dropped, and a guest's placeholders are mapped
|
|
back to the host's episodes (`restore_jam_private_items`); a change that
|
|
drops, duplicates or seeks in them is refused. Volume remains local. Commands carry unique IDs and are retried until
|
|
the host acknowledges them, while inactive participants expire from the
|
|
runtime session. Regenerating the capability or restarting the host invalidates
|
|
the previous link.
|
|
|
|
## Discovery and direct communication
|
|
|
|
Furumi separates finding content from transferring it.
|
|
|
|
```text
|
|
discovery plane
|
|
Local catalog ───────> DHT <─────── Other catalogs
|
|
│
|
|
│ peer + content identity
|
|
v
|
|
direct P2P connection
|
|
├── catalog protocol
|
|
├── audio protocol
|
|
└── device-sync protocol
|
|
```
|
|
|
|
The DHT is the distributed index. Nodes publish compact searchable
|
|
descriptions of their local library and query the network without contacting a
|
|
central search service.
|
|
|
|
Opening a local artist or release card in a network-enabled library view
|
|
enriches it asynchronously. DHT matches identify likely catalog owners, while
|
|
a bounded set of known peers can also answer directly when the index is
|
|
incomplete. Card results are replaceable snapshots: reopening a card or
|
|
periodic maintenance retries discovery, with at most one request per card in
|
|
flight. A failed refresh keeps the last usable snapshot, and never prevents
|
|
browsing the local tracks.
|
|
|
|
Similarity discovery uses a separate schema-independent DHT overlay. A node
|
|
derives a deterministic 256-bit routing signature from every local embedding,
|
|
groups them into fixed two-level LSH buckets, and publishes compact summaries
|
|
containing only fine-bucket representatives, its peer identity, and the ticket
|
|
needed to dial a previously unknown owner. The owner signs every summary with
|
|
its existing transport key, so storage peers can relay and cache it but cannot
|
|
impersonate or modify it. Summaries expire with the ordinary library-record TTL
|
|
and are replaceable federation cache, never local library authority.
|
|
|
|
A similarity search first performs bounded multi-probe LSH lookups to rank
|
|
likely owners, then sends the existing normalized-vector request directly to
|
|
at most 16 peers initially and 48 on fallback. Known peers remain a rollout
|
|
fallback. The model, preprocessing, durable embeddings, exact cosine search,
|
|
and consent policy remain client-owned; `music-dht` owns only compatible
|
|
routing math, signed records, replication, and wire bounds.
|
|
|
|
Once a peer is known, communication moves to direct P2P streams provided by
|
|
iroh through `music-dht`. Furumi defines separate application protocols for
|
|
catalog requests, audio transfer, and trusted-device synchronization. This
|
|
keeps discovery traffic small and lets large or private exchanges happen only
|
|
between the participating peers.
|
|
|
|
Relay-assisted connectivity may help peers establish a route, but relays do
|
|
not become catalog authorities or application-state owners.
|
|
|
|
## Identity and content resolution
|
|
|
|
Network operations refer to content independently of any one library row.
|
|
Content identifiers allow a node to ask:
|
|
|
|
1. Is this track already present in my local library?
|
|
2. Does one of my trusted devices have it?
|
|
3. Which federation peers currently advertise it?
|
|
|
|
Resolution follows that order conceptually: prefer a ready local source, reuse
|
|
known content where possible, and fetch from a peer only when necessary.
|
|
|
|
A federated track can initially exist as a lightweight pending item in a queue
|
|
or playlist. When playback reaches it, Furumi resolves an available peer,
|
|
starts the transfer, and either uses the cache or imports the result into the
|
|
local library. The rest of the player continues to work with the same
|
|
`TrackItem` model, so local and remote availability do not require separate
|
|
playback systems.
|
|
|
|
## Offline-first synchronization
|
|
|
|
Trusted devices do not share a live database connection. Each device records
|
|
operations locally and exchanges them when connectivity returns.
|
|
|
|
The synchronization model combines:
|
|
|
|
- immutable operation identifiers for deduplication;
|
|
- hybrid logical timestamps for deterministic last-writer decisions;
|
|
- materialized tables for fast UI queries;
|
|
- tombstones so deletion survives offline replicas;
|
|
- per-peer acknowledgements to determine when old tombstones can be compacted;
|
|
- snapshots to repair a peer that missed older operations.
|
|
|
|
Vectors only grow, so operations hidden from a peer while it ran an older
|
|
protocol are never sent again after it upgrades. Snapshots are the recovery
|
|
path for that case; the podcast sections carry the subscription, share and
|
|
progress registers and the most recent listening sessions, bounded by the
|
|
shared FRID limits and by the line budget of each message.
|
|
|
|
This is eventual consistency scoped to a trusted device group. A temporarily
|
|
offline laptop can modify playlists, another device can continue playback, and
|
|
both can later converge without a permanently available coordinator.
|
|
|
|
Membership changes use the same replicated model. Revocation is state that
|
|
must propagate and converge, not an ephemeral server-side session flag.
|
|
|
|
## Playback across devices
|
|
|
|
A persisted device identity has exactly one live coordinator. The TUI holds
|
|
an OS file lock beside its device-sync database for the entire runtime; two
|
|
installations using the same user data directory cannot open it concurrently.
|
|
Network polling is independent per trusted peer, with one in-flight exchange
|
|
per peer and a bounded deadline. A stalled peer must not delay the next poll
|
|
of a healthy output. Poll tasks are cancelled when federation shuts down.
|
|
|
|
Playback has one logical state but remains physically local to the device
|
|
producing audio.
|
|
|
|
The synchronized state describes the queue, current item, position, pause
|
|
state, volume, shuffle/repeat mode, and the active playback owner. Commands are
|
|
targeted and deduplicated. Handoff transfers intent and position; the receiving
|
|
device resolves the track against its own library or federation sources before
|
|
starting its audio engine. Each queue item names its source: a podcast episode
|
|
travels as `PlaybackSource::PodcastEpisode` with the reference needed to play
|
|
it (the receiving device streams it from the publisher at the handed-off
|
|
position, with or without a subscription). A queue with episodes is not handed
|
|
to a device below protocol v4, and playback commands from such a device are
|
|
ignored while the local queue has episodes. Such a device still gets the
|
|
playback snapshot with its coordination envelope, but with every episode
|
|
replaced by an opaque "Private item" (`redact_for_jam`): an engine renews the
|
|
owner's liveness only from the owner's own announcements, so an old device
|
|
that heard nothing would take over by automatic failover after
|
|
`owner_timeout_ms` and replace the queue. This departs from FRID's
|
|
`PLAYBACK_PROTOCOL.md` rule 1 ("otherwise send `None`") and is reported to
|
|
FRID as a contract gap. An old device that mirrors such a queue drops the
|
|
`source` its types do not know, so each placeholder becomes a music item
|
|
titled "Private item"; when it later takes over (Play on it, a paused-startup
|
|
claim, failover while this device is gone) or sends a command, it announces
|
|
those. States from devices below v4 are therefore cleaned on receipt
|
|
(`drop_echoed_private_items`: bare music items with that title and no content
|
|
id, federated source, artist, release or duration), with a status message.
|
|
|
|
Active-device leases and idle timing prevent stale snapshots from immediately
|
|
taking control after a device reconnects. This provides practical coordination
|
|
without introducing a central playback arbiter.
|
|
|
|
## Local application architecture
|
|
|
|
Inside one node, Furumi uses an event-driven state machine:
|
|
|
|
```text
|
|
terminal / player / database / network / OS media events
|
|
│
|
|
v
|
|
AppEvent
|
|
│
|
|
input → Action
|
|
│
|
|
v
|
|
update(AppState)
|
|
│
|
|
optional Effect
|
|
│
|
|
v
|
|
asynchronous runtime work
|
|
│
|
|
└──────────> AppEvent
|
|
```
|
|
|
|
`AppState` is the single source of truth for the interface. The update layer
|
|
performs deterministic state transitions and requests effects; it does not
|
|
perform blocking I/O. SQLite access, imports, artwork decoding, DHT queries,
|
|
peer transfers, and audio preparation run through runtime services and report
|
|
their results as events.
|
|
|
|
This structure gives the TUI three important properties:
|
|
|
|
- rendering is a pure projection of current state;
|
|
- input behavior can be tested without starting audio or networking;
|
|
- slow peers and large imports cannot block terminal interaction.
|
|
|
|
The audio engine is similarly isolated. The application owns the logical
|
|
queue, while `player::Controller` owns rodio playback and receives explicit
|
|
commands. Prefetching prepares the next source before the current item ends.
|
|
|
|
### Versioned key bindings
|
|
|
|
Key bindings are semantic `Action` values loaded from the bundled defaults and
|
|
merged with the user's `keymap.toml`. Some actions carry positional meaning
|
|
(`GoToTab(index)` follows the displayed tab order), so changing the tab order
|
|
changes what an existing user file means. The keymap file therefore carries a
|
|
format `version`. Files from an older format are adapted in memory when they
|
|
are loaded and the user is told once per start; Furumi never rewrites a
|
|
user's configuration. The current format, version 2, orders tabs as Library,
|
|
Playlists, Queue, Podcasts, Settings, Logs; unversioned files use the earlier
|
|
order and have their tab indices remapped. A `version` key that TOML attached
|
|
to a binding (written after a `[[keymaps]]` header) is rejected, so a versioned
|
|
file is never silently mistaken for a legacy one.
|
|
|
|
## Podcasts
|
|
|
|
Podcasts are a separate content type, not library tracks. The shared contract
|
|
lives in FRID: `music_dht::podcast` defines podcast and episode identity, feed
|
|
URL canonicalization, the RSS/Atom parser and the merge rules, and
|
|
`furumi_library::podcasts::PodcastStore` persists the catalog, the personal
|
|
registers (subscription, share, progress) and listening sessions in
|
|
`podcasts.sqlite3`. The TUI does not re-derive ids or merge rules.
|
|
|
|
The TUI owns what the contract leaves to clients:
|
|
|
|
- **Fetching.** Feeds are fetched with conditional requests (ETag,
|
|
Last-Modified), bounded size (32 MiB per feed, 10 MiB per cover) and time
|
|
(15 s to connect, 60 s per request, 120 s for a whole fetch with its
|
|
redirects), and at most 10 redirects (http and https only) followed by
|
|
hand. The
|
|
address that the leading permanent hops (301/308) lead to becomes a feed
|
|
alias and the fetch URL, even when a temporary hop (CDN, tracker) follows
|
|
it; a chain that starts with a temporary hop never moves the feed.
|
|
Validators are dropped after a permanent redirect because they belong to
|
|
the old address. The prototype database's validators are dropped once at
|
|
import, so the first check parses the feed (seasons and episode numbers
|
|
were not stored by the prototype).
|
|
- **Scheduling.** The store keeps each feed's local fetch state (validators,
|
|
last error, consecutive failures, next check). A timer asks it which
|
|
subscriptions are due; feeds are checked at most a few at a time, a success
|
|
waits an hour, and failures back off exponentially (honouring
|
|
`Retry-After`). Errors never clear the stored catalog.
|
|
- **Runtime boundary.** Every store call, fetch and parse of the app runs on
|
|
the blocking pool or as a task and reports back through `AppEvent`s;
|
|
`update::podcasts` holds the pure state transitions. The device-sync
|
|
stream handlers call the store (snapshot export and merges) inside
|
|
`block_in_place`, so a store busy with a large feed refresh does not hold
|
|
a Tokio worker's other tasks; they are never called on the UI thread. Store open failures (newer schema,
|
|
foreign file) disable only the Podcasts tab and leave the file untouched.
|
|
- **Sync log.** Local actions (subscribe, unsubscribe, mark played, progress)
|
|
draw their operation stamps from the device-sync log through
|
|
`DeviceSync::run_podcast_action`, and the operations are appended with
|
|
exactly those stamps, so the store's registers and the log agree. The lock
|
|
order is podcast store, then sync log; device sync never calls the store
|
|
while it holds the log. Only the newest progress operation of an origin per
|
|
episode stays in the log (later operations of one origin always win the
|
|
register comparison).
|
|
- **Device sync.** Received podcast operations are kept in the log (and
|
|
relayed) and merged into the store with `PodcastStore::apply_remote_op`;
|
|
invalid ones are skipped but acknowledged. Operations that arrive before
|
|
the store opens wait in `sync_podcast_pending` and are applied when it is
|
|
attached. Snapshot sections are exported with `fill_snapshot` and merged
|
|
with `apply_snapshot` after the operations of the same message. The UI
|
|
reloads what it shows after such changes and checks the feed of a
|
|
subscription that came from another device.
|
|
- **Queue identity.** An episode is a `TrackItem` with an explicit
|
|
`podcast` reference (`TrackItem::podcast_episode`); its numeric id is a
|
|
shared sentinel and never identifies it. Queue keys check the episode id
|
|
first (`ep:…`), then music content ids, federated sources and library rows.
|
|
Music-only paths (likes, playlists, history, content-id resolution,
|
|
federation download, similarity, share links, metadata edits, release and
|
|
artist jumps) check `is_podcast()` and skip episodes. On the wire an
|
|
episode is `PlaybackSource::PodcastEpisode`; received ones become episodes
|
|
again (`TrackItem::from_playback_track`) and the library source mode never
|
|
drops them. Jam private placeholders are numbered queue entries that go
|
|
back on the wire as `PlaybackSource::Private`.
|
|
- **Playback.** Starting an episode resolves its current audio URL and
|
|
resume position from the store, opens `podcasts::stream` (a bounded
|
|
Range-request reader on its own thread), decodes and positions it with
|
|
coarse seeking, all off the UI and audio threads, then hands the source to
|
|
the audio thread with the player's source generation. Any later start or
|
|
stop bumps that generation, so a slow stream never replaces what the user
|
|
chose since. A stale audio URL (4xx) triggers one feed refresh and a retry
|
|
with the address the feed lists for the same episode id. A stream that
|
|
cannot seek does not start at a saved position it cannot reach, and seeks
|
|
in it (or in an episode still connecting) are refused. The stream is
|
|
cancelled by the same generation: a superseded start stops connecting or
|
|
reading up to its resume offset, and a read blocked on a stalled server
|
|
inside the audio callback returns within 100 ms, so it cannot hold the
|
|
audio thread past the next stop or start. The player does not report the
|
|
end of a superseded source. Pause and resume pressed while a source is
|
|
prepared update the intent it starts with.
|
|
- **End of a stream.** The reader records whether the decoder stopped on a
|
|
read error (lost connection, expired URL, cancellation) and whether the
|
|
server announced the file size. Only an end that the server described, or
|
|
one within the completion window, completes the episode and moves the
|
|
queue on; otherwise the last seen position is saved and playback stops on
|
|
the episode (`playback::played_to_the_end`).
|
|
- **Progress.** `podcasts::progress` runs one writer thread so every
|
|
progress write of this device is ordered. The app tick follows the
|
|
position and actual listening time and sends: an explicit start (or
|
|
"start over"), checkpoints every 20 s and on pause, explicit seeks (saved
|
|
once the audio thread reports that the seek worked,
|
|
`PlayerEvent::Seeked`), completion (`reaches_completion` or the real end
|
|
of the stream) and an end with the last
|
|
seen position on stop, track change, handoff and exit. When the store
|
|
reports a newer generation (another device started over, for example), the
|
|
playback stops checkpointing until the user's next explicit action.
|
|
Listening sessions are recorded at pause, completion and end; the store
|
|
keeps those that pass the shared threshold. Queue items carry the latest
|
|
progress generation this device saw, so a handoff target starts its
|
|
session above it.
|
|
|
|
## Scripted visualizations
|
|
|
|
Visualizations are an extension boundary rather than hard-coded rendering
|
|
paths. Rust owns audio sampling, script execution, validation, and terminal
|
|
drawing; Rhai scripts own the visual composition.
|
|
|
|
```text
|
|
rodio source
|
|
│
|
|
v
|
|
audio analyzer ──> normalized features + scope samples
|
|
│
|
|
v
|
|
Rhai render(input)
|
|
│
|
|
v
|
|
validated draw commands
|
|
│
|
|
v
|
|
ratatui frame buffer
|
|
```
|
|
|
|
The player analyzer derives a bounded, renderer-independent input model:
|
|
energy, bass, mid, treble, beat strength, waveform samples, playback progress,
|
|
volume, pause state, track metadata, time, and terminal dimensions. Each
|
|
script implements `render(input)` and returns declarative commands such as
|
|
clear, cell, line, rectangle, trace, and text. Scripts never receive the
|
|
ratatui frame or audio engine directly.
|
|
|
|
This command boundary is intentional:
|
|
|
|
- scripts remain independent of Rust UI internals;
|
|
- the host validates command shapes, colors, coordinates, and arrays;
|
|
- drawing is clipped to the current terminal area;
|
|
- script failures become an in-UI visualizer error instead of corrupting the
|
|
terminal or stopping playback.
|
|
|
|
Rhai files live in the user's visualization directory. The runtime discovers
|
|
them dynamically, compiles the selected script, caches its AST, and recompiles
|
|
it when the file modification time changes. A visualization can therefore be
|
|
created or edited while Furumi is running without rebuilding or restarting the
|
|
application. Bundled scripts use the same path and contract as user scripts,
|
|
so built-in and custom visualizations exercise the same runtime.
|
|
|
|
The v2 primitives are sufficient for small perspective wireframes without a
|
|
native 3D engine. The bundled morphing cube transforms eight vertices in Rhai
|
|
and batches its twelve edges into trace/vertical-line commands. Perspective,
|
|
audio-driven deformation, and depth cues stay in the user-editable script;
|
|
Rust rasterizes the resulting 2D commands. This deliberately avoids per-cell
|
|
script command maps and does not provide filled meshes or a depth buffer.
|
|
The richer cube preset adds bounded particle, ring, inner-cage, and echo
|
|
layers. Echo poses are reconstructed from earlier times with current audio
|
|
features, rather than retaining previous frames; particles have deterministic
|
|
lifetimes. Small terminals omit expensive layers and reduce particle counts.
|
|
|
|
The Rhai engine is configured as a sandboxed computation environment. Module
|
|
loading through `import` and `export` is disabled, no filesystem or network API
|
|
is exposed to scripts, and execution is bounded by limits on operations, call
|
|
depth, variables, functions, expression depth, and collection/string sizes.
|
|
Only the input map, Rhai language primitives, and a small set of mathematical
|
|
helpers are available.
|
|
|
|
The sandbox protects responsiveness and keeps visualization code in its
|
|
intended role: transforming current audio features into drawing commands. It
|
|
is not a plugin mechanism for accessing the library, network, or player
|
|
controls.
|
|
|
|
Fullscreen execution currently happens synchronously during UI drawing, with a fresh
|
|
Rhai scope for each frame; scripts should derive motion from time and the
|
|
already-smoothed audio features rather than rely on retained mutable state.
|
|
The 50 ms animation timer gives a nominal 20 FPS cadence (other events can
|
|
also trigger redraws). Operation limits are not wall-clock deadlines. The
|
|
host also checks the script modification time during drawing, so slow script
|
|
storage or expensive custom scripts can still delay input. Benchmark script
|
|
evaluation and buffer drawing separately from real terminal throughput before
|
|
increasing scene complexity or the refresh rate.
|
|
|
|
The embedded status surface uses the same Rhai engine, input map, command
|
|
decoder, and clipped buffer rasterizer with a one-row viewport. It has an
|
|
independent AST cache and a fixed user-editable script in
|
|
`visualizations/status/braille.rhai`, installed if absent. Exact copies of the
|
|
previous bundled default can be atomically upgraded; edited files are preserved. It is not a
|
|
fullscreen preset. During local playback the visual timer samples the audio
|
|
analyzer without increasing trusted-device publication frequency. At most
|
|
one blocking render job is in flight; excess ticks are dropped. File access,
|
|
compilation, evaluation, and buffer preparation happen on that worker.
|
|
An `AppEvent` delivers a prepared row to `AppState`; UI drawing only copies
|
|
cells. Its audio input comes from the decoded-source analyzer before output
|
|
volume scaling; the volume field remains informational. Pause suspends jobs
|
|
and retains the last frame, even when the row needs resizing. Generation
|
|
checks discard results invalidated by track changes, resize, pause/resume,
|
|
or stop. Script errors are confined to the row and retried so
|
|
editing the file repairs the display. Status scripts have a smaller operation
|
|
budget, bounded source/output sizes, and cannot draw outside their viewport.
|
|
|
|
## Music-similarity indexing
|
|
|
|
Similarity search is an optional local capability and is disabled by default.
|
|
When enabled, a background pipeline downloads a selected ONNX model, verifies
|
|
its pinned SHA-256 digest, decodes durable local tracks, and stores normalized
|
|
embeddings in the library SQLite database. Embeddings are keyed by an exact
|
|
fingerprint of the model artifact and preprocessing profile. Old profile rows
|
|
remain available while a new profile is calculated, and the in-memory exact
|
|
cosine index switches only after the replacement profile is usable.
|
|
|
|
The SQLite rows are the canonical derived store. The in-memory index can be
|
|
discarded and rebuilt, and neither is required for import, browsing, or
|
|
playback. Remote/cache-only tracks are never scheduled for local embedding.
|
|
|
|
Federated similarity uses a separate versioned direct-stream protocol. With
|
|
explicit privacy consent, the requester sends only a normalized embedding and
|
|
its profile fingerprint to a bounded set of known peers. It does not publish
|
|
queries to the DHT. Each peer searches its own active local index and returns a
|
|
bounded metadata result with a compact embedding SimHash. The requester uses
|
|
that signature to suppress near-duplicate recordings across peers without
|
|
receiving every result vector. Fan-out, concurrency, message sizes, and
|
|
timeouts are bounded; incompatible profiles are rejected. This direct
|
|
peer-selection layer can later be replaced by DHT routing without changing
|
|
local storage or ranking.
|
|
|
|
## Persistence boundaries
|
|
|
|
Furumi stores different kinds of state according to their lifetime:
|
|
|
|
| State | Storage | Role |
|
|
| --- | --- | --- |
|
|
| Library, playlists, likes, history | SQLite | Durable local source of truth |
|
|
| Podcast subscriptions, episodes, progress | SQLite (`podcasts.sqlite3`, FRID store) | Durable personal state (synced with trusted devices) and a refreshable episode catalog |
|
|
| Device operation log and replicas | SQLite | Offline synchronization |
|
|
| Versioned track embeddings | SQLite | Durable, locally rebuildable similarity data |
|
|
| Federation catalog cache | SQLite/cache | Faster network browsing |
|
|
| Audio and artwork cache | Filesystem cache | Reusable fetched data |
|
|
| Settings, keymap, identity | Platform config/data dirs | Node configuration |
|
|
| Queue and playback snapshots | Application/device sync state | Continuity and handoff |
|
|
|
|
Caches are replaceable. The local library, the podcast store's personal state
|
|
and the device operation log are durable.
|
|
This distinction lets maintenance and recovery code discard derived network
|
|
data without risking the user's collection.
|
|
|
|
## Failure model
|
|
|
|
Expected failures are treated as ordinary state:
|
|
|
|
- a DHT query may return partial results;
|
|
- an advertised peer may be offline by the time a track is requested;
|
|
- a transfer may stop and be retried through another source;
|
|
- trusted devices may reconnect with overlapping changes;
|
|
- cached metadata may be stale;
|
|
- an audio device may disappear during playback.
|
|
|
|
The architecture avoids converting these cases into global failure. Search can
|
|
show partial data, synchronization can resume, and playback resolution can try
|
|
another source. Errors return to the application as events so the UI can expose
|
|
them without terminating the node.
|
|
|
|
## Main implementation boundaries
|
|
|
|
The source tree follows the architectural responsibilities:
|
|
|
|
- `library/` owns the local catalog and import pipeline;
|
|
- `player/` owns audio playback and analysis;
|
|
- `similarity.rs` owns model acquisition, preprocessing, background indexing,
|
|
and the replaceable exact in-memory index;
|
|
- `federation/` owns DHT-facing search, peer catalogs, and audio exchange;
|
|
- `podcasts/` owns feed HTTP (conditional requests, redirects, limits),
|
|
refresh scheduling policy, the episode stream reader and the progress
|
|
writer; the podcast model, identity, merge rules and SQLite store come
|
|
from FRID;
|
|
- `devices.rs` owns trusted-device replication and playback coordination;
|
|
- `app/` owns state transitions and runtime orchestration;
|
|
- `ui/` renders the TUI;
|
|
- `media.rs` integrates platform media controls;
|
|
- `visualizer.rs` hosts programmable Rhai visualizations.
|
|
|
|
Dependencies should continue to point inward toward typed models and explicit
|
|
events. UI code should not own network tasks, network protocols should not
|
|
mutate UI state directly, and the local library should not depend on the
|
|
presence of federation.
|
|
|
|
## Architectural invariants
|
|
|
|
Future changes should preserve these rules:
|
|
|
|
1. A node must start and play its local library without network access.
|
|
2. No central Furumi service may become required for discovery, playback, or
|
|
trusted-device synchronization.
|
|
3. Federation membership must not imply personal-device trust.
|
|
4. Remote state must be merged or cached locally, never treated as an always
|
|
available database.
|
|
5. Network and storage work must remain outside the interactive UI path.
|
|
6. More peers should improve availability; losing peers should only reduce
|
|
remote capabilities.
|