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
|
2026-11-19 22:04:40 +02:00
|
|
|
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.
|
2026-11-19 21:14:54 +02:00
|
|
|
- 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
|
2026-11-19 23:12:21 +02:00
|
|
|
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'
|
2026-11-20 00:31:41 +02:00
|
|
|
copies of the feed, and keeps it while any of them still shares it. The
|
|
|
|
|
account whose copy the published card shows keeps providing it while it
|
|
|
|
|
shares (also after a server restart, recognised by the card's text), so
|
|
|
|
|
another account sharing the podcast later does not replace the card's
|
|
|
|
|
text; a new card preferably uses a copy the server downloaded itself
|
|
|
|
|
from the podcast's original address. If that account's copy changes
|
|
|
|
|
while the server restarts, the card may be rebuilt from another sharing
|
|
|
|
|
account's copy. Other members see that this server shares the
|
2026-11-20 00:07:22 +02:00
|
|
|
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.
|
2026-11-19 23:12:21 +02:00
|
|
|
- Publishing needs federation to be enabled on the server (Settings →
|
|
|
|
|
Federation). Without it, the share decision is kept and the card is
|
2026-11-20 00:07:22 +02:00
|
|
|
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
|
2026-11-20 00:30:51 +02:00
|
|
|
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.
|
2026-11-20 00:07:22 +02:00
|
|
|
- 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.
|
2026-11-19 23:12:21 +02:00
|
|
|
- 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`.
|
2026-11-19 16:58:32 +02:00
|
|
|
|
2026-11-19 23:32:20 +02:00
|
|
|
### 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**
|
2026-11-20 00:07:22 +02:00
|
|
|
(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
|
2026-11-20 00:32:23 +02:00
|
|
|
second subscription. A podcast you follow is changed only by its own
|
|
|
|
|
address: when a feed found under another address only claims to have
|
|
|
|
|
moved to yours (or is an old copy of it), nothing of that feed is written
|
|
|
|
|
into your podcast; if you had unsubscribed, it is subscribed again with
|
|
|
|
|
its own data and refreshed from its own address.
|
2026-11-19 23:32:20 +02:00
|
|
|
|
|
|
|
|
- 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
|
2026-11-20 00:07:22 +02:00
|
|
|
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.
|
2026-11-19 23:32:20 +02:00
|
|
|
- **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
|
2026-11-20 00:07:22 +02:00
|
|
|
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.
|
2026-11-19 23:32:20 +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
|
2026-11-19 21:55:22 +02:00
|
|
|
episodes. Accounts subscribed to the same feed share one request. Each run
|
2026-11-19 22:41:02 +02:00
|
|
|
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
|
2026-11-19 22:42:40 +02:00
|
|
|
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.
|
2026-11-19 20:24:30 +02:00
|
|
|
|
|
|
|
|
The server therefore makes outgoing HTTP(S) requests to podcast publishers.
|
2026-11-19 21:51:45 +02:00
|
|
|
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.
|
2026-11-19 22:39:22 +02:00
|
|
|
"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.
|
2026-11-19 20:24:30 +02:00
|
|
|
|
|
|
|
|
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
|
2026-11-19 21:57:45 +02:00
|
|
|
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.
|
2026-11-19 21:14:54 +02:00
|
|
|
- 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.
|