Files
furumi-web/docs/administration.md
T

244 lines
13 KiB
Markdown
Raw Normal View History

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.
### 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 on the web ports 80, 443, 8080 and 8443:
feed or audio URLs that point to loopback, private, link-local, CGNAT or cloud
metadata addresses, directly, through DNS or through a redirect, or to any
other port, are refused. System proxy settings are not used for these
requests. Users only see the kind of failure (address not allowed, could not
connect, HTTP status, not a feed); the details, without the URL, are in the
server log and, for scheduled refreshes, in the job log with the podcast id.
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.
### 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.
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.
### 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.