Files
furumi-web/docs/administration.md
T
sanapachandClaude Opus 5.5 767134d1dd Keep replica room for the cards a rebalance publishes
Replicas count unexpired tombstones toward the 256 records per
publisher and refuse new keys beyond it. A round now admits at most as
many podcasts that need a new key as that room allows, so a fair-share
rebalance never displaces cards for newcomers the replicas would refuse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:12:52 +02:00

22 KiB

Using and administering Furumusic

Project overview · Installation · Development and tests

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 plays them (see 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. Reloading the page, or pressing Play after a pause while another player went on with the episode, continues from the newest saved position. Previous on an episode goes back 15 seconds instead of to the start. Marking the episode that is playing played or unplayed pauses it.
  • 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. Only podcasts you share explicitly are published (see below). 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.

Sharing a podcast in the federation

Share in the federation on a podcast page publishes a public card of the podcast so that members of the federation network outside your own devices can find it and subscribe. The card holds only the podcast's public metadata: title, author, description, artwork and site links, the feed URL, the number of episodes and the newest publication date. It never contains your progress, history, listening counts, device names or your account. Stop sharing or Unsubscribe revokes it; your progress is kept.

  • Sharing is your decision and is synchronized with your other Furumi players, like the subscription. A podcast shared on another player is shared here too, and turning it off anywhere turns it off everywhere. A new subscription, including subscribing again, is always private.
  • If the feed URL looks like it may contain private data (an access token or key in the address, a host of personal subscriber feeds, a long random part), the web player shows a confirmation dialog with the exact address before publishing it. Such feeds are often personal: publishing one can let others use your access. The confirmation belongs to this server and to this one decision; it is asked again when you share again, when the feed moves to another address, and when sharing was turned on on another player.
  • The server publishes the card with its federation identity (the same node key that publishes its music library), not with an identity of your account. When several accounts of this server share the same podcast, the server publishes one card for it, built from one of these accounts' copies of the feed (preferably one the server downloaded itself, and the same account as long as it keeps sharing, so another account sharing the podcast later does not replace the card's text), and keeps it while any of them still shares it. Other members see that this server shares the podcast, not who. Podcasts shared by a deactivated account are no longer published (within five minutes).
  • The podcast page says what this server does with the card: published, publishing, waiting for your confirmation, held back by the server's limit, or not possible because federation is off or public discovery is unavailable. It shows only this server's publication: a Furumi player such as the terminal player publishes its own card with its own identity when you share there, so the card may be public through that player while this server still waits for your confirmation. The podcast list marks a podcast with Sharing on when your decision is to share it.
  • Publishing needs federation to be enabled on the server (Settings → Federation). Without it, the share decision is kept and the card is published once federation runs.
  • A server publishes at most 192 podcasts, shared fairly between the accounts that share podcasts: every account gets its turn in rotation, so an account whose shared podcasts fit in its part of the limit (192 divided by the number of sharing accounts) never loses a published card because other accounts share many podcasts. When the limit is reached, only podcasts of accounts beyond their part wait (newest shares first; cards already published are kept before new ones), and the podcast page says that the card is held back. Members' caches keep at most 256 records per server, including revocations of the last 24 hours, so a new card also waits while recent revocations fill that room, and no published card is given up for a card the federation would not store.
  • A podcast whose stored data cannot be read (for example after a damaged import) is treated as not shared, and its card is revoked; the other podcasts are still published and revoked as usual.
  • Revoking is eventually consistent: the server publishes a signed revocation at once, but a federation peer that missed it may show the old card for up to 12 hours. Subscriptions other members made from the card stay theirs.

The server joins the separate podcast-discovery overlay (furumi-fd/podcast-dht/1) of the federation network and keeps its routing contacts and the cards it holds for others in podcast-dht.sqlite3 in the federation data directory (a cache that can be deleted while the server is stopped). If the overlay cannot start, the server log says "public podcast discovery disabled" and everything else keeps working. The admin federation status (/admin/v2/api/federation) reports podcast_discovery and podcast_discovery_peers.

Finding podcasts in the federation

The search box searches the federation too. Podcasts that members shared appear under Federation → Podcasts, marked Podcast and kept apart from music; podcasts you already follow are marked Already subscribed (also when you follow the same feed under an older address it moved from). If you follow the feed only under the newer address of a card's moved feed, the result list cannot tell yet; opening the card reads the feed, sees the move and shows Already subscribed with Open, and neither Subscribe nor Add RSS with the old address creates a second subscription.

  • Opening a card shows its title, author, description, artwork and the feed URL, then loads the seasons and episodes from the feed itself through the server: the newest 50 episodes, and the newest 50 of one season when you pick its chip (pick it again for all seasons). Nothing is stored until you subscribe. Closing the card, or picking another season, cancels a loading preview.
  • Subscribe adds your own private subscription: the server downloads the feed from the card's address, as for Add RSS, and you can then play, share or unsubscribe it like any other. The member who published the card is never contacted and does not need to stay online; their card is only a pointer to the public feed. The subscription keeps the podcast's identity, so your other Furumi players recognise it, and nobody else sees it.
  • Card texts and links come from other members and may be wrong. The player shows them as plain text, opens only web links, and loads artwork directly from its host only over HTTPS (like the artwork of subscribed podcasts). Only the original feed address of a card is used: an address a member claims the feed moved to is ignored unless the feed itself redirects there.
  • Search results show only cards; no member's subscriptions, progress or account are ever visible. A card disappears from search results within 12 hours after it is revoked.
  • Podcast search needs federation on this server. When public discovery is off or unavailable, the search shows music only. When the podcast search fails or times out, the music results are still shown, with a note that the podcast search did not answer.

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. Each run checks at most 200 feeds (2400 an hour), taking accounts in turns: first the most overdue feed of every account, then the second, and so on. An account with many or slow feeds therefore does not delay the others, but can use the capacity nobody else needs.

An account can add up to 1000 subscriptions and, from the browser, up to 10 000 episodes outside its feeds (handed-off queue items; episodes synced from its own devices are not limited); beyond that the request is refused with HTTP 422. It can have two feed downloads ("add RSS", Refresh) and four proxied audio streams in progress at once (16 and 64 for the whole server); beyond that the request is refused with HTTP 429.

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. "Address not allowed" is only said for what the URL itself shows (scheme, credentials, port, an IP address). A host name that resolves to a blocked address gets the same answer as a name that does not resolve or a server that does not answer ("could not connect"), so users cannot find out which names exist in the server's internal DNS.

Episode audio is streamed by the browser directly from the publisher. Some 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 sent by the account's own clients (its paired devices, or its browser when it plays a handed-off episode the catalog does not know yet). A signed-in user controls both (anyone can subscribe to a feed they host), so any signed-in user can make the server fetch audio from any public URL, as with feed refreshes.
  • What limits that: the same public-address and port checks as for feeds apply to every connection and redirect, and only audio is passed through. The publisher's Content-Type must be audio; for a generic binary type (application/octet-stream or none), the URL must have an audio file extension or the file must start like an audio file (MP3, AAC, Ogg, FLAC, WAV, M4A). The enclosure type written in the feed is never trusted. No HTML, no video. Requests carry a single byte range, are limited to 1 GiB and 4 hours each and to four streams per account (64 for the server), 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

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:

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.