From a0c0da8a8283bc82c49da417c4f95188ab4baac5 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:39:44 +0100
Subject: [PATCH 1/4] refactor(media): move media, scanner and watcher into
 their own directories

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/{media.rs => media/mod.rs}     | 0
 src/{scanner.rs => scanner/mod.rs} | 0
 src/{watcher.rs => watcher/mod.rs} | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename src/{media.rs => media/mod.rs} (100%)
 rename src/{scanner.rs => scanner/mod.rs} (100%)
 rename src/{watcher.rs => watcher/mod.rs} (100%)

diff --git a/src/media.rs b/src/media/mod.rs
similarity index 100%
rename from src/media.rs
rename to src/media/mod.rs
diff --git a/src/scanner.rs b/src/scanner/mod.rs
similarity index 100%
rename from src/scanner.rs
rename to src/scanner/mod.rs
diff --git a/src/watcher.rs b/src/watcher/mod.rs
similarity index 100%
rename from src/watcher.rs
rename to src/watcher/mod.rs

From 52ee60d4f8ead027b02936dac8a65bab8cfedb5e Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:56:06 +0100
Subject: [PATCH 2/4] refactor(media): split the media service into transcode,
 stream, artwork and canvas

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/media/artwork.rs   |  153 +++
 src/media/canvas.rs    |  329 ++++++
 src/media/mod.rs       | 2169 ++--------------------------------------
 src/media/stream.rs    |  701 +++++++++++++
 src/media/tests.rs     |  458 +++++++++
 src/media/transcode.rs |  493 +++++++++
 6 files changed, 2204 insertions(+), 2099 deletions(-)
 create mode 100644 src/media/artwork.rs
 create mode 100644 src/media/canvas.rs
 create mode 100644 src/media/stream.rs
 create mode 100644 src/media/tests.rs
 create mode 100644 src/media/transcode.rs

diff --git a/src/media/artwork.rs b/src/media/artwork.rs
new file mode 100644
index 00000000..39093225
--- /dev/null
+++ b/src/media/artwork.rs
@@ -0,0 +1,153 @@
+//! Covers: where a stored artwork is read from, and the route that serves it.
+
+use axum::{
+    extract::{Path as AxumPath, State},
+    http::{header, HeaderMap, StatusCode},
+    response::{IntoResponse, Response},
+};
+
+use super::{bearer_principal, MediaError};
+use crate::AppState;
+
+/// Artwork addressed by its own hash: the bytes behind the URL cannot change,
+/// so a client never needs to ask again.
+const ARTWORK_CANONICAL_CACHE: &str = "private, max-age=31536000, immutable";
+/// Artwork addressed by a track, album or artist: the URL resolves whichever
+/// cover that entity carries *now*, and a rescan can move it.
+const ARTWORK_ALIAS_CACHE: &str = "private, no-cache";
+
+/// Content type for a stored artwork, or `None` for a format we never wrote.
+///
+/// Shared by the native route and the Subsonic facade: two copies would drift
+/// on the day a format is added, and the client that got
+/// `application/octet-stream` would simply show no cover.
+pub fn artwork_mime(format: &str) -> Option<&'static str> {
+    match format {
+        "jpg" | "jpeg" => Some("image/jpeg"),
+        "png" => Some("image/png"),
+        "webp" => Some("image/webp"),
+        _ => None,
+    }
+}
+
+/// Reads an artwork file from the store.
+///
+/// `hash` and `format` come from the database, never from the request, so the
+/// joined path cannot escape `artwork_dir` — the caller resolves the request's
+/// id through `artwork_for_user`, which also enforces tenancy.
+pub async fn read_artwork(
+    artwork_dir: &std::path::Path,
+    hash: &str,
+    format: &str,
+) -> Option<(&'static str, Vec<u8>)> {
+    let mime = artwork_mime(format)?;
+    let bytes = tokio::fs::read(artwork_dir.join(format!("{hash}.{format}")))
+        .await
+        .ok()?;
+    Some((mime, bytes))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/artwork/{artwork_id}",
+    tag = "media",
+    params((
+        "artwork_id" = String,
+        Path,
+        description = "An `artwork_hash` from any catalogue payload, or the id of a track, \
+                       album or artist that carries one."
+    )),
+    responses(
+        (status = 200, description = "Cover image", content_type = "image/jpeg"),
+        (status = 401),
+        (status = 404)
+    )
+)]
+/// Serves a cover behind the same bearer as the rest of the native API.
+///
+/// Catalogue payloads carry `artwork_hash` but nothing resolved it: only the
+/// Subsonic facade served images, behind a separate credential. A native client
+/// therefore showed a remote catalogue with no covers at all.
+///
+/// Access is re-checked per request through `artwork_for_user`, so a hash
+/// guessed from another tenant's library answers 404 like anything else.
+pub async fn artwork(
+    State(state): State<AppState>,
+    AxumPath(artwork_id): AxumPath<String>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    let (hash, format) = state
+        .services
+        .artwork_for_user(user.id, &artwork_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "artwork lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+
+    // How the URL was addressed decides what a client may do with the answer,
+    // and the two forms are not the same resource.
+    //
+    // Addressed by hash, the hash *is* the content: this URL can never answer
+    // differently, so a client should stop revalidating it entirely. Addressed
+    // by a track, album or artist id, the lookup above resolved that entity's
+    // *current* cover — and a rescan that finds new embedded art moves it. The
+    // alias must stay revalidatable or a replaced cover would be frozen in
+    // every client's cache for a year.
+    //
+    // `private` on both, and neither becomes `public`: the route is
+    // authenticated and tenant-checked, and two accounts whose libraries hold
+    // the same cover share its hash, so a shared cache keyed on the URL would
+    // hand one tenant's artwork to another with no credential in sight. A
+    // private cache is the client's own and loses nothing by the restriction.
+    let cache_control = if artwork_id == hash {
+        ARTWORK_CANONICAL_CACHE
+    } else {
+        ARTWORK_ALIAS_CACHE
+    };
+    // The validator is the hash either way, which is what makes revalidating an
+    // alias a 304 rather than a second full transfer of the same bytes.
+    let etag = format!("\"{hash}\"");
+    if if_none_match_hits(&headers, &etag) {
+        return Ok((
+            StatusCode::NOT_MODIFIED,
+            [
+                (header::CACHE_CONTROL, cache_control.to_owned()),
+                (header::ETAG, etag),
+            ],
+        )
+            .into_response());
+    }
+
+    let (mime, bytes) = read_artwork(&state.artwork_dir, &hash, &format)
+        .await
+        .ok_or(MediaError::NotFound)?;
+    Ok((
+        StatusCode::OK,
+        [
+            (header::CONTENT_TYPE, mime.to_owned()),
+            (header::CACHE_CONTROL, cache_control.to_owned()),
+            (header::ETAG, etag),
+        ],
+        bytes,
+    )
+        .into_response())
+}
+
+/// Whether the request already holds this exact entity.
+///
+/// `*` matches anything the client has, which for a single-representation
+/// resource is this one.
+pub(super) fn if_none_match_hits(headers: &HeaderMap, etag: &str) -> bool {
+    headers
+        .get(header::IF_NONE_MATCH)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(|value| {
+            value
+                .split(',')
+                .map(str::trim)
+                .any(|candidate| candidate == etag || candidate == "*")
+        })
+}
diff --git a/src/media/canvas.rs b/src/media/canvas.rs
new file mode 100644
index 00000000..64358ebe
--- /dev/null
+++ b/src/media/canvas.rs
@@ -0,0 +1,329 @@
+//! Canvas loops: the routes that serve, place, remove and ticket them.
+
+use axum::{
+    extract::{Path as AxumPath, State},
+    http::{header, HeaderMap, HeaderValue, StatusCode},
+    response::{IntoResponse, Response},
+};
+use bytes::Bytes;
+use uuid::Uuid;
+
+use super::artwork::if_none_match_hits;
+use super::stream::{serve_file, StreamTicketResponse};
+use super::{bearer_principal, MediaError};
+use crate::AppState;
+
+/// A canvas addressed by its hash. The bytes behind a hash never change, so
+/// this URL can never answer differently and a client should stop asking.
+const CANVAS_CANONICAL_CACHE: &str = "private, max-age=31536000, immutable";
+/// A canvas addressed by a track: the link is what it resolves, and a member
+/// can replace it at any moment. Stated apart from the artwork constants that
+/// happen to hold the same policy — a canvas is not a cover, and one changing
+/// must not drag the other.
+const CANVAS_ALIAS_CACHE: &str = "private, no-cache";
+
+fn mime_for_canvas(format: &str) -> &'static str {
+    match format {
+        "webm" => "video/webm",
+        // The store only ever holds what the probe accepted, and that is one of
+        // exactly two containers.
+        _ => "video/mp4",
+    }
+}
+
+/// Serves the blob behind a canvas, once something has authorised it.
+///
+/// Shared by the three ways in — the hash, the track alias, and a ticket — so
+/// the caching rule and the 304 live in one place and cannot drift apart per
+/// route. Which `cache_control` applies is the caller's decision, because only
+/// the caller knows how the URL was addressed.
+async fn serve_canvas(
+    state: &AppState,
+    blob: &crate::services::CanvasBlob,
+    headers: &HeaderMap,
+    cache_control: &'static str,
+) -> Result<Response, MediaError> {
+    // The validator is the hash however the URL was addressed, which is what
+    // makes revalidating an alias a 304 rather than a second transfer of bytes
+    // the client already holds.
+    let etag = format!("\"{}\"", blob.hash);
+    if if_none_match_hits(headers, &etag) {
+        return Ok((
+            StatusCode::NOT_MODIFIED,
+            [
+                (header::CACHE_CONTROL, cache_control.to_owned()),
+                (header::ETAG, etag),
+            ],
+        )
+            .into_response());
+    }
+    let range = headers
+        .get(header::RANGE)
+        .and_then(|value| value.to_str().ok());
+    let path = state.services.canvas_file(blob);
+    let mut response = serve_file(&path, range, mime_for_canvas(&blob.format)).await?;
+    let served = response.headers_mut();
+    served.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_str(cache_control).map_err(|_| MediaError::Internal)?,
+    );
+    served.insert(
+        header::ETAG,
+        HeaderValue::from_str(&etag).map_err(|_| MediaError::Internal)?,
+    );
+    Ok(response)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/canvas/{canvas_hash}",
+    tag = "media",
+    params(("canvas_hash" = String, Path)),
+    responses(
+        (status = 200, description = "The loop, immutable under this URL"),
+        (status = 206),
+        (status = 304),
+        (status = 401),
+        (status = 404)
+    )
+)]
+pub async fn canvas_by_hash(
+    State(state): State<AppState>,
+    AxumPath(canvas_hash): AxumPath<String>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    // Knowing a hash establishes nothing. Two accounts that are strangers to
+    // each other can hold the same loop, so this resolves through membership
+    // the way `artwork_for_user` does, and a hash nobody reachable references
+    // answers exactly like one that does not exist.
+    let blob = state
+        .services
+        .canvas_for_user(user.id, &canvas_hash)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "canvas lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    serve_canvas(&state, &blob, &headers, CANVAS_CANONICAL_CACHE).await
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/tracks/{track_id}/canvas",
+    tag = "media",
+    params(("track_id" = Uuid, Path)),
+    responses(
+        (status = 200, description = "The loop this track carries now"),
+        (status = 206),
+        (status = 304),
+        (status = 401),
+        (status = 404)
+    )
+)]
+pub async fn canvas_for_track(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    // A track id is guessed no worse than a hash, so the alias is no more an
+    // authorisation than the fingerprint is: membership in the track's library,
+    // re-read on this request. A track that does not exist, one belonging to
+    // somebody else, and one with no canvas all answer 404.
+    let blob = state
+        .services
+        .canvas_for_track(user.id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "canvas alias lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    serve_canvas(&state, &blob, &headers, CANVAS_ALIAS_CACHE).await
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v2/tracks/{track_id}/canvas",
+    tag = "media",
+    params(("track_id" = Uuid, Path)),
+    request_body(content = Vec<u8>, description = "An mp4 or webm loop"),
+    responses(
+        (status = 200, body = CanvasResponse),
+        (status = 401),
+        (status = 404),
+        (status = 409, description = "The library's canvas quota is full"),
+        (status = 413),
+        (status = 422, description = "Not a short loop this server will take")
+    )
+)]
+pub async fn put_canvas(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Result<axum::Json<CanvasResponse>, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    let device = crate::api::origin_device(&state, &headers, user.id)
+        .await
+        .map_err(|_| MediaError::InvalidRequest)?;
+    let blob = state
+        .services
+        .place_canvas(user.id, track_id, &body, device)
+        .await
+        .map_err(canvas_error)?;
+    Ok(axum::Json(CanvasResponse {
+        url: format!("/api/v2/canvas/{}", blob.hash),
+        hash: blob.hash,
+        format: blob.format,
+        byte_size: blob.byte_size,
+    }))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v2/tracks/{track_id}/canvas",
+    tag = "media",
+    params(("track_id" = Uuid, Path)),
+    responses((status = 204), (status = 401), (status = 404))
+)]
+pub async fn delete_canvas(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    headers: HeaderMap,
+) -> Result<StatusCode, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    let device = crate::api::origin_device(&state, &headers, user.id)
+        .await
+        .map_err(|_| MediaError::InvalidRequest)?;
+    state
+        .services
+        .remove_canvas(user.id, track_id, device)
+        .await
+        .map_err(canvas_error)?;
+    Ok(StatusCode::NO_CONTENT)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v2/tracks/{track_id}/canvas-ticket",
+    tag = "media",
+    params(("track_id" = Uuid, Path)),
+    responses((status = 200, body = StreamTicketResponse), (status = 401), (status = 404))
+)]
+pub async fn create_canvas_ticket(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    headers: HeaderMap,
+) -> Result<axum::Json<StreamTicketResponse>, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    // Minting proves access now; redeeming re-proves it. A member removed
+    // between the two loses the canvas immediately rather than at expiry.
+    state
+        .services
+        .canvas_for_track(user.id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "canvas ticket authorization lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    let expires_at = i64::try_from(state.stream_ticket_ttl.as_millis())
+        .ok()
+        .and_then(|ttl| crate::authentication::now_ms().checked_add(ttl))
+        .ok_or_else(|| {
+            tracing::error!("stream ticket TTL does not fit in an epoch timestamp");
+            MediaError::Internal
+        })?;
+    let ticket = crate::stream_ticket::mint(
+        &state.secret_box,
+        crate::stream_ticket::TicketKind::Canvas,
+        user.id,
+        track_id,
+        expires_at,
+    )
+    .map_err(|error| {
+        tracing::error!(error = %error, "canvas ticket minting failed");
+        MediaError::Internal
+    })?;
+    // Relative, for the same reason the audio ticket is: it is consumed by the
+    // client that just authenticated, not sent out of the application.
+    Ok(axum::Json(StreamTicketResponse {
+        url: format!("/api/v2/canvas-stream/{ticket}"),
+        expires_at,
+    }))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/canvas-stream/{ticket}",
+    tag = "media",
+    params(("ticket" = String, Path)),
+    responses(
+        (status = 200, description = "What <video src> plays"),
+        (status = 206),
+        (status = 304),
+        (status = 404)
+    )
+)]
+pub async fn canvas_with_ticket(
+    State(state): State<AppState>,
+    AxumPath(ticket): AxumPath<String>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    // This route serves a canvas, and it says so. Without the assertion an
+    // audio ticket would open a canvas and the reverse — which is the whole
+    // reason the kind is inside the sealed payload.
+    let (_, user_id, track_id) =
+        crate::stream_ticket::verify(&state.secret_box, &ticket, crate::authentication::now_ms())
+            .filter(|(kind, ..)| *kind == crate::stream_ticket::TicketKind::Canvas)
+            .ok_or(MediaError::NotFound)?;
+    // Re-checked on every redemption, so a ticket cannot outlive the membership
+    // that justified it.
+    let blob = state
+        .services
+        .canvas_for_track(user_id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "ticket canvas authorization lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    // Addressed by a ticket that names a track, so this resolves the link of
+    // the moment exactly as the alias does, and caches like it.
+    serve_canvas(&state, &blob, &headers, CANVAS_ALIAS_CACHE).await
+}
+
+/// Maps a canvas refusal onto the status that says it.
+///
+/// `Forbidden` becomes 404 like everywhere else in this API: a caller who may
+/// not place a canvas learns nothing about whether the library would have taken
+/// one. `Invalid` is 422 rather than 400 — the request was well formed, and
+/// what it carried is not a short loop this server will keep.
+fn canvas_error(error: crate::services::ServiceError) -> MediaError {
+    match error {
+        crate::services::ServiceError::NotFound | crate::services::ServiceError::Forbidden => {
+            MediaError::NotFound
+        }
+        crate::services::ServiceError::Invalid => MediaError::InvalidRequest,
+        crate::services::ServiceError::Conflict => MediaError::Conflict,
+        error => {
+            tracing::error!(error = %error, "canvas mutation failed");
+            MediaError::Internal
+        }
+    }
+}
+
+/// What a placed canvas answers with.
+#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
+pub struct CanvasResponse {
+    /// Where the bytes are, addressed by content. Immutable under this URL.
+    pub url: String,
+    pub hash: String,
+    /// `mp4` or `webm`, decided by reading the bytes rather than by trusting
+    /// what the request called them.
+    pub format: String,
+    pub byte_size: i64,
+}
diff --git a/src/media/mod.rs b/src/media/mod.rs
index c66ef89f..db6ce7f5 100644
--- a/src/media/mod.rs
+++ b/src/media/mod.rs
@@ -1,10 +1,27 @@
 //! Tenant-authorized native playback, FFmpeg transcoding and content cache.
 
+mod artwork;
+mod canvas;
+mod stream;
+#[cfg(test)]
+pub(crate) mod tests;
+mod transcode;
+
+pub use artwork::{__path_artwork, artwork, artwork_mime, read_artwork};
+pub use canvas::{
+    __path_canvas_by_hash, __path_canvas_for_track, __path_canvas_with_ticket,
+    __path_create_canvas_ticket, __path_delete_canvas, __path_put_canvas, canvas_by_hash,
+    canvas_for_track, canvas_with_ticket, create_canvas_ticket, delete_canvas, put_canvas,
+    CanvasResponse,
+};
+pub use stream::{
+    __path_create_stream_ticket, __path_stream_track, __path_stream_with_ticket,
+    create_stream_ticket, stream_track, stream_with_ticket, DownloadQuery, StreamTicketResponse,
+};
+pub(crate) use stream::{attachment, secure_track_path};
+
 use std::{
-    collections::HashMap,
-    ffi::OsStr,
-    io,
-    path::{Component, Path, PathBuf},
+    path::{Path, PathBuf},
     process::Stdio,
     sync::{
         atomic::{AtomicUsize, Ordering},
@@ -15,45 +32,25 @@ use std::{
 
 use axum::handler::Handler;
 use axum::{
-    body::Body,
-    extract::{Path as AxumPath, Query, State},
     http::{header, HeaderMap, HeaderValue, StatusCode},
     response::{IntoResponse, Response},
     routing::get,
     Router,
 };
-use bytes::Bytes;
 use dashmap::{DashMap, DashSet};
 use serde::Deserialize;
 use tokio::{
-    io::{AsyncReadExt, AsyncSeekExt, AsyncWriteExt},
     process::Command,
-    sync::{mpsc, Mutex, Semaphore},
+    sync::{Mutex, Semaphore},
 };
-use tokio_stream::wrappers::ReceiverStream;
-use tokio_util::io::ReaderStream;
 use uuid::Uuid;
 
-use crate::{
-    catalog::StreamTrack,
-    config::Config,
-    replay_gain::{Gain, ReplayGainMode},
-    AppState,
-};
+use crate::{config::Config, replay_gain::ReplayGainMode, AppState};
 
-const STREAM_CHUNK_SIZE: usize = 64 * 1024;
-const MAX_RANGE_BYTES: u64 = 8 * 1024 * 1024;
-const TRANSCODE_PROFILE_VERSION: &str = "waveflow-ffmpeg-v1";
 /// Audio is tenant-scoped and reached through a bearer token or a stream
 /// ticket, so the same URL means different things to different callers. No
 /// shared cache may retain a copy.
 const MEDIA_CACHE_CONTROL: &str = "private, no-store";
-/// Artwork addressed by its own hash: the bytes behind the URL cannot change,
-/// so a client never needs to ask again.
-const ARTWORK_CANONICAL_CACHE: &str = "private, max-age=31536000, immutable";
-/// Artwork addressed by a track, album or artist: the URL resolves whichever
-/// cover that entity carries *now*, and a rescan can move it.
-const ARTWORK_ALIAS_CACHE: &str = "private, no-cache";
 
 /// The protocols FFmpeg and ffprobe may open on behalf of an input
 /// (RFC-023 decision 2): local files, and nothing else.
@@ -157,22 +154,6 @@ pub struct StreamQuery {
     pub offset_ms: u64,
 }
 
-/// `?download=1` on a stream ticket (RFC-012 decision 5).
-///
-/// Its own extractor rather than a field on [`StreamQuery`], which the
-/// Subsonic façade and the bearer route share and which has no business
-/// learning a header choice only the ticket route makes.
-#[derive(Debug, Default, Deserialize)]
-pub struct DownloadQuery {
-    download: Option<String>,
-}
-
-impl DownloadQuery {
-    fn asked(&self) -> bool {
-        matches!(self.download.as_deref(), Some("1" | "true"))
-    }
-}
-
 #[derive(Debug)]
 pub enum MediaError {
     Unauthorized,
@@ -258,1266 +239,6 @@ impl MediaService {
     pub fn transcoding_available(&self) -> bool {
         self.inner.transcoding_available
     }
-
-    pub async fn serve(
-        &self,
-        user_id: Uuid,
-        track: StreamTrack,
-        query: StreamQuery,
-        range: Option<&str>,
-    ) -> Result<Response, MediaError> {
-        self.serve_with_replay_gain(user_id, track, query, range, ReplayGainMode::Off)
-            .await
-    }
-
-    /// [`Self::serve`], a transcode levelled by the track's ReplayGain under
-    /// `mode` (RFC-022, what was still open). The original is served as it is
-    /// whatever the mode says: the gain rides on an encode that happens anyway,
-    /// and never causes one. A gain is part of the cache key, so a levelled
-    /// encode is never handed to a request that did not ask for it; no gain —
-    /// the mode off, or a track with no tags — keeps the key it always had.
-    pub async fn serve_with_replay_gain(
-        &self,
-        user_id: Uuid,
-        track: StreamTrack,
-        query: StreamQuery,
-        range: Option<&str>,
-        mode: ReplayGainMode,
-    ) -> Result<Response, MediaError> {
-        let gain = crate::replay_gain::gain(track.replay_gain, mode);
-        if !track.available {
-            return Err(MediaError::NotFound);
-        }
-        let source = secure_track_path(
-            &track.library_root,
-            &track.relative_path,
-            &self.inner.link_roots,
-            &track.link_policy,
-        )
-        .await
-            .map_err(|error| {
-                tracing::warn!(track_id = %track.id, library_id = %track.library_id, error = %error, "media path rejected");
-                MediaError::NotFound
-            })?;
-
-        if query.format == OutputFormat::Raw {
-            if query.offset_ms != 0 || query.bitrate.is_some() {
-                return Err(MediaError::InvalidRequest);
-            }
-            return serve_file(&source, range, mime_for_path(&source)).await;
-        }
-
-        let bitrate = validate_bitrate(query.format, query.bitrate)?;
-        if query.offset_ms > track.duration_ms.max(0) as u64 {
-            return Err(MediaError::InvalidRequest);
-        }
-        let key = cache_key(&track.full_hash, query.format, bitrate, gain);
-        let cache_path = self
-            .inner
-            .cache_dir
-            .join(format!("{key}.{}", extension(query.format)));
-
-        if query.offset_ms == 0 && tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
-            self.inner
-                .cache_access
-                .insert(cache_path.clone(), SystemTime::now());
-            return serve_file(&cache_path, range, mime_for_format(query.format)).await;
-        }
-
-        // A byte range has no stable meaning until a transcode is complete, so
-        // seeking a live transcode goes through offset_ms instead. A range
-        // that starts at the first byte is not a seek though: it is how every
-        // player opens a resource. Refusing it made a client fail on the first
-        // play of a track and succeed on the second, once the cache existed —
-        // Feishin with `bytes=0-`, then Juliet with the `bytes=0-1` probe iOS
-        // sends before anything else.
-        if range.is_some_and(|value| !starts_at_the_first_byte(value)) {
-            return Err(MediaError::RangeNotSatisfiable(None));
-        }
-
-        if query.offset_ms > 0 {
-            let response = self
-                .stream_transcode(
-                    user_id,
-                    source.clone(),
-                    query.format,
-                    bitrate,
-                    gain,
-                    query.offset_ms,
-                    None,
-                )
-                .await?;
-            // After the live stream has its slots, never before: the listener
-            // waiting on this request comes first, and a fill that took the
-            // last slot would be the reason they were answered 429.
-            if !tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
-                self.fill_cache_behind_a_seek(
-                    source,
-                    query.format,
-                    bitrate,
-                    gain,
-                    key,
-                    cache_path,
-                    fill_deadline(track.duration_ms),
-                );
-            }
-            return Ok(response);
-        }
-
-        let lock = self
-            .inner
-            .cache_locks
-            .entry(key.clone())
-            .or_insert_with(|| Arc::new(Mutex::new(())))
-            .clone();
-        let guard = lock.lock_owned().await;
-        if tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
-            drop(guard);
-            self.inner
-                .cache_access
-                .insert(cache_path.clone(), SystemTime::now());
-            // Whoever held the lock finished the transcode, so the range that
-            // had no meaning a moment ago has one now, and the second caller
-            // gets the same partial answer it would have got from the cache.
-            return serve_file(&cache_path, range, mime_for_format(query.format)).await;
-        }
-
-        self.stream_transcode(
-            user_id,
-            source,
-            query.format,
-            bitrate,
-            gain,
-            0,
-            Some((cache_path, guard)),
-        )
-        .await
-    }
-
-    /// The FFmpeg invocation for a transcode, up to where its output goes.
-    ///
-    /// Shared by the live stream, which sends it to a pipe, and the cache fill
-    /// behind a seek, which sends it to a file. Two copies of these arguments
-    /// would drift apart the day one of them changed, and the cache would start
-    /// holding a different encode from the one its key names.
-    fn transcode_command(
-        &self,
-        source: &Path,
-        format: OutputFormat,
-        bitrate: u32,
-        gain: Option<Gain>,
-        offset_ms: u64,
-    ) -> Result<Command, MediaError> {
-        let mut command = Command::new(&self.inner.ffmpeg);
-        command.arg("-hide_banner").arg("-loglevel").arg("error");
-        if offset_ms > 0 {
-            command
-                .arg("-ss")
-                .arg(format!("{:.3}", offset_ms as f64 / 1000.0));
-        }
-        file_input(&mut command, source).args(["-vn", "-map_metadata", "-1"]);
-        if let Some(gain) = gain {
-            command.arg("-af").arg(gain.filter());
-        }
-        let bitrate_arg = format!("{bitrate}k");
-        match format {
-            OutputFormat::Mp3 => {
-                command.args(["-c:a", "libmp3lame", "-b:a", &bitrate_arg, "-f", "mp3"]);
-            }
-            OutputFormat::Opus => {
-                command.args([
-                    "-c:a",
-                    "libopus",
-                    "-b:a",
-                    &bitrate_arg,
-                    "-vbr",
-                    "on",
-                    "-f",
-                    "ogg",
-                ]);
-            }
-            OutputFormat::Aac => {
-                // FFmpeg's own encoder, which every build has: `libfdk_aac` is
-                // better at low rates and missing from most builds, since its
-                // licence is not GPL-compatible.
-                command.args(["-c:a", "aac", "-b:a", &bitrate_arg, "-f", "adts"]);
-            }
-            OutputFormat::Raw => return Err(MediaError::InvalidRequest),
-        }
-        Ok(command)
-    }
-
-    /// Transcodes the whole track into the cache, behind a seek into a live
-    /// transcode of it. Issue #185.
-    ///
-    /// Seeking a live transcode goes through `offset_ms`, and asking for it is
-    /// the very act that abandons the offset-0 stream: the only one allowed to
-    /// fill the cache, and one whose departure kills its encoder and deletes its
-    /// partial file. The stream replacing it is not the whole track and is not
-    /// cached. Without this, a track seeked on its first play stayed a live
-    /// transcode on every later play, without byte ranges, so the client seeked
-    /// through `offset_ms` again and abandoned the stream again.
-    ///
-    /// **Below anything a listener is waiting on.** It starts only when it can
-    /// take a global slot and still leave one free, so it never turns a live
-    /// request into a 429, and it never counts against the account's own limit,
-    /// which the seek itself is holding. Without that room it does nothing, and
-    /// the next seek asks again.
-    ///
-    /// **Outside the cache lock.** The play a seek abandons still holds that
-    /// lock for the moment it takes to notice its consumer is gone, and the seek
-    /// lands inside that moment: waiting for the lock or giving up on it would
-    /// both miss the one case this is for. A second writer of the same key costs
-    /// an encode and nothing worse — each writes its own staging file, and the
-    /// one that finds the cache already there discards its own.
-    ///
-    /// **Bounded by `deadline`.** A live stream ends when its listener leaves;
-    /// a fill has no listener, so without a deadline an encode that never
-    /// finished would hold its slot and its key until the server restarted.
-    /// Past it, FFmpeg is killed and nothing it wrote is kept.
-    #[allow(clippy::too_many_arguments)]
-    fn fill_cache_behind_a_seek(
-        &self,
-        source: PathBuf,
-        format: OutputFormat,
-        bitrate: u32,
-        gain: Option<Gain>,
-        key: String,
-        cache_path: PathBuf,
-        deadline: Duration,
-    ) {
-        if !self.inner.pending_fills.insert(key.clone()) {
-            return;
-        }
-        // Released on every way out from here on, the refusals included, so a
-        // fill that could not start never stops the next seek from asking.
-        let pending = PendingFill {
-            inner: Arc::clone(&self.inner),
-            key,
-        };
-        // Two permits in one step and one handed straight back: a slot, with
-        // another still free after it. Checking for two and then taking one
-        // would leave a gap in which a second fill takes the last.
-        let Ok(mut global) = Arc::clone(&self.inner.global).try_acquire_many_owned(2) else {
-            return;
-        };
-        drop(global.split(1));
-        let Ok(mut command) = self.transcode_command(&source, format, bitrate, gain, 0) else {
-            return;
-        };
-        let staging = staging_path(&cache_path);
-        command
-            .arg("-y")
-            .arg(&staging)
-            .stdin(Stdio::null())
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .kill_on_drop(true);
-        let inner = Arc::clone(&self.inner);
-        inner.active_transcodes.fetch_add(1, Ordering::Relaxed);
-
-        tokio::spawn(async move {
-            // Declared in this order so they drop in the reverse one: the key
-            // and the slot are given back before the count reaches zero, so a
-            // caller waiting on the count finds all three released.
-            let _active = ActiveGuard(&inner.active_transcodes);
-            let _global = global;
-            let _pending = pending;
-            let mut child = match command.spawn() {
-                Ok(child) => child,
-                Err(error) => {
-                    tracing::warn!(error = %error, "failed to spawn ffmpeg for a cache fill");
-                    return;
-                }
-            };
-            let finished = match tokio::time::timeout(deadline, child.wait()).await {
-                Ok(status) => status.is_ok_and(|status| status.success()),
-                // Killed and awaited before its staging file is removed: a file
-                // a live process still holds cannot be deleted on Windows.
-                Err(_) => {
-                    let _ = child.kill().await;
-                    false
-                }
-            };
-            if !finished {
-                tracing::warn!(
-                    path = %source.display(),
-                    "ffmpeg cache fill failed or ran past its deadline"
-                );
-                let _ = tokio::fs::remove_file(&staging).await;
-                return;
-            }
-            // A play from the start may have committed the same key meanwhile.
-            // Its file is as good as this one, and replacing a file a reader
-            // may be streaming from is not a write worth making.
-            if tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
-                let _ = tokio::fs::remove_file(&staging).await;
-                return;
-            }
-            if let Err(error) = tokio::fs::rename(&staging, &cache_path).await {
-                tracing::warn!(error = %error, "transcode cache fill could not be committed");
-                let _ = tokio::fs::remove_file(&staging).await;
-                return;
-            }
-            inner.cache_access.insert(cache_path, SystemTime::now());
-            prune_cache(&inner).await;
-        });
-    }
-
-    #[allow(clippy::too_many_arguments)]
-    async fn stream_transcode(
-        &self,
-        user_id: Uuid,
-        source: PathBuf,
-        format: OutputFormat,
-        bitrate: u32,
-        gain: Option<Gain>,
-        offset_ms: u64,
-        cache: Option<(PathBuf, tokio::sync::OwnedMutexGuard<()>)>,
-    ) -> Result<Response, MediaError> {
-        let global = Arc::clone(&self.inner.global)
-            .try_acquire_owned()
-            .map_err(|_| MediaError::Busy)?;
-        let user_semaphore = self
-            .inner
-            .users
-            .entry(user_id)
-            .or_insert_with(|| Arc::new(Semaphore::new(self.inner.per_user_limit)))
-            .clone();
-        let user = user_semaphore
-            .try_acquire_owned()
-            .map_err(|_| MediaError::Busy)?;
-
-        let mut command = self.transcode_command(&source, format, bitrate, gain, offset_ms)?;
-        command
-            .arg("pipe:1")
-            .stdin(Stdio::null())
-            .stdout(Stdio::piped())
-            .stderr(Stdio::null())
-            .kill_on_drop(true);
-        let mut child = command.spawn().map_err(|error| {
-            tracing::error!(error = %error, "failed to spawn ffmpeg");
-            MediaError::Internal
-        })?;
-        let mut stdout = child.stdout.take().ok_or(MediaError::Internal)?;
-        let (sender, receiver) = mpsc::channel::<Result<Bytes, io::Error>>(8);
-        let inner = Arc::clone(&self.inner);
-        inner.active_transcodes.fetch_add(1, Ordering::Relaxed);
-
-        tokio::spawn(async move {
-            let _global = global;
-            let _user = user;
-            let _active = ActiveGuard(&inner.active_transcodes);
-            let (cache_path, _cache_guard) = match cache {
-                Some((path, guard)) => (Some(path), Some(guard)),
-                None => (None, None),
-            };
-            let temp_path = cache_path.as_deref().map(staging_path);
-            let mut cache_file = match temp_path.as_ref() {
-                Some(path) => match tokio::fs::File::create(path).await {
-                    Ok(file) => Some(file),
-                    Err(error) => {
-                        tracing::warn!(error = %error, path = %path.display(), "transcode cache write disabled for request");
-                        None
-                    }
-                },
-                None => None,
-            };
-            let mut buffer = vec![0u8; STREAM_CHUNK_SIZE];
-            let mut consumer_present = true;
-            loop {
-                // Watch for the consumer leaving alongside the read instead of
-                // only noticing on the next send. FFmpeg can sit on a chunk for
-                // a long time under load, and until it yields one there is
-                // nothing to fail on, so an abandoned transcode would hold a
-                // process and a concurrency slot for as long as the encode took.
-                // Both branches are cancel-safe, and `biased` checks departure
-                // first so a consumer that left during the read is seen at once.
-                let read = tokio::select! {
-                    biased;
-                    _ = sender.closed() => {
-                        consumer_present = false;
-                        break;
-                    }
-                    result = stdout.read(&mut buffer) => result,
-                };
-                match read {
-                    Ok(0) => break,
-                    Ok(read) => {
-                        if let Some(file) = cache_file.as_mut() {
-                            if let Err(error) = file.write_all(&buffer[..read]).await {
-                                tracing::warn!(error = %error, "transcode cache write failed");
-                                cache_file = None;
-                            }
-                        }
-                        if sender
-                            .send(Ok(Bytes::copy_from_slice(&buffer[..read])))
-                            .await
-                            .is_err()
-                        {
-                            consumer_present = false;
-                            break;
-                        }
-                    }
-                    Err(error) => {
-                        let _ = sender.send(Err(error)).await;
-                        consumer_present = false;
-                        break;
-                    }
-                }
-            }
-
-            if !consumer_present {
-                let _ = child.kill().await;
-                if let Some(path) = temp_path.as_ref() {
-                    let _ = tokio::fs::remove_file(path).await;
-                }
-                return;
-            }
-            let success = child
-                .wait()
-                .await
-                .map(|status| status.success())
-                .unwrap_or(false);
-            if success {
-                if let Some(mut file) = cache_file {
-                    if file.flush().await.is_ok() {
-                        drop(file);
-                        if let (Some(temp), Some(final_path)) =
-                            (temp_path.as_ref(), cache_path.as_ref())
-                        {
-                            if tokio::fs::rename(temp, final_path).await.is_ok() {
-                                inner
-                                    .cache_access
-                                    .insert(final_path.clone(), SystemTime::now());
-                                prune_cache(&inner).await;
-                            }
-                        }
-                    }
-                } else if let Some(path) = temp_path.as_ref() {
-                    let _ = tokio::fs::remove_file(path).await;
-                }
-            } else {
-                tracing::warn!(path = %source.display(), "ffmpeg transcode failed");
-                if let Some(path) = temp_path.as_ref() {
-                    let _ = tokio::fs::remove_file(path).await;
-                }
-            }
-        });
-
-        let body = Body::from_stream(ReceiverStream::new(receiver));
-        Ok((
-            StatusCode::OK,
-            [
-                (header::CONTENT_TYPE, mime_for_format(format)),
-                (header::CACHE_CONTROL, MEDIA_CACHE_CONTROL),
-                (header::ACCEPT_RANGES, "none"),
-            ],
-            body,
-        )
-            .into_response())
-    }
-}
-
-/// Releases a key's claim on the cache fill however the fill ends, so one that
-/// failed or never started does not stop the next seek from asking again.
-struct PendingFill {
-    inner: Arc<MediaInner>,
-    key: String,
-}
-
-impl Drop for PendingFill {
-    fn drop(&mut self) {
-        self.inner.pending_fills.remove(&self.key);
-    }
-}
-
-struct ActiveGuard<'a>(&'a AtomicUsize);
-
-impl Drop for ActiveGuard<'_> {
-    fn drop(&mut self) {
-        self.0.fetch_sub(1, Ordering::Relaxed);
-    }
-}
-
-/// Content type for a stored artwork, or `None` for a format we never wrote.
-///
-/// Shared by the native route and the Subsonic facade: two copies would drift
-/// on the day a format is added, and the client that got
-/// `application/octet-stream` would simply show no cover.
-pub fn artwork_mime(format: &str) -> Option<&'static str> {
-    match format {
-        "jpg" | "jpeg" => Some("image/jpeg"),
-        "png" => Some("image/png"),
-        "webp" => Some("image/webp"),
-        _ => None,
-    }
-}
-
-/// Reads an artwork file from the store.
-///
-/// `hash` and `format` come from the database, never from the request, so the
-/// joined path cannot escape `artwork_dir` — the caller resolves the request's
-/// id through `artwork_for_user`, which also enforces tenancy.
-pub async fn read_artwork(
-    artwork_dir: &std::path::Path,
-    hash: &str,
-    format: &str,
-) -> Option<(&'static str, Vec<u8>)> {
-    let mime = artwork_mime(format)?;
-    let bytes = tokio::fs::read(artwork_dir.join(format!("{hash}.{format}")))
-        .await
-        .ok()?;
-    Some((mime, bytes))
-}
-
-/// A canvas addressed by its hash. The bytes behind a hash never change, so
-/// this URL can never answer differently and a client should stop asking.
-const CANVAS_CANONICAL_CACHE: &str = "private, max-age=31536000, immutable";
-/// A canvas addressed by a track: the link is what it resolves, and a member
-/// can replace it at any moment. Stated apart from the artwork constants that
-/// happen to hold the same policy — a canvas is not a cover, and one changing
-/// must not drag the other.
-const CANVAS_ALIAS_CACHE: &str = "private, no-cache";
-
-fn mime_for_canvas(format: &str) -> &'static str {
-    match format {
-        "webm" => "video/webm",
-        // The store only ever holds what the probe accepted, and that is one of
-        // exactly two containers.
-        _ => "video/mp4",
-    }
-}
-
-/// Serves the blob behind a canvas, once something has authorised it.
-///
-/// Shared by the three ways in — the hash, the track alias, and a ticket — so
-/// the caching rule and the 304 live in one place and cannot drift apart per
-/// route. Which `cache_control` applies is the caller's decision, because only
-/// the caller knows how the URL was addressed.
-async fn serve_canvas(
-    state: &AppState,
-    blob: &crate::services::CanvasBlob,
-    headers: &HeaderMap,
-    cache_control: &'static str,
-) -> Result<Response, MediaError> {
-    // The validator is the hash however the URL was addressed, which is what
-    // makes revalidating an alias a 304 rather than a second transfer of bytes
-    // the client already holds.
-    let etag = format!("\"{}\"", blob.hash);
-    if if_none_match_hits(headers, &etag) {
-        return Ok((
-            StatusCode::NOT_MODIFIED,
-            [
-                (header::CACHE_CONTROL, cache_control.to_owned()),
-                (header::ETAG, etag),
-            ],
-        )
-            .into_response());
-    }
-    let range = headers
-        .get(header::RANGE)
-        .and_then(|value| value.to_str().ok());
-    let path = state.services.canvas_file(blob);
-    let mut response = serve_file(&path, range, mime_for_canvas(&blob.format)).await?;
-    let served = response.headers_mut();
-    served.insert(
-        header::CACHE_CONTROL,
-        HeaderValue::from_str(cache_control).map_err(|_| MediaError::Internal)?,
-    );
-    served.insert(
-        header::ETAG,
-        HeaderValue::from_str(&etag).map_err(|_| MediaError::Internal)?,
-    );
-    Ok(response)
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/canvas/{canvas_hash}",
-    tag = "media",
-    params(("canvas_hash" = String, Path)),
-    responses(
-        (status = 200, description = "The loop, immutable under this URL"),
-        (status = 206),
-        (status = 304),
-        (status = 401),
-        (status = 404)
-    )
-)]
-pub async fn canvas_by_hash(
-    State(state): State<AppState>,
-    AxumPath(canvas_hash): AxumPath<String>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    // Knowing a hash establishes nothing. Two accounts that are strangers to
-    // each other can hold the same loop, so this resolves through membership
-    // the way `artwork_for_user` does, and a hash nobody reachable references
-    // answers exactly like one that does not exist.
-    let blob = state
-        .services
-        .canvas_for_user(user.id, &canvas_hash)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "canvas lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    serve_canvas(&state, &blob, &headers, CANVAS_CANONICAL_CACHE).await
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/tracks/{track_id}/canvas",
-    tag = "media",
-    params(("track_id" = Uuid, Path)),
-    responses(
-        (status = 200, description = "The loop this track carries now"),
-        (status = 206),
-        (status = 304),
-        (status = 401),
-        (status = 404)
-    )
-)]
-pub async fn canvas_for_track(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    // A track id is guessed no worse than a hash, so the alias is no more an
-    // authorisation than the fingerprint is: membership in the track's library,
-    // re-read on this request. A track that does not exist, one belonging to
-    // somebody else, and one with no canvas all answer 404.
-    let blob = state
-        .services
-        .canvas_for_track(user.id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "canvas alias lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    serve_canvas(&state, &blob, &headers, CANVAS_ALIAS_CACHE).await
-}
-
-#[utoipa::path(
-    put,
-    path = "/api/v2/tracks/{track_id}/canvas",
-    tag = "media",
-    params(("track_id" = Uuid, Path)),
-    request_body(content = Vec<u8>, description = "An mp4 or webm loop"),
-    responses(
-        (status = 200, body = CanvasResponse),
-        (status = 401),
-        (status = 404),
-        (status = 409, description = "The library's canvas quota is full"),
-        (status = 413),
-        (status = 422, description = "Not a short loop this server will take")
-    )
-)]
-pub async fn put_canvas(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    headers: HeaderMap,
-    body: Bytes,
-) -> Result<axum::Json<CanvasResponse>, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    let device = crate::api::origin_device(&state, &headers, user.id)
-        .await
-        .map_err(|_| MediaError::InvalidRequest)?;
-    let blob = state
-        .services
-        .place_canvas(user.id, track_id, &body, device)
-        .await
-        .map_err(canvas_error)?;
-    Ok(axum::Json(CanvasResponse {
-        url: format!("/api/v2/canvas/{}", blob.hash),
-        hash: blob.hash,
-        format: blob.format,
-        byte_size: blob.byte_size,
-    }))
-}
-
-#[utoipa::path(
-    delete,
-    path = "/api/v2/tracks/{track_id}/canvas",
-    tag = "media",
-    params(("track_id" = Uuid, Path)),
-    responses((status = 204), (status = 401), (status = 404))
-)]
-pub async fn delete_canvas(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    headers: HeaderMap,
-) -> Result<StatusCode, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    let device = crate::api::origin_device(&state, &headers, user.id)
-        .await
-        .map_err(|_| MediaError::InvalidRequest)?;
-    state
-        .services
-        .remove_canvas(user.id, track_id, device)
-        .await
-        .map_err(canvas_error)?;
-    Ok(StatusCode::NO_CONTENT)
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/v2/tracks/{track_id}/canvas-ticket",
-    tag = "media",
-    params(("track_id" = Uuid, Path)),
-    responses((status = 200, body = StreamTicketResponse), (status = 401), (status = 404))
-)]
-pub async fn create_canvas_ticket(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    headers: HeaderMap,
-) -> Result<axum::Json<StreamTicketResponse>, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    // Minting proves access now; redeeming re-proves it. A member removed
-    // between the two loses the canvas immediately rather than at expiry.
-    state
-        .services
-        .canvas_for_track(user.id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "canvas ticket authorization lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    let expires_at = i64::try_from(state.stream_ticket_ttl.as_millis())
-        .ok()
-        .and_then(|ttl| crate::authentication::now_ms().checked_add(ttl))
-        .ok_or_else(|| {
-            tracing::error!("stream ticket TTL does not fit in an epoch timestamp");
-            MediaError::Internal
-        })?;
-    let ticket = crate::stream_ticket::mint(
-        &state.secret_box,
-        crate::stream_ticket::TicketKind::Canvas,
-        user.id,
-        track_id,
-        expires_at,
-    )
-    .map_err(|error| {
-        tracing::error!(error = %error, "canvas ticket minting failed");
-        MediaError::Internal
-    })?;
-    // Relative, for the same reason the audio ticket is: it is consumed by the
-    // client that just authenticated, not sent out of the application.
-    Ok(axum::Json(StreamTicketResponse {
-        url: format!("/api/v2/canvas-stream/{ticket}"),
-        expires_at,
-    }))
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/canvas-stream/{ticket}",
-    tag = "media",
-    params(("ticket" = String, Path)),
-    responses(
-        (status = 200, description = "What <video src> plays"),
-        (status = 206),
-        (status = 304),
-        (status = 404)
-    )
-)]
-pub async fn canvas_with_ticket(
-    State(state): State<AppState>,
-    AxumPath(ticket): AxumPath<String>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    // This route serves a canvas, and it says so. Without the assertion an
-    // audio ticket would open a canvas and the reverse — which is the whole
-    // reason the kind is inside the sealed payload.
-    let (_, user_id, track_id) =
-        crate::stream_ticket::verify(&state.secret_box, &ticket, crate::authentication::now_ms())
-            .filter(|(kind, ..)| *kind == crate::stream_ticket::TicketKind::Canvas)
-            .ok_or(MediaError::NotFound)?;
-    // Re-checked on every redemption, so a ticket cannot outlive the membership
-    // that justified it.
-    let blob = state
-        .services
-        .canvas_for_track(user_id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "ticket canvas authorization lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    // Addressed by a ticket that names a track, so this resolves the link of
-    // the moment exactly as the alias does, and caches like it.
-    serve_canvas(&state, &blob, &headers, CANVAS_ALIAS_CACHE).await
-}
-
-/// Maps a canvas refusal onto the status that says it.
-///
-/// `Forbidden` becomes 404 like everywhere else in this API: a caller who may
-/// not place a canvas learns nothing about whether the library would have taken
-/// one. `Invalid` is 422 rather than 400 — the request was well formed, and
-/// what it carried is not a short loop this server will keep.
-fn canvas_error(error: crate::services::ServiceError) -> MediaError {
-    match error {
-        crate::services::ServiceError::NotFound | crate::services::ServiceError::Forbidden => {
-            MediaError::NotFound
-        }
-        crate::services::ServiceError::Invalid => MediaError::InvalidRequest,
-        crate::services::ServiceError::Conflict => MediaError::Conflict,
-        error => {
-            tracing::error!(error = %error, "canvas mutation failed");
-            MediaError::Internal
-        }
-    }
-}
-
-/// What a placed canvas answers with.
-#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
-pub struct CanvasResponse {
-    /// Where the bytes are, addressed by content. Immutable under this URL.
-    pub url: String,
-    pub hash: String,
-    /// `mp4` or `webm`, decided by reading the bytes rather than by trusting
-    /// what the request called them.
-    pub format: String,
-    pub byte_size: i64,
-}
-
-pub fn router(state: AppState) -> Router {
-    // Read before the state moves into the router: the ceiling follows the
-    // configured canvas size, so the two cannot disagree.
-    let canvas_body_limit = state.canvas_body_limit;
-    Router::new()
-        .route("/api/v2/artwork/{artwork_id}", get(artwork))
-        .route("/api/v2/canvas/{canvas_hash}", get(canvas_by_hash))
-        .route(
-            "/api/v2/tracks/{track_id}/canvas",
-            get(canvas_for_track)
-                .put(put_canvas.layer(axum::extract::DefaultBodyLimit::max(canvas_body_limit)))
-                .delete(delete_canvas),
-        )
-        .route(
-            "/api/v2/tracks/{track_id}/canvas-ticket",
-            axum::routing::post(create_canvas_ticket),
-        )
-        // Outside the bearer surface, like the audio one and for the same
-        // reason: <video src> cannot send an Authorization header.
-        .route("/api/v2/canvas-stream/{ticket}", get(canvas_with_ticket))
-        .route("/api/v2/tracks/{track_id}/stream", get(stream_track))
-        .route(
-            "/api/v2/tracks/{track_id}/stream-ticket",
-            axum::routing::post(create_stream_ticket),
-        )
-        // Deliberately outside the bearer-authenticated surface: the sealed
-        // ticket in the path is the credential, because <audio src> cannot send
-        // an Authorization header.
-        .route("/api/v2/stream/{ticket}", get(stream_with_ticket))
-        .with_state(state)
-}
-
-#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
-pub struct StreamTicketResponse {
-    /// Path to play from, already containing the ticket.
-    ///
-    /// **Always relative to this server**, never absolute — unlike a share URL,
-    /// which is prefixed with `WAVEFLOW_PUBLIC_URL` because it is meant to be
-    /// sent outside the application. Clients may safely reject an absolute or
-    /// protocol-relative value here, and are encouraged to.
-    pub url: String,
-    pub expires_at: i64,
-}
-
-/// Resolves a Bearer caller for the media routes through the same door as
-/// every other route.
-///
-/// These three used to extract the header and call the authenticator
-/// themselves, which meant they were outside the one place scopes are
-/// checked. They are reads, so today the check grants what it already
-/// granted; the point is that a mutation added here cannot quietly skip it,
-/// which is exactly how the scope list came to be stored and never read.
-///
-/// `/api/v2/stream/{ticket}` is deliberately not routed through this: its
-/// credential is the sealed ticket in the path, because `<audio src>` cannot
-/// send an Authorization header.
-async fn bearer_principal(
-    state: &AppState,
-    headers: &HeaderMap,
-) -> Result<crate::authentication::AuthUser, MediaError> {
-    crate::api::authenticated(state, headers, crate::api::Access::Read)
-        .await
-        .map_err(|_| MediaError::Unauthorized)
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/artwork/{artwork_id}",
-    tag = "media",
-    params((
-        "artwork_id" = String,
-        Path,
-        description = "An `artwork_hash` from any catalogue payload, or the id of a track, \
-                       album or artist that carries one."
-    )),
-    responses(
-        (status = 200, description = "Cover image", content_type = "image/jpeg"),
-        (status = 401),
-        (status = 404)
-    )
-)]
-/// Serves a cover behind the same bearer as the rest of the native API.
-///
-/// Catalogue payloads carry `artwork_hash` but nothing resolved it: only the
-/// Subsonic facade served images, behind a separate credential. A native client
-/// therefore showed a remote catalogue with no covers at all.
-///
-/// Access is re-checked per request through `artwork_for_user`, so a hash
-/// guessed from another tenant's library answers 404 like anything else.
-pub async fn artwork(
-    State(state): State<AppState>,
-    AxumPath(artwork_id): AxumPath<String>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    let (hash, format) = state
-        .services
-        .artwork_for_user(user.id, &artwork_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "artwork lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-
-    // How the URL was addressed decides what a client may do with the answer,
-    // and the two forms are not the same resource.
-    //
-    // Addressed by hash, the hash *is* the content: this URL can never answer
-    // differently, so a client should stop revalidating it entirely. Addressed
-    // by a track, album or artist id, the lookup above resolved that entity's
-    // *current* cover — and a rescan that finds new embedded art moves it. The
-    // alias must stay revalidatable or a replaced cover would be frozen in
-    // every client's cache for a year.
-    //
-    // `private` on both, and neither becomes `public`: the route is
-    // authenticated and tenant-checked, and two accounts whose libraries hold
-    // the same cover share its hash, so a shared cache keyed on the URL would
-    // hand one tenant's artwork to another with no credential in sight. A
-    // private cache is the client's own and loses nothing by the restriction.
-    let cache_control = if artwork_id == hash {
-        ARTWORK_CANONICAL_CACHE
-    } else {
-        ARTWORK_ALIAS_CACHE
-    };
-    // The validator is the hash either way, which is what makes revalidating an
-    // alias a 304 rather than a second full transfer of the same bytes.
-    let etag = format!("\"{hash}\"");
-    if if_none_match_hits(&headers, &etag) {
-        return Ok((
-            StatusCode::NOT_MODIFIED,
-            [
-                (header::CACHE_CONTROL, cache_control.to_owned()),
-                (header::ETAG, etag),
-            ],
-        )
-            .into_response());
-    }
-
-    let (mime, bytes) = read_artwork(&state.artwork_dir, &hash, &format)
-        .await
-        .ok_or(MediaError::NotFound)?;
-    Ok((
-        StatusCode::OK,
-        [
-            (header::CONTENT_TYPE, mime.to_owned()),
-            (header::CACHE_CONTROL, cache_control.to_owned()),
-            (header::ETAG, etag),
-        ],
-        bytes,
-    )
-        .into_response())
-}
-
-/// Whether the request already holds this exact entity.
-///
-/// `*` matches anything the client has, which for a single-representation
-/// resource is this one.
-fn if_none_match_hits(headers: &HeaderMap, etag: &str) -> bool {
-    headers
-        .get(header::IF_NONE_MATCH)
-        .and_then(|value| value.to_str().ok())
-        .is_some_and(|value| {
-            value
-                .split(',')
-                .map(str::trim)
-                .any(|candidate| candidate == etag || candidate == "*")
-        })
-}
-
-#[utoipa::path(
-    post,
-    path = "/api/v2/tracks/{track_id}/stream-ticket",
-    tag = "media",
-    params(("track_id" = Uuid, Path)),
-    responses(
-        (status = 200, body = StreamTicketResponse),
-        (status = 401),
-        (status = 404)
-    )
-)]
-pub async fn create_stream_ticket(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    headers: HeaderMap,
-) -> Result<axum::Json<StreamTicketResponse>, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    // Minting proves access now; redeeming re-proves it, so a ticket cannot
-    // outlive the membership that justified it.
-    state
-        // A track this account reads, or a stored podcast episode (RFC-025
-        // decision 11): the one lookup every stream route makes.
-        .services
-        .stream_source_for_user(user.id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "stream ticket authorization lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    // Saturating on overflow would mint a ticket that never expires; a TTL that
-    // cannot be represented is a misconfiguration, not something to round off.
-    let expires_at = i64::try_from(state.stream_ticket_ttl.as_millis())
-        .ok()
-        .and_then(|ttl| crate::authentication::now_ms().checked_add(ttl))
-        .ok_or_else(|| {
-            tracing::error!("stream ticket TTL does not fit in an epoch timestamp");
-            MediaError::Internal
-        })?;
-    let ticket = crate::stream_ticket::mint(
-        &state.secret_box,
-        crate::stream_ticket::TicketKind::Audio,
-        user.id,
-        track_id,
-        expires_at,
-    )
-    .map_err(|error| {
-        tracing::error!(error = %error, "stream ticket minting failed");
-        MediaError::Internal
-    })?;
-    // Deliberately relative, and deliberately unlike `createShare`, which does
-    // prefix WAVEFLOW_PUBLIC_URL. A share link is made to leave the
-    // application; a ticket is consumed by the client that just authenticated.
-    // Handing it an absolute URL would let the server redirect playback to a
-    // host the user never authenticated against — which is why native clients
-    // reject absolute and protocol-relative values. Do not "harmonise" the two.
-    Ok(axum::Json(StreamTicketResponse {
-        url: format!("/api/v2/stream/{ticket}"),
-        expires_at,
-    }))
-}
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/stream/{ticket}",
-    tag = "media",
-    params(
-        ("ticket" = String, Path),
-        ("format" = Option<String>, Query, description = "raw, mp3, opus or aac (ADTS)"),
-        ("bitrate" = Option<u32>, Query),
-        ("offset_ms" = Option<u64>, Query),
-        ("download" = Option<String>, Query, description = "1: the original, as an attachment named after the file (RFC-012)")
-    ),
-    responses(
-        (status = 200, description = "Original or live transcoded audio"),
-        (status = 206, description = "Original or completed cached transcode range"),
-        (status = 404),
-        (status = 416),
-        (status = 422, description = "A download asked for together with a transcode or an offset"),
-        (status = 429)
-    )
-)]
-pub async fn stream_with_ticket(
-    State(state): State<AppState>,
-    AxumPath(ticket): AxumPath<String>,
-    Query(query): Query<StreamQuery>,
-    Query(download): Query<DownloadQuery>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    // An invalid, forged or expired ticket is indistinguishable from an unknown
-    // track, so probing tells an attacker nothing. A ticket of another kind
-    // joins them: this route serves audio, and it says so rather than trusting
-    // that only audio tickets reach it.
-    let (_, user_id, track_id) =
-        crate::stream_ticket::verify(&state.secret_box, &ticket, crate::authentication::now_ms())
-            .filter(|(kind, ..)| *kind == crate::stream_ticket::TicketKind::Audio)
-            .ok_or(MediaError::NotFound)?;
-    let track = state
-        .services
-        .stream_source_for_user(user_id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "ticket stream authorization lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    let range = headers
-        .get(header::RANGE)
-        .and_then(|value| value.to_str().ok());
-    if !download.asked() {
-        return state.media.serve(user_id, track, query, range).await;
-    }
-    // A download is the file. A transcode, a bit rate or an offset would make
-    // it something else under the file's own name, so asking for one with it
-    // is refused rather than quietly ignored.
-    if query.format != OutputFormat::Raw || query.bitrate.is_some() || query.offset_ms != 0 {
-        return Err(MediaError::InvalidRequest);
-    }
-    let name = download_name(&state, user_id, &track).await;
-    let mut response = state.media.serve(user_id, track, query, range).await?;
-    response
-        .headers_mut()
-        .insert(header::CONTENT_DISPOSITION, attachment(&name));
-    Ok(response)
-}
-
-/// The name a downloaded file is saved under.
-///
-/// A scanned track's own basename, which is what its owner called it. A track
-/// received through RFC-008 is named by its hash on disk, so it is saved as
-/// `Artist - Title.ext` from its tags instead — the hash is truthful and of no
-/// use to anyone who opens their downloads folder.
-async fn download_name(state: &AppState, user_id: Uuid, track: &StreamTrack) -> String {
-    let path = Path::new(&track.relative_path);
-    let basename = path
-        .file_name()
-        .and_then(OsStr::to_str)
-        .unwrap_or("track")
-        .to_owned();
-    let received = track
-        .relative_path
-        .split('/')
-        .next()
-        .is_some_and(|first| first == crate::services::uploads::MANAGED_DIR);
-    if !received {
-        return basename;
-    }
-    let extension = path.extension().and_then(OsStr::to_str).unwrap_or("");
-    let song = state
-        .services
-        .songs_by_ids(user_id, &[track.id])
-        .await
-        .ok()
-        .and_then(|songs| songs.into_iter().next());
-    let Some(song) = song else {
-        return basename;
-    };
-    let stem = match song
-        .artist
-        .as_deref()
-        .map(str::trim)
-        .filter(|a| !a.is_empty())
-    {
-        Some(artist) => format!("{artist} - {}", song.title.trim()),
-        None => song.title.trim().to_owned(),
-    };
-    if stem.is_empty() {
-        return basename;
-    }
-    if extension.is_empty() {
-        stem
-    } else {
-        format!("{stem}.{extension}")
-    }
-}
-
-/// `attachment` with the name in both forms RFC 6266 gives it.
-///
-/// `filename` is an ASCII fallback, every character a browser could misread
-/// in a quoted string — a quote, a backslash, a control, anything outside
-/// ASCII — replaced by `_`, and a separator too, so no browser builds a path
-/// from it. `filename*` carries the real name, percent-encoded UTF-8, and
-/// every current browser prefers it.
-pub(crate) fn attachment(name: &str) -> HeaderValue {
-    let cleaned: String = name
-        .chars()
-        .map(|c| match c {
-            '/' | '\\' => '_',
-            c if c.is_control() => '_',
-            c => c,
-        })
-        .collect();
-    let fallback: String = cleaned
-        .chars()
-        .map(|c| match c {
-            ' '..='~' if c != '"' && c != '\\' => c,
-            _ => '_',
-        })
-        .collect();
-    let encoded = percent_encoding::utf8_percent_encode(&cleaned, ATTR_CHAR).to_string();
-    HeaderValue::from_str(&format!(
-        "attachment; filename=\"{fallback}\"; filename*=UTF-8''{encoded}"
-    ))
-    .unwrap_or_else(|_| HeaderValue::from_static("attachment"))
-}
-
-/// Everything but RFC 5987's `attr-char` is percent-encoded in `filename*`.
-const ATTR_CHAR: &percent_encoding::AsciiSet = &percent_encoding::NON_ALPHANUMERIC
-    .remove(b'!')
-    .remove(b'#')
-    .remove(b'$')
-    .remove(b'&')
-    .remove(b'+')
-    .remove(b'-')
-    .remove(b'.')
-    .remove(b'^')
-    .remove(b'_')
-    .remove(b'`')
-    .remove(b'|')
-    .remove(b'~');
-
-#[utoipa::path(
-    get,
-    path = "/api/v2/tracks/{track_id}/stream",
-    tag = "media",
-    params(
-        ("track_id" = Uuid, Path),
-        ("format" = Option<String>, Query, description = "raw, mp3, opus or aac (ADTS)"),
-        ("bitrate" = Option<u32>, Query),
-        ("offset_ms" = Option<u64>, Query)
-    ),
-    responses(
-        (status = 200, description = "Original or live transcoded audio"),
-        (status = 206, description = "Original or completed cached transcode range"),
-        (status = 401),
-        (status = 404),
-        (status = 416),
-        (status = 429)
-    )
-)]
-pub async fn stream_track(
-    State(state): State<AppState>,
-    AxumPath(track_id): AxumPath<Uuid>,
-    Query(query): Query<StreamQuery>,
-    headers: HeaderMap,
-) -> Result<Response, MediaError> {
-    let user = bearer_principal(&state, &headers).await?;
-    let track = state
-        // A track this account reads, or a stored podcast episode (RFC-025
-        // decision 11): the one lookup every stream route makes.
-        .services
-        .stream_source_for_user(user.id, track_id)
-        .await
-        .map_err(|error| {
-            tracing::error!(error = %error, "stream authorization lookup failed");
-            MediaError::Internal
-        })?
-        .ok_or(MediaError::NotFound)?;
-    let range = headers
-        .get(header::RANGE)
-        .and_then(|value| value.to_str().ok());
-    state.media.serve(user.id, track, query, range).await
 }
 
 impl IntoResponse for MediaError {
@@ -1604,805 +325,55 @@ async fn check_tool(path: &Path, name: &str) -> anyhow::Result<Vec<u8>> {
     Ok(output.stdout)
 }
 
-///
-/// **A link on the way** is refused, with one exception: a library following
-/// links stores a file in an allowed folder outside its root under the path
-/// the walk reached it through (RFC-021, links outside the root). Such a path
-/// is accepted only while that library still follows links, and only when it
-/// resolves, now, into one of `link_roots` and into no other library's root —
-/// re-read on every request, so a link retargeted since the scan, or a links
-/// setting turned off since, leads nowhere. Another library's file is never
-/// reached through a link, whoever asks: the caller's access was checked on
-/// this track's library only.
-pub(crate) async fn secure_track_path(
-    root: &Path,
-    relative: &str,
-    link_roots: &crate::link_roots::LinkRoots,
-    policy: &crate::link_roots::LinkPolicy,
-) -> io::Result<PathBuf> {
-    let canonical_root = tokio::fs::canonicalize(root).await?;
-    let relative = Path::new(relative);
-    if relative.as_os_str().is_empty()
-        || relative
-            .components()
-            .any(|component| !matches!(component, Component::Normal(_)))
-    {
-        return Err(io::Error::new(
-            io::ErrorKind::PermissionDenied,
-            "invalid relative media path",
-        ));
-    }
-
-    let mut cursor = canonical_root.clone();
-    let mut through_link = false;
-    for component in relative.components() {
-        let Component::Normal(component) = component else {
-            unreachable!("components validated above")
-        };
-        cursor.push(component);
-        if tokio::fs::symlink_metadata(&cursor)
-            .await?
-            .file_type()
-            .is_symlink()
-        {
-            if !policy.follow_links || link_roots.is_empty() {
-                return Err(io::Error::new(
-                    io::ErrorKind::PermissionDenied,
-                    "symlink media path rejected",
-                ));
-            }
-            through_link = true;
-        }
-    }
-    let canonical_file = tokio::fs::canonicalize(&cursor).await?;
-    let reachable = if through_link {
-        // Off the async worker: resolving a root is a blocking call, and a
-        // hung network mount would otherwise hold the worker with it.
-        let (link_roots, policy, target) =
-            (link_roots.clone(), policy.clone(), canonical_file.clone());
-        tokio::task::spawn_blocking(move || {
-            crate::link_roots::admits(
-                &link_roots.resolved(),
-                &policy.other_libraries_resolved(),
-                &target,
-            )
-        })
-        .await
-        .map_err(io::Error::other)?
-    } else {
-        canonical_file.starts_with(&canonical_root)
-    };
-    if !reachable || !tokio::fs::metadata(&canonical_file).await?.is_file() {
-        return Err(io::Error::new(
-            io::ErrorKind::PermissionDenied,
-            "media path escapes library",
-        ));
-    }
-    Ok(canonical_file)
-}
-
-async fn serve_file(
-    path: &Path,
-    range: Option<&str>,
-    mime: &'static str,
-) -> Result<Response, MediaError> {
-    let file = tokio::fs::File::open(path)
-        .await
-        .map_err(|_| MediaError::NotFound)?;
-    let size = file
-        .metadata()
-        .await
-        .map_err(|_| MediaError::NotFound)?
-        .len();
-    match range {
-        Some(range) => {
-            let (start, end) =
-                parse_range(range, size).ok_or(MediaError::RangeNotSatisfiable(Some(size)))?;
-            serve_partial(file, start, end, size, mime).await
-        }
-        None => {
-            let mut response = Response::new(Body::from_stream(ReaderStream::new(file)));
-            *response.status_mut() = StatusCode::OK;
-            response
-                .headers_mut()
-                .insert(header::CONTENT_TYPE, HeaderValue::from_static(mime));
-            response.headers_mut().insert(
-                header::CONTENT_LENGTH,
-                HeaderValue::from_str(&size.to_string()).map_err(|_| MediaError::Internal)?,
-            );
-            response
-                .headers_mut()
-                .insert(header::ACCEPT_RANGES, HeaderValue::from_static("bytes"));
-            response.headers_mut().insert(
-                header::CACHE_CONTROL,
-                HeaderValue::from_static(MEDIA_CACHE_CONTROL),
-            );
-            Ok(response)
-        }
-    }
-}
-
-async fn serve_partial(
-    mut file: tokio::fs::File,
-    start: u64,
-    end: u64,
-    size: u64,
-    mime: &'static str,
-) -> Result<Response, MediaError> {
-    file.seek(std::io::SeekFrom::Start(start))
-        .await
-        .map_err(|_| MediaError::Internal)?;
-    let length = end - start + 1;
-    let stream = ReaderStream::new(file.take(length));
-    let mut response = Response::new(Body::from_stream(stream));
-    *response.status_mut() = StatusCode::PARTIAL_CONTENT;
-    let headers = response.headers_mut();
-    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static(mime));
-    headers.insert(
-        header::CONTENT_LENGTH,
-        HeaderValue::from_str(&length.to_string()).map_err(|_| MediaError::Internal)?,
-    );
-    headers.insert(header::ACCEPT_RANGES, HeaderValue::from_static("bytes"));
-    headers.insert(
-        header::CACHE_CONTROL,
-        HeaderValue::from_static(MEDIA_CACHE_CONTROL),
-    );
-    headers.insert(
-        header::CONTENT_RANGE,
-        HeaderValue::from_str(&format!("bytes {start}-{end}/{size}"))
-            .map_err(|_| MediaError::Internal)?,
-    );
-    Ok(response)
+pub fn router(state: AppState) -> Router {
+    // Read before the state moves into the router: the ceiling follows the
+    // configured canvas size, so the two cannot disagree.
+    let canvas_body_limit = state.canvas_body_limit;
+    Router::new()
+        .route("/api/v2/artwork/{artwork_id}", get(artwork))
+        .route("/api/v2/canvas/{canvas_hash}", get(canvas_by_hash))
+        .route(
+            "/api/v2/tracks/{track_id}/canvas",
+            get(canvas_for_track)
+                .put(put_canvas.layer(axum::extract::DefaultBodyLimit::max(canvas_body_limit)))
+                .delete(delete_canvas),
+        )
+        .route(
+            "/api/v2/tracks/{track_id}/canvas-ticket",
+            axum::routing::post(create_canvas_ticket),
+        )
+        // Outside the bearer surface, like the audio one and for the same
+        // reason: <video src> cannot send an Authorization header.
+        .route("/api/v2/canvas-stream/{ticket}", get(canvas_with_ticket))
+        .route("/api/v2/tracks/{track_id}/stream", get(stream_track))
+        .route(
+            "/api/v2/tracks/{track_id}/stream-ticket",
+            axum::routing::post(create_stream_ticket),
+        )
+        // Deliberately outside the bearer-authenticated surface: the sealed
+        // ticket in the path is the credential, because <audio src> cannot send
+        // an Authorization header.
+        .route("/api/v2/stream/{ticket}", get(stream_with_ticket))
+        .with_state(state)
 }
 
-/// Whether a `Range` header starts at the first byte, which is how a player
-/// opens a resource rather than how it seeks into one. Browsers send `bytes=0-`;
-/// iOS AVFoundation first probes with `bytes=0-1` to learn the size and type.
-/// Both mean "begin here", and neither can be refused without breaking the
-/// first play of every track.
+/// Resolves a Bearer caller for the media routes through the same door as
+/// every other route.
 ///
-/// The answer to such a request is the whole stream rather than the bytes
-/// asked for, which HTTP allows: a server may always ignore `Range` and answer
-/// 200. Before the transcode exists there is no total length to put in a
-/// `Content-Range`, so a partial answer is not available to give.
-fn starts_at_the_first_byte(value: &str) -> bool {
-    value.strip_prefix("bytes=").is_some_and(|spec| {
-        // A multipart range is several ranges, and this answers with one body.
-        let Some((start, end)) = spec.trim().split_once('-') else {
-            return false;
-        };
-        start.trim().parse::<u64>() == Ok(0)
-            // A malformed end - a second hyphen, a word - is not a range this
-            // understands, so it is refused rather than read as an open.
-            && (end.trim().is_empty() || end.trim().parse::<u64>().is_ok())
-    })
-}
-
-fn parse_range(value: &str, size: u64) -> Option<(u64, u64)> {
-    if size == 0 {
-        return None;
-    }
-    let value = value.strip_prefix("bytes=")?;
-    if value.contains(',') {
-        return None;
-    }
-    let (start, end) = value.trim().split_once('-')?;
-    // Trimmed on both bounds, like `starts_at_the_first_byte`: a spelling the
-    // cold path accepts must not be refused once the cache exists.
-    let (start, end) = (start.trim(), end.trim());
-    if start.is_empty() {
-        let suffix = end.parse::<u64>().ok()?.min(size).min(MAX_RANGE_BYTES);
-        if suffix == 0 {
-            return None;
-        }
-        return Some((size - suffix, size - 1));
-    }
-    let start = start.parse::<u64>().ok()?;
-    if start >= size {
-        return None;
-    }
-    let requested_end = if end.is_empty() {
-        size - 1
-    } else {
-        end.parse::<u64>().ok()?.min(size - 1)
-    };
-    if requested_end < start {
-        return None;
-    }
-    Some((start, requested_end.min(start + MAX_RANGE_BYTES - 1)))
-}
-
-fn validate_bitrate(format: OutputFormat, bitrate: Option<u32>) -> Result<u32, MediaError> {
-    let bitrate = bitrate.unwrap_or(match format {
-        OutputFormat::Mp3 => 192,
-        OutputFormat::Opus => 128,
-        OutputFormat::Aac => 192,
-        OutputFormat::Raw => return Err(MediaError::InvalidRequest),
-    });
-    if !(32..=512).contains(&bitrate) {
-        return Err(MediaError::InvalidRequest);
-    }
-    Ok(bitrate)
-}
-
-/// How far past the track's own length a cache fill may run.
+/// These three used to extract the header and call the authenticator
+/// themselves, which meant they were outside the one place scopes are
+/// checked. They are reads, so today the check grants what it already
+/// granted; the point is that a mutation added here cannot quietly skip it,
+/// which is exactly how the scope list came to be stored and never read.
 ///
-/// Encodes run many times faster than the music, so the track's length is
-/// already a generous bound, and a fill slower than that has stopped being a
-/// background job on a server with other work. The minute covers FFmpeg
-/// starting on a busy machine, and a track whose length the scan did not learn.
-const FILL_DEADLINE_MARGIN: Duration = Duration::from_secs(60);
-
-/// The deadline a cache fill of a track this long runs under.
-fn fill_deadline(duration_ms: i64) -> Duration {
-    Duration::from_millis(u64::try_from(duration_ms).unwrap_or(0))
-        .saturating_add(FILL_DEADLINE_MARGIN)
-}
-
-/// Where a transcode is written before it is whole, beside the name it will
-/// take. The pruning pass skips `.part-`, and the suffix is unique, so two
-/// writers of one key never share a file.
-fn staging_path(cache_path: &Path) -> PathBuf {
-    cache_path.with_extension(format!(
-        "{}.part-{}",
-        cache_path
-            .extension()
-            .and_then(OsStr::to_str)
-            .unwrap_or("cache"),
-        Uuid::new_v4()
-    ))
-}
-
-fn cache_key(source_hash: &str, format: OutputFormat, bitrate: u32, gain: Option<Gain>) -> String {
-    // A gain is named only when there is one, so every key written before
-    // ReplayGain existed is still the key of the same encode.
-    let gain = gain
-        .map(|gain| format!(":{}", gain.key()))
-        .unwrap_or_default();
-    blake3::hash(
-        format!("{source_hash}:{format:?}:{bitrate}:{TRANSCODE_PROFILE_VERSION}{gain}").as_bytes(),
-    )
-    .to_hex()
-    .to_string()
-}
-
-fn extension(format: OutputFormat) -> &'static str {
-    match format {
-        OutputFormat::Raw => "bin",
-        OutputFormat::Mp3 => "mp3",
-        OutputFormat::Opus => "opus",
-        OutputFormat::Aac => "aac",
-    }
-}
-
-fn mime_for_format(format: OutputFormat) -> &'static str {
-    match format {
-        OutputFormat::Raw => "application/octet-stream",
-        OutputFormat::Mp3 => "audio/mpeg",
-        OutputFormat::Opus => "audio/ogg",
-        OutputFormat::Aac => "audio/aac",
-    }
-}
-
-fn mime_for_path(path: &Path) -> &'static str {
-    match path
-        .extension()
-        .and_then(OsStr::to_str)
-        .unwrap_or_default()
-        .to_ascii_lowercase()
-        .as_str()
-    {
-        "mp3" => "audio/mpeg",
-        "flac" => "audio/flac",
-        "wav" => "audio/wav",
-        "ogg" | "oga" | "opus" => "audio/ogg",
-        "m4a" | "mp4" => "audio/mp4",
-        "aac" => "audio/aac",
-        "dsf" | "dff" => "audio/dsd",
-        _ => "application/octet-stream",
-    }
-}
-
-async fn prune_cache(inner: &MediaInner) {
-    let Ok(mut directory) = tokio::fs::read_dir(&inner.cache_dir).await else {
-        return;
-    };
-    let mut files = Vec::new();
-    let mut total = 0u64;
-    while let Ok(Some(entry)) = directory.next_entry().await {
-        let path = entry.path();
-        if path
-            .file_name()
-            .and_then(OsStr::to_str)
-            .is_some_and(|name| name.contains(".part-"))
-        {
-            continue;
-        }
-        let Ok(metadata) = entry.metadata().await else {
-            continue;
-        };
-        if !metadata.is_file() {
-            continue;
-        }
-        total = total.saturating_add(metadata.len());
-        let accessed = inner
-            .cache_access
-            .get(&path)
-            .map(|value| *value)
-            .or_else(|| metadata.modified().ok())
-            .unwrap_or(SystemTime::UNIX_EPOCH);
-        files.push((accessed, path, metadata.len()));
-    }
-    files.sort_by_key(|(accessed, _, _)| *accessed);
-    let mut removed = HashMap::new();
-    for (_, path, size) in files {
-        if total <= inner.cache_max_bytes {
-            break;
-        }
-        if tokio::fs::remove_file(&path).await.is_ok() {
-            total = total.saturating_sub(size);
-            inner.cache_access.remove(&path);
-            removed.insert(path, size);
-        }
-    }
-    if !removed.is_empty() {
-        tracing::debug!(files = removed.len(), "transcode cache pruned");
-    }
-}
-
-#[cfg(test)]
-pub(crate) mod tests {
-    use std::{
-        path::PathBuf,
-        sync::Arc,
-        time::{Duration, SystemTime},
-    };
-
-    use dashmap::DashMap;
-    use tokio::sync::{Mutex, Semaphore};
-
-    use super::{
-        attachment, cache_key, parse_range, prune_cache, secure_track_path,
-        starts_at_the_first_byte, MediaInner, MediaService, OutputFormat,
-    };
-
-    /// A download's name in both forms, whatever it holds.
-    ///
-    /// The fallback is what an old browser builds a path from, so a quote, a
-    /// backslash, a separator or anything outside ASCII must not survive in
-    /// it; `filename*` must carry the real name, accents and all.
-    #[test]
-    fn a_download_name_is_safe_in_both_forms() {
-        let header = attachment("Björk - Hyperballad \"live\" 1/2\\3.flac");
-        let header = header.to_str().unwrap();
-        assert_eq!(
-            header,
-            "attachment; filename=\"Bj_rk - Hyperballad _live_ 1_2_3.flac\"; \
-             filename*=UTF-8''Bj%C3%B6rk%20-%20Hyperballad%20%22live%22%201_2_3.flac"
-        );
-        // A control character is no part of a name.
-        let header = attachment("a\nb.flac");
-        assert!(
-            header
-                .to_str()
-                .unwrap()
-                .starts_with("attachment; filename=\"a_b.flac\""),
-            "{header:?}"
-        );
-    }
-
-    #[test]
-    fn ranges_are_bounded_and_validated() {
-        assert_eq!(parse_range("bytes=2-5", 10), Some((2, 5)));
-        assert_eq!(parse_range("bytes=8-", 10), Some((8, 9)));
-        assert_eq!(parse_range("bytes=-3", 10), Some((7, 9)));
-        assert_eq!(parse_range("bytes=10-", 10), None);
-        assert_eq!(parse_range("bytes=5-2", 10), None);
-        assert_eq!(parse_range("bytes=0-1,4-5", 10), None);
-        // Whitespace is tolerated on both bounds, so that a range the cold
-        // transcode path accepts is still satisfiable from the cache.
-        assert_eq!(parse_range("bytes= 0- ", 10), Some((0, 9)));
-        assert_eq!(parse_range("bytes= 2 - 5 ", 10), Some((2, 5)));
-    }
-
-    #[test]
-    fn a_range_from_the_first_byte_opens_a_resource() {
-        // How a browser opens an audio element, and how iOS probes one.
-        assert!(starts_at_the_first_byte("bytes=0-"));
-        assert!(starts_at_the_first_byte("bytes=0-1"));
-        assert!(starts_at_the_first_byte("bytes=0-1023"));
-        assert!(starts_at_the_first_byte("bytes= 0- "));
-        // Starting anywhere else is a seek, and has no meaning yet.
-        assert!(!starts_at_the_first_byte("bytes=1-"));
-        assert!(!starts_at_the_first_byte("bytes=19924-429882"));
-        assert!(!starts_at_the_first_byte("bytes=-3"));
-        // One body cannot answer several ranges.
-        assert!(!starts_at_the_first_byte("bytes=0-1,4-5"));
-        assert!(!starts_at_the_first_byte("items=0-"));
-        assert!(!starts_at_the_first_byte("bytes=00x-1"));
-        // A malformed end is not an open either.
-        assert!(!starts_at_the_first_byte("bytes=0-1-2"));
-        assert!(!starts_at_the_first_byte("bytes=0-invalid"));
-    }
-
-    #[tokio::test]
-    async fn media_paths_reject_parent_components_and_symlinks() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("library");
-        std::fs::create_dir_all(&root).unwrap();
-        std::fs::write(root.join("safe.wav"), b"audio").unwrap();
-        let none = crate::link_roots::LinkRoots::default();
-        let policy = crate::link_roots::LinkPolicy::default();
-        assert!(secure_track_path(&root, "safe.wav", &none, &policy)
-            .await
-            .is_ok());
-        assert!(secure_track_path(&root, "../safe.wav", &none, &policy)
-            .await
-            .is_err());
-
-        let link = root.join("linked.wav");
-        #[cfg(unix)]
-        let linked = std::os::unix::fs::symlink(root.join("safe.wav"), &link).is_ok();
-        #[cfg(windows)]
-        let linked = std::os::windows::fs::symlink_file(root.join("safe.wav"), &link).is_ok();
-        if linked {
-            assert!(secure_track_path(&root, "linked.wav", &none, &policy)
-                .await
-                .is_err());
-        }
-    }
-
-    /// A stored path through a link is accepted only when its library follows
-    /// links and it resolves, now, into an allowed folder outside the root
-    /// and into no other library (RFC-021, links outside the root): not into
-    /// the root itself, not anywhere else, not into another library's root
-    /// inside the allowed folder, not once the folder is no longer allowed,
-    /// and not once the library stopped following links.
-    #[tokio::test]
-    async fn a_link_is_followed_into_an_allowed_folder_only() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("library");
-        let farm = temp.path().join("farm");
-        let neighbour = farm.join("neighbour");
-        let elsewhere = temp.path().join("elsewhere");
-        for folder in [&root, &farm, &neighbour, &elsewhere] {
-            std::fs::create_dir_all(folder).unwrap();
-        }
-        std::fs::write(farm.join("kept.wav"), b"audio").unwrap();
-        std::fs::write(neighbour.join("theirs.wav"), b"audio").unwrap();
-        std::fs::write(elsewhere.join("secret.wav"), b"audio").unwrap();
-        std::fs::write(root.join("own.wav"), b"audio").unwrap();
-        #[cfg(unix)]
-        let make = |target: &std::path::Path, link: &std::path::Path| {
-            std::os::unix::fs::symlink(target, link).is_ok()
-        };
-        #[cfg(windows)]
-        let make = |target: &std::path::Path, link: &std::path::Path| {
-            std::os::windows::fs::symlink_file(target, link).is_ok()
-        };
-        if !(make(&farm.join("kept.wav"), &root.join("farmed.wav"))
-            && make(&neighbour.join("theirs.wav"), &root.join("crossing.wav"))
-            && make(&elsewhere.join("secret.wav"), &root.join("stolen.wav"))
-            && make(&root.join("own.wav"), &root.join("mine.wav")))
-        {
-            eprintln!("skipped: this system will not let the test make a symbolic link");
-            return;
-        }
-        let allowed = crate::link_roots::LinkRoots::new(vec![farm.clone()]);
-        let following = crate::link_roots::LinkPolicy {
-            follow_links: true,
-            other_libraries: vec![neighbour.clone()],
-        };
-        assert!(secure_track_path(&root, "farmed.wav", &allowed, &following)
-            .await
-            .is_ok());
-        assert!(
-            secure_track_path(&root, "crossing.wav", &allowed, &following)
-                .await
-                .is_err(),
-            "another library's file is never reached through a link"
-        );
-        assert!(secure_track_path(&root, "stolen.wav", &allowed, &following)
-            .await
-            .is_err());
-        assert!(
-            secure_track_path(&root, "mine.wav", &allowed, &following)
-                .await
-                .is_err(),
-            "a link inside the root is stored by its target, never by itself"
-        );
-        let none = crate::link_roots::LinkRoots::default();
-        assert!(secure_track_path(&root, "farmed.wav", &none, &following)
-            .await
-            .is_err());
-        let not_following = crate::link_roots::LinkPolicy {
-            follow_links: false,
-            ..following
-        };
-        assert!(
-            secure_track_path(&root, "farmed.wav", &allowed, &not_following)
-                .await
-                .is_err(),
-            "a library that does not follow links reads no link, allowlist or not"
-        );
-    }
-
-    #[tokio::test]
-    async fn cache_pruning_removes_the_least_recently_used_file() {
-        let temp = tempfile::tempdir().unwrap();
-        let old = temp.path().join("old.mp3");
-        let recent = temp.path().join("recent.mp3");
-        std::fs::write(&old, b"1234").unwrap();
-        std::fs::write(&recent, b"5678").unwrap();
-        let access = DashMap::new();
-        access.insert(old.clone(), SystemTime::UNIX_EPOCH);
-        access.insert(recent.clone(), SystemTime::now());
-        let inner = MediaInner {
-            ffmpeg: PathBuf::from("ffmpeg"),
-            ffprobe: PathBuf::from("ffprobe"),
-            cache_dir: temp.path().to_path_buf(),
-            cache_max_bytes: 4,
-            global: Arc::new(Semaphore::new(1)),
-            global_limit: 1,
-            per_user_limit: 1,
-            users: DashMap::new(),
-            cache_locks: DashMap::new(),
-            cache_access: access,
-            pending_fills: dashmap::DashSet::new(),
-            active_transcodes: std::sync::atomic::AtomicUsize::new(0),
-            transcoding_available: true,
-            ffmpeg_digest: String::new(),
-            link_roots: crate::link_roots::LinkRoots::default(),
-            subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
-        };
-        prune_cache(&inner).await;
-        assert!(!old.exists());
-        assert!(recent.exists());
-    }
-
-    /// The fill behind a seek neither waits on the cache lock nor gives up on
-    /// it. The play a seek abandons still holds that lock for the moment it
-    /// takes to notice its consumer is gone, and the seek lands inside that
-    /// moment. No integration test can arrange that instant; a test inside the
-    /// module can, by holding the lock itself the way the dying play does.
-    #[tokio::test]
-    async fn a_seek_fills_the_cache_while_the_abandoned_play_still_holds_its_lock() {
-        let temp = tempfile::tempdir().unwrap();
-        let mut config = crate::Config::for_data_dir(temp.path().join("data"));
-        config.transcode_global_limit = 4;
-        let media = MediaService::initialize(&config).await.unwrap();
-        let source = temp.path().join("track.wav");
-        silent_wav(&source, 2);
-
-        let key = cache_key("abandoned", OutputFormat::Mp3, 96, None);
-        let cache_path = media.inner.cache_dir.join(format!("{key}.mp3"));
-        let lock = media
-            .inner
-            .cache_locks
-            .entry(key.clone())
-            .or_insert_with(|| Arc::new(Mutex::new(())))
-            .clone();
-        let _held = lock.lock_owned().await;
-
-        media.fill_cache_behind_a_seek(
-            source,
-            OutputFormat::Mp3,
-            96,
-            None,
-            key,
-            cache_path.clone(),
-            Duration::from_secs(60),
-        );
-        assert_eq!(
-            media.active_transcodes(),
-            1,
-            "the fill must start while the lock is held"
-        );
-        for _ in 0..3_000 {
-            if media.active_transcodes() == 0 {
-                break;
-            }
-            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
-        }
-        assert_eq!(
-            media.active_transcodes(),
-            0,
-            "the fill must not wait for the lock"
-        );
-        assert!(
-            cache_path.exists(),
-            "the fill must commit the whole transcode"
-        );
-    }
-
-    /// A fill has no listener who can leave, so nothing else ends an encode
-    /// that never finishes. Past its deadline FFmpeg is killed, and neither a
-    /// cache file, nor a staging file, nor the key's claim is left behind —
-    /// the slot and the key are free for the next seek.
-    #[tokio::test]
-    async fn a_cache_fill_past_its_deadline_is_killed_and_leaves_nothing() {
-        let temp = tempfile::tempdir().unwrap();
-        let mut config = crate::Config::for_data_dir(temp.path().join("data"));
-        config.transcode_global_limit = 4;
-        let media = MediaService::initialize(&config).await.unwrap();
-        let source = temp.path().join("track.wav");
-        silent_wav(&source, 30);
-
-        let key = cache_key("overdue", OutputFormat::Mp3, 96, None);
-        let cache_path = media.inner.cache_dir.join(format!("{key}.mp3"));
-        // A millisecond: less than FFmpeg takes to start, let alone to finish.
-        media.fill_cache_behind_a_seek(
-            source,
-            OutputFormat::Mp3,
-            96,
-            None,
-            key,
-            cache_path.clone(),
-            Duration::from_millis(1),
-        );
-        assert_eq!(media.active_transcodes(), 1);
-        for _ in 0..3_000 {
-            if media.active_transcodes() == 0 {
-                break;
-            }
-            tokio::time::sleep(Duration::from_millis(10)).await;
-        }
-        assert_eq!(
-            media.active_transcodes(),
-            0,
-            "an overdue fill must give its slot back"
-        );
-        assert!(!cache_path.exists(), "an overdue fill must not commit");
-        let staged = std::fs::read_dir(&media.inner.cache_dir)
-            .unwrap()
-            .filter_map(Result::ok)
-            .any(|entry| entry.file_name().to_string_lossy().contains(".part-"));
-        assert!(!staged, "an overdue fill must remove its staging file");
-        assert!(
-            media.inner.pending_fills.is_empty(),
-            "an overdue fill must free its key for the next seek"
-        );
-    }
-
-    /// A listener on loopback that counts the connections it is offered and
-    /// closes each at once: what "nothing was fetched" is measured with.
-    pub(crate) async fn counting_listener() -> (
-        std::net::SocketAddr,
-        Arc<std::sync::atomic::AtomicUsize>,
-        tokio::task::JoinHandle<()>,
-    ) {
-        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
-        let address = listener.local_addr().unwrap();
-        let count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
-        let counted = Arc::clone(&count);
-        let task = tokio::spawn(async move {
-            while let Ok((socket, _)) = listener.accept().await {
-                counted.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
-                drop(socket);
-            }
-        });
-        (address, count, task)
-    }
-
-    fn a_media_service(dir: &std::path::Path) -> MediaService {
-        MediaService {
-            inner: Arc::new(MediaInner {
-                ffmpeg: PathBuf::from("ffmpeg"),
-                ffprobe: PathBuf::from("ffprobe"),
-                cache_dir: dir.to_path_buf(),
-                cache_max_bytes: 0,
-                global: Arc::new(Semaphore::new(1)),
-                global_limit: 1,
-                per_user_limit: 1,
-                users: DashMap::new(),
-                cache_locks: DashMap::new(),
-                cache_access: DashMap::new(),
-                pending_fills: dashmap::DashSet::new(),
-                active_transcodes: std::sync::atomic::AtomicUsize::new(0),
-                transcoding_available: true,
-                ffmpeg_digest: String::new(),
-                link_roots: crate::link_roots::LinkRoots::default(),
-                subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
-            }),
-        }
-    }
-
-    /// Runs the transcode FFmpeg would be given for `source`, to nowhere, and
-    /// answers whether it succeeded.
-    async fn transcode(media: &MediaService, source: &std::path::Path) -> bool {
-        let mut command = media
-            .transcode_command(source, OutputFormat::Mp3, 128, None, 0)
-            .unwrap();
-        command
-            .arg("pipe:1")
-            .stdin(std::process::Stdio::null())
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .kill_on_drop(true);
-        tokio::time::timeout(Duration::from_secs(60), command.status())
-            .await
-            .expect("ffmpeg must not hang on an input it refuses")
-            .expect("ffmpeg must be on PATH")
-            .success()
-    }
-
-    /// FFmpeg opens files and nothing else, whatever the input names
-    /// (RFC-023 decision 2).
-    ///
-    /// Three inputs, one property:
-    ///
-    /// - **A path that is a URL.** Without the whitelist FFmpeg connects to
-    ///   it; this is the case that tells the whitelist from its absence.
-    /// - **A playlist that names one.** An HLS playlist pointing at the same
-    ///   listener. FFmpeg 8 already refuses `http` from inside a file opened
-    ///   through `file` (its default nested list is `file,crypto,data`), so
-    ///   this one holds on that build either way: it is here so the property
-    ///   stays tested on a build whose default is wider.
-    /// - **A `concat:` URL** of two real files, which the default decodes.
-    ///
-    /// And one control: the same command plays a real file, so the whitelist
-    /// is proved not to be in the way of the one protocol the server uses —
-    /// on Windows too, where a path starts with a drive letter and a colon.
-    #[tokio::test]
-    async fn ffmpeg_opens_files_and_nothing_else() {
-        let temp = tempfile::tempdir().unwrap();
-        let media = a_media_service(temp.path());
-        let real = temp.path().join("real.wav");
-        silent_wav(&real, 1);
-        assert!(
-            transcode(&media, &real).await,
-            "a real file must still play"
-        );
-
-        let (address, connections, listener) = counting_listener().await;
-        let url = format!("http://{address}/track.mp3");
-        assert!(!transcode(&media, std::path::Path::new(&url)).await);
-
-        let playlist = temp.path().join("trap.m3u8");
-        std::fs::write(
-            &playlist,
-            format!(
-                "#EXTM3U\n#EXT-X-TARGETDURATION:1\n#EXTINF:1,\nhttp://{address}/segment.mp3\n#EXT-X-ENDLIST\n"
-            ),
-        )
-        .unwrap();
-        assert!(!transcode(&media, &playlist).await);
-
-        let concat = format!("concat:{}|{}", real.display(), real.display());
-        assert!(
-            !transcode(&media, std::path::Path::new(&concat)).await,
-            "a concat: input must be refused"
-        );
-
-        // Connections are counted as they are accepted; give the last one
-        // the moment it needs to land before reading the count.
-        tokio::time::sleep(Duration::from_millis(200)).await;
-        listener.abort();
-        assert_eq!(
-            connections.load(std::sync::atomic::Ordering::SeqCst),
-            0,
-            "ffmpeg must not have contacted anything"
-        );
-    }
-
-    /// Silence at 8 kHz, as long as asked.
-    pub(crate) fn silent_wav(path: &std::path::Path, seconds: u32) {
-        let generated = std::process::Command::new("ffmpeg")
-            .args([
-                "-hide_banner",
-                "-loglevel",
-                "error",
-                "-y",
-                "-f",
-                "lavfi",
-                "-i",
-                "anullsrc=r=8000:cl=mono",
-                "-t",
-            ])
-            .arg(seconds.to_string())
-            .arg(path)
-            .status()
-            .expect("ffmpeg must be on PATH");
-        assert!(generated.success());
-    }
+/// `/api/v2/stream/{ticket}` is deliberately not routed through this: its
+/// credential is the sealed ticket in the path, because `<audio src>` cannot
+/// send an Authorization header.
+async fn bearer_principal(
+    state: &AppState,
+    headers: &HeaderMap,
+) -> Result<crate::authentication::AuthUser, MediaError> {
+    crate::api::authenticated(state, headers, crate::api::Access::Read)
+        .await
+        .map_err(|_| MediaError::Unauthorized)
 }
diff --git a/src/media/stream.rs b/src/media/stream.rs
new file mode 100644
index 00000000..eab18b51
--- /dev/null
+++ b/src/media/stream.rs
@@ -0,0 +1,701 @@
+//! Playing a track's audio: the stream routes and their tickets, the path
+//! check, downloads, and the byte ranges a file is served by.
+
+use std::{
+    ffi::OsStr,
+    io,
+    path::{Component, Path, PathBuf},
+    sync::Arc,
+    time::SystemTime,
+};
+
+use axum::{
+    body::Body,
+    extract::{Path as AxumPath, Query, State},
+    http::{header, HeaderMap, HeaderValue, StatusCode},
+    response::Response,
+};
+use serde::Deserialize;
+use tokio::{
+    io::{AsyncReadExt, AsyncSeekExt},
+    sync::Mutex,
+};
+use tokio_util::io::ReaderStream;
+use uuid::Uuid;
+
+use super::transcode::{cache_key, extension, fill_deadline, mime_for_format};
+use super::{
+    bearer_principal, MediaError, MediaService, OutputFormat, StreamQuery, MEDIA_CACHE_CONTROL,
+};
+use crate::{catalog::StreamTrack, replay_gain::ReplayGainMode, AppState};
+
+const MAX_RANGE_BYTES: u64 = 8 * 1024 * 1024;
+
+/// `?download=1` on a stream ticket (RFC-012 decision 5).
+///
+/// Its own extractor rather than a field on [`StreamQuery`], which the
+/// Subsonic façade and the bearer route share and which has no business
+/// learning a header choice only the ticket route makes.
+#[derive(Debug, Default, Deserialize)]
+pub struct DownloadQuery {
+    download: Option<String>,
+}
+
+impl DownloadQuery {
+    fn asked(&self) -> bool {
+        matches!(self.download.as_deref(), Some("1" | "true"))
+    }
+}
+
+impl MediaService {
+    pub async fn serve(
+        &self,
+        user_id: Uuid,
+        track: StreamTrack,
+        query: StreamQuery,
+        range: Option<&str>,
+    ) -> Result<Response, MediaError> {
+        self.serve_with_replay_gain(user_id, track, query, range, ReplayGainMode::Off)
+            .await
+    }
+
+    /// [`Self::serve`], a transcode levelled by the track's ReplayGain under
+    /// `mode` (RFC-022, what was still open). The original is served as it is
+    /// whatever the mode says: the gain rides on an encode that happens anyway,
+    /// and never causes one. A gain is part of the cache key, so a levelled
+    /// encode is never handed to a request that did not ask for it; no gain —
+    /// the mode off, or a track with no tags — keeps the key it always had.
+    pub async fn serve_with_replay_gain(
+        &self,
+        user_id: Uuid,
+        track: StreamTrack,
+        query: StreamQuery,
+        range: Option<&str>,
+        mode: ReplayGainMode,
+    ) -> Result<Response, MediaError> {
+        let gain = crate::replay_gain::gain(track.replay_gain, mode);
+        if !track.available {
+            return Err(MediaError::NotFound);
+        }
+        let source = secure_track_path(
+            &track.library_root,
+            &track.relative_path,
+            &self.inner.link_roots,
+            &track.link_policy,
+        )
+        .await
+            .map_err(|error| {
+                tracing::warn!(track_id = %track.id, library_id = %track.library_id, error = %error, "media path rejected");
+                MediaError::NotFound
+            })?;
+
+        if query.format == OutputFormat::Raw {
+            if query.offset_ms != 0 || query.bitrate.is_some() {
+                return Err(MediaError::InvalidRequest);
+            }
+            return serve_file(&source, range, mime_for_path(&source)).await;
+        }
+
+        let bitrate = validate_bitrate(query.format, query.bitrate)?;
+        if query.offset_ms > track.duration_ms.max(0) as u64 {
+            return Err(MediaError::InvalidRequest);
+        }
+        let key = cache_key(&track.full_hash, query.format, bitrate, gain);
+        let cache_path = self
+            .inner
+            .cache_dir
+            .join(format!("{key}.{}", extension(query.format)));
+
+        if query.offset_ms == 0 && tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
+            self.inner
+                .cache_access
+                .insert(cache_path.clone(), SystemTime::now());
+            return serve_file(&cache_path, range, mime_for_format(query.format)).await;
+        }
+
+        // A byte range has no stable meaning until a transcode is complete, so
+        // seeking a live transcode goes through offset_ms instead. A range
+        // that starts at the first byte is not a seek though: it is how every
+        // player opens a resource. Refusing it made a client fail on the first
+        // play of a track and succeed on the second, once the cache existed —
+        // Feishin with `bytes=0-`, then Juliet with the `bytes=0-1` probe iOS
+        // sends before anything else.
+        if range.is_some_and(|value| !starts_at_the_first_byte(value)) {
+            return Err(MediaError::RangeNotSatisfiable(None));
+        }
+
+        if query.offset_ms > 0 {
+            let response = self
+                .stream_transcode(
+                    user_id,
+                    source.clone(),
+                    query.format,
+                    bitrate,
+                    gain,
+                    query.offset_ms,
+                    None,
+                )
+                .await?;
+            // After the live stream has its slots, never before: the listener
+            // waiting on this request comes first, and a fill that took the
+            // last slot would be the reason they were answered 429.
+            if !tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
+                self.fill_cache_behind_a_seek(
+                    source,
+                    query.format,
+                    bitrate,
+                    gain,
+                    key,
+                    cache_path,
+                    fill_deadline(track.duration_ms),
+                );
+            }
+            return Ok(response);
+        }
+
+        let lock = self
+            .inner
+            .cache_locks
+            .entry(key.clone())
+            .or_insert_with(|| Arc::new(Mutex::new(())))
+            .clone();
+        let guard = lock.lock_owned().await;
+        if tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
+            drop(guard);
+            self.inner
+                .cache_access
+                .insert(cache_path.clone(), SystemTime::now());
+            // Whoever held the lock finished the transcode, so the range that
+            // had no meaning a moment ago has one now, and the second caller
+            // gets the same partial answer it would have got from the cache.
+            return serve_file(&cache_path, range, mime_for_format(query.format)).await;
+        }
+
+        self.stream_transcode(
+            user_id,
+            source,
+            query.format,
+            bitrate,
+            gain,
+            0,
+            Some((cache_path, guard)),
+        )
+        .await
+    }
+}
+
+#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
+pub struct StreamTicketResponse {
+    /// Path to play from, already containing the ticket.
+    ///
+    /// **Always relative to this server**, never absolute — unlike a share URL,
+    /// which is prefixed with `WAVEFLOW_PUBLIC_URL` because it is meant to be
+    /// sent outside the application. Clients may safely reject an absolute or
+    /// protocol-relative value here, and are encouraged to.
+    pub url: String,
+    pub expires_at: i64,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v2/tracks/{track_id}/stream-ticket",
+    tag = "media",
+    params(("track_id" = Uuid, Path)),
+    responses(
+        (status = 200, body = StreamTicketResponse),
+        (status = 401),
+        (status = 404)
+    )
+)]
+pub async fn create_stream_ticket(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    headers: HeaderMap,
+) -> Result<axum::Json<StreamTicketResponse>, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    // Minting proves access now; redeeming re-proves it, so a ticket cannot
+    // outlive the membership that justified it.
+    state
+        // A track this account reads, or a stored podcast episode (RFC-025
+        // decision 11): the one lookup every stream route makes.
+        .services
+        .stream_source_for_user(user.id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "stream ticket authorization lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    // Saturating on overflow would mint a ticket that never expires; a TTL that
+    // cannot be represented is a misconfiguration, not something to round off.
+    let expires_at = i64::try_from(state.stream_ticket_ttl.as_millis())
+        .ok()
+        .and_then(|ttl| crate::authentication::now_ms().checked_add(ttl))
+        .ok_or_else(|| {
+            tracing::error!("stream ticket TTL does not fit in an epoch timestamp");
+            MediaError::Internal
+        })?;
+    let ticket = crate::stream_ticket::mint(
+        &state.secret_box,
+        crate::stream_ticket::TicketKind::Audio,
+        user.id,
+        track_id,
+        expires_at,
+    )
+    .map_err(|error| {
+        tracing::error!(error = %error, "stream ticket minting failed");
+        MediaError::Internal
+    })?;
+    // Deliberately relative, and deliberately unlike `createShare`, which does
+    // prefix WAVEFLOW_PUBLIC_URL. A share link is made to leave the
+    // application; a ticket is consumed by the client that just authenticated.
+    // Handing it an absolute URL would let the server redirect playback to a
+    // host the user never authenticated against — which is why native clients
+    // reject absolute and protocol-relative values. Do not "harmonise" the two.
+    Ok(axum::Json(StreamTicketResponse {
+        url: format!("/api/v2/stream/{ticket}"),
+        expires_at,
+    }))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/stream/{ticket}",
+    tag = "media",
+    params(
+        ("ticket" = String, Path),
+        ("format" = Option<String>, Query, description = "raw, mp3, opus or aac (ADTS)"),
+        ("bitrate" = Option<u32>, Query),
+        ("offset_ms" = Option<u64>, Query),
+        ("download" = Option<String>, Query, description = "1: the original, as an attachment named after the file (RFC-012)")
+    ),
+    responses(
+        (status = 200, description = "Original or live transcoded audio"),
+        (status = 206, description = "Original or completed cached transcode range"),
+        (status = 404),
+        (status = 416),
+        (status = 422, description = "A download asked for together with a transcode or an offset"),
+        (status = 429)
+    )
+)]
+pub async fn stream_with_ticket(
+    State(state): State<AppState>,
+    AxumPath(ticket): AxumPath<String>,
+    Query(query): Query<StreamQuery>,
+    Query(download): Query<DownloadQuery>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    // An invalid, forged or expired ticket is indistinguishable from an unknown
+    // track, so probing tells an attacker nothing. A ticket of another kind
+    // joins them: this route serves audio, and it says so rather than trusting
+    // that only audio tickets reach it.
+    let (_, user_id, track_id) =
+        crate::stream_ticket::verify(&state.secret_box, &ticket, crate::authentication::now_ms())
+            .filter(|(kind, ..)| *kind == crate::stream_ticket::TicketKind::Audio)
+            .ok_or(MediaError::NotFound)?;
+    let track = state
+        .services
+        .stream_source_for_user(user_id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "ticket stream authorization lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    let range = headers
+        .get(header::RANGE)
+        .and_then(|value| value.to_str().ok());
+    if !download.asked() {
+        return state.media.serve(user_id, track, query, range).await;
+    }
+    // A download is the file. A transcode, a bit rate or an offset would make
+    // it something else under the file's own name, so asking for one with it
+    // is refused rather than quietly ignored.
+    if query.format != OutputFormat::Raw || query.bitrate.is_some() || query.offset_ms != 0 {
+        return Err(MediaError::InvalidRequest);
+    }
+    let name = download_name(&state, user_id, &track).await;
+    let mut response = state.media.serve(user_id, track, query, range).await?;
+    response
+        .headers_mut()
+        .insert(header::CONTENT_DISPOSITION, attachment(&name));
+    Ok(response)
+}
+
+/// The name a downloaded file is saved under.
+///
+/// A scanned track's own basename, which is what its owner called it. A track
+/// received through RFC-008 is named by its hash on disk, so it is saved as
+/// `Artist - Title.ext` from its tags instead — the hash is truthful and of no
+/// use to anyone who opens their downloads folder.
+async fn download_name(state: &AppState, user_id: Uuid, track: &StreamTrack) -> String {
+    let path = Path::new(&track.relative_path);
+    let basename = path
+        .file_name()
+        .and_then(OsStr::to_str)
+        .unwrap_or("track")
+        .to_owned();
+    let received = track
+        .relative_path
+        .split('/')
+        .next()
+        .is_some_and(|first| first == crate::services::uploads::MANAGED_DIR);
+    if !received {
+        return basename;
+    }
+    let extension = path.extension().and_then(OsStr::to_str).unwrap_or("");
+    let song = state
+        .services
+        .songs_by_ids(user_id, &[track.id])
+        .await
+        .ok()
+        .and_then(|songs| songs.into_iter().next());
+    let Some(song) = song else {
+        return basename;
+    };
+    let stem = match song
+        .artist
+        .as_deref()
+        .map(str::trim)
+        .filter(|a| !a.is_empty())
+    {
+        Some(artist) => format!("{artist} - {}", song.title.trim()),
+        None => song.title.trim().to_owned(),
+    };
+    if stem.is_empty() {
+        return basename;
+    }
+    if extension.is_empty() {
+        stem
+    } else {
+        format!("{stem}.{extension}")
+    }
+}
+
+/// `attachment` with the name in both forms RFC 6266 gives it.
+///
+/// `filename` is an ASCII fallback, every character a browser could misread
+/// in a quoted string — a quote, a backslash, a control, anything outside
+/// ASCII — replaced by `_`, and a separator too, so no browser builds a path
+/// from it. `filename*` carries the real name, percent-encoded UTF-8, and
+/// every current browser prefers it.
+pub(crate) fn attachment(name: &str) -> HeaderValue {
+    let cleaned: String = name
+        .chars()
+        .map(|c| match c {
+            '/' | '\\' => '_',
+            c if c.is_control() => '_',
+            c => c,
+        })
+        .collect();
+    let fallback: String = cleaned
+        .chars()
+        .map(|c| match c {
+            ' '..='~' if c != '"' && c != '\\' => c,
+            _ => '_',
+        })
+        .collect();
+    let encoded = percent_encoding::utf8_percent_encode(&cleaned, ATTR_CHAR).to_string();
+    HeaderValue::from_str(&format!(
+        "attachment; filename=\"{fallback}\"; filename*=UTF-8''{encoded}"
+    ))
+    .unwrap_or_else(|_| HeaderValue::from_static("attachment"))
+}
+
+/// Everything but RFC 5987's `attr-char` is percent-encoded in `filename*`.
+const ATTR_CHAR: &percent_encoding::AsciiSet = &percent_encoding::NON_ALPHANUMERIC
+    .remove(b'!')
+    .remove(b'#')
+    .remove(b'$')
+    .remove(b'&')
+    .remove(b'+')
+    .remove(b'-')
+    .remove(b'.')
+    .remove(b'^')
+    .remove(b'_')
+    .remove(b'`')
+    .remove(b'|')
+    .remove(b'~');
+
+#[utoipa::path(
+    get,
+    path = "/api/v2/tracks/{track_id}/stream",
+    tag = "media",
+    params(
+        ("track_id" = Uuid, Path),
+        ("format" = Option<String>, Query, description = "raw, mp3, opus or aac (ADTS)"),
+        ("bitrate" = Option<u32>, Query),
+        ("offset_ms" = Option<u64>, Query)
+    ),
+    responses(
+        (status = 200, description = "Original or live transcoded audio"),
+        (status = 206, description = "Original or completed cached transcode range"),
+        (status = 401),
+        (status = 404),
+        (status = 416),
+        (status = 429)
+    )
+)]
+pub async fn stream_track(
+    State(state): State<AppState>,
+    AxumPath(track_id): AxumPath<Uuid>,
+    Query(query): Query<StreamQuery>,
+    headers: HeaderMap,
+) -> Result<Response, MediaError> {
+    let user = bearer_principal(&state, &headers).await?;
+    let track = state
+        // A track this account reads, or a stored podcast episode (RFC-025
+        // decision 11): the one lookup every stream route makes.
+        .services
+        .stream_source_for_user(user.id, track_id)
+        .await
+        .map_err(|error| {
+            tracing::error!(error = %error, "stream authorization lookup failed");
+            MediaError::Internal
+        })?
+        .ok_or(MediaError::NotFound)?;
+    let range = headers
+        .get(header::RANGE)
+        .and_then(|value| value.to_str().ok());
+    state.media.serve(user.id, track, query, range).await
+}
+
+///
+/// **A link on the way** is refused, with one exception: a library following
+/// links stores a file in an allowed folder outside its root under the path
+/// the walk reached it through (RFC-021, links outside the root). Such a path
+/// is accepted only while that library still follows links, and only when it
+/// resolves, now, into one of `link_roots` and into no other library's root —
+/// re-read on every request, so a link retargeted since the scan, or a links
+/// setting turned off since, leads nowhere. Another library's file is never
+/// reached through a link, whoever asks: the caller's access was checked on
+/// this track's library only.
+pub(crate) async fn secure_track_path(
+    root: &Path,
+    relative: &str,
+    link_roots: &crate::link_roots::LinkRoots,
+    policy: &crate::link_roots::LinkPolicy,
+) -> io::Result<PathBuf> {
+    let canonical_root = tokio::fs::canonicalize(root).await?;
+    let relative = Path::new(relative);
+    if relative.as_os_str().is_empty()
+        || relative
+            .components()
+            .any(|component| !matches!(component, Component::Normal(_)))
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "invalid relative media path",
+        ));
+    }
+
+    let mut cursor = canonical_root.clone();
+    let mut through_link = false;
+    for component in relative.components() {
+        let Component::Normal(component) = component else {
+            unreachable!("components validated above")
+        };
+        cursor.push(component);
+        if tokio::fs::symlink_metadata(&cursor)
+            .await?
+            .file_type()
+            .is_symlink()
+        {
+            if !policy.follow_links || link_roots.is_empty() {
+                return Err(io::Error::new(
+                    io::ErrorKind::PermissionDenied,
+                    "symlink media path rejected",
+                ));
+            }
+            through_link = true;
+        }
+    }
+    let canonical_file = tokio::fs::canonicalize(&cursor).await?;
+    let reachable = if through_link {
+        // Off the async worker: resolving a root is a blocking call, and a
+        // hung network mount would otherwise hold the worker with it.
+        let (link_roots, policy, target) =
+            (link_roots.clone(), policy.clone(), canonical_file.clone());
+        tokio::task::spawn_blocking(move || {
+            crate::link_roots::admits(
+                &link_roots.resolved(),
+                &policy.other_libraries_resolved(),
+                &target,
+            )
+        })
+        .await
+        .map_err(io::Error::other)?
+    } else {
+        canonical_file.starts_with(&canonical_root)
+    };
+    if !reachable || !tokio::fs::metadata(&canonical_file).await?.is_file() {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "media path escapes library",
+        ));
+    }
+    Ok(canonical_file)
+}
+
+pub(super) async fn serve_file(
+    path: &Path,
+    range: Option<&str>,
+    mime: &'static str,
+) -> Result<Response, MediaError> {
+    let file = tokio::fs::File::open(path)
+        .await
+        .map_err(|_| MediaError::NotFound)?;
+    let size = file
+        .metadata()
+        .await
+        .map_err(|_| MediaError::NotFound)?
+        .len();
+    match range {
+        Some(range) => {
+            let (start, end) =
+                parse_range(range, size).ok_or(MediaError::RangeNotSatisfiable(Some(size)))?;
+            serve_partial(file, start, end, size, mime).await
+        }
+        None => {
+            let mut response = Response::new(Body::from_stream(ReaderStream::new(file)));
+            *response.status_mut() = StatusCode::OK;
+            response
+                .headers_mut()
+                .insert(header::CONTENT_TYPE, HeaderValue::from_static(mime));
+            response.headers_mut().insert(
+                header::CONTENT_LENGTH,
+                HeaderValue::from_str(&size.to_string()).map_err(|_| MediaError::Internal)?,
+            );
+            response
+                .headers_mut()
+                .insert(header::ACCEPT_RANGES, HeaderValue::from_static("bytes"));
+            response.headers_mut().insert(
+                header::CACHE_CONTROL,
+                HeaderValue::from_static(MEDIA_CACHE_CONTROL),
+            );
+            Ok(response)
+        }
+    }
+}
+
+async fn serve_partial(
+    mut file: tokio::fs::File,
+    start: u64,
+    end: u64,
+    size: u64,
+    mime: &'static str,
+) -> Result<Response, MediaError> {
+    file.seek(std::io::SeekFrom::Start(start))
+        .await
+        .map_err(|_| MediaError::Internal)?;
+    let length = end - start + 1;
+    let stream = ReaderStream::new(file.take(length));
+    let mut response = Response::new(Body::from_stream(stream));
+    *response.status_mut() = StatusCode::PARTIAL_CONTENT;
+    let headers = response.headers_mut();
+    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static(mime));
+    headers.insert(
+        header::CONTENT_LENGTH,
+        HeaderValue::from_str(&length.to_string()).map_err(|_| MediaError::Internal)?,
+    );
+    headers.insert(header::ACCEPT_RANGES, HeaderValue::from_static("bytes"));
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static(MEDIA_CACHE_CONTROL),
+    );
+    headers.insert(
+        header::CONTENT_RANGE,
+        HeaderValue::from_str(&format!("bytes {start}-{end}/{size}"))
+            .map_err(|_| MediaError::Internal)?,
+    );
+    Ok(response)
+}
+
+/// Whether a `Range` header starts at the first byte, which is how a player
+/// opens a resource rather than how it seeks into one. Browsers send `bytes=0-`;
+/// iOS AVFoundation first probes with `bytes=0-1` to learn the size and type.
+/// Both mean "begin here", and neither can be refused without breaking the
+/// first play of every track.
+///
+/// The answer to such a request is the whole stream rather than the bytes
+/// asked for, which HTTP allows: a server may always ignore `Range` and answer
+/// 200. Before the transcode exists there is no total length to put in a
+/// `Content-Range`, so a partial answer is not available to give.
+pub(super) fn starts_at_the_first_byte(value: &str) -> bool {
+    value.strip_prefix("bytes=").is_some_and(|spec| {
+        // A multipart range is several ranges, and this answers with one body.
+        let Some((start, end)) = spec.trim().split_once('-') else {
+            return false;
+        };
+        start.trim().parse::<u64>() == Ok(0)
+            // A malformed end - a second hyphen, a word - is not a range this
+            // understands, so it is refused rather than read as an open.
+            && (end.trim().is_empty() || end.trim().parse::<u64>().is_ok())
+    })
+}
+
+pub(super) fn parse_range(value: &str, size: u64) -> Option<(u64, u64)> {
+    if size == 0 {
+        return None;
+    }
+    let value = value.strip_prefix("bytes=")?;
+    if value.contains(',') {
+        return None;
+    }
+    let (start, end) = value.trim().split_once('-')?;
+    // Trimmed on both bounds, like `starts_at_the_first_byte`: a spelling the
+    // cold path accepts must not be refused once the cache exists.
+    let (start, end) = (start.trim(), end.trim());
+    if start.is_empty() {
+        let suffix = end.parse::<u64>().ok()?.min(size).min(MAX_RANGE_BYTES);
+        if suffix == 0 {
+            return None;
+        }
+        return Some((size - suffix, size - 1));
+    }
+    let start = start.parse::<u64>().ok()?;
+    if start >= size {
+        return None;
+    }
+    let requested_end = if end.is_empty() {
+        size - 1
+    } else {
+        end.parse::<u64>().ok()?.min(size - 1)
+    };
+    if requested_end < start {
+        return None;
+    }
+    Some((start, requested_end.min(start + MAX_RANGE_BYTES - 1)))
+}
+
+fn validate_bitrate(format: OutputFormat, bitrate: Option<u32>) -> Result<u32, MediaError> {
+    let bitrate = bitrate.unwrap_or(match format {
+        OutputFormat::Mp3 => 192,
+        OutputFormat::Opus => 128,
+        OutputFormat::Aac => 192,
+        OutputFormat::Raw => return Err(MediaError::InvalidRequest),
+    });
+    if !(32..=512).contains(&bitrate) {
+        return Err(MediaError::InvalidRequest);
+    }
+    Ok(bitrate)
+}
+
+fn mime_for_path(path: &Path) -> &'static str {
+    match path
+        .extension()
+        .and_then(OsStr::to_str)
+        .unwrap_or_default()
+        .to_ascii_lowercase()
+        .as_str()
+    {
+        "mp3" => "audio/mpeg",
+        "flac" => "audio/flac",
+        "wav" => "audio/wav",
+        "ogg" | "oga" | "opus" => "audio/ogg",
+        "m4a" | "mp4" => "audio/mp4",
+        "aac" => "audio/aac",
+        "dsf" | "dff" => "audio/dsd",
+        _ => "application/octet-stream",
+    }
+}
diff --git a/src/media/tests.rs b/src/media/tests.rs
new file mode 100644
index 00000000..781d3c47
--- /dev/null
+++ b/src/media/tests.rs
@@ -0,0 +1,458 @@
+//! Unit tests of the media service: byte ranges, media paths, the transcode
+//! cache, and what FFmpeg may open.
+
+use std::{
+    path::PathBuf,
+    sync::Arc,
+    time::{Duration, SystemTime},
+};
+
+use dashmap::DashMap;
+use tokio::sync::{Mutex, Semaphore};
+
+use super::{
+    attachment, secure_track_path,
+    stream::{parse_range, starts_at_the_first_byte},
+    transcode::{cache_key, prune_cache},
+    MediaInner, MediaService, OutputFormat,
+};
+
+/// A download's name in both forms, whatever it holds.
+///
+/// The fallback is what an old browser builds a path from, so a quote, a
+/// backslash, a separator or anything outside ASCII must not survive in
+/// it; `filename*` must carry the real name, accents and all.
+#[test]
+fn a_download_name_is_safe_in_both_forms() {
+    let header = attachment("Björk - Hyperballad \"live\" 1/2\\3.flac");
+    let header = header.to_str().unwrap();
+    assert_eq!(
+        header,
+        "attachment; filename=\"Bj_rk - Hyperballad _live_ 1_2_3.flac\"; \
+         filename*=UTF-8''Bj%C3%B6rk%20-%20Hyperballad%20%22live%22%201_2_3.flac"
+    );
+    // A control character is no part of a name.
+    let header = attachment("a\nb.flac");
+    assert!(
+        header
+            .to_str()
+            .unwrap()
+            .starts_with("attachment; filename=\"a_b.flac\""),
+        "{header:?}"
+    );
+}
+
+#[test]
+fn ranges_are_bounded_and_validated() {
+    assert_eq!(parse_range("bytes=2-5", 10), Some((2, 5)));
+    assert_eq!(parse_range("bytes=8-", 10), Some((8, 9)));
+    assert_eq!(parse_range("bytes=-3", 10), Some((7, 9)));
+    assert_eq!(parse_range("bytes=10-", 10), None);
+    assert_eq!(parse_range("bytes=5-2", 10), None);
+    assert_eq!(parse_range("bytes=0-1,4-5", 10), None);
+    // Whitespace is tolerated on both bounds, so that a range the cold
+    // transcode path accepts is still satisfiable from the cache.
+    assert_eq!(parse_range("bytes= 0- ", 10), Some((0, 9)));
+    assert_eq!(parse_range("bytes= 2 - 5 ", 10), Some((2, 5)));
+}
+
+#[test]
+fn a_range_from_the_first_byte_opens_a_resource() {
+    // How a browser opens an audio element, and how iOS probes one.
+    assert!(starts_at_the_first_byte("bytes=0-"));
+    assert!(starts_at_the_first_byte("bytes=0-1"));
+    assert!(starts_at_the_first_byte("bytes=0-1023"));
+    assert!(starts_at_the_first_byte("bytes= 0- "));
+    // Starting anywhere else is a seek, and has no meaning yet.
+    assert!(!starts_at_the_first_byte("bytes=1-"));
+    assert!(!starts_at_the_first_byte("bytes=19924-429882"));
+    assert!(!starts_at_the_first_byte("bytes=-3"));
+    // One body cannot answer several ranges.
+    assert!(!starts_at_the_first_byte("bytes=0-1,4-5"));
+    assert!(!starts_at_the_first_byte("items=0-"));
+    assert!(!starts_at_the_first_byte("bytes=00x-1"));
+    // A malformed end is not an open either.
+    assert!(!starts_at_the_first_byte("bytes=0-1-2"));
+    assert!(!starts_at_the_first_byte("bytes=0-invalid"));
+}
+
+#[tokio::test]
+async fn media_paths_reject_parent_components_and_symlinks() {
+    let temp = tempfile::tempdir().unwrap();
+    let root = temp.path().join("library");
+    std::fs::create_dir_all(&root).unwrap();
+    std::fs::write(root.join("safe.wav"), b"audio").unwrap();
+    let none = crate::link_roots::LinkRoots::default();
+    let policy = crate::link_roots::LinkPolicy::default();
+    assert!(secure_track_path(&root, "safe.wav", &none, &policy)
+        .await
+        .is_ok());
+    assert!(secure_track_path(&root, "../safe.wav", &none, &policy)
+        .await
+        .is_err());
+
+    let link = root.join("linked.wav");
+    #[cfg(unix)]
+    let linked = std::os::unix::fs::symlink(root.join("safe.wav"), &link).is_ok();
+    #[cfg(windows)]
+    let linked = std::os::windows::fs::symlink_file(root.join("safe.wav"), &link).is_ok();
+    if linked {
+        assert!(secure_track_path(&root, "linked.wav", &none, &policy)
+            .await
+            .is_err());
+    }
+}
+
+/// A stored path through a link is accepted only when its library follows
+/// links and it resolves, now, into an allowed folder outside the root
+/// and into no other library (RFC-021, links outside the root): not into
+/// the root itself, not anywhere else, not into another library's root
+/// inside the allowed folder, not once the folder is no longer allowed,
+/// and not once the library stopped following links.
+#[tokio::test]
+async fn a_link_is_followed_into_an_allowed_folder_only() {
+    let temp = tempfile::tempdir().unwrap();
+    let root = temp.path().join("library");
+    let farm = temp.path().join("farm");
+    let neighbour = farm.join("neighbour");
+    let elsewhere = temp.path().join("elsewhere");
+    for folder in [&root, &farm, &neighbour, &elsewhere] {
+        std::fs::create_dir_all(folder).unwrap();
+    }
+    std::fs::write(farm.join("kept.wav"), b"audio").unwrap();
+    std::fs::write(neighbour.join("theirs.wav"), b"audio").unwrap();
+    std::fs::write(elsewhere.join("secret.wav"), b"audio").unwrap();
+    std::fs::write(root.join("own.wav"), b"audio").unwrap();
+    #[cfg(unix)]
+    let make = |target: &std::path::Path, link: &std::path::Path| {
+        std::os::unix::fs::symlink(target, link).is_ok()
+    };
+    #[cfg(windows)]
+    let make = |target: &std::path::Path, link: &std::path::Path| {
+        std::os::windows::fs::symlink_file(target, link).is_ok()
+    };
+    if !(make(&farm.join("kept.wav"), &root.join("farmed.wav"))
+        && make(&neighbour.join("theirs.wav"), &root.join("crossing.wav"))
+        && make(&elsewhere.join("secret.wav"), &root.join("stolen.wav"))
+        && make(&root.join("own.wav"), &root.join("mine.wav")))
+    {
+        eprintln!("skipped: this system will not let the test make a symbolic link");
+        return;
+    }
+    let allowed = crate::link_roots::LinkRoots::new(vec![farm.clone()]);
+    let following = crate::link_roots::LinkPolicy {
+        follow_links: true,
+        other_libraries: vec![neighbour.clone()],
+    };
+    assert!(secure_track_path(&root, "farmed.wav", &allowed, &following)
+        .await
+        .is_ok());
+    assert!(
+        secure_track_path(&root, "crossing.wav", &allowed, &following)
+            .await
+            .is_err(),
+        "another library's file is never reached through a link"
+    );
+    assert!(secure_track_path(&root, "stolen.wav", &allowed, &following)
+        .await
+        .is_err());
+    assert!(
+        secure_track_path(&root, "mine.wav", &allowed, &following)
+            .await
+            .is_err(),
+        "a link inside the root is stored by its target, never by itself"
+    );
+    let none = crate::link_roots::LinkRoots::default();
+    assert!(secure_track_path(&root, "farmed.wav", &none, &following)
+        .await
+        .is_err());
+    let not_following = crate::link_roots::LinkPolicy {
+        follow_links: false,
+        ..following
+    };
+    assert!(
+        secure_track_path(&root, "farmed.wav", &allowed, &not_following)
+            .await
+            .is_err(),
+        "a library that does not follow links reads no link, allowlist or not"
+    );
+}
+
+#[tokio::test]
+async fn cache_pruning_removes_the_least_recently_used_file() {
+    let temp = tempfile::tempdir().unwrap();
+    let old = temp.path().join("old.mp3");
+    let recent = temp.path().join("recent.mp3");
+    std::fs::write(&old, b"1234").unwrap();
+    std::fs::write(&recent, b"5678").unwrap();
+    let access = DashMap::new();
+    access.insert(old.clone(), SystemTime::UNIX_EPOCH);
+    access.insert(recent.clone(), SystemTime::now());
+    let inner = MediaInner {
+        ffmpeg: PathBuf::from("ffmpeg"),
+        ffprobe: PathBuf::from("ffprobe"),
+        cache_dir: temp.path().to_path_buf(),
+        cache_max_bytes: 4,
+        global: Arc::new(Semaphore::new(1)),
+        global_limit: 1,
+        per_user_limit: 1,
+        users: DashMap::new(),
+        cache_locks: DashMap::new(),
+        cache_access: access,
+        pending_fills: dashmap::DashSet::new(),
+        active_transcodes: std::sync::atomic::AtomicUsize::new(0),
+        transcoding_available: true,
+        ffmpeg_digest: String::new(),
+        link_roots: crate::link_roots::LinkRoots::default(),
+        subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
+    };
+    prune_cache(&inner).await;
+    assert!(!old.exists());
+    assert!(recent.exists());
+}
+
+/// The fill behind a seek neither waits on the cache lock nor gives up on
+/// it. The play a seek abandons still holds that lock for the moment it
+/// takes to notice its consumer is gone, and the seek lands inside that
+/// moment. No integration test can arrange that instant; a test inside the
+/// module can, by holding the lock itself the way the dying play does.
+#[tokio::test]
+async fn a_seek_fills_the_cache_while_the_abandoned_play_still_holds_its_lock() {
+    let temp = tempfile::tempdir().unwrap();
+    let mut config = crate::Config::for_data_dir(temp.path().join("data"));
+    config.transcode_global_limit = 4;
+    let media = MediaService::initialize(&config).await.unwrap();
+    let source = temp.path().join("track.wav");
+    silent_wav(&source, 2);
+
+    let key = cache_key("abandoned", OutputFormat::Mp3, 96, None);
+    let cache_path = media.inner.cache_dir.join(format!("{key}.mp3"));
+    let lock = media
+        .inner
+        .cache_locks
+        .entry(key.clone())
+        .or_insert_with(|| Arc::new(Mutex::new(())))
+        .clone();
+    let _held = lock.lock_owned().await;
+
+    media.fill_cache_behind_a_seek(
+        source,
+        OutputFormat::Mp3,
+        96,
+        None,
+        key,
+        cache_path.clone(),
+        Duration::from_secs(60),
+    );
+    assert_eq!(
+        media.active_transcodes(),
+        1,
+        "the fill must start while the lock is held"
+    );
+    for _ in 0..3_000 {
+        if media.active_transcodes() == 0 {
+            break;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+    }
+    assert_eq!(
+        media.active_transcodes(),
+        0,
+        "the fill must not wait for the lock"
+    );
+    assert!(
+        cache_path.exists(),
+        "the fill must commit the whole transcode"
+    );
+}
+
+/// A fill has no listener who can leave, so nothing else ends an encode
+/// that never finishes. Past its deadline FFmpeg is killed, and neither a
+/// cache file, nor a staging file, nor the key's claim is left behind —
+/// the slot and the key are free for the next seek.
+#[tokio::test]
+async fn a_cache_fill_past_its_deadline_is_killed_and_leaves_nothing() {
+    let temp = tempfile::tempdir().unwrap();
+    let mut config = crate::Config::for_data_dir(temp.path().join("data"));
+    config.transcode_global_limit = 4;
+    let media = MediaService::initialize(&config).await.unwrap();
+    let source = temp.path().join("track.wav");
+    silent_wav(&source, 30);
+
+    let key = cache_key("overdue", OutputFormat::Mp3, 96, None);
+    let cache_path = media.inner.cache_dir.join(format!("{key}.mp3"));
+    // A millisecond: less than FFmpeg takes to start, let alone to finish.
+    media.fill_cache_behind_a_seek(
+        source,
+        OutputFormat::Mp3,
+        96,
+        None,
+        key,
+        cache_path.clone(),
+        Duration::from_millis(1),
+    );
+    assert_eq!(media.active_transcodes(), 1);
+    for _ in 0..3_000 {
+        if media.active_transcodes() == 0 {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    assert_eq!(
+        media.active_transcodes(),
+        0,
+        "an overdue fill must give its slot back"
+    );
+    assert!(!cache_path.exists(), "an overdue fill must not commit");
+    let staged = std::fs::read_dir(&media.inner.cache_dir)
+        .unwrap()
+        .filter_map(Result::ok)
+        .any(|entry| entry.file_name().to_string_lossy().contains(".part-"));
+    assert!(!staged, "an overdue fill must remove its staging file");
+    assert!(
+        media.inner.pending_fills.is_empty(),
+        "an overdue fill must free its key for the next seek"
+    );
+}
+
+/// A listener on loopback that counts the connections it is offered and
+/// closes each at once: what "nothing was fetched" is measured with.
+pub(crate) async fn counting_listener() -> (
+    std::net::SocketAddr,
+    Arc<std::sync::atomic::AtomicUsize>,
+    tokio::task::JoinHandle<()>,
+) {
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let address = listener.local_addr().unwrap();
+    let count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+    let counted = Arc::clone(&count);
+    let task = tokio::spawn(async move {
+        while let Ok((socket, _)) = listener.accept().await {
+            counted.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            drop(socket);
+        }
+    });
+    (address, count, task)
+}
+
+fn a_media_service(dir: &std::path::Path) -> MediaService {
+    MediaService {
+        inner: Arc::new(MediaInner {
+            ffmpeg: PathBuf::from("ffmpeg"),
+            ffprobe: PathBuf::from("ffprobe"),
+            cache_dir: dir.to_path_buf(),
+            cache_max_bytes: 0,
+            global: Arc::new(Semaphore::new(1)),
+            global_limit: 1,
+            per_user_limit: 1,
+            users: DashMap::new(),
+            cache_locks: DashMap::new(),
+            cache_access: DashMap::new(),
+            pending_fills: dashmap::DashSet::new(),
+            active_transcodes: std::sync::atomic::AtomicUsize::new(0),
+            transcoding_available: true,
+            ffmpeg_digest: String::new(),
+            link_roots: crate::link_roots::LinkRoots::default(),
+            subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
+        }),
+    }
+}
+
+/// Runs the transcode FFmpeg would be given for `source`, to nowhere, and
+/// answers whether it succeeded.
+async fn transcode(media: &MediaService, source: &std::path::Path) -> bool {
+    let mut command = media
+        .transcode_command(source, OutputFormat::Mp3, 128, None, 0)
+        .unwrap();
+    command
+        .arg("pipe:1")
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .kill_on_drop(true);
+    tokio::time::timeout(Duration::from_secs(60), command.status())
+        .await
+        .expect("ffmpeg must not hang on an input it refuses")
+        .expect("ffmpeg must be on PATH")
+        .success()
+}
+
+/// FFmpeg opens files and nothing else, whatever the input names
+/// (RFC-023 decision 2).
+///
+/// Three inputs, one property:
+///
+/// - **A path that is a URL.** Without the whitelist FFmpeg connects to
+///   it; this is the case that tells the whitelist from its absence.
+/// - **A playlist that names one.** An HLS playlist pointing at the same
+///   listener. FFmpeg 8 already refuses `http` from inside a file opened
+///   through `file` (its default nested list is `file,crypto,data`), so
+///   this one holds on that build either way: it is here so the property
+///   stays tested on a build whose default is wider.
+/// - **A `concat:` URL** of two real files, which the default decodes.
+///
+/// And one control: the same command plays a real file, so the whitelist
+/// is proved not to be in the way of the one protocol the server uses —
+/// on Windows too, where a path starts with a drive letter and a colon.
+#[tokio::test]
+async fn ffmpeg_opens_files_and_nothing_else() {
+    let temp = tempfile::tempdir().unwrap();
+    let media = a_media_service(temp.path());
+    let real = temp.path().join("real.wav");
+    silent_wav(&real, 1);
+    assert!(
+        transcode(&media, &real).await,
+        "a real file must still play"
+    );
+
+    let (address, connections, listener) = counting_listener().await;
+    let url = format!("http://{address}/track.mp3");
+    assert!(!transcode(&media, std::path::Path::new(&url)).await);
+
+    let playlist = temp.path().join("trap.m3u8");
+    std::fs::write(
+        &playlist,
+        format!(
+            "#EXTM3U\n#EXT-X-TARGETDURATION:1\n#EXTINF:1,\nhttp://{address}/segment.mp3\n#EXT-X-ENDLIST\n"
+        ),
+    )
+    .unwrap();
+    assert!(!transcode(&media, &playlist).await);
+
+    let concat = format!("concat:{}|{}", real.display(), real.display());
+    assert!(
+        !transcode(&media, std::path::Path::new(&concat)).await,
+        "a concat: input must be refused"
+    );
+
+    // Connections are counted as they are accepted; give the last one
+    // the moment it needs to land before reading the count.
+    tokio::time::sleep(Duration::from_millis(200)).await;
+    listener.abort();
+    assert_eq!(
+        connections.load(std::sync::atomic::Ordering::SeqCst),
+        0,
+        "ffmpeg must not have contacted anything"
+    );
+}
+
+/// Silence at 8 kHz, as long as asked.
+pub(crate) fn silent_wav(path: &std::path::Path, seconds: u32) {
+    let generated = std::process::Command::new("ffmpeg")
+        .args([
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=r=8000:cl=mono",
+            "-t",
+        ])
+        .arg(seconds.to_string())
+        .arg(path)
+        .status()
+        .expect("ffmpeg must be on PATH");
+    assert!(generated.success());
+}
diff --git a/src/media/transcode.rs b/src/media/transcode.rs
new file mode 100644
index 00000000..94577dcd
--- /dev/null
+++ b/src/media/transcode.rs
@@ -0,0 +1,493 @@
+//! The transcode cache: the FFmpeg command, the live transcode that fills the
+//! cache from the first byte, the fill behind a seek, and the pruning pass.
+
+use std::{
+    collections::HashMap,
+    ffi::OsStr,
+    io,
+    path::{Path, PathBuf},
+    process::Stdio,
+    sync::{
+        atomic::{AtomicUsize, Ordering},
+        Arc,
+    },
+    time::{Duration, SystemTime},
+};
+
+use axum::{
+    body::Body,
+    http::{header, StatusCode},
+    response::{IntoResponse, Response},
+};
+use bytes::Bytes;
+use tokio::{
+    io::{AsyncReadExt, AsyncWriteExt},
+    process::Command,
+    sync::{mpsc, Semaphore},
+};
+use tokio_stream::wrappers::ReceiverStream;
+use uuid::Uuid;
+
+use super::{file_input, MediaError, MediaInner, MediaService, OutputFormat, MEDIA_CACHE_CONTROL};
+use crate::replay_gain::Gain;
+
+const STREAM_CHUNK_SIZE: usize = 64 * 1024;
+const TRANSCODE_PROFILE_VERSION: &str = "waveflow-ffmpeg-v1";
+
+impl MediaService {
+    /// The FFmpeg invocation for a transcode, up to where its output goes.
+    ///
+    /// Shared by the live stream, which sends it to a pipe, and the cache fill
+    /// behind a seek, which sends it to a file. Two copies of these arguments
+    /// would drift apart the day one of them changed, and the cache would start
+    /// holding a different encode from the one its key names.
+    pub(super) fn transcode_command(
+        &self,
+        source: &Path,
+        format: OutputFormat,
+        bitrate: u32,
+        gain: Option<Gain>,
+        offset_ms: u64,
+    ) -> Result<Command, MediaError> {
+        let mut command = Command::new(&self.inner.ffmpeg);
+        command.arg("-hide_banner").arg("-loglevel").arg("error");
+        if offset_ms > 0 {
+            command
+                .arg("-ss")
+                .arg(format!("{:.3}", offset_ms as f64 / 1000.0));
+        }
+        file_input(&mut command, source).args(["-vn", "-map_metadata", "-1"]);
+        if let Some(gain) = gain {
+            command.arg("-af").arg(gain.filter());
+        }
+        let bitrate_arg = format!("{bitrate}k");
+        match format {
+            OutputFormat::Mp3 => {
+                command.args(["-c:a", "libmp3lame", "-b:a", &bitrate_arg, "-f", "mp3"]);
+            }
+            OutputFormat::Opus => {
+                command.args([
+                    "-c:a",
+                    "libopus",
+                    "-b:a",
+                    &bitrate_arg,
+                    "-vbr",
+                    "on",
+                    "-f",
+                    "ogg",
+                ]);
+            }
+            OutputFormat::Aac => {
+                // FFmpeg's own encoder, which every build has: `libfdk_aac` is
+                // better at low rates and missing from most builds, since its
+                // licence is not GPL-compatible.
+                command.args(["-c:a", "aac", "-b:a", &bitrate_arg, "-f", "adts"]);
+            }
+            OutputFormat::Raw => return Err(MediaError::InvalidRequest),
+        }
+        Ok(command)
+    }
+
+    /// Transcodes the whole track into the cache, behind a seek into a live
+    /// transcode of it. Issue #185.
+    ///
+    /// Seeking a live transcode goes through `offset_ms`, and asking for it is
+    /// the very act that abandons the offset-0 stream: the only one allowed to
+    /// fill the cache, and one whose departure kills its encoder and deletes its
+    /// partial file. The stream replacing it is not the whole track and is not
+    /// cached. Without this, a track seeked on its first play stayed a live
+    /// transcode on every later play, without byte ranges, so the client seeked
+    /// through `offset_ms` again and abandoned the stream again.
+    ///
+    /// **Below anything a listener is waiting on.** It starts only when it can
+    /// take a global slot and still leave one free, so it never turns a live
+    /// request into a 429, and it never counts against the account's own limit,
+    /// which the seek itself is holding. Without that room it does nothing, and
+    /// the next seek asks again.
+    ///
+    /// **Outside the cache lock.** The play a seek abandons still holds that
+    /// lock for the moment it takes to notice its consumer is gone, and the seek
+    /// lands inside that moment: waiting for the lock or giving up on it would
+    /// both miss the one case this is for. A second writer of the same key costs
+    /// an encode and nothing worse — each writes its own staging file, and the
+    /// one that finds the cache already there discards its own.
+    ///
+    /// **Bounded by `deadline`.** A live stream ends when its listener leaves;
+    /// a fill has no listener, so without a deadline an encode that never
+    /// finished would hold its slot and its key until the server restarted.
+    /// Past it, FFmpeg is killed and nothing it wrote is kept.
+    #[allow(clippy::too_many_arguments)]
+    pub(super) fn fill_cache_behind_a_seek(
+        &self,
+        source: PathBuf,
+        format: OutputFormat,
+        bitrate: u32,
+        gain: Option<Gain>,
+        key: String,
+        cache_path: PathBuf,
+        deadline: Duration,
+    ) {
+        if !self.inner.pending_fills.insert(key.clone()) {
+            return;
+        }
+        // Released on every way out from here on, the refusals included, so a
+        // fill that could not start never stops the next seek from asking.
+        let pending = PendingFill {
+            inner: Arc::clone(&self.inner),
+            key,
+        };
+        // Two permits in one step and one handed straight back: a slot, with
+        // another still free after it. Checking for two and then taking one
+        // would leave a gap in which a second fill takes the last.
+        let Ok(mut global) = Arc::clone(&self.inner.global).try_acquire_many_owned(2) else {
+            return;
+        };
+        drop(global.split(1));
+        let Ok(mut command) = self.transcode_command(&source, format, bitrate, gain, 0) else {
+            return;
+        };
+        let staging = staging_path(&cache_path);
+        command
+            .arg("-y")
+            .arg(&staging)
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .kill_on_drop(true);
+        let inner = Arc::clone(&self.inner);
+        inner.active_transcodes.fetch_add(1, Ordering::Relaxed);
+
+        tokio::spawn(async move {
+            // Declared in this order so they drop in the reverse one: the key
+            // and the slot are given back before the count reaches zero, so a
+            // caller waiting on the count finds all three released.
+            let _active = ActiveGuard(&inner.active_transcodes);
+            let _global = global;
+            let _pending = pending;
+            let mut child = match command.spawn() {
+                Ok(child) => child,
+                Err(error) => {
+                    tracing::warn!(error = %error, "failed to spawn ffmpeg for a cache fill");
+                    return;
+                }
+            };
+            let finished = match tokio::time::timeout(deadline, child.wait()).await {
+                Ok(status) => status.is_ok_and(|status| status.success()),
+                // Killed and awaited before its staging file is removed: a file
+                // a live process still holds cannot be deleted on Windows.
+                Err(_) => {
+                    let _ = child.kill().await;
+                    false
+                }
+            };
+            if !finished {
+                tracing::warn!(
+                    path = %source.display(),
+                    "ffmpeg cache fill failed or ran past its deadline"
+                );
+                let _ = tokio::fs::remove_file(&staging).await;
+                return;
+            }
+            // A play from the start may have committed the same key meanwhile.
+            // Its file is as good as this one, and replacing a file a reader
+            // may be streaming from is not a write worth making.
+            if tokio::fs::try_exists(&cache_path).await.unwrap_or(false) {
+                let _ = tokio::fs::remove_file(&staging).await;
+                return;
+            }
+            if let Err(error) = tokio::fs::rename(&staging, &cache_path).await {
+                tracing::warn!(error = %error, "transcode cache fill could not be committed");
+                let _ = tokio::fs::remove_file(&staging).await;
+                return;
+            }
+            inner.cache_access.insert(cache_path, SystemTime::now());
+            prune_cache(&inner).await;
+        });
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub(super) async fn stream_transcode(
+        &self,
+        user_id: Uuid,
+        source: PathBuf,
+        format: OutputFormat,
+        bitrate: u32,
+        gain: Option<Gain>,
+        offset_ms: u64,
+        cache: Option<(PathBuf, tokio::sync::OwnedMutexGuard<()>)>,
+    ) -> Result<Response, MediaError> {
+        let global = Arc::clone(&self.inner.global)
+            .try_acquire_owned()
+            .map_err(|_| MediaError::Busy)?;
+        let user_semaphore = self
+            .inner
+            .users
+            .entry(user_id)
+            .or_insert_with(|| Arc::new(Semaphore::new(self.inner.per_user_limit)))
+            .clone();
+        let user = user_semaphore
+            .try_acquire_owned()
+            .map_err(|_| MediaError::Busy)?;
+
+        let mut command = self.transcode_command(&source, format, bitrate, gain, offset_ms)?;
+        command
+            .arg("pipe:1")
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .kill_on_drop(true);
+        let mut child = command.spawn().map_err(|error| {
+            tracing::error!(error = %error, "failed to spawn ffmpeg");
+            MediaError::Internal
+        })?;
+        let mut stdout = child.stdout.take().ok_or(MediaError::Internal)?;
+        let (sender, receiver) = mpsc::channel::<Result<Bytes, io::Error>>(8);
+        let inner = Arc::clone(&self.inner);
+        inner.active_transcodes.fetch_add(1, Ordering::Relaxed);
+
+        tokio::spawn(async move {
+            let _global = global;
+            let _user = user;
+            let _active = ActiveGuard(&inner.active_transcodes);
+            let (cache_path, _cache_guard) = match cache {
+                Some((path, guard)) => (Some(path), Some(guard)),
+                None => (None, None),
+            };
+            let temp_path = cache_path.as_deref().map(staging_path);
+            let mut cache_file = match temp_path.as_ref() {
+                Some(path) => match tokio::fs::File::create(path).await {
+                    Ok(file) => Some(file),
+                    Err(error) => {
+                        tracing::warn!(error = %error, path = %path.display(), "transcode cache write disabled for request");
+                        None
+                    }
+                },
+                None => None,
+            };
+            let mut buffer = vec![0u8; STREAM_CHUNK_SIZE];
+            let mut consumer_present = true;
+            loop {
+                // Watch for the consumer leaving alongside the read instead of
+                // only noticing on the next send. FFmpeg can sit on a chunk for
+                // a long time under load, and until it yields one there is
+                // nothing to fail on, so an abandoned transcode would hold a
+                // process and a concurrency slot for as long as the encode took.
+                // Both branches are cancel-safe, and `biased` checks departure
+                // first so a consumer that left during the read is seen at once.
+                let read = tokio::select! {
+                    biased;
+                    _ = sender.closed() => {
+                        consumer_present = false;
+                        break;
+                    }
+                    result = stdout.read(&mut buffer) => result,
+                };
+                match read {
+                    Ok(0) => break,
+                    Ok(read) => {
+                        if let Some(file) = cache_file.as_mut() {
+                            if let Err(error) = file.write_all(&buffer[..read]).await {
+                                tracing::warn!(error = %error, "transcode cache write failed");
+                                cache_file = None;
+                            }
+                        }
+                        if sender
+                            .send(Ok(Bytes::copy_from_slice(&buffer[..read])))
+                            .await
+                            .is_err()
+                        {
+                            consumer_present = false;
+                            break;
+                        }
+                    }
+                    Err(error) => {
+                        let _ = sender.send(Err(error)).await;
+                        consumer_present = false;
+                        break;
+                    }
+                }
+            }
+
+            if !consumer_present {
+                let _ = child.kill().await;
+                if let Some(path) = temp_path.as_ref() {
+                    let _ = tokio::fs::remove_file(path).await;
+                }
+                return;
+            }
+            let success = child
+                .wait()
+                .await
+                .map(|status| status.success())
+                .unwrap_or(false);
+            if success {
+                if let Some(mut file) = cache_file {
+                    if file.flush().await.is_ok() {
+                        drop(file);
+                        if let (Some(temp), Some(final_path)) =
+                            (temp_path.as_ref(), cache_path.as_ref())
+                        {
+                            if tokio::fs::rename(temp, final_path).await.is_ok() {
+                                inner
+                                    .cache_access
+                                    .insert(final_path.clone(), SystemTime::now());
+                                prune_cache(&inner).await;
+                            }
+                        }
+                    }
+                } else if let Some(path) = temp_path.as_ref() {
+                    let _ = tokio::fs::remove_file(path).await;
+                }
+            } else {
+                tracing::warn!(path = %source.display(), "ffmpeg transcode failed");
+                if let Some(path) = temp_path.as_ref() {
+                    let _ = tokio::fs::remove_file(path).await;
+                }
+            }
+        });
+
+        let body = Body::from_stream(ReceiverStream::new(receiver));
+        Ok((
+            StatusCode::OK,
+            [
+                (header::CONTENT_TYPE, mime_for_format(format)),
+                (header::CACHE_CONTROL, MEDIA_CACHE_CONTROL),
+                (header::ACCEPT_RANGES, "none"),
+            ],
+            body,
+        )
+            .into_response())
+    }
+}
+
+/// Releases a key's claim on the cache fill however the fill ends, so one that
+/// failed or never started does not stop the next seek from asking again.
+struct PendingFill {
+    inner: Arc<MediaInner>,
+    key: String,
+}
+
+impl Drop for PendingFill {
+    fn drop(&mut self) {
+        self.inner.pending_fills.remove(&self.key);
+    }
+}
+
+struct ActiveGuard<'a>(&'a AtomicUsize);
+
+impl Drop for ActiveGuard<'_> {
+    fn drop(&mut self) {
+        self.0.fetch_sub(1, Ordering::Relaxed);
+    }
+}
+
+/// How far past the track's own length a cache fill may run.
+///
+/// Encodes run many times faster than the music, so the track's length is
+/// already a generous bound, and a fill slower than that has stopped being a
+/// background job on a server with other work. The minute covers FFmpeg
+/// starting on a busy machine, and a track whose length the scan did not learn.
+const FILL_DEADLINE_MARGIN: Duration = Duration::from_secs(60);
+
+/// The deadline a cache fill of a track this long runs under.
+pub(super) fn fill_deadline(duration_ms: i64) -> Duration {
+    Duration::from_millis(u64::try_from(duration_ms).unwrap_or(0))
+        .saturating_add(FILL_DEADLINE_MARGIN)
+}
+
+/// Where a transcode is written before it is whole, beside the name it will
+/// take. The pruning pass skips `.part-`, and the suffix is unique, so two
+/// writers of one key never share a file.
+fn staging_path(cache_path: &Path) -> PathBuf {
+    cache_path.with_extension(format!(
+        "{}.part-{}",
+        cache_path
+            .extension()
+            .and_then(OsStr::to_str)
+            .unwrap_or("cache"),
+        Uuid::new_v4()
+    ))
+}
+
+pub(super) fn cache_key(
+    source_hash: &str,
+    format: OutputFormat,
+    bitrate: u32,
+    gain: Option<Gain>,
+) -> String {
+    // A gain is named only when there is one, so every key written before
+    // ReplayGain existed is still the key of the same encode.
+    let gain = gain
+        .map(|gain| format!(":{}", gain.key()))
+        .unwrap_or_default();
+    blake3::hash(
+        format!("{source_hash}:{format:?}:{bitrate}:{TRANSCODE_PROFILE_VERSION}{gain}").as_bytes(),
+    )
+    .to_hex()
+    .to_string()
+}
+
+pub(super) fn extension(format: OutputFormat) -> &'static str {
+    match format {
+        OutputFormat::Raw => "bin",
+        OutputFormat::Mp3 => "mp3",
+        OutputFormat::Opus => "opus",
+        OutputFormat::Aac => "aac",
+    }
+}
+
+pub(super) fn mime_for_format(format: OutputFormat) -> &'static str {
+    match format {
+        OutputFormat::Raw => "application/octet-stream",
+        OutputFormat::Mp3 => "audio/mpeg",
+        OutputFormat::Opus => "audio/ogg",
+        OutputFormat::Aac => "audio/aac",
+    }
+}
+
+pub(super) async fn prune_cache(inner: &MediaInner) {
+    let Ok(mut directory) = tokio::fs::read_dir(&inner.cache_dir).await else {
+        return;
+    };
+    let mut files = Vec::new();
+    let mut total = 0u64;
+    while let Ok(Some(entry)) = directory.next_entry().await {
+        let path = entry.path();
+        if path
+            .file_name()
+            .and_then(OsStr::to_str)
+            .is_some_and(|name| name.contains(".part-"))
+        {
+            continue;
+        }
+        let Ok(metadata) = entry.metadata().await else {
+            continue;
+        };
+        if !metadata.is_file() {
+            continue;
+        }
+        total = total.saturating_add(metadata.len());
+        let accessed = inner
+            .cache_access
+            .get(&path)
+            .map(|value| *value)
+            .or_else(|| metadata.modified().ok())
+            .unwrap_or(SystemTime::UNIX_EPOCH);
+        files.push((accessed, path, metadata.len()));
+    }
+    files.sort_by_key(|(accessed, _, _)| *accessed);
+    let mut removed = HashMap::new();
+    for (_, path, size) in files {
+        if total <= inner.cache_max_bytes {
+            break;
+        }
+        if tokio::fs::remove_file(&path).await.is_ok() {
+            total = total.saturating_sub(size);
+            inner.cache_access.remove(&path);
+            removed.insert(path, size);
+        }
+    }
+    if !removed.is_empty() {
+        tracing::debug!(files = removed.len(), "transcode cache pruned");
+    }
+}

From 1616922116e9dad58a5bf7e672b3e94734f0fa65 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:56:07 +0100
Subject: [PATCH 3/4] refactor(scanner): split the scanner into job, discovery
 and extract

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/scanner/discovery/mod.rs   |  667 +++++++++++
 src/scanner/discovery/tests.rs |  144 +++
 src/scanner/extract/mod.rs     |  605 ++++++++++
 src/scanner/extract/tests.rs   |  134 +++
 src/scanner/job.rs             |  387 +++++++
 src/scanner/mod.rs             | 1914 +-------------------------------
 6 files changed, 1947 insertions(+), 1904 deletions(-)
 create mode 100644 src/scanner/discovery/mod.rs
 create mode 100644 src/scanner/discovery/tests.rs
 create mode 100644 src/scanner/extract/mod.rs
 create mode 100644 src/scanner/extract/tests.rs
 create mode 100644 src/scanner/job.rs

diff --git a/src/scanner/discovery/mod.rs b/src/scanner/discovery/mod.rs
new file mode 100644
index 00000000..aab1bc6a
--- /dev/null
+++ b/src/scanner/discovery/mod.rs
@@ -0,0 +1,667 @@
+//! Walking a library: ignore files, built-in exclusions, links, scopes, and
+//! what a walk can say it saw missing.
+
+use std::{
+    collections::HashSet,
+    fs,
+    io::Read,
+    path::{Path, PathBuf},
+};
+
+use uuid::Uuid;
+use walkdir::WalkDir;
+
+use super::extract::sidecar_options;
+
+#[cfg(test)]
+mod tests;
+
+/// The ignore file a folder may hold (RFC-021 decision 1).
+pub const IGNORE_FILE: &str = ".waveflowignore";
+
+/// Beyond this an ignore file is refused rather than read: a list of
+/// exclusions has no business being larger, and the walk reads one per folder.
+const MAX_IGNORE_BYTES: u64 = 64 * 1024;
+
+/// Names the walk never enters, whatever an ignore file says (RFC-021
+/// decision 1), beside every name beginning with a dot. Compared without
+/// regard to case: `$RECYCLE.BIN` is spelled several ways by the systems that
+/// write it.
+const BUILT_IN_EXCLUSIONS: [&str; 6] = [
+    "@eaDir",
+    "#recycle",
+    "#snapshot",
+    "$RECYCLE.BIN",
+    "System Volume Information",
+    "lost+found",
+];
+
+/// How many skipped links one scan names in the log, one line each, before it
+/// only counts the rest.
+const LOGGED_LINKS: usize = 20;
+
+/// Whether an entry below the root is left out by name. The root and the
+/// folders above it are never asked: a library may well live under a dot
+/// folder, and a temporary directory always does.
+fn built_in_exclusion(name: &std::ffi::OsStr, depth: usize, is_dir: bool) -> bool {
+    let name = name.to_string_lossy();
+    if name.starts_with('.') {
+        // Received files land here (RFC-008), and the scan is what keeps them
+        // in the catalogue after the upload that applied them.
+        return !(depth == 1 && is_dir && name == crate::services::uploads::MANAGED_DIR);
+    }
+    BUILT_IN_EXCLUSIONS
+        .iter()
+        .any(|excluded| excluded.eq_ignore_ascii_case(&name))
+}
+
+/// What one folder's ignore file says.
+enum Rules {
+    /// No file, or a root file with nothing in it.
+    None,
+    Matcher(ignore::gitignore::Gitignore),
+    /// An empty file below the root: the folder and everything under it.
+    ExcludeAll,
+    /// A file the walk cannot use, and why. Its folder counts as unreadable.
+    Unusable(&'static str),
+}
+
+/// Reads `dir`'s ignore file, if it has one. Never through a link, and never
+/// in a way that can block, as the lyrics sidecars are read.
+fn load_rules(dir: &Path, at_root: bool) -> Rules {
+    let file = dir.join(IGNORE_FILE);
+    let metadata = match fs::symlink_metadata(&file) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Rules::None,
+        Err(_) => return Rules::Unusable("its .waveflowignore could not be read"),
+    };
+    if !metadata.is_file() {
+        return Rules::Unusable("its .waveflowignore is not a regular file");
+    }
+    if metadata.len() > MAX_IGNORE_BYTES {
+        return Rules::Unusable("its .waveflowignore is larger than 64 KiB");
+    }
+    let Some(text) = sidecar_options().open(&file).ok().and_then(|opened| {
+        let mut bytes = Vec::new();
+        opened
+            .take(MAX_IGNORE_BYTES + 1)
+            .read_to_end(&mut bytes)
+            .ok()?;
+        (bytes.len() as u64 <= MAX_IGNORE_BYTES)
+            .then(|| String::from_utf8_lossy(&bytes).into_owned())
+    }) else {
+        return Rules::Unusable("its .waveflowignore could not be read");
+    };
+    let text = text.trim_start_matches('\u{feff}');
+    if text.trim().is_empty() {
+        // At the root an empty file excludes nothing: one stray file must not
+        // mark a whole library missing.
+        return if at_root {
+            Rules::None
+        } else {
+            Rules::ExcludeAll
+        };
+    }
+    let mut builder = ignore::gitignore::GitignoreBuilder::new(dir);
+    for line in text.lines() {
+        if builder.add_line(None, line).is_err() {
+            return Rules::Unusable("its .waveflowignore holds a pattern that cannot be read");
+        }
+    }
+    match builder.build() {
+        Ok(matcher) => Rules::Matcher(matcher),
+        Err(_) => Rules::Unusable("its .waveflowignore holds a pattern that cannot be read"),
+    }
+}
+
+/// Why the walk left a symbolic link behind (RFC-021 decision 3).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SkippedLink {
+    /// The library does not follow links.
+    NotFollowed,
+    /// Its target lies outside the library root.
+    Outside,
+    /// Its target does not exist, or cannot be read.
+    Broken,
+    /// It leads back to one of its own ancestors.
+    Loop,
+}
+
+impl SkippedLink {
+    fn reason(self) -> &'static str {
+        match self {
+            Self::NotFollowed => "the library does not follow links",
+            Self::Outside => "its target is outside the library",
+            Self::Broken => "its target cannot be read",
+            Self::Loop => "it leads back to a folder above it",
+        }
+    }
+}
+
+/// A folder the walk could not read, relative to the root, and why.
+pub(super) struct Unreadable {
+    pub(super) folder: String,
+    pub(super) reason: &'static str,
+}
+
+/// What the walk found: the audio files, in catalogue path order, each with
+/// the path it is read from and the path the catalogue knows it by, and the
+/// folders it could not read, relative to the root.
+pub(super) struct Discovery {
+    pub(super) paths: Vec<(PathBuf, String)>,
+    pub(super) unreadable: Vec<Unreadable>,
+    /// An error named no path inside the root, so the walk cannot say which
+    /// tracks it missed: none may be marked missing.
+    pub(super) incomplete: bool,
+    /// Entries left out by an exclusion, a folder counting once whatever it
+    /// holds (RFC-021 decision 2). They count as not discovered.
+    pub(super) excluded: usize,
+    /// Symbolic links the walk did not follow (RFC-021 decision 3).
+    pub(super) skipped_links: usize,
+}
+
+/// Where one walk may go: the library root, whether it follows links, and —
+/// when it does — the folders outside the root a link may reach into and the
+/// other libraries' roots no link may reach into (RFC-021, links outside the
+/// root). Every path in it is canonical.
+pub(super) struct Reach<'a> {
+    pub(super) root: &'a Path,
+    pub(super) follow_links: bool,
+    pub(super) link_roots: &'a [PathBuf],
+    pub(super) libraries: &'a [PathBuf],
+}
+
+impl Reach<'_> {
+    /// Whether a followed link may lead to `target`, a canonical path.
+    fn admits_target(&self, target: &Path) -> bool {
+        target.starts_with(self.root)
+            || crate::link_roots::admits(self.link_roots, self.libraries, target)
+    }
+
+    /// What the walk reached at `path`: the canonical path to read it from,
+    /// and the path relative to the root the catalogue names it by.
+    ///
+    /// Without links, the path as walked. With links, a target inside the root
+    /// is named by its canonical path, so one file is one track however many
+    /// links name it (decision 3); a target in an allowed folder outside it has
+    /// no path inside the root, so it is named by the path the walk reached it
+    /// through — links included, which is why the stream check accepts a link
+    /// that resolves into an allowed folder. Anything else names nothing.
+    fn catalogue_name(&self, path: &Path) -> Option<(PathBuf, String)> {
+        if !self.follow_links {
+            return Some((path.to_path_buf(), relative_to(self.root, path)));
+        }
+        let canonical = fs::canonicalize(path).ok()?;
+        if canonical.starts_with(self.root) {
+            let name = relative_to(self.root, &canonical);
+            return Some((canonical, name));
+        }
+        (crate::link_roots::admits(self.link_roots, self.libraries, &canonical)
+            && path.starts_with(self.root))
+        .then(|| (canonical, relative_to(self.root, path)))
+    }
+}
+
+/// What the walk accumulates while `walkdir` decides, entry by entry, what to
+/// enter. Shared between the filter and the loop, hence the cell.
+#[derive(Default)]
+struct WalkState {
+    /// Each folder's ignore rules, by the path the walk sees it under.
+    rules: std::collections::HashMap<PathBuf, ignore::gitignore::Gitignore>,
+    unreadable: Vec<Unreadable>,
+    excluded: usize,
+    skipped_links: usize,
+    /// A folder could not be read and could not be named as the catalogue
+    /// names its tracks: no track may be marked missing.
+    incomplete: bool,
+}
+
+impl WalkState {
+    /// Records a folder the walk could not read, or could not use the rules
+    /// of, under the name its tracks carry in the catalogue (RFC-018
+    /// decision 3, RFC-021 decision 3).
+    ///
+    /// With links followed, a track is stored under its canonical path, and a
+    /// folder reached through a link has another name: spared under the
+    /// link's, its tracks would be marked missing anyway. So the folder is
+    /// named as the catalogue names what it holds; one that names nothing
+    /// leaves the walk incomplete.
+    fn unreadable(&mut self, reach: &Reach<'_>, path: &Path, reason: &'static str) {
+        match reach.catalogue_name(path).map(|(_, name)| name) {
+            Some(folder) => {
+                tracing::warn!(
+                    path = %folder,
+                    reason,
+                    "a folder in the library could not be used; its tracks are left as they are"
+                );
+                self.unreadable.push(Unreadable { folder, reason });
+            }
+            None => {
+                tracing::warn!(
+                    path = %relative_to(reach.root, path),
+                    reason,
+                    "a folder reached through a link could not be used, nor resolved; nothing is marked missing this scan"
+                );
+                self.incomplete = true;
+                self.unreadable.push(Unreadable {
+                    folder: "<unknown>".to_owned(),
+                    reason,
+                });
+            }
+        }
+    }
+
+    /// Whether an ignore file of a folder above `path` leaves it out. The
+    /// deepest file that has an opinion decides, as in git.
+    fn ignored(&self, root: &Path, path: &Path, is_dir: bool) -> bool {
+        let mut folder = path.parent();
+        while let Some(current) = folder {
+            if let Some(rules) = self.rules.get(current) {
+                let matched = rules.matched(path, is_dir);
+                if matched.is_ignore() {
+                    return true;
+                }
+                if matched.is_whitelist() {
+                    return false;
+                }
+            }
+            if current == root {
+                break;
+            }
+            folder = current.parent();
+        }
+        false
+    }
+
+    fn skip_link(&mut self, path: &str, why: SkippedLink) {
+        self.skipped_links += 1;
+        if self.skipped_links <= LOGGED_LINKS {
+            tracing::info!(path = %path, reason = why.reason(), "a symbolic link in the library was skipped");
+        }
+    }
+}
+
+/// A path relative to the root, as the catalogue and the log spell it.
+fn relative_to(root: &Path, path: &Path) -> String {
+    path.strip_prefix(root)
+        .map(|path| path.to_string_lossy().replace('\\', "/"))
+        .unwrap_or_else(|_| "<outside the library>".to_owned())
+}
+
+/// The walk's decision on one entry below where it started: enter it, or
+/// leave it. `base` is how deep below the root the walk started, so the rules
+/// that depend on depth read the depth below the root.
+fn admit(
+    entry: &walkdir::DirEntry,
+    reach: &Reach<'_>,
+    base: usize,
+    walk: &std::cell::RefCell<WalkState>,
+) -> bool {
+    if entry.depth() == 0 {
+        return true;
+    }
+    let root = reach.root;
+    let mut walk = walk.borrow_mut();
+    let path = entry.path();
+    // Followed, `file_type` is the target's; not followed, it is the link's.
+    let is_dir = entry.file_type().is_dir();
+    let is_link = if reach.follow_links {
+        entry.path_is_symlink()
+    } else {
+        entry.file_type().is_symlink()
+    };
+    // The rules themselves: read with their folder, never counted as left out.
+    if entry.file_name() == IGNORE_FILE {
+        return false;
+    }
+    // By the name the walk sees, a link's own included (decision 1).
+    if built_in_exclusion(entry.file_name(), base + entry.depth(), is_dir)
+        || walk.ignored(root, path, is_dir)
+    {
+        walk.excluded += 1;
+        tracing::debug!(path = %relative_to(root, path), "left out of the scan");
+        return false;
+    }
+    if is_link {
+        let skipped = if !reach.follow_links {
+            Some(SkippedLink::NotFollowed)
+        } else {
+            match fs::canonicalize(path) {
+                Ok(target) if reach.admits_target(&target) => None,
+                Ok(_) => Some(SkippedLink::Outside),
+                Err(_) => Some(SkippedLink::Broken),
+            }
+        };
+        if let Some(why) = skipped {
+            walk.skip_link(&relative_to(root, path), why);
+            return false;
+        }
+    } else if is_dir && reach.follow_links && !reach.link_roots.is_empty() {
+        // A folder that is no link itself, reached through one into an
+        // allowed folder, may be another library's root: the link that led
+        // here stops at it, and is counted as skipped there.
+        match fs::canonicalize(path) {
+            Ok(target) if reach.admits_target(&target) => {}
+            _ => {
+                walk.skip_link(&relative_to(root, path), SkippedLink::Outside);
+                return false;
+            }
+        }
+    }
+    if is_dir {
+        match load_rules(path, false) {
+            Rules::None => {}
+            Rules::Matcher(rules) => {
+                walk.rules.insert(path.to_path_buf(), rules);
+            }
+            Rules::ExcludeAll => {
+                walk.excluded += 1;
+                tracing::debug!(path = %relative_to(root, path), "left out of the scan by an empty ignore file");
+                return false;
+            }
+            Rules::Unusable(reason) => {
+                walk.unreadable(reach, path, reason);
+                return false;
+            }
+        }
+    }
+    true
+}
+
+/// How many folders a scoped scan walks at most. A watcher that saw changes in
+/// more than this is told to walk the whole library instead: a list that long
+/// says the changes were everywhere, and walking it folder by folder would
+/// cost more than the walk it was meant to save.
+pub(crate) const MAX_SCOPE_FOLDERS: usize = 64;
+
+/// A scope as a scoped walk may use it: folders relative to the root, spelled
+/// with `/`, none of them nested in another, at most [`MAX_SCOPE_FOLDERS`].
+///
+/// `None` — the whole library — for anything that is not plainly such a list:
+/// an empty folder (the root itself), a `..`, an absolute path, too many
+/// folders. Walking more than asked is always safe; walking less is not.
+pub(crate) fn normalised_scope(scope: &[String]) -> Option<Vec<String>> {
+    let mut folders = Vec::with_capacity(scope.len());
+    for folder in scope {
+        // A trailing separator is a spelling; a leading one is an absolute
+        // path, which no folder of a library is.
+        if folder.starts_with('/') {
+            return None;
+        }
+        let folder = folder.trim_end_matches('/');
+        if folder.is_empty()
+            || folder
+                .split('/')
+                .any(|part| part.is_empty() || part == "." || part == ".." || part.contains('\\'))
+            || Path::new(folder).is_absolute()
+        {
+            return None;
+        }
+        folders.push(folder.to_owned());
+    }
+    folders.sort();
+    folders.dedup();
+    // A folder is dropped when any of its ancestors is listed too. Sorting
+    // alone does not put a folder's descendants right after it — `-`, ` ` and
+    // `(` sort before `/`, so "Rock - Live" falls between "Rock" and
+    // "Rock/Album" — hence every ancestor is asked, not the last one kept.
+    let listed: HashSet<&str> = folders.iter().map(String::as_str).collect();
+    let kept: Vec<String> = folders
+        .iter()
+        .filter(|folder| {
+            !folder
+                .match_indices('/')
+                .any(|(at, _)| listed.contains(&folder[..at]))
+        })
+        .cloned()
+        .collect();
+    (!kept.is_empty() && kept.len() <= MAX_SCOPE_FOLDERS).then_some(kept)
+}
+
+/// Where a scoped walk of `folder` starts, and how deep below the root that
+/// is — or `None` when there is nothing to walk there.
+///
+/// Every folder on the way down is judged as the whole walk would have judged
+/// it, so a scoped walk reads exactly what a full one would read below it: the
+/// built-in exclusions and every ignore file above it, which are loaded as it
+/// goes. A folder on the way that is excluded is left out, and what the
+/// catalogue holds under it counts as not discovered (RFC-021 decision 2); one
+/// that cannot be read, or whose rules cannot be used, is unreadable and spares
+/// its tracks (RFC-018 decision 3). A folder that is gone was walked, and
+/// nothing is there. A scoped walk reads no link, so a link on the way leads
+/// nowhere, as it would in a walk that does not follow links.
+fn enter_scope(
+    reach: &Reach<'_>,
+    walk: &std::cell::RefCell<WalkState>,
+    folder: &str,
+) -> Option<(PathBuf, usize)> {
+    let root = reach.root;
+    let mut current = root.to_path_buf();
+    let parts: Vec<&str> = folder.split('/').collect();
+    for (index, name) in parts.iter().enumerate() {
+        let depth = index + 1;
+        let next = current.join(name);
+        let metadata = match fs::symlink_metadata(&next) {
+            Ok(metadata) => metadata,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return None,
+            Err(_) => {
+                walk.borrow_mut()
+                    .unreadable(reach, &next, "folder could not be read");
+                return None;
+            }
+        };
+        let mut state = walk.borrow_mut();
+        if metadata.file_type().is_symlink() {
+            state.skip_link(&relative_to(root, &next), SkippedLink::NotFollowed);
+            return None;
+        }
+        if !metadata.is_dir() {
+            // A file where a folder was named: the folder above it, walked
+            // whole, holds it.
+            return Some((current, depth - 1));
+        }
+        if built_in_exclusion(std::ffi::OsStr::new(name), depth, true)
+            || state.ignored(root, &next, true)
+        {
+            state.excluded += 1;
+            return None;
+        }
+        match load_rules(&next, false) {
+            Rules::None => {}
+            Rules::Matcher(rules) => {
+                state.rules.insert(next.clone(), rules);
+            }
+            Rules::ExcludeAll => {
+                state.excluded += 1;
+                return None;
+            }
+            Rules::Unusable(reason) => {
+                state.unreadable(reach, &next, reason);
+                return None;
+            }
+        }
+        current = next;
+    }
+    Some((current, parts.len()))
+}
+
+/// Walks the library (RFC-018 decision 3, RFC-021 decisions 1 to 3), or only
+/// the folders of `scope` when the watcher could name them.
+///
+/// An entry the walk cannot read is logged by its path relative to the root,
+/// never the absolute one, and the walk goes on; only the root itself failing
+/// fails the scan, since then nothing can be told apart — and that includes an
+/// ignore file at the root the walk cannot use.
+///
+/// With `follow_links`, a file reached through a link is returned under the
+/// name [`Reach::catalogue_name`] gives it, and once only, however many links
+/// name it.
+pub(super) fn discover_audio(
+    reach: &Reach<'_>,
+    scope: Option<&[String]>,
+) -> anyhow::Result<Discovery> {
+    let root = reach.root;
+    let walk = std::cell::RefCell::new(WalkState::default());
+    match load_rules(root, true) {
+        Rules::Matcher(rules) => {
+            walk.borrow_mut().rules.insert(root.to_path_buf(), rules);
+        }
+        Rules::Unusable(reason) => {
+            anyhow::bail!("the .waveflowignore at the library root cannot be used: {reason}")
+        }
+        Rules::None | Rules::ExcludeAll => {}
+    }
+    let starts: Vec<(PathBuf, usize)> = match scope {
+        None => vec![(root.to_path_buf(), 0)],
+        Some(folders) => folders
+            .iter()
+            .filter_map(|folder| enter_scope(reach, &walk, folder))
+            .collect(),
+    };
+    let mut paths = Vec::new();
+    let mut incomplete = false;
+    for (start, base) in starts {
+        let entries = WalkDir::new(&start)
+            .follow_links(reach.follow_links)
+            .into_iter()
+            .filter_entry(|entry| admit(entry, reach, base, &walk));
+        for entry in entries {
+            let entry = match entry {
+                Ok(entry) => entry,
+                Err(error) if error.depth() == 0 && base == 0 => return Err(error.into()),
+                Err(error) => {
+                    let mut walk = walk.borrow_mut();
+                    // A link the walk was told to follow and could not: a loop,
+                    // or a target it cannot read. A link, not a folder, so
+                    // nothing under a folder is spared for it.
+                    let link = if error.loop_ancestor().is_some() {
+                        Some(SkippedLink::Loop)
+                    } else if reach.follow_links
+                        && error.path().is_some_and(|path| {
+                            fs::symlink_metadata(path)
+                                .is_ok_and(|meta| meta.file_type().is_symlink())
+                        })
+                    {
+                        Some(SkippedLink::Broken)
+                    } else {
+                        None
+                    };
+                    let named = error.path().filter(|path| path.starts_with(root));
+                    match (link, named) {
+                        (Some(why), Some(path)) => walk.skip_link(&relative_to(root, path), why),
+                        (_, None) => {
+                            tracing::warn!("the library walk failed somewhere it could not name");
+                            incomplete = true;
+                            walk.unreadable.push(Unreadable {
+                                folder: "<unknown>".to_owned(),
+                                reason: "folder could not be read",
+                            });
+                        }
+                        (None, Some(path)) => {
+                            walk.unreadable(reach, path, "folder could not be read");
+                        }
+                    }
+                    continue;
+                }
+            };
+            // A link is only ever yielded here when it is followed, and then
+            // its type is its target's.
+            if !entry.file_type().is_file() {
+                continue;
+            }
+            let Some((path, name)) = reach.catalogue_name(entry.path()) else {
+                continue;
+            };
+            let supported = path
+                .extension()
+                .and_then(|value| value.to_str())
+                .is_some_and(|ext| {
+                    waveflow_core::scanner::AUDIO_EXTENSIONS
+                        .iter()
+                        .any(|candidate| candidate.eq_ignore_ascii_case(ext))
+                });
+            if supported {
+                paths.push((path, name));
+            }
+        }
+    }
+    paths.sort_by(|left, right| left.1.cmp(&right.1));
+    // Followed links can name one file twice, or name a file the walk also
+    // found directly: the first name in catalogue order keeps it.
+    let mut read = HashSet::new();
+    paths.retain(|(path, _)| read.insert(path.clone()));
+    let walk = walk.into_inner();
+    if walk.skipped_links > LOGGED_LINKS {
+        tracing::info!(
+            count = walk.skipped_links - LOGGED_LINKS,
+            "further symbolic links in the library were skipped"
+        );
+    }
+    Ok(Discovery {
+        paths,
+        unreadable: walk.unreadable,
+        incomplete: incomplete || walk.incomplete,
+        excluded: walk.excluded,
+        skipped_links: walk.skipped_links,
+    })
+}
+
+/// What one walk saw, as relocation needs it: the files it found, what it
+/// could not look at, and — for a scoped walk — where it looked at all.
+pub(super) struct Walked<'a> {
+    pub(super) discovered: &'a HashSet<String>,
+    pub(super) unreadable: &'a [String],
+    pub(super) incomplete: bool,
+    /// The folders a scoped walk covered, `None` for the whole library.
+    pub(super) scope: Option<&'a [String]>,
+}
+
+/// Whether `path` is `folder` or lies under it, compared as text.
+fn under(path: &str, folder: &str) -> bool {
+    path == folder
+        || path
+            .strip_prefix(folder)
+            .is_some_and(|rest| rest.starts_with('/'))
+}
+
+impl Walked<'_> {
+    /// Whether the walk can say this track's file is gone: it looked where the
+    /// file was, did not find it, and that place is not under a folder it
+    /// could not read. A scoped walk did not look outside its folders, so a
+    /// track there is never one it saw missing — which is what keeps a scoped
+    /// scan from moving the identity of a track it never looked for onto a
+    /// file it found.
+    fn saw_missing(&self, relative_path: &str) -> bool {
+        !self.incomplete
+            && self
+                .scope
+                .is_none_or(|folders| folders.iter().any(|folder| under(relative_path, folder)))
+            && !self.discovered.contains(relative_path)
+            && !self
+                .unreadable
+                .iter()
+                .any(|folder| under(relative_path, folder))
+    }
+}
+
+/// The candidates a scan may still claim.
+///
+/// A track whose file this walk found is not missing, whatever a hash or a hint
+/// says about it, and one already claimed by an earlier file in this batch is
+/// spoken for. Nor is one under a folder the walk could not read, or any at all
+/// when the walk could not say what it missed (RFC-018 decision 3): its file
+/// may be right where it was. What survives is what genuinely disappeared — and
+/// a relocation is only recorded when exactly one thing did, because moving a
+/// favourite onto the wrong row is worse than not moving it at all.
+pub(super) fn unclaimed(
+    candidates: Vec<crate::catalog::ExistingTrack>,
+    walked: &Walked<'_>,
+    claimed: &HashSet<Uuid>,
+) -> Vec<crate::catalog::ExistingTrack> {
+    candidates
+        .into_iter()
+        .filter(|candidate| {
+            walked.saw_missing(&candidate.relative_path) && !claimed.contains(&candidate.id)
+        })
+        .collect()
+}
diff --git a/src/scanner/discovery/tests.rs b/src/scanner/discovery/tests.rs
new file mode 100644
index 00000000..2e1a5307
--- /dev/null
+++ b/src/scanner/discovery/tests.rs
@@ -0,0 +1,144 @@
+//! Unit tests of the walk's rules: exclusions, ignore files, scopes, and what
+//! counts as missing.
+
+use super::{built_in_exclusion, load_rules, Rules, Walked, IGNORE_FILE, MAX_IGNORE_BYTES};
+
+/// RFC-021 decision 1: what is left out by name, below the root only, and
+/// the one dot folder that is not.
+#[test]
+fn built_in_exclusions_spare_the_folder_uploads_land_in() {
+    use std::ffi::OsStr;
+    for name in [
+        ".hidden",
+        "._Track.flac",
+        ".Trash-1000",
+        "@eaDir",
+        "#recycle",
+        "$Recycle.Bin",
+        "System Volume Information",
+        "LOST+FOUND",
+    ] {
+        assert!(built_in_exclusion(OsStr::new(name), 1, true), "{name}");
+    }
+    assert!(!built_in_exclusion(OsStr::new("Album"), 1, true));
+    assert!(!built_in_exclusion(OsStr::new("eaDir"), 1, true));
+    // Received files: kept directly under the root, and only there.
+    assert!(!built_in_exclusion(
+        OsStr::new(".waveflow-managed"),
+        1,
+        true
+    ));
+    assert!(built_in_exclusion(OsStr::new(".waveflow-managed"), 2, true));
+    assert!(built_in_exclusion(
+        OsStr::new(".waveflow-managed"),
+        1,
+        false
+    ));
+}
+
+/// RFC-021 decision 1: an empty file excludes its folder except at the
+/// root, and a file the walk cannot use says why.
+#[test]
+fn ignore_files_are_read_as_the_rfc_says() {
+    let temp = tempfile::tempdir().unwrap();
+    let dir = temp.path();
+    assert!(matches!(load_rules(dir, false), Rules::None));
+
+    std::fs::write(dir.join(IGNORE_FILE), " \n\t\n").unwrap();
+    assert!(matches!(load_rules(dir, false), Rules::ExcludeAll));
+    assert!(
+        matches!(load_rules(dir, true), Rules::None),
+        "an empty file at the root must exclude nothing"
+    );
+
+    std::fs::write(dir.join(IGNORE_FILE), "# scans\n*.wav\n!Keep.wav\n").unwrap();
+    let Rules::Matcher(rules) = load_rules(dir, false) else {
+        panic!("a valid file is a matcher");
+    };
+    assert!(rules.matched(dir.join("Drop.wav"), false).is_ignore());
+    assert!(rules.matched(dir.join("Keep.wav"), false).is_whitelist());
+
+    std::fs::write(dir.join(IGNORE_FILE), "[z-a]\n").unwrap();
+    assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
+
+    std::fs::write(
+        dir.join(IGNORE_FILE),
+        vec![b'#'; MAX_IGNORE_BYTES as usize + 1],
+    )
+    .unwrap();
+    assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
+
+    std::fs::remove_file(dir.join(IGNORE_FILE)).unwrap();
+    std::fs::create_dir(dir.join(IGNORE_FILE)).unwrap();
+    assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
+}
+
+/// A track under a folder the walk could not read is not missing, so no
+/// file elsewhere may claim it; nor may any track when the walk could not
+/// name what it missed.
+#[test]
+fn a_track_the_walk_could_not_see_is_not_missing() {
+    let discovered = std::collections::HashSet::from(["Found/One.wav".to_owned()]);
+    let unreadable = vec!["Locked".to_owned()];
+    let walked = Walked {
+        discovered: &discovered,
+        unreadable: &unreadable,
+        incomplete: false,
+        scope: None,
+    };
+    assert!(!walked.saw_missing("Found/One.wav"));
+    assert!(!walked.saw_missing("Locked/Two.wav"));
+    assert!(!walked.saw_missing("Locked"));
+    assert!(walked.saw_missing("Lockedness/Three.wav"));
+    assert!(walked.saw_missing("Gone/Four.wav"));
+    let incomplete = Walked {
+        incomplete: true,
+        ..walked
+    };
+    assert!(!incomplete.saw_missing("Gone/Four.wav"));
+    // A scoped walk looked in its folders only: a track anywhere else was
+    // not looked for, so it was not seen missing.
+    let scope = vec!["Gone".to_owned()];
+    let scoped = Walked {
+        scope: Some(&scope),
+        ..walked
+    };
+    assert!(scoped.saw_missing("Gone/Four.wav"));
+    assert!(!scoped.saw_missing("Elsewhere/Five.wav"));
+    assert!(!scoped.saw_missing("Goner/Six.wav"));
+}
+
+/// A scope is a list of folders a walk can trust, or the whole library.
+#[test]
+fn a_scope_is_plain_folders_or_the_whole_library() {
+    let folders = |list: &[&str]| list.iter().map(|f| (*f).to_owned()).collect::<Vec<_>>();
+    assert_eq!(
+        super::normalised_scope(&folders(&["b/c", "a", "a/x/y", "b/c/", "bc"])),
+        Some(folders(&["a", "b/c", "bc"])),
+        "nested folders are covered by their parent, and a prefix is not a parent"
+    );
+    // A sibling that sorts between a folder and its child: "-", " " and
+    // "(" all come before "/".
+    assert_eq!(
+        super::normalised_scope(&folders(&[
+            "Rock/Album",
+            "Rock - Live",
+            "Rock",
+            "Artist (Live)",
+            "Artist/Album/CD1"
+        ])),
+        Some(folders(&[
+            "Artist (Live)",
+            "Artist/Album/CD1",
+            "Rock",
+            "Rock - Live"
+        ])),
+    );
+    for whole in [&[""][..], &["a/../b"], &["/etc"], &["a//b"], &["."], &[]] {
+        assert_eq!(super::normalised_scope(&folders(whole)), None, "{whole:?}");
+    }
+    let many: Vec<String> = (0..=super::MAX_SCOPE_FOLDERS)
+        .map(|index| format!("f{index}"))
+        .collect();
+    assert_eq!(super::normalised_scope(&many), None);
+}
diff --git a/src/scanner/extract/mod.rs b/src/scanner/extract/mod.rs
new file mode 100644
index 00000000..d25b7ec9
--- /dev/null
+++ b/src/scanner/extract/mod.rs
@@ -0,0 +1,605 @@
+//! Reading one file: the pre-check that skips it, its tags, credits, cover,
+//! DSD metadata, and the lyrics embedded in it or kept beside it.
+
+use std::{fs, io::Read, path::Path, time::UNIX_EPOCH};
+
+use lofty::{
+    file::TaggedFileExt,
+    prelude::{Accessor, AudioFile, ItemKey},
+};
+use uuid::Uuid;
+
+use crate::{
+    catalog::{ArtworkInput, CatalogTrackInput},
+    lyrics::{self, LyricsInput},
+};
+
+#[cfg(test)]
+mod tests;
+
+const MAX_LYRICS_BYTES: u64 = 1024 * 1024;
+
+/// What a scan does with one discovered file.
+pub(super) enum Scanned {
+    /// Unchanged since the last scan: skipped without being opened.
+    Skipped(Uuid),
+    /// Read, with the sidecar signature to record once it is applied.
+    /// `None` when a sidecar could not be opened: nothing is recorded, so the
+    /// file is read again until it can be.
+    Read(Box<Result<CatalogTrackInput, String>>, Option<String>),
+}
+
+/// The pre-check, then the read (RFC-018 decision 1).
+///
+/// A file whose size, modification time and sidecar signature match what the
+/// catalogue holds, on an available track that already has its relocation
+/// hint, is skipped from a `stat` alone. Anything else, and every file on a
+/// full scan, is read as before.
+pub(super) fn scan_file(
+    path: &Path,
+    artwork_dir: &Path,
+    known: Option<crate::catalog::SkipFacts>,
+    full: bool,
+) -> Scanned {
+    let signature = sidecar_signature(path);
+    if let Some(known) = known.filter(|_| !full) {
+        let unchanged = file_stamp(path).is_some_and(|(size, modified_at)| {
+            size == known.file_size && modified_at == known.modified_at
+        }) && known.available
+            && known.has_pid
+            && signature.is_some()
+            && known.sidecar_signature == signature;
+        if unchanged {
+            return Scanned::Skipped(known.id);
+        }
+    }
+    Scanned::Read(Box::new(extract_file(path, artwork_dir)), signature)
+}
+
+/// A file's size and modification time, as `extract_file` records them.
+fn file_stamp(path: &Path) -> Option<(i64, i64)> {
+    let metadata = fs::metadata(path).ok()?;
+    let modified_at = metadata
+        .modified()
+        .ok()
+        .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
+        .map(|value| value.as_millis() as i64)
+        .unwrap_or(0);
+    Some((metadata.len() as i64, modified_at))
+}
+
+/// The two lyrics sidecars a scan reads beside an audio file, by size and
+/// modification time, absent ones as `-`:
+/// `lrc:<size>:<mtime_ms>|txt:<size>:<mtime_ms>`. Adding, editing or deleting
+/// either changes it; it is never empty.
+///
+/// `None` when a sidecar exists but cannot be opened. The read then goes ahead
+/// without its lyrics, and recording the signature would skip the file for as
+/// long as the sidecar's size and time stay put — a permission fixed later
+/// moves neither. With no signature the file is read on every scan until the
+/// sidecar can be.
+///
+/// Read without following links, and a sidecar that is not a regular file — a
+/// link, a FIFO, a folder — counts as absent, since `read_sidecar` would not
+/// read it either. Only a regular file is opened, and never in a way that can
+/// block.
+fn sidecar_signature(path: &Path) -> Option<String> {
+    let mut parts = Vec::with_capacity(2);
+    for extension in ["lrc", "txt"] {
+        let sidecar = path.with_extension(extension);
+        match fs::symlink_metadata(&sidecar) {
+            Ok(metadata) if metadata.is_file() => {
+                sidecar_options().open(&sidecar).ok()?;
+                let modified_at = metadata
+                    .modified()
+                    .ok()
+                    .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
+                    .map(|value| value.as_millis() as i64)
+                    .unwrap_or(0);
+                parts.push(format!("{extension}:{}:{modified_at}", metadata.len()));
+            }
+            _ => parts.push(format!("{extension}:-")),
+        }
+    }
+    Some(parts.join("|"))
+}
+
+/// How a sidecar is opened, for reading it and for checking that it can be:
+/// never through a link, and without blocking on a special file swapped in
+/// after it was looked at.
+pub(super) fn sidecar_options() -> fs::OpenOptions {
+    let mut options = fs::OpenOptions::new();
+    options.read(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK);
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::OpenOptionsExt;
+        // Open the reparse point itself so descriptor metadata can reject a
+        // symlink instead of validating one path and reading its later target.
+        const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+        options.custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
+    }
+    options
+}
+
+pub(crate) fn extract_file(path: &Path, artwork_dir: &Path) -> Result<CatalogTrackInput, String> {
+    let metadata = fs::metadata(path).map_err(|error| format!("metadata: {error}"))?;
+    let size = metadata.len() as i64;
+    let modified_at = metadata
+        .modified()
+        .ok()
+        .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
+        .map(|value| value.as_millis() as i64)
+        .unwrap_or(0);
+    let quick_hash =
+        waveflow_core::scanner::hash_file(path).map_err(|error| format!("quick hash: {error}"))?;
+    let full_hash = waveflow_core::scanner::hash_file_full(path)
+        .map_err(|error| format!("full hash: {error}"))?;
+    let relative_path = path
+        .file_name()
+        .and_then(|v| v.to_str())
+        .unwrap_or("unknown")
+        .to_owned();
+
+    if matches!(
+        path.extension()
+            .and_then(|v| v.to_str())
+            .map(str::to_ascii_lowercase)
+            .as_deref(),
+        Some("dsf" | "dff")
+    ) {
+        return extract_dsd(
+            path,
+            artwork_dir,
+            relative_path,
+            size,
+            modified_at,
+            quick_hash,
+            full_hash,
+        );
+    }
+    let tagged = lofty::read_from_path(path).map_err(|error| format!("lofty: {error}"))?;
+    let props = tagged.properties();
+    let tag = tagged.primary_tag().or_else(|| tagged.first_tag());
+    let title = tag
+        .and_then(|tag| tag.title().map(|value| value.into_owned()))
+        .unwrap_or_else(|| {
+            path.file_stem()
+                .and_then(|v| v.to_str())
+                .unwrap_or("Unknown")
+                .to_owned()
+        });
+    let cover = tag
+        .and_then(|tag| waveflow_core::scanner::extract_cover(tag, artwork_dir))
+        .or_else(|| waveflow_core::scanner::extract_folder_cover(path, artwork_dir));
+    let artwork = cover.map(|cover| artwork_input(artwork_dir, cover));
+    let lyrics = extract_lyrics(path, tag);
+    let lyrics_hash = lyrics_hash(&lyrics);
+    let raw = raw_credits(tag);
+    let extended = extended_tags(tag);
+    Ok(CatalogTrackInput {
+        relative_path,
+        file_size: size,
+        modified_at,
+        quick_hash,
+        full_hash,
+        title,
+        artist: tag.and_then(|t| t.artist().map(|v| v.into_owned())),
+        artists: raw.artists,
+        album_artists: raw.album_artists,
+        roles: raw.roles,
+        performer_pairs: raw.performer_pairs,
+        album: tag.and_then(|t| t.album().map(|v| v.into_owned())),
+        album_artist: tag.and_then(waveflow_core::scanner::extract_album_artist),
+        is_compilation: tag.is_some_and(waveflow_core::scanner::extract_compilation_flag),
+        genre: tag.and_then(|t| t.genre().map(|v| v.into_owned())),
+        year: tag.and_then(|t| t.date().map(|v| v.year as i64)),
+        track_number: tag.and_then(|t| t.track().map(i64::from)),
+        disc_number: tag.and_then(|t| t.disk().map(i64::from)),
+        duration_ms: props.duration().as_millis() as i64,
+        bitrate: props.audio_bitrate().map(i64::from),
+        sample_rate: props.sample_rate().map(i64::from),
+        channels: props.channels().map(i64::from),
+        bit_depth: props.bit_depth().map(i64::from).filter(|v| *v > 0),
+        codec: waveflow_core::scanner::file_type_label(tagged.file_type()),
+        musical_key: tag.and_then(waveflow_core::scanner::extract_musical_key),
+        musicbrainz_recording_id: extended.musicbrainz_recording_id,
+        musicbrainz_release_id: extended.musicbrainz_release_id,
+        musicbrainz_artist_id: extended.musicbrainz_artist_id,
+        replay_gain_track_gain: extended.replay_gain_track_gain,
+        replay_gain_track_peak: extended.replay_gain_track_peak,
+        replay_gain_album_gain: extended.replay_gain_album_gain,
+        replay_gain_album_peak: extended.replay_gain_album_peak,
+        bpm: extended.bpm,
+        sort_title: extended.sort_title,
+        sort_album: extended.sort_album,
+        sort_album_artist: extended.sort_album_artist,
+        sort_artist: extended.sort_artist,
+        comment: extended.comment,
+        isrc: extended.isrc,
+        moods: extended.moods,
+        explicit_status: extended.explicit_status,
+        original_release_date: extended.original_release_date,
+        release_date: extended.release_date,
+        release_types: extended.release_types,
+        record_labels: extended.record_labels,
+        disc_subtitle: extended.disc_subtitle,
+        tag_rating: tag
+            .and_then(waveflow_core::scanner::extract_rating)
+            .map(i64::from),
+        artwork,
+        lyrics_hash,
+        lyrics,
+    })
+}
+
+fn artwork_input(dir: &Path, cover: waveflow_core::scanner::ExtractedCover) -> ArtworkInput {
+    let bytes = fs::metadata(dir.join(format!("{}.{}", cover.hash, cover.format)))
+        .map(|v| v.len() as i64)
+        .unwrap_or(0);
+    ArtworkInput {
+        hash: cover.hash,
+        format: cover.format,
+        source: cover.source.as_str().to_owned(),
+        byte_size: bytes,
+    }
+}
+
+fn extract_dsd(
+    path: &Path,
+    artwork_dir: &Path,
+    relative_path: String,
+    size: i64,
+    modified_at: i64,
+    quick_hash: String,
+    full_hash: String,
+) -> Result<CatalogTrackInput, String> {
+    use waveflow_core::audio_format::dsd::{
+        metadata::read_metadata,
+        parser::{parse_dff, parse_dsf, DsdContainer},
+    };
+    let ext = path
+        .extension()
+        .and_then(|v| v.to_str())
+        .unwrap_or("")
+        .to_ascii_lowercase();
+    let mut file = fs::File::open(path).map_err(|e| e.to_string())?;
+    let layout = if ext == "dsf" {
+        parse_dsf(&mut file).map_err(|e| e.to_string())?
+    } else {
+        parse_dff(&mut file).map_err(|e| e.to_string())?
+    };
+    let meta = read_metadata(&mut file, layout.container).unwrap_or_default();
+    let codec = layout
+        .dsd_rate_multiple()
+        .map(|v| format!("DSD{v}"))
+        .or_else(|| {
+            Some(
+                match layout.container {
+                    DsdContainer::Dsf => "DSF",
+                    DsdContainer::Dff => "DFF",
+                }
+                .into(),
+            )
+        });
+    let artwork = waveflow_core::scanner::extract_folder_cover(path, artwork_dir)
+        .map(|v| artwork_input(artwork_dir, v));
+    let lyrics = extract_lyrics(path, None);
+    let lyrics_hash = lyrics_hash(&lyrics);
+    let extended = extended_tags(None);
+    Ok(CatalogTrackInput {
+        relative_path,
+        file_size: size,
+        modified_at,
+        quick_hash,
+        full_hash,
+        title: meta.title.unwrap_or_else(|| {
+            path.file_stem()
+                .and_then(|v| v.to_str())
+                .unwrap_or("Unknown")
+                .into()
+        }),
+        artist: meta.artist.clone(),
+        // DSD has no tag reader beyond its own metadata block, so the only
+        // credit it can name is the artist tag. Every other role list stays
+        // empty rather than being invented.
+        artists: Vec::new(),
+        album_artists: Vec::new(),
+        roles: Vec::new(),
+        performer_pairs: Vec::new(),
+        album: meta.album,
+        album_artist: None,
+        is_compilation: false,
+        genre: meta.genre,
+        year: meta.year,
+        track_number: meta.track_number,
+        disc_number: meta.disc_number,
+        duration_ms: layout.duration_ms() as i64,
+        bitrate: None,
+        sample_rate: Some(layout.sample_rate_hz as i64),
+        channels: Some(layout.channels.count() as i64),
+        bit_depth: Some(1),
+        codec,
+        musical_key: None,
+        tag_rating: None,
+        musicbrainz_recording_id: extended.musicbrainz_recording_id,
+        musicbrainz_release_id: extended.musicbrainz_release_id,
+        musicbrainz_artist_id: extended.musicbrainz_artist_id,
+        replay_gain_track_gain: extended.replay_gain_track_gain,
+        replay_gain_track_peak: extended.replay_gain_track_peak,
+        replay_gain_album_gain: extended.replay_gain_album_gain,
+        replay_gain_album_peak: extended.replay_gain_album_peak,
+        bpm: extended.bpm,
+        sort_title: extended.sort_title,
+        sort_album: extended.sort_album,
+        sort_album_artist: extended.sort_album_artist,
+        sort_artist: extended.sort_artist,
+        comment: extended.comment,
+        isrc: extended.isrc,
+        moods: extended.moods,
+        explicit_status: extended.explicit_status,
+        original_release_date: extended.original_release_date,
+        release_date: extended.release_date,
+        release_types: extended.release_types,
+        record_labels: extended.record_labels,
+        disc_subtitle: extended.disc_subtitle,
+        artwork,
+        lyrics_hash,
+        lyrics,
+    })
+}
+
+/// The OpenSubsonic media tags the scanner reads beyond the Subsonic 1.16 set.
+///
+/// Grouped rather than inlined because both entry points build a
+/// [`CatalogTrackInput`], and the DSD path has no tag reader at all: it has to
+/// produce the same shape with every field empty rather than a different one.
+#[derive(Debug, Default)]
+struct ExtendedTags {
+    musicbrainz_recording_id: Option<String>,
+    musicbrainz_release_id: Option<String>,
+    musicbrainz_artist_id: Option<String>,
+    replay_gain_track_gain: Option<f64>,
+    replay_gain_track_peak: Option<f64>,
+    replay_gain_album_gain: Option<f64>,
+    replay_gain_album_peak: Option<f64>,
+    bpm: Option<i64>,
+    sort_title: Option<String>,
+    sort_album: Option<String>,
+    sort_album_artist: Option<String>,
+    sort_artist: Option<String>,
+    comment: Option<String>,
+    isrc: Option<String>,
+    moods: Option<String>,
+    explicit_status: Option<String>,
+    original_release_date: Option<String>,
+    release_date: Option<String>,
+    release_types: Option<String>,
+    record_labels: Option<String>,
+    disc_subtitle: Option<String>,
+}
+
+/// Reads every credit a file names, in tag order.
+///
+/// The role vocabulary and the tag each role is read from follow the
+/// reference. `WRITER` folds onto `COMPOSER` as it does there: the two are one
+/// credit on the overwhelming majority of files that carry either, and telling
+/// them apart would invent a distinction the taggers do not make.
+///
+/// `PERFORMER` is the one role whose credit carries a second value. ID3 stores
+/// it as a musician-credits frame lofty exposes only through its own tag type,
+/// so what reaches here is the generic spelling — `Name (instrument)` — which
+/// [`crate::tags::split_performer`] takes apart.
+fn raw_credits(tag: Option<&lofty::tag::Tag>) -> crate::tags::RawCredits {
+    use crate::tags::Role;
+    let Some(tag) = tag else {
+        return crate::tags::RawCredits::default();
+    };
+    let values = |key: ItemKey| -> Vec<String> {
+        tag.get_strings(key)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::to_owned)
+            .collect()
+    };
+    let single = |key: ItemKey| -> Option<String> {
+        tag.get_string(key)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::to_owned)
+    };
+
+    let mut roles: Vec<(Role, Vec<String>)> = Vec::new();
+    let mut composers = values(ItemKey::Composer);
+    composers.extend(values(ItemKey::Writer));
+    if !composers.is_empty() {
+        roles.push((Role::Composer, composers));
+    }
+    for (role, key) in [
+        (Role::Lyricist, ItemKey::Lyricist),
+        (Role::Conductor, ItemKey::Conductor),
+        (Role::Arranger, ItemKey::Arranger),
+        (Role::Producer, ItemKey::Producer),
+        (Role::Director, ItemKey::Director),
+        (Role::Engineer, ItemKey::Engineer),
+        (Role::Mixer, ItemKey::MixEngineer),
+        (Role::Remixer, ItemKey::Remixer),
+        (Role::DjMixer, ItemKey::MixDj),
+    ] {
+        let found = values(key);
+        if !found.is_empty() {
+            roles.push((role, found));
+        }
+    }
+
+    let performer_pairs = values(ItemKey::Performer)
+        .into_iter()
+        .map(|value| crate::tags::split_performer(&value))
+        .collect();
+
+    crate::tags::RawCredits {
+        artist: values(ItemKey::TrackArtist),
+        artists: values(ItemKey::TrackArtists),
+        album_artist: values(ItemKey::AlbumArtist),
+        album_artists: values(ItemKey::AlbumArtists),
+        sort_artist: single(ItemKey::TrackArtistSortOrder),
+        sort_album_artist: single(ItemKey::AlbumArtistSortOrder),
+        is_compilation: waveflow_core::scanner::extract_compilation_flag(tag),
+        roles,
+        performer_pairs,
+    }
+}
+fn extended_tags(tag: Option<&lofty::tag::Tag>) -> ExtendedTags {
+    let Some(tag) = tag else {
+        return ExtendedTags::default();
+    };
+    let text = |key: ItemKey| {
+        tag.get_string(key)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::to_owned)
+    };
+    // A tag written as several items rather than one `;`-joined string. Joined
+    // here so the column holds one spelling, and split again on the way out by
+    // the same helper that splits `moods`.
+    let joined = |key: ItemKey| {
+        let values = tag
+            .get_strings(key)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .collect::<Vec<_>>();
+        (!values.is_empty()).then(|| values.join("; "))
+    };
+    // ReplayGain tags carry their unit: `-7.32 dB`. Reading only the first
+    // token keeps the suffix from turning a valid measurement into none. A
+    // non-finite value is discarded rather than stored: it would travel all
+    // the way to a player as a volume adjustment.
+    let gain = |key: ItemKey| {
+        tag.get_string(key)
+            .and_then(|value| value.split_whitespace().next())
+            .and_then(|value| value.parse::<f64>().ok())
+            .filter(|value| value.is_finite())
+    };
+    ExtendedTags {
+        musicbrainz_recording_id: text(ItemKey::MusicBrainzRecordingId),
+        musicbrainz_release_id: text(ItemKey::MusicBrainzReleaseId),
+        musicbrainz_artist_id: text(ItemKey::MusicBrainzArtistId),
+        replay_gain_track_gain: gain(ItemKey::ReplayGainTrackGain),
+        replay_gain_track_peak: gain(ItemKey::ReplayGainTrackPeak),
+        replay_gain_album_gain: gain(ItemKey::ReplayGainAlbumGain),
+        replay_gain_album_peak: gain(ItemKey::ReplayGainAlbumPeak),
+        // Both spellings occur in the wild, and a fractional value is written
+        // often enough that parsing the whole string would drop it entirely.
+        bpm: text(ItemKey::IntegerBpm)
+            .or_else(|| text(ItemKey::Bpm))
+            .and_then(|value| {
+                value
+                    .split(['.', ','])
+                    .next()
+                    .and_then(|whole| whole.parse::<i64>().ok())
+            })
+            .filter(|value| *value > 0),
+        sort_title: text(ItemKey::TrackTitleSortOrder),
+        sort_album: text(ItemKey::AlbumTitleSortOrder),
+        sort_album_artist: text(ItemKey::AlbumArtistSortOrder),
+        sort_artist: text(ItemKey::TrackArtistSortOrder),
+        comment: text(ItemKey::Comment),
+        isrc: text(ItemKey::Isrc),
+        moods: text(ItemKey::Mood),
+        // Normalised to the two words the specification defines. The tag
+        // spells the same thing differently per format — MP4 writes the
+        // iTunes rating as 1 or 2, others write words — and a client only
+        // ever compares against `explicit` and `clean`. A tag that says
+        // "no advisory" is not a claim that the work is clean, so it maps to
+        // no value rather than to the second word.
+        explicit_status: text(ItemKey::ParentalAdvisory).and_then(|value| {
+            match value.to_ascii_lowercase().as_str() {
+                "1" | "true" | "explicit" => Some("explicit".to_owned()),
+                "2" | "clean" | "edited" => Some("clean".to_owned()),
+                _ => None,
+            }
+        }),
+        original_release_date: text(ItemKey::OriginalReleaseDate),
+        release_date: text(ItemKey::ReleaseDate).or_else(|| text(ItemKey::RecordingDate)),
+        release_types: joined(ItemKey::MusicBrainzReleaseType),
+        // `LABEL` is the tag Picard writes and the one the reference reads;
+        // `PUBLISHER` is the older spelling the same value arrives under on
+        // files tagged by anything else.
+        record_labels: joined(ItemKey::Label).or_else(|| joined(ItemKey::Publisher)),
+        disc_subtitle: text(ItemKey::SetSubtitle),
+    }
+}
+
+fn extract_lyrics(path: &Path, tag: Option<&lofty::tag::Tag>) -> Vec<LyricsInput> {
+    let mut found = Vec::new();
+    if let Some(tag) = tag {
+        for key in [ItemKey::UnsyncLyrics, ItemKey::Lyrics] {
+            if let Some(content) = tag.get_string(key) {
+                push_lyrics(&mut found, "embedded", content);
+            }
+        }
+    }
+    for (extension, source) in [("lrc", "sidecar_lrc"), ("txt", "sidecar_text")] {
+        let sidecar = path.with_extension(extension);
+        if let Some(content) = read_sidecar(&sidecar) {
+            push_lyrics(&mut found, source, &content);
+        }
+    }
+    found
+}
+
+fn push_lyrics(found: &mut Vec<LyricsInput>, source: &'static str, content: &str) {
+    let content = lyrics::normalize_content(content);
+    if content.trim().is_empty()
+        || found
+            .iter()
+            .any(|existing| existing.source == source && existing.content == content)
+    {
+        return;
+    }
+    let synced = lyrics::has_lrc_timestamps(&content);
+    found.push(LyricsInput {
+        source,
+        lang: "xxx".into(),
+        synced,
+        content,
+    });
+}
+
+fn read_sidecar(path: &Path) -> Option<String> {
+    let file = sidecar_options().open(path).ok()?;
+    let metadata = file.metadata().ok()?;
+    if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() > MAX_LYRICS_BYTES
+    {
+        return None;
+    }
+    let mut bytes = Vec::with_capacity(metadata.len() as usize);
+    file.take(MAX_LYRICS_BYTES + 1)
+        .read_to_end(&mut bytes)
+        .ok()?;
+    if bytes.len() as u64 > MAX_LYRICS_BYTES {
+        return None;
+    }
+    // Not `String::from_utf8`: lyrics written by a tool on a Chinese, Japanese
+    // or Korean Windows are in that system's code page, and a strict UTF-8
+    // read dropped them whole. The core decoder is the one the desktop reads
+    // the same files with, so both answer the same text for them.
+    Some(waveflow_core::text_encoding::decode(&bytes).into_owned())
+}
+
+fn lyrics_hash(entries: &[LyricsInput]) -> String {
+    let mut hasher = blake3::Hasher::new();
+    for entry in entries {
+        hasher.update(entry.source.as_bytes());
+        hasher.update(&[0]);
+        hasher.update(entry.lang.as_bytes());
+        hasher.update(&[u8::from(entry.synced)]);
+        hasher.update(entry.content.as_bytes());
+        hasher.update(&[0xff]);
+    }
+    hasher.finalize().to_hex().to_string()
+}
diff --git a/src/scanner/extract/tests.rs b/src/scanner/extract/tests.rs
new file mode 100644
index 00000000..4c635a3e
--- /dev/null
+++ b/src/scanner/extract/tests.rs
@@ -0,0 +1,134 @@
+//! Unit tests of the tag readers and the lyrics sidecars.
+
+use super::{extended_tags, read_sidecar, MAX_LYRICS_BYTES};
+use lofty::{
+    prelude::ItemKey,
+    tag::{Tag, TagType},
+};
+
+#[test]
+fn extended_tags_survive_the_shapes_real_files_use() {
+    // MP4 is the tag type whose lofty mapping covers every key this reads.
+    // The others cover a subset each — ID3v2 carries the recording MBID in
+    // a UFID frame rather than a text one, and Vorbis comments spell BPM
+    // only as `Bpm` — which is what the fallbacks in `extended_tags` are
+    // for. This test is about the parsing, so it uses the tag type that
+    // exercises all of it at once.
+    let mut tag = Tag::new(TagType::Mp4Ilst);
+    // ReplayGain is written with its unit, and a leading + is legal.
+    assert!(tag.insert_text(ItemKey::ReplayGainTrackGain, "-7.32 dB".into()));
+    assert!(tag.insert_text(ItemKey::ReplayGainAlbumGain, "+1.50 dB".into()));
+    assert!(tag.insert_text(ItemKey::ReplayGainTrackPeak, "0.988525".into()));
+    // BPM is often fractional even in the integer key.
+    assert!(tag.insert_text(ItemKey::IntegerBpm, "128.5".into()));
+    assert!(tag.insert_text(ItemKey::MusicBrainzRecordingId, "  rec-1  ".into()));
+    assert!(tag.insert_text(ItemKey::Comment, "   ".into()));
+    assert!(tag.insert_text(ItemKey::Isrc, "FRZ039800212".into()));
+    assert!(tag.insert_text(ItemKey::Mood, "Melancholic; Warm".into()));
+    assert!(tag.insert_text(ItemKey::ParentalAdvisory, "2".into()));
+    // The three sort keys, which the catalogue derives album and artist
+    // sort names from. A joined credit carries a joined sort tag, and the
+    // pairing happens where the names are split — what this pins is that
+    // all three arrive at all, under the tag type that spells them.
+    assert!(tag.insert_text(ItemKey::AlbumTitleSortOrder, "Night Sessions, The".into()));
+    assert!(tag.insert_text(ItemKey::AlbumArtistSortOrder, "Nocturnes, The".into()));
+    assert!(tag.insert_text(
+        ItemKey::TrackArtistSortOrder,
+        "Nocturnes, The; Reed, Ada".into()
+    ));
+    let extended = extended_tags(Some(&tag));
+    assert_eq!(extended.replay_gain_track_gain, Some(-7.32));
+    assert_eq!(extended.replay_gain_album_gain, Some(1.5));
+    assert_eq!(extended.replay_gain_track_peak, Some(0.988_525));
+    assert_eq!(extended.replay_gain_album_peak, None);
+    assert_eq!(extended.bpm, Some(128));
+    // Trimmed, and a tag holding only whitespace is no value at all
+    // rather than an empty one the presence rule would then report as
+    // meaningful.
+    assert_eq!(extended.musicbrainz_recording_id.as_deref(), Some("rec-1"));
+    assert_eq!(extended.comment, None);
+    assert_eq!(extended.isrc.as_deref(), Some("FRZ039800212"));
+    assert_eq!(extended.moods.as_deref(), Some("Melancholic; Warm"));
+    // The per-format spelling is normalised to the two words the
+    // specification defines; a client compares against nothing else.
+    assert_eq!(extended.explicit_status.as_deref(), Some("clean"));
+    assert_eq!(extended.sort_album.as_deref(), Some("Night Sessions, The"));
+    assert_eq!(
+        extended.sort_album_artist.as_deref(),
+        Some("Nocturnes, The")
+    );
+    assert_eq!(
+        extended.sort_artist.as_deref(),
+        Some("Nocturnes, The; Reed, Ada")
+    );
+
+    // Unparseable measurements are dropped rather than stored: a NaN gain
+    // would reach a player as a volume adjustment.
+    let mut broken = Tag::new(TagType::Mp4Ilst);
+    assert!(broken.insert_text(ItemKey::ReplayGainTrackGain, "loud".into()));
+    assert!(broken.insert_text(ItemKey::ReplayGainAlbumPeak, "NaN".into()));
+    assert!(broken.insert_text(ItemKey::IntegerBpm, "0".into()));
+    let broken = extended_tags(Some(&broken));
+    assert_eq!(broken.replay_gain_track_gain, None);
+    assert_eq!(broken.replay_gain_album_peak, None);
+    assert_eq!(broken.bpm, None);
+    // A tag saying "no advisory" is not a claim that the work is clean.
+    let mut neutral = Tag::new(TagType::Mp4Ilst);
+    assert!(neutral.insert_text(ItemKey::ParentalAdvisory, "0".into()));
+    assert_eq!(extended_tags(Some(&neutral)).explicit_status, None);
+
+    // The DSD path has no tag reader and must produce the same shape.
+    let absent = extended_tags(None);
+    assert_eq!(absent.musicbrainz_recording_id, None);
+    assert_eq!(absent.bpm, None);
+}
+
+#[test]
+fn sidecar_reader_rejects_invalid_files_and_symlinks() {
+    let temp = tempfile::tempdir().unwrap();
+    let valid = temp.path().join("valid.lrc");
+    std::fs::write(&valid, "[00:01]safe").unwrap();
+    assert_eq!(read_sidecar(&valid).as_deref(), Some("[00:01]safe"));
+
+    let oversized = temp.path().join("oversized.lrc");
+    std::fs::write(&oversized, vec![b'x'; MAX_LYRICS_BYTES as usize + 1]).unwrap();
+    assert!(read_sidecar(&oversized).is_none());
+
+    assert!(read_sidecar(temp.path()).is_none());
+
+    let link = temp.path().join("linked.lrc");
+    #[cfg(unix)]
+    let linked = std::os::unix::fs::symlink(&valid, &link).is_ok();
+    #[cfg(windows)]
+    let linked = std::os::windows::fs::symlink_file(&valid, &link).is_ok();
+    if linked {
+        assert!(read_sidecar(&link).is_none());
+    }
+}
+
+/// Lyrics saved by a tool on a Japanese Windows, in that system's code
+/// page. A strict UTF-8 read dropped the file whole, so the track had no
+/// lyrics at all.
+#[test]
+fn sidecar_lyrics_that_are_not_utf8_are_read_in_their_own_encoding() {
+    let temp = tempfile::tempdir().unwrap();
+    let text = "[00:01.00]今日はいい天気ですね、一緒に公園を散歩しましょう\n\
+                [00:05.50]湖に光が映って、風が森を通り抜ける音がする";
+    let (bytes, _, unmappable) = encoding_rs::SHIFT_JIS.encode(text);
+    assert!(!unmappable, "Shift_JIS holds the sample");
+    assert!(
+        std::str::from_utf8(&bytes).is_err(),
+        "the sample is not UTF-8 by accident"
+    );
+    let japanese = temp.path().join("japanese.lrc");
+    std::fs::write(&japanese, &bytes).unwrap();
+    assert_eq!(read_sidecar(&japanese).as_deref(), Some(text));
+
+    // A byte-order mark names the encoding and is not part of the text.
+    // Kept, it sat in front of the first timestamp.
+    let marked = temp.path().join("marked.lrc");
+    let mut bytes = vec![0xEF, 0xBB, 0xBF];
+    bytes.extend_from_slice(b"[00:01]marked");
+    std::fs::write(&marked, bytes).unwrap();
+    assert_eq!(read_sidecar(&marked).as_deref(), Some("[00:01]marked"));
+}
diff --git a/src/scanner/job.rs b/src/scanner/job.rs
new file mode 100644
index 00000000..1921c534
--- /dev/null
+++ b/src/scanner/job.rs
@@ -0,0 +1,387 @@
+//! One scan job from start to finish: the walk, the reads in batches, what
+//! each batch applies to the catalogue, and the progress it reports.
+
+use std::{collections::HashSet, path::PathBuf, sync::Arc};
+
+use futures_util::{stream, StreamExt};
+use uuid::Uuid;
+
+use super::discovery::{discover_audio, unclaimed, Discovery, Reach, Walked};
+use super::extract::{scan_file, Scanned};
+use super::{normalised_scope, ScanManager, ScanProgress};
+use crate::catalog::{ApplyOutcome, CatalogApply, LibraryRecord};
+
+impl ScanManager {
+    pub(super) async fn run(&self, scan_id: Uuid, library: LibraryRecord) -> anyhow::Result<()> {
+        let lock = self.library_lock(library.id);
+        let _library_guard = lock.lock().await;
+        // Read again under the lock rather than trusted from the queue: the
+        // library may have been moved, had its links setting changed, or been
+        // deleted since this job was queued (RFC-021 decision 5).
+        let Some(settings) = self.db.library_scan_settings(library.id).await? else {
+            tracing::info!(library_id = %library.id, %scan_id, "the library was deleted before its scan ran");
+            return Ok(());
+        };
+        let library = settings.library;
+        tokio::fs::create_dir_all(&self.artwork_dir).await?;
+        let root = tokio::fs::canonicalize(&library.root_path).await?;
+        let follow_links = settings.follow_links;
+        // The folders a followed link may reach outside the root, and every
+        // other library's root, which none may reach into. Resolved when the
+        // walk starts, on the blocking pool with it, so a mount that appeared
+        // since the boot counts, one that went does not, and one that hangs
+        // holds no async worker.
+        let (link_roots, other_roots) = if follow_links && !self.link_roots.is_empty() {
+            let others = self
+                .db
+                .all_libraries()
+                .await?
+                .into_iter()
+                .filter(|other| other.id != library.id)
+                .map(|other| other.root_path)
+                .collect::<Vec<_>>();
+            (Some(self.link_roots.clone()), others)
+        } else {
+            (None, Vec::new())
+        };
+        // Read before the walk is chosen, not after it: a scan that died
+        // halfway left the request standing, and the run picking up after it
+        // has to honour a request it never saw made. A scoped walk is no
+        // answer to it — it would record a partial walk as the full one and
+        // clear the request — so a pending full scan walks everything.
+        let full = self.db.full_scan_requested(library.id).await?;
+        if full {
+            tracing::info!(library_id = %library.id, "scanning every file, skipping nothing");
+        }
+        // Only a walk that reads no link is ever scoped: a folder reached
+        // through a link is named by its target, and the watcher names the
+        // path it saw, so the two could not be told to agree.
+        let scope = match self.db.scan_scope(scan_id).await? {
+            Some(scope) if !follow_links && !full => normalised_scope(&scope),
+            _ => None,
+        };
+        if let Some(scope) = scope.as_ref() {
+            tracing::info!(
+                library_id = %library.id,
+                folders = scope.len(),
+                "scanning the folders the watcher saw change"
+            );
+        }
+        let Discovery {
+            paths,
+            unreadable,
+            incomplete,
+            excluded,
+            skipped_links,
+        } = tokio::task::spawn_blocking({
+            let root = root.clone();
+            let scope = scope.clone();
+            move || {
+                let link_roots = link_roots.map(|roots| roots.resolved()).unwrap_or_default();
+                let libraries: Vec<PathBuf> = other_roots
+                    .iter()
+                    .filter_map(|other| std::fs::canonicalize(other).ok())
+                    .collect();
+                discover_audio(
+                    &Reach {
+                        root: &root,
+                        follow_links,
+                        link_roots: &link_roots,
+                        libraries: &libraries,
+                    },
+                    scope.as_deref(),
+                )
+            }
+        })
+        .await??;
+        let unreadable_folders: Vec<String> = unreadable
+            .iter()
+            .map(|folder| folder.folder.clone())
+            .collect();
+        let discovered: HashSet<String> =
+            paths.iter().map(|(_, relative)| relative.clone()).collect();
+        self.db
+            .start_walked_scan_job(
+                scan_id,
+                paths.len() as i64,
+                full,
+                excluded as i64,
+                skipped_links as i64,
+            )
+            .await?;
+
+        // What the catalogue already knows, read once: the pre-check compares
+        // against it before a file is opened (RFC-018 decision 1).
+        let facts = Arc::new(self.db.track_skip_facts(library.id).await?);
+        let artwork_dir = self.artwork_dir.clone();
+        // In path order, as they finish, a few batches at most in memory
+        // (RFC-018 decision 2): `buffered` keeps the order `paths` has, so the
+        // outcome is the same however the extractions interleave.
+        let mut scanned = stream::iter(paths.into_iter().map(|(path, relative)| {
+            let artwork = artwork_dir.clone();
+            let facts = Arc::clone(&facts);
+            async move {
+                let relative: anyhow::Result<String> = Ok(relative);
+                let known = relative
+                    .as_ref()
+                    .ok()
+                    .and_then(|relative| facts.get(relative))
+                    .cloned();
+                let result =
+                    tokio::task::spawn_blocking(move || scan_file(&path, &artwork, known, full))
+                        .await;
+                (relative, result)
+            }
+        }))
+        .buffered(self.parallelism)
+        .chunks(25);
+
+        let mut progress = ScanProgress {
+            scan_id,
+            library_id: library.id,
+            status: "running".into(),
+            total: discovered.len(),
+            processed: 0,
+            added: 0,
+            updated: 0,
+            moved: 0,
+            skipped: 0,
+            unavailable: 0,
+            errors: 0,
+            excluded: excluded as i64,
+            skipped_links: skipped_links as i64,
+            current_path: None,
+            message: None,
+        };
+
+        // A folder the walk could not read is reported, and its tracks are left
+        // as they are below (RFC-018 decision 3). So is one whose ignore file
+        // the walk could not use (RFC-021 decision 1), with its own reason.
+        if !unreadable.is_empty() {
+            progress.errors += unreadable.len() as i64;
+            let errors: Vec<(String, String)> = unreadable
+                .iter()
+                .map(|folder| (folder.folder.clone(), folder.reason.to_owned()))
+                .collect();
+            self.db.add_scan_errors(scan_id, &errors).await?;
+            // Written now, not left to the batches: a library whose only
+            // content sits under the unreadable folder has no batch at all.
+            self.tick(&progress).await?;
+        }
+
+        let walked = Walked {
+            discovered: &discovered,
+            unreadable: &unreadable_folders,
+            incomplete,
+            scope: scope.as_deref(),
+        };
+        while let Some(batch) = scanned.next().await {
+            let mut applies = Vec::new();
+            let mut seen = Vec::new();
+            let mut errors = Vec::new();
+            let mut claimed_relocations = HashSet::new();
+            let mut hints = Vec::new();
+            let mut signatures = Vec::new();
+            for (relative, task_result) in batch {
+                progress.processed += 1;
+                let task_result = match task_result {
+                    // Unchanged, and never opened.
+                    Ok(Scanned::Skipped(id)) => {
+                        seen.push(id);
+                        progress.skipped += 1;
+                        continue;
+                    }
+                    Ok(Scanned::Read(result, signature)) => {
+                        // Only a read that succeeded records what it read: a
+                        // failed one must be tried again, sidecars included.
+                        if let (Ok(relative), Ok(_), Some(signature)) =
+                            (&relative, result.as_ref(), signature)
+                        {
+                            signatures.push((relative.clone(), signature));
+                        }
+                        Ok(*result)
+                    }
+                    Err(error) => Err(error),
+                };
+                match (relative, task_result) {
+                    (Ok(relative), Ok(Ok(input))) => {
+                        let mut input = input;
+                        progress.current_path = Some(relative.clone());
+                        input.relative_path = relative.clone();
+                        let existing = self
+                            .db
+                            .existing_track_by_path(library.id, &relative)
+                            .await?;
+                        if let Some(existing) = existing.as_ref() {
+                            if !full
+                                && existing.file_size == input.file_size
+                                && existing.modified_at == input.modified_at
+                                && existing.quick_hash == input.quick_hash
+                                && existing.full_hash == input.full_hash
+                                && existing.lyrics_hash.as_deref() == Some(&input.lyrics_hash)
+                                && existing.available
+                            {
+                                // Skipped, but its hint may predate the
+                                // column. Computed only while it is missing,
+                                // so the scan after this one pays nothing.
+                                if existing.pid.is_none() {
+                                    hints.push((
+                                        existing.id,
+                                        crate::catalog::track_pid(
+                                            self.db.pid(),
+                                            library.id,
+                                            &input,
+                                        ),
+                                    ));
+                                }
+                                seen.push(existing.id);
+                                progress.skipped += 1;
+                                continue;
+                            }
+                        }
+                        let mut moved = false;
+                        let existing_id = if let Some(existing) = existing {
+                            Some(existing.id)
+                        } else {
+                            // Content first: a byte-identical file under a new
+                            // path is the same file, and nothing else needs to
+                            // be consulted.
+                            let mut missing = unclaimed(
+                                self.db
+                                    .relocation_candidates(library.id, &input.full_hash)
+                                    .await?,
+                                &walked,
+                                &claimed_relocations,
+                            );
+                            if missing.is_empty() {
+                                // The bytes changed as well as the path — a
+                                // re-encode, typically. The tags are the only
+                                // thing left that can say the two files are
+                                // one, so the hint is asked, and only here:
+                                // where the hash spoke, it was believed.
+                                missing = unclaimed(
+                                    self.db
+                                        .relocation_candidates_by_pid(
+                                            library.id,
+                                            crate::catalog::track_pid(
+                                                self.db.pid(),
+                                                library.id,
+                                                &input,
+                                            ),
+                                        )
+                                        .await?,
+                                    &walked,
+                                    &claimed_relocations,
+                                );
+                            }
+                            if missing.len() == 1 {
+                                moved = true;
+                                claimed_relocations.insert(missing[0].id);
+                                Some(missing[0].id)
+                            } else {
+                                None
+                            }
+                        };
+                        applies.push(CatalogApply {
+                            input,
+                            existing_id,
+                            moved,
+                            // A scan is nobody's request in particular.
+                            origin_device_id: None,
+                        });
+                    }
+                    (relative, result) => {
+                        progress.errors += 1;
+                        let path = relative.unwrap_or_else(|_| "<invalid-relative-path>".into());
+                        let message = match result {
+                            Ok(Err(error)) => error,
+                            Err(error) => format!("extract worker failed: {error}"),
+                            Ok(Ok(_)) => "relative path failed".into(),
+                        };
+                        progress.current_path = Some(path.clone());
+                        errors.push((path, message));
+                    }
+                }
+            }
+            self.db.mark_tracks_seen(&seen, scan_id).await?;
+            self.db.backfill_track_pids(&hints).await?;
+            for outcome in self
+                .db
+                .apply_catalog_tracks(library.id, scan_id, &applies)
+                .await?
+            {
+                match outcome {
+                    ApplyOutcome::Added => progress.added += 1,
+                    ApplyOutcome::Updated => progress.updated += 1,
+                    ApplyOutcome::Moved => progress.moved += 1,
+                }
+            }
+            self.db
+                .set_sidecar_signatures(library.id, &signatures)
+                .await?;
+            self.db.add_scan_errors(scan_id, &errors).await?;
+            self.tick(&progress).await?;
+        }
+
+        self.db
+            .mark_tracks_under_seen(library.id, &unreadable_folders, scan_id)
+            .await?;
+        // A walk error that named no path leaves no folder to spare, so
+        // nothing this walk missed can be called missing.
+        progress.unavailable = if incomplete {
+            tracing::warn!(
+                library_id = %library.id,
+                "the walk could not say what it failed to read; nothing is marked missing this scan"
+            );
+            0
+        } else {
+            self.db
+                .mark_unseen_unavailable_within(library.id, scan_id, scope.as_deref())
+                .await?
+        };
+        // After availability is settled, not before: the album and artist
+        // identifiers are a majority vote over the tracks that are still there,
+        // so a file that vanished must stop voting first.
+        // Sort names first: the derivation pass closes by indexing every
+        // artist name together with its sort name, so that name has to be
+        // settled before it is read.
+        self.db.consolidate_sort_names(library.id).await?;
+        self.db.consolidate_catalog_derivations(library.id).await?;
+        self.db
+            .finish_scan_job(scan_id, progress.unavailable)
+            .await?;
+        progress.status = "completed".into();
+        progress.current_path = None;
+        self.publish(progress);
+        Ok(())
+    }
+
+    async fn tick(&self, progress: &ScanProgress) -> Result<(), sqlx::Error> {
+        if progress.processed == progress.total || progress.processed.is_multiple_of(25) {
+            self.db
+                .update_scan_job(
+                    scan_id(progress),
+                    progress.processed as i64,
+                    progress.added,
+                    progress.updated,
+                    progress.moved,
+                    progress.skipped,
+                    progress.errors,
+                    progress.current_path.as_deref(),
+                )
+                .await?;
+            self.publish(progress.clone());
+        }
+        Ok(())
+    }
+
+    pub(super) fn publish(&self, progress: ScanProgress) {
+        if let Some(sender) = self.events.get(&progress.scan_id) {
+            let _ = sender.send(progress);
+        }
+    }
+}
+
+fn scan_id(progress: &ScanProgress) -> Uuid {
+    progress.scan_id
+}
diff --git a/src/scanner/mod.rs b/src/scanner/mod.rs
index 81ddbcfb..e5a7fb5a 100644
--- a/src/scanner/mod.rs
+++ b/src/scanner/mod.rs
@@ -1,34 +1,24 @@
 //! Server-authoritative filesystem scanner with SSE-ready progress events.
 
-use std::{
-    collections::HashSet,
-    fs,
-    io::Read,
-    path::{Path, PathBuf},
-    sync::Arc,
-    time::UNIX_EPOCH,
-};
+mod discovery;
+mod extract;
+mod job;
+
+pub use discovery::IGNORE_FILE;
+pub(crate) use discovery::{normalised_scope, MAX_SCOPE_FOLDERS};
+pub(crate) use extract::extract_file;
+
+use std::{collections::HashSet, path::PathBuf, sync::Arc};
 
 use dashmap::DashMap;
-use futures_util::{stream, StreamExt};
-use lofty::{
-    file::TaggedFileExt,
-    prelude::{Accessor, AudioFile, ItemKey},
-};
 use tokio::sync::{broadcast, watch, Mutex};
 use uuid::Uuid;
-use walkdir::WalkDir;
 
 use crate::{
-    catalog::{
-        ApplyOutcome, ArtworkInput, CatalogApply, CatalogTrackInput, LibraryRecord, ScanJobRecord,
-    },
+    catalog::{CatalogTrackInput, LibraryRecord, ScanJobRecord},
     database::Database,
-    lyrics::{self, LyricsInput},
 };
 
-const MAX_LYRICS_BYTES: u64 = 1024 * 1024;
-
 /// One reading of a scan in flight, as it travels between the scanning task and
 /// whoever is watching.
 ///
@@ -372,1888 +362,4 @@ impl ScanManager {
             Err(error) => tracing::warn!(error = %error, "could not list libraries for scanner"),
         }
     }
-
-    async fn run(&self, scan_id: Uuid, library: LibraryRecord) -> anyhow::Result<()> {
-        let lock = self.library_lock(library.id);
-        let _library_guard = lock.lock().await;
-        // Read again under the lock rather than trusted from the queue: the
-        // library may have been moved, had its links setting changed, or been
-        // deleted since this job was queued (RFC-021 decision 5).
-        let Some(settings) = self.db.library_scan_settings(library.id).await? else {
-            tracing::info!(library_id = %library.id, %scan_id, "the library was deleted before its scan ran");
-            return Ok(());
-        };
-        let library = settings.library;
-        tokio::fs::create_dir_all(&self.artwork_dir).await?;
-        let root = tokio::fs::canonicalize(&library.root_path).await?;
-        let follow_links = settings.follow_links;
-        // The folders a followed link may reach outside the root, and every
-        // other library's root, which none may reach into. Resolved when the
-        // walk starts, on the blocking pool with it, so a mount that appeared
-        // since the boot counts, one that went does not, and one that hangs
-        // holds no async worker.
-        let (link_roots, other_roots) = if follow_links && !self.link_roots.is_empty() {
-            let others = self
-                .db
-                .all_libraries()
-                .await?
-                .into_iter()
-                .filter(|other| other.id != library.id)
-                .map(|other| other.root_path)
-                .collect::<Vec<_>>();
-            (Some(self.link_roots.clone()), others)
-        } else {
-            (None, Vec::new())
-        };
-        // Read before the walk is chosen, not after it: a scan that died
-        // halfway left the request standing, and the run picking up after it
-        // has to honour a request it never saw made. A scoped walk is no
-        // answer to it — it would record a partial walk as the full one and
-        // clear the request — so a pending full scan walks everything.
-        let full = self.db.full_scan_requested(library.id).await?;
-        if full {
-            tracing::info!(library_id = %library.id, "scanning every file, skipping nothing");
-        }
-        // Only a walk that reads no link is ever scoped: a folder reached
-        // through a link is named by its target, and the watcher names the
-        // path it saw, so the two could not be told to agree.
-        let scope = match self.db.scan_scope(scan_id).await? {
-            Some(scope) if !follow_links && !full => normalised_scope(&scope),
-            _ => None,
-        };
-        if let Some(scope) = scope.as_ref() {
-            tracing::info!(
-                library_id = %library.id,
-                folders = scope.len(),
-                "scanning the folders the watcher saw change"
-            );
-        }
-        let Discovery {
-            paths,
-            unreadable,
-            incomplete,
-            excluded,
-            skipped_links,
-        } = tokio::task::spawn_blocking({
-            let root = root.clone();
-            let scope = scope.clone();
-            move || {
-                let link_roots = link_roots.map(|roots| roots.resolved()).unwrap_or_default();
-                let libraries: Vec<PathBuf> = other_roots
-                    .iter()
-                    .filter_map(|other| std::fs::canonicalize(other).ok())
-                    .collect();
-                discover_audio(
-                    &Reach {
-                        root: &root,
-                        follow_links,
-                        link_roots: &link_roots,
-                        libraries: &libraries,
-                    },
-                    scope.as_deref(),
-                )
-            }
-        })
-        .await??;
-        let unreadable_folders: Vec<String> = unreadable
-            .iter()
-            .map(|folder| folder.folder.clone())
-            .collect();
-        let discovered: HashSet<String> =
-            paths.iter().map(|(_, relative)| relative.clone()).collect();
-        self.db
-            .start_walked_scan_job(
-                scan_id,
-                paths.len() as i64,
-                full,
-                excluded as i64,
-                skipped_links as i64,
-            )
-            .await?;
-
-        // What the catalogue already knows, read once: the pre-check compares
-        // against it before a file is opened (RFC-018 decision 1).
-        let facts = Arc::new(self.db.track_skip_facts(library.id).await?);
-        let artwork_dir = self.artwork_dir.clone();
-        // In path order, as they finish, a few batches at most in memory
-        // (RFC-018 decision 2): `buffered` keeps the order `paths` has, so the
-        // outcome is the same however the extractions interleave.
-        let mut scanned = stream::iter(paths.into_iter().map(|(path, relative)| {
-            let artwork = artwork_dir.clone();
-            let facts = Arc::clone(&facts);
-            async move {
-                let relative: anyhow::Result<String> = Ok(relative);
-                let known = relative
-                    .as_ref()
-                    .ok()
-                    .and_then(|relative| facts.get(relative))
-                    .cloned();
-                let result =
-                    tokio::task::spawn_blocking(move || scan_file(&path, &artwork, known, full))
-                        .await;
-                (relative, result)
-            }
-        }))
-        .buffered(self.parallelism)
-        .chunks(25);
-
-        let mut progress = ScanProgress {
-            scan_id,
-            library_id: library.id,
-            status: "running".into(),
-            total: discovered.len(),
-            processed: 0,
-            added: 0,
-            updated: 0,
-            moved: 0,
-            skipped: 0,
-            unavailable: 0,
-            errors: 0,
-            excluded: excluded as i64,
-            skipped_links: skipped_links as i64,
-            current_path: None,
-            message: None,
-        };
-
-        // A folder the walk could not read is reported, and its tracks are left
-        // as they are below (RFC-018 decision 3). So is one whose ignore file
-        // the walk could not use (RFC-021 decision 1), with its own reason.
-        if !unreadable.is_empty() {
-            progress.errors += unreadable.len() as i64;
-            let errors: Vec<(String, String)> = unreadable
-                .iter()
-                .map(|folder| (folder.folder.clone(), folder.reason.to_owned()))
-                .collect();
-            self.db.add_scan_errors(scan_id, &errors).await?;
-            // Written now, not left to the batches: a library whose only
-            // content sits under the unreadable folder has no batch at all.
-            self.tick(&progress).await?;
-        }
-
-        let walked = Walked {
-            discovered: &discovered,
-            unreadable: &unreadable_folders,
-            incomplete,
-            scope: scope.as_deref(),
-        };
-        while let Some(batch) = scanned.next().await {
-            let mut applies = Vec::new();
-            let mut seen = Vec::new();
-            let mut errors = Vec::new();
-            let mut claimed_relocations = HashSet::new();
-            let mut hints = Vec::new();
-            let mut signatures = Vec::new();
-            for (relative, task_result) in batch {
-                progress.processed += 1;
-                let task_result = match task_result {
-                    // Unchanged, and never opened.
-                    Ok(Scanned::Skipped(id)) => {
-                        seen.push(id);
-                        progress.skipped += 1;
-                        continue;
-                    }
-                    Ok(Scanned::Read(result, signature)) => {
-                        // Only a read that succeeded records what it read: a
-                        // failed one must be tried again, sidecars included.
-                        if let (Ok(relative), Ok(_), Some(signature)) =
-                            (&relative, result.as_ref(), signature)
-                        {
-                            signatures.push((relative.clone(), signature));
-                        }
-                        Ok(*result)
-                    }
-                    Err(error) => Err(error),
-                };
-                match (relative, task_result) {
-                    (Ok(relative), Ok(Ok(input))) => {
-                        let mut input = input;
-                        progress.current_path = Some(relative.clone());
-                        input.relative_path = relative.clone();
-                        let existing = self
-                            .db
-                            .existing_track_by_path(library.id, &relative)
-                            .await?;
-                        if let Some(existing) = existing.as_ref() {
-                            if !full
-                                && existing.file_size == input.file_size
-                                && existing.modified_at == input.modified_at
-                                && existing.quick_hash == input.quick_hash
-                                && existing.full_hash == input.full_hash
-                                && existing.lyrics_hash.as_deref() == Some(&input.lyrics_hash)
-                                && existing.available
-                            {
-                                // Skipped, but its hint may predate the
-                                // column. Computed only while it is missing,
-                                // so the scan after this one pays nothing.
-                                if existing.pid.is_none() {
-                                    hints.push((
-                                        existing.id,
-                                        crate::catalog::track_pid(
-                                            self.db.pid(),
-                                            library.id,
-                                            &input,
-                                        ),
-                                    ));
-                                }
-                                seen.push(existing.id);
-                                progress.skipped += 1;
-                                continue;
-                            }
-                        }
-                        let mut moved = false;
-                        let existing_id = if let Some(existing) = existing {
-                            Some(existing.id)
-                        } else {
-                            // Content first: a byte-identical file under a new
-                            // path is the same file, and nothing else needs to
-                            // be consulted.
-                            let mut missing = unclaimed(
-                                self.db
-                                    .relocation_candidates(library.id, &input.full_hash)
-                                    .await?,
-                                &walked,
-                                &claimed_relocations,
-                            );
-                            if missing.is_empty() {
-                                // The bytes changed as well as the path — a
-                                // re-encode, typically. The tags are the only
-                                // thing left that can say the two files are
-                                // one, so the hint is asked, and only here:
-                                // where the hash spoke, it was believed.
-                                missing = unclaimed(
-                                    self.db
-                                        .relocation_candidates_by_pid(
-                                            library.id,
-                                            crate::catalog::track_pid(
-                                                self.db.pid(),
-                                                library.id,
-                                                &input,
-                                            ),
-                                        )
-                                        .await?,
-                                    &walked,
-                                    &claimed_relocations,
-                                );
-                            }
-                            if missing.len() == 1 {
-                                moved = true;
-                                claimed_relocations.insert(missing[0].id);
-                                Some(missing[0].id)
-                            } else {
-                                None
-                            }
-                        };
-                        applies.push(CatalogApply {
-                            input,
-                            existing_id,
-                            moved,
-                            // A scan is nobody's request in particular.
-                            origin_device_id: None,
-                        });
-                    }
-                    (relative, result) => {
-                        progress.errors += 1;
-                        let path = relative.unwrap_or_else(|_| "<invalid-relative-path>".into());
-                        let message = match result {
-                            Ok(Err(error)) => error,
-                            Err(error) => format!("extract worker failed: {error}"),
-                            Ok(Ok(_)) => "relative path failed".into(),
-                        };
-                        progress.current_path = Some(path.clone());
-                        errors.push((path, message));
-                    }
-                }
-            }
-            self.db.mark_tracks_seen(&seen, scan_id).await?;
-            self.db.backfill_track_pids(&hints).await?;
-            for outcome in self
-                .db
-                .apply_catalog_tracks(library.id, scan_id, &applies)
-                .await?
-            {
-                match outcome {
-                    ApplyOutcome::Added => progress.added += 1,
-                    ApplyOutcome::Updated => progress.updated += 1,
-                    ApplyOutcome::Moved => progress.moved += 1,
-                }
-            }
-            self.db
-                .set_sidecar_signatures(library.id, &signatures)
-                .await?;
-            self.db.add_scan_errors(scan_id, &errors).await?;
-            self.tick(&progress).await?;
-        }
-
-        self.db
-            .mark_tracks_under_seen(library.id, &unreadable_folders, scan_id)
-            .await?;
-        // A walk error that named no path leaves no folder to spare, so
-        // nothing this walk missed can be called missing.
-        progress.unavailable = if incomplete {
-            tracing::warn!(
-                library_id = %library.id,
-                "the walk could not say what it failed to read; nothing is marked missing this scan"
-            );
-            0
-        } else {
-            self.db
-                .mark_unseen_unavailable_within(library.id, scan_id, scope.as_deref())
-                .await?
-        };
-        // After availability is settled, not before: the album and artist
-        // identifiers are a majority vote over the tracks that are still there,
-        // so a file that vanished must stop voting first.
-        // Sort names first: the derivation pass closes by indexing every
-        // artist name together with its sort name, so that name has to be
-        // settled before it is read.
-        self.db.consolidate_sort_names(library.id).await?;
-        self.db.consolidate_catalog_derivations(library.id).await?;
-        self.db
-            .finish_scan_job(scan_id, progress.unavailable)
-            .await?;
-        progress.status = "completed".into();
-        progress.current_path = None;
-        self.publish(progress);
-        Ok(())
-    }
-
-    async fn tick(&self, progress: &ScanProgress) -> Result<(), sqlx::Error> {
-        if progress.processed == progress.total || progress.processed.is_multiple_of(25) {
-            self.db
-                .update_scan_job(
-                    scan_id(progress),
-                    progress.processed as i64,
-                    progress.added,
-                    progress.updated,
-                    progress.moved,
-                    progress.skipped,
-                    progress.errors,
-                    progress.current_path.as_deref(),
-                )
-                .await?;
-            self.publish(progress.clone());
-        }
-        Ok(())
-    }
-
-    fn publish(&self, progress: ScanProgress) {
-        if let Some(sender) = self.events.get(&progress.scan_id) {
-            let _ = sender.send(progress);
-        }
-    }
-}
-
-fn scan_id(progress: &ScanProgress) -> Uuid {
-    progress.scan_id
-}
-
-/// What a scan does with one discovered file.
-enum Scanned {
-    /// Unchanged since the last scan: skipped without being opened.
-    Skipped(Uuid),
-    /// Read, with the sidecar signature to record once it is applied.
-    /// `None` when a sidecar could not be opened: nothing is recorded, so the
-    /// file is read again until it can be.
-    Read(Box<Result<CatalogTrackInput, String>>, Option<String>),
-}
-
-/// The pre-check, then the read (RFC-018 decision 1).
-///
-/// A file whose size, modification time and sidecar signature match what the
-/// catalogue holds, on an available track that already has its relocation
-/// hint, is skipped from a `stat` alone. Anything else, and every file on a
-/// full scan, is read as before.
-fn scan_file(
-    path: &Path,
-    artwork_dir: &Path,
-    known: Option<crate::catalog::SkipFacts>,
-    full: bool,
-) -> Scanned {
-    let signature = sidecar_signature(path);
-    if let Some(known) = known.filter(|_| !full) {
-        let unchanged = file_stamp(path).is_some_and(|(size, modified_at)| {
-            size == known.file_size && modified_at == known.modified_at
-        }) && known.available
-            && known.has_pid
-            && signature.is_some()
-            && known.sidecar_signature == signature;
-        if unchanged {
-            return Scanned::Skipped(known.id);
-        }
-    }
-    Scanned::Read(Box::new(extract_file(path, artwork_dir)), signature)
-}
-
-/// A file's size and modification time, as `extract_file` records them.
-fn file_stamp(path: &Path) -> Option<(i64, i64)> {
-    let metadata = fs::metadata(path).ok()?;
-    let modified_at = metadata
-        .modified()
-        .ok()
-        .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
-        .map(|value| value.as_millis() as i64)
-        .unwrap_or(0);
-    Some((metadata.len() as i64, modified_at))
-}
-
-/// The two lyrics sidecars a scan reads beside an audio file, by size and
-/// modification time, absent ones as `-`:
-/// `lrc:<size>:<mtime_ms>|txt:<size>:<mtime_ms>`. Adding, editing or deleting
-/// either changes it; it is never empty.
-///
-/// `None` when a sidecar exists but cannot be opened. The read then goes ahead
-/// without its lyrics, and recording the signature would skip the file for as
-/// long as the sidecar's size and time stay put — a permission fixed later
-/// moves neither. With no signature the file is read on every scan until the
-/// sidecar can be.
-///
-/// Read without following links, and a sidecar that is not a regular file — a
-/// link, a FIFO, a folder — counts as absent, since `read_sidecar` would not
-/// read it either. Only a regular file is opened, and never in a way that can
-/// block.
-fn sidecar_signature(path: &Path) -> Option<String> {
-    let mut parts = Vec::with_capacity(2);
-    for extension in ["lrc", "txt"] {
-        let sidecar = path.with_extension(extension);
-        match fs::symlink_metadata(&sidecar) {
-            Ok(metadata) if metadata.is_file() => {
-                sidecar_options().open(&sidecar).ok()?;
-                let modified_at = metadata
-                    .modified()
-                    .ok()
-                    .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
-                    .map(|value| value.as_millis() as i64)
-                    .unwrap_or(0);
-                parts.push(format!("{extension}:{}:{modified_at}", metadata.len()));
-            }
-            _ => parts.push(format!("{extension}:-")),
-        }
-    }
-    Some(parts.join("|"))
-}
-
-/// How a sidecar is opened, for reading it and for checking that it can be:
-/// never through a link, and without blocking on a special file swapped in
-/// after it was looked at.
-fn sidecar_options() -> fs::OpenOptions {
-    let mut options = fs::OpenOptions::new();
-    options.read(true);
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::OpenOptionsExt;
-        options.custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK);
-    }
-    #[cfg(windows)]
-    {
-        use std::os::windows::fs::OpenOptionsExt;
-        // Open the reparse point itself so descriptor metadata can reject a
-        // symlink instead of validating one path and reading its later target.
-        const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
-        options.custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
-    }
-    options
-}
-
-/// The ignore file a folder may hold (RFC-021 decision 1).
-pub const IGNORE_FILE: &str = ".waveflowignore";
-
-/// Beyond this an ignore file is refused rather than read: a list of
-/// exclusions has no business being larger, and the walk reads one per folder.
-const MAX_IGNORE_BYTES: u64 = 64 * 1024;
-
-/// Names the walk never enters, whatever an ignore file says (RFC-021
-/// decision 1), beside every name beginning with a dot. Compared without
-/// regard to case: `$RECYCLE.BIN` is spelled several ways by the systems that
-/// write it.
-const BUILT_IN_EXCLUSIONS: [&str; 6] = [
-    "@eaDir",
-    "#recycle",
-    "#snapshot",
-    "$RECYCLE.BIN",
-    "System Volume Information",
-    "lost+found",
-];
-
-/// How many skipped links one scan names in the log, one line each, before it
-/// only counts the rest.
-const LOGGED_LINKS: usize = 20;
-
-/// Whether an entry below the root is left out by name. The root and the
-/// folders above it are never asked: a library may well live under a dot
-/// folder, and a temporary directory always does.
-fn built_in_exclusion(name: &std::ffi::OsStr, depth: usize, is_dir: bool) -> bool {
-    let name = name.to_string_lossy();
-    if name.starts_with('.') {
-        // Received files land here (RFC-008), and the scan is what keeps them
-        // in the catalogue after the upload that applied them.
-        return !(depth == 1 && is_dir && name == crate::services::uploads::MANAGED_DIR);
-    }
-    BUILT_IN_EXCLUSIONS
-        .iter()
-        .any(|excluded| excluded.eq_ignore_ascii_case(&name))
-}
-
-/// What one folder's ignore file says.
-enum Rules {
-    /// No file, or a root file with nothing in it.
-    None,
-    Matcher(ignore::gitignore::Gitignore),
-    /// An empty file below the root: the folder and everything under it.
-    ExcludeAll,
-    /// A file the walk cannot use, and why. Its folder counts as unreadable.
-    Unusable(&'static str),
-}
-
-/// Reads `dir`'s ignore file, if it has one. Never through a link, and never
-/// in a way that can block, as the lyrics sidecars are read.
-fn load_rules(dir: &Path, at_root: bool) -> Rules {
-    let file = dir.join(IGNORE_FILE);
-    let metadata = match fs::symlink_metadata(&file) {
-        Ok(metadata) => metadata,
-        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Rules::None,
-        Err(_) => return Rules::Unusable("its .waveflowignore could not be read"),
-    };
-    if !metadata.is_file() {
-        return Rules::Unusable("its .waveflowignore is not a regular file");
-    }
-    if metadata.len() > MAX_IGNORE_BYTES {
-        return Rules::Unusable("its .waveflowignore is larger than 64 KiB");
-    }
-    let Some(text) = sidecar_options().open(&file).ok().and_then(|opened| {
-        let mut bytes = Vec::new();
-        opened
-            .take(MAX_IGNORE_BYTES + 1)
-            .read_to_end(&mut bytes)
-            .ok()?;
-        (bytes.len() as u64 <= MAX_IGNORE_BYTES)
-            .then(|| String::from_utf8_lossy(&bytes).into_owned())
-    }) else {
-        return Rules::Unusable("its .waveflowignore could not be read");
-    };
-    let text = text.trim_start_matches('\u{feff}');
-    if text.trim().is_empty() {
-        // At the root an empty file excludes nothing: one stray file must not
-        // mark a whole library missing.
-        return if at_root {
-            Rules::None
-        } else {
-            Rules::ExcludeAll
-        };
-    }
-    let mut builder = ignore::gitignore::GitignoreBuilder::new(dir);
-    for line in text.lines() {
-        if builder.add_line(None, line).is_err() {
-            return Rules::Unusable("its .waveflowignore holds a pattern that cannot be read");
-        }
-    }
-    match builder.build() {
-        Ok(matcher) => Rules::Matcher(matcher),
-        Err(_) => Rules::Unusable("its .waveflowignore holds a pattern that cannot be read"),
-    }
-}
-
-/// Why the walk left a symbolic link behind (RFC-021 decision 3).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum SkippedLink {
-    /// The library does not follow links.
-    NotFollowed,
-    /// Its target lies outside the library root.
-    Outside,
-    /// Its target does not exist, or cannot be read.
-    Broken,
-    /// It leads back to one of its own ancestors.
-    Loop,
-}
-
-impl SkippedLink {
-    fn reason(self) -> &'static str {
-        match self {
-            Self::NotFollowed => "the library does not follow links",
-            Self::Outside => "its target is outside the library",
-            Self::Broken => "its target cannot be read",
-            Self::Loop => "it leads back to a folder above it",
-        }
-    }
-}
-
-/// A folder the walk could not read, relative to the root, and why.
-struct Unreadable {
-    folder: String,
-    reason: &'static str,
-}
-
-/// What the walk found: the audio files, in catalogue path order, each with
-/// the path it is read from and the path the catalogue knows it by, and the
-/// folders it could not read, relative to the root.
-struct Discovery {
-    paths: Vec<(PathBuf, String)>,
-    unreadable: Vec<Unreadable>,
-    /// An error named no path inside the root, so the walk cannot say which
-    /// tracks it missed: none may be marked missing.
-    incomplete: bool,
-    /// Entries left out by an exclusion, a folder counting once whatever it
-    /// holds (RFC-021 decision 2). They count as not discovered.
-    excluded: usize,
-    /// Symbolic links the walk did not follow (RFC-021 decision 3).
-    skipped_links: usize,
-}
-
-/// Where one walk may go: the library root, whether it follows links, and —
-/// when it does — the folders outside the root a link may reach into and the
-/// other libraries' roots no link may reach into (RFC-021, links outside the
-/// root). Every path in it is canonical.
-struct Reach<'a> {
-    root: &'a Path,
-    follow_links: bool,
-    link_roots: &'a [PathBuf],
-    libraries: &'a [PathBuf],
-}
-
-impl Reach<'_> {
-    /// Whether a followed link may lead to `target`, a canonical path.
-    fn admits_target(&self, target: &Path) -> bool {
-        target.starts_with(self.root)
-            || crate::link_roots::admits(self.link_roots, self.libraries, target)
-    }
-
-    /// What the walk reached at `path`: the canonical path to read it from,
-    /// and the path relative to the root the catalogue names it by.
-    ///
-    /// Without links, the path as walked. With links, a target inside the root
-    /// is named by its canonical path, so one file is one track however many
-    /// links name it (decision 3); a target in an allowed folder outside it has
-    /// no path inside the root, so it is named by the path the walk reached it
-    /// through — links included, which is why the stream check accepts a link
-    /// that resolves into an allowed folder. Anything else names nothing.
-    fn catalogue_name(&self, path: &Path) -> Option<(PathBuf, String)> {
-        if !self.follow_links {
-            return Some((path.to_path_buf(), relative_to(self.root, path)));
-        }
-        let canonical = fs::canonicalize(path).ok()?;
-        if canonical.starts_with(self.root) {
-            let name = relative_to(self.root, &canonical);
-            return Some((canonical, name));
-        }
-        (crate::link_roots::admits(self.link_roots, self.libraries, &canonical)
-            && path.starts_with(self.root))
-        .then(|| (canonical, relative_to(self.root, path)))
-    }
-}
-
-/// What the walk accumulates while `walkdir` decides, entry by entry, what to
-/// enter. Shared between the filter and the loop, hence the cell.
-#[derive(Default)]
-struct WalkState {
-    /// Each folder's ignore rules, by the path the walk sees it under.
-    rules: std::collections::HashMap<PathBuf, ignore::gitignore::Gitignore>,
-    unreadable: Vec<Unreadable>,
-    excluded: usize,
-    skipped_links: usize,
-    /// A folder could not be read and could not be named as the catalogue
-    /// names its tracks: no track may be marked missing.
-    incomplete: bool,
-}
-
-impl WalkState {
-    /// Records a folder the walk could not read, or could not use the rules
-    /// of, under the name its tracks carry in the catalogue (RFC-018
-    /// decision 3, RFC-021 decision 3).
-    ///
-    /// With links followed, a track is stored under its canonical path, and a
-    /// folder reached through a link has another name: spared under the
-    /// link's, its tracks would be marked missing anyway. So the folder is
-    /// named as the catalogue names what it holds; one that names nothing
-    /// leaves the walk incomplete.
-    fn unreadable(&mut self, reach: &Reach<'_>, path: &Path, reason: &'static str) {
-        match reach.catalogue_name(path).map(|(_, name)| name) {
-            Some(folder) => {
-                tracing::warn!(
-                    path = %folder,
-                    reason,
-                    "a folder in the library could not be used; its tracks are left as they are"
-                );
-                self.unreadable.push(Unreadable { folder, reason });
-            }
-            None => {
-                tracing::warn!(
-                    path = %relative_to(reach.root, path),
-                    reason,
-                    "a folder reached through a link could not be used, nor resolved; nothing is marked missing this scan"
-                );
-                self.incomplete = true;
-                self.unreadable.push(Unreadable {
-                    folder: "<unknown>".to_owned(),
-                    reason,
-                });
-            }
-        }
-    }
-
-    /// Whether an ignore file of a folder above `path` leaves it out. The
-    /// deepest file that has an opinion decides, as in git.
-    fn ignored(&self, root: &Path, path: &Path, is_dir: bool) -> bool {
-        let mut folder = path.parent();
-        while let Some(current) = folder {
-            if let Some(rules) = self.rules.get(current) {
-                let matched = rules.matched(path, is_dir);
-                if matched.is_ignore() {
-                    return true;
-                }
-                if matched.is_whitelist() {
-                    return false;
-                }
-            }
-            if current == root {
-                break;
-            }
-            folder = current.parent();
-        }
-        false
-    }
-
-    fn skip_link(&mut self, path: &str, why: SkippedLink) {
-        self.skipped_links += 1;
-        if self.skipped_links <= LOGGED_LINKS {
-            tracing::info!(path = %path, reason = why.reason(), "a symbolic link in the library was skipped");
-        }
-    }
-}
-
-/// A path relative to the root, as the catalogue and the log spell it.
-fn relative_to(root: &Path, path: &Path) -> String {
-    path.strip_prefix(root)
-        .map(|path| path.to_string_lossy().replace('\\', "/"))
-        .unwrap_or_else(|_| "<outside the library>".to_owned())
-}
-
-/// The walk's decision on one entry below where it started: enter it, or
-/// leave it. `base` is how deep below the root the walk started, so the rules
-/// that depend on depth read the depth below the root.
-fn admit(
-    entry: &walkdir::DirEntry,
-    reach: &Reach<'_>,
-    base: usize,
-    walk: &std::cell::RefCell<WalkState>,
-) -> bool {
-    if entry.depth() == 0 {
-        return true;
-    }
-    let root = reach.root;
-    let mut walk = walk.borrow_mut();
-    let path = entry.path();
-    // Followed, `file_type` is the target's; not followed, it is the link's.
-    let is_dir = entry.file_type().is_dir();
-    let is_link = if reach.follow_links {
-        entry.path_is_symlink()
-    } else {
-        entry.file_type().is_symlink()
-    };
-    // The rules themselves: read with their folder, never counted as left out.
-    if entry.file_name() == IGNORE_FILE {
-        return false;
-    }
-    // By the name the walk sees, a link's own included (decision 1).
-    if built_in_exclusion(entry.file_name(), base + entry.depth(), is_dir)
-        || walk.ignored(root, path, is_dir)
-    {
-        walk.excluded += 1;
-        tracing::debug!(path = %relative_to(root, path), "left out of the scan");
-        return false;
-    }
-    if is_link {
-        let skipped = if !reach.follow_links {
-            Some(SkippedLink::NotFollowed)
-        } else {
-            match fs::canonicalize(path) {
-                Ok(target) if reach.admits_target(&target) => None,
-                Ok(_) => Some(SkippedLink::Outside),
-                Err(_) => Some(SkippedLink::Broken),
-            }
-        };
-        if let Some(why) = skipped {
-            walk.skip_link(&relative_to(root, path), why);
-            return false;
-        }
-    } else if is_dir && reach.follow_links && !reach.link_roots.is_empty() {
-        // A folder that is no link itself, reached through one into an
-        // allowed folder, may be another library's root: the link that led
-        // here stops at it, and is counted as skipped there.
-        match fs::canonicalize(path) {
-            Ok(target) if reach.admits_target(&target) => {}
-            _ => {
-                walk.skip_link(&relative_to(root, path), SkippedLink::Outside);
-                return false;
-            }
-        }
-    }
-    if is_dir {
-        match load_rules(path, false) {
-            Rules::None => {}
-            Rules::Matcher(rules) => {
-                walk.rules.insert(path.to_path_buf(), rules);
-            }
-            Rules::ExcludeAll => {
-                walk.excluded += 1;
-                tracing::debug!(path = %relative_to(root, path), "left out of the scan by an empty ignore file");
-                return false;
-            }
-            Rules::Unusable(reason) => {
-                walk.unreadable(reach, path, reason);
-                return false;
-            }
-        }
-    }
-    true
-}
-
-/// How many folders a scoped scan walks at most. A watcher that saw changes in
-/// more than this is told to walk the whole library instead: a list that long
-/// says the changes were everywhere, and walking it folder by folder would
-/// cost more than the walk it was meant to save.
-pub(crate) const MAX_SCOPE_FOLDERS: usize = 64;
-
-/// A scope as a scoped walk may use it: folders relative to the root, spelled
-/// with `/`, none of them nested in another, at most [`MAX_SCOPE_FOLDERS`].
-///
-/// `None` — the whole library — for anything that is not plainly such a list:
-/// an empty folder (the root itself), a `..`, an absolute path, too many
-/// folders. Walking more than asked is always safe; walking less is not.
-pub(crate) fn normalised_scope(scope: &[String]) -> Option<Vec<String>> {
-    let mut folders = Vec::with_capacity(scope.len());
-    for folder in scope {
-        // A trailing separator is a spelling; a leading one is an absolute
-        // path, which no folder of a library is.
-        if folder.starts_with('/') {
-            return None;
-        }
-        let folder = folder.trim_end_matches('/');
-        if folder.is_empty()
-            || folder
-                .split('/')
-                .any(|part| part.is_empty() || part == "." || part == ".." || part.contains('\\'))
-            || Path::new(folder).is_absolute()
-        {
-            return None;
-        }
-        folders.push(folder.to_owned());
-    }
-    folders.sort();
-    folders.dedup();
-    // A folder is dropped when any of its ancestors is listed too. Sorting
-    // alone does not put a folder's descendants right after it — `-`, ` ` and
-    // `(` sort before `/`, so "Rock - Live" falls between "Rock" and
-    // "Rock/Album" — hence every ancestor is asked, not the last one kept.
-    let listed: HashSet<&str> = folders.iter().map(String::as_str).collect();
-    let kept: Vec<String> = folders
-        .iter()
-        .filter(|folder| {
-            !folder
-                .match_indices('/')
-                .any(|(at, _)| listed.contains(&folder[..at]))
-        })
-        .cloned()
-        .collect();
-    (!kept.is_empty() && kept.len() <= MAX_SCOPE_FOLDERS).then_some(kept)
-}
-
-/// Where a scoped walk of `folder` starts, and how deep below the root that
-/// is — or `None` when there is nothing to walk there.
-///
-/// Every folder on the way down is judged as the whole walk would have judged
-/// it, so a scoped walk reads exactly what a full one would read below it: the
-/// built-in exclusions and every ignore file above it, which are loaded as it
-/// goes. A folder on the way that is excluded is left out, and what the
-/// catalogue holds under it counts as not discovered (RFC-021 decision 2); one
-/// that cannot be read, or whose rules cannot be used, is unreadable and spares
-/// its tracks (RFC-018 decision 3). A folder that is gone was walked, and
-/// nothing is there. A scoped walk reads no link, so a link on the way leads
-/// nowhere, as it would in a walk that does not follow links.
-fn enter_scope(
-    reach: &Reach<'_>,
-    walk: &std::cell::RefCell<WalkState>,
-    folder: &str,
-) -> Option<(PathBuf, usize)> {
-    let root = reach.root;
-    let mut current = root.to_path_buf();
-    let parts: Vec<&str> = folder.split('/').collect();
-    for (index, name) in parts.iter().enumerate() {
-        let depth = index + 1;
-        let next = current.join(name);
-        let metadata = match fs::symlink_metadata(&next) {
-            Ok(metadata) => metadata,
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return None,
-            Err(_) => {
-                walk.borrow_mut()
-                    .unreadable(reach, &next, "folder could not be read");
-                return None;
-            }
-        };
-        let mut state = walk.borrow_mut();
-        if metadata.file_type().is_symlink() {
-            state.skip_link(&relative_to(root, &next), SkippedLink::NotFollowed);
-            return None;
-        }
-        if !metadata.is_dir() {
-            // A file where a folder was named: the folder above it, walked
-            // whole, holds it.
-            return Some((current, depth - 1));
-        }
-        if built_in_exclusion(std::ffi::OsStr::new(name), depth, true)
-            || state.ignored(root, &next, true)
-        {
-            state.excluded += 1;
-            return None;
-        }
-        match load_rules(&next, false) {
-            Rules::None => {}
-            Rules::Matcher(rules) => {
-                state.rules.insert(next.clone(), rules);
-            }
-            Rules::ExcludeAll => {
-                state.excluded += 1;
-                return None;
-            }
-            Rules::Unusable(reason) => {
-                state.unreadable(reach, &next, reason);
-                return None;
-            }
-        }
-        current = next;
-    }
-    Some((current, parts.len()))
-}
-
-/// Walks the library (RFC-018 decision 3, RFC-021 decisions 1 to 3), or only
-/// the folders of `scope` when the watcher could name them.
-///
-/// An entry the walk cannot read is logged by its path relative to the root,
-/// never the absolute one, and the walk goes on; only the root itself failing
-/// fails the scan, since then nothing can be told apart — and that includes an
-/// ignore file at the root the walk cannot use.
-///
-/// With `follow_links`, a file reached through a link is returned under the
-/// name [`Reach::catalogue_name`] gives it, and once only, however many links
-/// name it.
-fn discover_audio(reach: &Reach<'_>, scope: Option<&[String]>) -> anyhow::Result<Discovery> {
-    let root = reach.root;
-    let walk = std::cell::RefCell::new(WalkState::default());
-    match load_rules(root, true) {
-        Rules::Matcher(rules) => {
-            walk.borrow_mut().rules.insert(root.to_path_buf(), rules);
-        }
-        Rules::Unusable(reason) => {
-            anyhow::bail!("the .waveflowignore at the library root cannot be used: {reason}")
-        }
-        Rules::None | Rules::ExcludeAll => {}
-    }
-    let starts: Vec<(PathBuf, usize)> = match scope {
-        None => vec![(root.to_path_buf(), 0)],
-        Some(folders) => folders
-            .iter()
-            .filter_map(|folder| enter_scope(reach, &walk, folder))
-            .collect(),
-    };
-    let mut paths = Vec::new();
-    let mut incomplete = false;
-    for (start, base) in starts {
-        let entries = WalkDir::new(&start)
-            .follow_links(reach.follow_links)
-            .into_iter()
-            .filter_entry(|entry| admit(entry, reach, base, &walk));
-        for entry in entries {
-            let entry = match entry {
-                Ok(entry) => entry,
-                Err(error) if error.depth() == 0 && base == 0 => return Err(error.into()),
-                Err(error) => {
-                    let mut walk = walk.borrow_mut();
-                    // A link the walk was told to follow and could not: a loop,
-                    // or a target it cannot read. A link, not a folder, so
-                    // nothing under a folder is spared for it.
-                    let link = if error.loop_ancestor().is_some() {
-                        Some(SkippedLink::Loop)
-                    } else if reach.follow_links
-                        && error.path().is_some_and(|path| {
-                            fs::symlink_metadata(path)
-                                .is_ok_and(|meta| meta.file_type().is_symlink())
-                        })
-                    {
-                        Some(SkippedLink::Broken)
-                    } else {
-                        None
-                    };
-                    let named = error.path().filter(|path| path.starts_with(root));
-                    match (link, named) {
-                        (Some(why), Some(path)) => walk.skip_link(&relative_to(root, path), why),
-                        (_, None) => {
-                            tracing::warn!("the library walk failed somewhere it could not name");
-                            incomplete = true;
-                            walk.unreadable.push(Unreadable {
-                                folder: "<unknown>".to_owned(),
-                                reason: "folder could not be read",
-                            });
-                        }
-                        (None, Some(path)) => {
-                            walk.unreadable(reach, path, "folder could not be read");
-                        }
-                    }
-                    continue;
-                }
-            };
-            // A link is only ever yielded here when it is followed, and then
-            // its type is its target's.
-            if !entry.file_type().is_file() {
-                continue;
-            }
-            let Some((path, name)) = reach.catalogue_name(entry.path()) else {
-                continue;
-            };
-            let supported = path
-                .extension()
-                .and_then(|value| value.to_str())
-                .is_some_and(|ext| {
-                    waveflow_core::scanner::AUDIO_EXTENSIONS
-                        .iter()
-                        .any(|candidate| candidate.eq_ignore_ascii_case(ext))
-                });
-            if supported {
-                paths.push((path, name));
-            }
-        }
-    }
-    paths.sort_by(|left, right| left.1.cmp(&right.1));
-    // Followed links can name one file twice, or name a file the walk also
-    // found directly: the first name in catalogue order keeps it.
-    let mut read = HashSet::new();
-    paths.retain(|(path, _)| read.insert(path.clone()));
-    let walk = walk.into_inner();
-    if walk.skipped_links > LOGGED_LINKS {
-        tracing::info!(
-            count = walk.skipped_links - LOGGED_LINKS,
-            "further symbolic links in the library were skipped"
-        );
-    }
-    Ok(Discovery {
-        paths,
-        unreadable: walk.unreadable,
-        incomplete: incomplete || walk.incomplete,
-        excluded: walk.excluded,
-        skipped_links: walk.skipped_links,
-    })
-}
-
-/// What one walk saw, as relocation needs it: the files it found, what it
-/// could not look at, and — for a scoped walk — where it looked at all.
-struct Walked<'a> {
-    discovered: &'a HashSet<String>,
-    unreadable: &'a [String],
-    incomplete: bool,
-    /// The folders a scoped walk covered, `None` for the whole library.
-    scope: Option<&'a [String]>,
-}
-
-/// Whether `path` is `folder` or lies under it, compared as text.
-fn under(path: &str, folder: &str) -> bool {
-    path == folder
-        || path
-            .strip_prefix(folder)
-            .is_some_and(|rest| rest.starts_with('/'))
-}
-
-impl Walked<'_> {
-    /// Whether the walk can say this track's file is gone: it looked where the
-    /// file was, did not find it, and that place is not under a folder it
-    /// could not read. A scoped walk did not look outside its folders, so a
-    /// track there is never one it saw missing — which is what keeps a scoped
-    /// scan from moving the identity of a track it never looked for onto a
-    /// file it found.
-    fn saw_missing(&self, relative_path: &str) -> bool {
-        !self.incomplete
-            && self
-                .scope
-                .is_none_or(|folders| folders.iter().any(|folder| under(relative_path, folder)))
-            && !self.discovered.contains(relative_path)
-            && !self
-                .unreadable
-                .iter()
-                .any(|folder| under(relative_path, folder))
-    }
-}
-
-/// The candidates a scan may still claim.
-///
-/// A track whose file this walk found is not missing, whatever a hash or a hint
-/// says about it, and one already claimed by an earlier file in this batch is
-/// spoken for. Nor is one under a folder the walk could not read, or any at all
-/// when the walk could not say what it missed (RFC-018 decision 3): its file
-/// may be right where it was. What survives is what genuinely disappeared — and
-/// a relocation is only recorded when exactly one thing did, because moving a
-/// favourite onto the wrong row is worse than not moving it at all.
-fn unclaimed(
-    candidates: Vec<crate::catalog::ExistingTrack>,
-    walked: &Walked<'_>,
-    claimed: &HashSet<Uuid>,
-) -> Vec<crate::catalog::ExistingTrack> {
-    candidates
-        .into_iter()
-        .filter(|candidate| {
-            walked.saw_missing(&candidate.relative_path) && !claimed.contains(&candidate.id)
-        })
-        .collect()
-}
-
-pub(crate) fn extract_file(path: &Path, artwork_dir: &Path) -> Result<CatalogTrackInput, String> {
-    let metadata = fs::metadata(path).map_err(|error| format!("metadata: {error}"))?;
-    let size = metadata.len() as i64;
-    let modified_at = metadata
-        .modified()
-        .ok()
-        .and_then(|value| value.duration_since(UNIX_EPOCH).ok())
-        .map(|value| value.as_millis() as i64)
-        .unwrap_or(0);
-    let quick_hash =
-        waveflow_core::scanner::hash_file(path).map_err(|error| format!("quick hash: {error}"))?;
-    let full_hash = waveflow_core::scanner::hash_file_full(path)
-        .map_err(|error| format!("full hash: {error}"))?;
-    let relative_path = path
-        .file_name()
-        .and_then(|v| v.to_str())
-        .unwrap_or("unknown")
-        .to_owned();
-
-    if matches!(
-        path.extension()
-            .and_then(|v| v.to_str())
-            .map(str::to_ascii_lowercase)
-            .as_deref(),
-        Some("dsf" | "dff")
-    ) {
-        return extract_dsd(
-            path,
-            artwork_dir,
-            relative_path,
-            size,
-            modified_at,
-            quick_hash,
-            full_hash,
-        );
-    }
-    let tagged = lofty::read_from_path(path).map_err(|error| format!("lofty: {error}"))?;
-    let props = tagged.properties();
-    let tag = tagged.primary_tag().or_else(|| tagged.first_tag());
-    let title = tag
-        .and_then(|tag| tag.title().map(|value| value.into_owned()))
-        .unwrap_or_else(|| {
-            path.file_stem()
-                .and_then(|v| v.to_str())
-                .unwrap_or("Unknown")
-                .to_owned()
-        });
-    let cover = tag
-        .and_then(|tag| waveflow_core::scanner::extract_cover(tag, artwork_dir))
-        .or_else(|| waveflow_core::scanner::extract_folder_cover(path, artwork_dir));
-    let artwork = cover.map(|cover| artwork_input(artwork_dir, cover));
-    let lyrics = extract_lyrics(path, tag);
-    let lyrics_hash = lyrics_hash(&lyrics);
-    let raw = raw_credits(tag);
-    let extended = extended_tags(tag);
-    Ok(CatalogTrackInput {
-        relative_path,
-        file_size: size,
-        modified_at,
-        quick_hash,
-        full_hash,
-        title,
-        artist: tag.and_then(|t| t.artist().map(|v| v.into_owned())),
-        artists: raw.artists,
-        album_artists: raw.album_artists,
-        roles: raw.roles,
-        performer_pairs: raw.performer_pairs,
-        album: tag.and_then(|t| t.album().map(|v| v.into_owned())),
-        album_artist: tag.and_then(waveflow_core::scanner::extract_album_artist),
-        is_compilation: tag.is_some_and(waveflow_core::scanner::extract_compilation_flag),
-        genre: tag.and_then(|t| t.genre().map(|v| v.into_owned())),
-        year: tag.and_then(|t| t.date().map(|v| v.year as i64)),
-        track_number: tag.and_then(|t| t.track().map(i64::from)),
-        disc_number: tag.and_then(|t| t.disk().map(i64::from)),
-        duration_ms: props.duration().as_millis() as i64,
-        bitrate: props.audio_bitrate().map(i64::from),
-        sample_rate: props.sample_rate().map(i64::from),
-        channels: props.channels().map(i64::from),
-        bit_depth: props.bit_depth().map(i64::from).filter(|v| *v > 0),
-        codec: waveflow_core::scanner::file_type_label(tagged.file_type()),
-        musical_key: tag.and_then(waveflow_core::scanner::extract_musical_key),
-        musicbrainz_recording_id: extended.musicbrainz_recording_id,
-        musicbrainz_release_id: extended.musicbrainz_release_id,
-        musicbrainz_artist_id: extended.musicbrainz_artist_id,
-        replay_gain_track_gain: extended.replay_gain_track_gain,
-        replay_gain_track_peak: extended.replay_gain_track_peak,
-        replay_gain_album_gain: extended.replay_gain_album_gain,
-        replay_gain_album_peak: extended.replay_gain_album_peak,
-        bpm: extended.bpm,
-        sort_title: extended.sort_title,
-        sort_album: extended.sort_album,
-        sort_album_artist: extended.sort_album_artist,
-        sort_artist: extended.sort_artist,
-        comment: extended.comment,
-        isrc: extended.isrc,
-        moods: extended.moods,
-        explicit_status: extended.explicit_status,
-        original_release_date: extended.original_release_date,
-        release_date: extended.release_date,
-        release_types: extended.release_types,
-        record_labels: extended.record_labels,
-        disc_subtitle: extended.disc_subtitle,
-        tag_rating: tag
-            .and_then(waveflow_core::scanner::extract_rating)
-            .map(i64::from),
-        artwork,
-        lyrics_hash,
-        lyrics,
-    })
-}
-
-fn artwork_input(dir: &Path, cover: waveflow_core::scanner::ExtractedCover) -> ArtworkInput {
-    let bytes = fs::metadata(dir.join(format!("{}.{}", cover.hash, cover.format)))
-        .map(|v| v.len() as i64)
-        .unwrap_or(0);
-    ArtworkInput {
-        hash: cover.hash,
-        format: cover.format,
-        source: cover.source.as_str().to_owned(),
-        byte_size: bytes,
-    }
-}
-
-fn extract_dsd(
-    path: &Path,
-    artwork_dir: &Path,
-    relative_path: String,
-    size: i64,
-    modified_at: i64,
-    quick_hash: String,
-    full_hash: String,
-) -> Result<CatalogTrackInput, String> {
-    use waveflow_core::audio_format::dsd::{
-        metadata::read_metadata,
-        parser::{parse_dff, parse_dsf, DsdContainer},
-    };
-    let ext = path
-        .extension()
-        .and_then(|v| v.to_str())
-        .unwrap_or("")
-        .to_ascii_lowercase();
-    let mut file = fs::File::open(path).map_err(|e| e.to_string())?;
-    let layout = if ext == "dsf" {
-        parse_dsf(&mut file).map_err(|e| e.to_string())?
-    } else {
-        parse_dff(&mut file).map_err(|e| e.to_string())?
-    };
-    let meta = read_metadata(&mut file, layout.container).unwrap_or_default();
-    let codec = layout
-        .dsd_rate_multiple()
-        .map(|v| format!("DSD{v}"))
-        .or_else(|| {
-            Some(
-                match layout.container {
-                    DsdContainer::Dsf => "DSF",
-                    DsdContainer::Dff => "DFF",
-                }
-                .into(),
-            )
-        });
-    let artwork = waveflow_core::scanner::extract_folder_cover(path, artwork_dir)
-        .map(|v| artwork_input(artwork_dir, v));
-    let lyrics = extract_lyrics(path, None);
-    let lyrics_hash = lyrics_hash(&lyrics);
-    let extended = extended_tags(None);
-    Ok(CatalogTrackInput {
-        relative_path,
-        file_size: size,
-        modified_at,
-        quick_hash,
-        full_hash,
-        title: meta.title.unwrap_or_else(|| {
-            path.file_stem()
-                .and_then(|v| v.to_str())
-                .unwrap_or("Unknown")
-                .into()
-        }),
-        artist: meta.artist.clone(),
-        // DSD has no tag reader beyond its own metadata block, so the only
-        // credit it can name is the artist tag. Every other role list stays
-        // empty rather than being invented.
-        artists: Vec::new(),
-        album_artists: Vec::new(),
-        roles: Vec::new(),
-        performer_pairs: Vec::new(),
-        album: meta.album,
-        album_artist: None,
-        is_compilation: false,
-        genre: meta.genre,
-        year: meta.year,
-        track_number: meta.track_number,
-        disc_number: meta.disc_number,
-        duration_ms: layout.duration_ms() as i64,
-        bitrate: None,
-        sample_rate: Some(layout.sample_rate_hz as i64),
-        channels: Some(layout.channels.count() as i64),
-        bit_depth: Some(1),
-        codec,
-        musical_key: None,
-        tag_rating: None,
-        musicbrainz_recording_id: extended.musicbrainz_recording_id,
-        musicbrainz_release_id: extended.musicbrainz_release_id,
-        musicbrainz_artist_id: extended.musicbrainz_artist_id,
-        replay_gain_track_gain: extended.replay_gain_track_gain,
-        replay_gain_track_peak: extended.replay_gain_track_peak,
-        replay_gain_album_gain: extended.replay_gain_album_gain,
-        replay_gain_album_peak: extended.replay_gain_album_peak,
-        bpm: extended.bpm,
-        sort_title: extended.sort_title,
-        sort_album: extended.sort_album,
-        sort_album_artist: extended.sort_album_artist,
-        sort_artist: extended.sort_artist,
-        comment: extended.comment,
-        isrc: extended.isrc,
-        moods: extended.moods,
-        explicit_status: extended.explicit_status,
-        original_release_date: extended.original_release_date,
-        release_date: extended.release_date,
-        release_types: extended.release_types,
-        record_labels: extended.record_labels,
-        disc_subtitle: extended.disc_subtitle,
-        artwork,
-        lyrics_hash,
-        lyrics,
-    })
-}
-
-/// The OpenSubsonic media tags the scanner reads beyond the Subsonic 1.16 set.
-///
-/// Grouped rather than inlined because both entry points build a
-/// [`CatalogTrackInput`], and the DSD path has no tag reader at all: it has to
-/// produce the same shape with every field empty rather than a different one.
-#[derive(Debug, Default)]
-struct ExtendedTags {
-    musicbrainz_recording_id: Option<String>,
-    musicbrainz_release_id: Option<String>,
-    musicbrainz_artist_id: Option<String>,
-    replay_gain_track_gain: Option<f64>,
-    replay_gain_track_peak: Option<f64>,
-    replay_gain_album_gain: Option<f64>,
-    replay_gain_album_peak: Option<f64>,
-    bpm: Option<i64>,
-    sort_title: Option<String>,
-    sort_album: Option<String>,
-    sort_album_artist: Option<String>,
-    sort_artist: Option<String>,
-    comment: Option<String>,
-    isrc: Option<String>,
-    moods: Option<String>,
-    explicit_status: Option<String>,
-    original_release_date: Option<String>,
-    release_date: Option<String>,
-    release_types: Option<String>,
-    record_labels: Option<String>,
-    disc_subtitle: Option<String>,
-}
-
-/// Reads every credit a file names, in tag order.
-///
-/// The role vocabulary and the tag each role is read from follow the
-/// reference. `WRITER` folds onto `COMPOSER` as it does there: the two are one
-/// credit on the overwhelming majority of files that carry either, and telling
-/// them apart would invent a distinction the taggers do not make.
-///
-/// `PERFORMER` is the one role whose credit carries a second value. ID3 stores
-/// it as a musician-credits frame lofty exposes only through its own tag type,
-/// so what reaches here is the generic spelling — `Name (instrument)` — which
-/// [`crate::tags::split_performer`] takes apart.
-fn raw_credits(tag: Option<&lofty::tag::Tag>) -> crate::tags::RawCredits {
-    use crate::tags::Role;
-    let Some(tag) = tag else {
-        return crate::tags::RawCredits::default();
-    };
-    let values = |key: ItemKey| -> Vec<String> {
-        tag.get_strings(key)
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-            .map(str::to_owned)
-            .collect()
-    };
-    let single = |key: ItemKey| -> Option<String> {
-        tag.get_string(key)
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-            .map(str::to_owned)
-    };
-
-    let mut roles: Vec<(Role, Vec<String>)> = Vec::new();
-    let mut composers = values(ItemKey::Composer);
-    composers.extend(values(ItemKey::Writer));
-    if !composers.is_empty() {
-        roles.push((Role::Composer, composers));
-    }
-    for (role, key) in [
-        (Role::Lyricist, ItemKey::Lyricist),
-        (Role::Conductor, ItemKey::Conductor),
-        (Role::Arranger, ItemKey::Arranger),
-        (Role::Producer, ItemKey::Producer),
-        (Role::Director, ItemKey::Director),
-        (Role::Engineer, ItemKey::Engineer),
-        (Role::Mixer, ItemKey::MixEngineer),
-        (Role::Remixer, ItemKey::Remixer),
-        (Role::DjMixer, ItemKey::MixDj),
-    ] {
-        let found = values(key);
-        if !found.is_empty() {
-            roles.push((role, found));
-        }
-    }
-
-    let performer_pairs = values(ItemKey::Performer)
-        .into_iter()
-        .map(|value| crate::tags::split_performer(&value))
-        .collect();
-
-    crate::tags::RawCredits {
-        artist: values(ItemKey::TrackArtist),
-        artists: values(ItemKey::TrackArtists),
-        album_artist: values(ItemKey::AlbumArtist),
-        album_artists: values(ItemKey::AlbumArtists),
-        sort_artist: single(ItemKey::TrackArtistSortOrder),
-        sort_album_artist: single(ItemKey::AlbumArtistSortOrder),
-        is_compilation: waveflow_core::scanner::extract_compilation_flag(tag),
-        roles,
-        performer_pairs,
-    }
-}
-fn extended_tags(tag: Option<&lofty::tag::Tag>) -> ExtendedTags {
-    let Some(tag) = tag else {
-        return ExtendedTags::default();
-    };
-    let text = |key: ItemKey| {
-        tag.get_string(key)
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-            .map(str::to_owned)
-    };
-    // A tag written as several items rather than one `;`-joined string. Joined
-    // here so the column holds one spelling, and split again on the way out by
-    // the same helper that splits `moods`.
-    let joined = |key: ItemKey| {
-        let values = tag
-            .get_strings(key)
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-            .collect::<Vec<_>>();
-        (!values.is_empty()).then(|| values.join("; "))
-    };
-    // ReplayGain tags carry their unit: `-7.32 dB`. Reading only the first
-    // token keeps the suffix from turning a valid measurement into none. A
-    // non-finite value is discarded rather than stored: it would travel all
-    // the way to a player as a volume adjustment.
-    let gain = |key: ItemKey| {
-        tag.get_string(key)
-            .and_then(|value| value.split_whitespace().next())
-            .and_then(|value| value.parse::<f64>().ok())
-            .filter(|value| value.is_finite())
-    };
-    ExtendedTags {
-        musicbrainz_recording_id: text(ItemKey::MusicBrainzRecordingId),
-        musicbrainz_release_id: text(ItemKey::MusicBrainzReleaseId),
-        musicbrainz_artist_id: text(ItemKey::MusicBrainzArtistId),
-        replay_gain_track_gain: gain(ItemKey::ReplayGainTrackGain),
-        replay_gain_track_peak: gain(ItemKey::ReplayGainTrackPeak),
-        replay_gain_album_gain: gain(ItemKey::ReplayGainAlbumGain),
-        replay_gain_album_peak: gain(ItemKey::ReplayGainAlbumPeak),
-        // Both spellings occur in the wild, and a fractional value is written
-        // often enough that parsing the whole string would drop it entirely.
-        bpm: text(ItemKey::IntegerBpm)
-            .or_else(|| text(ItemKey::Bpm))
-            .and_then(|value| {
-                value
-                    .split(['.', ','])
-                    .next()
-                    .and_then(|whole| whole.parse::<i64>().ok())
-            })
-            .filter(|value| *value > 0),
-        sort_title: text(ItemKey::TrackTitleSortOrder),
-        sort_album: text(ItemKey::AlbumTitleSortOrder),
-        sort_album_artist: text(ItemKey::AlbumArtistSortOrder),
-        sort_artist: text(ItemKey::TrackArtistSortOrder),
-        comment: text(ItemKey::Comment),
-        isrc: text(ItemKey::Isrc),
-        moods: text(ItemKey::Mood),
-        // Normalised to the two words the specification defines. The tag
-        // spells the same thing differently per format — MP4 writes the
-        // iTunes rating as 1 or 2, others write words — and a client only
-        // ever compares against `explicit` and `clean`. A tag that says
-        // "no advisory" is not a claim that the work is clean, so it maps to
-        // no value rather than to the second word.
-        explicit_status: text(ItemKey::ParentalAdvisory).and_then(|value| {
-            match value.to_ascii_lowercase().as_str() {
-                "1" | "true" | "explicit" => Some("explicit".to_owned()),
-                "2" | "clean" | "edited" => Some("clean".to_owned()),
-                _ => None,
-            }
-        }),
-        original_release_date: text(ItemKey::OriginalReleaseDate),
-        release_date: text(ItemKey::ReleaseDate).or_else(|| text(ItemKey::RecordingDate)),
-        release_types: joined(ItemKey::MusicBrainzReleaseType),
-        // `LABEL` is the tag Picard writes and the one the reference reads;
-        // `PUBLISHER` is the older spelling the same value arrives under on
-        // files tagged by anything else.
-        record_labels: joined(ItemKey::Label).or_else(|| joined(ItemKey::Publisher)),
-        disc_subtitle: text(ItemKey::SetSubtitle),
-    }
-}
-
-fn extract_lyrics(path: &Path, tag: Option<&lofty::tag::Tag>) -> Vec<LyricsInput> {
-    let mut found = Vec::new();
-    if let Some(tag) = tag {
-        for key in [ItemKey::UnsyncLyrics, ItemKey::Lyrics] {
-            if let Some(content) = tag.get_string(key) {
-                push_lyrics(&mut found, "embedded", content);
-            }
-        }
-    }
-    for (extension, source) in [("lrc", "sidecar_lrc"), ("txt", "sidecar_text")] {
-        let sidecar = path.with_extension(extension);
-        if let Some(content) = read_sidecar(&sidecar) {
-            push_lyrics(&mut found, source, &content);
-        }
-    }
-    found
-}
-
-fn push_lyrics(found: &mut Vec<LyricsInput>, source: &'static str, content: &str) {
-    let content = lyrics::normalize_content(content);
-    if content.trim().is_empty()
-        || found
-            .iter()
-            .any(|existing| existing.source == source && existing.content == content)
-    {
-        return;
-    }
-    let synced = lyrics::has_lrc_timestamps(&content);
-    found.push(LyricsInput {
-        source,
-        lang: "xxx".into(),
-        synced,
-        content,
-    });
-}
-
-fn read_sidecar(path: &Path) -> Option<String> {
-    let file = sidecar_options().open(path).ok()?;
-    let metadata = file.metadata().ok()?;
-    if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() > MAX_LYRICS_BYTES
-    {
-        return None;
-    }
-    let mut bytes = Vec::with_capacity(metadata.len() as usize);
-    file.take(MAX_LYRICS_BYTES + 1)
-        .read_to_end(&mut bytes)
-        .ok()?;
-    if bytes.len() as u64 > MAX_LYRICS_BYTES {
-        return None;
-    }
-    // Not `String::from_utf8`: lyrics written by a tool on a Chinese, Japanese
-    // or Korean Windows are in that system's code page, and a strict UTF-8
-    // read dropped them whole. The core decoder is the one the desktop reads
-    // the same files with, so both answer the same text for them.
-    Some(waveflow_core::text_encoding::decode(&bytes).into_owned())
-}
-
-fn lyrics_hash(entries: &[LyricsInput]) -> String {
-    let mut hasher = blake3::Hasher::new();
-    for entry in entries {
-        hasher.update(entry.source.as_bytes());
-        hasher.update(&[0]);
-        hasher.update(entry.lang.as_bytes());
-        hasher.update(&[u8::from(entry.synced)]);
-        hasher.update(entry.content.as_bytes());
-        hasher.update(&[0xff]);
-    }
-    hasher.finalize().to_hex().to_string()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{
-        built_in_exclusion, extended_tags, load_rules, read_sidecar, Rules, Walked, IGNORE_FILE,
-        MAX_IGNORE_BYTES, MAX_LYRICS_BYTES,
-    };
-
-    /// RFC-021 decision 1: what is left out by name, below the root only, and
-    /// the one dot folder that is not.
-    #[test]
-    fn built_in_exclusions_spare_the_folder_uploads_land_in() {
-        use std::ffi::OsStr;
-        for name in [
-            ".hidden",
-            "._Track.flac",
-            ".Trash-1000",
-            "@eaDir",
-            "#recycle",
-            "$Recycle.Bin",
-            "System Volume Information",
-            "LOST+FOUND",
-        ] {
-            assert!(built_in_exclusion(OsStr::new(name), 1, true), "{name}");
-        }
-        assert!(!built_in_exclusion(OsStr::new("Album"), 1, true));
-        assert!(!built_in_exclusion(OsStr::new("eaDir"), 1, true));
-        // Received files: kept directly under the root, and only there.
-        assert!(!built_in_exclusion(
-            OsStr::new(".waveflow-managed"),
-            1,
-            true
-        ));
-        assert!(built_in_exclusion(OsStr::new(".waveflow-managed"), 2, true));
-        assert!(built_in_exclusion(
-            OsStr::new(".waveflow-managed"),
-            1,
-            false
-        ));
-    }
-
-    /// RFC-021 decision 1: an empty file excludes its folder except at the
-    /// root, and a file the walk cannot use says why.
-    #[test]
-    fn ignore_files_are_read_as_the_rfc_says() {
-        let temp = tempfile::tempdir().unwrap();
-        let dir = temp.path();
-        assert!(matches!(load_rules(dir, false), Rules::None));
-
-        std::fs::write(dir.join(IGNORE_FILE), " \n\t\n").unwrap();
-        assert!(matches!(load_rules(dir, false), Rules::ExcludeAll));
-        assert!(
-            matches!(load_rules(dir, true), Rules::None),
-            "an empty file at the root must exclude nothing"
-        );
-
-        std::fs::write(dir.join(IGNORE_FILE), "# scans\n*.wav\n!Keep.wav\n").unwrap();
-        let Rules::Matcher(rules) = load_rules(dir, false) else {
-            panic!("a valid file is a matcher");
-        };
-        assert!(rules.matched(dir.join("Drop.wav"), false).is_ignore());
-        assert!(rules.matched(dir.join("Keep.wav"), false).is_whitelist());
-
-        std::fs::write(dir.join(IGNORE_FILE), "[z-a]\n").unwrap();
-        assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
-
-        std::fs::write(
-            dir.join(IGNORE_FILE),
-            vec![b'#'; MAX_IGNORE_BYTES as usize + 1],
-        )
-        .unwrap();
-        assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
-
-        std::fs::remove_file(dir.join(IGNORE_FILE)).unwrap();
-        std::fs::create_dir(dir.join(IGNORE_FILE)).unwrap();
-        assert!(matches!(load_rules(dir, false), Rules::Unusable(_)));
-    }
-
-    /// A track under a folder the walk could not read is not missing, so no
-    /// file elsewhere may claim it; nor may any track when the walk could not
-    /// name what it missed.
-    #[test]
-    fn a_track_the_walk_could_not_see_is_not_missing() {
-        let discovered = std::collections::HashSet::from(["Found/One.wav".to_owned()]);
-        let unreadable = vec!["Locked".to_owned()];
-        let walked = Walked {
-            discovered: &discovered,
-            unreadable: &unreadable,
-            incomplete: false,
-            scope: None,
-        };
-        assert!(!walked.saw_missing("Found/One.wav"));
-        assert!(!walked.saw_missing("Locked/Two.wav"));
-        assert!(!walked.saw_missing("Locked"));
-        assert!(walked.saw_missing("Lockedness/Three.wav"));
-        assert!(walked.saw_missing("Gone/Four.wav"));
-        let incomplete = Walked {
-            incomplete: true,
-            ..walked
-        };
-        assert!(!incomplete.saw_missing("Gone/Four.wav"));
-        // A scoped walk looked in its folders only: a track anywhere else was
-        // not looked for, so it was not seen missing.
-        let scope = vec!["Gone".to_owned()];
-        let scoped = Walked {
-            scope: Some(&scope),
-            ..walked
-        };
-        assert!(scoped.saw_missing("Gone/Four.wav"));
-        assert!(!scoped.saw_missing("Elsewhere/Five.wav"));
-        assert!(!scoped.saw_missing("Goner/Six.wav"));
-    }
-
-    /// A scope is a list of folders a walk can trust, or the whole library.
-    #[test]
-    fn a_scope_is_plain_folders_or_the_whole_library() {
-        let folders = |list: &[&str]| list.iter().map(|f| (*f).to_owned()).collect::<Vec<_>>();
-        assert_eq!(
-            super::normalised_scope(&folders(&["b/c", "a", "a/x/y", "b/c/", "bc"])),
-            Some(folders(&["a", "b/c", "bc"])),
-            "nested folders are covered by their parent, and a prefix is not a parent"
-        );
-        // A sibling that sorts between a folder and its child: "-", " " and
-        // "(" all come before "/".
-        assert_eq!(
-            super::normalised_scope(&folders(&[
-                "Rock/Album",
-                "Rock - Live",
-                "Rock",
-                "Artist (Live)",
-                "Artist/Album/CD1"
-            ])),
-            Some(folders(&[
-                "Artist (Live)",
-                "Artist/Album/CD1",
-                "Rock",
-                "Rock - Live"
-            ])),
-        );
-        for whole in [&[""][..], &["a/../b"], &["/etc"], &["a//b"], &["."], &[]] {
-            assert_eq!(super::normalised_scope(&folders(whole)), None, "{whole:?}");
-        }
-        let many: Vec<String> = (0..=super::MAX_SCOPE_FOLDERS)
-            .map(|index| format!("f{index}"))
-            .collect();
-        assert_eq!(super::normalised_scope(&many), None);
-    }
-    use lofty::{
-        prelude::ItemKey,
-        tag::{Tag, TagType},
-    };
-
-    #[test]
-    fn extended_tags_survive_the_shapes_real_files_use() {
-        // MP4 is the tag type whose lofty mapping covers every key this reads.
-        // The others cover a subset each — ID3v2 carries the recording MBID in
-        // a UFID frame rather than a text one, and Vorbis comments spell BPM
-        // only as `Bpm` — which is what the fallbacks in `extended_tags` are
-        // for. This test is about the parsing, so it uses the tag type that
-        // exercises all of it at once.
-        let mut tag = Tag::new(TagType::Mp4Ilst);
-        // ReplayGain is written with its unit, and a leading + is legal.
-        assert!(tag.insert_text(ItemKey::ReplayGainTrackGain, "-7.32 dB".into()));
-        assert!(tag.insert_text(ItemKey::ReplayGainAlbumGain, "+1.50 dB".into()));
-        assert!(tag.insert_text(ItemKey::ReplayGainTrackPeak, "0.988525".into()));
-        // BPM is often fractional even in the integer key.
-        assert!(tag.insert_text(ItemKey::IntegerBpm, "128.5".into()));
-        assert!(tag.insert_text(ItemKey::MusicBrainzRecordingId, "  rec-1  ".into()));
-        assert!(tag.insert_text(ItemKey::Comment, "   ".into()));
-        assert!(tag.insert_text(ItemKey::Isrc, "FRZ039800212".into()));
-        assert!(tag.insert_text(ItemKey::Mood, "Melancholic; Warm".into()));
-        assert!(tag.insert_text(ItemKey::ParentalAdvisory, "2".into()));
-        // The three sort keys, which the catalogue derives album and artist
-        // sort names from. A joined credit carries a joined sort tag, and the
-        // pairing happens where the names are split — what this pins is that
-        // all three arrive at all, under the tag type that spells them.
-        assert!(tag.insert_text(ItemKey::AlbumTitleSortOrder, "Night Sessions, The".into()));
-        assert!(tag.insert_text(ItemKey::AlbumArtistSortOrder, "Nocturnes, The".into()));
-        assert!(tag.insert_text(
-            ItemKey::TrackArtistSortOrder,
-            "Nocturnes, The; Reed, Ada".into()
-        ));
-        let extended = extended_tags(Some(&tag));
-        assert_eq!(extended.replay_gain_track_gain, Some(-7.32));
-        assert_eq!(extended.replay_gain_album_gain, Some(1.5));
-        assert_eq!(extended.replay_gain_track_peak, Some(0.988_525));
-        assert_eq!(extended.replay_gain_album_peak, None);
-        assert_eq!(extended.bpm, Some(128));
-        // Trimmed, and a tag holding only whitespace is no value at all
-        // rather than an empty one the presence rule would then report as
-        // meaningful.
-        assert_eq!(extended.musicbrainz_recording_id.as_deref(), Some("rec-1"));
-        assert_eq!(extended.comment, None);
-        assert_eq!(extended.isrc.as_deref(), Some("FRZ039800212"));
-        assert_eq!(extended.moods.as_deref(), Some("Melancholic; Warm"));
-        // The per-format spelling is normalised to the two words the
-        // specification defines; a client compares against nothing else.
-        assert_eq!(extended.explicit_status.as_deref(), Some("clean"));
-        assert_eq!(extended.sort_album.as_deref(), Some("Night Sessions, The"));
-        assert_eq!(
-            extended.sort_album_artist.as_deref(),
-            Some("Nocturnes, The")
-        );
-        assert_eq!(
-            extended.sort_artist.as_deref(),
-            Some("Nocturnes, The; Reed, Ada")
-        );
-
-        // Unparseable measurements are dropped rather than stored: a NaN gain
-        // would reach a player as a volume adjustment.
-        let mut broken = Tag::new(TagType::Mp4Ilst);
-        assert!(broken.insert_text(ItemKey::ReplayGainTrackGain, "loud".into()));
-        assert!(broken.insert_text(ItemKey::ReplayGainAlbumPeak, "NaN".into()));
-        assert!(broken.insert_text(ItemKey::IntegerBpm, "0".into()));
-        let broken = extended_tags(Some(&broken));
-        assert_eq!(broken.replay_gain_track_gain, None);
-        assert_eq!(broken.replay_gain_album_peak, None);
-        assert_eq!(broken.bpm, None);
-        // A tag saying "no advisory" is not a claim that the work is clean.
-        let mut neutral = Tag::new(TagType::Mp4Ilst);
-        assert!(neutral.insert_text(ItemKey::ParentalAdvisory, "0".into()));
-        assert_eq!(extended_tags(Some(&neutral)).explicit_status, None);
-
-        // The DSD path has no tag reader and must produce the same shape.
-        let absent = extended_tags(None);
-        assert_eq!(absent.musicbrainz_recording_id, None);
-        assert_eq!(absent.bpm, None);
-    }
-
-    #[test]
-    fn sidecar_reader_rejects_invalid_files_and_symlinks() {
-        let temp = tempfile::tempdir().unwrap();
-        let valid = temp.path().join("valid.lrc");
-        std::fs::write(&valid, "[00:01]safe").unwrap();
-        assert_eq!(read_sidecar(&valid).as_deref(), Some("[00:01]safe"));
-
-        let oversized = temp.path().join("oversized.lrc");
-        std::fs::write(&oversized, vec![b'x'; MAX_LYRICS_BYTES as usize + 1]).unwrap();
-        assert!(read_sidecar(&oversized).is_none());
-
-        assert!(read_sidecar(temp.path()).is_none());
-
-        let link = temp.path().join("linked.lrc");
-        #[cfg(unix)]
-        let linked = std::os::unix::fs::symlink(&valid, &link).is_ok();
-        #[cfg(windows)]
-        let linked = std::os::windows::fs::symlink_file(&valid, &link).is_ok();
-        if linked {
-            assert!(read_sidecar(&link).is_none());
-        }
-    }
-
-    /// Lyrics saved by a tool on a Japanese Windows, in that system's code
-    /// page. A strict UTF-8 read dropped the file whole, so the track had no
-    /// lyrics at all.
-    #[test]
-    fn sidecar_lyrics_that_are_not_utf8_are_read_in_their_own_encoding() {
-        let temp = tempfile::tempdir().unwrap();
-        let text = "[00:01.00]今日はいい天気ですね、一緒に公園を散歩しましょう\n\
-                    [00:05.50]湖に光が映って、風が森を通り抜ける音がする";
-        let (bytes, _, unmappable) = encoding_rs::SHIFT_JIS.encode(text);
-        assert!(!unmappable, "Shift_JIS holds the sample");
-        assert!(
-            std::str::from_utf8(&bytes).is_err(),
-            "the sample is not UTF-8 by accident"
-        );
-        let japanese = temp.path().join("japanese.lrc");
-        std::fs::write(&japanese, &bytes).unwrap();
-        assert_eq!(read_sidecar(&japanese).as_deref(), Some(text));
-
-        // A byte-order mark names the encoding and is not part of the text.
-        // Kept, it sat in front of the first timestamp.
-        let marked = temp.path().join("marked.lrc");
-        let mut bytes = vec![0xEF, 0xBB, 0xBF];
-        bytes.extend_from_slice(b"[00:01]marked");
-        std::fs::write(&marked, bytes).unwrap();
-        assert_eq!(read_sidecar(&marked).as_deref(), Some("[00:01]marked"));
-    }
 }

From e7e822ecf458bb68ea675153b2fec5ac0d3bf057 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:56:08 +0100
Subject: [PATCH 4/4] refactor(watcher): move the watcher's unit tests into
 their own file

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/watcher/mod.rs   | 275 +------------------------------------------
 src/watcher/tests.rs | 275 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 276 insertions(+), 274 deletions(-)
 create mode 100644 src/watcher/tests.rs

diff --git a/src/watcher/mod.rs b/src/watcher/mod.rs
index ebdc2dc1..61c65aac 100644
--- a/src/watcher/mod.rs
+++ b/src/watcher/mod.rs
@@ -486,277 +486,4 @@ pub fn rewatch(
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn library(id: Uuid, root: &str) -> LibraryRecord {
-        LibraryRecord {
-            id,
-            name: "watched".into(),
-            root_path: PathBuf::from(root),
-        }
-    }
-
-    /// inotify, as far as sharing goes: one descriptor per folder, shared by
-    /// every watch that covers it, and taking a recursive watch back clears
-    /// every descriptor beneath its root. A refused root fails partway, after
-    /// placing its own descriptor, as a watch limit reached mid-tree does.
-    struct SharedDescriptors {
-        folders: Vec<PathBuf>,
-        descriptors: HashSet<PathBuf>,
-        refuse: HashSet<PathBuf>,
-    }
-
-    impl Watches for SharedDescriptors {
-        fn watch(&mut self, root: &Path) -> Result<(), String> {
-            for folder in self
-                .folders
-                .iter()
-                .filter(|folder| folder.starts_with(root))
-            {
-                if self.refuse.contains(root) && folder != root {
-                    return Err("no space left for another watch".into());
-                }
-                self.descriptors.insert(folder.clone());
-            }
-            Ok(())
-        }
-
-        fn unwatch(&mut self, root: &Path) {
-            self.descriptors.retain(|folder| !folder.starts_with(root));
-        }
-    }
-
-    impl SharedDescriptors {
-        fn covers(&self, root: &str) -> bool {
-            self.folders
-                .iter()
-                .filter(|folder| folder.starts_with(root))
-                .all(|folder| self.descriptors.contains(folder))
-        }
-    }
-
-    /// The enclosing library is re-installed, then the nested one fails and
-    /// is cleaned up — which strips the enclosing library's descriptors in the
-    /// nested tree. The enclosing library must end up watched whole.
-    #[test]
-    fn a_nested_failure_does_not_leave_the_library_around_it_half_watched() {
-        let folders: Vec<PathBuf> = [
-            "/music",
-            "/music/rock",
-            "/music/classical",
-            "/music/classical/bach",
-        ]
-        .into_iter()
-        .map(PathBuf::from)
-        .collect();
-        let mut kernel = SharedDescriptors {
-            descriptors: folders.iter().cloned().collect(),
-            folders,
-            refuse: HashSet::from([PathBuf::from("/music/classical")]),
-        };
-        let (outer, inner) = (Uuid::new_v4(), Uuid::new_v4());
-        let mut watched = HashMap::from([
-            (outer, library(outer, "/music")),
-            (inner, library(inner, "/music/classical")),
-        ]);
-        let mut refused = HashSet::new();
-        // A library at the bottom of both went away, and took its folder's
-        // descriptor with it.
-        kernel.unwatch(Path::new("/music/classical/bach"));
-
-        rewatch(
-            &mut kernel,
-            &mut watched,
-            &mut refused,
-            vec![PathBuf::from("/music/classical/bach")],
-        );
-
-        assert!(
-            kernel.covers("/music"),
-            "the enclosing library was left without its nested folders"
-        );
-        assert!(watched.contains_key(&outer));
-        assert!(!watched.contains_key(&inner));
-        assert!(refused.contains(&(inner, PathBuf::from("/music/classical"))));
-    }
-
-    /// `WAVEFLOW_WATCH_DELAY_SECS` has no ceiling: a delay too long to
-    /// multiply must not panic the watcher's task.
-    #[test]
-    fn an_enormous_delay_does_not_panic() {
-        let mut settle = Settle::new(Duration::from_secs(u64::MAX));
-        let library = Uuid::new_v4();
-        let now = Instant::now();
-        settle.touch(library, now);
-        assert!(settle.due(now, |_| false).is_empty());
-    }
-
-    /// Removing a recursive inotify watch removes every descriptor beneath
-    /// it, so the libraries nested under it — and the one around it, when the
-    /// removed one was nested — are named to be watched again.
-    #[test]
-    fn a_removed_watch_names_the_libraries_it_shared_descriptors_with() {
-        let (outer, inner, beside) = (Uuid::new_v4(), Uuid::new_v4(), Uuid::new_v4());
-        let libraries = HashMap::from([
-            (outer, library(outer, "/music")),
-            (inner, library(inner, "/music/classical")),
-            (beside, library(beside, "/podcasts")),
-        ]);
-        let mut both = vec![outer, inner];
-        both.sort();
-        assert_eq!(sharing_watches_with(&libraries, Path::new("/music")), both);
-        assert_eq!(
-            sharing_watches_with(&libraries, Path::new("/music/classical")),
-            both
-        );
-        assert_eq!(
-            sharing_watches_with(&libraries, Path::new("/music/rock")),
-            vec![outer]
-        );
-        assert!(sharing_watches_with(&libraries, Path::new("/elsewhere")).is_empty());
-    }
-
-    #[test]
-    fn a_library_is_due_once_its_changes_are_quiet() {
-        let delay = Duration::from_secs(10);
-        let mut settle = Settle::new(delay);
-        let library = Uuid::new_v4();
-        let start = Instant::now();
-        settle.touch(library, start);
-        settle.touch(library, start + Duration::from_secs(8));
-        assert!(settle
-            .due(start + Duration::from_secs(17), |_| false)
-            .is_empty());
-        assert_eq!(
-            settle.due(start + Duration::from_secs(18), |_| false),
-            vec![library]
-        );
-        assert!(
-            !settle.is_pending(library),
-            "a due library is no longer pending"
-        );
-    }
-
-    #[test]
-    fn changes_that_never_settle_are_scanned_after_thirty_delays() {
-        let delay = Duration::from_secs(1);
-        let mut settle = Settle::new(delay);
-        let library = Uuid::new_v4();
-        let start = Instant::now();
-        // A change every second, for thirty seconds: never quiet for a delay.
-        for second in 0..30 {
-            settle.touch(library, start + Duration::from_secs(second));
-            assert!(settle
-                .due(start + Duration::from_millis(second * 1000 + 100), |_| {
-                    false
-                })
-                .is_empty());
-        }
-        assert_eq!(
-            settle.due(start + Duration::from_secs(30), |_| false),
-            vec![library]
-        );
-    }
-
-    /// Never a second scan while one runs: the library stays pending, and is
-    /// due as soon as the scan is over.
-    #[test]
-    fn no_scan_starts_while_one_runs_for_the_library() {
-        let delay = Duration::from_secs(1);
-        let mut settle = Settle::new(delay);
-        let (busy, idle) = (Uuid::new_v4(), Uuid::new_v4());
-        let start = Instant::now();
-        settle.touch(busy, start);
-        settle.touch(idle, start);
-        let later = start + Duration::from_secs(5);
-        assert_eq!(settle.due(later, |id| id == busy), vec![idle]);
-        assert!(settle.is_pending(busy));
-        assert_eq!(settle.due(later, |_| false), vec![busy]);
-    }
-
-    /// Folders gather until the library settles; anything that needs the
-    /// whole library, or too many folders, turns the scope into all of it.
-    #[test]
-    fn a_settled_library_names_the_folders_its_changes_were_in() {
-        let delay = Duration::from_secs(1);
-        let mut settle = Settle::new(delay);
-        let (scoped, whole, crowded) = (Uuid::new_v4(), Uuid::new_v4(), Uuid::new_v4());
-        let start = Instant::now();
-        settle.touch_folder(scoped, "Rock/Album".into(), start);
-        settle.touch_folder(scoped, "Jazz".into(), start);
-        settle.touch_folder(scoped, "Jazz".into(), start);
-        settle.touch_folder(whole, "Rock".into(), start);
-        settle.touch(whole, start);
-        settle.touch_folder(whole, "Jazz".into(), start);
-        for index in 0..=crate::scanner::MAX_SCOPE_FOLDERS {
-            settle.touch_folder(crowded, format!("f{index}"), start);
-        }
-        let mut due = settle.due_with_scope(start + delay, |_| false);
-        due.sort_by_key(|(id, _)| *id);
-        let scope = |id: Uuid| due.iter().find(|(due, _)| *due == id).unwrap().1.clone();
-        assert_eq!(
-            scope(scoped),
-            Some(vec!["Jazz".to_owned(), "Rock/Album".to_owned()])
-        );
-        assert_eq!(scope(whole), None, "once whole, a library stays whole");
-        assert_eq!(scope(crowded), None);
-    }
-
-    #[test]
-    fn a_change_is_scoped_to_the_folder_it_was_in() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path();
-        std::fs::create_dir_all(root.join("Artist/Album")).unwrap();
-        std::fs::write(root.join("Artist/Album/a.flac"), b"x").unwrap();
-        assert_eq!(
-            folder_of(root, &root.join("Artist/Album/a.flac")).as_deref(),
-            Some("Artist/Album")
-        );
-        assert_eq!(
-            folder_of(root, &root.join("Artist/Album")).as_deref(),
-            Some("Artist/Album"),
-            "a folder is its own scope"
-        );
-        assert_eq!(
-            folder_of(root, &root.join("Artist/Gone/b.flac")).as_deref(),
-            Some("Artist/Gone"),
-            "something gone is in its parent's"
-        );
-        assert_eq!(folder_of(root, &root.join("top.flac")), None);
-        assert_eq!(folder_of(root, root), None);
-        assert_eq!(folder_of(root, Path::new("/elsewhere/c.flac")), None);
-    }
-
-    #[test]
-    fn reads_and_received_files_are_not_changes() {
-        let read = Event::new(EventKind::Access(notify::event::AccessKind::Any));
-        assert!(!relevant(&read));
-        let atime = Event::new(EventKind::Modify(ModifyKind::Metadata(
-            MetadataKind::AccessTime,
-        )));
-        assert!(!relevant(&atime));
-        let created = Event::new(EventKind::Create(notify::event::CreateKind::File));
-        assert!(relevant(&created));
-
-        let (outer, inner) = (Uuid::new_v4(), Uuid::new_v4());
-        let libraries = HashMap::from([
-            (outer, library(outer, "/music")),
-            (inner, library(inner, "/music/classical")),
-        ]);
-        assert_eq!(
-            library_of(&libraries, Path::new("/music/rock/a.flac")),
-            Some(outer)
-        );
-        assert_eq!(
-            library_of(&libraries, Path::new("/music/classical/b.flac")),
-            Some(inner),
-            "the deepest root owns the path"
-        );
-        assert_eq!(
-            library_of(&libraries, Path::new("/music/.waveflow-managed/c.part")),
-            None
-        );
-        assert_eq!(library_of(&libraries, Path::new("/elsewhere/d.flac")), None);
-    }
-}
+mod tests;
diff --git a/src/watcher/tests.rs b/src/watcher/tests.rs
new file mode 100644
index 00000000..817fdefc
--- /dev/null
+++ b/src/watcher/tests.rs
@@ -0,0 +1,275 @@
+//! Unit tests of the watcher: debouncing, scoping a change to its folder,
+//! which events count, and how watches are shared and re-established.
+
+use super::*;
+
+fn library(id: Uuid, root: &str) -> LibraryRecord {
+    LibraryRecord {
+        id,
+        name: "watched".into(),
+        root_path: PathBuf::from(root),
+    }
+}
+
+/// inotify, as far as sharing goes: one descriptor per folder, shared by
+/// every watch that covers it, and taking a recursive watch back clears
+/// every descriptor beneath its root. A refused root fails partway, after
+/// placing its own descriptor, as a watch limit reached mid-tree does.
+struct SharedDescriptors {
+    folders: Vec<PathBuf>,
+    descriptors: HashSet<PathBuf>,
+    refuse: HashSet<PathBuf>,
+}
+
+impl Watches for SharedDescriptors {
+    fn watch(&mut self, root: &Path) -> Result<(), String> {
+        for folder in self
+            .folders
+            .iter()
+            .filter(|folder| folder.starts_with(root))
+        {
+            if self.refuse.contains(root) && folder != root {
+                return Err("no space left for another watch".into());
+            }
+            self.descriptors.insert(folder.clone());
+        }
+        Ok(())
+    }
+
+    fn unwatch(&mut self, root: &Path) {
+        self.descriptors.retain(|folder| !folder.starts_with(root));
+    }
+}
+
+impl SharedDescriptors {
+    fn covers(&self, root: &str) -> bool {
+        self.folders
+            .iter()
+            .filter(|folder| folder.starts_with(root))
+            .all(|folder| self.descriptors.contains(folder))
+    }
+}
+
+/// The enclosing library is re-installed, then the nested one fails and
+/// is cleaned up — which strips the enclosing library's descriptors in the
+/// nested tree. The enclosing library must end up watched whole.
+#[test]
+fn a_nested_failure_does_not_leave_the_library_around_it_half_watched() {
+    let folders: Vec<PathBuf> = [
+        "/music",
+        "/music/rock",
+        "/music/classical",
+        "/music/classical/bach",
+    ]
+    .into_iter()
+    .map(PathBuf::from)
+    .collect();
+    let mut kernel = SharedDescriptors {
+        descriptors: folders.iter().cloned().collect(),
+        folders,
+        refuse: HashSet::from([PathBuf::from("/music/classical")]),
+    };
+    let (outer, inner) = (Uuid::new_v4(), Uuid::new_v4());
+    let mut watched = HashMap::from([
+        (outer, library(outer, "/music")),
+        (inner, library(inner, "/music/classical")),
+    ]);
+    let mut refused = HashSet::new();
+    // A library at the bottom of both went away, and took its folder's
+    // descriptor with it.
+    kernel.unwatch(Path::new("/music/classical/bach"));
+
+    rewatch(
+        &mut kernel,
+        &mut watched,
+        &mut refused,
+        vec![PathBuf::from("/music/classical/bach")],
+    );
+
+    assert!(
+        kernel.covers("/music"),
+        "the enclosing library was left without its nested folders"
+    );
+    assert!(watched.contains_key(&outer));
+    assert!(!watched.contains_key(&inner));
+    assert!(refused.contains(&(inner, PathBuf::from("/music/classical"))));
+}
+
+/// `WAVEFLOW_WATCH_DELAY_SECS` has no ceiling: a delay too long to
+/// multiply must not panic the watcher's task.
+#[test]
+fn an_enormous_delay_does_not_panic() {
+    let mut settle = Settle::new(Duration::from_secs(u64::MAX));
+    let library = Uuid::new_v4();
+    let now = Instant::now();
+    settle.touch(library, now);
+    assert!(settle.due(now, |_| false).is_empty());
+}
+
+/// Removing a recursive inotify watch removes every descriptor beneath
+/// it, so the libraries nested under it — and the one around it, when the
+/// removed one was nested — are named to be watched again.
+#[test]
+fn a_removed_watch_names_the_libraries_it_shared_descriptors_with() {
+    let (outer, inner, beside) = (Uuid::new_v4(), Uuid::new_v4(), Uuid::new_v4());
+    let libraries = HashMap::from([
+        (outer, library(outer, "/music")),
+        (inner, library(inner, "/music/classical")),
+        (beside, library(beside, "/podcasts")),
+    ]);
+    let mut both = vec![outer, inner];
+    both.sort();
+    assert_eq!(sharing_watches_with(&libraries, Path::new("/music")), both);
+    assert_eq!(
+        sharing_watches_with(&libraries, Path::new("/music/classical")),
+        both
+    );
+    assert_eq!(
+        sharing_watches_with(&libraries, Path::new("/music/rock")),
+        vec![outer]
+    );
+    assert!(sharing_watches_with(&libraries, Path::new("/elsewhere")).is_empty());
+}
+
+#[test]
+fn a_library_is_due_once_its_changes_are_quiet() {
+    let delay = Duration::from_secs(10);
+    let mut settle = Settle::new(delay);
+    let library = Uuid::new_v4();
+    let start = Instant::now();
+    settle.touch(library, start);
+    settle.touch(library, start + Duration::from_secs(8));
+    assert!(settle
+        .due(start + Duration::from_secs(17), |_| false)
+        .is_empty());
+    assert_eq!(
+        settle.due(start + Duration::from_secs(18), |_| false),
+        vec![library]
+    );
+    assert!(
+        !settle.is_pending(library),
+        "a due library is no longer pending"
+    );
+}
+
+#[test]
+fn changes_that_never_settle_are_scanned_after_thirty_delays() {
+    let delay = Duration::from_secs(1);
+    let mut settle = Settle::new(delay);
+    let library = Uuid::new_v4();
+    let start = Instant::now();
+    // A change every second, for thirty seconds: never quiet for a delay.
+    for second in 0..30 {
+        settle.touch(library, start + Duration::from_secs(second));
+        assert!(settle
+            .due(start + Duration::from_millis(second * 1000 + 100), |_| {
+                false
+            })
+            .is_empty());
+    }
+    assert_eq!(
+        settle.due(start + Duration::from_secs(30), |_| false),
+        vec![library]
+    );
+}
+
+/// Never a second scan while one runs: the library stays pending, and is
+/// due as soon as the scan is over.
+#[test]
+fn no_scan_starts_while_one_runs_for_the_library() {
+    let delay = Duration::from_secs(1);
+    let mut settle = Settle::new(delay);
+    let (busy, idle) = (Uuid::new_v4(), Uuid::new_v4());
+    let start = Instant::now();
+    settle.touch(busy, start);
+    settle.touch(idle, start);
+    let later = start + Duration::from_secs(5);
+    assert_eq!(settle.due(later, |id| id == busy), vec![idle]);
+    assert!(settle.is_pending(busy));
+    assert_eq!(settle.due(later, |_| false), vec![busy]);
+}
+
+/// Folders gather until the library settles; anything that needs the
+/// whole library, or too many folders, turns the scope into all of it.
+#[test]
+fn a_settled_library_names_the_folders_its_changes_were_in() {
+    let delay = Duration::from_secs(1);
+    let mut settle = Settle::new(delay);
+    let (scoped, whole, crowded) = (Uuid::new_v4(), Uuid::new_v4(), Uuid::new_v4());
+    let start = Instant::now();
+    settle.touch_folder(scoped, "Rock/Album".into(), start);
+    settle.touch_folder(scoped, "Jazz".into(), start);
+    settle.touch_folder(scoped, "Jazz".into(), start);
+    settle.touch_folder(whole, "Rock".into(), start);
+    settle.touch(whole, start);
+    settle.touch_folder(whole, "Jazz".into(), start);
+    for index in 0..=crate::scanner::MAX_SCOPE_FOLDERS {
+        settle.touch_folder(crowded, format!("f{index}"), start);
+    }
+    let mut due = settle.due_with_scope(start + delay, |_| false);
+    due.sort_by_key(|(id, _)| *id);
+    let scope = |id: Uuid| due.iter().find(|(due, _)| *due == id).unwrap().1.clone();
+    assert_eq!(
+        scope(scoped),
+        Some(vec!["Jazz".to_owned(), "Rock/Album".to_owned()])
+    );
+    assert_eq!(scope(whole), None, "once whole, a library stays whole");
+    assert_eq!(scope(crowded), None);
+}
+
+#[test]
+fn a_change_is_scoped_to_the_folder_it_was_in() {
+    let temp = tempfile::tempdir().unwrap();
+    let root = temp.path();
+    std::fs::create_dir_all(root.join("Artist/Album")).unwrap();
+    std::fs::write(root.join("Artist/Album/a.flac"), b"x").unwrap();
+    assert_eq!(
+        folder_of(root, &root.join("Artist/Album/a.flac")).as_deref(),
+        Some("Artist/Album")
+    );
+    assert_eq!(
+        folder_of(root, &root.join("Artist/Album")).as_deref(),
+        Some("Artist/Album"),
+        "a folder is its own scope"
+    );
+    assert_eq!(
+        folder_of(root, &root.join("Artist/Gone/b.flac")).as_deref(),
+        Some("Artist/Gone"),
+        "something gone is in its parent's"
+    );
+    assert_eq!(folder_of(root, &root.join("top.flac")), None);
+    assert_eq!(folder_of(root, root), None);
+    assert_eq!(folder_of(root, Path::new("/elsewhere/c.flac")), None);
+}
+
+#[test]
+fn reads_and_received_files_are_not_changes() {
+    let read = Event::new(EventKind::Access(notify::event::AccessKind::Any));
+    assert!(!relevant(&read));
+    let atime = Event::new(EventKind::Modify(ModifyKind::Metadata(
+        MetadataKind::AccessTime,
+    )));
+    assert!(!relevant(&atime));
+    let created = Event::new(EventKind::Create(notify::event::CreateKind::File));
+    assert!(relevant(&created));
+
+    let (outer, inner) = (Uuid::new_v4(), Uuid::new_v4());
+    let libraries = HashMap::from([
+        (outer, library(outer, "/music")),
+        (inner, library(inner, "/music/classical")),
+    ]);
+    assert_eq!(
+        library_of(&libraries, Path::new("/music/rock/a.flac")),
+        Some(outer)
+    );
+    assert_eq!(
+        library_of(&libraries, Path::new("/music/classical/b.flac")),
+        Some(inner),
+        "the deepest root owns the path"
+    );
+    assert_eq!(
+        library_of(&libraries, Path::new("/music/.waveflow-managed/c.part")),
+        None
+    );
+    assert_eq!(library_of(&libraries, Path::new("/elsewhere/d.flac")), None);
+}