diff --git a/docs-developers/server/api/reference.md b/docs-developers/server/api/reference.md index 83732ee..2ce20de 100644 --- a/docs-developers/server/api/reference.md +++ b/docs-developers/server/api/reference.md @@ -53,10 +53,13 @@ it the moment it pairs. `version` is stamped from the release tag (`"dev"` for l `transcode` is true only when ffmpeg is configured; `web_player` only when the `/web` mount is populated; `upload` and `websocket` are reserved for future phases and currently always false. `api_keys` is true on servers that support -user-minted [personal API keys](#personal-api-keys). `metadata` is true when the -server has [community metadata lookup](#get-apiv1librariesidmeta) configured -(`metadata.enabled` and a `metadata.base_url`); clients gate the enriched-book -section on it. +user-minted [personal API keys](#personal-api-keys). `metadata` reflects the +**runtime** state of [community metadata lookup](#get-apiv1librariesidmeta): it +is true only when a valid `metadata.base_url` is configured **and** the lookup is +switched on. An admin can flip it on or off at runtime via +[`PATCH /api/v1/admin/settings`](#patch-apiv1adminsettings) (no restart), so this +flag can change during a server's lifetime; clients gate the enriched-book +section on it and should re-read it after reconnecting. ### `GET /healthz` ยท `GET /api/v1/healthz` @@ -1314,6 +1317,56 @@ a cross-user "currently listening" feed (up to 200 rows, newest first; `title`/ } ``` +## Admin: settings + +Runtime-toggleable server settings, surfaced in the console's **Overview** +section. The envelope is a feature-keyed object so future settings can join it +without reshaping the wire contract; today it carries only `metadata`. + +### `GET /api/v1/admin/settings` + +*Admin.* Returns the current runtime settings. + +```json +{ + "metadata": { + "enabled": true, + "base_url": "https://meta.audiosilo.app", + "available": true + } +} +``` + +For `metadata`: `enabled` is the runtime on/off flag; `base_url` is the +configured metadata service URL (empty when none is set); `available` reports +whether the lookup **can** be enabled at all - true only when `base_url` is a +valid absolute `http(s)` URL. When `available` is false the feature is +permanently off until the server config gains a valid `base_url`, and any attempt +to enable it is rejected. The live `metadata` [capability](#get-apiv1server) is +`enabled && available`. + +### `PATCH /api/v1/admin/settings` + +*Admin.* Flips runtime settings and persists them to `config.yaml` (so the change +survives a restart). Send only the fields you want to change - an **absent field +is left unchanged**. Returns the same envelope as `GET` with the new state. + +```json +{ "metadata": { "enabled": false } } +``` + +Setting `metadata.enabled` to `true` when the lookup is unavailable (no valid +`metadata.base_url`) is a **`400`** - configure `metadata.base_url` first. +Toggling the flag takes effect immediately across the server: it gates +`GET /libraries/{id}/meta` and the `metadata` capability, so every connected +player starts or stops showing the enriched-book section without a restart. + +| Status | Meaning | +|---|---| +| `200` | updated; body is the current settings envelope | +| `400` | invalid body, or enabling metadata when no valid `metadata.base_url` is configured | +| `500` | the settings could not be persisted (the in-memory change is rolled back) | + ## Well-known Native deep-link association files. Both are *Public*, config-driven diff --git a/docs-developers/server/configuration.md b/docs-developers/server/configuration.md index 5764629..b749054 100644 --- a/docs-developers/server/configuration.md +++ b/docs-developers/server/configuration.md @@ -119,12 +119,22 @@ off all outbound calls. | Key | Type / default | Meaning | |---|---|---| -| `metadata.enabled` | bool, `true` | Turn the metadata lookup on. When `false`, the server makes **no outbound metadata calls**, `GET /libraries/{id}/meta` returns 404, and the `metadata` capability reports false so players hide the enriched-book section entirely | +| `metadata.enabled` | bool, `true` | Turn the metadata lookup on. When `false`, the server makes **no outbound metadata calls**, `GET /libraries/{id}/meta` returns 404, and the `metadata` capability reports false so players hide the enriched-book section entirely. Seeds the initial state only - an admin can flip this at runtime (see below) | | `metadata.base_url` | string, `"https://meta.audiosilo.app"` | Base URL of the metadata service (the site is served at `/` and the API at `/api/v1`). **Must be an absolute `http`/`https` URL when metadata is enabled** | -Turning it off is the one-key privacy switch: with `metadata.enabled: false` -the server never contacts the metadata service, and every player connected to it -stops showing the section (they gate on the `metadata` capability). Enrichment is +`metadata.enabled` is **runtime-toggleable**: an admin can switch the lookup on +or off from the console's **Overview** section (or via +[`PATCH /admin/settings`](api/reference.md#patch-apiv1adminsettings)) with no +restart, and the change is **persisted back to `config.yaml`**. The YAML value +and `AUDIOSILO_METADATA_ENABLED` only **seed** the initial state at startup; the +admin toggle is the durable source of truth thereafter. `metadata.base_url` +stays config-only - it defines whether the feature is *available* at all (a valid +absolute `http(s)` URL), and the toggle can only enable the lookup when a valid +base URL is set. + +Turning it off is the one-key privacy switch: with the lookup disabled the server +never contacts the metadata service, and every player connected to it stops +showing the section (they gate on the `metadata` capability). Enrichment is strictly additive and cached - a slow or unreachable service degrades to no section, never a broken page. diff --git a/docs-users/admin/console-tour.md b/docs-users/admin/console-tour.md index 8d41ec6..7019fe2 100644 --- a/docs-users/admin/console-tour.md +++ b/docs-users/admin/console-tour.md @@ -66,7 +66,7 @@ button, the language selector, and the server's version number. ![The Overview section with stat cards, per-library counts and the listening feed](/img/screenshots/admin/overview.png) **Overview** is the console's home screen ("Library size and what people are -listening to"). It has three parts: +listening to"). It has four parts: ### Stat cards @@ -100,6 +100,27 @@ The feed shows saved listening progress as of when you opened the Overview - reopen the section to refresh (players report progress periodically while playing). +### Community metadata lookup + +A single switch that turns the **community metadata lookup** on or off for the +whole server. When it is on, books that can be matched (they carry an ASIN or +ISBN) gain an extra "About this book" section in the player - a description, +production details, and the series they belong to - drawn from the free, +community-run catalogue at +[meta.audiosilo.app](https://meta.audiosilo.app). See +[About this book](../listening/browsing.md#about-this-book) for what listeners +see. + +- Flipping the switch takes effect immediately for **everyone connected**, and + the choice is remembered across restarts. +- Turning it **off** is a one-tap privacy switch: your server stops contacting + the metadata service at all, and the extra section disappears from every + player. +- The card also shows the **Source** - the metadata service address your server + uses. If no service is configured, the switch is greyed out and a note explains + that a service address must be set in the server configuration first (see the + metadata setting in the [configuration reference](/developers/server/configuration)). + :::note The console holds no special powers of its own - every action it performs is checked by the server against your admin account. That's also why nothing diff --git a/docs-users/listening/browsing.md b/docs-users/listening/browsing.md index 97ea1d8..5b85f33 100644 --- a/docs-users/listening/browsing.md +++ b/docs-users/listening/browsing.md @@ -59,7 +59,7 @@ Some books show an extra section below the chapters with more about the title: - A **More in this series** row - other books in the same series, each opening its page on the metadata site so you can see what to read next. - A **View on AudioSilo Meta** link to the book's full entry. -This information comes from the **AudioSilo community metadata database** at [meta.audiosilo.app](https://meta.audiosilo.app), a free, community-run catalogue of audiobook details. It appears only when the book can be matched (it carries an ASIN or ISBN) and your server has the metadata lookup switched on. If a book has no extra section, it simply isn't matched or your admin has turned the feature off - nothing else on the page changes. A server admin can disable the lookup entirely, in which case no book shows this section (see the metadata setting in the [configuration reference](/developers/server/configuration)). +This information comes from the **AudioSilo community metadata database** at [meta.audiosilo.app](https://meta.audiosilo.app), a free, community-run catalogue of audiobook details. It appears only when the book can be matched (it carries an ASIN or ISBN) and your server has the metadata lookup switched on. If a book has no extra section, it simply isn't matched or your admin has turned the feature off - nothing else on the page changes. A server admin can switch the lookup on or off at any time from the admin console's Overview section (see the [console tour](../admin/console-tour.md#community-metadata-lookup)); when it is off, no book shows this section. ## Search diff --git a/static/img/screenshots/admin/overview.png b/static/img/screenshots/admin/overview.png index ec4f39c..b65eeec 100644 Binary files a/static/img/screenshots/admin/overview.png and b/static/img/screenshots/admin/overview.png differ