forked from Furumi/furumi-web
Release 0.12 fails a whole sync batch on a podcast operation kind, so rolling back is only safe after the relayed podcast operations are removed: document the step in docs/administration.md and run it in the m_0055 backwards operation. The typed queue now records the current track id and queue position written with it, next to the legacy ids. A 0.12 release that only moved to another track in the same queue no longer leaves a stale typed position that the next upgrade would restore. Jam placeholders are never stored in a user's own typed queue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
157 lines
8.4 KiB
Markdown
157 lines
8.4 KiB
Markdown
# 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.
|
|
|
|
Queues synchronized from other Furumi players can contain podcast episodes. The
|
|
web player keeps them in the queue, in order and with their position, and shows
|
|
them as **Podcast · not playable in the web player yet**; local playback skips
|
|
them. 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.
|
|
|
|
### 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.
|
|
|
|
## 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.
|