Fixed merge feature

.gitignore

@@ -3,3 +3,5 @@
 /.claude
 /media
 /federation
+/similarity-models
+/federation-cache

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "furumusic"
-version = "0.6.4-fd"
+version = "0.10.4"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 
@@ -12,8 +12,12 @@ cot = { version = "0.6.0", default-features = false, features = ["postgres", "js
 schemars = { version = "0.9", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 openidconnect = "4.0"
-reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
-tokio = { version = "1", features = ["sync", "fs", "io-util"] }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "stream"] }
+tokio = { version = "1", features = ["sync", "fs", "io-util", "process"] }
+tokio-util = "0.7"
+libc = "0.2"
+async-stream = "0.3"
+bytes = "1"
 tower = "0.5"
 base64 = "0.22"
 blake3 = "1"
@@ -29,6 +33,10 @@ md-5 = "0.10"
 image = { version = "0.25", default-features = false, features = ["jpeg", "png", "webp", "gif", "bmp"] }
 sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
 anyhow = "1.0"
+futures-util = "0.3"
+rodio = { version = "0.22.2", default-features = false, features = ["mp3", "flac", "vorbis", "wav", "symphonia-aac", "symphonia-isomp4", "symphonia-alac", "symphonia-adpcm", "symphonia-aiff", "symphonia-mkv", "symphonia-pcm"] }
+rustfft = "6.4.1"
+tract-onnx = "0.23.4"
 tokio-cron-scheduler = "0.15"
 croner = "3"
 async-trait = "0.1"
@@ -37,4 +45,4 @@ uuid = "1"
 librqbit = { version = "8.1.1", features = ["disable-upload"] }
 # P2P federation: publishes the library into a shared DHT and serves audio /
 # catalogs to furumi peers (TUI clients) over the frid stack.
-music-dht = { git = "https://gt.hexor.cy/ab/frid.git" }
+music-dht = "0.4.0"

Dockerfile

@@ -1,4 +1,4 @@
-FROM rust:1-slim AS builder
+FROM rust:1-bookworm AS builder
 
 RUN apt-get update \
     && apt-get install -y --no-install-recommends pkg-config libssl-dev ca-certificates \
@@ -14,14 +14,25 @@ COPY templates ./templates
 
 RUN cargo build --release
 
+FROM denoland/deno:bin-2.8.3 AS deno
+
 FROM debian:bookworm-slim
 
+ARG YT_DLP_VERSION=2026.07.04
+
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends ca-certificates \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        ffmpeg \
+        python3 \
+        python3-pip \
+    && pip3 install --break-system-packages --no-cache-dir --disable-pip-version-check \
+        "yt-dlp[default]==${YT_DLP_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /data
 COPY --from=builder /app/target/release/furumusic /usr/local/bin/furumusic
+COPY --from=deno /deno /usr/local/bin/deno
 
 EXPOSE 8000
 CMD ["furumusic", "-l", "0.0.0.0:8000"]

README.md

@@ -1,201 +1,143 @@
-# furumusic
+# Furumusic
 
-Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL.
+**Your library. Your users. Your network.**
 
-Built with Rust ([cot](https://cot.rs) framework).
+Furumusic is a self-hosted, multi-user music server with a full web player and
+support for the Furumi federated network. It turns a collection of music files
+into a shared library that is available from any modern browser, while every
+user keeps their own playlists, likes, listening history, and playback state.
 
-## Quick start
+Music can be uploaded directly, imported from a `.torrent` file, or downloaded
+from a magnet link. An optional AI-assisted import pipeline reads the available
+tags and path information, reconstructs inconsistent metadata, finds artwork,
+and organizes the result into artists, releases, and tracks. Uncertain matches
+are kept for review instead of silently entering the library with bad data.
+
+## Why Furumusic?
+
+Furumusic is for a household, a small community, or anyone who wants one music
+library without handing it to a subscription service. The server owns the
+catalog and media files; the browser is only the player.
+
+- one shared library with separate user accounts;
+- a responsive web player with artists, releases, search, queue, and playlists;
+- direct file uploads and imports from YouTube, torrent files, or magnet links;
+- optional AI-assisted recognition and normalization of metadata;
+- password login or OIDC/SSO with group-based access control;
+- optional federation without a central catalog or search service;
+- trusted-device pairing, playback handoff, and synchronization between Furumi
+  players;
+- Last.fm scrobbling and similarity-based discovery when configured.
+
+Furumusic does not include music. Import only media you are allowed to store and
+share.
+
+## Importing music
+
+Users can add audio files from the web interface or ask the server to download
+selected files from a torrent. Both routes feed the same import pipeline, so a
+library remains consistent regardless of where its files came from.
+
+The importer combines embedded tags, filenames, folder structure, and existing
+catalog context. With an OpenAI-compatible language model configured, it can
+normalize artist and release names, separate featured artists, recover track
+numbers and release types, and flag ambiguous results for a user to approve.
+Cover art is taken from nearby image files or embedded artwork when available.
+
+The inbox and permanent library are separate directories. New files are first
+processed in the inbox and are moved into the organized library only after
+their metadata has been accepted.
+
+## Federation
+
+Federation is optional. Independent Furumusic and Furumi players that use the
+same Network ID discover one another as a logical network. Each peer keeps its
+own library and can continue working alone.
+
+When federation is enabled, local and remote artists, releases, and tracks can
+appear in the same search and library views. Missing audio is streamed from an
+available peer and can optionally be retained locally. Similarity search also
+stays decentralized: embeddings and exact ranking remain on the instance that
+owns the music.
+
+Trusted-device pairing is separate from public catalog discovery. It connects
+a user's own Furumi players so likes, playlists, playback state, and control can
+move between approved devices.
+
+## Build and run
+
+Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition
+support. Create an empty database, provide its connection URL, and start the
+server:
 
 ```bash
-export FURU_DATABASE_URL=postgresql://user:pass@localhost/furumusic
-cargo run
-# Open http://localhost:8000/admin/setup to create the first admin account
+export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic'
+cargo run --release --locked
 ```
 
-## Project structure
+Open <http://127.0.0.1:8000/admin/setup> to create the first administrator.
+After setup, configure the inbox and library directories under **Admin →
+Settings** before importing music.
 
+To listen on another address or port:
+
+```bash
+cargo run --release --locked -- -l 0.0.0.0:8000
 ```
-Cargo.toml                  Project manifest and dependencies
-build.rs                    Captures rustc version + target at compile time
-src/
-  main.rs                   Entrypoint; HTTP router, login/logout handlers, tracing init
-  config.rs                 3-tier config system (default → DB → env); FURU_* env vars
-  auth.rs                   Session auth, Role enum (Admin/User), login/logout/guards
-  user.rs                   User + OidcLink DB models, CRUD, password hashing, migrations
-  oidc.rs                   OIDC/SSO flow: discovery, PKCE, token exchange, user provisioning
-  i18n/
-    mod.rs                  Language resolution (cookie → Accept-Language → default), extractor
-    phrases.rs              All UI strings in English and Russian (translations! macro)
-  api/
-    mod.rs                  JSON API endpoints (mounted at /api), session-based auth
-  admin/
-    mod.rs                  Admin sub-app router: dashboard, settings, users, debug, setup
-    views.rs                Admin page handlers and templates
-templates/
-  base.html                 Root HTML layout with lang/title blocks
-  login.html                Login page (password + optional SSO button)
-  admin/
-    layout.html             Admin sidebar/nav wrapper
-    index.html              Admin dashboard
-    debug.html              Build info + config table (with secret redaction)
-    settings.html           OIDC and auth settings form
-    setup.html              First-run admin account creation
-    users.html              User list
-    user_form.html          User create/edit form
+
+A Nix development shell is included for Linux and macOS:
+
+```bash
+nix develop
+cargo run --locked
 ```
 
+The repository also contains a multi-stage `Dockerfile` for building a small
+runtime image. A deployment must provide PostgreSQL plus persistent, writable
+volumes for the inbox and music library.
+
+## Configuration
+
+Most settings can be changed from the administration interface. Every setting
+also has a `FURU_`-prefixed environment variable; environment values take
+priority over values stored in PostgreSQL.
+
+The settings needed for a useful first installation are:
+
+| Setting | Purpose |
+| --- | --- |
+| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service |
+| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files |
+| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library |
+| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline |
+| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server |
+| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata |
+| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery |
+| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network |
+
+AI recognition, federation, similarity search, Last.fm, and OIDC are optional.
+A local password-authenticated server can be used without any of them.
+
 ## Architecture
 
-### Config system (`src/config.rs`)
+Furumusic is written in Rust on the
+[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts,
+playlists, configuration, and background-job state. Audio inspection uses
+Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid
+protocol stack provides decentralized catalog search, media transfer, and
+connected-device synchronization.
 
-Every setting lives in `AppConfig` and is resolved in three layers:
+The browser interface and JSON API are served by the same application. Import,
+artwork, metadata enrichment, similarity indexing, and maintenance run as
+durable background jobs rather than blocking playback requests.
 
-1. **Compiled default** — `AppConfig::default()`
-2. **Database override** — rows in the `furumusic__config_entry` table
-3. **Environment variable** — `FURU_<FIELD_NAME>` (highest priority)
+## Contributing
 
-`ConfigSources` tracks where each field's effective value came from (shown in the admin debug page).
+Bug reports, design discussions, and patches are welcome. Before submitting a
+change, run:
 
-**To add a new config field:**
-
-1. Add the field to `AppConfig` struct
-2. Set its default in `AppConfig::default()`
-3. Add the field to `ConfigSources` struct and its `Default` impl
-4. Add it to the `impl_env_overrides!(…)` invocation
-5. Add an `apply_db_field!()` call in `apply_db_overrides`
-6. Add an `entry!()` line in `admin/views.rs → config_display_entries()`
-
-### Auth (`src/auth.rs`)
-
-Session-based authentication with two roles:
-
-- **`Role::Admin`** — full access to admin panel
-- **`Role::User`** — standard user
-
-Key functions:
-- `login(session, user_id)` — sets session, cycles session ID
-- `logout(session)` — flushes session
-- `get_session_user(session, db)` — returns `AuthenticatedUser` if active
-- `require_admin_or_redirect(session, db)` — guard that returns 403 or redirects to `/login`
-
-### OIDC/SSO (`src/oidc.rs`)
-
-Full OpenID Connect authorization code flow with PKCE:
-
-1. `GET /auth/oidc/start` — discovers provider, builds auth URL, stores CSRF/nonce/PKCE in session, redirects to IdP
-2. `GET /auth/oidc/callback` — validates CSRF, exchanges code for tokens, verifies ID token, provisions user
-
-Provider metadata is cached for 1 hour and invalidated when OIDC config changes.
-
-**Group access and role mapping:** The `oidc_user_groups` config field lists OIDC group names (comma-separated) allowed to access the service. When it is set, users outside both `oidc_user_groups` and `oidc_admin_groups` are denied before provisioning/login. The `oidc_admin_groups` config field lists OIDC group names that grant the admin role. Groups are extracted from the `groups` claim in the ID token JWT payload.
-
-**User provisioning order:**
-1. Find existing `OidcLink` by issuer+sub → update claims, update role
-2. Find existing `User` by email → create OidcLink, update role
-3. Create new user (no password) + OidcLink
-
-Stale links (pointing to deleted users) are cleaned up automatically.
-
-### User model (`src/user.rs`)
-
-Two database models:
-
-- **`User`** — id, username (unique), password (optional for OIDC-only), email, display_name, avatar_url, role, is_active
-- **`OidcLink`** — id, user_id, issuer, sub, email, name, avatar_url; unique index on (issuer, sub)
-
-Migrations: M0003 (User table), M0004 (OidcLink table), M0005 (OidcLink indexes).
-
-### i18n (`src/i18n/`)
-
-Compile-time bilingual UI (English + Russian).
-
-- `translations!` macro in `phrases.rs` generates a `Translations` struct with static `EN` and `RU` instances
-- Language resolution: `furu_lang` cookie → `Accept-Language` header → English default
-- `I18n` is a cot request extractor — handlers receive it automatically
-- `set_lang` endpoint (`/set-lang?lang=ru&next=/`) sets the cookie
-
-### API (`src/api/`)
-
-JSON API mounted at `/api`. Uses the same session cookie as HTML pages — works automatically for same-origin frontend requests (no CORS, no tokens needed).
-
-Helpers in `api/mod.rs`:
-- `json_ok(value)` — 200 with `application/json`
-- `json_error(status, message)` — error response as `{"error": "..."}`
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/api/me` | GET | Current user (id, name, role) or 401 |
-
-**Swagger UI** is available at `/swagger/` when `FURU_SWAGGER_ENABLED=true`. The OpenAPI spec is auto-generated from handler types.
-
-To add a new API endpoint:
-1. Define request/response structs with `#[derive(Serialize, JsonSchema)]`
-2. Write an async handler, return `Json(response).into_response()`
-3. Add a `Route::with_api_handler_and_name(…, api_get(handler), …)` in `ApiApp::router()`
-4. The endpoint appears automatically in Swagger UI
-
-### Admin panel (`src/admin/`)
-
-Mounted at `/admin`. All routes (except `/admin/setup`) require `Role::Admin`.
-
-| Route | Purpose |
-|-------|---------|
-| `/admin/setup` | First-run: create initial admin (only works when zero users exist) |
-| `/admin/` | Dashboard |
-| `/admin/debug` | Build info, config values with sources, DB connectivity |
-| `/admin/settings` | OIDC config, auth toggles (saved to DB config table) |
-| `/admin/users` | User list |
-| `/admin/users/new` | Create user |
-| `/admin/users/{id}/edit` | Edit user |
-| `/admin/users/{id}/delete` | Delete user (POST) |
-
-## How to extend
-
-### 1. Add a config field
-
-See [Config system](#config-system-srcconfigrs) above — 6 locations to update.
-
-### 2. Add a database model
-
-1. Define a struct with `#[cot::db::model]` in a new or existing file
-2. Write a migration struct implementing `cot::db::migrations::Migration`
-3. Register the migration in the `AdminApp::migrations()` method in `src/admin/mod.rs`
-
-### 3. Add a page
-
-1. Create a template in `templates/`
-2. Write a handler function that returns `Html`
-3. Add a `Route::with_handler_and_name(…)` in the appropriate `router()` method
-4. If admin-only, wrap with `require_admin_or_redirect`
-
-### 4. Add a translation
-
-Add a line to the `translations!` macro in `src/i18n/phrases.rs`:
-
-```rust
-my_key: "English text", "Русский текст";
+```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
+cargo test --all-targets
 ```
-
-Access it in handlers/templates as `i18n.t.my_key` (or `t.my_key` in templates).
-
-### 5. Add an API endpoint
-
-Same as adding a page, but return a JSON response instead of `Html`. The `json` feature is enabled in Cargo.toml.
-
-## Environment variables
-
-All prefixed with `FURU_`. Priority: env var > DB override > compiled default.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `FURU_DATABASE_URL` | PostgreSQL connection URL | *(empty — required)* |
-| `FURU_LOG_LEVEL` | Tracing filter (e.g. `info`, `debug`, `warn,furumusic=trace`) | `info` |
-| `FURU_AUTH_PASSWORD_ENABLED` | Enable password login | `true` |
-| `FURU_AUTH_SSO_ENABLED` | Enable SSO/OIDC login | `false` |
-| `FURU_OIDC_ISSUER` | OIDC issuer URL | *(empty)* |
-| `FURU_OIDC_CLIENT_ID` | OIDC client ID | *(empty)* |
-| `FURU_OIDC_CLIENT_SECRET` | OIDC client secret | *(empty)* |
-| `FURU_OIDC_BUTTON_TEXT` | SSO button label | `Sign in with SSO` |
-| `FURU_OIDC_ADMIN_GROUPS` | Comma-separated OIDC groups that grant admin | *(empty)* |
-| `FURU_OIDC_USER_GROUPS` | Comma-separated OIDC groups allowed to access the service. Empty means any authenticated SSO user is allowed. | *(empty)* |
-| `FURU_SWAGGER_ENABLED` | Serve Swagger UI at `/swagger/` | `false` |

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1786106723,
+        "narHash": "sha256-zDSUbpoeo/9ZmD2+wXnzxoo1+uhL8vxc0b8yuYMKYq0=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "f13ff45afd1bb73e640eaa08a7066dbed07e3238",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,41 @@
+{
+  description = "Furumusic development environment";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs = { nixpkgs, ... }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forEachSystem = function:
+        nixpkgs.lib.genAttrs supportedSystems (system:
+          function (import nixpkgs { inherit system; }));
+    in
+    {
+      devShells = forEachSystem (pkgs: {
+        default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [
+            cargo
+            clippy
+            pkg-config
+            rustc
+            rustfmt
+          ];
+
+          buildInputs = with pkgs; [
+            cacert
+            deno
+            ffmpeg-headless
+            openssl
+            yt-dlp
+          ] ++ lib.optionals stdenv.isDarwin [ libiconv ];
+
+          RUST_SRC_PATH = "${pkgs.rustPlatform.rustLibSrc}";
+        };
+      });
+    };
+}

src/admin/mod.rs

@@ -422,6 +422,20 @@ impl App for AdminApp {
                 }),
                 "admin_v2_federation_status",
             ),
+            Route::with_handler_and_name(
+                "/v2/api/similarity",
+                get(move |session: Session, db: Database| async move {
+                    v2::similarity_status(session, db).await
+                }),
+                "admin_v2_similarity_status",
+            ),
+            Route::with_handler_and_name(
+                "/v2/api/similarity/clear",
+                cot::router::method::post(move |session: Session, db: Database| async move {
+                    v2::similarity_clear(session, db).await
+                }),
+                "admin_v2_similarity_clear",
+            ),
             Route::with_handler_and_name(
                 "/v2/api/federation/sync",
                 cot::router::method::post(move |session: Session, db: Database| async move {
@@ -697,6 +711,34 @@ impl App for AdminApp {
                 },
                 "admin_v2_library_bulk",
             ),
+            Route::with_handler_and_name(
+                "/v2/api/library/releases/merge",
+                {
+                    let pool = Arc::clone(&pool);
+                    let pool_config = Arc::clone(&pool_config);
+                    cot::router::method::post(
+                        move |session: Session,
+                              db: Database,
+                              json: Json<v2::MergeReleasesRequest>| {
+                            let pool = Arc::clone(&pool);
+                            let pool_config = Arc::clone(&pool_config);
+                            async move {
+                                let pg_pool = pool
+                                    .get_or_init(|| async {
+                                        sqlx::postgres::PgPoolOptions::new()
+                                            .max_connections(5)
+                                            .connect(&pool_config.database_url)
+                                            .await
+                                            .expect("admin pool")
+                                    })
+                                    .await;
+                                v2::merge_releases(session, db, pg_pool, json).await
+                            }
+                        },
+                    )
+                },
+                "admin_v2_library_releases_merge",
+            ),
             // -- Dashboard ----------------------------------------------------
             Route::with_handler_and_name(
                 "/",
@@ -1055,19 +1097,34 @@ impl App for AdminApp {
                 ),
                 "admin_releases_edit",
             ),
-            Route::with_handler_and_name(
-                "/releases/{id}/delete",
-                cot::router::method::post(
-                    |session: Session, db: Database, path: Path<PathId>| async move {
-                        let admin = match auth::require_admin_or_redirect(&session, &db).await {
-                            Ok(u) => u,
-                            Err(resp) => return Ok(resp),
-                        };
-                        views::releases_delete(admin, &db, path.0.id).await
-                    },
-                ),
-                "admin_releases_delete",
-            ),
+            {
+                let pool = Arc::clone(&pool);
+                let pool_config = Arc::clone(&pool_config);
+                Route::with_handler_and_name(
+                    "/releases/{id}/delete",
+                    cot::router::method::post(move |session: Session, db: Database, path: Path<PathId>| {
+                        let pool = Arc::clone(&pool);
+                        let pool_config = Arc::clone(&pool_config);
+                        async move {
+                            let admin = match auth::require_admin_or_redirect(&session, &db).await {
+                                Ok(u) => u,
+                                Err(resp) => return Ok(resp),
+                            };
+                            let pg_pool = pool
+                                .get_or_init(|| async {
+                                    sqlx::postgres::PgPoolOptions::new()
+                                        .max_connections(5)
+                                        .connect(&pool_config.database_url)
+                                        .await
+                                        .expect("admin pool")
+                                })
+                                .await;
+                            views::releases_delete(admin, &db, pg_pool, path.0.id).await
+                        }
+                    }),
+                    "admin_releases_delete",
+                )
+            },
             // -- Media Files --------------------------------------------------
             Route::with_handler_and_name(
                 "/media-files",

src/admin/v2.rs

@@ -16,7 +16,7 @@ use sqlx::{PgPool, Postgres, QueryBuilder};
 use super::BUILD_INFO;
 use crate::agent;
 use crate::auth::{self, AuthenticatedUser, Role};
-use crate::config::{AppConfig, ConfigEntry, ConfigSources};
+use crate::config::{AppConfig, ConfigEntry, ConfigSources, DownloadProxy};
 use crate::i18n::{I18n, Translations};
 use crate::scheduler::{self, JobRegistry, JobRun, ScheduledJob};
 
@@ -69,6 +69,21 @@ pub(super) struct BulkLibraryRequest {
     filter: Option<LibraryFilter>,
 }
 
+#[derive(Debug, Deserialize)]
+pub(super) struct MergeReleasesRequest {
+    release_ids: Vec<i64>,
+    target_release_id: i64,
+    title: String,
+    release_type: String,
+    #[serde(default, deserialize_with = "deserialize_optional_stringish")]
+    year: Option<String>,
+    hidden: bool,
+    cover_file_id: Option<i64>,
+    #[serde(default)]
+    artist_ids: Vec<i64>,
+    tracks: Vec<ReleaseTrackUpdateRequest>,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct MetadataBackfillRunRequest {
     #[serde(default = "default_true")]
@@ -417,6 +432,14 @@ struct MutationResponse {
     affected: u64,
 }
 
+#[derive(Debug, Serialize, JsonSchema)]
+struct MergeReleasesResponse {
+    ok: bool,
+    merged_releases: u64,
+    moved_tracks: u64,
+    item: LibraryItemDto,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 struct AdminSettingsDto {
     values: AdminSettingsValues,
@@ -452,6 +475,60 @@ struct AdminSettingsValues {
     federation_enabled: bool,
     #[serde(default)]
     federation_network_id: String,
+    #[serde(default)]
+    federation_save_on_listen: bool,
+    #[serde(default)]
+    similarity_enabled: bool,
+    #[serde(default = "default_similarity_model")]
+    similarity_model: String,
+    #[serde(default = "default_similarity_profile")]
+    similarity_profile: String,
+    #[serde(default = "default_similarity_workers")]
+    similarity_workers: String,
+    #[serde(default = "default_true")]
+    downloads_enabled: bool,
+    #[serde(default = "default_true")]
+    torrent_downloads_enabled: bool,
+    #[serde(default = "default_true")]
+    youtube_downloads_enabled: bool,
+    #[serde(default)]
+    download_proxies: Vec<AdminDownloadProxy>,
+    #[serde(default)]
+    torrent_proxy_id: String,
+    #[serde(default)]
+    youtube_proxy_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+struct AdminDownloadProxy {
+    id: String,
+    address: String,
+    #[serde(default)]
+    username: String,
+    #[serde(default)]
+    password: String,
+}
+
+impl From<DownloadProxy> for AdminDownloadProxy {
+    fn from(proxy: DownloadProxy) -> Self {
+        Self {
+            id: proxy.id,
+            address: proxy.address,
+            username: proxy.username,
+            password: proxy.password,
+        }
+    }
+}
+
+impl From<AdminDownloadProxy> for DownloadProxy {
+    fn from(proxy: AdminDownloadProxy) -> Self {
+        Self {
+            id: proxy.id,
+            address: proxy.address,
+            username: proxy.username,
+            password: proxy.password,
+        }
+    }
 }
 
 #[derive(Debug, Clone, Serialize, JsonSchema)]
@@ -478,6 +555,17 @@ struct AdminSettingsSources {
     agent_concurrency: &'static str,
     federation_enabled: &'static str,
     federation_network_id: &'static str,
+    federation_save_on_listen: &'static str,
+    similarity_enabled: &'static str,
+    similarity_model: &'static str,
+    similarity_profile: &'static str,
+    similarity_workers: &'static str,
+    downloads_enabled: &'static str,
+    torrent_downloads_enabled: &'static str,
+    youtube_downloads_enabled: &'static str,
+    download_proxies: &'static str,
+    torrent_proxy_id: &'static str,
+    youtube_proxy_id: &'static str,
 }
 
 #[derive(Debug, Deserialize)]
@@ -506,6 +594,40 @@ pub(super) struct UpdateSettingsRequest {
     federation_enabled: bool,
     #[serde(default)]
     federation_network_id: String,
+    #[serde(default)]
+    federation_save_on_listen: bool,
+    #[serde(default)]
+    similarity_enabled: bool,
+    #[serde(default = "default_similarity_model")]
+    similarity_model: String,
+    #[serde(default = "default_similarity_profile")]
+    similarity_profile: String,
+    #[serde(default = "default_similarity_workers")]
+    similarity_workers: String,
+    #[serde(default = "default_true")]
+    downloads_enabled: bool,
+    #[serde(default = "default_true")]
+    torrent_downloads_enabled: bool,
+    #[serde(default = "default_true")]
+    youtube_downloads_enabled: bool,
+    #[serde(default)]
+    download_proxies: Vec<AdminDownloadProxy>,
+    #[serde(default)]
+    torrent_proxy_id: String,
+    #[serde(default)]
+    youtube_proxy_id: String,
+}
+
+fn default_similarity_model() -> String {
+    crate::similarity::DEFAULT_MODEL_ID.to_owned()
+}
+
+fn default_similarity_profile() -> String {
+    crate::similarity::DEFAULT_PROFILE_ID.to_owned()
+}
+
+fn default_similarity_workers() -> String {
+    "1".to_owned()
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -560,6 +682,7 @@ struct LibraryItemDetailDto {
     release_id: Option<i64>,
     track_number: Option<i32>,
     disc_number: Option<i32>,
+    current_image_file_id: Option<i64>,
     current_image_url: Option<String>,
     selected_artist_ids: Vec<i64>,
     artists: Vec<ArtistOptionDto>,
@@ -943,6 +1066,70 @@ pub async fn update_settings(
     if let Err(response) = require_admin_json(&session, &db).await {
         return Ok(response);
     }
+    let similarity_model = body.similarity_model.trim().to_string();
+    if crate::similarity::model_by_id(&similarity_model).is_none() {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "unknown similarity model",
+        ));
+    }
+    let similarity_profile = body.similarity_profile.trim().to_string();
+    if crate::similarity::profile_by_id(&similarity_profile).is_none() {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "unknown similarity preprocessing profile",
+        ));
+    }
+    let similarity_workers = match body.similarity_workers.trim().parse::<u64>() {
+        Ok(workers @ 1..=16) => workers,
+        _ => {
+            return Ok(json_error(
+                StatusCode::BAD_REQUEST,
+                "similarity workers must be an integer from 1 to 16",
+            ));
+        }
+    };
+    if body.download_proxies.len() > 32 {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "at most 32 download proxies can be saved",
+        ));
+    }
+    let mut download_proxies = Vec::with_capacity(body.download_proxies.len());
+    let mut proxy_ids = HashSet::new();
+    for (index, proxy) in body.download_proxies.into_iter().enumerate() {
+        let proxy = match DownloadProxy::from(proxy).normalized() {
+            Ok(proxy) => proxy,
+            Err(error) => {
+                return Ok(json_error(
+                    StatusCode::BAD_REQUEST,
+                    &format!("proxy {}: {error}", index + 1),
+                ));
+            }
+        };
+        if !proxy_ids.insert(proxy.id.clone()) {
+            return Ok(json_error(
+                StatusCode::BAD_REQUEST,
+                "download proxy ids must be unique",
+            ));
+        }
+        download_proxies.push(proxy);
+    }
+    let torrent_proxy_id = body.torrent_proxy_id.trim().to_string();
+    let youtube_proxy_id = body.youtube_proxy_id.trim().to_string();
+    for (method, proxy_id) in [
+        ("torrent", torrent_proxy_id.as_str()),
+        ("YouTube", youtube_proxy_id.as_str()),
+    ] {
+        if !proxy_id.is_empty() && !proxy_ids.contains(proxy_id) {
+            return Ok(json_error(
+                StatusCode::BAD_REQUEST,
+                &format!("selected {method} proxy is not in the saved proxy list"),
+            ));
+        }
+    }
+    let download_proxies_json = serde_json::to_string(&download_proxies)
+        .map_err(|error| cot::Error::internal(error.to_string()))?;
     let fields = [
         (
             "auth_password_enabled",
@@ -993,6 +1180,26 @@ pub async fn update_settings(
             "federation_network_id",
             body.federation_network_id.trim().to_string(),
         ),
+        (
+            "federation_save_on_listen",
+            body.federation_save_on_listen.to_string(),
+        ),
+        ("similarity_enabled", body.similarity_enabled.to_string()),
+        ("similarity_model", similarity_model),
+        ("similarity_profile", similarity_profile),
+        ("similarity_workers", similarity_workers.to_string()),
+        ("downloads_enabled", body.downloads_enabled.to_string()),
+        (
+            "torrent_downloads_enabled",
+            body.torrent_downloads_enabled.to_string(),
+        ),
+        (
+            "youtube_downloads_enabled",
+            body.youtube_downloads_enabled.to_string(),
+        ),
+        ("download_proxies", download_proxies_json),
+        ("torrent_proxy_id", torrent_proxy_id),
+        ("youtube_proxy_id", youtube_proxy_id),
     ];
     for (key, value) in fields {
         let mut entry = ConfigEntry::new(key.to_string(), value);
@@ -1005,6 +1212,7 @@ pub async fn update_settings(
     // the freshly saved settings — no server restart involved.
     let (fresh, _) = AppConfig::load_with_db(&db).await;
     tokio::spawn(async move {
+        crate::similarity::handle().apply(&fresh);
         crate::federation::handle().apply(&fresh).await;
     });
     Json(serde_json::json!({ "ok": true })).into_response()
@@ -1024,6 +1232,57 @@ pub async fn federation_status(
     Json(crate::federation::handle().status().await).into_response()
 }
 
+pub async fn similarity_status(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    let manager = crate::similarity::handle();
+    let status = manager.status();
+    let model_id = if status.model.is_empty() {
+        crate::similarity::DEFAULT_MODEL_ID
+    } else {
+        &status.model
+    };
+    let profiles = crate::similarity::PROFILES
+        .iter()
+        .map(|profile| {
+            serde_json::json!({
+                "id": profile.id,
+                "title": profile.title,
+                "details": crate::similarity::profile_details(
+                    profile.id,
+                    model_id,
+                ).unwrap_or_default(),
+            })
+        })
+        .collect::<Vec<_>>();
+    Json(serde_json::json!({
+        "status": status,
+        "models": crate::similarity::MODELS,
+        "profiles": profiles,
+    }))
+    .into_response()
+}
+
+pub async fn similarity_clear(
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+    match crate::similarity::handle().clear().await {
+        Ok(()) => Json(serde_json::json!({ "ok": true })).into_response(),
+        Err(error) => Ok(json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("embedding cleanup failed: {error:#}"),
+        )),
+    }
+}
+
 pub async fn federation_sync(
     session: Session,
     db: Database,
@@ -1115,6 +1374,15 @@ pub async fn settings_probe(
 }
 
 fn settings_dto(config: AppConfig, sources: ConfigSources) -> AdminSettingsDto {
+    let download_proxies = config
+        .parsed_download_proxies()
+        .unwrap_or_else(|error| {
+            tracing::warn!(%error, "ignoring invalid saved download proxy list");
+            Vec::new()
+        })
+        .into_iter()
+        .map(AdminDownloadProxy::from)
+        .collect();
     AdminSettingsDto {
         lastfm_api_key_configured: !config.lastfm_api_key.trim().is_empty(),
         lastfm_shared_secret_configured: !config.lastfm_shared_secret.trim().is_empty(),
@@ -1143,6 +1411,17 @@ fn settings_dto(config: AppConfig, sources: ConfigSources) -> AdminSettingsDto {
             agent_concurrency: config.agent_concurrency.to_string(),
             federation_enabled: config.federation_enabled,
             federation_network_id: config.federation_network_id,
+            federation_save_on_listen: config.federation_save_on_listen,
+            similarity_enabled: config.similarity_enabled,
+            similarity_model: config.similarity_model,
+            similarity_profile: config.similarity_profile,
+            similarity_workers: config.similarity_workers.to_string(),
+            downloads_enabled: config.downloads_enabled,
+            torrent_downloads_enabled: config.torrent_downloads_enabled,
+            youtube_downloads_enabled: config.youtube_downloads_enabled,
+            download_proxies,
+            torrent_proxy_id: config.torrent_proxy_id,
+            youtube_proxy_id: config.youtube_proxy_id,
         },
         sources: AdminSettingsSources {
             auth_password_enabled: sources.auth_password_enabled.code(),
@@ -1167,6 +1446,17 @@ fn settings_dto(config: AppConfig, sources: ConfigSources) -> AdminSettingsDto {
             agent_concurrency: sources.agent_concurrency.code(),
             federation_enabled: sources.federation_enabled.code(),
             federation_network_id: sources.federation_network_id.code(),
+            federation_save_on_listen: sources.federation_save_on_listen.code(),
+            similarity_enabled: sources.similarity_enabled.code(),
+            similarity_model: sources.similarity_model.code(),
+            similarity_profile: sources.similarity_profile.code(),
+            similarity_workers: sources.similarity_workers.code(),
+            downloads_enabled: sources.downloads_enabled.code(),
+            torrent_downloads_enabled: sources.torrent_downloads_enabled.code(),
+            youtube_downloads_enabled: sources.youtube_downloads_enabled.code(),
+            download_proxies: sources.download_proxies.code(),
+            torrent_proxy_id: sources.torrent_proxy_id.code(),
+            youtube_proxy_id: sources.youtube_proxy_id.code(),
         },
     }
 }
@@ -1800,10 +2090,182 @@ pub async fn bulk_library(
         .into_response();
     }
 
-    let affected = apply_library_action(pool, &kind, action, &ids).await?;
+    let storage_dir = if action == "delete" && matches!(kind.as_str(), "releases" | "tracks") {
+        AppConfig::load_with_db(&db).await.0.agent_storage_dir
+    } else {
+        String::new()
+    };
+    let affected = apply_library_action(pool, &kind, action, &ids, &storage_dir).await?;
     Json(MutationResponse { ok: true, affected }).into_response()
 }
 
+pub async fn merge_releases(
+    session: Session,
+    db: Database,
+    pool: &PgPool,
+    Json(body): Json<MergeReleasesRequest>,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+
+    let mut release_ids = body.release_ids;
+    release_ids.retain(|id| *id > 0);
+    release_ids.sort_unstable();
+    release_ids.dedup();
+    if release_ids.len() < 2 {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "select at least two releases to merge",
+        ));
+    }
+    if release_ids.len() > 250 {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "at most 250 releases can be merged at once",
+        ));
+    }
+    if !release_ids.contains(&body.target_release_id) {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "destination release must be part of the selection",
+        ));
+    }
+
+    let title = body.title.trim();
+    if title.is_empty() {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "title cannot be empty"));
+    }
+    if title.chars().count() > 255 {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "title cannot exceed 255 characters",
+        ));
+    }
+    let release_type = body.release_type.trim().to_lowercase();
+    if !matches!(
+        release_type.as_str(),
+        "album"
+            | "single"
+            | "ep"
+            | "compilation"
+            | "mixtape"
+            | "live"
+            | "soundtrack"
+            | "remix"
+            | "demo"
+            | "unknown"
+    ) {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "invalid release type"));
+    }
+    let year = match parse_merge_optional_i32(body.year.as_deref(), 0, 3000, "year") {
+        Ok(year) => year,
+        Err(message) => return Ok(json_error(StatusCode::BAD_REQUEST, &message)),
+    };
+
+    let mut tracks = Vec::with_capacity(body.tracks.len());
+    for track in body.tracks {
+        if track.id <= 0 {
+            return Ok(json_error(StatusCode::BAD_REQUEST, "invalid track id"));
+        }
+        let track_number = match parse_merge_optional_i32(
+            track.track_number.as_deref(),
+            1,
+            9999,
+            "track number",
+        ) {
+            Ok(value) => value,
+            Err(message) => return Ok(json_error(StatusCode::BAD_REQUEST, &message)),
+        };
+        let disc_number =
+            match parse_merge_optional_i32(track.disc_number.as_deref(), 1, 999, "disc number") {
+                Ok(value) => value,
+                Err(message) => return Ok(json_error(StatusCode::BAD_REQUEST, &message)),
+            };
+        tracks.push(crate::library_cleanup::ReleaseMergeTrack {
+            id: track.id,
+            track_number,
+            disc_number,
+        });
+    }
+
+    let existing_release_ids: Vec<i64> =
+        sqlx::query_scalar("SELECT id FROM furumusic__release WHERE id = ANY($1) ORDER BY id")
+            .bind(&release_ids)
+            .fetch_all(pool)
+            .await
+            .map_err(|error| cot::Error::internal(error.to_string()))?;
+    if existing_release_ids != release_ids {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "one or more selected releases no longer exist",
+        ));
+    }
+    let selected_track_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__track WHERE release_id = ANY($1) ORDER BY id",
+    )
+    .bind(&release_ids)
+    .fetch_all(pool)
+    .await
+    .map_err(|error| cot::Error::internal(error.to_string()))?;
+    let mut requested_track_ids = tracks.iter().map(|track| track.id).collect::<Vec<_>>();
+    requested_track_ids.sort_unstable();
+    if requested_track_ids.windows(2).any(|ids| ids[0] == ids[1])
+        || requested_track_ids != selected_track_ids
+    {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "track list does not match the selected releases; reopen the merge wizard",
+        ));
+    }
+
+    let storage_dir = AppConfig::load_with_db(&db).await.0.agent_storage_dir;
+    let result = match crate::library_cleanup::merge_releases(
+        pool,
+        crate::library_cleanup::ReleaseMergeSpec {
+            release_ids,
+            target_release_id: body.target_release_id,
+            title: title.to_owned(),
+            title_sort: normalize_name(title),
+            release_type,
+            year,
+            hidden: body.hidden,
+            cover_file_id: body.cover_file_id,
+            artist_ids: body.artist_ids,
+            tracks,
+        },
+        &storage_dir,
+    )
+    .await
+    {
+        Ok(result) => result,
+        Err(error) => {
+            tracing::error!(?error, "release merge failed");
+            return Ok(json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "release merge failed; no changes were committed",
+            ));
+        }
+    };
+
+    let Some(item) = fetch_library_item(pool, "releases", body.target_release_id)
+        .await
+        .map_err(|error| cot::Error::internal(error.to_string()))?
+    else {
+        return Ok(json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "merged release could not be loaded",
+        ));
+    };
+    Json(MergeReleasesResponse {
+        ok: true,
+        merged_releases: result.merged_releases,
+        moved_tracks: result.moved_tracks,
+        item,
+    })
+    .into_response()
+}
+
 async fn require_admin_json(
     session: &Session,
     db: &Database,
@@ -2873,6 +3335,7 @@ async fn load_library_item_detail(
         release_id: None,
         track_number: None,
         disc_number: None,
+        current_image_file_id: None,
         current_image_url: None,
         selected_artist_ids: Vec::new(),
         artists: Vec::new(),
@@ -2893,6 +3356,7 @@ async fn load_library_item_detail(
                     .flatten();
             detail.current_image_url =
                 image_file_id.map(|id| format!("/api/player/cover/{id}/large"));
+            detail.current_image_file_id = image_file_id;
             detail.available_covers = artist_available_covers(pool, detail.item.id).await?;
         }
         "releases" => {
@@ -2907,6 +3371,7 @@ async fn load_library_item_detail(
                 detail.year = year;
                 detail.current_image_url =
                     cover_file_id.map(|id| format!("/api/player/cover/{id}/large"));
+                detail.current_image_file_id = cover_file_id;
             }
             detail.selected_artist_ids = sqlx::query_as::<_, IdRow>(
                 "SELECT artist_id AS id FROM furumusic__release_artist WHERE release_id = $1 ORDER BY position, artist_id",
@@ -3354,10 +3819,11 @@ async fn apply_library_action(
     kind: &str,
     action: &str,
     ids: &[i64],
+    storage_dir: &str,
 ) -> cot::Result<u64> {
     match action {
         "hide" | "show" => set_library_visibility(pool, kind, ids, action == "hide").await,
-        "delete" => delete_library_items(pool, kind, ids).await,
+        "delete" => delete_library_items(pool, kind, ids, storage_dir).await,
         _ => Ok(0),
     }
 }
@@ -3408,10 +3874,15 @@ async fn set_library_visibility(
     Ok(result.rows_affected())
 }
 
-async fn delete_library_items(pool: &PgPool, kind: &str, ids: &[i64]) -> cot::Result<u64> {
+async fn delete_library_items(
+    pool: &PgPool,
+    kind: &str,
+    ids: &[i64],
+    storage_dir: &str,
+) -> cot::Result<u64> {
     match kind {
-        "releases" => delete_releases(pool, ids).await,
-        "tracks" => delete_tracks(pool, ids).await,
+        "releases" => delete_releases(pool, ids, storage_dir).await,
+        "tracks" => delete_tracks(pool, ids, storage_dir).await,
         "playlists" => delete_playlists(pool, ids).await,
         _ => delete_artists(pool, ids).await,
     }
@@ -3441,95 +3912,16 @@ async fn delete_artists(pool: &PgPool, ids: &[i64]) -> cot::Result<u64> {
     Ok(result.rows_affected())
 }
 
-async fn delete_releases(pool: &PgPool, ids: &[i64]) -> cot::Result<u64> {
-    let track_ids =
-        sqlx::query_as::<_, IdRow>("SELECT id FROM furumusic__track WHERE release_id = ANY($1)")
-            .bind(ids)
-            .fetch_all(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?
-            .into_iter()
-            .map(|row| row.id)
-            .collect::<Vec<_>>();
-
-    if !track_ids.is_empty() {
-        sqlx::query("DELETE FROM furumusic__playlist_track WHERE track_id = ANY($1)")
-            .bind(&track_ids)
-            .execute(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?;
-        sqlx::query("DELETE FROM furumusic__user_liked_track WHERE track_id = ANY($1)")
-            .bind(&track_ids)
-            .execute(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?;
-        sqlx::query("DELETE FROM furumusic__play_history WHERE track_id = ANY($1)")
-            .bind(&track_ids)
-            .execute(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?;
-        sqlx::query("DELETE FROM furumusic__track_genre WHERE track_id = ANY($1)")
-            .bind(&track_ids)
-            .execute(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?;
-        sqlx::query("DELETE FROM furumusic__track_artist WHERE track_id = ANY($1)")
-            .bind(&track_ids)
-            .execute(pool)
-            .await
-            .map_err(|e| cot::Error::internal(e.to_string()))?;
-    }
-
-    sqlx::query("DELETE FROM furumusic__track WHERE release_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
+async fn delete_releases(pool: &PgPool, ids: &[i64], storage_dir: &str) -> cot::Result<u64> {
+    crate::library_cleanup::delete_releases(pool, ids, storage_dir)
         .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    sqlx::query("DELETE FROM furumusic__release_artist WHERE release_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    let result = sqlx::query("DELETE FROM furumusic__release WHERE id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    Ok(result.rows_affected())
+        .map_err(|error| cot::Error::internal(error.to_string()))
 }
 
-async fn delete_tracks(pool: &PgPool, ids: &[i64]) -> cot::Result<u64> {
-    sqlx::query("DELETE FROM furumusic__playlist_track WHERE track_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
+async fn delete_tracks(pool: &PgPool, ids: &[i64], storage_dir: &str) -> cot::Result<u64> {
+    crate::library_cleanup::delete_tracks(pool, ids, storage_dir)
         .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    sqlx::query("DELETE FROM furumusic__user_liked_track WHERE track_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    sqlx::query("DELETE FROM furumusic__play_history WHERE track_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    sqlx::query("DELETE FROM furumusic__track_genre WHERE track_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    sqlx::query("DELETE FROM furumusic__track_artist WHERE track_id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    let result = sqlx::query("DELETE FROM furumusic__track WHERE id = ANY($1)")
-        .bind(ids)
-        .execute(pool)
-        .await
-        .map_err(|e| cot::Error::internal(e.to_string()))?;
-    Ok(result.rows_affected())
+        .map_err(|error| cot::Error::internal(error.to_string()))
 }
 
 async fn delete_playlists(pool: &PgPool, ids: &[i64]) -> cot::Result<u64> {
@@ -3916,6 +4308,24 @@ fn parse_optional_admin_i32(value: Option<&str>, min: i32, max: i32) -> Option<i
         .map(|parsed| parsed.clamp(min, max))
 }
 
+fn parse_merge_optional_i32(
+    value: Option<&str>,
+    min: i32,
+    max: i32,
+    field: &str,
+) -> Result<Option<i32>, String> {
+    let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(None);
+    };
+    let parsed = value
+        .parse::<i32>()
+        .map_err(|_| format!("{field} must be an integer from {min} to {max}"))?;
+    if !(min..=max).contains(&parsed) {
+        return Err(format!("{field} must be from {min} to {max}"));
+    }
+    Ok(Some(parsed))
+}
+
 fn deserialize_optional_stringish<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
 where
     D: Deserializer<'de>,
@@ -3989,3 +4399,22 @@ fn size_display(bytes: i64) -> String {
         format!("{bytes} B")
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::parse_merge_optional_i32;
+
+    #[test]
+    fn merge_numbers_preserve_empty_values_and_reject_invalid_input() {
+        assert_eq!(
+            parse_merge_optional_i32(None, 1, 9999, "track number").unwrap(),
+            None
+        );
+        assert_eq!(
+            parse_merge_optional_i32(Some(" 38 "), 1, 9999, "track number").unwrap(),
+            Some(38)
+        );
+        assert!(parse_merge_optional_i32(Some("0"), 1, 9999, "track number").is_err());
+        assert!(parse_merge_optional_i32(Some("nope"), 1, 9999, "track number").is_err());
+    }
+}

src/admin/views.rs

@@ -1262,9 +1262,11 @@ pub async fn releases_update(
 pub async fn releases_delete(
     _admin: AuthenticatedUser,
     db: &Database,
+    pool: &sqlx::PgPool,
     release_id: i64,
 ) -> cot::Result<cot::http::Response<Body>> {
-    Release::delete_by_id(db, release_id)
+    let (config, _) = AppConfig::load_with_db(db).await;
+    crate::library_cleanup::delete_releases(pool, &[release_id], &config.agent_storage_dir)
         .await
         .map_err(|e| cot::Error::internal(format!("failed to delete release: {e}")))?;
     Ok(auth::redirect("/admin/releases"))

src/config.rs

@@ -137,6 +137,17 @@ pub struct ConfigSources {
     pub lastfm_shared_secret: ConfigSource,
     pub federation_enabled: ConfigSource,
     pub federation_network_id: ConfigSource,
+    pub federation_save_on_listen: ConfigSource,
+    pub similarity_enabled: ConfigSource,
+    pub similarity_model: ConfigSource,
+    pub similarity_profile: ConfigSource,
+    pub similarity_workers: ConfigSource,
+    pub downloads_enabled: ConfigSource,
+    pub torrent_downloads_enabled: ConfigSource,
+    pub youtube_downloads_enabled: ConfigSource,
+    pub download_proxies: ConfigSource,
+    pub torrent_proxy_id: ConfigSource,
+    pub youtube_proxy_id: ConfigSource,
 }
 
 impl Default for ConfigSources {
@@ -166,6 +177,17 @@ impl Default for ConfigSources {
             lastfm_shared_secret: ConfigSource::Default,
             federation_enabled: ConfigSource::Default,
             federation_network_id: ConfigSource::Default,
+            federation_save_on_listen: ConfigSource::Default,
+            similarity_enabled: ConfigSource::Default,
+            similarity_model: ConfigSource::Default,
+            similarity_profile: ConfigSource::Default,
+            similarity_workers: ConfigSource::Default,
+            downloads_enabled: ConfigSource::Default,
+            torrent_downloads_enabled: ConfigSource::Default,
+            youtube_downloads_enabled: ConfigSource::Default,
+            download_proxies: ConfigSource::Default,
+            torrent_proxy_id: ConfigSource::Default,
+            youtube_proxy_id: ConfigSource::Default,
         }
     }
 }
@@ -228,6 +250,84 @@ macro_rules! impl_env_overrides {
 // AppConfig
 // ---------------------------------------------------------------------------
 
+/// Saved SOCKS5 proxy used by user-facing download methods.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct DownloadProxy {
+    pub id: String,
+    pub address: String,
+    #[serde(default)]
+    pub username: String,
+    #[serde(default)]
+    pub password: String,
+}
+
+impl DownloadProxy {
+    /// Validate and normalize a proxy without performing network or DNS I/O.
+    pub fn normalized(mut self) -> anyhow::Result<Self> {
+        self.id = self.id.trim().to_string();
+        self.address = self.address.trim().to_string();
+
+        if self.id.is_empty() || self.id.len() > 64 {
+            anyhow::bail!("proxy id must contain from 1 to 64 characters");
+        }
+        if !self
+            .id
+            .chars()
+            .all(|character| character.is_ascii_alphanumeric() || matches!(character, '-' | '_'))
+        {
+            anyhow::bail!("proxy id may contain only letters, digits, '-' and '_'");
+        }
+        if self.address.is_empty() || self.address.len() > 512 {
+            anyhow::bail!("proxy address must contain a host and port");
+        }
+        if self
+            .address
+            .chars()
+            .any(|character| matches!(character, '/' | '?' | '#' | '@'))
+        {
+            anyhow::bail!("proxy address must be in host:port format");
+        }
+        if self.username.len() > 256 || self.password.len() > 256 {
+            anyhow::bail!("proxy credentials are too long");
+        }
+
+        let parsed = reqwest::Url::parse(&format!("socks5://{}", self.address))
+            .map_err(|_| anyhow::anyhow!("proxy address must be in host:port format"))?;
+        let host = parsed
+            .host_str()
+            .filter(|host| !host.trim().is_empty())
+            .ok_or_else(|| anyhow::anyhow!("proxy address has no host"))?;
+        let port = parsed
+            .port()
+            .ok_or_else(|| anyhow::anyhow!("proxy address has no port"))?;
+        if port == 0 {
+            anyhow::bail!("proxy port must be between 1 and 65535");
+        }
+        self.address = if host.starts_with('[') && host.ends_with(']') {
+            format!("{host}:{port}")
+        } else if host.contains(':') {
+            format!("[{host}]:{port}")
+        } else {
+            format!("{host}:{port}")
+        };
+        Ok(self)
+    }
+
+    /// Build the URL accepted by librqbit and yt-dlp. Credentials are included
+    /// only when both fields are non-empty.
+    pub fn socks_url(&self) -> anyhow::Result<String> {
+        let proxy = self.clone().normalized()?;
+        let mut url = reqwest::Url::parse(&format!("socks5://{}", proxy.address))?;
+        if !proxy.username.is_empty() && !proxy.password.is_empty() {
+            url.set_username(&proxy.username)
+                .map_err(|_| anyhow::anyhow!("invalid proxy username"))?;
+            url.set_password(Some(&proxy.password))
+                .map_err(|_| anyhow::anyhow!("invalid proxy password"))?;
+        }
+        Ok(url.to_string())
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AppConfig {
     /// PostgreSQL connection URL.
@@ -280,6 +380,29 @@ pub struct AppConfig {
     /// Federation network id — the shared secret every peer of the network
     /// uses to find the others.
     pub federation_network_id: String,
+    /// Whether a federated track requested for playback is imported into the
+    /// shared local library. This is a server-wide administrator policy.
+    pub federation_save_on_listen: bool,
+    /// Whether local embedding calculation and similarity search are enabled.
+    pub similarity_enabled: bool,
+    /// Embedding model selected by the administrator.
+    pub similarity_model: String,
+    /// Audio preprocessing profile selected by the administrator.
+    pub similarity_profile: String,
+    /// Maximum number of concurrent CPU embedding workers.
+    pub similarity_workers: u64,
+    /// Whether the download manager and local-file uploads are available.
+    pub downloads_enabled: bool,
+    /// Whether torrent imports are available when the download manager is enabled.
+    pub torrent_downloads_enabled: bool,
+    /// Whether YouTube imports are available when the download manager is enabled.
+    pub youtube_downloads_enabled: bool,
+    /// JSON-encoded list of [`DownloadProxy`] entries.
+    pub download_proxies: String,
+    /// Saved proxy id used for torrent downloads; empty means a direct connection.
+    pub torrent_proxy_id: String,
+    /// Saved proxy id used for YouTube downloads; empty means a direct connection.
+    pub youtube_proxy_id: String,
 }
 
 impl Default for AppConfig {
@@ -309,6 +432,20 @@ impl Default for AppConfig {
             lastfm_shared_secret: String::new(),
             federation_enabled: false,
             federation_network_id: String::new(),
+            federation_save_on_listen: false,
+            similarity_enabled: false,
+            similarity_model: "discogs-effnet-bsdynamic-1".into(),
+            similarity_profile: "furumi-full-track-v1".into(),
+            similarity_workers: std::thread::available_parallelism()
+                .map(|count| (count.get() / 2).clamp(1, 4) as u64)
+                .unwrap_or(1),
+            // Preserve the behavior from before these controls were added.
+            downloads_enabled: true,
+            torrent_downloads_enabled: true,
+            youtube_downloads_enabled: true,
+            download_proxies: "[]".into(),
+            torrent_proxy_id: String::new(),
+            youtube_proxy_id: String::new(),
         }
     }
 }
@@ -339,6 +476,17 @@ impl_env_overrides!(
     lastfm_shared_secret,
     federation_enabled,
     federation_network_id,
+    federation_save_on_listen,
+    similarity_enabled,
+    similarity_model,
+    similarity_profile,
+    similarity_workers,
+    downloads_enabled,
+    torrent_downloads_enabled,
+    youtube_downloads_enabled,
+    download_proxies,
+    torrent_proxy_id,
+    youtube_proxy_id,
 );
 
 impl AppConfig {
@@ -468,6 +616,44 @@ impl AppConfig {
         apply_db_field!(lastfm_shared_secret);
         apply_db_field!(federation_enabled);
         apply_db_field!(federation_network_id);
+        apply_db_field!(federation_save_on_listen);
+        apply_db_field!(similarity_enabled);
+        apply_db_field!(similarity_model);
+        apply_db_field!(similarity_profile);
+        apply_db_field!(similarity_workers);
+        apply_db_field!(downloads_enabled);
+        apply_db_field!(torrent_downloads_enabled);
+        apply_db_field!(youtube_downloads_enabled);
+        apply_db_field!(download_proxies);
+        apply_db_field!(torrent_proxy_id);
+        apply_db_field!(youtube_proxy_id);
+    }
+
+    pub fn parsed_download_proxies(&self) -> anyhow::Result<Vec<DownloadProxy>> {
+        let proxies: Vec<DownloadProxy> = serde_json::from_str(&self.download_proxies)
+            .map_err(|_| anyhow::anyhow!("saved download proxy list is invalid"))?;
+        proxies.into_iter().map(DownloadProxy::normalized).collect()
+    }
+
+    pub fn selected_proxy_url(&self, proxy_id: &str) -> anyhow::Result<Option<String>> {
+        let proxy_id = proxy_id.trim();
+        if proxy_id.is_empty() {
+            return Ok(None);
+        }
+        let proxy = self
+            .parsed_download_proxies()?
+            .into_iter()
+            .find(|proxy| proxy.id == proxy_id)
+            .ok_or_else(|| anyhow::anyhow!("selected download proxy is not configured"))?;
+        proxy.socks_url().map(Some)
+    }
+
+    pub fn torrent_proxy_url(&self) -> anyhow::Result<Option<String>> {
+        self.selected_proxy_url(&self.torrent_proxy_id)
+    }
+
+    pub fn youtube_proxy_url(&self) -> anyhow::Result<Option<String>> {
+        self.selected_proxy_url(&self.youtube_proxy_id)
     }
 }
 
@@ -487,6 +673,60 @@ mod tests {
         let cfg = AppConfig::default();
         assert!(cfg.database_url.is_empty());
         assert_eq!(cfg.log_level, "info");
+        assert!(!cfg.similarity_enabled);
+        assert_eq!(cfg.similarity_model, crate::similarity::DEFAULT_MODEL_ID);
+        assert_eq!(
+            cfg.similarity_profile,
+            crate::similarity::DEFAULT_PROFILE_ID
+        );
+        assert!((1..=4).contains(&cfg.similarity_workers));
+        assert!(cfg.downloads_enabled);
+        assert!(cfg.torrent_downloads_enabled);
+        assert!(cfg.youtube_downloads_enabled);
+        assert!(cfg.parsed_download_proxies().unwrap().is_empty());
+    }
+
+    #[test]
+    fn download_proxy_url_encodes_complete_credentials() {
+        let proxy = DownloadProxy {
+            id: "proxy-1".into(),
+            address: "proxy.example:1080".into(),
+            username: "user name".into(),
+            password: "p@ss:word".into(),
+        };
+        assert_eq!(
+            proxy.socks_url().unwrap(),
+            "socks5://user%20name:p%40ss%3Aword@proxy.example:1080"
+        );
+    }
+
+    #[test]
+    fn download_proxy_url_omits_partial_credentials() {
+        let proxy = DownloadProxy {
+            id: "proxy-1".into(),
+            address: "127.0.0.1:1080".into(),
+            username: "user".into(),
+            password: String::new(),
+        };
+        assert_eq!(proxy.socks_url().unwrap(), "socks5://127.0.0.1:1080");
+    }
+
+    #[test]
+    fn selected_download_proxy_is_resolved_by_id() {
+        let mut cfg = AppConfig::default();
+        cfg.download_proxies = serde_json::to_string(&[DownloadProxy {
+            id: "youtube".into(),
+            address: "[::1]:9050".into(),
+            username: String::new(),
+            password: String::new(),
+        }])
+        .unwrap();
+        cfg.youtube_proxy_id = "youtube".into();
+        assert_eq!(
+            cfg.youtube_proxy_url().unwrap().as_deref(),
+            Some("socks5://[::1]:9050")
+        );
+        assert_eq!(cfg.torrent_proxy_url().unwrap(), None);
     }
 
     #[test]

src/federation/capabilities.rs

@@ -0,0 +1,80 @@
+//! Informational publication of the protocol versions exposed by this peer.
+
+use std::time::Duration;
+
+use anyhow::Result;
+use music_dht::StreamAcceptor;
+use music_dht::capabilities::{
+    CAPABILITIES_PROTOCOL_VERSION, CapabilityManifest, CapabilityMessage, JAM_ID, SIMILARITY_ID,
+    read_message, write_message,
+};
+
+use super::serve::AUDIO_PROTOCOL_VERSION;
+
+fn local_manifest() -> CapabilityManifest {
+    CapabilityManifest::frid("furumusic", env!("CARGO_PKG_VERSION"))
+        // The web server does not expose federation Jam yet.
+        .without_protocol(JAM_ID)
+        .with_protocol("audio", AUDIO_PROTOCOL_VERSION)
+        .with_protocol(
+            SIMILARITY_ID,
+            music_dht::similarity::SIMILARITY_PROTOCOL_VERSION,
+        )
+}
+
+pub async fn serve(mut acceptor: StreamAcceptor) {
+    while let Some(stream) = acceptor.accept().await {
+        tokio::spawn(async move {
+            if let Err(error) = serve_one(stream).await {
+                tracing::debug!("capability stream failed: {error:#}");
+            }
+        });
+    }
+}
+
+async fn serve_one(mut stream: music_dht::ByteStream) -> Result<()> {
+    let response = match read_message(&mut stream).await? {
+        CapabilityMessage::Get {
+            version: CAPABILITIES_PROTOCOL_VERSION,
+        } => CapabilityMessage::Manifest {
+            manifest: local_manifest(),
+        },
+        CapabilityMessage::Get { version } => CapabilityMessage::Error {
+            message: format!("unsupported capability protocol {version}"),
+        },
+        _ => CapabilityMessage::Error {
+            message: "expected capability request".to_string(),
+        },
+    };
+    write_message(&mut stream, &response).await?;
+    stream.send.finish()?;
+    let _ = tokio::time::timeout(Duration::from_secs(2), stream.send.stopped()).await;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn manifest_describes_only_supported_player_protocols() {
+        let manifest = local_manifest();
+        assert_eq!(manifest.application, "furumusic");
+        assert_eq!(
+            manifest.protocols.get("audio"),
+            Some(&AUDIO_PROTOCOL_VERSION)
+        );
+        assert!(!manifest.protocols.contains_key(JAM_ID));
+        assert_eq!(
+            manifest.protocols.get(SIMILARITY_ID),
+            Some(&music_dht::similarity::SIMILARITY_PROTOCOL_VERSION)
+        );
+        assert_eq!(
+            manifest
+                .protocols
+                .get(music_dht::capabilities::SIMILARITY_DHT_ID),
+            Some(&music_dht::similarity_lsh::SIMILARITY_DHT_PROTOCOL_VERSION)
+        );
+        manifest.validate().unwrap();
+    }
+}

src/federation/client.rs

@@ -0,0 +1,600 @@
+//! Receiving side of music federation.
+//!
+//! User-facing identity is content-addressed. An `(owner, item_id)` pair is
+//! only a source locator and several locators may resolve the same track.
+
+use std::collections::HashMap;
+
+use anyhow::{Context, Result};
+use music_dht::{ItemKind, LibraryItem, normalize_content_id};
+use serde::Serialize;
+use serde_json::{Value, json};
+use sqlx::Row as _;
+use tokio::io::AsyncReadExt;
+
+use super::{Federation, now_iso};
+
+const MAX_CATALOG_BYTES: u64 = 4 * 1024 * 1024;
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackKeyDto {
+    pub content_id: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ArtistKeyDto {
+    pub normalized_name: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ArtistRefDto {
+    pub key: ArtistKeyDto,
+    pub name: String,
+    pub local_id: Option<i64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ReleaseKeyDto {
+    pub normalized_title: String,
+    pub primary_artists: Vec<String>,
+    pub release_type: Option<String>,
+    pub year: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ReleaseRefDto {
+    pub key: ReleaseKeyDto,
+    pub local_id: Option<i64>,
+    pub title: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct FederationSourceDto {
+    pub owner: String,
+    pub item_id: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct LocalAvailabilityDto {
+    pub track_id: i64,
+    pub stream_url: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackMetadataDto {
+    pub title: String,
+    pub artists: Vec<ArtistRefDto>,
+    pub featured_artists: Vec<ArtistRefDto>,
+    pub release: Option<ReleaseRefDto>,
+    pub year: Option<i32>,
+    pub duration_seconds: Option<f64>,
+    pub track_number: Option<i32>,
+    pub disc_number: Option<i32>,
+    pub cover_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackAvailabilityDto {
+    pub state: &'static str,
+    pub local: Option<LocalAvailabilityDto>,
+    pub federation: Vec<FederationSourceDto>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TrackDto {
+    pub key: TrackKeyDto,
+    pub metadata: TrackMetadataDto,
+    pub availability: TrackAvailabilityDto,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub similarity_score: Option<f32>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct SearchEvent {
+    pub search_id: String,
+    pub sequence: u64,
+    pub kind: &'static str,
+    pub peer: Option<String>,
+    pub entity_key: Value,
+    pub entity: Value,
+}
+
+impl Federation {
+    pub async fn prepare_similarity_tracks(
+        &self,
+        tracks: Vec<super::similarity::RemoteSimilarityTrack>,
+    ) -> Result<Vec<TrackDto>> {
+        let pool = self.pool().await?;
+        let mut prepared = Vec::new();
+        for track in tracks {
+            let Some(content_id) = track.content_id.as_deref().and_then(normalize_content_id)
+            else {
+                continue;
+            };
+            let local = local_availability(&pool, &content_id).await?;
+            // A local result is already present in the first result section.
+            if local.is_some() {
+                continue;
+            }
+            let owner = track.owner;
+            let item_id = track.item_id;
+            let dto = TrackDto {
+                key: TrackKeyDto {
+                    content_id: content_id.clone(),
+                },
+                metadata: TrackMetadataDto {
+                    title: track.title,
+                    artists: artist_refs(&track.artist_names),
+                    featured_artists: artist_refs(&track.featured_artist_names),
+                    release: track.release_title.map(|title| ReleaseRefDto {
+                        key: ReleaseKeyDto {
+                            normalized_title: music_dht::normalize_name(&title),
+                            primary_artists: track
+                                .artist_names
+                                .iter()
+                                .map(|artist| music_dht::normalize_name(artist))
+                                .collect(),
+                            release_type: None,
+                            year: track.year,
+                        },
+                        local_id: None,
+                        title,
+                    }),
+                    year: track.year,
+                    duration_seconds: track.duration_seconds.map(|value| value as f64),
+                    track_number: track.track_number,
+                    disc_number: track.disc_number,
+                    cover_url: Some(format!(
+                        "/api/player/federation/tracks/artwork?owner={owner}&item_id={item_id}"
+                    )),
+                },
+                availability: TrackAvailabilityDto {
+                    state: "federated",
+                    local: None,
+                    federation: vec![FederationSourceDto { owner, item_id }],
+                },
+                similarity_score: Some(track.similarity_score),
+            };
+            persist_track_ref(&pool, &dto).await?;
+            prepared.push(dto);
+        }
+        Ok(prepared)
+    }
+
+    pub fn stream_artist_catalogs(
+        self: &std::sync::Arc<Self>,
+        name: String,
+    ) -> tokio::sync::mpsc::UnboundedReceiver<Result<(String, music_dht::catalog::CatalogArtist)>>
+    {
+        let (sender, receiver) = tokio::sync::mpsc::unbounded_channel();
+        let federation = std::sync::Arc::clone(self);
+        tokio::spawn(async move {
+            let result = async {
+                let service = federation.service().await?;
+                let normalized = music_dht::normalize_name(&name);
+                let outcome = service
+                    .search_network(&name)
+                    .await
+                    .map_err(|err| anyhow::anyhow!("federated artist search failed: {err}"))?;
+                let owners: std::collections::HashSet<_> = outcome
+                    .network_results
+                    .iter()
+                    .filter(|item| {
+                        (item.kind == ItemKind::Artist && item.normalized_name == normalized)
+                            || item
+                                .artist_names
+                                .iter()
+                                .chain(&item.featured_artist_names)
+                                .any(|artist| music_dht::normalize_name(artist) == normalized)
+                    })
+                    .map(|item| item.owner)
+                    .collect();
+                for owner in owners {
+                    let service = std::sync::Arc::clone(&service);
+                    let sender = sender.clone();
+                    let name = name.clone();
+                    tokio::spawn(async move {
+                        let result = tokio::time::timeout(
+                            std::time::Duration::from_secs(8),
+                            fetch_artist_catalog(&service, owner, &name),
+                        )
+                        .await
+                        .map_err(|_| anyhow::anyhow!("catalog request timed out"))
+                        .and_then(|result| result)
+                        .map(|artist| (owner.to_string(), artist));
+                        let _ = sender.send(result);
+                    });
+                }
+                Ok::<(), anyhow::Error>(())
+            }
+            .await;
+            if let Err(err) = result {
+                let _ = sender.send(Err(err));
+            }
+        });
+        receiver
+    }
+
+    /// Performs one bounded DHT search and returns entity upserts. The HTTP
+    /// layer streams each upsert independently; catalog fan-out can append
+    /// events to the same contract without changing the browser model.
+    pub async fn search_events(&self, search_id: &str, query: &str) -> Result<Vec<SearchEvent>> {
+        let query = query.trim();
+        anyhow::ensure!(!query.is_empty(), "search query is empty");
+        anyhow::ensure!(query.chars().count() <= 200, "search query is too long");
+
+        let started = std::time::Instant::now();
+        let service = self.service().await?;
+        tracing::info!(
+            search_id,
+            query,
+            connected_peers = service.connected_peers().len(),
+            known_contacts = service.known_peers().len(),
+            "federated search started"
+        );
+        let own = service.endpoint_id();
+        let result = tokio::time::timeout(
+            std::time::Duration::from_secs(20),
+            service.search_network(query),
+        )
+        .await
+        .map_err(|_| anyhow::anyhow!("federated search timed out after 20 seconds"))?
+        .map_err(|err| anyhow::anyhow!("federated search failed: {err}"))?;
+        tracing::info!(
+            search_id,
+            query,
+            local_results = result.local_results.len(),
+            network_results = result.network_results.len(),
+            queried_nodes = result.queried_nodes,
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "federated DHT search finished"
+        );
+        let all_items: Vec<LibraryItem> = result
+            .local_results
+            .into_iter()
+            .chain(result.network_results)
+            .collect();
+
+        let pool = self.pool().await?;
+        let mut by_content: HashMap<String, TrackDto> = HashMap::new();
+        for item in all_items.iter().filter(|item| item.kind == ItemKind::Track) {
+            let Some(content_id) = item.content_id.as_deref().and_then(normalize_content_id) else {
+                // A globally usable track reference must be verifiable.
+                continue;
+            };
+            let local = local_availability(&pool, &content_id).await?;
+            let source = FederationSourceDto {
+                owner: item.owner.to_string(),
+                item_id: hex(item.id.as_bytes()),
+            };
+            let entry = by_content.entry(content_id.clone()).or_insert_with(|| {
+                track_from_item(content_id.clone(), item, local, item.owner == own)
+            });
+            if !entry.availability.federation.iter().any(|candidate| {
+                candidate.owner == source.owner && candidate.item_id == source.item_id
+            }) {
+                entry.availability.federation.push(source);
+            }
+            if entry.availability.local.is_some() {
+                entry.availability.state = "local";
+            }
+        }
+
+        let mut tracks: Vec<_> = by_content.into_values().collect();
+        tracks.sort_by(|left, right| {
+            left.metadata
+                .title
+                .to_lowercase()
+                .cmp(&right.metadata.title.to_lowercase())
+        });
+
+        let mut events = Vec::with_capacity(all_items.len());
+        for (index, track) in tracks.into_iter().enumerate() {
+            persist_track_ref(&pool, &track).await?;
+            let peer = track
+                .availability
+                .federation
+                .first()
+                .map(|source| source.owner.clone());
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence: index as u64 + 1,
+                kind: "federation.track",
+                peer,
+                entity_key: serde_json::to_value(&track.key)?,
+                entity: serde_json::to_value(track)?,
+            });
+        }
+        let mut artist_peers: HashMap<String, (String, Vec<String>)> = HashMap::new();
+        let mut releases: HashMap<String, Value> = HashMap::new();
+        for item in &all_items {
+            match item.kind {
+                ItemKind::Artist => {
+                    let key = music_dht::normalize_name(&item.name);
+                    let entry = artist_peers
+                        .entry(key)
+                        .or_insert_with(|| (item.name.clone(), Vec::new()));
+                    let owner = item.owner.to_string();
+                    if !entry.1.contains(&owner) {
+                        entry.1.push(owner);
+                    }
+                }
+                ItemKind::Release => {
+                    let artist_keys: Vec<String> = item
+                        .artist_names
+                        .iter()
+                        .map(|name| music_dht::normalize_name(name))
+                        .collect();
+                    let normalized_title = music_dht::normalize_name(&item.name);
+                    let cover_url = all_items
+                        .iter()
+                        .find(|track| {
+                            track.kind == ItemKind::Track
+                                && track.release_title.as_deref().is_some_and(|title| {
+                                    music_dht::normalize_name(title) == normalized_title
+                                })
+                                && track.year == item.year
+                        })
+                        .map(|track| {
+                            format!(
+                                "/api/player/federation/tracks/artwork?owner={}&item_id={}",
+                                track.owner,
+                                hex(track.id.as_bytes())
+                            )
+                        });
+                    let key = format!(
+                        "{}|{}|{}",
+                        normalized_title,
+                        artist_keys.join(","),
+                        item.year.map_or_else(String::new, |year| year.to_string())
+                    );
+                    releases.entry(key.clone()).or_insert_with(|| {
+                        json!({
+                            "key": {
+                                "normalized_title": music_dht::normalize_name(&item.name),
+                                "primary_artists": artist_keys,
+                                "release_type": null,
+                                "year": item.year,
+                            },
+                            "title": item.name,
+                            "artists": item.artist_names,
+                            "year": item.year,
+                            "cover_url": cover_url,
+                            "sources": [{
+                                "owner": item.owner.to_string(),
+                                "item_id": hex(item.id.as_bytes()),
+                            }],
+                        })
+                    });
+                }
+                ItemKind::Track => {}
+            }
+        }
+        for (key, (name, peers)) in artist_peers {
+            let sequence = events.len() as u64 + 1;
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence,
+                kind: "federation.artist",
+                peer: peers.first().cloned(),
+                entity_key: json!({ "normalized_name": key }),
+                entity: json!({
+                    "key": { "normalized_name": key },
+                    "name": name,
+                    "image_url": null,
+                    "peers": peers,
+                }),
+            });
+        }
+        for (key, release) in releases {
+            let sequence = events.len() as u64 + 1;
+            events.push(SearchEvent {
+                search_id: search_id.to_owned(),
+                sequence,
+                kind: "federation.release",
+                peer: None,
+                entity_key: json!({ "composite": key }),
+                entity: release,
+            });
+        }
+        tracing::info!(
+            search_id,
+            query,
+            events = events.len(),
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "federated search response ready"
+        );
+        Ok(events)
+    }
+}
+
+async fn fetch_artist_catalog(
+    service: &music_dht::MusicDhtService,
+    owner: music_dht::EndpointId,
+    artist: &str,
+) -> Result<music_dht::catalog::CatalogArtist> {
+    let mut stream = service
+        .open_stream(owner, super::CATALOG_ALPN)
+        .await
+        .map_err(|err| anyhow::anyhow!("cannot reach catalog peer: {err}"))?;
+    let mut request = serde_json::to_vec(&music_dht::catalog::CatalogRequest {
+        artist: artist.to_owned(),
+        want: Some("catalog".to_owned()),
+        ..Default::default()
+    })?;
+    request.push(b'\n');
+    stream.send.write_all(&request).await?;
+    stream.send.finish()?;
+    let mut payload = Vec::new();
+    stream
+        .recv
+        .take(MAX_CATALOG_BYTES + 1)
+        .read_to_end(&mut payload)
+        .await?;
+    anyhow::ensure!(
+        payload.len() as u64 <= MAX_CATALOG_BYTES,
+        "catalog response is too large"
+    );
+    let response: music_dht::catalog::CatalogResponse =
+        serde_json::from_slice(&payload).context("invalid catalog response")?;
+    anyhow::ensure!(
+        response.ok,
+        "peer refused catalog: {}",
+        response.error.unwrap_or_else(|| "unknown error".to_owned())
+    );
+    response.artist.context("peer returned no artist catalog")
+}
+
+fn track_from_item(
+    content_id: String,
+    item: &LibraryItem,
+    local: Option<LocalAvailabilityDto>,
+    own: bool,
+) -> TrackDto {
+    let owner = item.owner.to_string();
+    let item_id = hex(item.id.as_bytes());
+    let artists = artist_refs(&item.artist_names);
+    let featured_artists = artist_refs(&item.featured_artist_names);
+    let release = item.release_title.as_ref().map(|title| ReleaseRefDto {
+        key: ReleaseKeyDto {
+            normalized_title: music_dht::normalize_name(title),
+            primary_artists: item
+                .artist_names
+                .iter()
+                .map(|artist| music_dht::normalize_name(artist))
+                .collect(),
+            release_type: None,
+            year: item.year,
+        },
+        local_id: None,
+        title: title.clone(),
+    });
+    let state = if local.is_some() || own {
+        "local"
+    } else {
+        "federated"
+    };
+    TrackDto {
+        key: TrackKeyDto { content_id },
+        metadata: TrackMetadataDto {
+            title: item.name.clone(),
+            artists,
+            featured_artists,
+            release,
+            year: item.year,
+            duration_seconds: item.duration_seconds,
+            track_number: item.track_number,
+            disc_number: item.disc_number,
+            cover_url: Some(format!(
+                "/api/player/federation/tracks/artwork?owner={owner}&item_id={item_id}"
+            )),
+        },
+        availability: TrackAvailabilityDto {
+            state,
+            local,
+            federation: vec![FederationSourceDto { owner, item_id }],
+        },
+        similarity_score: None,
+    }
+}
+
+fn artist_refs(names: &[String]) -> Vec<ArtistRefDto> {
+    names
+        .iter()
+        .map(|name| ArtistRefDto {
+            key: ArtistKeyDto {
+                normalized_name: music_dht::normalize_name(name),
+            },
+            name: name.clone(),
+            local_id: None,
+        })
+        .collect()
+}
+
+async fn local_availability(
+    pool: &sqlx::PgPool,
+    content_id: &str,
+) -> Result<Option<LocalAvailabilityDto>> {
+    let row = sqlx::query(
+        "SELECT t.id
+           FROM furumusic__federation_content_id_cache c
+           JOIN furumusic__track t ON t.audio_file_id = c.media_file_id
+          WHERE c.content_id = $1 AND t.is_hidden = false
+          LIMIT 1",
+    )
+    .bind(content_id)
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.map(|row| {
+        let track_id: i64 = row.get(0);
+        LocalAvailabilityDto {
+            track_id,
+            stream_url: format!("/api/player/stream/{track_id}"),
+        }
+    }))
+}
+
+async fn persist_track_ref(pool: &sqlx::PgPool, track: &TrackDto) -> Result<()> {
+    let metadata = serde_json::to_value(&track.metadata)?;
+    let local_id = track
+        .availability
+        .local
+        .as_ref()
+        .map(|local| local.track_id);
+    let row = sqlx::query(
+        "INSERT INTO furumusic__track_ref
+            (content_id, local_track_id, title, release_title, year,
+             duration_seconds, metadata_json, metadata_authority, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, 'federation', $8, $8)
+         ON CONFLICT (content_id) DO UPDATE SET
+            local_track_id = COALESCE(furumusic__track_ref.local_track_id, EXCLUDED.local_track_id),
+            title = EXCLUDED.title,
+            release_title = EXCLUDED.release_title,
+            year = EXCLUDED.year,
+            duration_seconds = EXCLUDED.duration_seconds,
+            metadata_json = EXCLUDED.metadata_json,
+            updated_at = EXCLUDED.updated_at
+         RETURNING id",
+    )
+    .bind(&track.key.content_id)
+    .bind(local_id)
+    .bind(&track.metadata.title)
+    .bind(
+        track
+            .metadata
+            .release
+            .as_ref()
+            .map(|release| &release.title),
+    )
+    .bind(track.metadata.year)
+    .bind(track.metadata.duration_seconds)
+    .bind(metadata)
+    .bind(now_iso())
+    .fetch_one(pool)
+    .await
+    .context("persisting content-addressed track reference failed")?;
+    let track_ref_id: i64 = row.get(0);
+    for source in &track.availability.federation {
+        sqlx::query(
+            "INSERT INTO furumusic__federation_track_source
+                (track_ref_id, owner_peer_id, item_id, last_seen_ms, metadata_json)
+             VALUES ($1, $2, $3, $4, $5)
+             ON CONFLICT (owner_peer_id, item_id) DO UPDATE SET
+                track_ref_id = EXCLUDED.track_ref_id,
+                last_seen_ms = EXCLUDED.last_seen_ms,
+                metadata_json = EXCLUDED.metadata_json",
+        )
+        .bind(track_ref_id)
+        .bind(&source.owner)
+        .bind(&source.item_id)
+        .bind(chrono::Utc::now().timestamp_millis())
+        .bind(json!({ "track": track.metadata }))
+        .execute(pool)
+        .await?;
+    }
+    Ok(())
+}
+
+fn hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}

src/federation/mod.rs

@@ -5,24 +5,35 @@
 //! releases, tracks — names and small metadata, never files) into the
 //! shared DHT and serves audio, track metadata, cover art and per-artist
 //! catalogs to other peers (TUI clients) over the same wire protocols the
-//! clients speak among themselves. Serve-only: the server does not search
-//! or download from other peers.
+//! clients speak among themselves. The web player also searches known peers
+//! for catalog metadata and, when enabled, compatible similarity embeddings;
+//! local playback and the local library remain independent of the network.
 //!
 //! Settings are the regular admin config entries (`federation_enabled`,
-//! `federation_network_id`) and apply on the fly — saving the settings
-//! starts, stops or re-joins the node without a server restart.
+//! `federation_network_id`, `federation_save_on_listen`) and apply on the fly —
+//! saving the settings starts, stops or re-joins the node without a server
+//! restart.
 
+mod capabilities;
+pub mod client;
+pub mod devices;
+mod receive;
 mod serve;
+mod similarity;
 mod storage;
 
+use std::collections::{HashMap, HashSet, VecDeque};
 use std::path::PathBuf;
 use std::sync::{Arc, OnceLock};
 use std::time::Duration;
 
 use anyhow::{Context, Result};
+use music_dht::capabilities::CAPABILITIES_ALPN;
+use music_dht::similarity_dht::SimilarityDht;
+use music_dht::similarity_lsh::SIMILARITY_DHT_ALPN;
 use music_dht::{
-    ItemKind, ItemSpec, MusicDhtConfig, MusicDhtService, NetworkId, PeerTicket, PublishStats,
-    RendezvousConfig, SyncStats,
+    ByteStream, ByteStreamConnectionStats, ItemKind, ItemSpec, MusicDhtConfig, MusicDhtService,
+    NetworkId, PeerTicket, PublishStats, RendezvousConfig, SyncStats,
 };
 use serde_json::{Value, json};
 use sqlx::PgPool;
@@ -32,26 +43,247 @@ use crate::config::AppConfig;
 use storage::PostgresFederationStorage;
 
 pub use serve::{AUDIO_ALPN, CATALOG_ALPN};
+pub use similarity::SIMILARITY_ALPN;
 
 /// How often the published library is re-synchronized with the database.
 const SYNC_INTERVAL: Duration = Duration::from_secs(60);
+const TRANSPORT_SAMPLE_LIMIT: usize = 16;
 
 struct Running {
     service: Arc<MusicDhtService>,
+    similarity_dht: Arc<SimilarityDht>,
     network_name: String,
     tasks: Vec<tokio::task::JoinHandle<()>>,
 }
 
+struct ContentHashJob {
+    media_file_id: i64,
+    sha256_hash: String,
+    file_path: String,
+}
+
+#[derive(Clone)]
+struct CachedArtwork {
+    bytes: Vec<u8>,
+    mime: String,
+    fetched_at: std::time::Instant,
+}
+
+#[derive(Debug, Clone)]
+struct TransportSample {
+    at: String,
+    protocol: &'static str,
+    direction: &'static str,
+    phase: &'static str,
+    peer_id: String,
+    selected_path: String,
+    open_paths: usize,
+    direct_paths: usize,
+    relay_paths: usize,
+    custom_paths: usize,
+    selected_rtt_ms: Option<u64>,
+    selected_tx_bytes: u64,
+    selected_rx_bytes: u64,
+    total_tx_bytes: u64,
+    total_rx_bytes: u64,
+    lost_packets: u64,
+    lost_bytes: u64,
+}
+
+impl TransportSample {
+    fn from_stats(
+        protocol: &'static str,
+        direction: &'static str,
+        phase: &'static str,
+        stats: ByteStreamConnectionStats,
+    ) -> Self {
+        Self {
+            at: now_iso(),
+            protocol,
+            direction,
+            phase,
+            peer_id: stats.peer_id.to_string(),
+            selected_path: stats.selected_path.as_str().to_string(),
+            open_paths: stats.open_paths,
+            direct_paths: stats.direct_paths,
+            relay_paths: stats.relay_paths,
+            custom_paths: stats.custom_paths,
+            selected_rtt_ms: stats
+                .selected_rtt
+                .map(|duration| duration.as_millis() as u64),
+            selected_tx_bytes: stats.selected_tx_bytes,
+            selected_rx_bytes: stats.selected_rx_bytes,
+            total_tx_bytes: stats.total_tx_bytes,
+            total_rx_bytes: stats.total_rx_bytes,
+            lost_packets: stats.lost_packets,
+            lost_bytes: stats.lost_bytes,
+        }
+    }
+}
+
+#[derive(Debug, Default)]
+struct TransportStatsState {
+    total_samples: u64,
+    direct_samples: u64,
+    relay_samples: u64,
+    custom_samples: u64,
+    unknown_samples: u64,
+    audio_samples: u64,
+    catalog_samples: u64,
+    sync_samples: u64,
+    similarity_samples: u64,
+    last: VecDeque<TransportSample>,
+}
+
+#[derive(Debug, Default)]
+pub struct TransportStats {
+    inner: std::sync::Mutex<TransportStatsState>,
+}
+
+impl TransportStats {
+    fn reset(&self) {
+        *lock(&self.inner) = TransportStatsState::default();
+    }
+
+    fn record(
+        &self,
+        protocol: &'static str,
+        direction: &'static str,
+        phase: &'static str,
+        stats: ByteStreamConnectionStats,
+    ) {
+        let sample = TransportSample::from_stats(protocol, direction, phase, stats);
+        let mut state = lock(&self.inner);
+        state.total_samples += 1;
+        match sample.selected_path.as_str() {
+            "direct" => state.direct_samples += 1,
+            "relay" => state.relay_samples += 1,
+            "custom" => state.custom_samples += 1,
+            _ => state.unknown_samples += 1,
+        }
+        match protocol {
+            "audio" => state.audio_samples += 1,
+            "catalog" => state.catalog_samples += 1,
+            "device-sync" => state.sync_samples += 1,
+            "similarity" => state.similarity_samples += 1,
+            _ => {}
+        }
+        state.last.push_front(sample);
+        while state.last.len() > TRANSPORT_SAMPLE_LIMIT {
+            state.last.pop_back();
+        }
+    }
+
+    fn snapshot(&self) -> Value {
+        let state = lock(&self.inner);
+        let latest = state.last.front();
+        json!({
+            "total_samples": state.total_samples,
+            "direct_samples": state.direct_samples,
+            "relay_samples": state.relay_samples,
+            "custom_samples": state.custom_samples,
+            "unknown_samples": state.unknown_samples,
+            "audio_samples": state.audio_samples,
+            "catalog_samples": state.catalog_samples,
+            "sync_samples": state.sync_samples,
+            "similarity_samples": state.similarity_samples,
+            "last_path": latest.map(|sample| sample.selected_path.clone()),
+            "last_rtt_ms": latest.and_then(|sample| sample.selected_rtt_ms),
+            "last_peer": latest.map(|sample| sample.peer_id.clone()),
+            "last": state.last.iter().map(|sample| json!({
+                "at": sample.at,
+                "protocol": sample.protocol,
+                "direction": sample.direction,
+                "phase": sample.phase,
+                "peer_id": sample.peer_id,
+                "selected_path": sample.selected_path,
+                "open_paths": sample.open_paths,
+                "direct_paths": sample.direct_paths,
+                "relay_paths": sample.relay_paths,
+                "custom_paths": sample.custom_paths,
+                "selected_rtt_ms": sample.selected_rtt_ms,
+                "selected_tx_bytes": sample.selected_tx_bytes,
+                "selected_rx_bytes": sample.selected_rx_bytes,
+                "total_tx_bytes": sample.total_tx_bytes,
+                "total_rx_bytes": sample.total_rx_bytes,
+                "lost_packets": sample.lost_packets,
+                "lost_bytes": sample.lost_bytes,
+            })).collect::<Vec<_>>(),
+        })
+    }
+}
+
+async fn enrich_transport_users(pool: &PgPool, transport: &mut Value) {
+    let Some(samples) = transport.get_mut("last").and_then(Value::as_array_mut) else {
+        return;
+    };
+    let peer_ids: Vec<String> = samples
+        .iter()
+        .filter_map(|sample| sample.get("peer_id").and_then(Value::as_str))
+        .map(str::to_owned)
+        .collect();
+    if peer_ids.is_empty() {
+        return;
+    }
+    let Ok(rows) = sqlx::query(
+        "SELECT DISTINCT ON (d.endpoint_id)
+                d.endpoint_id,
+                COALESCE(NULLIF(u.display_name, ''), u.username::text) AS user_name
+         FROM furumusic__fed_device d
+         JOIN furumusic__user u ON u.id = d.user_id
+         WHERE d.endpoint_id = ANY($1) AND d.revoked_at_ms IS NULL
+         ORDER BY d.endpoint_id, d.last_seen_ms DESC NULLS LAST",
+    )
+    .bind(&peer_ids)
+    .fetch_all(pool)
+    .await
+    else {
+        return;
+    };
+    let users: HashMap<String, String> = rows
+        .into_iter()
+        .map(|row| (row.get("endpoint_id"), row.get("user_name")))
+        .collect();
+    for sample in samples {
+        let Some(peer_id) = sample.get("peer_id").and_then(Value::as_str) else {
+            continue;
+        };
+        let Some(user_name) = users.get(peer_id) else {
+            continue;
+        };
+        if let Some(object) = sample.as_object_mut() {
+            object.insert("user_name".to_owned(), Value::String(user_name.clone()));
+        }
+    }
+}
+
+pub fn record_stream_transport(
+    stats: &Arc<TransportStats>,
+    protocol: &'static str,
+    direction: &'static str,
+    phase: &'static str,
+    stream: &ByteStream,
+) {
+    stats.record(protocol, direction, phase, stream.connection_stats());
+}
+
 pub struct Federation {
-    /// Transport data directory; server-side DHT state and identity live in PostgreSQL.
+    /// Transport files and replaceable similarity-routing cache. Durable
+    /// catalog DHT state and identity live in PostgreSQL.
     data_dir: PathBuf,
     database_url: std::sync::Mutex<String>,
     storage_dir: std::sync::Mutex<String>,
-    content_cache: std::sync::Mutex<std::collections::HashMap<i64, (String, String)>>,
+    save_on_listen: std::sync::atomic::AtomicBool,
+    content_cache: std::sync::Mutex<HashMap<i64, (String, String)>>,
+    content_pending: std::sync::Mutex<HashSet<i64>>,
+    prepared_cache: std::sync::Mutex<HashMap<String, (PathBuf, String)>>,
+    artwork_cache: std::sync::Mutex<HashMap<String, CachedArtwork>>,
+    download_locks: std::sync::Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>,
     pool: tokio::sync::OnceCell<PgPool>,
     running: tokio::sync::Mutex<Option<Running>>,
     last_sync: std::sync::Mutex<Option<String>>,
     last_error: std::sync::Mutex<Option<String>>,
+    transport_stats: Arc<TransportStats>,
 }
 
 fn now_iso() -> String {
@@ -72,11 +304,17 @@ pub fn handle() -> Arc<Federation> {
             data_dir: PathBuf::from(crate::media_paths::resolve_config_path("federation")),
             database_url: std::sync::Mutex::new(String::new()),
             storage_dir: std::sync::Mutex::new(String::new()),
+            save_on_listen: std::sync::atomic::AtomicBool::new(false),
             content_cache: std::sync::Mutex::new(Default::default()),
+            content_pending: std::sync::Mutex::new(Default::default()),
+            prepared_cache: std::sync::Mutex::new(Default::default()),
+            artwork_cache: std::sync::Mutex::new(Default::default()),
+            download_locks: std::sync::Mutex::new(Default::default()),
             pool: tokio::sync::OnceCell::new(),
             running: tokio::sync::Mutex::new(None),
             last_sync: std::sync::Mutex::new(None),
             last_error: std::sync::Mutex::new(None),
+            transport_stats: Arc::new(TransportStats::default()),
         })
     }))
 }
@@ -121,7 +359,8 @@ impl Federation {
         let mut effective = config.clone();
         let rows = sqlx::query(
             "SELECT key, value FROM furumusic__config_entry
-             WHERE key IN ('federation_enabled', 'federation_network_id', 'agent_storage_dir')",
+             WHERE key IN ('federation_enabled', 'federation_network_id',
+                           'federation_save_on_listen', 'agent_storage_dir')",
         )
         .fetch_all(&pool)
         .await
@@ -140,6 +379,11 @@ impl Federation {
                     }
                 }
                 "federation_network_id" => effective.federation_network_id = value,
+                "federation_save_on_listen" => {
+                    if let Ok(parsed) = value.parse() {
+                        effective.federation_save_on_listen = parsed;
+                    }
+                }
                 "agent_storage_dir" => {
                     effective.agent_storage_dir = crate::media_paths::resolve_config_path(&value);
                 }
@@ -154,6 +398,10 @@ impl Federation {
     pub async fn apply(self: &Arc<Self>, config: &AppConfig) {
         *lock(&self.database_url) = config.database_url.clone();
         *lock(&self.storage_dir) = config.agent_storage_dir.clone();
+        self.save_on_listen.store(
+            config.federation_save_on_listen,
+            std::sync::atomic::Ordering::Relaxed,
+        );
         let network = config.federation_network_id.trim().to_string();
         if config.federation_enabled && !network.is_empty() {
             if let Err(err) = self.start(network, config.agent_storage_dir.clone()).await {
@@ -179,6 +427,10 @@ impl Federation {
 
         let dht_storage = Arc::new(PostgresFederationStorage::new(pool.clone()).await?);
         let secret_key = dht_storage.load_or_create_secret_key().await?;
+        self.transport_stats.reset();
+        tokio::fs::create_dir_all(&self.data_dir)
+            .await
+            .with_context(|| format!("creating {}", self.data_dir.display()))?;
 
         let config = MusicDhtConfig::builder()
             .data_dir(&self.data_dir)
@@ -187,6 +439,10 @@ impl Federation {
             .rendezvous(RendezvousConfig::default())
             .stream_protocol(AUDIO_ALPN)
             .stream_protocol(CATALOG_ALPN)
+            .stream_protocol(devices::SYNC_ALPN)
+            .schema_independent_stream_protocol(SIMILARITY_ALPN)
+            .schema_independent_stream_protocol(SIMILARITY_DHT_ALPN)
+            .schema_independent_stream_protocol(CAPABILITIES_ALPN)
             .build()
             .map_err(|err| anyhow::anyhow!("invalid federation config: {err}"))?;
         let (service, mut events) =
@@ -200,6 +456,25 @@ impl Federation {
             "federation started"
         );
 
+        let similarity_dht = SimilarityDht::open(
+            Arc::clone(&service),
+            self.data_dir.join("similarity-routing.sqlite3"),
+        )
+        .await
+        .map_err(|error| anyhow::anyhow!("failed to start the similarity DHT: {error}"))?;
+        let similarity_dht_acceptor = service
+            .stream_acceptor(SIMILARITY_DHT_ALPN)
+            .map_err(|error| anyhow::anyhow!("failed to take similarity DHT acceptor: {error}"))?;
+        let similarity_dht_serve_task =
+            tokio::spawn(Arc::clone(&similarity_dht).serve(similarity_dht_acceptor));
+        let similarity_dht_maintenance_task =
+            tokio::spawn(Arc::clone(&similarity_dht).maintenance());
+        let similarity_manager = crate::similarity::handle();
+        let similarity_dht_sync_task = tokio::spawn(similarity_route_sync_loop(
+            Arc::clone(&similarity_dht),
+            Arc::clone(&similarity_manager),
+        ));
+
         // Drain DHT events into the log; the channel is bounded.
         let event_task = tokio::spawn(async move {
             while let Some(event) = events.recv().await {
@@ -225,21 +500,66 @@ impl Federation {
             pool.clone(),
             storage_dir.clone(),
             service.endpoint_id(),
+            Arc::clone(&self.transport_stats),
         ));
         let catalog_acceptor = service
             .stream_acceptor(CATALOG_ALPN)
             .map_err(|err| anyhow::anyhow!("failed to take the catalog acceptor: {err}"))?;
         let catalog_task = tokio::spawn(serve::serve_catalog(
             catalog_acceptor,
-            pool,
+            pool.clone(),
             storage_dir,
             service.endpoint_id(),
+            Arc::clone(&self.transport_stats),
+        ));
+        let device_acceptor = service
+            .stream_acceptor(devices::SYNC_ALPN)
+            .map_err(|err| anyhow::anyhow!("failed to take the device-sync acceptor: {err}"))?;
+        let device_hub = crate::player::PlayerDeviceHub::shared();
+        let device_task = tokio::spawn(devices::serve_peers(
+            device_acceptor,
+            pool.clone(),
+            Arc::clone(&service),
+            Arc::clone(&device_hub),
+            Arc::clone(&self.transport_stats),
+        ));
+        let device_sync_task = tokio::spawn(devices::sync_loop(
+            pool,
+            Arc::clone(&service),
+            device_hub,
+            Arc::clone(&self.transport_stats),
+        ));
+        let capabilities_acceptor = service
+            .stream_acceptor(CAPABILITIES_ALPN)
+            .map_err(|err| anyhow::anyhow!("failed to take the capabilities acceptor: {err}"))?;
+        let capabilities_task = tokio::spawn(capabilities::serve(capabilities_acceptor));
+        let similarity_acceptor = service
+            .stream_acceptor(SIMILARITY_ALPN)
+            .map_err(|err| anyhow::anyhow!("failed to take the similarity acceptor: {err}"))?;
+        let similarity_task = tokio::spawn(similarity::serve_peers(
+            similarity_acceptor,
+            similarity_manager,
+            service.endpoint_id(),
+            Arc::clone(&self.transport_stats),
         ));
 
         *guard = Some(Running {
             service,
+            similarity_dht,
             network_name,
-            tasks: vec![event_task, sync_task, audio_task, catalog_task],
+            tasks: vec![
+                event_task,
+                sync_task,
+                audio_task,
+                catalog_task,
+                device_task,
+                device_sync_task,
+                capabilities_task,
+                similarity_task,
+                similarity_dht_serve_task,
+                similarity_dht_maintenance_task,
+                similarity_dht_sync_task,
+            ],
         });
         self.set_error(None);
         drop(guard);
@@ -262,6 +582,20 @@ impl Federation {
             .context("federation is not running")
     }
 
+    async fn similarity_services(&self) -> Result<(Arc<MusicDhtService>, Arc<SimilarityDht>)> {
+        self.running
+            .lock()
+            .await
+            .as_ref()
+            .map(|running| {
+                (
+                    Arc::clone(&running.service),
+                    Arc::clone(&running.similarity_dht),
+                )
+            })
+            .context("federation is not running")
+    }
+
     async fn spawn_sync_soon(self: &Arc<Self>) {
         if let Ok(service) = self.service().await {
             let fed = Arc::clone(self);
@@ -286,7 +620,7 @@ impl Federation {
         Ok(())
     }
 
-    async fn sync_once(&self, service: &MusicDhtService) -> Result<SyncStats> {
+    async fn sync_once(self: &Arc<Self>, service: &MusicDhtService) -> Result<SyncStats> {
         let specs = match self.collect_specs().await {
             Ok(specs) => specs,
             Err(err) => {
@@ -346,7 +680,7 @@ impl Federation {
 
     /// Everything the regular player shows, as DHT item specs: non-hidden
     /// artists, releases and tracks (a track also hides with its release).
-    async fn collect_specs(&self) -> Result<Vec<ItemSpec>> {
+    async fn collect_specs(self: &Arc<Self>) -> Result<Vec<ItemSpec>> {
         let pool = self.pool().await?;
         let mut specs = Vec::new();
 
@@ -434,24 +768,37 @@ impl Federation {
         let tracks = sqlx::query(
             "SELECT t.id, t.title, COALESCE(t.year, r.year), t.duration_seconds,
                     r.title, r.release_type, t.track_number, t.disc_number,
-                    t.audio_file_id, m.file_path, m.sha256_hash
+                    t.audio_file_id, m.file_path, m.sha256_hash, c.content_id
              FROM furumusic__track t
              JOIN furumusic__release r ON r.id = t.release_id
              JOIN furumusic__media_file m ON m.id = t.audio_file_id
+             LEFT JOIN furumusic__federation_content_id_cache c
+                    ON c.media_file_id = m.id AND c.sha256_hash = m.sha256_hash
              WHERE t.is_hidden = false AND r.is_hidden = false",
         )
         .fetch_all(&pool)
         .await?;
         let storage_dir = lock(&self.storage_dir).clone();
+        let mut content_hash_jobs = Vec::new();
         for row in &tracks {
             let id: i64 = row.get(0);
             let duration: f64 = row.get(3);
             let media_file_id: i64 = row.get(8);
             let file_path: String = row.get(9);
             let sha256_hash: String = row.get(10);
-            let content_id = self
-                .content_id_for_media(media_file_id, sha256_hash, file_path, &storage_dir)
-                .await;
+            let cached_content_id: Option<String> = row.get(11);
+            let content_id = cached_content_id
+                .or_else(|| self.cached_content_id_for_media(media_file_id, &sha256_hash));
+            if content_id.is_none()
+                && !storage_dir.trim().is_empty()
+                && self.mark_content_hash_pending(media_file_id)
+            {
+                content_hash_jobs.push(ContentHashJob {
+                    media_file_id,
+                    sha256_hash,
+                    file_path,
+                });
+            }
             specs.push(ItemSpec {
                 local_key: format!("track:{id}"),
                 kind: ItemKind::Track,
@@ -467,30 +814,67 @@ impl Federation {
                 content_id,
             });
         }
+        self.spawn_content_warmer(pool.clone(), storage_dir, content_hash_jobs);
 
         Ok(specs)
     }
 
-    async fn content_id_for_media(
-        &self,
-        media_file_id: i64,
-        sha256_hash: String,
-        file_path: String,
-        storage_dir: &str,
-    ) -> Option<String> {
+    fn cached_content_id_for_media(&self, media_file_id: i64, sha256_hash: &str) -> Option<String> {
         if let Some((cached_hash, content_id)) = lock(&self.content_cache).get(&media_file_id)
-            && cached_hash == &sha256_hash
+            && cached_hash == sha256_hash
         {
             return Some(content_id.clone());
         }
-        let storage_dir = storage_dir.to_string();
-        let content_id =
-            tokio::task::spawn_blocking(move || audio_content_id(&storage_dir, &file_path))
+        None
+    }
+
+    fn mark_content_hash_pending(&self, media_file_id: i64) -> bool {
+        lock(&self.content_pending).insert(media_file_id)
+    }
+
+    fn spawn_content_warmer(
+        self: &Arc<Self>,
+        pool: PgPool,
+        storage_dir: String,
+        jobs: Vec<ContentHashJob>,
+    ) {
+        if jobs.is_empty() {
+            return;
+        }
+        let fed = Arc::clone(self);
+        tokio::spawn(async move {
+            let total = jobs.len();
+            let mut stored = 0usize;
+            for job in jobs {
+                let job_storage_dir = storage_dir.clone();
+                let job_file_path = job.file_path.clone();
+                let content_id = tokio::task::spawn_blocking(move || {
+                    audio_content_id(&job_storage_dir, &job_file_path)
+                })
                 .await
                 .ok()
-                .flatten()?;
-        lock(&self.content_cache).insert(media_file_id, (sha256_hash, content_id.clone()));
-        Some(content_id)
+                .flatten();
+                lock(&fed.content_pending).remove(&job.media_file_id);
+                if let Some(content_id) = content_id {
+                    lock(&fed.content_cache).insert(
+                        job.media_file_id,
+                        (job.sha256_hash.clone(), content_id.clone()),
+                    );
+                    if let Err(err) =
+                        persist_content_id(&pool, job.media_file_id, &job.sha256_hash, &content_id)
+                            .await
+                    {
+                        tracing::warn!(
+                            media_file_id = job.media_file_id,
+                            "federation content-id cache write failed: {err:#}"
+                        );
+                    } else {
+                        stored += 1;
+                    }
+                }
+            }
+            tracing::info!(total, stored, "federation content-id cache warm finished");
+        });
     }
 
     /// Live status for the admin page.
@@ -509,13 +893,19 @@ impl Federation {
                     .iter()
                     .map(|p| p.to_string())
                     .collect();
+                let mut transport = self.transport_stats.snapshot();
+                if let Ok(pool) = self.pool().await {
+                    enrich_transport_users(&pool, &mut transport).await;
+                }
                 json!({
                     "running": true,
                     "network": running.network_name,
                     "endpoint_id": service.endpoint_id().to_string(),
                     "connected_peers": peers,
                     "known_contacts": service.known_peers().len(),
+                    "similarity_routing_peers": running.similarity_dht.known_peers(),
                     "published_items": published,
+                    "transport": transport,
                 })
             }
             None => json!({ "running": false }),
@@ -548,6 +938,233 @@ impl Federation {
             .map_err(|err| anyhow::anyhow!("connect failed: {err}"))?;
         Ok(peer.to_string())
     }
+
+    pub async fn search_similarity(
+        &self,
+        query: crate::similarity::QueryVector,
+        limit: usize,
+    ) -> Result<similarity::SimilaritySearchOutcome> {
+        anyhow::ensure!(
+            crate::similarity::handle().enabled(),
+            "similarity search is disabled"
+        );
+        let (service, similarity_dht) = self.similarity_services().await?;
+        similarity::search(
+            service,
+            similarity_dht,
+            query,
+            limit,
+            Arc::clone(&self.transport_stats),
+        )
+        .await
+    }
+
+    pub async fn fed_device_status(
+        &self,
+        user_id: i64,
+        user_name: &str,
+    ) -> Result<devices::FedDeviceStatus> {
+        let pool = self.pool().await?;
+        devices::status(&pool, user_id, user_name).await
+    }
+
+    pub async fn fed_device_invite(&self, user_id: i64, user_name: &str) -> Result<String> {
+        let service = self.service().await?;
+        let pool = self.pool().await?;
+        devices::create_invite(&pool, service, user_id, user_name).await
+    }
+
+    pub async fn fed_device_connect(
+        &self,
+        user_id: i64,
+        user_name: &str,
+        invite: &str,
+    ) -> Result<String> {
+        let network_id = devices::invite_network_id(invite)?;
+        {
+            let guard = self.running.lock().await;
+            let Some(running) = guard.as_ref() else {
+                anyhow::bail!("federation is not running");
+            };
+            let expected = NetworkId::from_name(&running.network_name);
+            anyhow::ensure!(
+                network_id == expected,
+                "device invite belongs to a different federation network"
+            );
+        }
+        let service = self.service().await?;
+        let pool = self.pool().await?;
+        devices::connect_invite(
+            &pool,
+            service,
+            crate::player::PlayerDeviceHub::shared(),
+            Arc::clone(&self.transport_stats),
+            user_id,
+            user_name,
+            invite,
+        )
+        .await
+    }
+
+    pub async fn fed_device_answer_pairing(
+        &self,
+        user_id: i64,
+        request_id: &str,
+        accept: bool,
+        use_requester_group: bool,
+    ) -> Result<()> {
+        let pool = self.pool().await?;
+        devices::answer_pairing(&pool, user_id, request_id, accept, use_requester_group).await
+    }
+
+    pub async fn fed_device_revoke(&self, user_id: i64, device_id: &str) -> Result<()> {
+        let pool = self.pool().await?;
+        devices::revoke_device(&pool, user_id, device_id).await
+    }
+
+    pub async fn fed_device_sync_now(&self, user_id: i64) -> Result<()> {
+        let service = self.service().await?;
+        let pool = self.pool().await?;
+        devices::sync_once(
+            &pool,
+            service,
+            crate::player::PlayerDeviceHub::shared(),
+            Arc::clone(&self.transport_stats),
+            user_id,
+        )
+        .await
+    }
+
+    pub async fn fed_device_web_command(
+        &self,
+        user_id: i64,
+        target_device_id: &str,
+        command: &str,
+        payload: serde_json::Value,
+        current_state: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let pool = self.pool().await?;
+        devices::record_web_playback_command(
+            &pool,
+            user_id,
+            target_device_id,
+            command,
+            payload,
+            current_state,
+        )
+        .await
+    }
+
+    pub async fn fed_device_web_active_transfer(
+        &self,
+        user_id: i64,
+        target_device_id: &str,
+        previous_device_id: Option<&str>,
+        state: serde_json::Value,
+    ) -> Result<()> {
+        let pool = self.pool().await?;
+        devices::record_web_active_transfer(
+            &pool,
+            user_id,
+            target_device_id,
+            previous_device_id,
+            state,
+        )
+        .await
+    }
+
+    pub async fn fed_device_web_active_takeover(
+        &self,
+        user_id: i64,
+        previous_device_id: &str,
+        state: serde_json::Value,
+    ) -> Result<()> {
+        let pool = self.pool().await?;
+        devices::record_web_active_takeover(&pool, user_id, previous_device_id, state).await
+    }
+}
+
+async fn similarity_route_sync_loop(
+    routing: Arc<SimilarityDht>,
+    manager: Arc<crate::similarity::Manager>,
+) {
+    let mut interval = tokio::time::interval(SYNC_INTERVAL);
+    interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    let mut published_marker: Option<(String, blake3::Hash)> = None;
+    loop {
+        interval.tick().await;
+        if !manager.enabled() {
+            if published_marker.take().is_some() {
+                routing.clear_local_signatures();
+                tracing::info!("local similarity DHT publication disabled");
+            }
+            continue;
+        }
+        let status = manager.status();
+        let Some(profile_id) = status.active_profile else {
+            continue;
+        };
+        if status.phase != crate::similarity::Phase::Ready {
+            continue;
+        }
+        let signatures = match manager.routing_signatures(&profile_id).await {
+            Ok(signatures) => signatures,
+            Err(error) => {
+                tracing::warn!(%error, %profile_id, "similarity routing signatures unavailable");
+                continue;
+            }
+        };
+        let mut hasher = blake3::Hasher::new();
+        for signature in &signatures {
+            hasher.update(signature);
+        }
+        let marker = (profile_id.clone(), hasher.finalize());
+        if published_marker.as_ref() == Some(&marker) {
+            continue;
+        }
+        match routing
+            .sync_local_signatures(profile_id.clone(), signatures)
+            .await
+        {
+            Ok(stats) => {
+                tracing::info!(
+                    profile = %profile_id,
+                    records = stats.records,
+                    keys = stats.keys,
+                    remote_nodes = stats.remote_nodes,
+                    "local similarity DHT index synchronized"
+                );
+                published_marker = Some(marker);
+            }
+            Err(error) => {
+                tracing::warn!(%error, %profile_id, "similarity DHT synchronization failed");
+            }
+        }
+    }
+}
+
+async fn persist_content_id(
+    pool: &PgPool,
+    media_file_id: i64,
+    sha256_hash: &str,
+    content_id: &str,
+) -> Result<()> {
+    sqlx::query(
+        "INSERT INTO furumusic__federation_content_id_cache
+         (media_file_id, sha256_hash, content_id, updated_at)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (media_file_id) DO UPDATE SET
+            sha256_hash = EXCLUDED.sha256_hash,
+            content_id = EXCLUDED.content_id,
+            updated_at = EXCLUDED.updated_at",
+    )
+    .bind(media_file_id)
+    .bind(sha256_hash)
+    .bind(content_id)
+    .bind(now_iso())
+    .execute(pool)
+    .await?;
+    Ok(())
 }
 
 fn audio_content_id(storage_dir: &str, file_path: &str) -> Option<String> {

src/federation/serve.rs

@@ -3,18 +3,26 @@
 //! with the furumi TUI client and any other furumi peer.
 
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 
 use anyhow::Result;
-use music_dht::{ByteStream, EndpointId, ItemId, ItemKind, StreamAcceptor};
+pub use music_dht::catalog::CATALOG_ALPN;
+use music_dht::catalog::{
+    CatalogArtist, CatalogArtistPreview, CatalogImageHeader as ImageHeader, CatalogRelease,
+    CatalogRequest, CatalogResponse, CatalogTrack,
+};
+use music_dht::{ByteStream, EndpointId, ItemId, ItemKind, StreamAcceptor, normalize_name};
 use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use sqlx::Row as _;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncSeekExt, AsyncWriteExt};
 
+use super::{TransportStats, record_stream_transport};
+
 /// ALPN of the peer-to-peer audio streaming protocol.
 pub const AUDIO_ALPN: &[u8] = b"furumi-fd/audio/1";
-/// ALPN of the per-artist catalog protocol.
-pub const CATALOG_ALPN: &[u8] = b"furumi-fd/catalog/1";
+/// Version of the peer-to-peer audio streaming protocol.
+pub const AUDIO_PROTOCOL_VERSION: u16 = 1;
 
 /// Maximum size of a JSON protocol line (request or response header).
 const MAX_PROTOCOL_LINE: usize = 4096;
@@ -63,58 +71,6 @@ struct TrackMetadata {
     disc_number: Option<i32>,
 }
 
-#[derive(Debug, Deserialize)]
-struct CatalogRequest {
-    artist: String,
-    #[serde(default)]
-    want: Option<String>,
-    #[serde(default)]
-    release: Option<String>,
-}
-
-#[derive(Debug, Default, Serialize)]
-struct CatalogResponse {
-    ok: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    error: Option<String>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    artist: Option<CatalogArtist>,
-}
-
-#[derive(Debug, Default, Serialize)]
-struct CatalogArtist {
-    name: String,
-    releases: Vec<CatalogRelease>,
-}
-
-#[derive(Debug, Default, Serialize)]
-struct CatalogRelease {
-    title: String,
-    release_type: String,
-    year: Option<i32>,
-    tracks: Vec<CatalogTrack>,
-}
-
-#[derive(Debug, Default, Serialize)]
-struct CatalogTrack {
-    title: String,
-    track_number: Option<i32>,
-    disc_number: Option<i32>,
-    duration_seconds: Option<f64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    content_id: Option<String>,
-    item_id: String,
-}
-
-#[derive(Debug, Default, Serialize)]
-struct ImageHeader {
-    ok: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    error: Option<String>,
-    mime_type: String,
-    size: u64,
-}
-
 // ---------------------------------------------------------------------------
 // Framing helpers
 // ---------------------------------------------------------------------------
@@ -274,6 +230,31 @@ async fn track_artist_image_file(pool: &PgPool, track_id: i64) -> Result<Option<
     Ok(row.map(|row| (row.get(0), row.get(1))))
 }
 
+async fn track_catalog_artist_names(
+    pool: &PgPool,
+    track_id: i64,
+) -> Result<(Vec<String>, Vec<String>)> {
+    let mut artists = Vec::new();
+    let mut featured = Vec::new();
+    let rows = sqlx::query(
+        "SELECT a.name, ta.role FROM furumusic__track_artist ta
+         JOIN furumusic__artist a ON a.id = ta.artist_id
+         WHERE ta.track_id = $1 ORDER BY ta.position",
+    )
+    .bind(track_id)
+    .fetch_all(pool)
+    .await?;
+    for row in rows {
+        let name: String = row.get(0);
+        match row.get::<String, _>(1).as_str() {
+            "featuring" => featured.push(name),
+            "main" => artists.push(name),
+            _ => {}
+        }
+    }
+    Ok((artists, featured))
+}
+
 async fn track_metadata(pool: &PgPool, track_id: i64) -> Result<Option<TrackMetadata>> {
     let Some(track) = sqlx::query(
         "SELECT t.title, t.track_number, t.disc_number, COALESCE(t.year, r.year),
@@ -344,13 +325,16 @@ pub async fn serve_audio(
     pool: PgPool,
     storage_dir: String,
     own: EndpointId,
+    transport_stats: Arc<TransportStats>,
 ) {
     while let Some(stream) = acceptor.accept().await {
         let pool = pool.clone();
         let storage_dir = storage_dir.clone();
+        let transport_stats = Arc::clone(&transport_stats);
         tokio::spawn(async move {
             let peer = stream.peer_id;
-            if let Err(err) = serve_audio_one(stream, pool, storage_dir, own).await {
+            if let Err(err) = serve_audio_one(stream, pool, storage_dir, own, transport_stats).await
+            {
                 tracing::warn!(peer = %peer, "federation audio stream failed: {err:#}");
             }
         });
@@ -362,7 +346,9 @@ async fn serve_audio_one(
     pool: PgPool,
     storage_dir: String,
     own: EndpointId,
+    transport_stats: Arc<TransportStats>,
 ) -> Result<()> {
+    record_stream_transport(&transport_stats, "audio", "inbound", "open", &stream);
     let request: AudioRequest = serde_json::from_slice(&read_line(&mut stream.recv).await?)?;
     tracing::info!(
         peer = %stream.peer_id,
@@ -465,6 +451,7 @@ async fn serve_audio_one(
     // Wait until the peer read everything before dropping the stream,
     // otherwise the tail of the file is lost.
     let _ = stream.send.stopped().await;
+    record_stream_transport(&transport_stats, "audio", "inbound", "done", &stream);
     Ok(())
 }
 
@@ -493,13 +480,17 @@ pub async fn serve_catalog(
     pool: PgPool,
     storage_dir: String,
     own: EndpointId,
+    transport_stats: Arc<TransportStats>,
 ) {
     while let Some(stream) = acceptor.accept().await {
         let pool = pool.clone();
         let storage_dir = storage_dir.clone();
+        let transport_stats = Arc::clone(&transport_stats);
         tokio::spawn(async move {
             let peer = stream.peer_id;
-            if let Err(err) = serve_catalog_one(stream, pool, storage_dir, own).await {
+            if let Err(err) =
+                serve_catalog_one(stream, pool, storage_dir, own, transport_stats).await
+            {
                 tracing::warn!(peer = %peer, "federation catalog request failed: {err:#}");
             }
         });
@@ -511,7 +502,9 @@ async fn serve_catalog_one(
     pool: PgPool,
     storage_dir: String,
     own: EndpointId,
+    transport_stats: Arc<TransportStats>,
 ) -> Result<()> {
+    record_stream_transport(&transport_stats, "catalog", "inbound", "open", &stream);
     let request: CatalogRequest = serde_json::from_slice(&read_line(&mut stream.recv).await?)?;
     tracing::info!(
         peer = %stream.peer_id,
@@ -522,12 +515,28 @@ async fn serve_catalog_one(
 
     match request.want.as_deref() {
         None | Some("catalog") => {
-            let response = match build_catalog(&pool, &own, &storage_dir, &request.artist).await {
+            let response = match build_catalog(&pool, &own, &request.artist).await {
                 Ok(response) => response,
                 Err(err) => CatalogResponse {
                     ok: false,
                     error: Some(format!("catalog lookup failed: {err:#}")),
-                    artist: None,
+                    ..CatalogResponse::default()
+                },
+            };
+            stream
+                .send
+                .write_all(&serde_json::to_vec(&response)?)
+                .await?;
+        }
+        Some("artists") => {
+            let cursor = request.cursor.clone();
+            let limit = request.limit.unwrap_or(64).clamp(1, 200);
+            let response = match build_artist_slice(&pool, cursor, limit).await {
+                Ok(response) => response,
+                Err(err) => CatalogResponse {
+                    ok: false,
+                    error: Some(format!("artist slice lookup failed: {err:#}")),
+                    ..CatalogResponse::default()
                 },
             };
             stream
@@ -569,7 +578,7 @@ async fn serve_catalog_one(
             let response = CatalogResponse {
                 ok: false,
                 error: Some(format!("unknown request kind '{other}'")),
-                artist: None,
+                ..CatalogResponse::default()
             };
             stream
                 .send
@@ -579,15 +588,11 @@ async fn serve_catalog_one(
     }
     stream.send.finish()?;
     let _ = stream.send.stopped().await;
+    record_stream_transport(&transport_stats, "catalog", "inbound", "done", &stream);
     Ok(())
 }
 
-async fn build_catalog(
-    pool: &PgPool,
-    own: &EndpointId,
-    storage_dir: &str,
-    artist: &str,
-) -> Result<CatalogResponse> {
+async fn build_catalog(pool: &PgPool, own: &EndpointId, artist: &str) -> Result<CatalogResponse> {
     let Some(artist_row) = sqlx::query(
         "SELECT id, name FROM furumusic__artist
          WHERE LOWER(name) = LOWER($1) AND is_hidden = false
@@ -600,7 +605,7 @@ async fn build_catalog(
         return Ok(CatalogResponse {
             ok: false,
             error: Some("artist not found in the library".to_string()),
-            artist: None,
+            ..CatalogResponse::default()
         });
     };
     let artist_id: i64 = artist_row.get(0);
@@ -620,9 +625,11 @@ async fn build_catalog(
         let release_id: i64 = release_row.get(0);
         let track_rows = sqlx::query(
             "SELECT t.id, t.title, t.track_number, t.disc_number, t.duration_seconds,
-                    m.file_path
+                    c.content_id
              FROM furumusic__track t
              JOIN furumusic__media_file m ON m.id = t.audio_file_id
+             LEFT JOIN furumusic__federation_content_id_cache c
+                    ON c.media_file_id = m.id AND c.sha256_hash = m.sha256_hash
              WHERE t.release_id = $1 AND t.is_hidden = false
              ORDER BY t.disc_number NULLS FIRST, t.track_number NULLS LAST, t.title",
         )
@@ -633,14 +640,15 @@ async fn build_catalog(
         for row in track_rows {
             let track_id: i64 = row.get(0);
             let duration: f64 = row.get(4);
-            let file_path: String = row.get(5);
-            let content_id = catalog_content_id(storage_dir, file_path).await;
+            let (artists, featured_artists) = track_catalog_artist_names(pool, track_id).await?;
             tracks.push(CatalogTrack {
                 title: row.get(1),
+                artists,
+                featured_artists,
                 track_number: row.get(2),
                 disc_number: row.get(3),
                 duration_seconds: (duration > 0.0).then_some(duration),
-                content_id,
+                content_id: row.get(5),
                 item_id: item_id_of(own, track_id),
             });
         }
@@ -654,20 +662,83 @@ async fn build_catalog(
 
     Ok(CatalogResponse {
         ok: true,
-        error: None,
         artist: Some(CatalogArtist {
             name: artist_row.get(1),
             releases,
+            appears_on: Vec::new(),
         }),
+        ..CatalogResponse::default()
     })
 }
 
-async fn catalog_content_id(storage_dir: &str, file_path: String) -> Option<String> {
-    let storage_dir = storage_dir.to_string();
-    tokio::task::spawn_blocking(move || super::audio_content_id(&storage_dir, &file_path))
-        .await
-        .ok()
-        .flatten()
+async fn build_artist_slice(
+    pool: &PgPool,
+    cursor: Option<String>,
+    limit: usize,
+) -> Result<CatalogResponse> {
+    let offset = cursor
+        .as_deref()
+        .and_then(|value| value.parse::<i64>().ok())
+        .unwrap_or(0)
+        .max(0);
+    let rows = sqlx::query(
+        r#"SELECT a.name::text AS name,
+                  mf.file_path::text AS image_path,
+                  COALESCE(s.release_count, 0)::bigint AS release_count,
+                  COALESCE(s.track_count, 0)::bigint AS track_count
+           FROM furumusic__artist a
+           LEFT JOIN furumusic__media_file mf ON mf.id = a.image_file_id
+           LEFT JOIN (
+               SELECT appearance.artist_id,
+                      COUNT(DISTINCT appearance.release_id) FILTER (WHERE appearance.is_primary_release_artist) AS release_count,
+                      COUNT(DISTINCT appearance.track_id) AS track_count
+                 FROM (
+                        SELECT ta.artist_id,
+                               t.id AS track_id,
+                               r.id AS release_id,
+                               primary_release.artist_id IS NOT NULL AS is_primary_release_artist
+                          FROM furumusic__track_artist ta
+                          JOIN furumusic__track t ON t.id = ta.track_id AND t.is_hidden = false
+                          JOIN furumusic__release r ON r.id = t.release_id AND r.is_hidden = false
+                          LEFT JOIN furumusic__release_artist primary_release
+                            ON primary_release.release_id = r.id
+                           AND primary_release.artist_id = ta.artist_id
+                           AND primary_release.position = 0
+                      ) appearance
+                GROUP BY appearance.artist_id
+           ) s ON s.artist_id = a.id
+           WHERE a.is_hidden = false
+             AND COALESCE(s.track_count, 0) > 0
+           ORDER BY (COALESCE(s.release_count, 0) > 0) DESC,
+                    COALESCE(s.release_count, 0) DESC,
+                    COALESCE(s.track_count, 0) DESC,
+                    a.name_sort
+           LIMIT $1 OFFSET $2"#,
+    )
+    .bind(limit as i64 + 1)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+
+    let mut artists = Vec::with_capacity(rows.len().min(limit));
+    let has_more = rows.len() > limit;
+    for row in rows.into_iter().take(limit) {
+        let name: String = row.get(0);
+        artists.push(CatalogArtistPreview {
+            artist_key: normalize_name(&name),
+            name,
+            image_path: row.get(1),
+            release_count: row.get(2),
+            track_count: row.get(3),
+        });
+    }
+    let next_cursor = has_more.then(|| (offset + artists.len() as i64).to_string());
+    Ok(CatalogResponse {
+        ok: true,
+        artists,
+        next_cursor,
+        ..CatalogResponse::default()
+    })
 }
 
 async fn artist_image_by_name(pool: &PgPool, artist: &str) -> Result<Option<(String, String)>> {

src/federation/similarity.rs

@@ -0,0 +1,398 @@
+//! Furumusic policy and PostgreSQL adapter for the shared similarity protocol.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::{Context as _, Result};
+use futures_util::stream::{self, StreamExt as _};
+use music_dht::similarity::{self as wire, SimilarityHit, SimilarityRequest, SimilarityResponse};
+use music_dht::similarity_dht::SimilarityDht;
+use music_dht::{
+    ByteStream, EndpointId, ItemId, ItemKind, MusicDhtService, PeerTicket, StreamAcceptor,
+};
+
+use crate::similarity::{Manager, QueryVector};
+
+use super::TransportStats;
+
+pub use music_dht::similarity::SIMILARITY_ALPN;
+
+const INITIAL_QUERY_PEERS: usize = 16;
+const MAX_QUERY_PEERS: usize = 48;
+const QUERY_CONCURRENCY: usize = 8;
+const QUERY_TIMEOUT: Duration = Duration::from_secs(5);
+const ROUTING_TIMEOUT: Duration = Duration::from_secs(5);
+const MAX_PER_ARTIST: usize = 3;
+const MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE: u32 = 8;
+
+#[derive(Debug, Clone)]
+pub struct RemoteSimilarityTrack {
+    pub owner: String,
+    pub item_id: String,
+    pub title: String,
+    pub artist_names: Vec<String>,
+    pub featured_artist_names: Vec<String>,
+    pub year: Option<i32>,
+    pub duration_seconds: Option<i64>,
+    pub content_id: Option<String>,
+    pub release_title: Option<String>,
+    pub track_number: Option<i32>,
+    pub disc_number: Option<i32>,
+    pub similarity_score: f32,
+}
+
+pub struct SimilaritySearchOutcome {
+    pub tracks: Vec<RemoteSimilarityTrack>,
+    pub queried_peers: usize,
+}
+
+pub async fn serve_peers(
+    mut acceptor: StreamAcceptor,
+    manager: Arc<Manager>,
+    own: EndpointId,
+    transport: Arc<TransportStats>,
+) {
+    while let Some(stream) = acceptor.accept().await {
+        let manager = Arc::clone(&manager);
+        let transport = Arc::clone(&transport);
+        tokio::spawn(async move {
+            let peer = stream.peer_id;
+            if let Err(error) = serve_one(stream, manager, own, transport).await {
+                tracing::warn!(peer = %peer, "similarity request failed: {error:#}");
+            }
+        });
+    }
+}
+
+async fn serve_one(
+    mut stream: ByteStream,
+    manager: Arc<Manager>,
+    own: EndpointId,
+    transport: Arc<TransportStats>,
+) -> Result<()> {
+    super::record_stream_transport(&transport, "similarity", "inbound", "open", &stream);
+    let request = wire::read_request(&mut stream).await?;
+    let response = if !manager.enabled() {
+        SimilarityResponse::refused("similarity search is disabled on this instance")?
+    } else {
+        let profile_id = request.profile_id;
+        let vector = request.vector;
+        let limit = request.limit;
+        let rank_manager = Arc::clone(&manager);
+        let ranked = tokio::task::spawn_blocking(move || {
+            rank_manager.rank_vector(&profile_id, &vector, None, None, limit)
+        })
+        .await
+        .context("local similarity task failed")
+        .and_then(|result| result);
+        match ranked {
+            Ok(ranked) => {
+                let ids = ranked
+                    .iter()
+                    .map(|track| track.track_id)
+                    .collect::<Vec<_>>();
+                match manager.metadata_for_tracks(&ids).await {
+                    Ok(metadata) => {
+                        let by_id = ranked
+                            .into_iter()
+                            .map(|track| (track.track_id, track))
+                            .collect::<HashMap<_, _>>();
+                        let hits = metadata
+                            .into_iter()
+                            .filter_map(|track| {
+                                let ranked = by_id.get(&track.track_id)?;
+                                let hit = SimilarityHit {
+                                    score: ranked.score,
+                                    item_id: hex(
+                                        ItemId::derive(
+                                            &own,
+                                            ItemKind::Track,
+                                            &format!("track:{}", track.track_id),
+                                        )
+                                        .as_bytes(),
+                                    ),
+                                    title: track.title,
+                                    artist_names: track.artist_names,
+                                    featured_artist_names: track.featured_artist_names,
+                                    year: track.year,
+                                    duration_seconds: Some(track.duration_seconds.round() as i64),
+                                    content_id: track.content_id,
+                                    release_title: Some(track.release_title),
+                                    track_number: track.track_number,
+                                    disc_number: track.disc_number,
+                                    embedding_signature: Some(ranked.embedding_signature),
+                                };
+                                match hit.validate() {
+                                    Ok(()) => Some(hit),
+                                    Err(error) => {
+                                        tracing::debug!(%error, "invalid local similarity metadata skipped");
+                                        None
+                                    }
+                                }
+                            })
+                            .collect();
+                        SimilarityResponse::success(hits)?
+                    }
+                    Err(error) => SimilarityResponse::refused(format!(
+                        "similarity metadata is unavailable: {error:#}"
+                    ))?,
+                }
+            }
+            Err(error) => {
+                SimilarityResponse::refused(format!("similarity query is unavailable: {error:#}"))?
+            }
+        }
+    };
+    wire::write_response(&mut stream, &response).await?;
+    stream.send.finish()?;
+    let _ = stream.send.stopped().await;
+    super::record_stream_transport(&transport, "similarity", "inbound", "done", &stream);
+    Ok(())
+}
+
+pub async fn search(
+    service: Arc<MusicDhtService>,
+    routing: Arc<SimilarityDht>,
+    query: QueryVector,
+    limit: usize,
+    transport: Arc<TransportStats>,
+) -> Result<SimilaritySearchOutcome> {
+    let own = service.endpoint_id();
+    let routed = match tokio::time::timeout(
+        ROUTING_TIMEOUT,
+        routing.find_peers(&query.profile_id, &query.vector, MAX_QUERY_PEERS),
+    )
+    .await
+    {
+        Ok(Ok(peers)) => peers,
+        Err(_) => {
+            tracing::debug!("similarity DHT lookup timed out; using known peers");
+            Vec::new()
+        }
+        Ok(Err(error)) => {
+            tracing::debug!(%error, "similarity DHT lookup unavailable; using known peers");
+            Vec::new()
+        }
+    };
+    let mut seen = HashSet::new();
+    let mut peers: Vec<QueryPeer> = routed
+        .into_iter()
+        .filter_map(|ticket| {
+            let owner = ticket.endpoint_id();
+            (owner != own && seen.insert(owner)).then_some(QueryPeer {
+                owner,
+                ticket: Some(ticket),
+            })
+        })
+        .collect();
+    for peer in service
+        .connected_peers()
+        .into_iter()
+        .chain(service.known_peers().into_iter().map(|peer| peer.peer_id))
+    {
+        if peer != own && seen.insert(peer) {
+            peers.push(QueryPeer {
+                owner: peer,
+                ticket: None,
+            });
+        }
+        if peers.len() >= MAX_QUERY_PEERS {
+            break;
+        }
+    }
+    let query_signature = wire::embedding_signature(&query.vector)?;
+    let request = Arc::new(SimilarityRequest::new(
+        query.profile_id,
+        query.vector,
+        limit.clamp(1, wire::MAX_SIMILARITY_RESULTS),
+    )?);
+
+    let mut hits = Vec::new();
+    let initial = peers.len().min(INITIAL_QUERY_PEERS);
+    let mut queried_peers = initial;
+    let responses = query_peers(
+        Arc::clone(&service),
+        &peers[..initial],
+        Arc::clone(&request),
+        Arc::clone(&transport),
+    )
+    .await;
+    let mut successful = 0usize;
+    for response in responses {
+        match response {
+            Ok(peer_hits) => {
+                successful += 1;
+                hits.extend(peer_hits);
+            }
+            Err(error) => tracing::debug!(%error, "similarity peer query skipped"),
+        }
+    }
+    if initial < peers.len() && (hits.len() < limit || successful < initial.min(4)) {
+        queried_peers += peers.len() - initial;
+        for response in query_peers(
+            Arc::clone(&service),
+            &peers[initial..],
+            Arc::clone(&request),
+            Arc::clone(&transport),
+        )
+        .await
+        {
+            match response {
+                Ok(peer_hits) => hits.extend(peer_hits),
+                Err(error) => tracing::debug!(%error, "fallback similarity peer query skipped"),
+            }
+        }
+    }
+    hits.sort_by(|left, right| right.1.total_cmp(&left.1));
+    let mut dedup = HashSet::new();
+    let mut signatures = vec![query_signature];
+    let mut artist_counts: HashMap<String, usize> = HashMap::new();
+    let mut tracks = Vec::new();
+    for (track, _, signature) in hits {
+        if query
+            .source_content_id
+            .as_deref()
+            .is_some_and(|source| track.content_id.as_deref() == Some(source))
+        {
+            continue;
+        }
+        let key = track
+            .content_id
+            .clone()
+            .unwrap_or_else(|| format!("{}:{}", track.owner, track.item_id));
+        if !dedup.insert(key) {
+            continue;
+        }
+        if signature.is_some_and(|candidate| {
+            signatures.iter().any(|existing| {
+                wire::signature_distance(&candidate, existing)
+                    <= MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE
+            })
+        }) {
+            continue;
+        }
+        let artist = track
+            .artist_names
+            .first()
+            .map(|name| music_dht::normalize_name(name))
+            .unwrap_or_default();
+        let count = artist_counts.entry(artist.clone()).or_default();
+        if !artist.is_empty() && *count >= MAX_PER_ARTIST {
+            continue;
+        }
+        *count += 1;
+        if let Some(signature) = signature {
+            signatures.push(signature);
+        }
+        tracks.push(track);
+        if tracks.len() >= limit.min(wire::MAX_SIMILARITY_RESULTS) {
+            break;
+        }
+    }
+    Ok(SimilaritySearchOutcome {
+        tracks,
+        queried_peers,
+    })
+}
+
+type PeerHits = Vec<(
+    RemoteSimilarityTrack,
+    f32,
+    Option<[u8; wire::SIMILARITY_SIGNATURE_BYTES]>,
+)>;
+
+#[derive(Clone)]
+struct QueryPeer {
+    owner: EndpointId,
+    ticket: Option<PeerTicket>,
+}
+
+async fn query_peers(
+    service: Arc<MusicDhtService>,
+    peers: &[QueryPeer],
+    request: Arc<SimilarityRequest>,
+    transport: Arc<TransportStats>,
+) -> Vec<Result<PeerHits>> {
+    stream::iter(peers.iter().cloned().map(|peer| {
+        let service = Arc::clone(&service);
+        let request = Arc::clone(&request);
+        let transport = Arc::clone(&transport);
+        async move {
+            tokio::time::timeout(
+                QUERY_TIMEOUT,
+                query_peer(service, peer, &request, transport),
+            )
+            .await
+            .map_err(|_| anyhow::anyhow!("similarity peer timed out"))?
+        }
+    }))
+    .buffer_unordered(QUERY_CONCURRENCY)
+    .collect()
+    .await
+}
+
+async fn query_peer(
+    service: Arc<MusicDhtService>,
+    peer: QueryPeer,
+    request: &SimilarityRequest,
+    transport: Arc<TransportStats>,
+) -> Result<PeerHits> {
+    let owner = peer.owner;
+    let mut stream = match peer.ticket {
+        Some(ticket) => service.open_stream_to(&ticket, SIMILARITY_ALPN).await,
+        None => service.open_stream(owner, SIMILARITY_ALPN).await,
+    }
+    .map_err(|error| anyhow::anyhow!("cannot reach similarity peer: {error}"))?;
+    super::record_stream_transport(&transport, "similarity", "outbound", "open", &stream);
+    let response = wire::exchange(&mut stream, request).await?;
+    super::record_stream_transport(&transport, "similarity", "outbound", "done", &stream);
+    anyhow::ensure!(
+        response.ok,
+        "peer refused similarity query: {}",
+        response.error.unwrap_or_default()
+    );
+    Ok(response
+        .hits
+        .into_iter()
+        .map(|hit| {
+            let score = hit.score;
+            let signature = hit.embedding_signature;
+            (
+                RemoteSimilarityTrack {
+                    owner: owner.to_string(),
+                    item_id: hit.item_id,
+                    title: hit.title,
+                    artist_names: hit.artist_names,
+                    featured_artist_names: hit.featured_artist_names,
+                    year: hit.year,
+                    duration_seconds: hit.duration_seconds,
+                    content_id: hit.content_id,
+                    release_title: hit.release_title,
+                    track_number: hit.track_number,
+                    disc_number: hit.disc_number,
+                    similarity_score: score,
+                },
+                score,
+                signature,
+            )
+        })
+        .collect())
+}
+
+fn hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hamming_threshold_keeps_exact_and_near_duplicates_out() {
+        let query = [0u8; wire::SIMILARITY_SIGNATURE_BYTES];
+        let mut near = query;
+        near[0] = 0b0000_0111;
+        assert!(wire::signature_distance(&query, &near) <= MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE);
+    }
+}

src/federation/storage.rs

@@ -44,6 +44,14 @@ const SCHEMA: &[&str] = &[
         ticket        TEXT NOT NULL,
         last_seen_ms  BIGINT NOT NULL
     )",
+    "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+        media_file_id  BIGINT PRIMARY KEY,
+        sha256_hash    TEXT NOT NULL,
+        content_id     TEXT NOT NULL,
+        updated_at     TEXT NOT NULL
+    )",
+    "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+        ON furumusic__federation_content_id_cache(content_id)",
 ];
 
 #[derive(Debug, Clone)]
@@ -157,52 +165,21 @@ impl MusicDhtStorage for PostgresFederationStorage {
     }
 
     async fn store_dht_record(&self, key: DhtKey, record: StoredRecord) -> music_dht::Result<bool> {
-        let existing = sqlx::query(
-            "SELECT revision, deleted, expires_at_ms
-             FROM furumusic__federation_dht_record
-             WHERE dht_key = $1 AND item_id = $2 AND owner_peer_id = $3",
-        )
-        .bind(key.as_bytes().as_slice())
-        .bind(record.item.id.as_bytes().as_slice())
-        .bind(record.item.owner.to_string())
-        .fetch_optional(&self.pool)
-        .await
-        .map_err(db_error)?
-        .map(|row| {
-            (
-                row.get::<i64, _>(0) as u64,
-                row.get::<bool, _>(1),
-                row.get::<i64, _>(2) as u64,
-            )
-        });
+        let mut conn = self.pool.acquire().await.map_err(db_error)?;
+        store_record_in_conn(&mut conn, &key, &record).await
+    }
 
-        match decide_store(existing, &record) {
-            StoreDecision::Ignore => return Ok(false),
-            StoreDecision::Write | StoreDecision::RefreshExpiry(_) => {}
+    async fn store_dht_records(
+        &self,
+        entries: Vec<(DhtKey, StoredRecord)>,
+    ) -> music_dht::Result<Vec<bool>> {
+        let mut tx = self.pool.begin().await.map_err(db_error)?;
+        let mut stored = Vec::with_capacity(entries.len());
+        for (key, record) in &entries {
+            stored.push(store_record_in_conn(&mut tx, key, record).await?);
         }
-
-        let payload = postcard::to_stdvec(&record).map_err(db_error)?;
-        sqlx::query(
-            "INSERT INTO furumusic__federation_dht_record
-             (dht_key, item_id, owner_peer_id, payload, revision, deleted, expires_at_ms)
-             VALUES ($1, $2, $3, $4, $5, $6, $7)
-             ON CONFLICT (dht_key, item_id, owner_peer_id) DO UPDATE SET
-                payload = EXCLUDED.payload,
-                revision = EXCLUDED.revision,
-                deleted = EXCLUDED.deleted,
-                expires_at_ms = EXCLUDED.expires_at_ms",
-        )
-        .bind(key.as_bytes().as_slice())
-        .bind(record.item.id.as_bytes().as_slice())
-        .bind(record.item.owner.to_string())
-        .bind(payload)
-        .bind(record.item.revision as i64)
-        .bind(record.item.deleted)
-        .bind(record.expires_at_ms as i64)
-        .execute(&self.pool)
-        .await
-        .map_err(db_error)?;
-        Ok(true)
+        tx.commit().await.map_err(db_error)?;
+        Ok(stored)
     }
 
     async fn dht_records_by_key(
@@ -311,6 +288,62 @@ fn secret_from_bytes(bytes: Vec<u8>) -> music_dht::Result<SecretKey> {
     Ok(SecretKey::from_bytes(&bytes))
 }
 
+/// Applies one validated record following the revision/tombstone rules.
+/// Returns `true` if the record was written or refreshed. Runs against a
+/// pooled connection or an open transaction.
+async fn store_record_in_conn(
+    conn: &mut sqlx::PgConnection,
+    key: &DhtKey,
+    record: &StoredRecord,
+) -> music_dht::Result<bool> {
+    let existing = sqlx::query(
+        "SELECT revision, deleted, expires_at_ms
+         FROM furumusic__federation_dht_record
+         WHERE dht_key = $1 AND item_id = $2 AND owner_peer_id = $3",
+    )
+    .bind(key.as_bytes().as_slice())
+    .bind(record.item.id.as_bytes().as_slice())
+    .bind(record.item.owner.to_string())
+    .fetch_optional(&mut *conn)
+    .await
+    .map_err(db_error)?
+    .map(|row| {
+        (
+            row.get::<i64, _>(0) as u64,
+            row.get::<bool, _>(1),
+            row.get::<i64, _>(2) as u64,
+        )
+    });
+
+    match decide_store(existing, record) {
+        StoreDecision::Ignore => return Ok(false),
+        StoreDecision::Write | StoreDecision::RefreshExpiry(_) => {}
+    }
+
+    let payload = postcard::to_stdvec(record).map_err(db_error)?;
+    sqlx::query(
+        "INSERT INTO furumusic__federation_dht_record
+         (dht_key, item_id, owner_peer_id, payload, revision, deleted, expires_at_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         ON CONFLICT (dht_key, item_id, owner_peer_id) DO UPDATE SET
+            payload = EXCLUDED.payload,
+            revision = EXCLUDED.revision,
+            deleted = EXCLUDED.deleted,
+            expires_at_ms = EXCLUDED.expires_at_ms",
+    )
+    .bind(key.as_bytes().as_slice())
+    .bind(record.item.id.as_bytes().as_slice())
+    .bind(record.item.owner.to_string())
+    .bind(payload)
+    .bind(record.item.revision as i64)
+    .bind(record.item.deleted)
+    .bind(record.expires_at_ms as i64)
+    .execute(&mut *conn)
+    .await
+    .map_err(db_error)?;
+    Ok(true)
+}
+
 fn db_error(err: impl std::fmt::Display) -> MusicDhtError {
     MusicDhtError::Database(err.to_string())
 }

src/i18n/phrases.rs

@@ -96,9 +96,9 @@ translations! {
     settings_swagger:         "Swagger UI"                    , "Swagger UI";
     settings_swagger_help:    "Serves interactive API docs at /swagger/ (requires restart)" , "Интерактивная документация API на /swagger/ (требуется перезапуск)";
     settings_lastfm_api_key:  "Last.fm API key"               , "API ключ Last.fm";
-    settings_lastfm_api_key_help: "Used for Last.fm popularity and account connection" , "Используется для популярности Last.fm и подключения аккаунта";
+    settings_lastfm_api_key_help: "Identifies this application to Last.fm and enables metadata, popularity data, and user account connection" , "Идентифицирует приложение в Last.fm и включает метаданные, данные о популярности и подключение аккаунтов";
     settings_lastfm_shared_secret: "Last.fm shared secret"    , "Shared secret Last.fm";
-    settings_lastfm_shared_secret_help: "Required for signed Last.fm scrobbling requests" , "Нужен для подписанных запросов скробблинга Last.fm";
+    settings_lastfm_shared_secret_help: "Authenticates signed Last.fm requests, including scrobbling. Keep this value private" , "Подтверждает подписанные запросы Last.fm, включая скробблинг. Не раскрывайте это значение";
 
     // OIDC login errors
     login_oidc_error:         "SSO login failed. Please try again." , "Ошибка входа через SSO. Попробуйте ещё раз.";
@@ -298,6 +298,9 @@ translations! {
     player_likes_playlist:   "Likes"                           , "Лайки";
     player_listened:         "listened"                        , "прослушано";
     player_search_placeholder: "Search artists, releases, tracks..." , "Поиск артистов, релизов, треков...";
+    player_search_similar_to: "Search similar to:"                , "Поиск похожих на:";
+    player_find_similar:      "Find similar tracks"                , "Найти похожие треки";
+    player_similarity_failed: "Similarity search failed"           , "Не удалось найти похожие треки";
     player_connection_lost: "Server connection lost"             , "Нет соединения с сервером";
     player_connection_lost_detail: "Player cannot reach the server. Retrying..." , "Плеер не может связаться с сервером. Повторяю...";
     player_active_device:   "Active device"                   , "Активный девайс";
@@ -309,10 +312,14 @@ translations! {
     player_cancel:           "Cancel"                          , "Отмена";
     player_create:           "Create"                          , "Создать";
     player_save:             "Save"                            , "Сохранить";
+    player_done:             "Done"                            , "Готово";
     player_delete:           "Delete"                          , "Удалить";
     player_delete_playlist_confirm: "Delete this playlist?"     , "Удалить этот плейлист?";
     player_rename:           "Rename"                          , "Переименовать";
     player_close:            "Close"                           , "Закрыть";
+    player_interface_language: "Interface language"             , "Язык интерфейса";
+    player_language_description: "Choose the language used by the web player." , "Выберите язык интерфейса веб-плеера.";
+    player_switch_language:  "Русский"                         , "English";
     player_log_out:          "Log out"                         , "Выйти";
     player_admin_panel:      "Admin Panel"                     , "Админка";
     player_info:             "Info"                            , "Информация";
@@ -382,9 +389,54 @@ translations! {
     player_live_releases:    "Live releases"                   , "Концертные релизы";
     player_soundtracks:      "Soundtracks"                     , "Саундтреки";
 
-    // Player torrent/history UI
-    player_torrent_manager:  "Torrent manager"                 , "Торрент-менеджер";
-    player_import_torrent:   "Import torrent"                  , "Импортировать торрент";
+    // Player download/history UI
+    player_torrent_manager:  "Download Manager"                , "Менеджер загрузок";
+    player_import_torrent:   "Open Download Manager"           , "Открыть менеджер загрузок";
+    player_youtube:          "YouTube"                         , "YouTube";
+    player_torrents:         "Torrents"                        , "Торренты";
+    player_files:            "Files"                           , "Файлы";
+    player_youtube_url:      "Public video or playlist URL"    , "Ссылка на открытое видео или плейлист";
+    player_youtube_url_hint: "Public youtube.com, music.youtube.com and youtu.be links are supported. Each video is imported as one AI batch." , "Поддерживаются открытые ссылки youtube.com, music.youtube.com и youtu.be. Каждое видео импортируется одним ИИ-батчем.";
+    player_youtube_downloads: "YouTube downloads"              , "Загрузки YouTube";
+    player_no_youtube_downloads: "No YouTube downloads yet"    , "Загрузок YouTube пока нет";
+    player_youtube_parse:     "Check link"                     , "Проверить ссылку";
+    player_youtube_parsing:   "Reading YouTube link..."        , "Читаю ссылку YouTube...";
+    player_youtube_preview_failed: "Could not read YouTube link" , "Не удалось прочитать ссылку YouTube";
+    player_youtube_preview_title: "Choose videos to import"     , "Выберите видео для импорта";
+    player_youtube_select_all: "Select all"                    , "Отметить все";
+    player_youtube_clear_selection: "Clear selection"           , "Снять все";
+    player_youtube_selected_count: "selected"                  , "выбрано";
+    player_youtube_start_import: "Start import"                , "Начать импорт";
+    player_start_download:   "Start download"                  , "Начать загрузку";
+    player_retry_failed:     "Retry failed"                    , "Повторить ошибки";
+    player_download_steps:   "Processing steps"                , "Этапы обработки";
+    player_chapters:         "chapters"                        , "глав";
+    player_youtube_video:    "video"                           , "видео";
+    player_youtube_playlist: "playlist"                        , "плейлист";
+    player_youtube_items:    "videos"                          , "видео";
+    player_youtube_errors:   "errors"                          , "ошибок";
+    player_youtube_queued:   "Queued"                          , "В очереди";
+    player_youtube_resolving: "Reading link"                   , "Чтение ссылки";
+    player_youtube_postprocessing: "FFmpeg processing"         , "Обработка FFmpeg";
+    player_youtube_awaiting_ai: "Waiting for AI"               , "Ожидание ИИ";
+    player_youtube_ai_processing: "AI processing"              , "Обработка ИИ";
+    player_youtube_needs_review: "Needs review"                , "Требует проверки";
+    player_youtube_complete_with_errors: "Completed with errors" , "Завершено с ошибками";
+    player_youtube_skipped:  "Already imported"                , "Уже импортировано";
+    player_youtube_cancelled: "Stopped"                         , "Остановлено";
+    player_youtube_stop:     "Stop import"                     , "Остановить импорт";
+    player_youtube_stop_confirm: "Stop this YouTube import? Completed and already published audio will remain." , "Остановить этот импорт из YouTube? Готовое и уже переданное на обработку аудио останется.";
+    player_youtube_stopping: "Stopping YouTube import..."      , "Останавливаю импорт из YouTube...";
+    player_youtube_stopped:  "YouTube import stopped."         , "Импорт из YouTube остановлен.";
+    player_youtube_stop_failed: "Could not stop YouTube import" , "Не удалось остановить импорт из YouTube";
+    player_youtube_starting: "Adding YouTube download..."      , "Добавляю загрузку YouTube...";
+    player_youtube_started:  "YouTube download added."         , "Загрузка YouTube добавлена.";
+    player_youtube_load_failed: "Could not load YouTube downloads" , "Не удалось загрузить список YouTube";
+    player_youtube_start_failed: "Could not start YouTube download" , "Не удалось начать загрузку YouTube";
+    player_youtube_retry_failed: "Could not retry YouTube download" , "Не удалось повторить загрузку YouTube";
+    player_youtube_delete_failed: "Could not remove YouTube download" , "Не удалось удалить загрузку YouTube";
+    player_youtube_delete_confirm: "Remove this YouTube download from history? Imported audio will remain." , "Удалить эту загрузку YouTube из истории? Импортированное аудио останется.";
+    player_remove_from_history: "Remove from history"          , "Удалить из истории";
     player_client_idle:      "Client idle"                     , "Клиент простаивает";
     player_active:           "active"                          , "активно";
     player_ai_idle:          "AI idle"                         , "ИИ простаивает";
@@ -460,11 +512,24 @@ translations! {
     player_track_approved_imported: "Track approved and imported" , "Трек подтверждён и импортирован";
     player_failed_update_selected_tracks: "Failed to update selected tracks" , "Не удалось обновить выбранные треки";
     player_selected_tracks_updated: "Selected tracks updated"   , "Выбранные треки обновлены";
-    player_choose_saved_or_add_torrent: "Choose a saved item or upload new files." , "Выберите сохранённый элемент или загрузите новые файлы.";
+    player_choose_saved_or_add_torrent: "Choose a saved torrent or add a new one." , "Выберите сохранённый торрент или добавьте новый.";
     player_local_files:      "Local audio files"               , "Локальные аудиофайлы";
+    player_file_uploads:     "File uploads"                    , "Загрузки файлов";
+    player_drop_audio_title: "Drop audio files here"           , "Перетащите аудиофайлы сюда";
+    player_drop_audio_hint:  "or click to choose files"        , "или нажмите, чтобы выбрать файлы";
+    player_drop_audio_formats: "MP3, FLAC, WAV, M4A, OGG, Opus and AAC" , "MP3, FLAC, WAV, M4A, OGG, Opus и AAC";
+    player_upload_selected_files: "Upload selected files"      , "Загрузить выбранные файлы";
+    player_upload_history:   "Upload history"                  , "История загрузок";
+    player_no_file_uploads:  "No file uploads yet"             , "Загрузок файлов пока нет";
+    player_file_upload_load_failed: "Could not load file upload history" , "Не удалось загрузить историю файлов";
+    player_remove_file_upload_confirm: "Remove this file upload from history? Imported audio will remain." , "Удалить эту загрузку файла из истории? Импортированное аудио останется.";
+    player_file_upload_history_removed: "File upload removed from history." , "Загрузка файла удалена из истории.";
+    player_file_upload_history_remove_failed: "Could not remove file upload from history" , "Не удалось удалить загрузку файла из истории";
+    player_no_supported_audio_files: "Choose at least one supported audio file." , "Выберите хотя бы один поддерживаемый аудиофайл.";
     player_torrent_file:     "Torrent file"                    , "Torrent-файл";
     player_magnet_link:      "Magnet link"                     , "Magnet-ссылка";
-    player_upload_content:   "Upload"                          , "Загрузить";
+    player_upload_content:   "Preview torrent"                 , "Проверить торрент";
+    player_add_torrent:      "Add torrent"                     , "Добавить торрент";
     player_download_selected: "Download selected"              , "Скачать выбранное";
     player_pause_download:   "Pause download"                  , "Поставить на паузу";
     player_expand_all:       "Expand all"                      , "Развернуть всё";
@@ -494,7 +559,7 @@ translations! {
     player_no_plays_yet:     "No plays yet"                    , "Прослушиваний пока нет";
     player_page:             "Page"                            , "Страница";
     player_of:               "of"                              , "из";
-    player_choose_torrent:   "Choose local files, paste a magnet link, or choose a .torrent file." , "Выберите локальные файлы, вставьте magnet-ссылку или выберите .torrent файл.";
+    player_choose_torrent:   "Paste a magnet link or choose a .torrent file." , "Вставьте magnet-ссылку или выберите .torrent файл.";
     player_uploading_files:  "Uploading files..."              , "Загружаю файлы...";
     player_upload_complete:  "Upload complete. Files are queued for processing." , "Загрузка завершена. Файлы поставлены в обработку.";
     player_upload_failed:    "Upload failed"                   , "Загрузка не удалась";
@@ -504,8 +569,8 @@ translations! {
     player_all_files_selected: "All files are selected by default. Clear or adjust the tree before download." , "Все файлы выбраны по умолчанию. Перед скачиванием можно очистить или изменить выбор.";
     player_opening_saved_torrent: "Opening saved torrent..."   , "Открываю сохранённый торрент...";
     player_saved_torrent_opened: "Saved torrent opened. Adjust files or resume download." , "Сохранённый торрент открыт. Можно изменить файлы или продолжить скачивание.";
-    player_remove_torrent_confirm: "Remove this torrent from the client list? Downloaded files will stay on disk." , "Удалить этот торрент из списка клиента? Скачанные файлы останутся на диске.";
-    player_torrent_removed:  "Torrent removed from the client list." , "Торрент удалён из списка клиента.";
+    player_remove_torrent_confirm: "Remove this torrent from history? Downloaded files will stay on disk." , "Удалить этот торрент из истории? Скачанные файлы останутся на диске.";
+    player_torrent_removed:  "Torrent removed from history."   , "Торрент удалён из истории.";
     player_select_one_file:  "Select at least one file."       , "Выберите хотя бы один файл.";
     player_starting_download: "Starting download..."           , "Запускаю скачивание...";
     player_download_started: "Download started. Files will move to inbox when complete." , "Скачивание началось. После завершения файлы будут перенесены во входящие.";
@@ -516,6 +581,6 @@ translations! {
     player_pause_failed:     "Pause failed"                    , "Не удалось поставить на паузу";
     player_load_torrents_failed: "Could not load torrents"     , "Не удалось загрузить торренты";
     player_open_torrent_failed: "Could not open torrent"       , "Не удалось открыть торрент";
-    player_delete_torrent_failed: "Could not delete torrent"   , "Не удалось удалить торрент";
+    player_delete_torrent_failed: "Could not remove torrent from history" , "Не удалось удалить торрент из истории";
     player_load_ai_queue_failed: "Could not load AI queue"     , "Не удалось загрузить очередь ИИ";
 }

src/jobs/inbox_process.rs

@@ -988,23 +988,59 @@ pub async fn finalize_approved(
             })?
     };
 
-    let media_file = MediaFile::create(
-        db,
-        "audio",
-        &storage_path,
-        original_filename,
-        mime_type,
-        file_size,
-        sha256,
-        Some(ext),
-        audio_bitrate,
-        audio_sample_rate,
-        audio_bit_depth,
-        uploaded_by_user_id,
-        Some(uploader_name),
+    let reusable_media_id: Option<i64> = sqlx::query_scalar(
+        r#"SELECT media.id
+             FROM furumusic__media_file media
+            WHERE media.file_type = 'audio'
+              AND media.file_path = $1
+              AND media.sha256_hash = $2
+              AND NOT EXISTS (
+                    SELECT 1 FROM furumusic__track track
+                     WHERE track.audio_file_id = media.id OR track.cover_file_id = media.id
+              )
+              AND NOT EXISTS (
+                    SELECT 1 FROM furumusic__release release
+                     WHERE release.cover_file_id = media.id
+              )
+              AND NOT EXISTS (
+                    SELECT 1 FROM furumusic__artist artist
+                     WHERE artist.image_file_id = media.id
+              )
+              AND NOT EXISTS (
+                    SELECT 1 FROM furumusic__playlist playlist
+                     WHERE playlist.cover_file_id = media.id
+              )
+            ORDER BY media.id
+            LIMIT 1"#,
     )
-    .await
-    .map_err(|e| anyhow::anyhow!("failed to create media file: {e}"))?;
+    .bind(&storage_path)
+    .bind(sha256)
+    .fetch_optional(pool)
+    .await?;
+    let media_file = if let Some(media_file_id) = reusable_media_id {
+        MediaFile::get_by_id(db, media_file_id)
+            .await
+            .map_err(|error| anyhow::anyhow!("failed to load reusable media file: {error}"))?
+            .ok_or_else(|| anyhow::anyhow!("reusable media file disappeared"))?
+    } else {
+        MediaFile::create(
+            db,
+            "audio",
+            &storage_path,
+            original_filename,
+            mime_type,
+            file_size,
+            sha256,
+            Some(ext),
+            audio_bitrate,
+            audio_sample_rate,
+            audio_bit_depth,
+            uploaded_by_user_id,
+            Some(uploader_name),
+        )
+        .await
+        .map_err(|e| anyhow::anyhow!("failed to create media file: {e}"))?
+    };
 
     let track = Track::create(
         db,
@@ -1020,6 +1056,35 @@ pub async fn finalize_approved(
     .await
     .map_err(|e| anyhow::anyhow!("failed to create track: {e}"))?;
 
+    if let Err(error) = sqlx::query(
+        r#"INSERT INTO furumusic__youtube_import_media (item_id, media_file_id)
+           SELECT DISTINCT item.id, $1
+             FROM furumusic__youtube_download_item item
+             JOIN furumusic__pending_review review
+               ON item.inbox_path IS NOT NULL
+              AND (review.input_path = item.inbox_path
+                   OR left(review.input_path, length(item.inbox_path) + 1)
+                      = item.inbox_path || '/')
+            WHERE review.context_json IS NOT NULL
+              AND substring(
+                      review.context_json
+                      from '"sha256"[[:space:]]*:[[:space:]]*"([0-9a-fA-F]{64})"'
+                  ) = $2
+           ON CONFLICT (item_id, media_file_id) DO NOTHING"#,
+    )
+    .bind(media_file.id_val())
+    .bind(sha256)
+    .execute(pool)
+    .await
+    {
+        tracing::warn!(
+            track_id = track.id_val(),
+            media_file_id = media_file.id_val(),
+            error = %error,
+            "failed to link imported media to its YouTube download item"
+        );
+    }
+
     TrackArtist::create(db, track.id_val(), artist.id_val(), "main", 0)
         .await
         .map_err(|e| anyhow::anyhow!("failed to link track-artist: {e}"))?;

src/lastfm.rs

@@ -447,17 +447,17 @@ async fn fetch_pending_scrobbles(
                   o.duration_seconds,
                   o.attempt_count,
                   a.session_key::text AS session_key,
-                  t.title::text AS title,
-                  r.title::text AS album_title,
+                  COALESCE(o.track_title, t.title::text) AS title,
+                  COALESCE(o.album_title, r.title::text) AS album_title,
                   t.track_number,
-                  (
+                  COALESCE(o.artist_name, (
                     SELECT ar.name::text
                       FROM furumusic__track_artist ta
                       JOIN furumusic__artist ar ON ar.id = ta.artist_id
                      WHERE ta.track_id = t.id AND ta.role <> 'featuring'
                      ORDER BY ta.position
                      LIMIT 1
-                  ) AS artist_name,
+                  )) AS artist_name,
                   (
                     SELECT ar.name::text
                       FROM furumusic__release_artist ra
@@ -468,7 +468,7 @@ async fn fetch_pending_scrobbles(
                   ) AS album_artist_name
              FROM furumusic__lastfm_scrobble_outbox o
              JOIN furumusic__lastfm_account a ON a.user_id = o.user_id
-             JOIN furumusic__track t ON t.id = o.track_id
+             LEFT JOIN furumusic__track t ON t.id = o.track_id
              LEFT JOIN furumusic__release r ON r.id = t.release_id
             WHERE o.user_id = $1
               AND o.status IN ('pending', 'retry')

src/library_cleanup.rs

@@ -0,0 +1,813 @@
+use std::collections::HashSet;
+use std::io::ErrorKind;
+use std::path::PathBuf;
+
+use anyhow::{Context, bail};
+use sqlx::{FromRow, PgPool, Postgres, Transaction};
+use uuid::Uuid;
+
+#[derive(Debug, FromRow)]
+struct MediaFileRow {
+    id: i64,
+    file_type: String,
+    file_path: String,
+    sha256_hash: String,
+}
+
+#[derive(Debug, FromRow)]
+struct PlaybackStateRow {
+    id: i64,
+    current_track_id: Option<i64>,
+    position_ms: i32,
+    queue_json: String,
+    queue_position: i32,
+}
+
+#[derive(Debug)]
+struct QuarantinedFile {
+    original: PathBuf,
+    quarantined: PathBuf,
+}
+
+#[derive(Debug, Default)]
+struct Quarantine {
+    root: Option<PathBuf>,
+    files: Vec<QuarantinedFile>,
+}
+
+pub async fn delete_tracks(
+    pool: &PgPool,
+    requested_track_ids: &[i64],
+    storage_dir: &str,
+) -> anyhow::Result<u64> {
+    delete_scope(pool, requested_track_ids, &[], storage_dir).await
+}
+
+pub async fn delete_releases(
+    pool: &PgPool,
+    requested_release_ids: &[i64],
+    storage_dir: &str,
+) -> anyhow::Result<u64> {
+    let mut transaction = pool.begin().await?;
+    let release_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__release WHERE id = ANY($1) ORDER BY id FOR UPDATE",
+    )
+    .bind(requested_release_ids)
+    .fetch_all(&mut *transaction)
+    .await?;
+    if release_ids.is_empty() {
+        transaction.rollback().await?;
+        return Ok(0);
+    }
+    let track_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__track WHERE release_id = ANY($1) ORDER BY id FOR UPDATE",
+    )
+    .bind(&release_ids)
+    .fetch_all(&mut *transaction)
+    .await?;
+    delete_locked_scope(transaction, track_ids, release_ids, storage_dir, true).await
+}
+
+#[derive(Debug)]
+pub struct ReleaseMergeTrack {
+    pub id: i64,
+    pub track_number: Option<i32>,
+    pub disc_number: Option<i32>,
+}
+
+#[derive(Debug)]
+pub struct ReleaseMergeSpec {
+    pub release_ids: Vec<i64>,
+    pub target_release_id: i64,
+    pub title: String,
+    pub title_sort: String,
+    pub release_type: String,
+    pub year: Option<i32>,
+    pub hidden: bool,
+    pub cover_file_id: Option<i64>,
+    pub artist_ids: Vec<i64>,
+    pub tracks: Vec<ReleaseMergeTrack>,
+}
+
+#[derive(Debug)]
+pub struct ReleaseMergeResult {
+    pub merged_releases: u64,
+    pub moved_tracks: u64,
+}
+
+/// Merge several releases into one while preserving their tracks and media.
+///
+/// Source cover files are quarantined before the database transaction commits,
+/// just like normal library deletion. The cover selected for the destination
+/// and any media still referenced elsewhere are retained.
+pub async fn merge_releases(
+    pool: &PgPool,
+    mut spec: ReleaseMergeSpec,
+    storage_dir: &str,
+) -> anyhow::Result<ReleaseMergeResult> {
+    spec.release_ids.retain(|id| *id > 0);
+    spec.release_ids.sort_unstable();
+    spec.release_ids.dedup();
+    if spec.release_ids.len() < 2 {
+        bail!("select at least two releases to merge");
+    }
+    if !spec.release_ids.contains(&spec.target_release_id) {
+        bail!("destination release must be part of the selection");
+    }
+
+    let mut transaction = pool.begin().await?;
+    let locked_release_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__release WHERE id = ANY($1) ORDER BY id FOR UPDATE",
+    )
+    .bind(&spec.release_ids)
+    .fetch_all(&mut *transaction)
+    .await?;
+    if locked_release_ids != spec.release_ids {
+        bail!("one or more selected releases no longer exist; reopen the merge wizard");
+    }
+    let original_target_cover: Option<i64> =
+        sqlx::query_scalar("SELECT cover_file_id FROM furumusic__release WHERE id = $1")
+            .bind(spec.target_release_id)
+            .fetch_one(&mut *transaction)
+            .await?;
+
+    let source_release_ids = spec
+        .release_ids
+        .iter()
+        .copied()
+        .filter(|id| *id != spec.target_release_id)
+        .collect::<Vec<_>>();
+    let locked_track_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__track WHERE release_id = ANY($1) ORDER BY id FOR UPDATE",
+    )
+    .bind(&spec.release_ids)
+    .fetch_all(&mut *transaction)
+    .await?;
+    let mut requested_track_ids = spec.tracks.iter().map(|track| track.id).collect::<Vec<_>>();
+    requested_track_ids.sort_unstable();
+    if requested_track_ids.windows(2).any(|ids| ids[0] == ids[1]) {
+        bail!("the merge track list contains duplicates");
+    }
+    if requested_track_ids != locked_track_ids {
+        bail!("the selected releases changed; reopen the merge wizard before merging");
+    }
+
+    if let Some(cover_file_id) = spec.cover_file_id {
+        let valid_cover: Option<i64> = sqlx::query_scalar(
+            r#"SELECT r.cover_file_id
+                 FROM furumusic__release r
+                 JOIN furumusic__media_file mf ON mf.id = r.cover_file_id
+                WHERE r.id = ANY($1)
+                  AND r.cover_file_id = $2
+                  AND mf.file_type = 'cover_art'
+                LIMIT 1"#,
+        )
+        .bind(&spec.release_ids)
+        .bind(cover_file_id)
+        .fetch_optional(&mut *transaction)
+        .await?;
+        if valid_cover.is_none() {
+            bail!("selected cover does not belong to one of the merged releases");
+        }
+    }
+
+    let mut seen_artist_ids = HashSet::new();
+    spec.artist_ids
+        .retain(|id| *id > 0 && seen_artist_ids.insert(*id));
+    if !spec.artist_ids.is_empty() {
+        let existing_artist_ids: Vec<i64> =
+            sqlx::query_scalar("SELECT id FROM furumusic__artist WHERE id = ANY($1) ORDER BY id")
+                .bind(&spec.artist_ids)
+                .fetch_all(&mut *transaction)
+                .await?;
+        let mut requested_artist_ids = spec.artist_ids.clone();
+        requested_artist_ids.sort_unstable();
+        if existing_artist_ids != requested_artist_ids {
+            bail!("one or more selected artists no longer exist");
+        }
+    }
+
+    let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
+    let total_discs = spec
+        .tracks
+        .iter()
+        .filter_map(|track| track.disc_number)
+        .max();
+    sqlx::query(
+        r#"UPDATE furumusic__release
+              SET title = $2, title_sort = $3, release_type = $4, year = $5,
+                  cover_file_id = $6, total_tracks = $7, total_discs = $8,
+                  is_hidden = $9, model_name = NULL, updated_at = $10
+            WHERE id = $1"#,
+    )
+    .bind(spec.target_release_id)
+    .bind(&spec.title)
+    .bind(&spec.title_sort)
+    .bind(&spec.release_type)
+    .bind(spec.year)
+    .bind(spec.cover_file_id)
+    .bind(i32::try_from(spec.tracks.len()).unwrap_or(i32::MAX))
+    .bind(total_discs)
+    .bind(spec.hidden)
+    .bind(&now)
+    .execute(&mut *transaction)
+    .await?;
+
+    sqlx::query("DELETE FROM furumusic__release_artist WHERE release_id = $1")
+        .bind(spec.target_release_id)
+        .execute(&mut *transaction)
+        .await?;
+    for (position, artist_id) in spec.artist_ids.iter().enumerate() {
+        sqlx::query(
+            "INSERT INTO furumusic__release_artist (release_id, artist_id, position) VALUES ($1, $2, $3)",
+        )
+        .bind(spec.target_release_id)
+        .bind(*artist_id)
+        .bind(i32::try_from(position).unwrap_or(i32::MAX))
+        .execute(&mut *transaction)
+        .await?;
+    }
+
+    for track in &spec.tracks {
+        sqlx::query(
+            r#"UPDATE furumusic__track
+                  SET release_id = $1, track_number = $2, disc_number = $3,
+                      updated_at = $4
+                WHERE id = $5"#,
+        )
+        .bind(spec.target_release_id)
+        .bind(track.track_number)
+        .bind(track.disc_number)
+        .bind(&now)
+        .bind(track.id)
+        .execute(&mut *transaction)
+        .await?;
+    }
+
+    sqlx::query(
+        r#"INSERT INTO furumusic__entity_genre_tag
+                  (entity_kind, entity_id, genre_id, source, weight, updated_at)
+            SELECT 'release', $1, genre_id, source, weight, $3
+              FROM furumusic__entity_genre_tag
+             WHERE entity_kind = 'release' AND entity_id = ANY($2)
+            ON CONFLICT (entity_kind, entity_id, genre_id, source) DO UPDATE
+                SET weight = GREATEST(furumusic__entity_genre_tag.weight, EXCLUDED.weight),
+                    updated_at = EXCLUDED.updated_at"#,
+    )
+    .bind(spec.target_release_id)
+    .bind(&spec.release_ids)
+    .bind(&now)
+    .execute(&mut *transaction)
+    .await?;
+
+    let extra_media_ids = original_target_cover.into_iter().collect::<Vec<_>>();
+    let media_files = deletable_media_files_with_extra(
+        &mut transaction,
+        &[],
+        &source_release_ids,
+        &extra_media_ids,
+    )
+    .await?;
+    let quarantine = match quarantine_media_files(storage_dir, &media_files).await {
+        Ok(quarantine) => quarantine,
+        Err(error) => {
+            transaction.rollback().await?;
+            return Err(error);
+        }
+    };
+    let deletion = delete_database_rows(
+        &mut transaction,
+        &[],
+        &source_release_ids,
+        &media_files,
+        true,
+    )
+    .await;
+    if let Err(error) = deletion {
+        transaction.rollback().await?;
+        restore_quarantine(&quarantine).await;
+        return Err(error);
+    }
+    if let Err(error) = transaction.commit().await {
+        restore_quarantine(&quarantine).await;
+        return Err(error.into());
+    }
+    purge_quarantine(&quarantine).await;
+    remove_empty_storage_parents(storage_dir, &quarantine.files).await;
+
+    Ok(ReleaseMergeResult {
+        merged_releases: u64::try_from(spec.release_ids.len()).unwrap_or(u64::MAX),
+        moved_tracks: u64::try_from(spec.tracks.len()).unwrap_or(u64::MAX),
+    })
+}
+
+async fn delete_scope(
+    pool: &PgPool,
+    requested_track_ids: &[i64],
+    release_ids: &[i64],
+    storage_dir: &str,
+) -> anyhow::Result<u64> {
+    let mut transaction = pool.begin().await?;
+    let track_ids: Vec<i64> = sqlx::query_scalar(
+        "SELECT id FROM furumusic__track WHERE id = ANY($1) ORDER BY id FOR UPDATE",
+    )
+    .bind(requested_track_ids)
+    .fetch_all(&mut *transaction)
+    .await?;
+    if track_ids.is_empty() {
+        transaction.rollback().await?;
+        return Ok(0);
+    }
+    delete_locked_scope(
+        transaction,
+        track_ids,
+        release_ids.to_vec(),
+        storage_dir,
+        false,
+    )
+    .await
+}
+
+async fn delete_locked_scope(
+    mut transaction: Transaction<'_, Postgres>,
+    track_ids: Vec<i64>,
+    release_ids: Vec<i64>,
+    storage_dir: &str,
+    delete_release_rows: bool,
+) -> anyhow::Result<u64> {
+    let media_files = deletable_media_files(&mut transaction, &track_ids, &release_ids).await?;
+    let quarantine = match quarantine_media_files(storage_dir, &media_files).await {
+        Ok(quarantine) => quarantine,
+        Err(error) => {
+            transaction.rollback().await?;
+            return Err(error);
+        }
+    };
+
+    let deletion = delete_database_rows(
+        &mut transaction,
+        &track_ids,
+        &release_ids,
+        &media_files,
+        delete_release_rows,
+    )
+    .await;
+    let affected = match deletion {
+        Ok(affected) => affected,
+        Err(error) => {
+            transaction.rollback().await?;
+            restore_quarantine(&quarantine).await;
+            return Err(error);
+        }
+    };
+
+    if let Err(error) = transaction.commit().await {
+        restore_quarantine(&quarantine).await;
+        return Err(error.into());
+    }
+    purge_quarantine(&quarantine).await;
+    remove_empty_storage_parents(storage_dir, &quarantine.files).await;
+    Ok(affected)
+}
+
+async fn deletable_media_files(
+    transaction: &mut Transaction<'_, Postgres>,
+    track_ids: &[i64],
+    release_ids: &[i64],
+) -> anyhow::Result<Vec<MediaFileRow>> {
+    deletable_media_files_with_extra(transaction, track_ids, release_ids, &[]).await
+}
+
+async fn deletable_media_files_with_extra(
+    transaction: &mut Transaction<'_, Postgres>,
+    track_ids: &[i64],
+    release_ids: &[i64],
+    extra_media_ids: &[i64],
+) -> anyhow::Result<Vec<MediaFileRow>> {
+    Ok(sqlx::query_as(
+        r#"WITH seed_media(id) AS (
+               SELECT audio_file_id FROM furumusic__track WHERE id = ANY($1)
+               UNION
+               SELECT cover_file_id FROM furumusic__track
+                WHERE id = ANY($1) AND cover_file_id IS NOT NULL
+               UNION
+               SELECT cover_file_id FROM furumusic__release
+                WHERE id = ANY($2) AND cover_file_id IS NOT NULL
+               UNION
+               SELECT UNNEST($3::bigint[])
+           ), candidate_media(id) AS (
+               SELECT id FROM seed_media
+               UNION
+               SELECT duplicate.id
+                 FROM furumusic__media_file duplicate
+                 JOIN furumusic__media_file seed
+                   ON duplicate.file_path = seed.file_path
+                  AND duplicate.sha256_hash = seed.sha256_hash
+                 JOIN seed_media ON seed_media.id = seed.id
+           )
+           SELECT mf.id, mf.file_type::text AS file_type, mf.file_path,
+                  mf.sha256_hash::text AS sha256_hash
+             FROM furumusic__media_file mf
+             JOIN candidate_media candidate ON candidate.id = mf.id
+            WHERE NOT EXISTS (
+                      SELECT 1
+                        FROM furumusic__track track
+                        JOIN furumusic__media_file linked
+                          ON linked.id = track.audio_file_id
+                          OR linked.id = track.cover_file_id
+                       WHERE linked.file_path = mf.file_path
+                         AND linked.sha256_hash = mf.sha256_hash
+                         AND NOT (track.id = ANY($1))
+                  )
+              AND NOT EXISTS (
+                      SELECT 1
+                        FROM furumusic__release release
+                        JOIN furumusic__media_file linked
+                          ON linked.id = release.cover_file_id
+                       WHERE linked.file_path = mf.file_path
+                         AND linked.sha256_hash = mf.sha256_hash
+                         AND NOT (release.id = ANY($2))
+                  )
+              AND NOT EXISTS (
+                      SELECT 1
+                        FROM furumusic__artist artist
+                        JOIN furumusic__media_file linked
+                          ON linked.id = artist.image_file_id
+                       WHERE linked.file_path = mf.file_path
+                         AND linked.sha256_hash = mf.sha256_hash
+                  )
+              AND NOT EXISTS (
+                      SELECT 1
+                        FROM furumusic__playlist playlist
+                        JOIN furumusic__media_file linked
+                          ON linked.id = playlist.cover_file_id
+                       WHERE linked.file_path = mf.file_path
+                         AND linked.sha256_hash = mf.sha256_hash
+                  )
+            ORDER BY mf.id
+            FOR UPDATE OF mf"#,
+    )
+    .bind(track_ids)
+    .bind(release_ids)
+    .bind(extra_media_ids)
+    .fetch_all(&mut **transaction)
+    .await?)
+}
+
+async fn quarantine_media_files(
+    storage_dir: &str,
+    media_files: &[MediaFileRow],
+) -> anyhow::Result<Quarantine> {
+    if media_files.is_empty() {
+        return Ok(Quarantine::default());
+    }
+    if storage_dir.trim().is_empty() {
+        bail!("agent_storage_dir is not configured; refusing to leave deleted tracks on disk");
+    }
+
+    let storage_root = crate::media_paths::resolve_config_path_buf(storage_dir);
+    if storage_root.parent().is_none() {
+        bail!("agent_storage_dir must not be a filesystem root");
+    }
+    let quarantine_root = storage_root
+        .join(".furumusic-trash")
+        .join(Uuid::new_v4().to_string());
+    let mut quarantine = Quarantine {
+        root: Some(quarantine_root.clone()),
+        files: Vec::new(),
+    };
+    let mut seen = HashSet::new();
+    let result: anyhow::Result<()> =
+        async {
+            for media in media_files {
+                let original = checked_storage_path(storage_dir, &media.file_path)?;
+                let mut paths = vec![original.clone()];
+                if media.file_type == "cover_art" {
+                    paths.extend(crate::agent::cover_variants::COVER_VARIANTS.iter().map(
+                        |variant| crate::agent::cover_variants::variant_path(&original, *variant),
+                    ));
+                }
+
+                for (index, path) in paths.into_iter().enumerate() {
+                    if !seen.insert(path.clone()) {
+                        continue;
+                    }
+                    match tokio::fs::symlink_metadata(&path).await {
+                        Ok(metadata) if metadata.is_file() || metadata.file_type().is_symlink() => {
+                        }
+                        Ok(_) => bail!("media path is not a regular file: {}", path.display()),
+                        Err(error) if error.kind() == ErrorKind::NotFound => continue,
+                        Err(error) => return Err(error.into()),
+                    }
+                    tokio::fs::create_dir_all(&quarantine_root).await?;
+                    let extension = path
+                        .extension()
+                        .and_then(|value| value.to_str())
+                        .unwrap_or("bin");
+                    let quarantined = quarantine_root.join(format!(
+                        "{}-{index}-{}.{}",
+                        media.id,
+                        Uuid::new_v4(),
+                        extension
+                    ));
+                    tokio::fs::rename(&path, &quarantined)
+                        .await
+                        .with_context(|| format!("failed to remove {}", path.display()))?;
+                    quarantine.files.push(QuarantinedFile {
+                        original: path,
+                        quarantined,
+                    });
+                }
+            }
+            Ok(())
+        }
+        .await;
+    match result {
+        Ok(()) => Ok(quarantine),
+        Err(error) => {
+            restore_quarantine(&quarantine).await;
+            Err(error)
+        }
+    }
+}
+
+fn checked_storage_path(storage_dir: &str, stored_path: &str) -> anyhow::Result<PathBuf> {
+    let resolved = crate::media_paths::resolve_media_file_path(storage_dir, stored_path);
+    crate::media_paths::path_for_root(storage_dir, &resolved).with_context(|| {
+        format!(
+            "refusing to delete media outside agent_storage_dir: {}",
+            resolved.display()
+        )
+    })?;
+    Ok(resolved)
+}
+
+async fn restore_quarantine(quarantine: &Quarantine) {
+    for file in quarantine.files.iter().rev() {
+        if let Some(parent) = file.original.parent() {
+            let _ = tokio::fs::create_dir_all(parent).await;
+        }
+        let _ = tokio::fs::rename(&file.quarantined, &file.original).await;
+    }
+    if let Some(root) = &quarantine.root {
+        let _ = tokio::fs::remove_dir_all(root).await;
+    }
+}
+
+async fn purge_quarantine(quarantine: &Quarantine) {
+    if let Some(root) = &quarantine.root
+        && let Err(error) = tokio::fs::remove_dir_all(root).await
+        && error.kind() != ErrorKind::NotFound
+    {
+        tracing::warn!(path = %root.display(), error = %error, "failed to purge deleted media quarantine");
+    }
+    if let Some(parent) = quarantine.root.as_deref().and_then(|root| root.parent()) {
+        let _ = tokio::fs::remove_dir(parent).await;
+    }
+}
+
+async fn remove_empty_storage_parents(storage_dir: &str, files: &[QuarantinedFile]) {
+    let storage_root = crate::media_paths::resolve_config_path_buf(storage_dir);
+    let mut seen = HashSet::new();
+    for file in files {
+        let mut current = file.original.parent();
+        while let Some(directory) = current {
+            if directory == storage_root || !directory.starts_with(&storage_root) {
+                break;
+            }
+            if !seen.insert(directory.to_path_buf()) {
+                break;
+            }
+            match tokio::fs::remove_dir(directory).await {
+                Ok(()) => current = directory.parent(),
+                Err(_) => break,
+            }
+        }
+    }
+}
+
+async fn delete_database_rows(
+    transaction: &mut Transaction<'_, Postgres>,
+    track_ids: &[i64],
+    release_ids: &[i64],
+    media_files: &[MediaFileRow],
+    delete_release_rows: bool,
+) -> anyhow::Result<u64> {
+    cleanup_playback_states(transaction, track_ids).await?;
+
+    for table in [
+        "furumusic__playlist_track",
+        "furumusic__user_liked_track",
+        "furumusic__play_history",
+        "furumusic__track_popularity_history",
+        "furumusic__lastfm_scrobble_outbox",
+        "furumusic__track_genre",
+        "furumusic__track_artist",
+        "furumusic__track_embedding",
+    ] {
+        let query = format!("DELETE FROM {table} WHERE track_id = ANY($1)");
+        sqlx::query(&query)
+            .bind(track_ids)
+            .execute(&mut **transaction)
+            .await?;
+    }
+    for table in [
+        "furumusic__entity_genre_tag",
+        "furumusic__external_metadata_id",
+        "furumusic__artwork_lookup_state",
+    ] {
+        let query =
+            format!("DELETE FROM {table} WHERE entity_kind = 'track' AND entity_id = ANY($1)");
+        sqlx::query(&query)
+            .bind(track_ids)
+            .execute(&mut **transaction)
+            .await?;
+    }
+    for table in [
+        "furumusic__fed_state_like",
+        "furumusic__fed_state_playlist_item",
+        "furumusic__track_ref",
+        "furumusic__listen_event",
+    ] {
+        let query =
+            format!("UPDATE {table} SET local_track_id = NULL WHERE local_track_id = ANY($1)");
+        sqlx::query(&query)
+            .bind(track_ids)
+            .execute(&mut **transaction)
+            .await?;
+    }
+
+    let tracks_deleted = sqlx::query("DELETE FROM furumusic__track WHERE id = ANY($1)")
+        .bind(track_ids)
+        .execute(&mut **transaction)
+        .await?
+        .rows_affected();
+
+    if delete_release_rows {
+        for table in [
+            "furumusic__entity_genre_tag",
+            "furumusic__external_metadata_id",
+            "furumusic__artwork_lookup_state",
+        ] {
+            let query = format!(
+                "DELETE FROM {table} WHERE entity_kind = 'release' AND entity_id = ANY($1)"
+            );
+            sqlx::query(&query)
+                .bind(release_ids)
+                .execute(&mut **transaction)
+                .await?;
+        }
+        sqlx::query("DELETE FROM furumusic__release_artist WHERE release_id = ANY($1)")
+            .bind(release_ids)
+            .execute(&mut **transaction)
+            .await?;
+        sqlx::query("DELETE FROM furumusic__release WHERE id = ANY($1)")
+            .bind(release_ids)
+            .execute(&mut **transaction)
+            .await?;
+    }
+
+    let media_ids: Vec<i64> = media_files.iter().map(|media| media.id).collect();
+    if !media_ids.is_empty() {
+        let media_hashes: Vec<String> = media_files
+            .iter()
+            .map(|media| media.sha256_hash.clone())
+            .collect();
+        sqlx::query(
+            r#"UPDATE furumusic__youtube_download_item
+                  SET status = 'failed', progress_percent = 0,
+                      downloaded_bytes = 0, total_bytes = NULL,
+                      speed_bytes_per_sec = NULL, eta_seconds = NULL,
+                      error = 'Imported library files were deleted; this source can be imported again',
+                      completed_at = NULL, updated_at = $2
+                WHERE id IN (
+                    SELECT item_id
+                      FROM furumusic__youtube_import_media
+                     WHERE media_file_id = ANY($1)
+                )"#,
+        )
+        .bind(&media_ids)
+        .bind(chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string())
+        .execute(&mut **transaction)
+        .await?;
+
+        let review_ids: Vec<i64> = sqlx::query_scalar(
+            r#"SELECT id FROM furumusic__pending_review
+                WHERE context_json IS NOT NULL
+                  AND substring(
+                          context_json
+                          from '"sha256"[[:space:]]*:[[:space:]]*"([0-9a-fA-F]{64})"'
+                      ) = ANY($1)"#,
+        )
+        .bind(&media_hashes)
+        .fetch_all(&mut **transaction)
+        .await?;
+        if !review_ids.is_empty() {
+            sqlx::query(
+                "DELETE FROM furumusic__processing_stats WHERE pending_review_id = ANY($1)",
+            )
+            .bind(&review_ids)
+            .execute(&mut **transaction)
+            .await?;
+            sqlx::query("DELETE FROM furumusic__pending_review WHERE id = ANY($1)")
+                .bind(&review_ids)
+                .execute(&mut **transaction)
+                .await?;
+        }
+        sqlx::query(
+            "DELETE FROM furumusic__federation_content_id_cache WHERE media_file_id = ANY($1)",
+        )
+        .bind(&media_ids)
+        .execute(&mut **transaction)
+        .await?;
+        sqlx::query("DELETE FROM furumusic__media_file WHERE id = ANY($1)")
+            .bind(&media_ids)
+            .execute(&mut **transaction)
+            .await?;
+    }
+    Ok(if delete_release_rows {
+        u64::try_from(release_ids.len()).unwrap_or(u64::MAX)
+    } else {
+        tracks_deleted
+    })
+}
+
+async fn cleanup_playback_states(
+    transaction: &mut Transaction<'_, Postgres>,
+    track_ids: &[i64],
+) -> anyhow::Result<()> {
+    let deleted: HashSet<i64> = track_ids.iter().copied().collect();
+    let states: Vec<PlaybackStateRow> = sqlx::query_as(
+        "SELECT id, current_track_id, position_ms, queue_json, queue_position FROM furumusic__playback_state FOR UPDATE",
+    )
+    .fetch_all(&mut **transaction)
+    .await?;
+
+    for state in states {
+        let mut queue: Vec<i64> = serde_json::from_str(&state.queue_json).unwrap_or_default();
+        let original_queue = queue.clone();
+        queue.retain(|track_id| !deleted.contains(track_id));
+        let current_track_id = state.current_track_id.filter(|id| !deleted.contains(id));
+        if queue == original_queue && current_track_id == state.current_track_id {
+            continue;
+        }
+        let queue_position = current_track_id
+            .and_then(|current| queue.iter().position(|id| *id == current))
+            .map(|position| i32::try_from(position).unwrap_or(i32::MAX))
+            .unwrap_or_else(|| {
+                if queue.is_empty() {
+                    0
+                } else {
+                    state
+                        .queue_position
+                        .clamp(0, i32::try_from(queue.len() - 1).unwrap_or(i32::MAX))
+                }
+            });
+        let position_ms = if current_track_id.is_some() {
+            state.position_ms
+        } else {
+            0
+        };
+        let queue_json = serde_json::to_string(&queue)?;
+        sqlx::query(
+            r#"UPDATE furumusic__playback_state
+                  SET current_track_id = $2, position_ms = $3,
+                      queue_json = $4, queue_position = $5
+                WHERE id = $1"#,
+        )
+        .bind(state.id)
+        .bind(current_track_id)
+        .bind(position_ms)
+        .bind(queue_json)
+        .bind(queue_position)
+        .execute(&mut **transaction)
+        .await?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rejects_media_paths_outside_storage() {
+        assert!(checked_storage_path("/srv/music", "/etc/passwd").is_err());
+        assert!(checked_storage_path("/srv/music", "../outside.flac").is_err());
+        assert_eq!(
+            checked_storage_path("/srv/music", "Artist/Album/01.flac").unwrap(),
+            PathBuf::from("/srv/music/Artist/Album/01.flac")
+        );
+    }
+
+    #[test]
+    fn deleted_track_ids_are_removed_from_saved_queue() {
+        let deleted = HashSet::from([2_i64, 4]);
+        let mut queue = vec![1_i64, 2, 3, 4, 5];
+        queue.retain(|track_id| !deleted.contains(track_id));
+        assert_eq!(queue, vec![1, 3, 5]);
+        let serialized: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&queue).unwrap()).unwrap();
+        assert_eq!(serialized, serde_json::json!([1, 3, 5]));
+    }
+}

src/local_uploads.rs

@@ -0,0 +1,259 @@
+use std::collections::HashMap;
+
+use anyhow::{Context, bail};
+use serde::Serialize;
+use sqlx::{FromRow, PgPool};
+
+const LOCAL_UPLOAD_LIST_LIMIT: i64 = 100;
+
+#[derive(Debug, Clone, Serialize)]
+pub struct LocalUploadDto {
+    pub id: String,
+    pub filename: String,
+    pub size_bytes: u64,
+    pub status: String,
+    pub error: Option<String>,
+    pub created_at: String,
+    pub updated_at: String,
+    pub completed_at: Option<String>,
+}
+
+#[derive(Debug, Clone, FromRow)]
+struct LocalUploadRow {
+    id: String,
+    user_id: i64,
+    filename: String,
+    size_bytes: i64,
+    status: String,
+    inbox_path: String,
+    error: Option<String>,
+    created_at: String,
+    updated_at: String,
+    completed_at: Option<String>,
+}
+
+impl LocalUploadRow {
+    fn dto(&self) -> LocalUploadDto {
+        LocalUploadDto {
+            id: self.id.clone(),
+            filename: self.filename.clone(),
+            size_bytes: u64::try_from(self.size_bytes).unwrap_or(0),
+            status: self.status.clone(),
+            error: self.error.clone(),
+            created_at: self.created_at.clone(),
+            updated_at: self.updated_at.clone(),
+            completed_at: self.completed_at.clone(),
+        }
+    }
+}
+
+pub async fn create(
+    pool: &PgPool,
+    id: &str,
+    user_id: i64,
+    filename: &str,
+    size_bytes: u64,
+    inbox_path: &str,
+) -> anyhow::Result<()> {
+    let now = now_string();
+    sqlx::query(
+        r#"INSERT INTO furumusic__local_upload
+              (id, user_id, filename, size_bytes, status, inbox_path, error,
+               created_at, updated_at, completed_at)
+           VALUES ($1, $2, $3, $4, 'uploading', $5, NULL, $6, $6, NULL)"#,
+    )
+    .bind(id)
+    .bind(user_id)
+    .bind(filename)
+    .bind(i64::try_from(size_bytes).unwrap_or(i64::MAX))
+    .bind(inbox_path)
+    .bind(now)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+pub async fn mark_queued(pool: &PgPool, id: &str, user_id: i64) -> anyhow::Result<LocalUploadDto> {
+    update_status(pool, id, user_id, "queued", None).await?;
+    load(pool, user_id, id).await.map(|row| row.dto())
+}
+
+pub async fn mark_failed(pool: &PgPool, id: &str, user_id: i64, error: &str) -> anyhow::Result<()> {
+    update_status(pool, id, user_id, "failed", Some(error)).await
+}
+
+pub async fn list(
+    pool: &PgPool,
+    user_id: i64,
+    inbox_dir: &str,
+) -> anyhow::Result<Vec<LocalUploadDto>> {
+    sync_statuses(pool, user_id, inbox_dir).await?;
+    let rows: Vec<LocalUploadRow> = sqlx::query_as(
+        r#"SELECT id, user_id, filename, size_bytes, status, inbox_path, error,
+                  created_at, updated_at, completed_at
+           FROM furumusic__local_upload
+           WHERE user_id = $1
+           ORDER BY created_at DESC, id DESC
+           LIMIT $2"#,
+    )
+    .bind(user_id)
+    .bind(LOCAL_UPLOAD_LIST_LIMIT)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows.iter().map(LocalUploadRow::dto).collect())
+}
+
+pub async fn remove(pool: &PgPool, user_id: i64, id: &str) -> anyhow::Result<()> {
+    let result = sqlx::query("DELETE FROM furumusic__local_upload WHERE id = $1 AND user_id = $2")
+        .bind(id)
+        .bind(user_id)
+        .execute(pool)
+        .await?;
+    if result.rows_affected() == 0 {
+        bail!("file upload history entry not found");
+    }
+    Ok(())
+}
+
+async fn sync_statuses(pool: &PgPool, user_id: i64, inbox_dir: &str) -> anyhow::Result<()> {
+    let inbox_dir = inbox_dir.trim();
+    if inbox_dir.is_empty() {
+        bail!("agent_inbox_dir is not configured");
+    }
+    let inbox_root = crate::media_paths::resolve_config_path_buf(inbox_dir);
+    if !inbox_root.is_absolute() {
+        bail!("agent_inbox_dir must be an absolute path");
+    }
+
+    let rows: Vec<LocalUploadRow> = sqlx::query_as(
+        r#"SELECT id, user_id, filename, size_bytes, status, inbox_path, error,
+                  created_at, updated_at, completed_at
+           FROM furumusic__local_upload
+           WHERE user_id = $1 AND status <> 'complete'"#,
+    )
+    .bind(user_id)
+    .fetch_all(pool)
+    .await?;
+    if rows.is_empty() {
+        return Ok(());
+    }
+
+    let inbox_paths: Vec<String> = rows.iter().map(|row| row.inbox_path.clone()).collect();
+    let state_rows: Vec<(String, String, i64)> = sqlx::query_as(
+        r#"SELECT input_path, status::text, COUNT(*)
+           FROM furumusic__pending_review
+           WHERE input_path = ANY($1)
+           GROUP BY input_path, status"#,
+    )
+    .bind(&inbox_paths)
+    .fetch_all(pool)
+    .await?;
+    let mut states_by_path: HashMap<String, HashMap<String, i64>> = HashMap::new();
+    for (input_path, status, total) in state_rows {
+        states_by_path
+            .entry(input_path)
+            .or_default()
+            .insert(status, total);
+    }
+    let error_rows: Vec<(String, String)> = sqlx::query_as(
+        r#"SELECT DISTINCT ON (input_path) input_path, error_message
+           FROM furumusic__pending_review
+           WHERE input_path = ANY($1) AND status = 'failed'
+             AND error_message IS NOT NULL
+           ORDER BY input_path, id DESC"#,
+    )
+    .bind(&inbox_paths)
+    .fetch_all(pool)
+    .await?;
+    let errors_by_path: HashMap<String, String> = error_rows.into_iter().collect();
+
+    for row in rows {
+        let counts = states_by_path
+            .get(&row.inbox_path)
+            .cloned()
+            .unwrap_or_default();
+        let total: i64 = counts.values().sum();
+
+        let mut terminal_error = None;
+        let next = if total == 0 {
+            if matches!(row.status.as_str(), "uploading" | "failed" | "needs_review") {
+                continue;
+            }
+            let full_path = crate::media_paths::resolve_path_from_root(inbox_dir, &row.inbox_path);
+            if tokio::fs::try_exists(full_path).await.unwrap_or(false) {
+                "queued"
+            } else {
+                "complete"
+            }
+        } else if count(&counts, "processing") > 0 {
+            "ai_processing"
+        } else if count(&counts, "queued") > 0 {
+            "queued"
+        } else if count(&counts, "failed") > 0 {
+            terminal_error = errors_by_path.get(&row.inbox_path).cloned();
+            "failed"
+        } else if count(&counts, "pending") > 0 || count(&counts, "rejected") > 0 {
+            "needs_review"
+        } else if count(&counts, "approved") > 0 || count(&counts, "auto_approved") > 0 {
+            "complete"
+        } else {
+            "queued"
+        };
+
+        if row.status != next || row.error != terminal_error {
+            update_status(pool, &row.id, row.user_id, next, terminal_error.as_deref()).await?;
+        }
+    }
+    Ok(())
+}
+
+async fn update_status(
+    pool: &PgPool,
+    id: &str,
+    user_id: i64,
+    status: &str,
+    error: Option<&str>,
+) -> anyhow::Result<()> {
+    let now = now_string();
+    let completed_at =
+        matches!(status, "complete" | "failed" | "needs_review").then(|| now.clone());
+    sqlx::query(
+        r#"UPDATE furumusic__local_upload
+           SET status = $3, error = $4, updated_at = $5, completed_at = $6
+           WHERE id = $1 AND user_id = $2"#,
+    )
+    .bind(id)
+    .bind(user_id)
+    .bind(status)
+    .bind(error.map(trim_error))
+    .bind(&now)
+    .bind(completed_at)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+async fn load(pool: &PgPool, user_id: i64, id: &str) -> anyhow::Result<LocalUploadRow> {
+    sqlx::query_as(
+        r#"SELECT id, user_id, filename, size_bytes, status, inbox_path, error,
+                  created_at, updated_at, completed_at
+           FROM furumusic__local_upload WHERE id = $1 AND user_id = $2"#,
+    )
+    .bind(id)
+    .bind(user_id)
+    .fetch_optional(pool)
+    .await?
+    .context("file upload history entry not found")
+}
+
+fn count(counts: &HashMap<String, i64>, status: &str) -> i64 {
+    counts.get(status).copied().unwrap_or(0)
+}
+
+fn trim_error(value: &str) -> String {
+    value.chars().take(4_000).collect()
+}
+
+fn now_string() -> String {
+    chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string()
+}

src/main.rs

@@ -7,14 +7,18 @@ mod federation;
 mod i18n;
 mod jobs;
 mod lastfm;
+mod library_cleanup;
+mod local_uploads;
 mod media_paths;
 mod metrics;
 mod music;
 mod oidc;
 mod player;
 mod scheduler;
+mod similarity;
 mod torrents;
 mod user;
+mod youtube;
 
 use std::sync::Arc;
 
@@ -87,7 +91,13 @@ async fn index(
             return Ok(auth::redirect("/login"));
         }
     };
-    let template = player::PlayerPageTemplate { t: i18n.t };
+    let (config, _) = AppConfig::load_with_db(&db).await;
+    let template = player::PlayerPageTemplate {
+        t: i18n.t,
+        downloads_enabled: config.downloads_enabled,
+        torrent_downloads_enabled: config.downloads_enabled && config.torrent_downloads_enabled,
+        youtube_downloads_enabled: config.downloads_enabled && config.youtube_downloads_enabled,
+    };
     Html::new(template.render()?).into_response()
 }
 
@@ -567,6 +577,13 @@ impl Project for FuruProject {
             federation::handle().boot(&fed_config).await;
         });
 
+        // Embedding calculation is an independent, server-wide background
+        // service. It remains useful locally when federation is disabled.
+        let similarity_config = Arc::clone(&self.app_config);
+        tokio::spawn(async move {
+            similarity::handle().boot(&similarity_config).await;
+        });
+
         apps.register(cot::session::db::SessionApp::new());
         apps.register_with_views(
             FuruApp {

src/metrics.rs

@@ -841,6 +841,7 @@ const KNOWN_HTTP_ROUTES: &[&str] = &[
     "/admin/v2/api/library/item/image",
     "/admin/v2/api/library/item/upload-image",
     "/admin/v2/api/library/bulk",
+    "/admin/v2/api/library/releases/merge",
     "/admin/debug",
     "/admin/settings",
     "/admin/settings/probe",
@@ -884,10 +885,18 @@ const KNOWN_HTTP_ROUTES: &[&str] = &[
     "/api/player/lastfm/scrobble",
     "/api/player/agent-queue",
     "/api/player/offline/manifest",
+    "/api/player/youtube",
+    "/api/player/youtube/preview",
+    "/api/player/youtube/start",
+    "/api/player/youtube/{id}/retry",
+    "/api/player/youtube/{id}/cancel",
+    "/api/player/youtube/{id}",
+    "/api/player/uploads/local",
+    "/api/player/uploads/local/history",
+    "/api/player/uploads/local/history/{id}",
     "/api/player/torrents",
     "/api/player/torrents/session/{id}",
     "/api/player/torrents/preview",
-    "/api/player/uploads/local",
     "/api/player/uploads/tracks",
     "/api/player/uploads/tracks/{track_id}",
     "/api/player/uploads/bulk-tracks",
@@ -951,6 +960,22 @@ mod tests {
             known_http_route("/share/release/42"),
             Some("/share/release/{id}")
         );
+        assert_eq!(
+            known_http_route("/api/player/youtube/start"),
+            Some("/api/player/youtube/start")
+        );
+        assert_eq!(
+            known_http_route("/api/player/youtube/job-42/retry"),
+            Some("/api/player/youtube/{id}/retry")
+        );
+        assert_eq!(
+            known_http_route("/api/player/youtube/job-42/cancel"),
+            Some("/api/player/youtube/{id}/cancel")
+        );
+        assert_eq!(
+            known_http_route("/api/player/uploads/local/history/upload-42"),
+            Some("/api/player/uploads/local/history/{id}")
+        );
     }
 
     #[test]

src/music/mod.rs

@@ -1951,6 +1951,837 @@ pub mod db_migrations {
             &[Operation::custom(create_playlist_share_links).build()];
     }
 
+    #[cot::db::migrations::migration_op]
+    async fn create_fed_device_sync(ctx: migrations::MigrationContext<'_>) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+                    media_file_id BIGINT PRIMARY KEY,
+                    sha256_hash TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+                   ON furumusic__federation_content_id_cache (content_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device_identity (
+                    user_id BIGINT PRIMARY KEY,
+                    device_id TEXT NOT NULL UNIQUE,
+                    group_id TEXT NOT NULL,
+                    device_name TEXT NOT NULL,
+                    local_seq BIGINT NOT NULL DEFAULT 0,
+                    last_hlc_ms BIGINT NOT NULL DEFAULT 0,
+                    local_seeded_at_ms BIGINT NOT NULL DEFAULT 0,
+                    last_sync TEXT,
+                    last_error TEXT
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device (
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    name TEXT NOT NULL DEFAULT '',
+                    client_version TEXT NOT NULL DEFAULT '',
+                    protocol_version INTEGER NOT NULL DEFAULT 1,
+                    endpoint_id TEXT NOT NULL DEFAULT '',
+                    endpoint_ticket TEXT NOT NULL DEFAULT '',
+                    trusted_at_ms BIGINT,
+                    last_seen_ms BIGINT,
+                    revoked_at_ms BIGINT,
+                    revoked_by TEXT,
+                    revoke_cutoff_seq BIGINT,
+                    PRIMARY KEY (user_id, device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_fed_device_single_user
+                   ON furumusic__fed_device (device_id)
+                 WHERE trusted_at_ms IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_device_invite (
+                    invite_id TEXT PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    secret_hash TEXT NOT NULL,
+                    expires_at_ms BIGINT NOT NULL,
+                    created_at_ms BIGINT NOT NULL,
+                    used_at_ms BIGINT
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_pending_pairing (
+                    request_id TEXT PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    client_version TEXT NOT NULL,
+                    endpoint_id TEXT NOT NULL,
+                    endpoint_ticket TEXT NOT NULL,
+                    invite_id TEXT NOT NULL,
+                    created_at_ms BIGINT NOT NULL,
+                    answered_at_ms BIGINT,
+                    status TEXT NOT NULL,
+                    requester_group_id TEXT,
+                    requester_group_active_devices BIGINT NOT NULL DEFAULT 1,
+                    requester_group_devices_json TEXT NOT NULL DEFAULT '[]',
+                    use_requester_group BOOLEAN NOT NULL DEFAULT false
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_pending_pairing_user_status
+                   ON furumusic__fed_pending_pairing (user_id, status, created_at_ms DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_sync_ops (
+                    user_id BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    origin_device_id TEXT NOT NULL,
+                    seq BIGINT NOT NULL,
+                    kind TEXT NOT NULL,
+                    payload_json JSONB NOT NULL,
+                    hlc_ms BIGINT NOT NULL,
+                    received_at_ms BIGINT NOT NULL,
+                    tombstone BOOLEAN NOT NULL DEFAULT false,
+                    PRIMARY KEY (user_id, op_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_sync_ops_origin_seq
+                   ON furumusic__fed_sync_ops (user_id, origin_device_id, seq)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_sync_ops_tombstone
+                   ON furumusic__fed_sync_ops (user_id, tombstone)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_sync_vector (
+                    user_id BIGINT NOT NULL,
+                    device_id TEXT NOT NULL,
+                    max_seq BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_peer_ack (
+                    user_id BIGINT NOT NULL,
+                    peer_device_id TEXT NOT NULL,
+                    origin_device_id TEXT NOT NULL,
+                    max_seq BIGINT NOT NULL,
+                    updated_at_ms BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, peer_device_id, origin_device_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_like (
+                    user_id BIGINT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    liked BOOLEAN NOT NULL,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    fed_json JSONB,
+                    PRIMARY KEY (user_id, content_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_playlist (
+                    user_id BIGINT NOT NULL,
+                    playlist_id TEXT NOT NULL,
+                    local_playlist_id BIGINT,
+                    title TEXT NOT NULL,
+                    deleted BOOLEAN NOT NULL DEFAULT false,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    PRIMARY KEY (user_id, playlist_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_fed_state_playlist_local
+                   ON furumusic__fed_state_playlist (user_id, local_playlist_id)
+                 WHERE local_playlist_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_state_playlist_item (
+                    user_id BIGINT NOT NULL,
+                    playlist_id TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    present BOOLEAN NOT NULL DEFAULT true,
+                    position BIGINT NOT NULL DEFAULT 0,
+                    hlc_ms BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    fed_json JSONB,
+                    PRIMARY KEY (user_id, playlist_id, content_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_fed_state_playlist_item_playlist
+                   ON furumusic__fed_state_playlist_item
+                      (user_id, playlist_id, present, position)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__fed_playback_applied (
+                    user_id BIGINT NOT NULL,
+                    op_id TEXT NOT NULL,
+                    applied_at_ms BIGINT NOT NULL,
+                    PRIMARY KEY (user_id, op_id)
+                )",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0038CreateFedDeviceSync;
+
+    impl migrations::Migration for M0038CreateFedDeviceSync {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0038_create_fed_device_sync";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0037_create_playlist_share_links",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_fed_device_sync).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn ensure_federation_content_id_cache(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_content_id_cache (
+                    media_file_id BIGINT PRIMARY KEY,
+                    sha256_hash TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_furumusic_federation_content_id_cache_content_id
+                   ON furumusic__federation_content_id_cache (content_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0039EnsureFederationContentIdCache;
+
+    impl migrations::Migration for M0039EnsureFederationContentIdCache {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0039_ensure_federation_content_id_cache";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0038_create_fed_device_sync",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(ensure_federation_content_id_cache).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_content_addressed_music_refs(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        // A track reference is durable user-facing identity. `local_track_id`
+        // is availability, not identity: it may become non-NULL after a
+        // federated track is materialized without changing likes/playlists.
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__track_ref (
+                    id BIGSERIAL PRIMARY KEY,
+                    content_id TEXT NOT NULL UNIQUE,
+                    local_track_id BIGINT UNIQUE,
+                    title TEXT NOT NULL,
+                    release_title TEXT,
+                    year INTEGER,
+                    duration_seconds DOUBLE PRECISION,
+                    metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+                    metadata_authority TEXT NOT NULL DEFAULT 'local',
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_track_ref_local_track
+                   ON furumusic__track_ref (local_track_id)
+                 WHERE local_track_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__federation_track_source (
+                    track_ref_id BIGINT NOT NULL REFERENCES furumusic__track_ref(id)
+                        ON DELETE CASCADE,
+                    owner_peer_id TEXT NOT NULL,
+                    item_id TEXT NOT NULL,
+                    last_seen_ms BIGINT NOT NULL,
+                    metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+                    PRIMARY KEY (owner_peer_id, item_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_federation_track_source_ref
+                   ON furumusic__federation_track_source (track_ref_id, last_seen_ms DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__user_liked_track
+                   ADD COLUMN IF NOT EXISTS track_ref_id BIGINT
+                       REFERENCES furumusic__track_ref(id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_user_liked_track_ref_uniq
+                   ON furumusic__user_liked_track (user_id, track_ref_id)
+                 WHERE track_ref_id IS NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__playlist_track
+                   ADD COLUMN IF NOT EXISTS track_ref_id BIGINT
+                       REFERENCES furumusic__track_ref(id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_playlist_track_ref
+                   ON furumusic__playlist_track (track_ref_id)
+                 WHERE track_ref_id IS NOT NULL",
+            )
+            .await?;
+        // History deliberately remains local-track based. Only the web
+        // player's existing playback report records history and triggers
+        // Last.fm scrobbling.
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0040CreateContentAddressedMusicRefs;
+
+    impl migrations::Migration for M0040CreateContentAddressedMusicRefs {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0040_create_content_addressed_music_refs";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0039_ensure_federation_content_id_cache",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_content_addressed_music_refs).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_synced_listen_history(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__listen_event (
+                    user_id BIGINT NOT NULL,
+                    listen_id TEXT NOT NULL,
+                    content_id TEXT NOT NULL,
+                    local_track_id BIGINT,
+                    origin_device_id TEXT NOT NULL,
+                    started_at_ms BIGINT NOT NULL,
+                    listened_ms BIGINT NOT NULL,
+                    track_duration_ms BIGINT,
+                    ended_reason TEXT NOT NULL,
+                    qualified BOOLEAN NOT NULL,
+                    metadata_json JSONB NOT NULL,
+                    created_at TEXT NOT NULL,
+                    PRIMARY KEY (user_id, listen_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_listen_event_user_time
+                   ON furumusic__listen_event (user_id, started_at_ms DESC, listen_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_listen_event_content
+                   ON furumusic__listen_event (user_id, content_id)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "INSERT INTO furumusic__listen_event
+                    (user_id, listen_id, content_id, local_track_id,
+                     origin_device_id, started_at_ms, listened_ms,
+                     track_duration_ms, ended_reason, qualified,
+                     metadata_json, created_at)
+                 SELECT ph.user_id,
+                        'legacy-web:' || ph.id::text,
+                        tr.content_id,
+                        ph.track_id,
+                        ident.device_id,
+                        (EXTRACT(EPOCH FROM ph.played_at::timestamptz) * 1000)::bigint,
+                        COALESCE(ph.duration_listened, 0)::bigint * 1000,
+                        (t.duration_seconds * 1000)::bigint,
+                        CASE WHEN ph.completed THEN '\"finished\"' ELSE '\"unknown\"' END,
+                        ph.completed,
+                        jsonb_build_object(
+                            'title', t.title::text,
+                            'artist_names', COALESCE((
+                                SELECT jsonb_agg(a.name::text ORDER BY ta.position)
+                                  FROM furumusic__track_artist ta
+                                  JOIN furumusic__artist a ON a.id = ta.artist_id
+                                 WHERE ta.track_id = t.id
+                                   AND ta.role <> 'featuring'
+                            ), '[]'::jsonb),
+                            'featured_artist_names', COALESCE((
+                                SELECT jsonb_agg(a.name::text ORDER BY ta.position)
+                                  FROM furumusic__track_artist ta
+                                  JOIN furumusic__artist a ON a.id = ta.artist_id
+                                 WHERE ta.track_id = t.id
+                                   AND ta.role = 'featuring'
+                            ), '[]'::jsonb),
+                            'release_title', r.title::text
+                        ),
+                        ph.played_at::text
+                   FROM furumusic__play_history ph
+                   JOIN furumusic__track t ON t.id = ph.track_id
+                   JOIN furumusic__track_ref tr ON tr.local_track_id = ph.track_id
+                   JOIN furumusic__fed_device_identity ident
+                     ON ident.user_id = ph.user_id
+                   LEFT JOIN furumusic__release r ON r.id = t.release_id
+                 ON CONFLICT (user_id, listen_id) DO NOTHING",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__lastfm_scrobble_outbox
+                   ALTER COLUMN track_id DROP NOT NULL",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__lastfm_scrobble_outbox
+                   ADD COLUMN IF NOT EXISTS track_title TEXT,
+                   ADD COLUMN IF NOT EXISTS artist_name TEXT,
+                   ADD COLUMN IF NOT EXISTS album_title TEXT",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0041CreateSyncedListenHistory;
+
+    impl migrations::Migration for M0041CreateSyncedListenHistory {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0041_create_synced_listen_history";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0040_create_content_addressed_music_refs",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_synced_listen_history).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn repair_legacy_listen_qualification(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "UPDATE furumusic__listen_event le
+                    SET qualified = (
+                        ph.completed
+                        OR (
+                            COALESCE(ph.duration_listened, 0) >= 5
+                            AND COALESCE(t.duration_seconds, 0) > 0
+                            AND COALESCE(ph.duration_listened, 0) >= LEAST(
+                                COALESCE(t.duration_seconds, 0) / 2.0,
+                                240.0
+                            )
+                        )
+                    )
+                   FROM furumusic__play_history ph
+                   JOIN furumusic__track t ON t.id = ph.track_id
+                  WHERE le.user_id = ph.user_id
+                    AND le.listen_id = 'legacy-web:' || ph.id::text",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0042RepairLegacyListenQualification;
+
+    impl migrations::Migration for M0042RepairLegacyListenQualification {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0042_repair_legacy_listen_qualification";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0041_create_synced_listen_history",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(repair_legacy_listen_qualification).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_similarity_embeddings(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__similarity_profile (
+                    profile_id TEXT PRIMARY KEY,
+                    model_id TEXT NOT NULL,
+                    model_version TEXT NOT NULL,
+                    model_sha256 TEXT NOT NULL,
+                    preprocessing TEXT NOT NULL,
+                    dimensions INTEGER NOT NULL,
+                    active BOOLEAN NOT NULL DEFAULT FALSE,
+                    created_at TEXT NOT NULL
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_similarity_profile_active
+                   ON furumusic__similarity_profile (active)
+                 WHERE active = TRUE",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__track_embedding (
+                    track_id BIGINT NOT NULL REFERENCES furumusic__track(id)
+                        ON DELETE CASCADE,
+                    profile_id TEXT NOT NULL REFERENCES furumusic__similarity_profile(profile_id)
+                        ON DELETE CASCADE,
+                    dimensions INTEGER NOT NULL,
+                    vector BYTEA NOT NULL,
+                    source_sha256 TEXT NOT NULL,
+                    source_content_id TEXT,
+                    computed_at TEXT NOT NULL,
+                    PRIMARY KEY (track_id, profile_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_track_embedding_profile
+                   ON furumusic__track_embedding (profile_id, track_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0043CreateSimilarityEmbeddings;
+
+    impl migrations::Migration for M0043CreateSimilarityEmbeddings {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0043_create_similarity_embeddings";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0042_repair_legacy_listen_qualification",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_similarity_embeddings).build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn add_similarity_routing_signature(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "ALTER TABLE furumusic__track_embedding
+                 ADD COLUMN IF NOT EXISTS routing_signature BYTEA",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0044AddSimilarityRoutingSignature;
+
+    impl migrations::Migration for M0044AddSimilarityRoutingSignature {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0044_add_similarity_routing_signature";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0043_create_similarity_embeddings",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(add_similarity_routing_signature).build()];
+    }
+
+    // -- M0045: persistent YouTube download jobs ----------------------------
+
+    #[cot::db::migrations::migration_op]
+    async fn create_youtube_downloads(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__youtube_download (
+                    id VARCHAR(36) PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    source_url TEXT NOT NULL,
+                    title TEXT NOT NULL,
+                    source_kind VARCHAR(32) NOT NULL,
+                    status VARCHAR(32) NOT NULL,
+                    total_items INTEGER NOT NULL DEFAULT 0,
+                    completed_items INTEGER NOT NULL DEFAULT 0,
+                    failed_items INTEGER NOT NULL DEFAULT 0,
+                    review_items INTEGER NOT NULL DEFAULT 0,
+                    error TEXT,
+                    created_at VARCHAR(32) NOT NULL,
+                    updated_at VARCHAR(32) NOT NULL,
+                    completed_at VARCHAR(32)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__youtube_download_item (
+                    id VARCHAR(36) PRIMARY KEY,
+                    job_id VARCHAR(36) NOT NULL REFERENCES furumusic__youtube_download(id) ON DELETE CASCADE,
+                    source_id VARCHAR(128) NOT NULL,
+                    source_url TEXT NOT NULL,
+                    title TEXT NOT NULL,
+                    playlist_index INTEGER NOT NULL,
+                    status VARCHAR(32) NOT NULL,
+                    progress_percent DOUBLE PRECISION NOT NULL DEFAULT 0,
+                    downloaded_bytes BIGINT NOT NULL DEFAULT 0,
+                    total_bytes BIGINT,
+                    speed_bytes_per_sec BIGINT,
+                    eta_seconds BIGINT,
+                    chapter_count INTEGER NOT NULL DEFAULT 0,
+                    audio_file_count INTEGER NOT NULL DEFAULT 0,
+                    inbox_path TEXT,
+                    error TEXT,
+                    created_at VARCHAR(32) NOT NULL,
+                    updated_at VARCHAR(32) NOT NULL,
+                    completed_at VARCHAR(32),
+                    UNIQUE(job_id, source_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_youtube_download_user_updated
+                   ON furumusic__youtube_download (user_id, updated_at DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_youtube_download_user_status
+                   ON furumusic__youtube_download (user_id, status)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_youtube_download_item_job_status
+                   ON furumusic__youtube_download_item (job_id, status, playlist_index)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_youtube_download_item_source
+                   ON furumusic__youtube_download_item (source_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0045CreateYouTubeDownloads;
+
+    impl migrations::Migration for M0045CreateYouTubeDownloads {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0045_create_youtube_downloads";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0044_add_similarity_routing_signature",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_youtube_downloads).build()];
+    }
+
+    // -- M0046: persistent direct-file upload history -----------------------
+
+    #[cot::db::migrations::migration_op]
+    async fn create_local_upload_history(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__local_upload (
+                    id VARCHAR(36) PRIMARY KEY,
+                    user_id BIGINT NOT NULL,
+                    filename TEXT NOT NULL,
+                    size_bytes BIGINT NOT NULL DEFAULT 0,
+                    status VARCHAR(32) NOT NULL,
+                    inbox_path TEXT NOT NULL,
+                    error TEXT,
+                    created_at VARCHAR(32) NOT NULL,
+                    updated_at VARCHAR(32) NOT NULL,
+                    completed_at VARCHAR(32)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_local_upload_user_updated
+                   ON furumusic__local_upload (user_id, updated_at DESC)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_local_upload_user_status
+                   ON furumusic__local_upload (user_id, status)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0046CreateLocalUploadHistory;
+
+    impl migrations::Migration for M0046CreateLocalUploadHistory {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0046_create_local_upload_history";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0045_create_youtube_downloads",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_local_upload_history).build()];
+    }
+
+    // -- M0047: durable YouTube item -> imported media links ---------------
+
+    #[cot::db::migrations::migration_op]
+    async fn create_youtube_import_media_links(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__youtube_import_media (
+                    item_id VARCHAR(36) NOT NULL
+                        REFERENCES furumusic__youtube_download_item(id) ON DELETE CASCADE,
+                    media_file_id BIGINT NOT NULL
+                        REFERENCES furumusic__media_file(id) ON DELETE CASCADE,
+                    PRIMARY KEY (item_id, media_file_id)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_youtube_import_media_file
+                   ON furumusic__youtube_import_media (media_file_id)",
+            )
+            .await?;
+        // Backfill links for existing imports through the inbox review hash.
+        ctx.db
+            .raw(
+                "INSERT INTO furumusic__youtube_import_media (item_id, media_file_id)
+                 SELECT DISTINCT item.id, media.id
+                   FROM furumusic__youtube_download_item item
+                   JOIN furumusic__pending_review review
+                     ON item.inbox_path IS NOT NULL
+                    AND (review.input_path = item.inbox_path
+                         OR left(review.input_path, length(item.inbox_path) + 1)
+                            = item.inbox_path || '/')
+                   JOIN furumusic__media_file media
+                     ON media.sha256_hash::text = substring(
+                            review.context_json
+                            from '\"sha256\"[[:space:]]*:[[:space:]]*\"([0-9a-fA-F]{64})\"'
+                        )
+                   JOIN furumusic__track track ON track.audio_file_id = media.id
+                 WHERE review.context_json IS NOT NULL
+                 ON CONFLICT (item_id, media_file_id) DO NOTHING",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0047CreateYouTubeImportMediaLinks;
+
+    impl migrations::Migration for M0047CreateYouTubeImportMediaLinks {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0047_create_youtube_import_media_links";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] = &[
+            migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0046_create_local_upload_history",
+            ),
+            migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0027_create_processing_stats",
+            ),
+        ];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_youtube_import_media_links).build()];
+    }
+
     pub const MIGRATIONS: &[&SyncDynMigration] = &[
         &M0006CreateMediaFile,
         &M0007CreateArtist,
@@ -1979,5 +2810,15 @@ pub mod db_migrations {
         &M0035CreateEntityGenreTags,
         &M0036CreateExternalMetadataIds,
         &M0037CreatePlaylistShareLinks,
+        &M0038CreateFedDeviceSync,
+        &M0039EnsureFederationContentIdCache,
+        &M0040CreateContentAddressedMusicRefs,
+        &M0041CreateSyncedListenHistory,
+        &M0042RepairLegacyListenQualification,
+        &M0043CreateSimilarityEmbeddings,
+        &M0044AddSimilarityRoutingSignature,
+        &M0045CreateYouTubeDownloads,
+        &M0046CreateLocalUploadHistory,
+        &M0047CreateYouTubeImportMediaLinks,
     ];
 }

src/player/dto.rs

@@ -51,6 +51,7 @@ pub(super) struct ArtistRef {
 #[derive(Debug, Clone, Serialize, JsonSchema)]
 pub(super) struct TrackItem {
     pub(super) id: i64,
+    pub(super) content_id: Option<String>,
     pub(super) title: String,
     pub(super) track_number: Option<i32>,
     pub(super) disc_number: Option<i32>,
@@ -74,6 +75,15 @@ pub(super) struct TrackItem {
     pub(super) lastfm_updated_at: Option<String>,
 }
 
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlaylistTrackItem {
+    pub(super) playlist_track_id: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) sort_key: Option<i64>,
+    #[serde(flatten)]
+    pub(super) track: TrackItem,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct ArtistAppearanceTrack {
     pub(super) id: i64,
@@ -265,6 +275,24 @@ pub(super) struct PlayerDevicesResponse {
     pub(super) playback_state: Option<PlayerDevicePlaybackStateDto>,
 }
 
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDeviceConnectRequest {
+    pub(super) invite: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDevicePairingAnswerRequest {
+    pub(super) request_id: String,
+    pub(super) accept: bool,
+    #[serde(default)]
+    pub(super) use_requester_group: bool,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FedDeviceRevokeRequest {
+    pub(super) device_id: String,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct PlayerDevicePollResponse {
     pub(super) device_id: String,
@@ -286,7 +314,7 @@ pub(super) struct PlaylistDetail {
     pub(super) is_public: bool,
     pub(super) is_saved: bool,
     pub(super) kind: String,
-    pub(super) tracks: Vec<TrackItem>,
+    pub(super) tracks: Vec<PlaylistTrackItem>,
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -513,14 +541,16 @@ pub(super) struct UserUploadReviewUpdateRequest {
 
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct PlayHistoryItem {
-    pub(super) id: i64,
-    pub(super) track_id: i64,
+    pub(super) id: String,
+    pub(super) track_id: Option<i64>,
     pub(super) track_title: String,
     pub(super) release_title: Option<String>,
-    pub(super) track: TrackItem,
+    pub(super) track: serde_json::Value,
     pub(super) played_at: String,
     pub(super) duration_listened: Option<i32>,
     pub(super) completed: bool,
+    pub(super) device_id: String,
+    pub(super) device_name: String,
 }
 
 #[derive(Debug, Serialize, JsonSchema)]
@@ -536,6 +566,46 @@ pub(super) struct LikeStatus {
     pub(super) liked: bool,
 }
 
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct ContentTrackMutation {
+    pub(super) content_id: String,
+    pub(super) liked: Option<bool>,
+    pub(super) playlist_id: Option<i64>,
+    pub(super) position: Option<i64>,
+    pub(super) federation: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct PrepareFederatedTrackRequest {
+    pub(super) content_id: String,
+    pub(super) owner: Option<String>,
+    pub(super) item_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtworkQuery {
+    pub(super) owner: String,
+    pub(super) item_id: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtistQuery {
+    pub(super) name: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationCatalogArtworkQuery {
+    pub(super) owner: String,
+    pub(super) artist: String,
+    pub(super) release: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct FederationArtworkDiscoveryQuery {
+    pub(super) artist: String,
+    pub(super) release: Option<String>,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct LikedIds {
     pub(super) track_ids: Vec<i64>,

src/player/queries.rs

@@ -3,9 +3,11 @@ use serde::Deserialize;
 #[derive(Debug, Deserialize)]
 pub(super) struct HistoryEntry {
     pub(super) track_id: i64,
+    pub(super) listen_id: Option<String>,
     pub(super) started_at: Option<i64>,
     pub(super) duration_listened: Option<i32>,
     pub(super) completed: bool,
+    pub(super) ended_reason: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -42,7 +44,13 @@ pub(super) struct AddTracksRequest {
 
 #[derive(Debug, Deserialize)]
 pub(super) struct RemoveTrackRequest {
-    pub(super) track_id: i64,
+    pub(super) track_id: Option<i64>,
+    pub(super) playlist_track_id: Option<i64>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct ReorderPlaylistRequest {
+    pub(super) playlist_track_ids: Vec<i64>,
 }
 
 #[derive(Debug, Deserialize)]

src/player/rows.rs

@@ -95,6 +95,7 @@ pub(super) struct PlaylistInfoRow {
 
 #[derive(sqlx::FromRow)]
 pub(super) struct PlaylistTrackRow {
+    pub(super) playlist_track_id: Option<i64>,
     pub(super) id: i64,
     pub(super) title: String,
     pub(super) track_number: Option<i32>,
@@ -253,34 +254,6 @@ pub(super) struct ReleaseUploaderRow {
     pub(super) track_count: i64,
 }
 
-#[derive(sqlx::FromRow)]
-pub(super) struct PlayHistoryTrackRow {
-    pub(super) history_id: i64,
-    pub(super) played_at: String,
-    pub(super) duration_listened: Option<i32>,
-    pub(super) completed: bool,
-    pub(super) id: i64,
-    pub(super) title: String,
-    pub(super) track_number: Option<i32>,
-    pub(super) disc_number: Option<i32>,
-    pub(super) duration_seconds: f64,
-    pub(super) cover_file_id: Option<i64>,
-    pub(super) release_cover_file_id: Option<i64>,
-    pub(super) release_id: i64,
-    pub(super) release_title: String,
-    pub(super) release_year: Option<i32>,
-    pub(super) uploader_name: String,
-    pub(super) audio_format: Option<String>,
-    pub(super) audio_bitrate: Option<i32>,
-    pub(super) audio_sample_rate: Option<i32>,
-    pub(super) audio_bit_depth: Option<i32>,
-    pub(super) file_size_bytes: Option<i64>,
-    pub(super) lastfm_listeners: Option<i64>,
-    pub(super) lastfm_playcount: Option<i64>,
-    pub(super) lastfm_rating: Option<f64>,
-    pub(super) lastfm_updated_at: Option<String>,
-}
-
 #[derive(sqlx::FromRow)]
 pub(super) struct ReleaseInfoRow {
     pub(super) id: i64,

src/torrents.rs

@@ -373,7 +373,8 @@ impl TorrentJob {
 
 pub struct TorrentService {
     temp_root: PathBuf,
-    session: OnceCell<Arc<Session>>,
+    sessions: Mutex<HashMap<String, Arc<Session>>>,
+    job_sessions: Mutex<HashMap<String, Arc<Session>>>,
     jobs: Mutex<HashMap<String, TorrentJob>>,
     resolving_jobs: Mutex<HashSet<String>>,
     scheduler_handle: Arc<OnceCell<Arc<SchedulerHandle>>>,
@@ -383,36 +384,47 @@ impl TorrentService {
     pub fn new(scheduler_handle: Arc<OnceCell<Arc<SchedulerHandle>>>) -> Self {
         Self {
             temp_root: std::env::temp_dir().join("furumusic").join("torrents"),
-            session: OnceCell::new(),
+            sessions: Mutex::new(HashMap::new()),
+            job_sessions: Mutex::new(HashMap::new()),
             jobs: Mutex::new(HashMap::new()),
             resolving_jobs: Mutex::new(HashSet::new()),
             scheduler_handle,
         }
     }
 
-    async fn session(&self) -> anyhow::Result<Arc<Session>> {
-        let temp_root = self.temp_root.clone();
-        self.session
-            .get_or_try_init(|| async move {
-                tokio::fs::create_dir_all(&temp_root).await?;
-                Session::new_with_opts(
-                    temp_root,
-                    SessionOptions {
-                        disable_upload: true,
-                        enable_upnp_port_forwarding: false,
-                        ..Default::default()
-                    },
-                )
-                .await
-            })
-            .await
-            .cloned()
+    async fn session(&self, proxy_url: Option<&str>) -> anyhow::Result<Arc<Session>> {
+        let key = proxy_url.unwrap_or_default().to_string();
+        let mut sessions = self.sessions.lock().await;
+        if let Some(session) = sessions.get(&key) {
+            return Ok(Arc::clone(session));
+        }
+
+        tokio::fs::create_dir_all(&self.temp_root).await?;
+        let session = Session::new_with_opts(
+            self.temp_root.clone(),
+            SessionOptions {
+                // SOCKS is intentionally limited to peer TCP and HTTP(S)
+                // tracker traffic. DHT and other UDP discovery stay direct.
+                disable_dht: false,
+                // Sessions are keyed by proxy and can coexist, so they cannot
+                // safely share one persisted DHT socket configuration.
+                disable_dht_persistence: true,
+                disable_upload: true,
+                enable_upnp_port_forwarding: false,
+                socks_proxy_url: proxy_url.map(str::to_owned),
+                ..Default::default()
+            },
+        )
+        .await?;
+        sessions.insert(key, Arc::clone(&session));
+        Ok(session)
     }
 
     pub async fn list(
         self: &Arc<Self>,
         pool: &PgPool,
         user_id: i64,
+        proxy_url: Option<String>,
     ) -> anyhow::Result<Vec<TorrentJobDto>> {
         let rows = sqlx::query_as::<_, TorrentSessionRow>(
             r#"SELECT id, user_id, name, info_hash, source_kind, source_label, torrent_bytes,
@@ -445,6 +457,7 @@ impl TorrentService {
                         row.id.clone(),
                         magnet,
                         row.created_at.clone(),
+                        proxy_url.clone(),
                     )
                     .await;
                 }
@@ -483,8 +496,9 @@ impl TorrentService {
         pool: &PgPool,
         user_id: i64,
         request: TorrentPreviewRequest,
+        proxy_url: Option<&str>,
     ) -> anyhow::Result<TorrentSessionDto> {
-        let session = self.session().await?;
+        let session = self.session(proxy_url).await?;
         let id = Uuid::new_v4().to_string();
         let output_dir = self.temp_root.join(&id).join("download");
         tokio::fs::create_dir_all(&output_dir).await?;
@@ -511,8 +525,15 @@ impl TorrentService {
                 .unwrap_or_else(|| info_hash.clone());
             let now = now_string();
             insert_pending_magnet(pool, &id, user_id, &name, &info_hash, &magnet, &now).await?;
-            self.spawn_resolve_pending_magnet(pool.clone(), user_id, id.clone(), magnet, now)
-                .await;
+            self.spawn_resolve_pending_magnet(
+                pool.clone(),
+                user_id,
+                id.clone(),
+                magnet,
+                now,
+                proxy_url.map(str::to_owned),
+            )
+            .await;
 
             let row = load_row(pool, user_id, &id).await?;
             return Ok(TorrentSessionDto {
@@ -611,6 +632,7 @@ impl TorrentService {
         id: String,
         magnet: String,
         created_at: String,
+        proxy_url: Option<String>,
     ) {
         {
             let mut resolving = self.resolving_jobs.lock().await;
@@ -622,7 +644,14 @@ impl TorrentService {
         let service = Arc::clone(self);
         tokio::spawn(async move {
             let result = service
-                .resolve_pending_magnet(&pool, user_id, &id, &magnet, &created_at)
+                .resolve_pending_magnet(
+                    &pool,
+                    user_id,
+                    &id,
+                    &magnet,
+                    &created_at,
+                    proxy_url.as_deref(),
+                )
                 .await;
             if let Err(err) = result {
                 update_resolving_error(&pool, &id, &err.to_string()).await;
@@ -638,8 +667,9 @@ impl TorrentService {
         id: &str,
         magnet: &str,
         created_at: &str,
+        proxy_url: Option<&str>,
     ) -> anyhow::Result<()> {
-        let session = self.session().await?;
+        let session = self.session(proxy_url).await?;
         let output_dir = self.temp_root.join(id).join("download");
         tokio::fs::create_dir_all(&output_dir).await?;
         let response = tokio::time::timeout(
@@ -743,7 +773,7 @@ impl TorrentService {
             jobs.remove(id).and_then(|job| job.handle)
         };
         if let Some(handle) = removed {
-            self.stop_torrent(&handle).await;
+            self.stop_torrent(id, &handle).await;
         }
 
         let result =
@@ -766,6 +796,7 @@ impl TorrentService {
         selected_files: Vec<usize>,
         inbox_dir: String,
         uploader_user_id: i64,
+        proxy_url: Option<&str>,
     ) -> anyhow::Result<TorrentJobDto> {
         if selected_files.is_empty() {
             bail!("select at least one file");
@@ -810,7 +841,7 @@ impl TorrentService {
         tokio::fs::create_dir_all(&output_dir).await?;
         mark_job_started(pool, id, &selected_files, &self.memory_job_dto(id).await?).await?;
 
-        let session = self.session().await?;
+        let session = self.session(proxy_url).await?;
         let response = match session
             .add_torrent(
                 AddTorrent::from_bytes(torrent_bytes),
@@ -838,6 +869,10 @@ impl TorrentService {
                 return Err(err);
             }
         };
+        self.job_sessions
+            .lock()
+            .await
+            .insert(id.to_string(), Arc::clone(&session));
 
         let dto = {
             let mut jobs = self.jobs.lock().await;
@@ -856,7 +891,7 @@ impl TorrentService {
                 if service.is_paused(&id).await {
                     return;
                 }
-                service.stop_torrent(&handle).await;
+                service.stop_torrent(&id, &handle).await;
                 service.fail_job(&pool, &id, err.to_string()).await;
                 crate::metrics::record_torrent_download(
                     "failed",
@@ -865,7 +900,7 @@ impl TorrentService {
                 );
                 return;
             }
-            service.stop_torrent(&handle).await;
+            service.stop_torrent(&id, &handle).await;
             if let Err(err) = service
                 .finalize_completed(&pool, &id, &inbox_dir, uploader_user_id)
                 .await
@@ -911,7 +946,7 @@ impl TorrentService {
 
         persist_progress(pool, &dto).await?;
         if let Some(handle) = handle {
-            self.stop_torrent(&handle).await;
+            self.stop_torrent(id, &handle).await;
         }
         Ok(dto)
     }
@@ -981,16 +1016,12 @@ impl TorrentService {
         }
     }
 
-    async fn stop_torrent(&self, handle: &Arc<ManagedTorrent>) {
-        match self.session().await {
-            Ok(session) => {
-                if let Err(err) = session.delete(handle.id().into(), false).await {
-                    tracing::warn!("failed to stop completed torrent: {err}");
-                }
-            }
-            Err(err) => {
-                tracing::warn!("failed to access torrent session for shutdown: {err}");
-            }
+    async fn stop_torrent(&self, id: &str, handle: &Arc<ManagedTorrent>) {
+        let session = self.job_sessions.lock().await.remove(id);
+        if let Some(session) = session
+            && let Err(err) = session.delete(handle.id().into(), false).await
+        {
+            tracing::warn!("failed to stop completed torrent: {err}");
         }
     }
 

templates/base.html

@@ -3,6 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='14' fill='%23111827'/%3E%3Cpath d='M27 15v31.5a9 9 0 1 1-5-8.1V22l27-6v24.5a9 9 0 1 1-5-8.1V15.9L27 20.5' fill='%2367e8f9'/%3E%3C/svg%3E">
     <title>{% block title %}{{ t.site_name }}{% endblock title %}</title>
     {% block head_extra %}{% endblock head_extra %}
 </head>

templates/player/modals.html

@@ -85,7 +85,7 @@
         </div>
     </template>
 
-    <!-- Torrent Import Modal -->
+    <!-- Download Manager Modal -->
     <template x-if="$store.torrents.modal">
         <div class="modal-overlay" @click.self="$store.torrents.close()">
             <div class="modal-box torrent-modal">
@@ -107,25 +107,47 @@
                     </button>
                     <div class="torrent-client-status">
                         <span class="torrent-status-pill"
+                              x-show="$store.torrents.sourceTab === 'torrents'"
                               :class="{ active: $store.torrents.activeCount() > 0 }"
                               x-text="$store.torrents.clientSummary()"></span>
+                        <span class="torrent-status-pill"
+                              x-show="$store.torrents.sourceTab === 'youtube'"
+                              :class="{ active: $store.torrents.youtubeActiveCount() > 0 }"
+                              x-text="$store.torrents.youtubeSummary()"></span>
                         <span class="torrent-status-pill torrent-agent-pill"
                               :class="{ active: $store.torrents.agentBusy() }">
                             <span class="torrent-agent-dot"></span>
                             <span x-text="$store.torrents.agentSummary()"></span>
                         </span>
                         <span class="torrent-status-pill"
+                              x-show="$store.torrents.sourceTab === 'torrents'"
                               x-text="$store.torrents.sessions.length + ' ' + T.saved"></span>
+                        <span class="torrent-status-pill"
+                              x-show="$store.torrents.sourceTab === 'youtube'"
+                              x-text="$store.torrents.youtubeJobs.length + ' ' + T.saved"></span>
+                        <span class="torrent-status-pill"
+                              x-show="$store.torrents.sourceTab === 'files'"
+                              x-text="$store.torrents.localUploadHistory.length + ' ' + T.saved"></span>
                     </div>
                 </div>
 
-                <div class="torrent-tabs">
+                <div class="torrent-tabs download-source-tabs">
+                    {% if youtube_downloads_enabled %}
                     <button class="torrent-tab-btn"
-                            :class="{ active: $store.torrents.activeTab === 'import' }"
-                            @click="$store.torrents.showImportTab()">{{ t.player_import }}</button>
+                            :class="{ active: $store.torrents.sourceTab === 'youtube' }"
+                            @click="$store.torrents.showSourceTab('youtube')">{{ t.player_youtube }}</button>
+                    {% endif %}
+                    {% if torrent_downloads_enabled %}
                     <button class="torrent-tab-btn"
-                            :class="{ active: $store.torrents.activeTab === 'uploads' }"
-                            @click="$store.torrents.showUploadsTab()">
+                            :class="{ active: $store.torrents.sourceTab === 'torrents' }"
+                            @click="$store.torrents.showSourceTab('torrents')">{{ t.player_torrents }}</button>
+                    {% endif %}
+                    <button class="torrent-tab-btn"
+                            :class="{ active: $store.torrents.sourceTab === 'files' }"
+                            @click="$store.torrents.showSourceTab('files')">{{ t.player_files }}</button>
+                    <button class="torrent-tab-btn"
+                            :class="{ active: $store.torrents.sourceTab === 'uploads' }"
+                            @click="$store.torrents.showSourceTab('uploads')">
                         <span>{{ t.player_my_uploads }}</span>
                         <span class="torrent-tab-count"
                               x-show="$store.torrents.uploadPendingTotal + $store.torrents.uploadQueuedTotal > 0"
@@ -133,7 +155,173 @@
                     </button>
                 </div>
 
-                <template x-if="$store.torrents.activeTab === 'import'">
+                <div class="youtube-manager-panel" x-show="$store.torrents.sourceTab === 'youtube'">
+                    <form class="youtube-download-form" @submit.prevent="$store.torrents.previewYoutubeUrl()">
+                        <label for="youtube-download-url">{{ t.player_youtube_url }}</label>
+                        <div class="youtube-download-form-row">
+                            <input id="youtube-download-url"
+                                   type="text"
+                                   inputmode="url"
+                                   autocomplete="url"
+                                   x-model="$store.torrents.youtubeUrl"
+                                   @input="$store.torrents.clearYoutubePreview()"
+                                   placeholder="https://www.youtube.com/watch?v=...">
+                            <button type="submit"
+                                    class="modal-btn modal-btn-primary"
+                                    :disabled="$store.torrents.youtubePreviewLoading || $store.torrents.youtubeSubmitting || !$store.torrents.youtubeUrl.trim()">
+                                <span x-text="$store.torrents.youtubePreviewLoading ? T.youtubeParsing : T.youtubeParse"></span>
+                            </button>
+                        </div>
+                        <p class="youtube-download-hint">{{ t.player_youtube_url_hint }}</p>
+                    </form>
+
+                    <template x-if="$store.torrents.youtubePreview">
+                        <section class="youtube-preview-card">
+                            <div class="youtube-preview-head">
+                                <div>
+                                    <h4>{{ t.player_youtube_preview_title }}</h4>
+                                    <p>
+                                        <strong x-text="$store.torrents.youtubePreview.title"></strong>
+                                        <span> · </span>
+                                        <span x-text="$store.torrents.youtubePreview.items.length + ' ' + T.youtubeItems"></span>
+                                    </p>
+                                </div>
+                                <div class="youtube-preview-controls">
+                                    <button type="button" class="modal-btn modal-btn-ghost"
+                                            @click="$store.torrents.selectAllYoutubePreview()">{{ t.player_youtube_select_all }}</button>
+                                    <button type="button" class="modal-btn modal-btn-ghost"
+                                            @click="$store.torrents.clearYoutubePreviewSelection()">{{ t.player_youtube_clear_selection }}</button>
+                                </div>
+                            </div>
+                            <div class="youtube-preview-list">
+                                <template x-for="item in $store.torrents.youtubePreview.items" :key="item.source_id">
+                                    <label class="youtube-preview-row"
+                                           :class="{ selected: $store.torrents.youtubePreviewIsSelected(item.source_id) }">
+                                        <input type="checkbox"
+                                               :checked="$store.torrents.youtubePreviewIsSelected(item.source_id)"
+                                               @change="$store.torrents.toggleYoutubePreviewItem(item.source_id)">
+                                        <span class="youtube-item-index" x-text="String(item.playlist_index).padStart(2, '0')"></span>
+                                        <span class="youtube-preview-item-title" x-text="item.title"></span>
+                                    </label>
+                                </template>
+                            </div>
+                            <div class="youtube-preview-footer">
+                                <span x-text="$store.torrents.youtubePreviewSelectedCount() + ' ' + T.youtubeSelectedCount"></span>
+                                <div>
+                                    <button type="button" class="modal-btn modal-btn-ghost"
+                                            @click="$store.torrents.clearYoutubePreview()">{{ t.player_cancel }}</button>
+                                    <button type="button" class="modal-btn modal-btn-primary"
+                                            @click="$store.torrents.startYoutubeDownload()"
+                                            :disabled="$store.torrents.youtubeSubmitting || $store.torrents.youtubePreviewSelectedCount() === 0">
+                                        {{ t.player_youtube_start_import }}
+                                    </button>
+                                </div>
+                            </div>
+                        </section>
+                    </template>
+
+                    <div class="youtube-download-list-head">
+                        <span>{{ t.player_youtube_downloads }}</span>
+                        <button class="modal-btn modal-btn-ghost"
+                                @click="$store.torrents.loadYoutubeJobs()"
+                                :disabled="$store.torrents.youtubeLoading">{{ t.player_refresh }}</button>
+                    </div>
+
+                    <div class="youtube-download-list">
+                        <template x-if="!$store.torrents.youtubeLoading && $store.torrents.youtubeJobs.length === 0">
+                            <div class="empty-state youtube-empty-state">
+                                <p>{{ t.player_no_youtube_downloads }}</p>
+                            </div>
+                        </template>
+
+                        <template x-for="job in $store.torrents.youtubeJobs" :key="job.id">
+                            <article class="youtube-job-card">
+                                <div class="youtube-job-head">
+                                    <div class="youtube-job-heading">
+                                        <div class="youtube-job-title" x-text="job.title"></div>
+                                        <div class="youtube-job-meta" x-text="$store.torrents.youtubeJobMeta(job)"></div>
+                                    </div>
+                                    <span class="torrent-status-badge"
+                                          :class="$store.torrents.youtubeStatusClass(job.status)"
+                                          x-text="$store.torrents.youtubeStatusLabel(job.status)"></span>
+                                </div>
+
+                                <div class="youtube-job-progress">
+                                    <div class="torrent-session-progress">
+                                        <div class="torrent-session-progress-bar"
+                                             :style="'width:' + $store.torrents.youtubeJobProgress(job) + '%'">
+                                        </div>
+                                    </div>
+                                    <span x-text="$store.torrents.youtubeJobProgressText(job)"></span>
+                                </div>
+
+                                <p class="youtube-job-error" x-show="job.error" x-text="job.error"></p>
+
+                                <div class="youtube-item-list">
+                                    <template x-for="item in job.items" :key="item.id">
+                                        <div class="youtube-item-row" :class="{ failed: $store.torrents.youtubeIsError(item.status) }">
+                                            <div class="youtube-item-head">
+                                                <span class="youtube-item-index" x-text="String(item.playlist_index).padStart(2, '0')"></span>
+                                                <div class="youtube-item-main">
+                                                    <div class="youtube-item-title" x-text="item.title"></div>
+                                                    <div class="youtube-item-meta" x-text="$store.torrents.youtubeItemMeta(item)"></div>
+                                                </div>
+                                                <span class="torrent-status-badge"
+                                                      :class="$store.torrents.youtubeStatusClass(item.status)"
+                                                      x-text="$store.torrents.youtubeStatusLabel(item.status)"></span>
+                                            </div>
+
+                                            <div class="youtube-item-download-progress" x-show="item.status === 'downloading'">
+                                                <div class="torrent-session-progress">
+                                                    <div class="torrent-session-progress-bar"
+                                                         :style="'width:' + Number(item.progress_percent || 0) + '%'">
+                                                    </div>
+                                                </div>
+                                                <span x-text="$store.torrents.youtubeDownloadMeta(item)"></span>
+                                            </div>
+
+                                            <div class="youtube-step-list" aria-label="{{ t.player_download_steps }}">
+                                                <span class="youtube-step" :class="$store.torrents.youtubeStepClass(item, 1)">
+                                                    <i></i><b>{{ t.player_downloading }}</b>
+                                                </span>
+                                                <span class="youtube-step" :class="$store.torrents.youtubeStepClass(item, 2)">
+                                                    <i></i><b>FFmpeg</b>
+                                                </span>
+                                                <span class="youtube-step" :class="$store.torrents.youtubeStepClass(item, 3)">
+                                                    <i></i><b>{{ t.player_ai_prefix }}</b>
+                                                </span>
+                                                <span class="youtube-step" :class="$store.torrents.youtubeStepClass(item, 4)">
+                                                    <i></i><b x-text="$store.torrents.youtubeFinalStepLabel(item)"></b>
+                                                </span>
+                                            </div>
+                                            <p class="youtube-item-error"
+                                               x-show="item.error"
+                                               x-text="item.error"></p>
+                                        </div>
+                                    </template>
+                                </div>
+
+                                <div class="youtube-job-actions">
+                                    <button class="modal-btn modal-btn-ghost"
+                                            x-show="job.review_items > 0 || job.items.some(item => item.status === 'ai_failed')"
+                                            @click="$store.torrents.openYoutubeReviews()">{{ t.player_my_uploads }}</button>
+                                    <button class="modal-btn modal-btn-pause"
+                                            x-show="$store.torrents.youtubeJobCancellable(job.status)"
+                                            :disabled="$store.torrents.youtubeCancellingIds.has(job.id)"
+                                            @click="$store.torrents.cancelYoutubeJob(job.id)">{{ t.player_youtube_stop }}</button>
+                                    <button class="modal-btn modal-btn-pause"
+                                            x-show="job.status !== 'cancelled' && (job.items.some(item => item.status === 'failed') || (job.status === 'failed' && job.total_items === 0))"
+                                            @click="$store.torrents.retryYoutubeJob(job.id)">{{ t.player_retry_failed }}</button>
+                                    <button class="modal-btn modal-btn-danger"
+                                            x-show="$store.torrents.youtubeJobTerminal(job.status)"
+                                            @click="$store.torrents.removeYoutubeJob(job.id)">{{ t.player_remove_from_history }}</button>
+                                </div>
+                            </article>
+                        </template>
+                    </div>
+                </div>
+
+                <div class="download-torrent-panel" x-show="$store.torrents.sourceTab === 'torrents'">
                 <div class="torrent-manager-layout">
                     <aside class="torrent-manager-sidebar">
                         <div class="torrent-manager-title">
@@ -173,7 +361,7 @@
                                     @click="$store.torrents.addNew()"
                                     :disabled="$store.torrents.loading">
                                 <span class="torrent-session-add-icon">+</span>
-                                <span>{{ t.player_upload }}</span>
+                                <span>{{ t.player_add_torrent }}</span>
                             </button>
                         </div>
                     </aside>
@@ -188,12 +376,6 @@
                         <template x-if="$store.torrents.isImporting()">
                             <div class="torrent-import-panel">
                                 <div class="torrent-modal-grid">
-                                    <div>
-                                        <label for="local-file-input">{{ t.player_local_files }}</label>
-                                        <input id="local-file-input" type="file" multiple accept="audio/*,.mp3,.flac,.wav,.m4a,.ogg,.opus,.aac"
-                                               @change="$store.torrents.setLocalFiles($event.target.files)">
-                                        <div class="torrent-upload-summary" x-text="$store.torrents.localUploadSummary()"></div>
-                                    </div>
                                     <div>
                                         <label for="torrent-magnet-input">{{ t.player_magnet_link }}</label>
                                         <input id="torrent-magnet-input" type="text"
@@ -206,17 +388,6 @@
                                                @change="$store.torrents.file = $event.target.files[0] || null">
                                     </div>
                                 </div>
-                                <div class="torrent-upload-progress"
-                                    x-show="$store.torrents.uploadProgress > 0 || ($store.torrents.localFiles.length > 0 && $store.torrents.loading)">
-                                    <div class="torrent-progress-head">
-                                        <span x-text="$store.torrents.uploadProgress >= 100 ? T.uploadComplete : T.uploadingFiles"></span>
-                                        <span x-text="$store.torrents.uploadProgressText"></span>
-                                    </div>
-                                    <div class="torrent-progress-track">
-                                        <div class="torrent-progress-bar"
-                                             :style="'width:' + $store.torrents.uploadProgress + '%'"></div>
-                                    </div>
-                                </div>
                                 <div class="torrent-actions">
                                     <button class="modal-btn modal-btn-primary" @click="$store.torrents.preview()" :disabled="$store.torrents.loading">
                                         {{ t.player_upload_content }}
@@ -282,7 +453,7 @@
                                 <button class="modal-btn modal-btn-danger"
                                         @click="$store.torrents.removeSession($store.torrents.previewData.id)"
                                         :disabled="$store.torrents.loading">
-                                    {{ t.player_delete }}
+                                    {{ t.player_remove_from_history }}
                                 </button>
                             </div>
                         </div>
@@ -341,9 +512,87 @@
                 </template>
                     </section>
                 </div>
-                </template>
+                </div>
 
-                <template x-if="$store.torrents.activeTab === 'uploads'">
+                <section class="file-upload-panel" x-show="$store.torrents.sourceTab === 'files'">
+                    <input id="direct-audio-file-input"
+                           class="file-upload-input"
+                           type="file"
+                           multiple
+                           accept="audio/*,.mp3,.flac,.wav,.m4a,.ogg,.opus,.aac"
+                           @change="$store.torrents.setLocalFiles($event.target.files); $event.target.value = ''">
+                    <label class="file-drop-zone"
+                           for="direct-audio-file-input"
+                           :class="{ dragging: $store.torrents.localFilesDragging }"
+                           @dragenter.prevent="$store.torrents.localFilesDragging = true"
+                           @dragover.prevent="$store.torrents.localFilesDragging = true"
+                           @dragleave.prevent="$store.torrents.leaveLocalFileDrop($event)"
+                           @drop.prevent="$store.torrents.dropLocalFiles($event)">
+                        <span class="file-drop-icon" aria-hidden="true">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
+                                <path d="M12 16V4"/><polyline points="7 9 12 4 17 9"/>
+                                <path d="M5 14v4a2 2 0 002 2h10a2 2 0 002-2v-4"/>
+                            </svg>
+                        </span>
+                        <strong>{{ t.player_drop_audio_title }}</strong>
+                        <span>{{ t.player_drop_audio_hint }}</span>
+                        <small>{{ t.player_drop_audio_formats }}</small>
+                    </label>
+
+                    <div class="file-upload-selection" x-show="$store.torrents.localFiles.length > 0">
+                        <span x-text="$store.torrents.localUploadSummary()"></span>
+                        <div>
+                            <button type="button" class="modal-btn modal-btn-ghost"
+                                    @click="$store.torrents.clearLocalFiles()"
+                                    :disabled="$store.torrents.localFilesUploading">{{ t.player_cancel }}</button>
+                            <button type="button" class="modal-btn modal-btn-primary"
+                                    @click="$store.torrents.uploadLocalFiles()"
+                                    :disabled="$store.torrents.localFilesUploading">{{ t.player_upload_selected_files }}</button>
+                        </div>
+                    </div>
+
+                    <div class="torrent-upload-progress"
+                         x-show="$store.torrents.localFilesUploading || $store.torrents.uploadProgress > 0">
+                        <div class="torrent-progress-head">
+                            <span x-text="$store.torrents.uploadProgress >= 100 ? T.uploadComplete : T.uploadingFiles"></span>
+                            <span x-text="$store.torrents.uploadProgressText"></span>
+                        </div>
+                        <div class="torrent-progress-track">
+                            <div class="torrent-progress-bar"
+                                 :style="'width:' + $store.torrents.uploadProgress + '%'"></div>
+                        </div>
+                    </div>
+
+                    <div class="youtube-download-list-head file-upload-history-head">
+                        <span>{{ t.player_upload_history }}</span>
+                        <button class="modal-btn modal-btn-ghost"
+                                @click="$store.torrents.loadLocalUploadHistory()"
+                                :disabled="$store.torrents.localUploadHistoryLoading">{{ t.player_refresh }}</button>
+                    </div>
+
+                    <div class="file-upload-history">
+                        <template x-if="!$store.torrents.localUploadHistoryLoading && $store.torrents.localUploadHistory.length === 0">
+                            <div class="empty-state youtube-empty-state"><p>{{ t.player_no_file_uploads }}</p></div>
+                        </template>
+                        <template x-for="item in $store.torrents.localUploadHistory" :key="item.id">
+                            <article class="file-upload-history-row">
+                                <div class="file-upload-history-main">
+                                    <div class="file-upload-history-title" x-text="item.filename"></div>
+                                    <div class="file-upload-history-meta"
+                                         x-text="$store.torrents.bytes(item.size_bytes) + ' · ' + $store.torrents.formatUploadDate(item.created_at)"></div>
+                                    <p class="youtube-item-error" x-show="item.error" x-text="item.error"></p>
+                                </div>
+                                <span class="torrent-status-badge"
+                                      :class="$store.torrents.youtubeStatusClass(item.status)"
+                                      x-text="$store.torrents.youtubeStatusLabel(item.status)"></span>
+                                <button class="modal-btn modal-btn-danger"
+                                        @click="$store.torrents.removeLocalUploadHistory(item.id)">{{ t.player_remove_from_history }}</button>
+                            </article>
+                        </template>
+                    </div>
+                </section>
+
+                <template x-if="$store.torrents.sourceTab === 'uploads'">
                     <section class="upload-manager-panel">
                         <div class="upload-manager-head">
                             <div>
@@ -636,6 +885,155 @@
         </div>
     </template>
 
+    <!-- User Settings Modal -->
+    <template x-if="$store.user.settingsOpen">
+        <div class="modal-overlay" @click.self="$store.user.closeSettings()">
+            <div class="modal-box user-settings-modal">
+                <div class="user-settings-head">
+                    <div>
+                        <h3>User settings</h3>
+                        <p>Personal services, listening history and trusted devices.</p>
+                    </div>
+                    <button class="mobile-list-action" @click="$store.user.closeSettings()" title="{{ t.player_close }}">
+                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                            <line x1="18" y1="6" x2="6" y2="18"/>
+                            <line x1="6" y1="6" x2="18" y2="18"/>
+                        </svg>
+                    </button>
+                </div>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>{{ t.player_interface_language }}</h4>
+                            <p>{{ t.player_language_description }}</p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                onclick="location.href='/set-lang?lang={% if t.lang.code() == "en" %}ru{% else %}en{% endif %}&next='+encodeURIComponent(location.pathname+location.search+location.hash)">{{ t.player_switch_language }}</button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Listening history</h4>
+                            <p>Review plays recorded by this web player.</p>
+                        </div>
+                        <button class="settings-secondary-btn" @click="$store.user.openHistoryFromSettings()">Open history</button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Last.fm</h4>
+                            <p x-text="$store.user.lastfmStatusLabel()"></p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                :class="$store.user.lastfmClass()"
+                                :disabled="$store.user.lastfmBusy || !$store.user.lastfm?.configured"
+                                @click="$store.user.handleLastfm()"
+                                x-text="$store.user.lastfm?.connected && !$store.user.lastfm?.reauth_required ? 'Disconnect' : 'Connect'"></button>
+                    </div>
+                </section>
+
+                <section class="user-settings-section user-settings-devices">
+                    <div class="user-settings-section-head">
+                        <div>
+                            <h4>Connected devices</h4>
+                            <p x-text="$store.devices.fedSummary()"></p>
+                        </div>
+                        <button class="settings-secondary-btn"
+                                :disabled="$store.devices.fedBusy"
+                                @click="$store.devices.syncFedDevices()">Sync now</button>
+                    </div>
+                    <template x-if="$store.devices.fedError">
+                        <div class="fed-device-error" x-text="$store.devices.fedError"></div>
+                    </template>
+
+                    <div class="settings-device-group">
+                        <div class="settings-device-label">Web player sessions</div>
+                        <template x-for="device in $store.devices.webDevices()" :key="'settings-web-' + device.id">
+                            <div class="settings-device-row">
+                                <span class="device-row-icon">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                                        <rect x="3" y="4" width="18" height="12" rx="2"/>
+                                        <path d="M8 20h8M12 16v4"/>
+                                    </svg>
+                                </span>
+                                <span class="fed-device-main">
+                                    <span class="fed-device-name" x-text="device.name"></span>
+                                    <span class="fed-device-meta"
+                                          x-text="device.is_current ? 'This browser session' : (device.is_active ? 'Active web session' : 'Web session')"></span>
+                                </span>
+                            </div>
+                        </template>
+                    </div>
+
+                    <div class="settings-device-group">
+                        <div class="settings-device-label">Trusted federation devices</div>
+                        <template x-for="request in $store.devices.fedPending()" :key="request.request_id">
+                            <div class="fed-pairing-card">
+                                <div class="fed-pairing-title" x-text="request.name || request.device_id"></div>
+                                <div class="fed-pairing-meta"
+                                     x-text="request.requester_group_id ? 'Already belongs to another sync group' : (request.client_version || 'Waiting for approval')"></div>
+                                <div class="fed-device-actions">
+                                    <button class="fed-action-btn primary"
+                                            @click="$store.devices.answerFedPairing(request, true, !!request.requester_group_id)"
+                                            x-text="request.requester_group_id ? 'Use existing group' : 'Approve'"></button>
+                                    <button class="fed-action-btn"
+                                            @click="$store.devices.answerFedPairing(request, false, false)">Reject</button>
+                                </div>
+                            </div>
+                        </template>
+                        <template x-for="device in $store.devices.fedDevices()" :key="'settings-fed-' + device.device_id">
+                            <div class="settings-device-row federation">
+                                <span class="device-row-icon federation-device-icon">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">
+                                        <circle cx="12" cy="12" r="3"/>
+                                        <path d="M5.6 8.5a7.5 7.5 0 000 7M18.4 8.5a7.5 7.5 0 010 7"/>
+                                        <path d="M2.8 5.8a11 11 0 000 12.4M21.2 5.8a11 11 0 010 12.4"/>
+                                    </svg>
+                                </span>
+                                <span class="fed-device-main">
+                                    <span class="fed-device-name" x-text="device.name || device.device_id"></span>
+                                    <span class="fed-device-meta"
+                                          x-text="device.is_self ? 'This web player' : (device.client_version || 'Trusted device')"></span>
+                                </span>
+                                <button class="fed-revoke-btn"
+                                        x-show="!device.is_self"
+                                        :disabled="$store.devices.fedBusy"
+                                        @click="$store.devices.revokeFedDevice(device)">Revoke</button>
+                            </div>
+                        </template>
+                    </div>
+
+                    <div class="settings-pairing-actions">
+                        <button class="settings-primary-btn"
+                                :disabled="$store.devices.fedBusy"
+                                @click="$store.devices.generateFedInvite()">Invite a device</button>
+                        <template x-if="$store.devices.fedInvite">
+                            <input class="fed-device-input"
+                                   readonly
+                                   :value="$store.devices.fedInvite"
+                                   @focus="$event.target.select()">
+                        </template>
+                        <div class="fed-connect-row">
+                            <input class="fed-device-input"
+                                   type="text"
+                                   placeholder="Paste frid:// invite"
+                                   x-model="$store.devices.fedInviteInput"
+                                   @keydown.enter.prevent="$store.devices.connectFedInvite()">
+                            <button class="settings-secondary-btn"
+                                    :disabled="$store.devices.fedBusy || !$store.devices.fedInviteInput.trim()"
+                                    @click="$store.devices.connectFedInvite()">Connect</button>
+                        </div>
+                    </div>
+                </section>
+            </div>
+        </div>
+    </template>
+
     <!-- Play History Modal -->
     <template x-if="$store.history.modal">
         <div class="modal-overlay" @click.self="$store.history.close()">
@@ -676,14 +1074,19 @@
                                     @click.stop="$store.history.playFrom(idx)"
                                     :title="item.track?.title || item.track_title">
                                 <template x-if="item.track && item.track.cover_url">
-                                    <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
+                                    <img :src="item.track.cover_url" alt="" aria-hidden="true" loading="lazy">
                                 </template>
                                 <template x-if="!item.track || !item.track.cover_url">
                                     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="12" cy="12" r="4"/></svg>
                                 </template>
                             </button>
                             <div class="track-info">
-                                <div class="track-title" x-text="item.track?.title || item.track_title"></div>
+                                <div class="track-title">
+                                    <span x-text="item.track?.title || item.track_title"></span>
+                                    <span class="history-device-badge"
+                                          :title="item.device_id"
+                                          x-text="item.device_name"></span>
+                                </div>
                                 <div class="track-artists-inline">
                                     <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(item.track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
                                         <span>