2026-11-18 15:17:50 +00:00
|
|
|
# Using and administering Furumusic
|
|
|
|
|
|
|
|
|
|
[Project overview](../README.md) · [Installation](setup.md) · [Development and tests](development.md)
|
|
|
|
|
|
|
|
|
|
## Access and public sharing
|
|
|
|
|
|
|
|
|
|
OIDC identifies accounts by issuer and subject. Matching admin groups take
|
|
|
|
|
precedence over matching user groups, and either SSO grant takes precedence over
|
|
|
|
|
a local role. Without matching groups (including an empty group configuration),
|
|
|
|
|
a new account waits for approval in **Admin → Users**. Any instance administrator
|
|
|
|
|
can approve it as a user or administrator. The waiting page updates automatically.
|
|
|
|
|
On subsequent SSO logins the group grant is refreshed: if it disappears, only an
|
|
|
|
|
independently assigned local role preserves access. Existing password accounts
|
|
|
|
|
keep their local roles; existing OIDC-only accounts retain their last SSO grant
|
|
|
|
|
until the next login, without receiving an implicit local approval.
|
|
|
|
|
|
|
|
|
|
Sharing creates an unguessable `/share/{token}` link to a snapshot of track IDs,
|
|
|
|
|
including their order and repetitions. Guests and accounts awaiting approval can
|
|
|
|
|
play and download only the tracks in that snapshot, using the regular player.
|
|
|
|
|
They cannot browse the library, search, use recommendations, or write personal
|
|
|
|
|
history. Signing in from a share returns to that share; signing in from the root
|
|
|
|
|
shows only the approval page until access is granted. Track info offers a browser
|
|
|
|
|
download of the original audio file. The old radio implementation is removed.
|
|
|
|
|
|
|
|
|
|
Migration `m_0053_local_approval_and_public_shares` deletes the old share records.
|
|
|
|
|
Old track/release/playlist URL routes are removed, with no compatibility layer.
|
|
|
|
|
Link expiry, cleanup, and revocation are not part of this implementation.
|
|
|
|
|
|
|
|
|
|
## Importing music
|
|
|
|
|
|
|
|
|
|
Users can add audio files from the web interface or ask the server to download
|
|
|
|
|
selected files from a torrent. Both routes feed the same import pipeline, so a
|
|
|
|
|
library remains consistent regardless of where its files came from.
|
|
|
|
|
|
|
|
|
|
The importer combines embedded tags, filenames, folder structure, and existing
|
|
|
|
|
catalog context. With an OpenAI-compatible language model configured, it can
|
|
|
|
|
normalize artist and release names, separate featured artists, recover track
|
|
|
|
|
numbers and release types, and flag ambiguous results for a user to approve.
|
|
|
|
|
Cover art is taken from nearby image files or embedded artwork when available.
|
|
|
|
|
|
|
|
|
|
The inbox and permanent library are separate directories. New files are first
|
|
|
|
|
processed in the inbox and are moved into the organized library only after
|
|
|
|
|
their metadata has been accepted.
|
|
|
|
|
|
|
|
|
|
## Importing into playlists
|
|
|
|
|
|
|
|
|
|
The player's download manager offers **Add downloads to a playlist** for file
|
|
|
|
|
and folder uploads and torrents, as well as YouTube. Choose an existing owned
|
|
|
|
|
playlist or create one before starting; leaving the choice empty imports only
|
|
|
|
|
into the library. Selected audio tracks are appended after processing or manual
|
|
|
|
|
approval, including files resolved to tracks already in the library.
|
|
|
|
|
|
|
|
|
|
Migration `m_0052_add_import_playlist_destinations` persists the destination and
|
|
|
|
|
completion receipts. Retries and restarts retain the choice, avoid duplicates,
|
|
|
|
|
and do not re-add tracks subsequently removed by the user. A started batch keeps
|
|
|
|
|
its destination for its remaining files.
|
|
|
|
|
|
|
|
|
|
## Federation
|
|
|
|
|
|
|
|
|
|
Federation is optional. Independent Furumusic and Furumi players that use the
|
|
|
|
|
same Network ID discover one another as a logical network. Each peer keeps its
|
|
|
|
|
own library and can continue working alone.
|
|
|
|
|
|
|
|
|
|
When federation is enabled, local and remote artists, releases, and tracks can
|
|
|
|
|
appear in the same search and library views. Missing audio is streamed from an
|
|
|
|
|
available peer and can optionally be retained locally. Similarity search also
|
|
|
|
|
stays decentralized: embeddings and exact ranking remain on the instance that
|
|
|
|
|
owns the music.
|
|
|
|
|
|
|
|
|
|
Trusted-device pairing is separate from public catalog discovery. It connects
|
|
|
|
|
a user's own Furumi players so likes, playlists, playback state, and control can
|
|
|
|
|
move between approved devices.
|
|
|
|
|
|
2026-11-19 21:14:54 +02:00
|
|
|
Queues synchronized from other Furumi players can contain podcast episodes;
|
|
|
|
|
the web player plays them (see [Podcasts](#podcasts)) and keeps them in order
|
|
|
|
|
with their position. A device that does not support podcasts yet (device-sync
|
|
|
|
|
protocol below 4, for example an older terminal player) cannot receive such a
|
|
|
|
|
queue: selecting it as the playback device shows that it needs an update, and
|
|
|
|
|
the episodes stay in the queue. Jam guests see podcast episodes of the host
|
|
|
|
|
only as private items they cannot play, add, remove or clear.
|
|
|
|
|
|
|
|
|
|
## Podcasts
|
|
|
|
|
|
|
|
|
|
**Podcasts** in the player sidebar lists your subscriptions with the number
|
|
|
|
|
of unplayed episodes and the result of the last feed check. Paste an RSS or
|
|
|
|
|
Atom feed URL to subscribe: the server loads the feed first and shows why when
|
|
|
|
|
it cannot (not a feed, not reachable, or an address that is not public). A
|
|
|
|
|
podcast page shows the description, the seasons (episodes without a season
|
|
|
|
|
form their own group), a search over episode titles and descriptions, filters
|
|
|
|
|
for unplayed, started and played episodes, and the recent listening history.
|
|
|
|
|
|
|
|
|
|
- **Play / Resume** continues an episode where you stopped, on whichever of
|
|
|
|
|
your Furumi players last saved it. **Start over** plays it from the
|
|
|
|
|
beginning; **Mark played** and **Mark unplayed** change its status without
|
|
|
|
|
playing (marking does not count as a listen). An episode counts as listened
|
|
|
|
|
when playback reaches its end, or its last 30 seconds or last 5 %, whichever
|
|
|
|
|
is shorter.
|
|
|
|
|
- The web player saves the position about every 20 seconds and when you
|
|
|
|
|
pause, seek, switch items, close the page or hand playback to another
|
|
|
|
|
device, without interrupting the audio.
|
|
|
|
|
- Handing playback to another device keeps the episode, its position and
|
|
|
|
|
whether it was paused. A later save of an older listening session never
|
|
|
|
|
moves the position back after you seek or start over elsewhere.
|
|
|
|
|
- **Unsubscribe** stops checking the feed and keeps your progress and history;
|
|
|
|
|
subscribing again continues where you stopped. **Refresh** checks the feed
|
|
|
|
|
now (at most every 30 seconds).
|
|
|
|
|
|
|
|
|
|
Privacy: a new subscription is private. Subscriptions, progress and listening
|
|
|
|
|
history are synchronized only between your own paired Furumi players (trusted
|
|
|
|
|
devices), never published to the federation, and Jam guests cannot see your
|
|
|
|
|
episodes. Publishing a podcast for discovery is not available in the web
|
|
|
|
|
player yet. Episodes are not stored on the server or shared with peers: the
|
|
|
|
|
browser streams the audio and loads the artwork directly from the publisher,
|
|
|
|
|
so the publisher sees your browser's address. With the audio proxy (below)
|
|
|
|
|
the publisher sees the server instead.
|
2026-11-19 16:58:32 +02:00
|
|
|
|
2026-11-19 20:24:30 +02:00
|
|
|
### Podcast feeds and audio
|
|
|
|
|
|
|
|
|
|
The `podcast_refresh` job (every five minutes, listed under Jobs) checks the
|
|
|
|
|
feeds of subscribed podcasts: each feed about once an hour with conditional
|
|
|
|
|
requests, failing feeds less and less often (up to once a day). It downloads
|
|
|
|
|
feed metadata only, never episode audio. A failing feed keeps its known
|
|
|
|
|
episodes. Accounts subscribed to the same feed share one request.
|
|
|
|
|
|
|
|
|
|
The server therefore makes outgoing HTTP(S) requests to podcast publishers.
|
|
|
|
|
It only connects to public addresses: feed or audio URLs that point to
|
|
|
|
|
loopback, private, link-local, CGNAT or cloud metadata addresses, directly,
|
|
|
|
|
through DNS or through a redirect, are refused. System proxy settings are not
|
|
|
|
|
used for these requests.
|
|
|
|
|
|
|
|
|
|
Episode audio is streamed by the browser directly from the publisher. Some
|
2026-11-19 21:14:54 +02:00
|
|
|
publishers cannot be played that way (plain HTTP while this server uses
|
|
|
|
|
HTTPS, or a server the browser refuses). For them, enable **Settings →
|
|
|
|
|
Podcasts → Podcast audio proxy** (`FURU_PODCAST_AUDIO_PROXY_ENABLED=true`):
|
|
|
|
|
the player then switches to the proxy when the direct URL fails or is plain
|
|
|
|
|
HTTP on an HTTPS page, and the server fetches the audio from the publisher
|
|
|
|
|
and passes it through without storing it. This uses the server's bandwidth.
|
|
|
|
|
|
|
|
|
|
Security model of the proxy:
|
|
|
|
|
|
|
|
|
|
- It takes an episode id, never a URL. The URL comes from the signed-in
|
|
|
|
|
account's own podcast catalog: its feeds, and episode references that its
|
|
|
|
|
own trusted devices sent (for example the current item of a handoff). Any
|
|
|
|
|
signed-in user can therefore make the server fetch audio URLs of feeds they
|
|
|
|
|
subscribe to, as with feed refreshes.
|
|
|
|
|
- The same public-address checks as for feeds apply to every connection and
|
|
|
|
|
redirect; only audio content types are passed through (no HTML, no video),
|
|
|
|
|
with a single byte range, up to 1 GiB and 4 hours per request, and no
|
|
|
|
|
cookies or credentials are sent.
|
|
|
|
|
- Responses are not cached or stored, and are marked `no-store`, `nosniff`
|
|
|
|
|
and sandboxed.
|
|
|
|
|
|
|
|
|
|
Leave it off unless your users need it.
|
2026-11-19 20:24:30 +02:00
|
|
|
|
2026-11-19 19:55:46 +02:00
|
|
|
### Upgrading from 0.13
|
|
|
|
|
|
2026-11-19 21:14:54 +02:00
|
|
|
Release 0.14 adds the podcast UI and playback described above; no setting is
|
|
|
|
|
needed besides the optional proxy.
|
|
|
|
|
|
2026-11-19 19:55:46 +02:00
|
|
|
Podcast state synchronized from other Furumi players is kept in per-account
|
|
|
|
|
podcast tables (`furumusic__podcast*`). The upgrade imports what 0.13 kept in
|
|
|
|
|
`furumusic__fed_podcast_relay`; that table is no longer used and can be
|
|
|
|
|
dropped by a later release. Release 0.13 does not read the new tables: after
|
|
|
|
|
a rollback it would serve the relay table as it was at the upgrade, and
|
|
|
|
|
devices would send their newer podcast state again in their snapshots.
|
|
|
|
|
|
2026-11-19 19:22:19 +02:00
|
|
|
### Rolling back to 0.12
|
|
|
|
|
|
|
|
|
|
Release 0.13 relays podcast synchronization operations from other Furumi
|
|
|
|
|
players. Release 0.12 cannot read them: device synchronization would fail for
|
|
|
|
|
every device that has not received them yet. Before you start a 0.12 release
|
|
|
|
|
on a database that 0.13 used, stop the server and remove those operations:
|
|
|
|
|
|
|
|
|
|
```sql
|
|
|
|
|
DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%';
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Devices that support podcasts keep their own podcast state. The relay table
|
|
|
|
|
`furumusic__fed_podcast_relay` and the typed queue column can stay: 0.12
|
|
|
|
|
ignores them, and after the next upgrade 0.13 returns the relayed podcast state
|
|
|
|
|
in its snapshots again and uses the typed queue only while it matches the
|
|
|
|
|
queue, current track and position that 0.12 saved.
|
|
|
|
|
|
2026-11-18 15:17:50 +00:00
|
|
|
## Admin statistics
|
|
|
|
|
|
|
|
|
|
The only admin interface is `/admin/v2`, also reachable from `/admin/`.
|
|
|
|
|
**Statistics** shows listening totals, a timeline, artist/track/release rankings,
|
|
|
|
|
and paginated history. Select an artist or track to see its listeners, then a
|
|
|
|
|
listener to see their history within the same filters. The **Users** list links
|
|
|
|
|
to each user's full statistics.
|
|
|
|
|
|
|
|
|
|
Periods use UTC. Counts come from the synchronized `listen_event` history: a
|
|
|
|
|
natural finish, half of a track, or four minutes qualifies as a play. Interrupted
|
|
|
|
|
sessions under five seconds are not retained. Short retained sessions contribute
|
|
|
|
|
to listened time but not play counts. The source filter separates this instance
|
|
|
|
|
from synchronized devices. Artist rankings use recorded artist names, including
|
|
|
|
|
featured credits; the same artist is counted once per event. Existing history
|
|
|
|
|
remains available when its local audio file is deleted. Library and service
|
|
|
|
|
cards show current instance totals, independently of the listening filters.
|
|
|
|
|
|
|
|
|
|
Migration `m_0051_add_listen_statistics_indexes` adds time and content indexes.
|
|
|
|
|
The old admin pages and `/admin/debug` are removed; first-run setup remains at
|
|
|
|
|
`/admin/setup`.
|
|
|
|
|
|
|
|
|
|
## Metadata Repair
|
|
|
|
|
|
|
|
|
|
Admin → Library Tools provides a chat for editing the selected library resources.
|
|
|
|
|
Use **Show related**, then **Deselect all** to choose only the resources needed
|
|
|
|
|
for the task. Selecting a release includes its tracks; individual tracks can
|
|
|
|
|
then be unchecked to exclude them. Unselected artists remain read-only context
|
|
|
|
|
and their IDs can still be used in credits. Releases show their years; tracks
|
|
|
|
|
show their source release.
|
|
|
|
|
|
|
|
|
|
The assistant sees the complete selected scope and replaces the proposed plan
|
|
|
|
|
after every clarification. Expand **Proposed changes** in the chat to review or
|
|
|
|
|
edit it before applying. Plans support moving tracks, creating releases, merging
|
|
|
|
|
releases, and deleting artists, releases, or tracks. Release deletion requires
|
|
|
|
|
explicit moves or deletion of all its tracks. Artist deletion detaches credits
|
|
|
|
|
and requires all credited releases and tracks to be included.
|
|
|
|
|
|
|
|
|
|
Applied plans are transactional and can be undone from History. Metadata Repair
|
|
|
|
|
retains audio and artwork files for Undo. Undo refuses to overwrite subsequent
|
|
|
|
|
metadata, playback, or federation changes.
|
|
|
|
|
|
|
|
|
|
## Last.fm popularity updates
|
|
|
|
|
|
|
|
|
|
The `lastfm_popularity` job defaults to **light** mode: it requests popularity
|
|
|
|
|
only for tracks without a completed lookup or with a changed title or primary
|
|
|
|
|
artist. Both matches (including zero counts) and explicit Last.fm “Track not
|
|
|
|
|
found” results are skipped on subsequent light runs. HTTP errors, timeouts,
|
|
|
|
|
invalid responses, and other API errors remain eligible for retry. A failed
|
|
|
|
|
full refresh also makes that track eligible for the next light run.
|
|
|
|
|
|
|
|
|
|
Choose **Full: refresh all visible tracks** in the task's admin parameters to
|
|
|
|
|
refresh existing statistics and retry previous misses. The options endpoint
|
|
|
|
|
`POST /admin/v2/api/jobs/lastfm_popularity/run-options` accepts
|
|
|
|
|
`{"refresh_existing": true}`; an empty object, scheduled runs, and the ordinary
|
|
|
|
|
run endpoint use light mode. Neither mode limits the number of tracks processed.
|
|
|
|
|
An authoritative miss clears current statistics while preserving their history.
|
|
|
|
|
The migration preserves existing popularity; legacy misses need one more lookup
|
|
|
|
|
because older versions did not persist them.
|