Release v1.60.0

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.github/workflows/sonarqube.yml

@@ -54,6 +54,11 @@ jobs:
       - name: Build the frontend bundle
         run: node scripts/minify.mjs
 
+      # Advisory until pre-existing failures are fixed (see architecture/qa.md).
+      - name: Central QA (fast)
+        continue-on-error: true
+        run: npm run qa -- --fast
+
       - name: SonarQube scan
         uses: SonarSource/sonarqube-scan-action@v8.1.0
         env:

.gitignore

@@ -60,3 +60,9 @@ Test-Magazin/
 
 # local todo list
 TODO.md
+
+# local experiments; two files here once held key-like literals
+scratch/test_openai.py
+scratch/test_google_imagen.py
+coverage.xml
+.coverage

CHANGELOG.md

@@ -9,6 +9,46 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) · versioned wi
 
 ---
 
+## [1.60.0] — 2026-10-04
+### Added
+- **`npm run qa`**: central QA command (`scripts/qa.mjs`) with timed stages (lint, python/node unit tests, Playwright, security scans, bundle freshness) and an opt-in SonarQube stage (`--sonar`, token from the environment only). See `architecture/qa.md`.
+
+### Changed
+- `npm run qa`: pyunit gets a fresh temp HOME/CONFIG_DIR/TMPDIR per run (cleaned afterwards); `--sonar` stage also produces Python `coverage.xml` when `coverage` is installed (else SKIPPED).
+- `guided_installer.py`: command execution extracted into a testable `run_command` helper (lowers cognitive complexity, python:S3776); no behaviour change.
+- **Voice list rows no longer show the "Source unknown" badge** (it crowded the play buttons). The badge stays in the voice inspector, next to the Source & consent panel.
+
+### Fixed
+- **Magazine specs no longer touch the live settings.** The export-provenance checkboxes read and saved `/api/settings` on the real app (a run left the default off, failing the next one); the spec now mocks it. The hostile deep-link spec waits for the lazily loaded magazine module before calling the parser.
+- **Duplicate German i18n keys and dead frontend code.** Removed 14 shadowed duplicate keys in `i18n.js` (effective translations unchanged), the unreachable body of `audiobookShowPreview`, and two identical-branch ternaries.
+- **Security hardening (Sonar findings).** The Docker installer downloads `get-docker.sh` into a private `mkdtemp` dir (not a predictable `/tmp` path) and removes it afterwards; the OMDb poster lookup uses HTTPS; the fish.audio cache key marks MD5 as `usedforsecurity=False`.
+- **Background jobs could be garbage-collected mid-run.** Fire-and-forget `asyncio.create_task` calls (magazine, conversation, tts, stt, library, sources) now go through `core.tasks.spawn`, which keeps a strong reference until the task ends and logs failures by exception class only.
+- **Voice archetype gallery broke `npm run check:frontend`**: its `say` helper collided with `magazine.js`; renamed to `archSay`.
+- **Export failed with HTTP 500 when provenance tagging failed** (EPUB/ZIP/article MP3 with audio ffmpeg cannot tag); it now ships the untagged file and logs a warning.
+- **Archetype `language` filter accepted only full names.** `GET /api/archetypes?language=de` returned 0 items; it now accepts ISO codes and names, case-insensitive (`de`, `DE`, `German`); unknown values return an empty list.
+- **LibriVox search returned 502 "unavailable" after 20-30 s.** Cause: the LibriVox API is erratic (10-40 s for any request, measured from host and container; egress/DNS/TLS fine) and the old call asked for `extended=1` (all chapters of 15 books) with a 30 s timeout, mapping every failure to one generic message. Now the list is light (no `extended`), the first chapter is fetched per book on demand (`GET /api/voice-sources/librivox/book/{id}`, UI "Load preview" / on import), timeout 25 s with one retry and backoff, failures cached 30 s, distinct messages (timeout / unreachable / HTTP status / unreadable) and a privacy-safe log line (exception class and query length only). Host/redirect rules unchanged.
+- **`export_provenance_default` missing from settings defaults.** It is now in the defaults (`true`), so `GET /api/settings` exposes it.
+### Added
+- **Voice archetype gallery (own, German-first).** "Voice gallery" card in Design a Voice: 40 hand-authored named voices (mostly German, a few English) in 7 categories, each a free-text Qwen3 VoiceDesign description with facets (gender, age, pitch, accent, tone) from the design-chip taxonomy. Search, facet chips, category list, favourites (browser storage), 24 cards per page rendered only after opening, labelled Preview (aria-live status) and "Use voice" (then "Open in Design" prefills the editor). `GET /api/archetypes`, `POST /api/archetypes/{id}/preview` (cached by sha256 of instruct, language, engine and seed 42; timeouts, blank-audio guard) and `POST /api/archetypes/{id}/use` (saves voice `archetype_<id>`, origin designed, provenance basis `unknown`, source `archetype/<id>`, note "synthetic designed voice"; idempotent). Own catalog, nothing copied from other projects; no network. Optional `scripts/render_archetype_previews.py` pre-renders all previews. Tests: `tests/test_voice_archetypes.py`, `tests/archetype-gallery.spec.js`. See `architecture/voice-archetypes.md`.
+- **Audiobook emotion tests.** Playwright `tests/audiobook-emotion.spec.js` (mocked routes) covers span-cast emotion -> `instruct` in `/api/tts-preview` (dialogue only, English tag, narration empty) and the line cache key; `tests/test_tts_instruct_payload.py` covers the instruct passthrough.
+- **LibriVox and Wikimedia Commons voice sources.** New tab in Get Voices Online searches the official LibriVox feed and the Commons MediaWiki API through `GET /api/voice-sources/{librivox|wikimedia}?q=&lang=` (fixed hosts, query cap 80, 10 results, 30 s timeout, 10 min cache, 1 s throttle, descriptive User-Agent, result URLs host-checked). Results show licence and a preview; "Import clip" trims (start/length) and stores provenance (LibriVox: public domain + check-the-reader note; Wikimedia: licence + attribution). `archive.org` and `upload.wikimedia.org` added to the audio proxy allowlist. Tests: `tests/test_voice_sources_new.py`, `tests/voice-sources-new.spec.js`. See `architecture/voice-sources.md`.
+- **Provenance tags on exported audio.** Magazine MP3 downloads, `audio.zip` and the MP3s inside the EPUB get ID3 tags (`synthetic_speech=true`, `generator`, `generator_version`, `generated_date`, comment; voice name only on opt-in) via one ffmpeg stream copy of a temp copy; stored audio is untouched. Per-export checkboxes on the magazine export row ("Mark as synthetic speech", "include voice name"), default from new setting `export_provenance_default` (on). `POST /api/export/provenance` and `python -m core.export_provenance file.mp3` read the tags back. Inaudible AudioSeal watermarking is researched (MIT code and weights, torch needed, weak message recovery after MP3/AAC) but only a stub `watermark(path)` that reports unavailable. Spoken disclosure is not implemented yet. Tests: `tests/test_watermark_tags.py`, `tests/magazine.spec.js`. See `architecture/watermarking.md`.
+- **Inline text tags for TTS (setting `inline_tags_enabled`, default OFF).** `[pause 500ms]`/`[pause 1.2s]` (max 10 s each, 60 s per text), `[spell]USA[/spell]` (German letter names for German text), `[slow]..[/slow]` / `[fast]..[/fast]` (0.85 / 1.15 via ffmpeg atempo, innermost wins, unclosed ends at paragraph). Known control tags (e.g. `[laugh]`) are stripped, never spoken; `[1]` and `[sic]` stay. Rendered in `POST /api/tts-preview` (also used by audiobook line previews), `/v1/audio/speech` (non-streaming), `/speak` and the MCP speak tool through one shared `ssml_lite.render_with_tags`; stripped only (never spoken) in streaming, spoken chat replies and magazine MP3 (timings stay exact). Settings -> General switch (accessible, DE/EN) and a syntax hint under the Try It Out and Read Aloud text boxes. Tests: `tests/test_ssml_lite.py`, `tests/test_inline_tags_paths.py`, `tests/inline-tags.spec.js`.
+- **Optional vocal isolation for URL/YouTube imports (default OFF).** `POST /api/isolate-vocals {id}` runs the Demucs CLI (`htdemucs`, two stems) on a registered temp audio and registers the vocals as a new id; the original stays valid. Needs `VOCAL_ISOLATION=1`, a `demucs` binary (or `VOCAL_ISOLATION_CMD`) and the weights already on disk; the app never downloads anything and nothing is added to the main image. Limits: 15 min input, 15 min runtime (`VOCAL_ISOLATION_MAX_SECONDS`/`_TIMEOUT`), one job at a time, cancelled on client disconnect, temp files always removed. `GET /api/version` reports `features.vocal_isolation`; the "Remove background music" button (clone page URL card and voice library add-URL) appears only then, with an aria-live status and a play original / play without music toggle. Tests: `tests/test_vocal_isolation.py`, `tests/vocal-isolation.spec.js`. See `architecture/vocal-isolation.md`.
+- **Voice export/import bundles.** `GET /api/voices/{id}/export` streams a `<id>.voice.zip` (audio, `reference.txt`, `meta.json` with seed, design prompt, rating/tags, `provenance`, `audio_problems`; optional picture and consent recording; `manifest.json` with format version, app version and sha256 per file; no temp files). `POST /api/voices/import` validates at the boundary: 150 MB upload cap, fixed flat member names only (zip-slip/path traversal rejected), per-file, total and compression-ratio caps, hashes verified, audio decoded, meta and provenance re-validated; a taken name gets a `_2` suffix, an identical voice is a no-op, nothing is overwritten. Voice library toolbar: "Export selected" and "Import bundle" (44px). Tests: `tests/test_voice_bundle.py`, `tests/voice-bundle.spec.js`. See `architecture/voice-bundle.md`.
+- **Consent/provenance field per voice.** Each voice gets `provenance` in its `.meta.json` (`basis`: own_voice, consented, licensed, public_domain or unknown; `source`, `licence`, `note`, optional `recorded_consent`, `set_at`). Existing voices count as `unknown`; `quick-import-voice` prefills the source URL (basis stays `unknown`). New `PUT /api/voices/{id}/provenance` (enum, length caps, control characters stripped, http(s) URLs only, no credentials) and `POST`/`GET /api/voices/{id}/consent-recording` (audio only, 10 MB cap, stored as `<voice>.consent`, moves/deletes with the voice). The voice inspector has a "Source & consent" section (typed note or MediaRecorder recording) and voices without a recorded basis show a "Source unknown" badge. Generation is not blocked. Data stays local. Tests: `tests/test_voice_provenance.py`, `tests/voice-provenance.spec.js`.
+- **Seed Finder: Auto-pick best.** `POST /api/seed-autopick {voice, text, seeds|count}` (default 8, max 16) generates candidates sequentially through the existing temporary-voice path (voices.json is always restored), scores each 0-100 (ASR word accuracy, loudness/clipping, `audio_problems`) and returns all sub-scores plus the winner. Degrades to loudness/problems when STT is unavailable. The UI highlights the winner; saving stays a click on "Use seed". Tests: `tests/test_seed_autopick.py`, `tests/seed-autopick.spec.js`.
+- **Voice Design: attribute chips.** Toggle chips (gender, age, pitch, pace, accent/region, tone/timbre, emotion; German + English labels) above the design prompt add or remove only their own phrase in the free-text description. The textarea stays fully free-form. Test: `tests/design-chips.spec.js`.
+- **Voice health: timestamped audio problems.** `core.audio.audio_problems` flags long interior silence, clipping and sudden level jumps (`problems` list with `kind`, `start_s`, `end_s`, `detail`, plus one warning per kind) in the route-test voice health; existing keys unchanged. Computed on demand and cached by file mtime, not in the voice list. Shown in the routing test result and in the Try-out voice panel (new `GET /api/voices/{id}/health`); imports store the result in meta (`audio_problems`). Tests: `tests/test_audio_problems.py`, `tests/voice-health.spec.js`.
+
+### Docs
+- **Audiobook emotions** section in `Manual.md` (filling, editing, voice types that honour them, limits) and an Emotions section in `architecture/audiobook-attribution.md`.
+
+### Changed
+- **Magazine interviews: journalist/guest voices.** Interview labels such as `c't:` (also `c’t`, `ct`, OCR `Cc't`), `Redaktion`, `Interviewer`, `Frage` are the interviewing side and are read in the narrator voice; every other recurring label is a guest and gets the second voice. Unlabelled blocks continue the current speaker's turn; headings, decks and bylines stay narrator. Detection stays strict (label starts a block and recurs at least twice). Audio-timing records now store each segment's voice and speaker. Tests: `tests/test_magazine.py` (`InterviewJournalistTests`).
+
+---
+
 ## [1.59.0] — 2026-10-04
 ### Changed
 - **Characters: global cast view in the sidebar, per-book characters inside Studio.** *Library > Characters / Cast* is now titled "All characters (all books)": one collapsible band per book (heading, per-book count, `aria-expanded`), first book open and the rest closed and not rendered until opened (DOM budget), and a *Search all books* field. Studio > Voices lists only the book picked in *Source*, under a "Book: <title>" chip with **Show characters of all books**; the Characters step shows the same chip; with no book picked Voices shows a prompt (Pick a book / show all books). Per-book actions stay in the band headers. Tests: `tests/characters-scope.spec.js`.
@@ -4708,7 +4748,8 @@ Initial feature-complete release.
 
 ---
 
-[Unreleased]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.59.0...HEAD
+[Unreleased]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.60.0...HEAD
+[1.60.0]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.59.0...v1.60.0
 [1.59.0]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.58.0...v1.59.0
 [1.58.0]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.57.0...v1.58.0
 [1.57.0]: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2/compare/v1.56.3...v1.57.0

PROJECT_MAP.md

@@ -56,6 +56,7 @@ Two self-hosted Docker instances, both port 7890:
 | Area | Server | Frontend | State |
 |---|---|---|---|
 | Voice library / clone / design | `routes/library.py`, `core/voice.py` | `library.js` | mature |
+| Voice archetype gallery (40 own German-first design voices, cached previews) | `core/voice_archetypes.py`, `routes/archetypes.py` | `voice-archetypes.js`, `s-design.html` | **new** — see [architecture/voice-archetypes.md](architecture/voice-archetypes.md) |
 | Read Aloud (books, PDFs) | `routes/reader.py` | `reader.js` | mature |
 | Audiobook casting (span mode: deterministic quote spans, LLM names speakers only; verify/recast) | `routes/conversation.py`, `core/attribution_spans.py` | `audiobook*.js`, `audiobook-spans.js`, `audiobook-cast-spans.js` | **new 2026-09-19** — see [architecture/audiobook-attribution.md](architecture/audiobook-attribution.md) |
 | Characters (avatar/concept identity, appearance forms) | `routes/characters.py`, `routes/conversation.py` | `library-characters.js`, `character-sheets.js` | **reworked 2026-09-19** — see [architecture/character-visual-identity.md](architecture/character-visual-identity.md) |
@@ -91,6 +92,8 @@ which is the writable volume.
 | `ALIGNER_URL` | forced-aligner sidecar for word timing (`http://tts-aligner:8000`; empty = off) |
 | `llm_url` / `llm_model` / `llm_api_key` | settings.json, OpenAI-compatible LLM |
 
+QA: `npm run qa -- --fast` runs lint, unit, security, build checks (see `architecture/qa.md`); optional `--sonar` needs `SONAR_HOST_URL` + `SONAR_TOKEN` in the shell/CI secrets.
+
 ## Pending decisions
 
 - Container registry: ghcr costs quota against a private package (≈427 MB per

VERSION

@@ -1 +1 @@
-1.59.0
+1.60.0

architecture/audiobook-attribution.md

@@ -142,6 +142,20 @@ just before it) gave +0.3 points — noise — and was not adopted.
 Request additions: `attribute_only` `[ids]` — the other spans are context; unrequested lines are never
 reported missing.
 
+## Emotions
+
+`/api/attribute-spans` returns `{speaker, emotion}` per dialogue id (1-2 words in the book's language; narration ids never
+get one). Path to audio: segment `emotion` -> `audiobookBuildScript` / `rehState.lines[].emotion` -> `audiobookLineVoice`
+-> `_buildInstruct` (English clause; German words via `_rehEmotionEnglishTag`) -> `fetchTtsPreviewBlob` ->
+`payload["instruct"]` (`core/tts_helpers.py`). The line audio cache key includes the instruct, so an edited emotion never
+serves stale audio. Fish-Speech uses `_rehInlineTone` ([tag]) instead.
+
+Limits: engine support differs (`routes/tts.py` `_backend_capabilities`: `voice_clone` style_aware false, instruct may be
+ignored; `voice_design` strong). Span-mode LLM failure leaves emotion empty. A custom attribution prompt is ignored in span
+mode. The merge pass keeps one emotion per block. Tests: `tests/audiobook-emotion.spec.js`,
+`tests/test_tts_instruct_payload.py`. No per-voice UI hint yet: the voice is only chosen later in the Rehearser, which already
+shows a tone warning for non-style-aware backends.
+
 ## Security / privacy
 
 Book text is sent to the configured LLM exactly as before (same endpoint, same settings);

architecture/inline-tags.md

@@ -0,0 +1,27 @@
+# Inline text tags (feature flag `inline_tags_enabled`, default off)
+
+Engine-independent preprocessing in `core/ssml_lite.py` (pure parser plus `render`). Our engines have no native tags, so the app splits text, synthesises each piece and joins the audio itself. Idea only is borrowed from other tools; no third-party code.
+
+## Syntax
+| Tag | Effect |
+|---|---|
+| `[pause 500ms]`, `[pause 1.2s]` | generated silence; max 10 s each, 60 s per text; invalid argument is dropped |
+| `[spell]USA[/spell]` | letters spoken one by one (`U S A`; German letter names `Uh Ess Ah` when language is German) |
+| `[slow]..[/slow]`, `[fast]..[/fast]` | speed factor 0.85 / 1.15 via ffmpeg `atempo` (`core.audio._change_tempo`) on the rendered segment; innermost wins |
+
+Unclosed `[slow]`/`[fast]`/`[spell]` end at the paragraph break (blank line).
+
+## Stripping rule
+Only these names are removed and never spoken (opening or closing, optional short argument): the four tags above plus `laugh(s/ing) chuckle sigh gasp cough breath breathe inhale exhale whisper shout music sfx noise beat silence emphasis excited sad angry happy calm sniff gulp clears_throat`. Everything else in brackets (`[1]`, `[sic]`, `[Anm.]`) is ordinary prose and untouched.
+
+## Flow
+`parse(text, language)` -> segments `{text, speed, pause_ms}` (tags never reach a segment, so any sentence chunker run on a segment cannot cut a tag) -> `render()` synthesises per segment, stretches, joins with silence -> one WAV. Duration therefore already includes pauses and stretching.
+
+## Coverage
+`ssml_lite.render_with_tags(text, synth, language, enabled)` is the one shared entry (plain `synth(text)` unless enabled and tagged); async routes bridge to it through `routes.tts._generate_with_tags`.
+- Rendered: `POST /api/tts-preview` (normal generate; audiobook line previews and Read Aloud call it from the browser, there is no server-side audiobook synthesis), `POST /v1/audio/speech` non-streaming branches (virtual, voice_design, magpie, nvidia, fish, default), `/speak` and the MCP speak tool. Route sounds and `_prepare_proxy_audio` run after rendering, so durations include pauses.
+- Stripped only (`plain_text`, never spoken): streaming `/v1/audio/speech`, sentence-streamed chat replies (`_make_tts_task`; a tag cut by the sentence splitter before it reaches the task can leak), seed-finder calls.
+- Magazine MP3 (`synthesize_article_audio`): tags are stripped from each prepared segment before sentence splitting, never rendered. Reason: `write_audio_timings` records per-sentence spans and character counts; inserted silence or stretched clips would need extra span types. Spans are measured on the audio actually joined, so they stay exact.
+- Off (default): text is passed through unchanged, tags are spoken literally.
+Engine speed params are not used: `atempo` works the same for every engine.
+Rollback: set `inline_tags_enabled` to false (Settings -> General switch).

architecture/magazine-ingestion.md

@@ -963,3 +963,7 @@ gets `audio_stale: true` with `audio_stale_reason`. Audio and timing files are *
   `static/js/magazine.js` and is not fixed here. Until it is, new stand-ins can appear.
 * Reading order across a page that holds two articles relies on the existing per-page order. A
   wrong page order gives a wrong *previous entry*.
+
+## Interview voice slots
+
+`interview_tts_segments` returns `{speaker, text, slot}` per block (slot 0 = narrator voice, 1 = second voice). A label must start a block and recur at least twice. Labels in `INTERVIEW_JOURNALIST_LABELS` (`c't`, `ct`, `redaktion`, `interviewer`, `frage`; apostrophes normalised, OCR `Cc't` folded) get slot 0; all other recurring labels get slot 1. With no journalist label, exactly two recurring labels are required and the first seen gets slot 0. Unlabelled blocks continue the current speaker; title/heading/deck/byline/figure_description reset to narrator. `write_audio_timings` records `voice` and `speaker` per segment.

architecture/qa.md

@@ -0,0 +1,51 @@
+# QA: `npm run qa`
+
+Developer-facing. Single entry point: `scripts/qa.mjs` (Node, no dependencies). Every stage is timed; a summary table is printed and the exit code is non-zero if any stage FAILs. SKIPPED never fails the run. Nothing is ever installed automatically.
+
+```bash
+npm run qa -- --fast        # everything except Playwright
+npm run qa                  # full, incl. Playwright (desktop + iphone)
+npm run qa -- --only e2e --grep voice-provenance
+npm run qa -- --sonar       # add the SonarQube stage
+npm run qa -- --list
+```
+
+## Stages
+
+| id | what | skipped when |
+|----|------|--------------|
+| format | formatter check | always for now (no formatter configured) |
+| lint | `node --check` over tracked static/js, scripts, tests mjs; `npm run check:frontend`; python `compileall`; `ruff` if installed | ruff missing -> noted only |
+| types | type check | no type checker configured |
+| pyunit | `unittest discover -s tests -p 'test_*.py'` with a temp `HOME`/`CONFIG_DIR` (avoids the `/home/app` permission error, never touches live data) | never |
+| nodeunit | `npm run test:unit` | never |
+| e2e | Playwright, projects `desktop` + `iphone`; `--grep` supported | `--fast` |
+| a11y | axe-core specs | axe-core not installed (recommend `npm i -D @axe-core/playwright`, add `tests/a11y.spec.js`) |
+| security | `npm audit --audit-level=high`, `pip-audit` (if installed + requirements.txt), secret scan (gitleaks if present, else built-in regexes over tracked files) | audits: network failure -> SKIPPED, not FAIL |
+| build | `npm run minify`, fails if `static/dist/main.min.js` changed (stale bundle; commit the regenerated file) | never |
+| perf | DOM budget is `tests/constrained.spec.js`, runs inside e2e | always (no separate stage) |
+| sonar | `sonar-scanner` with `sonar-project.properties` | no `--sonar`, or `SONAR_HOST_URL`/`SONAR_TOKEN` unset, or scanner missing |
+
+## Test isolation
+
+Playwright `baseURL` defaults to the live container (`http://localhost:7890`, override with `BASE_URL`). The specs mock every `/api/**` route (the live server only serves static files and the page), so no live data is written; use a throwaway instance via `BASE_URL` when in doubt. `--fast` never touches it. The secret scan prints only `file:line pattern-name`, never the match.
+
+## Isolation and coverage
+
+- `pyunit` and the coverage run each get a fresh `mkdtemp` HOME/CONFIG_DIR/TMPDIR (`isolatedPyEnv` in `scripts/qa.mjs`), removed afterwards. Stages run strictly sequentially, so e2e and pyunit never overlap.
+- Sonar stage: if `python3 -c 'import coverage'` works, it runs `coverage run -m unittest discover ...` and writes `coverage.xml` (read via `sonar.python.coverage.reportPaths`). Otherwise it prints SKIPPED; install with `pip install coverage`.
+- JS coverage is NOT collected. Playwright-driven coverage needs c8/V8 instrumentation of the served bundle (e.g. `page.coverage` + `v8-to-istanbul` -> `sonar.javascript.lcov.reportPaths`). Owner decision pending.
+
+## SonarQube / secrets
+
+`SONAR_HOST_URL` and `SONAR_TOKEN` are read from the environment only (shell or CI secrets). They are never written to files, argv or output (the scanner reads the token itself; output is redacted). The quality gate is awaited via `-Dsonar.qualitygate.wait=true`; no separate web API call is made.
+
+## CI
+
+`.github/workflows/sonarqube.yml` already runs compile/unittest/frontend/build steps and the Sonar action (token from `${{ secrets.SONAR_TOKEN }}`). An advisory (`continue-on-error`) `npm run qa -- --fast` step was added. Make it blocking once the pre-existing failures below are fixed.
+
+## Known pre-existing failures (2026-10-04)
+
+- `check:frontend`: duplicate top-level `say` in `static/js/voice-archetypes.js` and `static/js/magazine.js`.
+- `test_epub_export.EndpointTests.test_downloads_a_valid_epub`.
+- Secret scan: tracked `scratch/test_openai.py` and `scratch/test_google_imagen.py` contain key-like literals; rotate if real and remove from history/tracking.

architecture/seed-autopick.md

@@ -0,0 +1,6 @@
+# Seed auto-pick
+
+- `POST /api/seed-autopick` (routes/tts.py) validates input (`core/seed_score.seed_list`: explicit seeds 0-9999 or `count` 1-16, default 8), then for each seed calls `_seed_finder_request_audio` in a worker thread (shared `_SEED_FINDER_VOICE_LOCK`, voices.json restored in its `finally`), scores it in a second thread and moves on. Per-candidate timeout 240 s; a timeout ends the run (the worker still holds the lock until it restores). Client disconnect is checked between candidates (cancel = abort the fetch).
+- Scoring: `core/seed_score.py` (constants at top, formula in the docstring). Sub-scores come from `routes.stt._transcribe_audio` + `_word_accuracy` (imported lazily), `core.audio._loudness_info`, `core.audio.audio_problems`. First STT failure disables ASR for the rest of the run (`degraded: true`, `stt.note`).
+- Never saves. The UI confirms via the existing `/api/tts-voice-seed`.
+- Limits: sequential, so 16 candidates take minutes; audio returns base64 in the JSON (about 0.5 MB each).

architecture/vocal-isolation.md

@@ -0,0 +1,42 @@
+# Vocal isolation for URL/YouTube imports
+
+Status: implemented behind a flag, default OFF. Goal: remove music/background from a downloaded
+clip before trimming and cloning (`/api/download-yt` -> `/api/isolate-vocals` -> trim -> `quick-import-voice`).
+
+## Findings (read-only inspection, 2026-10-04)
+- App image: `python:3.11-slim-bookworm`, `requirements.txt` has no torch/onnx/demucs. The live app
+  container has no `torch` (`import torch` fails). It is `read_only: true`, `cap_drop: ALL`, 8 GB mem
+  limit, no GPU reservation. Source dirs are bind-mounted read-only.
+- GPU/torch live in other service containers (tts-faster-qwen3-*, aligner, ...), not reusable: different
+  images, no shared API for source separation.
+- There is no VAD, denoise or separation anywhere in the app today.
+
+## Options
+| Option | Footprint | Verdict |
+|---|---|---|
+| Demucs `htdemucs` (MIT code; weights MIT, ~80 MB, from dl.fbaipublicfiles.com via torch hub) in the main image | torch + torchaudio on ARM64 ~ 2-3 GB image growth | rejected: heavy, unconditional |
+| Demucs in a separate sidecar container | no growth of main image, GPU optional | best long-term, but needs a new image, compose service and network contract |
+| **Optional external Demucs CLI**, called as a subprocess, only when the flag is on and the binary + weights exist | zero deps in the main image; the owner picks where Demucs lives (venv on a bind mount, or a derived image) | **chosen** |
+| Lighter: RNNoise/DeepFilterNet/spectral gating | small, but removes noise only, not music/singing | does not meet the goal |
+
+Why the CLI: `demucs --two-stems=vocals -n htdemucs` is the stable public interface; no import-time cost,
+no behaviour change when absent. ARM64: `torch`/`torchaudio` publish aarch64 wheels (CUDA wheels exist for
+DGX Spark / GB10; CPU wheels work everywhere), `demucs` itself is pure Python (`pip install demucs`).
+A sidecar can later expose the same CLI via `VOCAL_ISOLATION_CMD` (e.g. `docker exec ...` wrapper) without code changes.
+
+## Safety rules
+- `VOCAL_ISOLATION=1` required; otherwise the feature reports unavailable and the API answers 503.
+- Available only if the command resolves AND the htdemucs weights file (`955717e8-*.th`) is already in
+  `$TORCH_HOME/hub/checkpoints` (default `~/.cache/torch`). The app never downloads weights: the owner
+  installs them once (documented in Manual.md). This prevents Demucs' silent first-run download.
+- Input bounded to `VOCAL_ISOLATION_MAX_SECONDS` (default 900), runtime to `VOCAL_ISOLATION_TIMEOUT`
+  (default 900 s), one job at a time (409 when busy), client disconnect cancels and kills the process.
+- Work happens in a private temp dir that is always removed; the result is converted to 24 kHz mono WAV
+  and registered as a new temp id. The original id is untouched (compare / undo in the UI).
+- Subprocess started with an argument list (no shell); the path comes from the registry, never from the client.
+
+## Contract
+- `GET /api/version` gains `features.vocal_isolation: bool`.
+- `POST /api/isolate-vocals {id}` -> `{id, duration}`. Errors: 400 bad id, 404 unknown id, 413 too long,
+  409 busy, 503 disabled/unavailable, 504 timeout, 500 failed (message without internals).
+- Offline behaviour: fully local; no network access.

architecture/voice-archetypes.md

@@ -0,0 +1,18 @@
+# Voice archetype gallery
+
+Code: `core/voice_archetypes.py` (catalog + filter), `routes/archetypes.py`, UI `static/js/voice-archetypes.js` (core module) + card in `static/sections/s-design.html`.
+
+**Catalog:** 40 entries authored here (no third-party data or code). Fields: `id`, `name_de`, `name_en`, `instruct` (free-text Qwen3 VoiceDesign description; German prompts transliterated to ASCII like the existing design presets), `category` (7 fixed), `language` (German/English), `facets` {gender, age, pitch, accent, tone} from the `DESIGN_CHIPS` vocabulary, `sample_script_de/en` (per category). Validated at import: unknown facet, category, language or duplicate/odd id raises ValueError (unit-tested).
+
+**API**
+- `GET /api/archetypes?gender&age&pitch&accent&language&category&q&offset&limit` -> `{total, items, categories, cached}`; limit capped at 100, q at 100 chars.
+- `POST /api/archetypes/{id}/preview` -> WAV. Cache `<CONFIG_DIR>/archetype_previews/<sha256(instruct|language|engine|seed)[:32]>.wav`; engine is the configured voice-design model, seed fixed to 42 (injected as extra param for this call only). Rendering goes through `_voice_design_request_audio` inside the shared bounded TTS queue, 240 s timeout, per-key lock, size cap 8 MB, blank/too-short audio rejected (502), atomic write. Cache is naturally bounded by the catalog size.
+- `POST /api/archetypes/{id}/use` -> saves voice `archetype_<id>` (normalized WAV from the cached preview, reference text = sample script, meta `origin: designed`, `voice_design_prompt`). Idempotent: an existing voice returns `created: false`.
+
+**Provenance choice:** `core/provenance.BASES` has no "synthetic" value, so basis is `unknown` (closest; nothing to consent to), `source` `archetype/<id>` (a `:` would be parsed as a URL scheme and rejected), `note` "synthetic designed voice".
+
+**UI:** the card is a collapsed `<details>`; nothing is fetched or rendered until opened (DOM budget). 24 cards per page ("Load more"), favourites in localStorage (guarded), DE translations in `i18n.js`.
+
+**Pre-render:** `scripts/render_archetype_previews.py` calls the preview endpoint for every entry (sequential, idempotent). No API key needed: the API-key gate accepts same-origin requests, so the script sends `Origin: <base>`; only local/LAN bases accepted.
+
+Not done: per-archetype audio shipped in the repo, user-defined archetypes, community import.

architecture/voice-bundle.md

@@ -0,0 +1,13 @@
+# Voice export/import bundles
+
+Code: `core/voice_bundle.py`; routes in `routes/library.py` (`GET /api/voices/{id}/export`, `POST /api/voices/import`); UI in `static/js/voice-library.js` + toolbar in `static/sections/s-voices.html`.
+
+Format (v1), flat ZIP, fixed member names only: `manifest.json`, `audio.<wav|mp3|m4a|flac|ogg|opus>`, `meta.json`, `reference.txt`, `picture.<jpg|jpeg|png|webp>`, `consent.<audio ext>`. Manifest: `format` (1), `app_version` (from `VERSION`), `voice_id`, `files` {member: sha256}. One voice per bundle; multi-select exports one bundle per voice. `meta.json` is the voice sidecar plus `audio_problems`; `provenance.recorded_consent` is only kept when a consent member exists.
+
+Export: streamed through a non-seekable ZIP writer (no temp files); manifest is written last so hashes are computed while streaming.
+
+Import threat model (bundle is hostile): upload cap 150 MB (`_copy_limited`); member names must be in the fixed set, so absolute paths, `..`, subdirectories and unknown extensions are rejected before anything is read; names are never used as paths (staged under fixed names in a hidden `.import-*` dir inside the voices dir, removed in `finally`); declared sizes are checked and real bytes are re-capped while reading; total uncompressed 200 MB, ratio cap 200 for members over 1 MB; manifest must list exactly the members and every sha256 must match; voice id must match `[A-Za-z0-9_-][A-Za-z0-9_.-]{0,99}`; audio must decode; `meta.json` goes through `_validate_voice_meta` and `validate_provenance` (set_at is reset). Nothing is executed.
+
+Name handling: never overwrite. Same id with identical audio hash -> `unchanged` (idempotent). Otherwise `_2`, `_3`, ... (max 99) -> `renamed`. Installed into the active voices dir and added to the voice index.
+
+Not done: no signature (hashes detect corruption/tampering of members but not a re-built manifest); explicit overwrite/skip choice; one request per bundle for multi-file import.

architecture/voice-health.md

@@ -0,0 +1,7 @@
+# Voice health and audio problems
+
+- `core/voice.py::_voice_health(p, analyze=False)` returns the metadata checks (`ok`, `warnings`, `duration`, `word_count`, `words_per_sec`, `loudness`) plus `problems`.
+- `core/audio.py::audio_problems` decodes with pydub in 50 ms chunks (first 120 s only) and returns `[{kind: silence|clipping|level_jump, start_s, end_s, detail}]`. Thresholds are `PROBLEM_*` constants. No new dependencies.
+- Cost model: decoding is the expensive part, so the voice list never analyses (`analyze=False` returns `meta["audio_problems"]`, empty if absent). Fresh analysis runs for `GET /api/voices/{id}/health` and the routing test, cached in-process by (path, mtime). Imports store the result in meta in `routes/sources.py::_prepare_imported_voice`; failures there never block the import.
+- UI: `fmtAudioProblems` (static/js/utils.js) renders text for the routing result and the Try-out voice panel (`#preview-match-problems`, `role=status`).
+- Limits: heuristics (RMS/peak per chunk); legacy voices show problems only after the health endpoint is called.

architecture/voice-provenance.md

@@ -0,0 +1,13 @@
+# Voice provenance and consent
+
+Data: `provenance` object in `<voice>.meta.json`: `basis` (own_voice | consented | licensed | public_domain | unknown), `source`, `licence`, `note`, `recorded_consent` (original filename of the consent clip, set only by the upload route), `set_at` (UTC ISO). Absent means `unknown`.
+
+Validation: `core/provenance.py` (`validate_provenance`) at the API boundary and again in `_validate_voice_meta` on every meta save: enum, length caps (source 500, licence 300, note 1000), control characters stripped, URL-looking sources must be http(s) without credentials.
+
+API: `PUT /api/voices/{id}/provenance`; `POST|GET /api/voices/{id}/consent-recording` (audio ext + audio MIME, 10 MB cap, atomic write to `<voice>.consent`, served with `nosniff`/no-store). The clip is part of the voice package (`_voice_package_paths`), so rename/move/trash carry it.
+
+Imports: `quick-import-voice` sets `provenance` via `import_provenance(page_url or audio_url)`; basis stays `unknown`.
+
+UI: `static/js/voice-inspector.js` ("Source & consent" panel, `provenanceBadge`), list badge in `voice-library.js`.
+
+Not done: gating generation/agentic use on basis (see TODO.md); consent clip is not cryptographically bound to the voice.

architecture/voice-sources.md

@@ -0,0 +1,30 @@
+# Voice sources: LibriVox and Wikimedia Commons
+
+Status: implemented. Code: `core/open_voice_sources.py`, routes in `routes/sources.py`, UI in `static/js/voice-sources.js` (tab "LibriVox & Wikimedia" in Get Voices Online).
+
+## Verified API facts (checked 2026-10-04, docs and live calls)
+LibriVox
+- `GET https://librivox.org/api/feed/audiobooks?title=^<q>&format=json&limit=15` (light list, no `extended`; the API takes 10-40 s even so). Audio is resolved per book on demand: `?id=<n>&format=json&extended=1`, first section whose `listen_url` is on an allowed host, exposed as `GET /api/voice-sources/librivox/book/{id}` (`{audio_url, section, reader, duration}`). Upstream calls: timeout 25 s, one retry after 1.5 s, failures cached 30 s, 502 messages distinguish timeout / unreachable / HTTP status / unreadable; logs carry exception class and query length only. A bare `title=` is an EXACT match (404 `{"error":...}` otherwise); the `^` prefix gives a prefix match. No language parameter: the language is filtered client-side on `language` ("English"). `extended=1` adds `sections[]` with `listen_url` (archive.org MP3, 64 kbps), `playtime` (s) and `readers[]`.
+- The docs state no rate limit and no terms. The extended feed is slow (about 14 s for 5-25 books), so timeout is 30 s, limit 15, results cached 10 min, one upstream call per second.
+- Licence (librivox.org/pages/public-domain): recordings are donated to the public domain, use without permission or attribution allowed (credit appreciated). Caveats: guaranteed public domain only under US law; source texts are pre-1923 works; translations are separate works; readers are volunteers and the page of a project may show a reader-specific note, so the UI/provenance note tells the user to check the reader's declared licence. A reader's voice is still a person's voice: public domain is not consent for voice cloning of a recognisable person; the provenance basis is a record, not a legal clearance.
+- Audio is hosted on archive.org (`www.archive.org/download/...` redirects to `iaNNN.us.archive.org`).
+
+Wikimedia Commons
+- `GET https://commons.wikimedia.org/w/api.php?action=query&generator=search&gsrnamespace=6&gsrsearch=filetype:audio <q>&prop=imageinfo&iiprop=url|extmetadata|mediatype&maxlag=5`. Per-file `extmetadata`: `LicenseShortName`, `LicenseUrl`, `Artist` (HTML, stripped), `AttributionRequired`. `inlanguage:` does not filter audio files, so `lang` is ignored for Wikimedia.
+- Etiquette (mediawiki.org API:Etiquette): descriptive User-Agent with contact info is mandatory, requests serial, use `maxlag`, back off on errors; clients can be blocked without notice. Our UA is `TTSVoiceCreator/1.0 (self-hosted voice library; official-API client)` (no personal data; Wikimedia prefers a contact URL/email, set one via a future env var if blocked or high volume).
+- Licences are per file. Attribution duties: CC BY and CC BY-SA require author, title, licence (with link) and a note of changes (trimming/cloning counts); CC BY-SA also requires derivatives under the same licence (a cloned voice model is arguably a derivative: treat as unresolved, prefer CC0/public domain/CC BY for anything published). Public domain/CC0: none. Some files carry non-copyright restrictions (personality rights).
+
+## NOT safe / not done
+- No HTML scraping of librivox.org, archive.org or commons pages; JSON APIs only.
+- No user-supplied URLs: API hosts are constants; every URL from a response must be https on an allowlisted host (`archive.org`, `upload.wikimedia.org`, page hosts `librivox.org`, `commons.wikimedia.org`) or the item is dropped. `quick-import-voice` with `source_kind` re-checks the audio host.
+- Redirects are not followed for API calls; generic `/api/proxy-audio` (existing) follows redirects and now also allows the two audio hosts.
+- Files without a licence in `extmetadata` are dropped. The licence string is trusted from Commons metadata and can be wrong; the user must still check.
+- Licence/attribution values sent by the browser at import are only length-capped, not re-fetched (single-user LAN tool).
+
+## Endpoints
+`GET /api/voice-sources/{librivox|wikimedia}?q=&lang=` : `q` required, max 80 chars, control chars stripped; `lang` 2-3 letters; max 10 items; 400 on bad input, 502 with a generic message on upstream failure. Item: `{source, book_id (librivox), title, reader, author, language, duration (s), licence, licence_url, source_url, audio_url (librivox: empty until resolved), attribution}`. Privacy: the query goes to librivox.org / commons.wikimedia.org; previews and import go to archive.org / upload.wikimedia.org (via this server).
+
+`POST /api/quick-import-voice` accepts `source_kind` (`librivox`|`wikimedia`), `licence`, `attribution`, `page_url`, `start`, `length` (clip, 3-120 s, default 0/30). Provenance: LibriVox -> `public_domain`, source = book page, note says to check the reader's licence. Wikimedia -> `licensed` (or `public_domain` when licence says public domain/CC0), licence, note `Attribution: ...`; `meta.attribution` also stored.
+
+## Cache and throttle
+In-process dict, TTL 600 s, max 200 entries (evict oldest); per-source lock with at least 1 s between upstream calls. Lost on restart; fine for one container.

architecture/watermarking.md

@@ -0,0 +1,26 @@
+# Provenance tags and watermarking for exported audio
+
+Status: tier 1 implemented (`core/export_provenance.py`); tier 2 (AudioSeal) stubbed, not installed.
+
+## Research (checked 2026-10-04)
+
+**AudioSeal (facebookresearch/audioseal)**
+- Licence: README states code AND model weights are MIT ("full MIT license, including the license for the model weights", since April 2024). Commercial use allowed. Verdict: licence acceptable.
+- Requirements: Python >= 3.8, PyTorch >= 1.13, OmegaConf, NumPy (einops for streaming). Weights are fetched from the Hugging Face hub on first use (network download, so must be baked in or mounted for an offline box).
+- ARM64/CPU: the host has torch 2.10 (aarch64, cu130), but the app image has no torch (nothing in Dockerfile/requirements). The generator is a small conv/LSTM net at 16 kHz and runs on CPU; no CPU benchmark was found in the docs, so cost per hour of audio is unverified (measure before promising). Docs flag torchaudio backend quirks (needs `soundfile` or torchaudio 2.1).
+- Robustness (paper "Proactive Detection of Voice Cloning with Localized Watermarking", arXiv 2401.17264, and third-party comparisons): detection (is-watermarked) stays high under MP3/AAC (mean AUC about 0.97; 128 kbps AAC detection 1.0), but exact recovery of the 16-bit message under AAC 128k falls to about 0 and newer comparisons report < 60% message accuracy under MP3/AAC. So: only "watermarked yes/no" is dependable after re-encode, not a voice/version id.
+- What is detectable: per-sample (1/16000 s) localized probability that audio was watermarked, plus optional 16-bit message. Needs the AudioSeal detector (python+torch); no public third party checks it. Trained at 16 kHz, resampling needed for 22-44 kHz audio. Adversarial removal is possible.
+
+**Tier 1 alternatives (no dependencies)**
+- Provenance tags in the container (ID3v2.3 TXXX/COMM via ffmpeg `-metadata`): `synthetic_speech=true`, `generator`, `generator_version`, `generated_date`, optional `voice` (name only), `comment`. Honest, trivially strippable, survives only while the container is kept.
+- Spoken disclosure ("Dieses Hörbuch wurde synthetisch erzeugt"): not strippable by metadata removal, but needs a TTS call plus a re-encoding concat; NOT implemented yet (see Open decisions).
+
+## Design
+
+1. Tier 1 (implemented): on export, one ffmpeg stream copy (`-c copy -map_metadata 0 -id3v2_version 3`) of the MP3 into a temp copy with the tags. The stored article audio is never changed. Applies to: single article download, `audio.zip`, and the MP3s inside the EPUB. Query `?provenance=1|0` and `&voice=1` per export; absent -> setting `export_provenance_default` (default true). No user names, paths or secrets are written; voice only when opted in, basename only; ffmpeg errors are not forwarded (they can contain paths).
+2. Verify: `POST /api/export/provenance` (raw audio body, 100 MB cap) returns the tags and `synthetic`; CLI `python -m core.export_provenance file.mp3` (exit 0 if tagged).
+3. Tier 2: `watermark(path)` raises `NotImplementedError`; `watermark_available()` is False. Enabling it later means: optional extra image/venv with torch + audioseal and pre-mounted weights, a feature flag, lazy import inside `watermark()`, and a decision on re-encode (watermark must be applied to PCM before the MP3 encode, i.e. at synthesis time, not on the finished MP3 copy).
+
+## Open decisions
+- Spoken disclosure: render once per language via the normal TTS path and concat at export (re-encode) - needs owner go-ahead.
+- Tier 2: needs torch in a sidecar container (not the main image); recommended only if an inaudible mark is really required, given weak message recovery after AAC/MP3.

core/audio.py

@@ -138,6 +138,78 @@ def _loudness_info(path: Path) -> dict:
     }
 
 
+# Audio problem detection (voice health). Thresholds are module constants.
+PROBLEM_CHUNK_MS = 50
+PROBLEM_MAX_S = 120            # bounded cost: only the first 2 minutes are scanned
+PROBLEM_SILENCE_DB = -50.0
+PROBLEM_SILENCE_MIN_S = 1.5
+PROBLEM_CLIP_DB = -0.1
+PROBLEM_CLIP_MIN_S = 0.1
+PROBLEM_JUMP_DB = 15.0
+PROBLEM_JUMP_WIN = 10          # chunks per level window (0.5 s)
+
+
+def audio_problems(src) -> list[dict]:
+    """Timestamped problems: long interior silence, clipping, sudden level jumps.
+
+    `src` is a path or an AudioSegment. Returns [{kind, start_s, end_s, detail}].
+    """
+    seg = src if isinstance(src, AudioSegment) else AudioSegment.from_file(str(src))
+    seg = seg.set_channels(1)[: PROBLEM_MAX_S * 1000]
+    step = PROBLEM_CHUNK_MS
+    rms, peak = [], []
+    for pos in range(0, len(seg), step):
+        ch = seg[pos:pos + step]
+        d, m = ch.dBFS, ch.max_dBFS
+        rms.append(d if d != float("-inf") else -90.0)
+        peak.append(m if m != float("-inf") else -90.0)
+
+    def runs(flags, min_chunks):
+        out, i = [], 0
+        while i < len(flags):
+            if flags[i]:
+                j = i
+                while j < len(flags) and flags[j]:
+                    j += 1
+                if j - i >= min_chunks:
+                    out.append((i, j))
+                i = j
+            else:
+                i += 1
+        return out
+
+    t = lambda i: round(i * step / 1000.0, 2)
+    problems: list[dict] = []
+    n = len(rms)
+    speech = [i for i, d in enumerate(rms) if d > PROBLEM_SILENCE_DB]
+    first, last = (speech[0], speech[-1]) if speech else (0, -1)
+    for a, b in runs([d <= PROBLEM_SILENCE_DB for d in rms], int(PROBLEM_SILENCE_MIN_S * 1000 / step)):
+        if a > first and b <= last:  # leading/trailing silence is normal
+            problems.append({"kind": "silence", "start_s": t(a), "end_s": t(b),
+                             "detail": f"{(b - a) * step / 1000:.1f}s of silence"})
+    for a, b in runs([m >= PROBLEM_CLIP_DB for m in peak], int(PROBLEM_CLIP_MIN_S * 1000 / step)):
+        problems.append({"kind": "clipping", "start_s": t(a), "end_s": t(b),
+                         "detail": f"peak at {max(peak[a:b]):.1f} dBFS"})
+    w = PROBLEM_JUMP_WIN
+    mean = lambda xs: sum(xs) / len(xs)
+    cand = []  # (index, delta) where adjacent windows differ enough; keep the strongest per cluster
+    for i in range(w, n - w + 1):
+        before, after = rms[i - w:i], rms[i:i + w]
+        if min(before) > PROBLEM_SILENCE_DB and min(after) > PROBLEM_SILENCE_DB:
+            delta = mean(after) - mean(before)
+            if abs(delta) >= PROBLEM_JUMP_DB:
+                if cand and i - cand[-1][0] <= w and abs(delta) <= abs(cand[-1][1]):
+                    continue
+                if cand and i - cand[-1][0] <= w:
+                    cand.pop()
+                cand.append((i, delta))
+    for i, delta in cand:
+        problems.append({"kind": "level_jump", "start_s": t(i), "end_s": t(i),
+                         "detail": f"{delta:+.0f} dB level change"})
+    problems.sort(key=lambda p: p["start_s"])
+    return problems
+
+
 def _auto_trim_bounds(path: Path) -> dict:
     seg = AudioSegment.from_file(str(path)).set_channels(1)
     dur_ms = len(seg)

core/config.py

@@ -38,13 +38,14 @@ _SETTINGS_KEYS = {
     "stt_language", "stt_preferred_backend",
     "auto_refine", "refine_model",
     "refine_fillers", "refine_repetitions", "refine_corrections", "refine_punctuation",
-    "captures_default_voice",
+    "captures_default_voice", "export_provenance_default",
     "client_voice_bindings",
     "llm_url", "llm_model", "llm_api_key",
     # Magazine layout is a vision task. Kept separate from the general text
     # LLM so page images never accidentally go to a text-only model.
     "magazine_layout_url", "magazine_layout_model",
     "vision_ocr_url", "vision_ocr_model", "vision_ocr_enabled",
+    "inline_tags_enabled",
     "vision_ocr_fallback_url", "vision_ocr_fallback_model",
     # OPDS catalogues to search for magazine issues: [{"name": ..., "url": ...}], no credentials.
     "magazine_opds_catalogs",
@@ -346,6 +347,8 @@ def _load_settings() -> dict:
         "vision_ocr_url":         _VISION_OCR_DEFAULT,
         "vision_ocr_model":       _VISION_OCR_MODEL_DEFAULT,
         "vision_ocr_enabled":     True,
+        "inline_tags_enabled":    False,
+        "export_provenance_default": True,
         "vision_ocr_fallback_url":   _VISION_OCR_FALLBACK_DEFAULT,
         "vision_ocr_fallback_model": _VISION_OCR_FALLBACK_MODEL_DEFAULT,
         "engine_local_urls":      {},

core/export_provenance.py

@@ -0,0 +1,71 @@
+"""Provenance tags for exported generated audio (tier 1) and the AudioSeal stub (tier 2).
+
+Tags are written with one ffmpeg stream copy (no re-encode) into a COPY of the MP3; the stored
+article audio is never modified. Tags never contain paths, user names or secrets; the voice is
+included only when the caller opts in. See architecture/watermarking.md.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+GENERATOR = "tts-voice-creator-clone-and-design-2"
+_KEYS = ("synthetic_speech", "generator", "generator_version", "generated_date", "voice")
+_CTRL = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def build_tags(app_version: str, voice: str = "", include_voice: bool = False, today: str = "") -> dict[str, str]:
+    tags = {
+        "synthetic_speech": "true",
+        "generator": GENERATOR,
+        "generator_version": _CTRL.sub("", str(app_version))[:32],
+        "generated_date": today or datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+    }
+    if include_voice and voice:
+        tags["voice"] = _CTRL.sub("", Path(str(voice)).name)[:80]   # name only, never a path
+    tags["comment"] = f"Synthetic speech (AI-generated) by {GENERATOR} {tags['generator_version']}"
+    return tags
+
+
+def apply_tags(src: Path, dst: Path, tags: dict[str, str]) -> Path:
+    """Copy src to dst (stream copy) with the tags; raises RuntimeError on ffmpeg failure."""
+    cmd = ["ffmpeg", "-y", "-v", "error", "-i", str(src), "-map", "0:a", "-map_metadata", "0",
+           "-c", "copy", "-id3v2_version", "3"]
+    for k, v in tags.items():
+        cmd += ["-metadata", f"{k}={v}"]
+    cmd.append(str(dst))
+    r = subprocess.run(cmd, capture_output=True, timeout=120)
+    if r.returncode != 0:
+        raise RuntimeError("tagging failed")        # ffmpeg stderr may contain paths: not forwarded
+    return dst
+
+
+def read_tags(path: Path) -> dict[str, str]:
+    """Provenance tags found in an audio file ({} if none). Never raises."""
+    try:
+        r = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format_tags", "-of", "json", str(path)],
+                           capture_output=True, timeout=30)
+        found = (json.loads(r.stdout or b"{}").get("format") or {}).get("tags") or {}
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return {}
+    low = {str(k).lower(): str(v) for k, v in found.items()}
+    return {k: low[k] for k in _KEYS if k in low}
+
+
+def watermark(path: Path) -> Path:
+    """Tier 2 (AudioSeal) is not installed in this image: always reports unavailable."""
+    raise NotImplementedError("Inaudible watermarking (AudioSeal) is not available in this build")
+
+
+def watermark_available() -> bool:
+    return False
+
+
+if __name__ == "__main__":        # verify CLI: python -m core.export_provenance file.mp3
+    import sys
+    found = read_tags(Path(sys.argv[1])) if len(sys.argv) == 2 else {}
+    print(json.dumps(found, indent=2))
+    sys.exit(0 if found.get("synthetic_speech") == "true" else 1)

core/magazine.py

@@ -5651,20 +5651,31 @@ def split_sentences_for_tts(text: str) -> list[str]:
 
 
 _INTERVIEW_LABEL_RE = re.compile(
-    r"^\s*([A-ZÄÖÜ][A-Za-zÄÖÜäöüß.'’\-]+(?:\s+[A-ZÄÖÜ][A-Za-zÄÖÜäöüß.'’\-]+){0,3})\s*:\s+(.+)$",
+    r"^\s*((?:[A-ZÄÖÜ][A-Za-zÄÖÜäöüß.'’\-]+(?:\s+[A-ZÄÖÜ][A-Za-zÄÖÜäöüß.'’\-]+){0,3})|[Cc]{1,2}['’‘`´]t|ct)\s*:\s+(.+)$",
     re.S,
 )
+# Labels of the interviewing side (casefolded, apostrophes normalised to "'"). Spoken in the narrator voice;
+# every other recurring label is a guest and gets the second voice.
+INTERVIEW_JOURNALIST_LABELS = frozenset({"c't", "ct", "redaktion", "interviewer", "frage"})
+_NON_TURN_TYPES = frozenset({"title", "heading", "deck", "byline", "figure_description"})
 
 
-def interview_tts_segments(blocks: Sequence[dict[str, Any]]) -> list[dict[str, str | None]]:
-    """Return article text segments with speaker labels for a two-person interview.
+def _label_key(label: str) -> str:
+    key = re.sub(r"[’‘`´]", "'", label.strip().casefold())
+    return "c't" if key == "cc't" else key       # OCR doubles the drop-cap: "Cc't:"
 
-    Detection is intentionally strict: exactly two recurring labels must begin
-    paragraph blocks.  Colons in ordinary prose therefore do not suddenly
-    switch voices.  Speaker labels themselves are omitted from speech because
-    the voice change already conveys who is talking.
+
+def interview_tts_segments(blocks: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return article text segments with speaker labels and voice slots for an interview.
+
+    Each segment: ``speaker`` (label or None), ``text`` (label stripped), ``slot`` (0 narrator voice,
+    1 second voice).  Detection is strict so colons in prose never switch voices: a label must start a
+    block and recur at least twice, and there must be a journalist label (``INTERVIEW_JOURNALIST_LABELS``)
+    or two distinct recurring labels.  Journalist -> slot 0, every other label -> slot 1; with no journalist
+    label the first label seen gets slot 0.  An unlabelled block continues the current speaker's turn;
+    titles/headings/decks/bylines and everything before the first label stay narrator.
     """
-    parsed: list[tuple[str | None, str]] = []
+    parsed: list[tuple[str | None, str, str, dict[str, Any]]] = []   # key, body, full text, block
     counts: dict[str, int] = {}
     labels: dict[str, str] = {}
     for block in blocks:
@@ -5673,22 +5684,32 @@ def interview_tts_segments(blocks: Sequence[dict[str, Any]]) -> list[dict[str, s
             continue
         match = _INTERVIEW_LABEL_RE.match(text)
         if not match:
-            parsed.append((None, text))
+            parsed.append((None, text, text, block))
             continue
         label, body = match.group(1).strip(), match.group(2).strip()
-        key = label.casefold()
+        key = _label_key(label)
         labels.setdefault(key, label)
         counts[key] = counts.get(key, 0) + 1
-        parsed.append((key, body))
+        parsed.append((key, body, text, block))
 
     recurring = [key for key, count in counts.items() if count >= 2]
-    if len(recurring) != 2:
-        return [{"speaker": None, "text": text} for _, text in parsed]
-    allowed = set(recurring)
-    return [
-        {"speaker": labels[speaker] if speaker in allowed else None, "text": text}
-        for speaker, text in parsed
-    ]
+    journalist = [k for k in recurring if k in INTERVIEW_JOURNALIST_LABELS]
+    if not journalist and len(recurring) != 2:
+        return [{"speaker": None, "text": full, "slot": 0} for _, _, full, _ in parsed]
+    slot_of = {k: (0 if k in journalist else 1) for k in recurring} if journalist else {k: i for i, k in enumerate(recurring)}
+    out: list[dict[str, Any]] = []
+    speaker: str | None = None
+    slot = 0
+    for key, body, full, block in parsed:
+        if key in slot_of:
+            speaker, slot = labels[key], slot_of[key]
+            out.append({"speaker": speaker, "text": body, "slot": slot})
+        elif block.get("type") in _NON_TURN_TYPES:
+            speaker, slot = None, 0
+            out.append({"speaker": None, "text": full, "slot": 0})
+        else:
+            out.append({"speaker": speaker, "text": full, "slot": slot})
+    return out
 
 
 def spoken_chars_for(blocks: Sequence[dict[str, Any]], timings: dict[str, Any] | None) -> list[int] | None:
@@ -5728,18 +5749,17 @@ def synthesize_article_audio(doc_dir: Path, article: dict[str, Any], layout: dic
         {"speaker": None, "text": b["text"], "spoken": b.get("spoken_text")}
         for b in blocks if (b.get("text") or "").strip()
     ]
-    speakers = []
-    for segment in segments:
-        speaker = segment.get("speaker")
-        if speaker and speaker not in speakers:
-            speakers.append(speaker)
-    voice_for = {speaker: (voice if i == 0 else interview_voice)
-                 for i, speaker in enumerate(speakers[:2])}
     utterances: list[tuple[str, str]] = []
     utterance_segment: list[int] = []        # which segment each utterance came from, for the timing record
     for n, segment in enumerate(segments):
         spoken = segment.get("spoken") or prepare_text_for_tts(str(segment["text"]), language, glossary)
-        segment_voice = voice_for.get(segment.get("speaker"), voice)
+        if settings.get("inline_tags_enabled"):
+            # Tags are stripped here, never rendered: pauses/stretch would shift the recorded sentence timings.
+            from core.ssml_lite import has_tags, plain_text
+            if has_tags(spoken):
+                spoken = plain_text(spoken, language)
+        segment_voice = interview_voice if segment.get("slot") == 1 else voice
+        segment["voice"] = segment_voice
         for sentence in split_sentences_for_tts(spoken):
             utterances.append((sentence, segment_voice))
             utterance_segment.append(n)
@@ -5849,7 +5869,9 @@ def write_audio_timings(mp3_path: Path, segments: Sequence[dict[str, Any]], utte
     record = {
         "version": 1, "interview": bool(interview), "duration_ms": int(spans[-1][1]) if spans else 0,
         "segments": [{"chars": len(str(seg.get("text") or "")), "times": times,
-                      **({"onsets": on} if onsets else {})}
+                      **({"onsets": on} if onsets else {}),
+                      **({"voice": seg["voice"]} if seg.get("voice") else {}),
+                      **({"speaker": seg["speaker"]} if seg.get("speaker") else {})}
                      for seg, times, on in zip(segments, per_segment, per_onset)],
     }
     try:

core/open_voice_sources.py

@@ -0,0 +1,268 @@
+"""LibriVox and Wikimedia Commons voice search (official APIs only, fixed hosts). See architecture/voice-sources.md."""
+from __future__ import annotations
+
+import html
+import json
+import logging
+import re
+import threading
+import time
+from urllib.parse import urlsplit
+
+import requests
+
+from core.provenance import validate_provenance
+
+LIBRIVOX_API = "https://librivox.org/api/feed/audiobooks"
+COMMONS_API = "https://commons.wikimedia.org/w/api.php"
+USER_AGENT = "TTSVoiceCreator/1.0 (self-hosted voice library; official-API client)"  # no personal data
+MAX_Q = 80
+MAX_RESULTS = 10
+MAX_BYTES = 8 * 1024 * 1024
+TIMEOUT = 25  # LibriVox is erratic: 10-40 s even for small feeds (measured 2026-10); one retry follows
+RETRIES = 1
+BACKOFF = 1.5
+NEG_TTL = 30  # seconds an upstream failure is remembered (stops hammering a slow API)
+CACHE_TTL = 600
+CACHE_MAX = 200
+MIN_INTERVAL = 1.0  # seconds between upstream calls per source (MediaWiki asks for serial requests)
+
+# host suffixes allowed in result URLs (checked on every URL taken from an API response)
+AUDIO_HOSTS = ("archive.org", "upload.wikimedia.org")
+PAGE_HOSTS = ("librivox.org", "archive.org", "commons.wikimedia.org")
+SOURCES = ("librivox", "wikimedia")
+LANG_NAMES = {
+    "en": "English", "de": "German", "fr": "French", "es": "Spanish", "it": "Italian", "pt": "Portuguese",
+    "nl": "Dutch", "pl": "Polish", "ru": "Russian", "ja": "Japanese", "zh": "Chinese", "sv": "Swedish",
+}
+_CTRL = re.compile(r"[\x00-\x1f\x7f]")
+_TAGS = re.compile(r"<[^>]*>")
+
+_cache: dict[tuple, tuple[float, list]] = {}
+_last_call: dict[str, float] = {}
+_locks = {s: threading.Lock() for s in SOURCES}
+_cache_lock = threading.Lock()
+_neg: dict[tuple, tuple[float, str]] = {}
+log = logging.getLogger(__name__)
+
+
+class SourceError(Exception):
+    """Bad input (400) or upstream failure (502); message is safe to show."""
+    def __init__(self, msg: str, status: int = 400):
+        super().__init__(msg)
+        self.status = status
+
+
+def host_ok(url: str, suffixes: tuple[str, ...]) -> bool:
+    try:
+        p = urlsplit(str(url))
+        h = (p.hostname or "").lower()
+    except ValueError:
+        return False
+    return p.scheme == "https" and not p.username and not p.password and any(h == s or h.endswith("." + s) for s in suffixes)
+
+
+def clean_query(q: str) -> str:
+    q = _CTRL.sub(" ", str(q or "")).strip()
+    q = re.sub(r"\s+", " ", q)
+    if not q:
+        raise SourceError("q is required")
+    if len(q) > MAX_Q:
+        raise SourceError(f"q is too long (max {MAX_Q})")
+    return q
+
+
+def clean_lang(lang: str) -> str:
+    lang = str(lang or "").strip().lower()
+    if lang and not re.fullmatch(r"[a-z]{2,3}", lang):
+        raise SourceError("lang must be a 2-3 letter code")
+    return lang
+
+
+def _text(value, limit=200) -> str:
+    return _CTRL.sub(" ", html.unescape(_TAGS.sub("", str(value or "")))).strip()[:limit]
+
+
+def _fetch(url: str, params: dict, src: str) -> dict:
+    r = requests.get(url, params=params, headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+                     timeout=(5, TIMEOUT), allow_redirects=False, stream=True)
+    if r.status_code == 404 and src == "librivox":
+        return {}
+    r.raise_for_status()
+    body = b""
+    for chunk in r.iter_content(65536):
+        body += chunk
+        if len(body) > MAX_BYTES:
+            raise SourceError("Upstream response too large", 502)
+    return json.loads(body.decode("utf-8", "replace"))
+
+
+def _get_json(url: str, params: dict) -> dict:
+    src = "librivox" if url == LIBRIVOX_API else "wikimedia"
+    with _locks[src]:
+        for attempt in range(RETRIES + 1):
+            wait = MIN_INTERVAL - (time.monotonic() - _last_call.get(src, 0.0))
+            if wait > 0:
+                time.sleep(wait)
+            _last_call[src] = time.monotonic()
+            try:
+                return _fetch(url, params, src)
+            except SourceError:
+                raise
+            except Exception as e:
+                # privacy-safe: exception class and query length only, never the query text
+                log.warning("%s fetch attempt %d failed: %s (query length %d)", src, attempt + 1, type(e).__name__,
+                            len(str(params.get("title") or params.get("gsrsearch") or "")))
+                if attempt < RETRIES:
+                    time.sleep(BACKOFF * (2 ** attempt))
+                    continue
+                if isinstance(e, requests.Timeout):
+                    msg = f"{src} did not answer in time (its API is slow); try again in a minute"
+                elif isinstance(e, requests.HTTPError):
+                    code = getattr(e.response, "status_code", "?")
+                    msg = f"{src} refused the request (HTTP {code})"
+                elif isinstance(e, requests.ConnectionError):
+                    msg = f"{src} is unreachable from this server"
+                else:
+                    msg = f"{src} returned an unreadable answer"
+                raise SourceError(msg, 502)
+
+
+def _librivox_items(q: str, lang: str) -> list[dict]:
+    # Light list (no extended=1: sections made the feed several times bigger and slower); audio is resolved per book.
+    data = _get_json(LIBRIVOX_API, {"title": "^" + q, "format": "json", "limit": 15})  # "^" = prefix match; bare title is exact
+    want = LANG_NAMES.get(lang, "").lower()
+    out = []
+    for b in (data.get("books") or []) if isinstance(data, dict) else []:
+        if not isinstance(b, dict):
+            continue
+        if want and str(b.get("language") or "").lower() != want:
+            continue
+        src_url, bid = b.get("url_librivox") or "", str(b.get("id") or "")
+        if not bid.isdigit() or len(bid) > 9 or not host_ok(src_url, PAGE_HOSTS):
+            continue
+        authors = ", ".join(_text(f"{a.get('first_name', '')} {a.get('last_name', '')}", 60) for a in (b.get("authors") or []) if isinstance(a, dict))
+        try:
+            dur = int(b.get("totaltimesecs") or 0)
+        except (TypeError, ValueError):
+            dur = 0
+        out.append({
+            "source": "librivox", "book_id": bid, "title": _text(b.get("title")), "reader": "", "author": authors,
+            "language": _text(b.get("language"), 40), "duration": dur,
+            "licence": "Public domain (LibriVox, USA)", "licence_url": "https://librivox.org/pages/public-domain/",
+            "source_url": src_url, "audio_url": "", "attribution": "",
+        })
+        if len(out) >= MAX_RESULTS:
+            break
+    return out
+
+
+def librivox_first_section(book_id: str) -> dict:
+    """First playable section of one book (title, reader, duration, host-checked audio_url)."""
+    book_id = str(book_id or "")
+    if not (book_id.isdigit() and len(book_id) <= 9):
+        raise SourceError("invalid book id")
+    key = ("librivox-book", book_id)
+    cached = _cache_get(key)
+    if cached is not None:
+        return cached
+    data = _cached_call(key, lambda: _get_json(LIBRIVOX_API, {"id": book_id, "format": "json", "extended": 1}))
+    for b in (data.get("books") or []) if isinstance(data, dict) else []:
+        for s in (b.get("sections") or []) if isinstance(b, dict) else []:
+            if isinstance(s, dict) and host_ok(s.get("listen_url") or "", AUDIO_HOSTS):
+                readers = ", ".join(_text(r.get("display_name"), 60) for r in (s.get("readers") or []) if isinstance(r, dict))
+                try:
+                    dur = int(s.get("playtime") or 0)
+                except (TypeError, ValueError):
+                    dur = 0
+                res = {"audio_url": s["listen_url"], "section": _text(s.get("title")), "reader": readers, "duration": dur}
+                _cache_put(key, res)
+                return res
+    raise SourceError("no playable audio found for this book", 404)
+
+
+def _wikimedia_items(q: str) -> list[dict]:
+    data = _get_json(COMMONS_API, {
+        "action": "query", "format": "json", "generator": "search", "gsrnamespace": 6, "gsrlimit": 20,
+        "gsrsearch": f"filetype:audio {q}", "prop": "imageinfo", "iiprop": "url|extmetadata|mediatype", "maxlag": 5,
+    })
+    pages = ((data.get("query") or {}).get("pages") or {}) if isinstance(data, dict) else {}
+    out = []
+    for p in sorted((x for x in pages.values() if isinstance(x, dict)), key=lambda x: x.get("index", 0)):
+        info = (p.get("imageinfo") or [{}])[0]
+        meta = info.get("extmetadata") or {}
+        mv = lambda k: (meta.get(k) or {}).get("value", "")
+        lic = _text(mv("LicenseShortName"), 80)
+        audio, page = info.get("url") or "", info.get("descriptionurl") or ""
+        if info.get("mediatype") != "AUDIO" or not lic or not host_ok(audio, AUDIO_HOSTS) or not host_ok(page, PAGE_HOSTS):
+            continue
+        licurl = mv("LicenseUrl") if host_ok(mv("LicenseUrl"), ("creativecommons.org", "wikimedia.org")) else ""
+        title = _text(re.sub(r"^File:|\.[A-Za-z0-9]+$", "", str(p.get("title") or "")))
+        artist = _text(mv("Artist"), 120)
+        out.append({
+            "source": "wikimedia", "title": title, "reader": artist, "author": artist, "language": "",
+            "duration": round(float(info.get("duration") or 0)), "licence": lic, "licence_url": licurl,
+            "source_url": page, "audio_url": audio,
+            "attribution": _text(f"{artist + ' / ' if artist else ''}{title}, {lic}, via Wikimedia Commons", 300),
+        })
+        if len(out) >= MAX_RESULTS:
+            break
+    return out
+
+
+def _cache_get(key):
+    with _cache_lock:
+        hit = _cache.get(key)
+        if hit and time.monotonic() - hit[0] < CACHE_TTL:
+            return hit[1]
+    return None
+
+
+def _cache_put(key, value):
+    with _cache_lock:
+        if len(_cache) >= CACHE_MAX:
+            _cache.pop(min(_cache, key=lambda k: _cache[k][0]))
+        _cache[key] = (time.monotonic(), value)
+
+
+def _cached_call(key, fn):
+    """Run fn; a SourceError is remembered for NEG_TTL seconds and re-raised instantly meanwhile."""
+    with _cache_lock:
+        bad = _neg.get(key)
+    if bad and time.monotonic() - bad[0] < NEG_TTL:
+        raise SourceError(bad[1], 502)
+    try:
+        return fn()
+    except SourceError as e:
+        if e.status >= 500:
+            with _cache_lock:
+                _neg[key] = (time.monotonic(), str(e))
+        raise
+
+
+def search(source: str, q: str, lang: str = "") -> list[dict]:
+    if source not in SOURCES:
+        raise SourceError("unknown source")
+    q, lang = clean_query(q), clean_lang(lang)
+    key = (source, q.lower(), lang if source == "librivox" else "")
+    hit = _cache_get(key)
+    if hit is not None:
+        return hit
+    items = _cached_call(key, lambda: _librivox_items(q, lang) if source == "librivox" else _wikimedia_items(q))
+    _cache_put(key, items)
+    return items
+
+
+def import_provenance_for(kind: str, source_url: str, licence: str, attribution: str) -> dict:
+    """Provenance prefill for an import from one of these sources (raises ValueError on bad input)."""
+    if kind == "librivox":
+        return validate_provenance({
+            "basis": "public_domain", "source": source_url, "licence": "Public domain (LibriVox)",
+            "note": "LibriVox recordings are donated to the public domain (guaranteed in the USA only). "
+                    "Check the reader's declared licence on the LibriVox page before use."})
+    if kind == "wikimedia":
+        pd = re.search(r"public domain|\bcc0\b|\bpd\b", licence, re.I)
+        return validate_provenance({
+            "basis": "public_domain" if pd else "licensed", "source": source_url, "licence": licence,
+            "note": ("Attribution: " + attribution)[:1000]})
+    raise ValueError("unknown source_kind")

core/provenance.py

@@ -0,0 +1,55 @@
+"""Consent/provenance sidecar field for voices (stored in <voice>.meta.json)."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from urllib.parse import urlsplit
+
+BASES = ("own_voice", "consented", "licensed", "public_domain", "unknown")
+CONSENT_EXTS = {".webm", ".ogg", ".opus", ".wav", ".mp3", ".m4a"}
+CONSENT_MIME = {".webm": "audio/webm", ".ogg": "audio/ogg", ".opus": "audio/ogg", ".wav": "audio/wav",
+                ".mp3": "audio/mpeg", ".m4a": "audio/mp4"}
+MAX_CONSENT_BYTES = 10 * 1024 * 1024
+_LIMITS = {"source": 500, "licence": 300, "note": 1000}
+_CTRL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
+
+
+def _clean(value, limit: int) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ValueError("Provenance text fields must be strings")
+    value = _CTRL.sub("", value).strip()
+    if len(value) > limit:
+        raise ValueError(f"Provenance text is too long (max {limit})")
+    return value
+
+
+def validate_provenance(data: dict, previous: dict | None = None) -> dict:
+    """Return a clean provenance dict or raise ValueError (-> HTTP 400)."""
+    if not isinstance(data, dict):
+        raise ValueError("Provenance must be an object")
+    basis = data.get("basis", "unknown")
+    if basis not in BASES:
+        raise ValueError("basis must be one of: " + ", ".join(BASES))
+    out = {"basis": basis}
+    for field, limit in _LIMITS.items():
+        out[field] = _clean(data.get(field), limit)
+    src = out["source"]
+    if re.match(r"^[a-z][a-z0-9+.-]*:", src, re.I):  # looks like a URL: http(s) only, no credentials
+        parts = urlsplit(src)
+        if parts.scheme.lower() not in {"http", "https"} or not parts.hostname or parts.username or parts.password:
+            raise ValueError("source URL must be http(s) without credentials")
+    prev = previous or {}
+    if prev.get("recorded_consent"):  # only the consent routes change the recording
+        out["recorded_consent"] = prev["recorded_consent"]
+    out["set_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    return out
+
+
+def import_provenance(source_url: str) -> dict:
+    """Prefill for imports from a known source; basis stays unknown until a human decides."""
+    try:
+        return validate_provenance({"basis": "unknown", "source": source_url})
+    except ValueError:
+        return {"basis": "unknown", "source": "", "licence": "", "note": ""}

core/seed_score.py

@@ -0,0 +1,72 @@
+"""Seed auto-pick scoring: combine ASR accuracy, loudness/clipping and audio problems into 0-100.
+
+score = weighted mean of the available sub-scores (each 0-100). Without ASR the
+accuracy weight is dropped and the rest re-normalised ("degraded" result).
+  accuracy  = ASR round-trip word accuracy (routes.stt._word_accuracy)
+  loudness  = 100 - |dBFS - target| * LOUD_PEN_PER_DB (capped) - CLIP_PEN if peak hits full scale
+  problems  = 100 - sum of per-kind penalties from core.audio.audio_problems
+"""
+from __future__ import annotations
+
+W_ACCURACY = 0.5
+W_LOUDNESS = 0.2
+W_PROBLEMS = 0.3
+
+LOUD_PEN_PER_DB = 4.0     # points lost per dB away from the target level
+LOUD_PEN_MAX = 60.0
+CLIP_PEN = 30.0           # peak at/above CLIP_PEAK_DBFS
+CLIP_PEAK_DBFS = -0.1
+
+PROBLEM_PENALTY = {"silence": 25.0, "level_jump": 20.0, "clipping": 10.0}
+PROBLEM_PENALTY_DEFAULT = 10.0
+
+DEFAULT_COUNT = 8
+MAX_COUNT = 16
+
+
+def loudness_score(info: dict) -> float:
+    dbfs, peak, target = info.get("dbfs"), info.get("peak_dbfs"), info.get("target_dbfs", -20.0)
+    if dbfs is None:
+        return 0.0
+    s = 100.0 - min(LOUD_PEN_MAX, abs(dbfs - target) * LOUD_PEN_PER_DB)
+    if peak is not None and peak >= CLIP_PEAK_DBFS:
+        s -= CLIP_PEN
+    return max(0.0, s)
+
+
+def problems_score(problems: list[dict]) -> float:
+    pen = sum(PROBLEM_PENALTY.get(p.get("kind"), PROBLEM_PENALTY_DEFAULT) for p in problems)
+    return max(0.0, 100.0 - pen)
+
+
+def combine(accuracy: float | None, loudness: float, problems: float) -> float:
+    parts = [(W_LOUDNESS, loudness), (W_PROBLEMS, problems)]
+    if accuracy is not None:
+        parts.append((W_ACCURACY, accuracy))
+    return round(sum(w * v for w, v in parts) / sum(w for w, _ in parts), 1)
+
+
+def pick_winner(candidates: list[dict]) -> int | None:
+    """Seed with the highest score (ties: lowest seed); errored candidates are skipped."""
+    ok = [c for c in candidates if not c.get("error") and c.get("score") is not None]
+    return min(ok, key=lambda c: (-c["score"], c["seed"]))["seed"] if ok else None
+
+
+def seed_list(seeds, count) -> list[int]:
+    """Validate the request: explicit seeds win, else 1..count; bounded to MAX_COUNT."""
+    if seeds is not None:
+        if not isinstance(seeds, list) or not seeds:
+            raise ValueError("seeds must be a non-empty list")
+        out = []
+        for s in seeds:
+            if isinstance(s, bool) or not isinstance(s, int) or not 0 <= s <= 9999:
+                raise ValueError("seeds must be integers 0-9999")
+            if s not in out:
+                out.append(s)
+        if len(out) > MAX_COUNT:
+            raise ValueError(f"at most {MAX_COUNT} seeds")
+        return out
+    n = DEFAULT_COUNT if count is None else count
+    if isinstance(n, bool) or not isinstance(n, int) or not 1 <= n <= MAX_COUNT:
+        raise ValueError(f"count must be 1-{MAX_COUNT}")
+    return list(range(1, n + 1))

core/ssml_lite.py

@@ -0,0 +1,176 @@
+"""Inline text tags for TTS, engine independent (idea only; no third-party code).
+
+Tags: [pause 500ms] [pause 1.2s], [spell]USA[/spell], [slow]..[/slow], [fast]..[/fast].
+parse() turns text into segments {text, speed, pause_ms}; render() synthesises and joins them.
+Only a fixed set of tag names is ever stripped, so "[1]" or "[sic]" stay untouched.
+"""
+from __future__ import annotations
+
+import re
+from typing import Callable
+
+MAX_PAUSE_MS = 10_000
+MAX_TOTAL_PAUSE_MS = 60_000
+SPEEDS = {"slow": 0.85, "fast": 1.15}
+
+# Control-style tags from other tools that must never be spoken. Allowlist, not "any [word]".
+STRIP_NAMES = frozenset({
+    "laugh", "laughs", "laughing", "chuckle", "sigh", "gasp", "cough", "breath", "breathe",
+    "inhale", "exhale", "whisper", "shout", "music", "sfx", "noise", "beat", "silence",
+    "emphasis", "excited", "sad", "angry", "happy", "calm", "sniff", "gulp", "clears_throat",
+})
+
+_TAG_RE = re.compile(r"\[(/?)([A-Za-z_]+)(?:[ \t]+([^\[\]\n]{0,24}))?\]")
+_PAUSE_ARG_RE = re.compile(r"^(\d+(?:\.\d+)?)\s*(ms|s)$", re.I)
+_PARA_RE = re.compile(r"(\n\s*\n)")
+
+_DE_LETTERS = {
+    "a": "Ah", "b": "Be", "c": "Ze", "d": "De", "e": "Eh", "f": "Eff", "g": "Ge", "h": "Ha",
+    "i": "Ih", "j": "Jott", "k": "Ka", "l": "Ell", "m": "Emm", "n": "Enn", "o": "Oh", "p": "Pe",
+    "q": "Ku", "r": "Err", "s": "Ess", "t": "Te", "u": "Uh", "v": "Fau", "w": "We", "x": "Iks",
+    "y": "Üpsilon", "z": "Zett", "ä": "Ä", "ö": "Ö", "ü": "Ü", "ß": "Ess-Zett",
+}
+
+
+def _spell(content: str, language: str) -> str:
+    chars = [c for c in content if not c.isspace()]
+    if language == "de":
+        return " ".join(_DE_LETTERS.get(c.lower(), c) for c in chars)
+    from core.pronunciations import spell_letters
+    return spell_letters("".join(chars))
+
+
+def _lang(text: str, language: str) -> str:
+    low = (language or "auto").strip().lower()
+    if low in {"de", "german", "deutsch"} or low.startswith("de-"):
+        return "de"
+    if low in {"", "auto"}:
+        from core.pronunciations import detect_text_language
+        return detect_text_language(text)
+    return "en"
+
+
+def _pause_ms(arg: str | None) -> int | None:
+    m = _PAUSE_ARG_RE.match((arg or "").strip())
+    if not m:
+        return None
+    ms = float(m.group(1)) * (1000 if m.group(2).lower() == "s" else 1)
+    return min(int(ms), MAX_PAUSE_MS)
+
+
+def has_tags(text: str) -> bool:
+    return any(m.group(2).lower() in {"pause", "spell", "slow", "fast"} | STRIP_NAMES
+               for m in _TAG_RE.finditer(text or ""))
+
+
+def _parse_paragraph(text: str, lang: str) -> list[dict]:
+    out: list[dict] = []
+    speeds: list[float] = []
+    spell_from: int | None = None          # index in `out` where an open [spell] started
+    pos = 0
+
+    def add(chunk: str) -> None:
+        if chunk:
+            out.append({"text": chunk, "speed": speeds[-1] if speeds else 1.0, "pause_ms": 0})
+
+    def close_spell() -> None:
+        nonlocal spell_from
+        if spell_from is not None:
+            joined = "".join(s["text"] for s in out[spell_from:])
+            del out[spell_from:]
+            add(_spell(joined, lang))
+            spell_from = None
+
+    for m in _TAG_RE.finditer(text):
+        name, closing = m.group(2).lower(), m.group(1) == "/"
+        known = name in {"pause", "spell", "slow", "fast"} or name in STRIP_NAMES
+        if not known:
+            continue                       # ordinary prose such as "[1]" or "[sic]": handled below
+        add(text[pos:m.start()])
+        pos = m.end()
+        if name == "pause" and not closing:
+            ms = _pause_ms(m.group(3))
+            if ms:
+                out.append({"text": "", "speed": 1.0, "pause_ms": ms})
+        elif name == "spell":
+            if closing:
+                close_spell()
+            elif spell_from is None:
+                spell_from = len(out)
+        elif name in SPEEDS:
+            if closing:
+                if speeds:
+                    speeds.pop()
+            else:
+                speeds.append(SPEEDS[name])
+        # anything else in STRIP_NAMES (and a stray [/pause]) is dropped
+    add(text[pos:])
+    close_spell()                          # unclosed [spell] runs to the end of the paragraph
+    return out
+
+
+def parse(text: str, language: str = "auto") -> list[dict]:
+    """Split text into segments; unclosed tags end at the paragraph break; pauses are capped."""
+    lang = _lang(text, language)
+    segments: list[dict] = []
+    for part in _PARA_RE.split(text or ""):
+        if _PARA_RE.fullmatch(part):
+            if segments and not segments[-1]["pause_ms"]:
+                segments[-1]["text"] += part
+            continue
+        segments.extend(_parse_paragraph(part, lang))
+    budget = MAX_TOTAL_PAUSE_MS
+    merged: list[dict] = []
+    for seg in segments:
+        if seg["pause_ms"]:
+            seg["pause_ms"] = min(seg["pause_ms"], budget)
+            budget -= seg["pause_ms"]
+            if not seg["pause_ms"]:
+                continue
+        elif merged and not merged[-1]["pause_ms"] and merged[-1]["speed"] == seg["speed"]:
+            merged[-1]["text"] += seg["text"]
+            continue
+        merged.append(seg)
+    return [s for s in merged if s["pause_ms"] or s["text"].strip()]
+
+
+def plain_text(text: str, language: str = "auto") -> str:
+    """Text with all tags resolved and no timing (for paths that cannot render pauses/speed)."""
+    return re.sub(r"[ \t]+", " ", " ".join(s["text"].strip() for s in parse(text, language) if s["text"].strip()))
+
+
+def render(text: str, synth: Callable[[str], tuple[bytes, str]], tempo: Callable[[bytes, float], bytes],
+           language: str = "auto") -> tuple[bytes, str]:
+    """Synthesise every segment, stretch slow/fast ones, join with generated silence -> WAV bytes.
+
+    The result's duration already includes pauses and stretching, so timings measured on it stay right.
+    """
+    import io
+    from pydub import AudioSegment
+
+    combined = AudioSegment.empty()
+    for seg in parse(text, language):
+        if seg["pause_ms"]:
+            rate = combined.frame_rate if len(combined) else 24000
+            combined += AudioSegment.silent(duration=seg["pause_ms"], frame_rate=rate)
+            continue
+        audio, media_type = synth(seg["text"].strip())
+        fmt = "wav" if audio[:4] == b"RIFF" or "wav" in media_type.lower() else None
+        piece = AudioSegment.from_file(io.BytesIO(audio), format=fmt)
+        if abs(seg["speed"] - 1.0) > 0.01:
+            buf = io.BytesIO()
+            piece.export(buf, format="wav")
+            piece = AudioSegment.from_file(io.BytesIO(tempo(buf.getvalue(), seg["speed"])), format="wav")
+        combined += piece
+    out = io.BytesIO()
+    combined.export(out, format="wav")
+    return out.getvalue(), "audio/wav"
+
+
+def render_with_tags(text: str, synth: Callable[[str], tuple[bytes, str]], language: str = "auto",
+                     enabled: bool = False) -> tuple[bytes, str]:
+    """Shared entry for every path that can render tags: plain `synth(text)` unless enabled and tagged."""
+    if not (enabled and has_tags(text)):
+        return synth(text)
+    from core.audio import _change_tempo
+    return render(text, synth, _change_tempo, language)

core/tasks.py

@@ -0,0 +1,23 @@
+"""Fire-and-forget asyncio tasks that are kept alive until they finish."""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+log = logging.getLogger(__name__)
+_BACKGROUND: set[asyncio.Task] = set()
+
+
+def _done(task: asyncio.Task) -> None:
+    _BACKGROUND.discard(task)
+    if not task.cancelled() and task.exception() is not None:
+        # class name only: exception text may carry paths/URLs/keys
+        log.error("background task failed: %s", type(task.exception()).__name__)
+
+
+def spawn(coro) -> asyncio.Task:
+    """create_task + strong reference (the loop only keeps weak ones)."""
+    task = asyncio.create_task(coro)
+    _BACKGROUND.add(task)
+    task.add_done_callback(_done)
+    return task

core/vocal_isolation.py

@@ -0,0 +1,82 @@
+"""Optional vocal isolation (Demucs CLI). Off unless VOCAL_ISOLATION=1; never downloads weights."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+import uuid
+from pathlib import Path
+
+from core.audio import _duration, _to_wav_24k
+from core.registry import TEMP_DIR
+
+_WEIGHTS_GLOB = "955717e8*.th"  # htdemucs
+_busy = threading.Lock()  # ponytail: one job at a time; a queue only if several users isolate concurrently
+
+
+class VocalIsolationError(Exception):
+    def __init__(self, message: str, status: int = 500):
+        super().__init__(message)
+        self.status = status
+
+
+def _cmd() -> str | None:
+    return os.environ.get("VOCAL_ISOLATION_CMD") or shutil.which("demucs")
+
+
+def _weights_present() -> bool:
+    home = Path(os.environ.get("TORCH_HOME") or Path.home() / ".cache" / "torch")
+    return any((home / "hub" / "checkpoints").glob(_WEIGHTS_GLOB))
+
+
+def enabled() -> bool:
+    return os.environ.get("VOCAL_ISOLATION", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def available() -> bool:
+    return enabled() and _cmd() is not None and _weights_present()
+
+
+def isolate_vocals(path: Path, cancel: threading.Event | None = None) -> Path:
+    """Return a new 24 kHz mono WAV with vocals only; `path` is left untouched."""
+    if not enabled():
+        raise VocalIsolationError("Vocal isolation is turned off (set VOCAL_ISOLATION=1).", 503)
+    cmd = _cmd()
+    if cmd is None or not _weights_present():
+        raise VocalIsolationError("Vocal isolation is not installed (Demucs or its weights are missing).", 503)
+    max_s = float(os.environ.get("VOCAL_ISOLATION_MAX_SECONDS", "900"))
+    timeout = float(os.environ.get("VOCAL_ISOLATION_TIMEOUT", "900"))
+    if _duration(path) > max_s:
+        raise VocalIsolationError(f"Audio is longer than {int(max_s // 60)} minutes; trim it first.", 413)
+    if not _busy.acquire(blocking=False):
+        raise VocalIsolationError("Another vocal isolation is running; try again shortly.", 409)
+    work = Path(tempfile.mkdtemp(prefix="vocal_", dir=TEMP_DIR))
+    try:
+        proc = subprocess.Popen(
+            [cmd, "--two-stems=vocals", "-n", "htdemucs", "-o", str(work), str(path)],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        deadline = time.monotonic() + timeout
+        while proc.poll() is None:
+            if cancel is not None and cancel.is_set():
+                proc.kill(); proc.wait()
+                raise VocalIsolationError("Vocal isolation was cancelled.", 499)
+            if time.monotonic() > deadline:
+                proc.kill(); proc.wait()
+                raise VocalIsolationError("Vocal isolation timed out.", 504)
+            time.sleep(0.2)
+        found = next(work.glob("*/*/vocals.*"), None)
+        if proc.returncode != 0 or found is None:
+            raise VocalIsolationError("Vocal isolation failed.", 500)
+        staged = TEMP_DIR / f"{uuid.uuid4().hex}_vocals{found.suffix}"
+        shutil.move(str(found), staged)
+        try:
+            return _to_wav_24k(staged)
+        finally:
+            staged.unlink(missing_ok=True)
+    finally:
+        _busy.release()
+        shutil.rmtree(work, ignore_errors=True)

core/voice.py

@@ -19,7 +19,7 @@ from core.constants import (
     _VOICE_TARGET_DBFS, _VOICE_PEAK_DBFS,
     _BENCHMARK_SENTENCES, _MAX_TTS_OUTPUT_SECONDS,
 )
-from core.audio import _duration, _export_normalized_wav
+from core.audio import _duration, _export_normalized_wav, audio_problems
 
 # ── File type constants ───────────────────────────────────────────────────────
 
@@ -165,6 +165,11 @@ def _validate_voice_meta(meta: dict) -> None:
     for field in ("enabled", "needs_tts_restart"):
         if field in meta and not isinstance(meta[field], bool):
             raise ValueError(f"Voice metadata field '{field}' must be boolean")
+    if "audio_problems" in meta and not isinstance(meta["audio_problems"], list):
+        raise ValueError("Voice metadata field 'audio_problems' must be a list")
+    if "provenance" in meta:
+        from core.provenance import validate_provenance
+        validate_provenance(meta["provenance"])
     for field in ("loudness", "benchmark"):
         if field in meta and meta[field] is not None and not isinstance(meta[field], dict):
             raise ValueError(f"Voice metadata field '{field}' must be an object")
@@ -260,7 +265,7 @@ def _remove_audio_variants(parent: Path, voice_id: str, keep: Path | None = None
 def _voice_package_paths(audio: Path) -> list[Path]:
     parent = audio.parent
     paths = []
-    for sfx in _AUDIO_EXTS + [".reference.txt", ".meta.json"] + _PICTURE_EXTS:
+    for sfx in _AUDIO_EXTS + [".reference.txt", ".meta.json", ".consent"] + _PICTURE_EXTS:
         p = parent / f"{audio.stem}{sfx}"
         if p.exists():
             paths.append(p)
@@ -334,12 +339,35 @@ def _read_reference_text(audio: Path) -> tuple[bool, str]:
 
 # ── Voice health and entry ────────────────────────────────────────────────────
 
+_PROBLEM_CACHE: dict[tuple[str, float], list[dict]] = {}
+_PROBLEM_LABEL = {"silence": "Long silence in reference audio", "clipping": "Clipping in reference audio",
+                  "level_jump": "Sudden level jump in reference audio"}
+
+
+def _voice_problems(p: Path) -> list[dict]:
+    """Cached by file mtime; decoding happens only on a cache miss."""
+    try:
+        key = (str(p), p.stat().st_mtime)
+    except OSError:
+        return []
+    if key not in _PROBLEM_CACHE:
+        try:
+            found = audio_problems(p)
+        except Exception:
+            found = []
+        if len(_PROBLEM_CACHE) > 512:
+            _PROBLEM_CACHE.clear()
+        _PROBLEM_CACHE[key] = found
+    return _PROBLEM_CACHE[key]
+
+
 def _voice_health(
     p: Path,
     *,
     meta: dict | None = None,
     duration: float | None = None,
     transcript: str | None = None,
+    analyze: bool = False,
 ) -> dict:
     if transcript is None:
         _has_ref, transcript = _read_reference_text(p)
@@ -367,9 +395,14 @@ def _voice_health(
     peak = loudness.get("peak_dbfs")
     if peak is not None and float(peak) > -0.1:
         warnings.append("Reference audio is clipping or too loud")
+    # Decoding audio is too slow for the voice list; only single-voice checks opt in.
+    problems = _voice_problems(p) if analyze else list(meta.get("audio_problems") or [])
+    for kind in dict.fromkeys(q["kind"] for q in problems):
+        warnings.append(_PROBLEM_LABEL[kind])
     return {
         "ok": not warnings,
         "warnings": warnings,
+        "problems": problems,
         "duration": round(duration, 2) if duration else None,
         "word_count": word_count,
         "words_per_sec": round(words_per_sec, 2) if words_per_sec else 0,

core/voice_archetypes.py

@@ -0,0 +1,178 @@
+"""Own German-first voice archetype catalog (hand-authored; no third-party data).
+
+Each archetype is a free-text Qwen3 VoiceDesign description plus facets that reuse the
+DESIGN_CHIPS taxonomy of static/js/voice-clone.js. Validated at import.
+"""
+from __future__ import annotations
+
+from core.open_voice_sources import LANG_NAMES
+
+FACET_VOCAB = {
+    "gender": {"male", "female", "neutral"},
+    "age": {"child", "teenager", "young adult", "middle-aged", "elderly"},
+    "pitch": {"high", "mid", "low"},
+    "accent": {"none", "british", "american", "australian", "irish", "german", "southern"},
+    "tone": {"warm", "husky", "crisp", "smooth", "rich", "magnetic", "authoritative"},
+}
+CATEGORIES = ("Narration & Story", "Conversational", "Characters & Animation", "Social Media",
+              "Entertainment & TV", "Advertisement", "Informative & Educational")
+LANGUAGES = {"German", "English"}
+SEED = 42
+_ID_OK = set("abcdefghijklmnopqrstuvwxyz0123456789_")
+
+_SCRIPTS = {  # per category; (de, en)
+    "Narration & Story": ("Der Nebel lag noch ueber dem Tal, als sie die alte Muehle erreichte und leise die Tuer oeffnete.",
+                          "Mist still lay over the valley as she reached the old mill and quietly opened the door."),
+    "Conversational": ("Hallo, schoen dass du da bist. Ich zeige dir kurz, wie alles funktioniert, Schritt fuer Schritt.",
+                       "Hi, great to have you here. Let me quickly show you how everything works, step by step."),
+    "Characters & Animation": ("Halt! Wer wagt es, meine Hoehle zu betreten? Na gut, setz dich, der Tee wird kalt.",
+                               "Halt! Who dares enter my cave? Oh, fine, sit down, the tea is getting cold."),
+    "Social Media": ("Okay Leute, heute zeige ich euch drei Tricks, die euren Alltag wirklich einfacher machen. Los geht's!",
+                     "Okay everyone, today I'm showing you three tricks that will really make your day easier. Let's go!"),
+    "Entertainment & TV": ("Guten Abend, meine Damen und Herren, und herzlich willkommen zu einer ganz besonderen Sendung.",
+                           "Good evening, ladies and gentlemen, and welcome to a very special show."),
+    "Advertisement": ("Jetzt neu: der Geschmack, auf den Sie gewartet haben. Probieren Sie es noch heute.",
+                      "Now new: the taste you have been waiting for. Try it today."),
+    "Informative & Educational": ("Heute lernen wir, wie Pflanzen aus Licht Energie gewinnen. Das nennt man Photosynthese.",
+                                  "Today we learn how plants turn light into energy. This is called photosynthesis."),
+}
+_N, _C, _CH, _S, _E, _A, _I = CATEGORIES
+
+# id, name_de, name_en, category, language, gender, age, pitch, accent, tone, instruct
+_ROWS = [
+ ("erzaehler_tief", "Der Chronist", "The Chronicler", _N, "German", "male", "middle-aged", "low", "none", "rich",
+  "Tiefe maennliche deutsche Erzaehlerstimme, mittleres Alter, voll und resonant, langsam und gelassen, klare Artikulation, ruhig und fesselnd, ideal fuer Hoerbuecher."),
+ ("erzaehlerin_warm", "Die Geschichtenerzaehlerin", "The Storyteller", _N, "German", "female", "middle-aged", "mid", "none", "warm",
+  "Warme weibliche deutsche Erzaehlerstimme, mittleres Alter, weich und einfuehlsam, ruhiges Tempo, sanfte Betonung, lebendig bei Spannungsbogen."),
+ ("grossvater_maerchen", "Opa Maerchen", "Grandpa Tales", _N, "German", "male", "elderly", "low", "none", "warm",
+  "Aelterer deutscher Grossvater, tiefe raue warme Stimme, sehr langsam, liebevoll schmunzelnd, erzaehlt Gutenachtgeschichten."),
+ ("oma_vorleserin", "Oma Vorlese", "Granny Reads", _N, "German", "female", "elderly", "mid", "none", "warm",
+  "Aeltere deutsche Frau, sanfte brueckige warme Stimme, langsames beruhigendes Tempo, muetterlich und geduldig."),
+ ("krimi_erzaehler", "Nachtschicht", "Night Shift", _N, "German", "male", "middle-aged", "low", "none", "husky",
+  "Tiefe heisere maennliche deutsche Stimme, trocken und nuechtern, langsames Tempo, duesterer Krimi-Ton mit leiser Spannung."),
+ ("fantasy_barde", "Der Barde", "The Bard", _N, "German", "male", "young adult", "mid", "none", "magnetic",
+  "Junger maennlicher deutscher Geschichtenerzaehler, magnetisch und theatralisch, ausdrucksstarke Betonung, wechselndes Tempo, Fantasy-Abenteuer."),
+ ("literatur_sprecherin", "Literaturabend", "Literary Evening", _N, "German", "female", "young adult", "low", "none", "smooth",
+  "Junge weibliche deutsche Stimme, tief und glatt, ruhig und intim, klare Aussprache, wie bei einer Lesung."),
+ ("british_narrator", "British Narrator", "British Narrator", _N, "English", "male", "middle-aged", "low", "british", "rich",
+  "Middle-aged male British narrator, deep and rich, slow measured pace, calm and authoritative, polished RP accent, suited for audiobooks."),
+ ("assistent_freundlich", "Freundliche Assistentin", "Friendly Assistant", _C, "German", "female", "young adult", "mid", "none", "warm",
+  "Junge weibliche deutsche Stimme, hell und freundlich, natuerliche Sprechgeschwindigkeit, klare Aussprache, nahbar und hilfsbereit."),
+ ("assistent_sachlich", "Sachlicher Assistent", "Matter-of-Fact Assistant", _C, "German", "male", "young adult", "mid", "none", "crisp",
+  "Junge maennliche deutsche Stimme, klar und sachlich, mittleres Tempo, neutral und zuverlaessig, praezise Aussprache."),
+ ("nachbarin_herzlich", "Die Nachbarin", "The Neighbour", _C, "German", "female", "middle-aged", "mid", "none", "warm",
+  "Herzliche weibliche deutsche Stimme, mittleres Alter, locker und plaudernd, schmunzelnd, natuerlicher Alltagston."),
+ ("kumpel_entspannt", "Der Kumpel", "The Buddy", _C, "German", "male", "young adult", "mid", "none", "smooth",
+  "Entspannte junge maennliche deutsche Stimme, lockerer Umgangston, freundlich und humorvoll, natuerliches Tempo."),
+ ("coach_ruhig", "Ruhiger Coach", "Calm Coach", _C, "German", "neutral", "middle-aged", "mid", "none", "smooth",
+  "Ruhige neutrale deutsche Stimme, mittleres Alter, sanft und bestaerkend, langsames Tempo, einfuehlsam, wie ein Meditationsguide."),
+ ("us_friend", "Friendly American", "Friendly American", _C, "English", "female", "young adult", "mid", "american", "warm",
+  "Young adult female American voice, warm and upbeat, natural conversational pace, friendly and clear."),
+ ("drachen_alt", "Der alte Drache", "The Old Dragon", _CH, "German", "male", "elderly", "low", "none", "authoritative",
+  "Uralte maennliche deutsche Stimme, extrem tief und grollend, sehr langsam, majestaetisch und bedrohlich, mit trockenem Humor."),
+ ("hexe_kratzig", "Die Kraeuterhexe", "The Herb Witch", _CH, "German", "female", "elderly", "mid", "none", "husky",
+  "Alte weibliche deutsche Stimme, kratzig und heiser, kichernd, schelmisch und geheimnisvoll, wechselndes Tempo."),
+ ("kind_neugierig", "Kleiner Entdecker", "Little Explorer", _CH, "German", "neutral", "child", "high", "none", "crisp",
+  "Kindliche deutsche Stimme, hoch und hell, neugierig und aufgeregt, schnelles Tempo, begeistert."),
+ ("teen_trotzig", "Der Trotzkopf", "The Rebel", _CH, "German", "female", "teenager", "high", "none", "crisp",
+  "Weibliche deutsche Teenagerstimme, hell, schnippisch und trotzig, schnelles Tempo, genervt aber liebenswert."),
+ ("held_mutig", "Der Held", "The Hero", _CH, "German", "male", "young adult", "mid", "none", "authoritative",
+  "Junger maennlicher deutscher Held, kraeftig und entschlossen, klare feste Stimme, mutig und aufrichtig."),
+ ("schurke_glatt", "Der Schurke", "The Villain", _CH, "German", "male", "middle-aged", "low", "none", "smooth",
+  "Glatte tiefe maennliche deutsche Stimme, kalt und hoeflich, langsames Tempo, bedrohlich leise, selbstgefaellig."),
+ ("roboter_freundlich", "Robo-Freund", "Robo Pal", _CH, "German", "neutral", "young adult", "mid", "none", "crisp",
+  "Neutrale deutsche Robotersaestimme, leicht metallisch und praezise, gleichmaessiges Tempo, freundlich und kindlich naiv."),
+ ("pirat_rau", "Kapitaen Salzbart", "Captain Saltbeard", _CH, "English", "male", "elderly", "low", "southern", "husky",
+  "Elderly male pirate captain, gravelly and husky, slow rolling pace, boisterous and gruff, salty seafaring character."),
+ ("irish_elf", "Irish Sprite", "Irish Sprite", _CH, "English", "female", "young adult", "high", "irish", "warm",
+  "Young adult female voice with a light Irish accent, playful and bright, quick lilting pace, mischievous fairy character."),
+ ("influencer_energie", "Energie-Influencerin", "Energy Influencer", _S, "German", "female", "young adult", "high", "none", "crisp",
+  "Junge weibliche deutsche Stimme, hoch, schnell und energiegeladen, begeistert, direkt an die Kamera gesprochen, Social-Media-Ton."),
+ ("streamer_locker", "Der Streamer", "The Streamer", _S, "German", "male", "young adult", "mid", "none", "crisp",
+  "Junger maennlicher deutscher Streamer, lockere schnelle Sprechweise, witzig und enthusiastisch, umgangssprachlich."),
+ ("kurzvideo_trocken", "Trockener Kommentar", "Deadpan Take", _S, "German", "neutral", "young adult", "mid", "none", "smooth",
+  "Neutrale junge deutsche Stimme, trocken und ironisch, ruhiges Tempo, nuechterner Humor fuer Kurzvideos."),
+ ("reel_sprecher", "Reel-Sprecher", "Reel Voice", _S, "English", "male", "young adult", "mid", "american", "magnetic",
+  "Young adult male American voice, punchy and magnetic, fast energetic pace, hooky delivery for short videos."),
+ ("moderator_abend", "Abendmoderator", "Evening Host", _E, "German", "male", "middle-aged", "mid", "none", "magnetic",
+  "Maennliche deutsche Moderatorenstimme, mittleres Alter, charmant und souveraen, magnetisch, mittleres Tempo, Fernsehshow."),
+ ("moderatorin_quiz", "Quiz-Moderatorin", "Quiz Host", _E, "German", "female", "young adult", "mid", "none", "crisp",
+  "Weibliche deutsche Quizshow-Moderatorin, jung, frisch und lebhaft, klare Betonung, spannungsvolle Pausen."),
+ ("trailer_donner", "Kino-Trailer", "Movie Trailer", _E, "German", "male", "middle-aged", "low", "none", "authoritative",
+  "Sehr tiefe maennliche deutsche Trailerstimme, donnernd und dramatisch, langsam mit starken Pausen, autoritaer."),
+ ("sportreporter", "Sportreporter", "Sports Commentator", _E, "German", "male", "middle-aged", "mid", "none", "crisp",
+  "Maennliche deutsche Sportreporterstimme, schnell und mitreissend, laut, steigende Spannung bei Hoehepunkten."),
+ ("aussie_host", "Aussie Host", "Aussie Host", _E, "English", "male", "young adult", "mid", "australian", "warm",
+  "Young adult male Australian host, laid-back and cheerful, natural conversational pace, charming."),
+ ("werbung_dynamisch", "Werbesprecher", "Ad Voice", _A, "German", "male", "young adult", "mid", "none", "smooth",
+  "Junge maennliche deutsche Werbestimme, glatt und selbstbewusst, dynamisches Tempo, ueberzeugend und sympathisch."),
+ ("werbung_premium", "Premium-Stimme", "Premium Voice", _A, "German", "female", "middle-aged", "low", "none", "rich",
+  "Tiefe weibliche deutsche Stimme, mittleres Alter, samtig und elegant, langsames Tempo, exklusiver Luxus-Ton."),
+ ("werbung_regional", "Der Landmetzger", "The Country Butcher", _A, "German", "male", "middle-aged", "mid", "southern", "warm",
+  "Herzlicher maennlicher deutscher Sprecher mit suedlichem Akzent, bodenstaendig und freundlich, gemuetliches Tempo, regionale Werbung."),
+ ("dozentin_klar", "Die Dozentin", "The Lecturer", _I, "German", "female", "middle-aged", "mid", "none", "crisp",
+  "Weibliche deutsche Dozentenstimme, mittleres Alter, klar und strukturiert, mittleres Tempo, geduldig erklaerend, deutliche Artikulation."),
+ ("doku_sprecher", "Dokumentation", "Documentary", _I, "German", "male", "elderly", "low", "none", "authoritative",
+  "Aeltere maennliche deutsche Stimme, tief und resonant, langsam und gelassen, ruhig und dokumentarisch, serioese vertrauensvolle Praesenz."),
+ ("nachrichten_sprecherin", "Nachrichtensprecherin", "News Anchor", _I, "German", "female", "middle-aged", "mid", "none", "authoritative",
+  "Weibliche deutsche Nachrichtensprecherin, sachlich und souveraen, gleichmaessiges Tempo, klare Standardsprache."),
+ ("kinder_lehrer", "Lehrer Lampe", "Teacher Lamp", _I, "German", "male", "young adult", "mid", "none", "warm",
+  "Junger maennlicher deutscher Lehrer fuer Kinder, freundlich und begeisternd, deutlich und langsam, lobend."),
+ ("science_en", "Science Explainer", "Science Explainer", _I, "English", "female", "young adult", "mid", "british", "crisp",
+  "Young adult female British voice, clear and curious, measured pace, enthusiastic explainer for science content."),
+]
+
+
+def _build() -> tuple[dict, ...]:
+    out, seen = [], set()
+    for (i, de, en, cat, lang, g, a, p, ac, tone, ins) in _ROWS:
+        script = _SCRIPTS[cat]
+        e = {"id": i, "name_de": de, "name_en": en, "instruct": ins, "category": cat, "language": lang,
+             "facets": {"gender": g, "age": a, "pitch": p, "accent": ac, "tone": tone},
+             "sample_script_de": script[0], "sample_script_en": script[1]}
+        if i in seen or not i or set(i) - _ID_OK:
+            raise ValueError(f"archetype id invalid or duplicate: {i!r}")
+        seen.add(i)
+        if cat not in CATEGORIES or lang not in LANGUAGES:
+            raise ValueError(f"{i}: bad category/language")
+        for k, v in e["facets"].items():
+            if v not in FACET_VOCAB[k]:
+                raise ValueError(f"{i}: unknown {k} facet {v!r}")
+        if not 20 <= len(ins) <= 600 or not de or not en:
+            raise ValueError(f"{i}: bad name/instruct length")
+        out.append(e)
+    return tuple(out)
+
+
+ARCHETYPES = _build()
+BY_ID = {a["id"]: a for a in ARCHETYPES}
+MAX_LIMIT = 100
+
+
+def _lang_name(v: str) -> str:
+    """ISO code or full name, case-insensitive -> canonical name; unknown values pass through (match nothing)."""
+    v = (v or "").strip()
+    return LANG_NAMES.get(v.lower()) or next((n for n in LANG_NAMES.values() if n.lower() == v.lower()), v)
+
+
+def list_archetypes(gender="", age="", pitch="", accent="", language="", category="", q="",
+                    offset=0, limit=24) -> dict:
+    flt = {"gender": gender, "age": age, "pitch": pitch, "accent": accent}
+    ql = (q or "").strip().lower()[:100]
+    lang = _lang_name(language)
+    rows = []
+    for a in ARCHETYPES:
+        if any(v and a["facets"][k] != v for k, v in flt.items()):
+            continue
+        if lang and a["language"] != lang or category and a["category"] != category:
+            continue
+        if ql and ql not in f'{a["name_de"]} {a["name_en"]} {a["instruct"]} {a["category"]}'.lower():
+            continue
+        rows.append(a)
+    offset = max(0, int(offset)); limit = max(1, min(MAX_LIMIT, int(limit)))
+    return {"total": len(rows), "offset": offset, "limit": limit, "items": rows[offset:offset + limit]}
+
+
+def preview_key(a: dict, engine: str, seed: int = SEED) -> str:
+    import hashlib
+    return hashlib.sha256(f'{a["instruct"]}|{a["language"]}|{engine}|{seed}'.encode()).hexdigest()

core/voice_bundle.py

@@ -0,0 +1,231 @@
+"""Voice export/import bundles (ZIP). See architecture/voice-bundle.md.
+
+Export streams a ZIP (no temp files). Import treats the archive as hostile:
+only fixed flat member names, capped sizes, hashes verified, nothing executed,
+no path from the archive is ever used.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Iterator
+
+from core.provenance import CONSENT_EXTS, MAX_CONSENT_BYTES, validate_provenance
+from core.voice import (
+    _AUDIO_EXTS, _PICTURE_EXTS, _find_voice_audio, _load_meta,
+    _save_meta, _validate_voice_meta, _voice_problems,
+)
+
+FORMAT_VERSION = 1
+MAX_BUNDLE_BYTES = 150 * 1024 * 1024      # compressed upload
+MAX_TOTAL_BYTES = 200 * 1024 * 1024       # uncompressed, all members
+MAX_AUDIO_BYTES = 150 * 1024 * 1024
+MAX_PICTURE_BYTES = 10 * 1024 * 1024
+MAX_TEXT_BYTES = 256 * 1024
+MAX_RATIO = 200                           # per-member compression ratio (zip-bomb)
+ID_RE = re.compile(r"^[A-Za-z0-9_\-][A-Za-z0-9_\-.]{0,99}$")
+_PICTURE_SET = {e.lstrip(".") for e in _PICTURE_EXTS}
+_AUDIO_SET = {e.lstrip(".") for e in _AUDIO_EXTS}
+_CONSENT_SET = {e.lstrip(".") for e in CONSENT_EXTS}
+
+
+class BundleError(ValueError):
+    """Invalid bundle (-> HTTP 400)."""
+
+
+def _limit_for(name: str) -> int | None:
+    if name in ("manifest.json", "meta.json", "reference.txt"):
+        return MAX_TEXT_BYTES
+    stem, _, ext = name.rpartition(".")
+    if stem == "audio" and ext in _AUDIO_SET:
+        return MAX_AUDIO_BYTES
+    if stem == "picture" and ext in _PICTURE_SET:
+        return MAX_PICTURE_BYTES
+    if stem == "consent" and ext in _CONSENT_SET:
+        return MAX_CONSENT_BYTES
+    return None
+
+
+def _app_version() -> str:
+    try:
+        return (Path(__file__).resolve().parents[1] / "VERSION").read_text().strip()
+    except OSError:
+        return "unknown"
+
+
+# ── export ────────────────────────────────────────────────────────────────────
+
+class _Sink:
+    """Non-seekable write target; the generator drains it between chunks."""
+    def __init__(self): self.buf = bytearray(); self.pos = 0
+    def write(self, b): self.buf += b; self.pos += len(b); return len(b)
+    def tell(self): return self.pos
+    def flush(self): pass
+    def drain(self):
+        out = bytes(self.buf); self.buf.clear(); return out
+
+
+def export_members(wav: Path) -> tuple[dict, list[tuple[str, Path | bytes]]]:
+    """Return (meta_for_bundle, [(member_name, path-or-bytes)]) for a voice."""
+    meta = _load_meta(wav)
+    meta["audio_problems"] = list(meta.get("audio_problems") or _voice_problems(wav))
+    members: list[tuple[str, Path | bytes]] = [(f"audio{wav.suffix.lower()}", wav)]
+    ref = wav.with_suffix(".reference.txt")
+    if ref.is_file():
+        members.append(("reference.txt", ref))
+    for ext in _PICTURE_EXTS:
+        pic = wav.with_suffix(ext)
+        if pic.is_file():
+            members.append((f"picture{ext}", pic))
+            break
+    consent = wav.with_suffix(".consent")
+    rec = (meta.get("provenance") or {}).get("recorded_consent") or ""
+    if consent.is_file() and Path(rec).suffix.lower() in CONSENT_EXTS:
+        members.append((f"consent{Path(rec).suffix.lower()}", consent))
+    members.append(("meta.json", (json.dumps(meta, indent=2, ensure_ascii=False) + "\n").encode()))
+    return meta, members
+
+
+def stream_bundle(voice_id: str, members: list[tuple[str, Path | bytes]]) -> Iterator[bytes]:
+    """Yield a ZIP; manifest.json (with sha256 per file) is written last."""
+    sink, hashes = _Sink(), {}
+    with zipfile.ZipFile(sink, "w", zipfile.ZIP_DEFLATED) as zf:
+        for name, src in members:
+            h = hashlib.sha256()
+            with zf.open(name, "w", force_zip64=True) as out:
+                if isinstance(src, bytes):
+                    h.update(src); out.write(src)
+                else:
+                    with src.open("rb") as f:
+                        while chunk := f.read(1024 * 1024):
+                            h.update(chunk); out.write(chunk)
+                            if sink.buf:
+                                yield sink.drain()
+            hashes[name] = h.hexdigest()
+            yield sink.drain()
+        manifest = {"format": FORMAT_VERSION, "app_version": _app_version(),
+                    "voice_id": voice_id, "files": hashes}
+        zf.writestr("manifest.json", json.dumps(manifest, indent=2))
+    yield sink.drain()
+
+
+# ── import ────────────────────────────────────────────────────────────────────
+
+def _read_member(zf: zipfile.ZipFile, info: zipfile.ZipInfo, limit: int, dest: Path | None = None) -> tuple[bytes, str]:
+    """Read at most `limit` bytes (declared size is not trusted); returns (data|b'', sha256)."""
+    h, total, data = hashlib.sha256(), 0, bytearray()
+    out = dest.open("wb") if dest else None
+    try:
+        with zf.open(info) as f:
+            while chunk := f.read(1024 * 1024):
+                total += len(chunk)
+                if total > limit:
+                    raise BundleError(f"Bundle member too large: {info.filename}")
+                h.update(chunk)
+                (out.write(chunk) if out else data.extend(chunk))
+    finally:
+        if out: out.close()
+    return bytes(data), h.hexdigest()
+
+
+def import_bundle(zip_path: Path, voices_dir: Path, scan_dir: Path, decode_check=None) -> dict:
+    """Validate and install a bundle. Returns {voice_id, status, wav}.
+
+    status: "imported" | "renamed" (name taken -> suffix) | "unchanged" (identical already present).
+    `decode_check(path)` must raise if the audio is not decodable.
+    """
+    if not zipfile.is_zipfile(zip_path):
+        raise BundleError("Not a ZIP file")
+    voices_dir.mkdir(parents=True, exist_ok=True)
+    stage = Path(tempfile.mkdtemp(prefix=".import-", dir=voices_dir))
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            infos = zf.infolist()
+            names = [i.filename for i in infos]
+            if len(set(names)) != len(names):
+                raise BundleError("Duplicate members in bundle")
+            total = 0
+            for i in infos:
+                if i.is_dir() or _limit_for(i.filename) is None:  # also rejects any path / traversal / unknown name
+                    raise BundleError("Unexpected member in bundle")
+                if i.file_size > _limit_for(i.filename) or (i.compress_size and i.file_size / i.compress_size > MAX_RATIO and i.file_size > 1024 * 1024):
+                    raise BundleError("Bundle member too large or suspiciously compressed")
+                total += i.file_size
+            if total > MAX_TOTAL_BYTES:
+                raise BundleError("Bundle is too large when unpacked")
+            by_name = {i.filename: i for i in infos}
+            if "manifest.json" not in by_name:
+                raise BundleError("manifest.json missing")
+            raw, _ = _read_member(zf, by_name["manifest.json"], MAX_TEXT_BYTES)
+            try:
+                manifest = json.loads(raw)
+            except ValueError:
+                raise BundleError("manifest.json is not valid JSON")
+            if not isinstance(manifest, dict) or manifest.get("format") != FORMAT_VERSION:
+                raise BundleError("Unsupported bundle format version")
+            files = manifest.get("files")
+            if not isinstance(files, dict) or set(files) != set(by_name) - {"manifest.json"}:
+                raise BundleError("Manifest does not match bundle contents")
+            voice_id = manifest.get("voice_id")
+            if not isinstance(voice_id, str) or not ID_RE.match(voice_id) or ".." in voice_id:
+                raise BundleError("Invalid voice id in manifest")
+            audio = [n for n in files if n.startswith("audio.")]
+            if len(audio) != 1:
+                raise BundleError("Bundle needs exactly one audio file")
+            staged: dict[str, Path] = {}
+            for n, expected in files.items():
+                p = stage / n  # n is a validated fixed name, never a path from the archive
+                _, digest = _read_member(zf, by_name[n], _limit_for(n), p)
+                if digest != expected:
+                    raise BundleError(f"Hash mismatch: {n}")
+                staged[n] = p
+        # decode + metadata re-validation (nothing is installed yet)
+        if decode_check:
+            try:
+                decode_check(staged[audio[0]])
+            except Exception:
+                raise BundleError("Audio file cannot be decoded")
+        try:
+            meta = json.loads(staged["meta.json"].read_bytes()) if "meta.json" in staged else {}
+            consent = next((n for n in staged if n.startswith("consent.")), None)
+            if "provenance" in meta:
+                prev = {"recorded_consent": "x"} if consent else None
+                meta["provenance"] = validate_provenance(meta["provenance"], prev)
+                meta["provenance"].pop("recorded_consent", None)
+                if consent:
+                    meta["provenance"]["recorded_consent"] = "consent" + Path(consent).suffix
+            _validate_voice_meta(meta)
+        except (ValueError, TypeError, AttributeError) as exc:
+            raise BundleError(f"Invalid metadata: {exc}")
+        # name handling: never overwrite; identical audio already present -> idempotent no-op
+        new_hash = files[audio[0]]
+        suffix = Path(audio[0]).suffix
+        vid, status, n = voice_id, "imported", 1
+        while (existing := _find_voice_audio(vid, scan_dir)) is not None or (voices_dir / f"{vid}{suffix}").exists():
+            if existing is not None and hashlib.sha256(existing.read_bytes()).hexdigest() == new_hash:
+                return {"voice_id": vid, "status": "unchanged", "wav": str(existing)}
+            n += 1
+            vid, status = f"{voice_id}_{n}", "renamed"
+            if n > 99:
+                raise BundleError("Too many voices with this name")
+        if consent:
+            meta.get("provenance", {}).update(recorded_consent=f"{vid}{Path(consent).suffix}")
+        dest = voices_dir / f"{vid}{suffix}"
+        shutil.move(str(staged[audio[0]]), dest)
+        if "reference.txt" in staged:
+            shutil.move(str(staged["reference.txt"]), dest.with_suffix(".reference.txt"))
+        for n_, p in staged.items():
+            if n_.startswith("picture."):
+                shutil.move(str(p), dest.with_suffix(Path(n_).suffix))
+            elif consent and n_ == consent:
+                shutil.move(str(p), dest.with_suffix(".consent"))
+        meta.pop("needs_tts_restart", None)
+        _save_meta(dest, meta)
+        return {"voice_id": vid, "status": status, "wav": str(dest)}
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)

guided_installer.py

@@ -6,6 +6,7 @@ import platform
 import queue
 import shutil
 import subprocess
+import tempfile
 import threading
 import webbrowser
 from pathlib import Path
@@ -45,6 +46,21 @@ MODEL_EXPLANATIONS = {
 }
 
 
+def run_command(cmd: list[str], log) -> bool:
+    """Run one command, log its output; return False if it failed (non-zero exit or exception)."""
+    try:
+        proc = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True)
+    except Exception as exc:
+        log(f"Failed: {exc}")
+        return False
+    for out in (proc.stdout, proc.stderr):
+        if out:
+            log(out)
+    if proc.returncode:
+        log(f"Command exited with {proc.returncode}")
+    return not proc.returncode
+
+
 class GuidedInstaller(tk.Tk):
     def __init__(self) -> None:
         super().__init__()
@@ -186,23 +202,15 @@ class GuidedInstaller(tk.Tk):
             self.log.see("end")
         self.after(120, self._drain_log)
 
-    def run_threaded(self, title: str, commands: list[list[str]]) -> None:
+    def run_threaded(self, title: str, commands: list[list[str]], cleanup_dir: str | None = None) -> None:
         def worker():
             self.log_line(f"\n== {title} ==")
             for cmd in commands:
                 self.log_line("$ " + " ".join(cmd))
-                try:
-                    proc = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True)
-                    if proc.stdout:
-                        self.log_line(proc.stdout)
-                    if proc.stderr:
-                        self.log_line(proc.stderr)
-                    if proc.returncode:
-                        self.log_line(f"Command exited with {proc.returncode}")
-                        break
-                except Exception as exc:
-                    self.log_line(f"Failed: {exc}")
+                if not run_command(cmd, self.log_line):
                     break
+            if cleanup_dir:
+                shutil.rmtree(cleanup_dir, ignore_errors=True)
         threading.Thread(target=worker, daemon=True).start()
 
     def command_ok(self, cmd: list[str]) -> bool:
@@ -260,11 +268,13 @@ class GuidedInstaller(tk.Tk):
             "Run Docker's official Linux convenience installer?\n\nThis may ask for sudo privileges and needs internet access.",
         ):
             return
+        tmp = tempfile.mkdtemp(prefix="docker-install-")  # 0700, unpredictable name
+        script = os.path.join(tmp, "get-docker.sh")
         self.run_threaded("Install Docker", [
-            ["curl", "-fsSL", "https://get.docker.com", "-o", "/tmp/get-docker.sh"],
-            ["sh", "/tmp/get-docker.sh"],
+            ["curl", "-fsSL", "https://get.docker.com", "-o", script],
+            ["sh", script],
             ["docker", "version"],
-        ])
+        ], cleanup_dir=tmp)
 
     def generate_compose(self) -> None:
         GENERATED_DIR.mkdir(parents=True, exist_ok=True)

package.json

@@ -10,6 +10,7 @@
     "install:browsers": "playwright install chromium",
     "minify": "node scripts/minify.mjs",
     "check:frontend": "node scripts/check-frontend.mjs",
+    "qa": "node scripts/qa.mjs",
     "test:unit": "node --test tests/*.test.mjs"
   },
   "devDependencies": {

routes/admin.py

@@ -199,7 +199,8 @@ async def browse_dirs_mkdir(payload: dict = Body(...)):
 
 @router.get("/api/version")
 async def get_version():
-    return {"version": __version__}
+    from core.vocal_isolation import available as _vocal_isolation
+    return {"version": __version__, "features": {"vocal_isolation": _vocal_isolation()}}
 
 
 @router.get("/api/changelog", response_class=PlainTextResponse)

routes/archetypes.py

@@ -0,0 +1,132 @@
+"""Voice archetype gallery: catalog, cached preview rendering, save-as-designed-voice."""
+from __future__ import annotations
+
+import asyncio
+import io
+import logging
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Query
+from fastapi.responses import FileResponse
+
+from core import voice_archetypes as va
+from core.audio import _export_normalized_wav
+from core.config import _load_settings
+from core.constants import CONFIG_DIR, _VOICE_DESIGN_MODEL, _VOICES_DIR_DEFAULT
+from core.provenance import validate_provenance
+from core.voice import _active_voices_dir, _find_voice_audio, _load_meta, _save_meta
+from core.voice_index import upsert_voice_in_index
+
+logger = logging.getLogger("uvicorn.error")
+router = APIRouter()
+
+RENDER_TIMEOUT_S = 240
+MAX_PREVIEW_BYTES = 8 * 1024 * 1024
+_LOCKS: dict[str, asyncio.Lock] = {}
+
+
+def cache_dir() -> Path:
+    return CONFIG_DIR / "archetype_previews"  # config/ is git-ignored; catalog is small so the cache is bounded
+
+
+def _get(aid: str) -> dict:
+    a = va.BY_ID.get(aid)
+    if a is None:
+        raise HTTPException(404, "Unknown archetype")
+    return a
+
+
+def _sample_text(a: dict) -> str:
+    return a["sample_script_de"] if a["language"] == "German" else a["sample_script_en"]
+
+
+def _is_blank(audio: bytes) -> bool:
+    from pydub import AudioSegment
+    seg = AudioSegment.from_file(io.BytesIO(audio))
+    return len(seg) < 300 or seg.max_possible_amplitude == 0 or seg.rms < 20
+
+
+def _render(a: dict, settings: dict) -> bytes:
+    """Blocking synthesis through the existing voice-design path, seed pinned."""
+    from core.tts_helpers import _voice_design_request_audio
+    pinned = {**settings, "tts_stability_enabled": True,
+              "tts_extra_params_by_backend": {"voice_design": {"seed": va.SEED}}}
+    gender = {"male": "M", "female": "F"}.get(a["facets"]["gender"], "")
+    audio, _ = _voice_design_request_audio(a["instruct"], _sample_text(a), a["language"], pinned, gender)
+    return audio
+
+
+async def _cached_preview(a: dict) -> Path:
+    key = va.preview_key(a, _VOICE_DESIGN_MODEL)
+    path = cache_dir() / f"{key[:32]}.wav"
+    if path.exists():
+        return path
+    lock = _LOCKS.setdefault(key, asyncio.Lock())
+    async with lock:
+        if path.exists():
+            return path
+        from routes.tts import _bounded_tts_call
+        try:
+            audio = await asyncio.wait_for(_bounded_tts_call(_render, a, _load_settings()), RENDER_TIMEOUT_S)
+        except HTTPException:
+            raise
+        except asyncio.TimeoutError:
+            raise HTTPException(504, "Preview rendering timed out")
+        except Exception as exc:
+            logger.warning("archetype preview failed (%s): %s", a["id"], exc)
+            raise HTTPException(502, "Preview rendering failed")
+        if not audio or len(audio) > MAX_PREVIEW_BYTES or _is_blank(audio):
+            raise HTTPException(502, "Engine returned blank or oversized audio")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+        with open(fd, "wb") as fh:
+            fh.write(audio)
+        Path(tmp).replace(path)
+    return path
+
+
+@router.get("/api/archetypes")
+async def archetypes_list(gender: str = "", age: str = "", pitch: str = "", accent: str = "",
+                          language: str = "", category: str = "", q: str = "",
+                          offset: int = Query(0, ge=0), limit: int = Query(24, ge=1, le=va.MAX_LIMIT)):
+    res = va.list_archetypes(gender, age, pitch, accent, language, category, q, offset, limit)
+    res["categories"] = list(va.CATEGORIES)
+    res["cached"] = [a["id"] for a in res["items"] if (cache_dir() / f"{va.preview_key(a, _VOICE_DESIGN_MODEL)[:32]}.wav").exists()]
+    return res
+
+
+@router.post("/api/archetypes/{aid}/preview")
+async def archetype_preview(aid: str):
+    return FileResponse(await _cached_preview(_get(aid)), media_type="audio/wav")
+
+
+@router.post("/api/archetypes/{aid}/use")
+async def archetype_use(aid: str):
+    a = _get(aid)
+    voice_id = f"archetype_{aid}"
+    settings = _load_settings()
+    existing = _find_voice_audio(voice_id, Path(settings.get("voices_scan_dir", _VOICES_DIR_DEFAULT)))
+    if existing is not None:  # idempotent per archetype id
+        return {"voice_id": voice_id, "created": False, "instruct": a["instruct"], "language": a["language"]}
+    src = await _cached_preview(a)
+    out_dir = _active_voices_dir(settings)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    wav = out_dir / f"{voice_id}.wav"
+    text = _sample_text(a)
+    await asyncio.to_thread(_export_normalized_wav, src, wav)
+    wav.with_suffix(".reference.txt").write_text(text, encoding="utf-8")
+    meta = _load_meta(wav)
+    meta.update({
+        "enabled": True, "origin": "designed", "name": a["name_de"], "gender": a["facets"]["gender"][:1].upper(),
+        "lang": a["language"], "transcript": text, "voice_design_prompt": a["instruct"],
+        "note": "Voice Archetype: " + a["instruct"][:240],
+        # no 'synthetic' basis exists in core.provenance.BASES; 'unknown' is the closest honest value
+        # (no real person, no consent/licence needed). ':' is avoided in source because
+        # validate_provenance parses 'x:' as a URL scheme.
+        "provenance": validate_provenance(
+            {"basis": "unknown", "source": f"archetype/{aid}", "note": "synthetic designed voice"}),
+    })
+    _save_meta(wav, meta)
+    await asyncio.to_thread(upsert_voice_in_index, settings, wav)
+    return {"voice_id": voice_id, "created": True, "instruct": a["instruct"], "language": a["language"]}

routes/conversation.py

@@ -23,6 +23,7 @@ from PIL import Image, ImageDraw, ImageOps
 from fastapi import APIRouter, File, Form, Header, HTTPException, Request, UploadFile
 from fastapi.responses import Response, StreamingResponse
 
+from core.tasks import spawn
 from core.config import _load_settings, _save_settings, _clean_preview_backend
 from core.constants import _VOICES_DIR_DEFAULT, _MAX_UPLOAD_BYTES
 from core.registry import _registry_get, TEMP_DIR
@@ -45,6 +46,7 @@ from core.attribution_spans import (
     parse_response as _span_parse_response, validate_spans as _span_validate,
     validate_only_ids as _span_validate_only_ids,
 )
+from core import ssml_lite
 from core.tts_helpers import _preview_request_audio
 from routes.stt import _transcribe_audio, _clean_stt_backend
 
@@ -929,7 +931,7 @@ async def match_characters_voices(request: Request):
                     oldest = min(_CAST_JOB_IDEMPOTENCY, key=lambda key: _CAST_JOB_IDEMPOTENCY[key][1])
                     _CAST_JOB_IDEMPOTENCY.pop(oldest, None)
         _cast_job_trim()
-        asyncio.create_task(_run_cast_job(job_id, job_data, {"idempotency-key": idempotency_key}))
+        spawn(_run_cast_job(job_id, job_data, {"idempotency-key": idempotency_key}))
         return {"job_id": job_id, "stage": "queued"}
     request_fingerprint = hashlib.sha256(json.dumps(data, sort_keys=True, default=str).encode()).hexdigest()
     if idempotency_key:
@@ -5670,7 +5672,9 @@ async def speak(request: Request):
     instruct = str(data.get("instruct") or "")
     try:
         audio, media_type = await asyncio.to_thread(
-            _preview_request_audio, text, voice, settings, instruct, backend
+            ssml_lite.render_with_tags, text,
+            lambda t: _preview_request_audio(t, voice, settings, instruct, backend),
+            "auto", bool(settings.get("inline_tags_enabled")),
         )
     except Exception as e:
         raise HTTPException(502, f"TTS error: {e}")
@@ -5813,7 +5817,9 @@ async def _mcp_tool_speak(args: dict, client_id: str) -> dict:
                 llm_model = settings.get("llm_model") or ""
                 text = await asyncio.to_thread(_rewrite_with_persona_sync, text, persona, llm_url, llm_model)
     audio, _media_type = await asyncio.to_thread(
-        _preview_request_audio, text, voice, settings, "", "voice_clone"
+        ssml_lite.render_with_tags, text,
+        lambda t: _preview_request_audio(t, voice, settings, "", "voice_clone"),
+        "auto", bool(settings.get("inline_tags_enabled")),
     )
     audio_b64 = base64.b64encode(audio).decode()
     return {
@@ -6103,6 +6109,8 @@ def _make_tts_task(
     sem: "asyncio.Semaphore | None",
     emotion: str = "",
 ) -> "asyncio.Task":
+    if settings.get("inline_tags_enabled"):
+        text = ssml_lite.plain_text(text) or text   # sentence-streamed chat reply: tags stripped, never spoken
     tts_text, instruct = _conv_tts_text_and_instruct(text, emotion, backend)
     if sem is None:
         return asyncio.create_task(

routes/library.py

@@ -9,8 +9,9 @@ from datetime import datetime
 from pathlib import Path
 
 from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
-from fastapi.responses import FileResponse, Response
+from fastapi.responses import FileResponse, Response, StreamingResponse
 
+from core.tasks import spawn
 from core.config import _load_settings
 from core.constants import _VOICES_DIR_DEFAULT, _OUTPUT_DIR_DEFAULT, _VOICE_TARGET_DBFS, _VOICE_PEAK_DBFS, _BENCHMARK_SENTENCES, _MAX_TTS_OUTPUT_SECONDS, _MAX_UPLOAD_BYTES, _MAX_PICTURE_BYTES, _MAX_SOUND_BYTES, _ALLOW_PRIVATE_DOWNLOADS
 from core.registry import _registry_put, _registry_get, TEMP_DIR
@@ -429,6 +430,14 @@ async def list_voices(refresh: bool = False):
     return await asyncio.to_thread(indexed_voices, settings, refresh=refresh)
 
 
+@router.get("/api/voices/{voice_id}/health")
+async def get_voice_health(voice_id: str):
+    settings = _load_settings()
+    scan_dir = Path(settings.get("voices_scan_dir", _VOICES_DIR_DEFAULT))
+    audio = _find_voice_audio(voice_id, scan_dir)
+    return await asyncio.to_thread(_voice_health, audio, analyze=True)
+
+
 @router.get("/api/voices/index")
 async def get_voice_index_info():
     return voice_index_info()
@@ -486,6 +495,96 @@ async def update_voice_meta(request: Request):
             if wav.with_suffix(".reference.txt").exists() else ""}
 
 
+def _provenance_voice(voice_id: str) -> tuple[Path, dict]:
+    settings = _load_settings()
+    wav = _find_voice_audio(voice_id, Path(settings.get("voices_scan_dir", _VOICES_DIR_DEFAULT)))
+    if wav is None:
+        raise HTTPException(404, f"Voice '{voice_id}' not found")
+    return wav, settings
+
+
+@router.put("/api/voices/{voice_id}/provenance")
+async def put_voice_provenance(voice_id: str, request: Request):
+    from core.provenance import validate_provenance
+    wav, _ = _provenance_voice(voice_id)
+    try:
+        data = await request.json()
+        meta = _load_meta(wav)
+        meta["provenance"] = validate_provenance(data, meta.get("provenance"))
+    except ValueError as exc:
+        raise HTTPException(400, str(exc))
+    _save_meta(wav, meta)
+    return {"ok": True, "provenance": meta["provenance"]}
+
+
+@router.post("/api/voices/{voice_id}/consent-recording")
+async def upload_consent_recording(voice_id: str, file: UploadFile = File(...)):
+    from core.provenance import CONSENT_EXTS, MAX_CONSENT_BYTES
+    wav, _ = _provenance_voice(voice_id)
+    suffix = _validated_upload_suffix(file.filename, default=".webm", allowed=CONSENT_EXTS)
+    if not (file.content_type or "").split(";")[0].strip().lower().startswith(("audio/", "video/webm")):
+        raise HTTPException(400, "Consent recording must be an audio file")
+    dest = wav.with_suffix(".consent")
+    tmp = dest.with_name(dest.name + ".part")
+    try:
+        with tmp.open("wb") as f:
+            _copy_limited(file.file, f, MAX_CONSENT_BYTES)
+        tmp.replace(dest)
+    finally:
+        tmp.unlink(missing_ok=True)
+    meta = _load_meta(wav)
+    prov = dict(meta.get("provenance") or {"basis": "unknown"})
+    prov["recorded_consent"] = f"{wav.stem}{suffix}"  # original type; served from the .consent file
+    meta["provenance"] = prov
+    _save_meta(wav, meta)
+    return {"ok": True, "provenance": prov}
+
+
+@router.get("/api/voices/{voice_id}/consent-recording")
+async def serve_consent_recording(voice_id: str):
+    from core.provenance import CONSENT_MIME
+    wav, _ = _provenance_voice(voice_id)
+    prov = _load_meta(wav).get("provenance") or {}
+    f = wav.with_suffix(".consent")
+    if not prov.get("recorded_consent") or not f.is_file():
+        raise HTTPException(404, "No consent recording")
+    mime = CONSENT_MIME.get(Path(prov["recorded_consent"]).suffix.lower(), "audio/webm")
+    return FileResponse(str(f), media_type=mime, headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"})
+
+
+@router.get("/api/voices/{voice_id}/export")
+async def export_voice_bundle(voice_id: str):
+    from core import voice_bundle as vb
+    wav, _ = _provenance_voice(voice_id)
+    _, members = await asyncio.to_thread(vb.export_members, wav)
+    safe = re.sub(r"[^A-Za-z0-9_.-]", "_", wav.stem)
+    return StreamingResponse(vb.stream_bundle(wav.stem, members), media_type="application/zip",
+                             headers={"Content-Disposition": f'attachment; filename="{safe}.voice.zip"',
+                                      "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"})
+
+
+@router.post("/api/voices/import")
+async def import_voice_bundle(file: UploadFile = File(...)):
+    from pydub import AudioSegment
+    from core import voice_bundle as vb
+    settings = _load_settings()
+    tmp = TEMP_DIR / f"bundle-{uuid.uuid4().hex}.zip"
+    try:
+        with tmp.open("wb") as f:
+            _copy_limited(file.file, f, vb.MAX_BUNDLE_BYTES)
+        try:
+            res = await asyncio.to_thread(
+                vb.import_bundle, tmp, _active_voices_dir(settings),
+                Path(settings.get("voices_scan_dir", _VOICES_DIR_DEFAULT)),
+                lambda p: AudioSegment.from_file(str(p)))
+        except vb.BundleError as exc:
+            raise HTTPException(400, str(exc))
+    finally:
+        tmp.unlink(missing_ok=True)
+    await asyncio.to_thread(upsert_voice_in_index, settings, Path(res["wav"]))
+    return {"ok": True, "voice_id": res["voice_id"], "status": res["status"]}
+
+
 @router.post("/api/voices/sync-folders")
 async def sync_voice_folders():
     settings = _load_settings()
@@ -641,7 +740,7 @@ async def prepare_missing_references(request: Request):
         "errors": [],
         "started_at": datetime.now().isoformat(),
     }
-    asyncio.create_task(_run_prepare_missing_job(job_id, candidates, settings))
+    spawn(_run_prepare_missing_job(job_id, candidates, settings))
     return {"job_id": job_id, "queued": len(candidates)}
 
 

routes/magazine.py

@@ -24,6 +24,7 @@ import io
 import json
 import logging
 import re
+import shutil
 import statistics
 import time
 import uuid
@@ -37,6 +38,7 @@ from fastapi.responses import FileResponse, Response
 from core import magazine as mag
 from core import magazine_untitled as untitled
 from core import word_alignment
+from core.tasks import spawn
 from core.config import _load_settings
 from core.constants import CONFIG_DIR
 from core.database import (
@@ -510,7 +512,7 @@ async def magazine_ingest(doc_id: str, request: Request):
     meta["ingest"] = {"status": "running", "job_id": job_id}
     _write_meta(d, meta)
 
-    asyncio.create_task(
+    spawn(
         asyncio.to_thread(_ingest_sync, doc_id, job_id, ocr_lang, render_dpi,
                           vision_ocr_url, vision_ocr_model,
                           vision_ocr_fallback_url, vision_ocr_fallback_model,
@@ -986,7 +988,7 @@ async def magazine_suggest_titles(doc_id: str):
     _require_magazine(doc_id)
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-suggest-titles", fingerprint=doc_id)
-    asyncio.create_task(asyncio.to_thread(_suggest_titles_sync, doc_id, job_id))
+    spawn(asyncio.to_thread(_suggest_titles_sync, doc_id, job_id))
     return {"job_id": job_id}
 
 
@@ -1381,7 +1383,7 @@ async def magazine_reocr_page(doc_id: str, page: int, request: Request):
         raise HTTPException(409, f"Page {page} is still being read; wait for it to finish")
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-reocr-page", fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(
+    spawn(
         asyncio.to_thread(_reocr_page_sync, doc_id, job_id, page,
                           vision_ocr_url, vision_ocr_model,
                           vision_ocr_fallback_url, vision_ocr_fallback_model)
@@ -1419,7 +1421,7 @@ async def magazine_rotate_page(doc_id: str, page: int, request: Request):
         raise HTTPException(409, f"Page {page} is still being turned or read; wait for it to finish before turning it again")
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-rotate-page", fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(asyncio.to_thread(_reocr_page_sync, doc_id, job_id, page, url, model, fb_url, fb_model, degrees))
+    spawn(asyncio.to_thread(_reocr_page_sync, doc_id, job_id, page, url, model, fb_url, fb_model, degrees))
     return {"job_id": job_id, "degrees": degrees}
 
 
@@ -1470,7 +1472,7 @@ def _start_quality_page_job(doc_id: str, page: int, mode: str,
     job_id = uuid.uuid4().hex
     background_job_create(job_id, f"magazine-quality-{mode}",
                           fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(asyncio.to_thread(
+    spawn(asyncio.to_thread(
         _quality_page_sync, doc_id, job_id, page, mode,
         str(settings.get("vision_ocr_url") or "").strip() or None,
         str(settings.get("vision_ocr_model") or "").strip() or None,
@@ -1701,7 +1703,7 @@ async def magazine_quality_run(doc_id: str):
     _require_magazine(doc_id)
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-quality-run", fingerprint=doc_id)
-    asyncio.create_task(asyncio.to_thread(_quality_run_sync, doc_id, job_id, _load_settings()))
+    spawn(asyncio.to_thread(_quality_run_sync, doc_id, job_id, _load_settings()))
     return {"job_id": job_id}
 
 
@@ -1769,7 +1771,7 @@ async def magazine_autofix_page(doc_id: str, page: int, request: Request):
     mode = "boxes" if isinstance(body, dict) and body.get("mode") == "boxes" else "all"
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-autofix", fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(asyncio.to_thread(_autofix_page_sync, doc_id, job_id, page, mode, _load_settings()))
+    spawn(asyncio.to_thread(_autofix_page_sync, doc_id, job_id, page, mode, _load_settings()))
     return {"job_id": job_id}
 
 
@@ -2252,7 +2254,7 @@ async def magazine_refine_figures(doc_id: str):
     _require_magazine(doc_id)
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-refine-figures", fingerprint=doc_id)
-    asyncio.create_task(asyncio.to_thread(_refine_figures_sync, doc_id, job_id))
+    spawn(asyncio.to_thread(_refine_figures_sync, doc_id, job_id))
     return {"job_id": job_id}
 
 
@@ -2266,7 +2268,7 @@ async def magazine_refine_page_figures(doc_id: str, page: int):
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-refine-page-figures",
                           fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(asyncio.to_thread(_refine_figures_sync, doc_id, job_id, page))
+    spawn(asyncio.to_thread(_refine_figures_sync, doc_id, job_id, page))
     return {"job_id": job_id}
 
 
@@ -2327,7 +2329,7 @@ async def magazine_add_region(doc_id: str, page: int, request: Request):
 
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-add-region", fingerprint=f"{doc_id}:{page}")
-    asyncio.create_task(
+    spawn(
         asyncio.to_thread(_add_region_sync, doc_id, job_id, page, [float(v) for v in bbox], kind, text,
                           vision_ocr_url, vision_ocr_model,
                           vision_ocr_fallback_url, vision_ocr_fallback_model)
@@ -2547,7 +2549,7 @@ async def magazine_describe_image(doc_id: str, image_id: str, request: Request):
 
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-describe-image", fingerprint=f"{doc_id}:{image_id}")
-    asyncio.create_task(
+    spawn(
         asyncio.to_thread(_describe_image_sync, doc_id, job_id, image_id,
                           vision_ocr_url, vision_ocr_model,
                           vision_ocr_fallback_url, vision_ocr_fallback_model)
@@ -3014,7 +3016,7 @@ async def magazine_spelling_agent(doc_id: str, request: Request):
         raise HTTPException(400, "No LLM model configured")
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-spelling", fingerprint=f"{doc_id}:{article or page or 'all'}")
-    asyncio.create_task(asyncio.to_thread(_spelling_agent_job, doc_id, job_id, article, page, settings))
+    spawn(asyncio.to_thread(_spelling_agent_job, doc_id, job_id, article, page, settings))
     return {"job_id": job_id}
 
 
@@ -3220,7 +3222,7 @@ async def magazine_generate_article_audio(doc_id: str, article_id: str, request:
         raise HTTPException(400, "No narrator voice given")
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-article-audio", fingerprint=f"{doc_id}:{article_id}")
-    asyncio.create_task(asyncio.to_thread(
+    spawn(asyncio.to_thread(
         _audio_generate_one_sync, doc_id, job_id, article_id, voice, interview_voice))
     return {"job_id": job_id}
 
@@ -3296,8 +3298,42 @@ def _article_download_filename(meta: dict, article: dict) -> str:
     return (name[:180] or article.get("id") or "article") + ".mp3"
 
 
+def _export_mp3(mp3: Path, tmpdir: Path, provenance: str, voice: str) -> Path:
+    """The MP3 to export: a tagged copy when provenance tags are on (query param, else the setting)."""
+    from core import export_provenance as ep
+    from core.constants import __version__
+    on = bool(_load_settings().get("export_provenance_default", True)) if provenance == "" else provenance == "1"
+    if not on:
+        return mp3
+    name = ""
+    if voice == "1":
+        segs = (mag.read_audio_timings(mp3) or {}).get("segments") or []
+        name = next((x.get("voice") for x in segs if isinstance(x, dict) and x.get("voice")), "") or ""
+    try:
+        return ep.apply_tags(mp3, tmpdir / mp3.name, ep.build_tags(__version__, name, voice == "1"))
+    except (RuntimeError, OSError, __import__("subprocess").SubprocessError):
+        logging.getLogger(__name__).warning("provenance tagging failed for %s; shipping the untagged file", mp3.name)
+        return mp3      # degrade gracefully: an untagged export beats a failed download
+
+
+@router.post("/api/export/provenance")
+async def export_provenance_verify(request: Request):
+    """Verify: read the provenance tags back from an uploaded audio file (raw body, 100 MB cap)."""
+    import tempfile
+    from core import export_provenance as ep
+    body = await request.body()
+    if not body or len(body) > 100 * 1024 * 1024:
+        raise HTTPException(400, "Send an audio file of up to 100 MB as the request body")
+    with tempfile.TemporaryDirectory(prefix="prov-") as t:
+        f = Path(t) / "in.bin"
+        f.write_bytes(body)
+        tags = await asyncio.to_thread(ep.read_tags, f)
+    return {"tags": tags, "synthetic": tags.get("synthetic_speech") == "true",
+            "watermark_available": ep.watermark_available()}
+
+
 @router.get("/api/magazine/{doc_id}/articles/{article_id}/audio")
-async def magazine_article_audio_file(doc_id: str, article_id: str):
+async def magazine_article_audio_file(doc_id: str, article_id: str, provenance: str = "", voice: str = ""):
     d, meta = _require_magazine(doc_id)
     article_id = _article_id(article_id)
     path = d / "audio" / f"{article_id}.mp3"
@@ -3305,7 +3341,16 @@ async def magazine_article_audio_file(doc_id: str, article_id: str):
         raise HTTPException(404, "No audio generated yet")
     articles = mag.load_articles(d)
     article = next((a for a in articles if a.get("id") == article_id), {"id": article_id})
-    return FileResponse(path, media_type="audio/mpeg", filename=_article_download_filename(meta, article))
+    from starlette.background import BackgroundTask
+    import tempfile
+    tmp = Path(tempfile.mkdtemp(prefix="mag-prov-"))
+    try:
+        out = await asyncio.to_thread(_export_mp3, path, tmp, provenance, voice)
+    except BaseException:
+        shutil.rmtree(tmp, ignore_errors=True)
+        raise
+    return FileResponse(out, media_type="audio/mpeg", filename=_article_download_filename(meta, article),
+                        background=BackgroundTask(shutil.rmtree, tmp, ignore_errors=True))
 
 
 def _audio_generate_batch_sync(doc_id: str, job_id: str, article_ids: list[str], voice: str,
@@ -3353,13 +3398,13 @@ async def magazine_generate_batch_audio(doc_id: str, request: Request):
         raise HTTPException(400, "No approved articles to render")
     job_id = uuid.uuid4().hex
     background_job_create(job_id, "magazine-audio-batch", fingerprint=doc_id)
-    asyncio.create_task(asyncio.to_thread(
+    spawn(asyncio.to_thread(
         _audio_generate_batch_sync, doc_id, job_id, article_ids, voice, interview_voice))
     return {"job_id": job_id, "count": len(article_ids)}
 
 
 @router.get("/api/magazine/{doc_id}/epub")
-async def magazine_epub(doc_id: str, article: str = ""):
+async def magazine_epub(doc_id: str, article: str = "", provenance: str = "", voice: str = ""):
     """The issue (or one article) as an EPUB 3 with Media Overlays: text that highlights as the MP3 plays.
 
     Only approved articles that already have audio are included, in listing order. Sentence timings are
@@ -3378,6 +3423,8 @@ async def magazine_epub(doc_id: str, article: str = ""):
         if not articles:
             raise HTTPException(404, "Article not found")
     parts = []
+    import tempfile
+    tagdir = Path(tempfile.mkdtemp(prefix="mag-prov-"))
     for a in articles:
         mp3 = d / "audio" / f"{a['id']}.mp3"
         if a.get("status") != "approved" or not mp3.is_file():
@@ -3391,12 +3438,13 @@ async def magazine_epub(doc_id: str, article: str = ""):
                 continue            # an unreadable MP3 cannot be given timings at all
             duration_ms = int(length * 1000)
         parts.append({"title": a.get("title") or "", "author": a.get("author") or "", "blocks": blocks,
-                      "mp3": mp3, "duration_ms": duration_ms, "timings": timings,
+                      "mp3": await asyncio.to_thread(_export_mp3, mp3, tagdir, provenance, voice),
+                      "duration_ms": duration_ms, "timings": timings,
                       "spoken_chars": mag.spoken_chars_for(blocks, timings)})
     if not parts:
+        shutil.rmtree(tagdir, ignore_errors=True)
         raise HTTPException(404, "No approved article has audio yet")
     language = mag.detect_article_language(b["text"] for p in parts for b in p["blocks"])
-    import tempfile
     tmp = tempfile.NamedTemporaryFile(prefix="mag-epub-", suffix=".epub", delete=False)
     tmp.close()
     out = Path(tmp.name)
@@ -3406,17 +3454,19 @@ async def magazine_epub(doc_id: str, article: str = ""):
                                 articles=parts, identifier=f"urn:uuid:{doc_id[:8]}-{doc_id[8:12]}-{doc_id[12:16]}-{doc_id[16:20]}-{doc_id[20:32]}")
     except ValueError as exc:
         out.unlink(missing_ok=True)
+        shutil.rmtree(tagdir, ignore_errors=True)
         raise HTTPException(404, str(exc))
     except BaseException:
         out.unlink(missing_ok=True)
+        shutil.rmtree(tagdir, ignore_errors=True)
         raise
     filename = re.sub(r"[^A-Za-z0-9._ -]+", "_", str(meta.get("title") or "magazine")).strip(" ._")[:80] or "magazine"
     return FileResponse(out, media_type="application/epub+zip", filename=f"{filename}.epub",
-                        background=BackgroundTask(lambda: out.unlink(missing_ok=True)))
+                        background=BackgroundTask(lambda: (out.unlink(missing_ok=True), shutil.rmtree(tagdir, ignore_errors=True))))
 
 
 @router.get("/api/magazine/{doc_id}/audio.zip")
-async def magazine_audio_zip(doc_id: str):
+async def magazine_audio_zip(doc_id: str, provenance: str = "", voice: str = ""):
     d, meta = _require_magazine(doc_id)
     audio_dir = d / "audio"
     if not audio_dir.is_dir():
@@ -3431,7 +3481,8 @@ async def magazine_audio_zip(doc_id: str):
     if not ordered:
         raise HTTPException(404, "No audio generated yet")
     buf = io.BytesIO()
-    with zipfile.ZipFile(buf, "w", zipfile.ZIP_STORED) as zf:
+    import tempfile
+    with tempfile.TemporaryDirectory(prefix="mag-prov-") as tagdir, zipfile.ZipFile(buf, "w", zipfile.ZIP_STORED) as zf:
         for i, a in enumerate(ordered, start=1):
             page = (a.get("pages") or [0])[0]
             name = _article_download_filename(meta, a)
@@ -3439,7 +3490,8 @@ async def magazine_audio_zip(doc_id: str):
             # by filename gives the reading order even where two articles
             # start on the same page.
             arcname = f"{i:03d} - " + name
-            zf.write(audio_dir / f"{a['id']}.mp3", arcname=arcname)
+            zf.write(await asyncio.to_thread(_export_mp3, audio_dir / f"{a['id']}.mp3", Path(tagdir), provenance, voice),
+                     arcname=arcname)
     buf.seek(0)
     safe_title = re.sub(r"[^\w \-]+", "", meta.get("title") or "magazine").strip() or "magazine"
     return Response(content=buf.getvalue(), media_type="application/zip",

routes/magazine_sources.py

@@ -15,6 +15,7 @@ import uuid
 from fastapi import APIRouter, HTTPException, Request
 
 from core import magazine_sources as ms
+from core.tasks import spawn
 from core.config import _load_settings, _save_settings
 from core.constants import CONFIG_DIR
 from core.database import background_job_create, background_job_update
@@ -162,5 +163,5 @@ async def magazine_sources_import(request: Request):
         async with _import_lock:
             await asyncio.to_thread(_download_sync, doc_id, job_id, key, item_id)
 
-    asyncio.create_task(run())
+    spawn(run())
     return {"id": doc_id, "job_id": job_id}

routes/sources.py

@@ -6,6 +6,7 @@ import glob
 import json
 import os
 import re
+import threading
 import uuid
 from datetime import datetime, timezone
 from html import unescape
@@ -16,9 +17,10 @@ import requests
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import StreamingResponse
 
+from core.tasks import spawn
 from core.config import _load_settings
 from core.constants import _VOICES_DIR_DEFAULT, _MAX_UPLOAD_BYTES, _ALLOW_PRIVATE_DOWNLOADS, CONFIG_DIR, _BENCHMARK_SENTENCES
-from core.registry import _registry_put, TEMP_DIR
+from core.registry import _registry_put, _registry_get, TEMP_DIR
 from core.validation import _validate_http_url
 from core.audio import _to_wav_24k, _duration
 from core.voice import (
@@ -60,6 +62,11 @@ async def _prepare_imported_voice(audio: Path, settings: dict) -> None:
     local service is captured in metadata rather than making the import fail.
     """
     meta = _load_meta(audio)
+    try:
+        from core.audio import audio_problems
+        meta["audio_problems"] = await asyncio.to_thread(audio_problems, audio)
+    except Exception:
+        pass  # analysis is advisory; never block the import
     meta["import_preparation"] = "transcribing"
     meta.pop("import_preparation_error", None)
     _save_meta(audio, meta)
@@ -147,6 +154,8 @@ _PROXY_AUDIO_DOMAINS: set[str] = {
     "sample-files.com",
     "platform.r2.fish.audio",
     "fish.audio",
+    "archive.org",
+    "upload.wikimedia.org",
 }
 _GDRIVE_MIME_EXT = {
     "audio/mpeg": "mp3", "audio/mp3": "mp3",
@@ -527,6 +536,24 @@ async def voice_sources_custom(request: Request):
     return _voice_sources_payload(data.get("urls") if isinstance(data, dict) else None)
 
 
+@router.get("/api/voice-sources/librivox/book/{book_id}")
+async def librivox_book_audio(book_id: str):
+    from core import open_voice_sources as ovs
+    try:
+        return await asyncio.to_thread(ovs.librivox_first_section, book_id)
+    except ovs.SourceError as e:
+        raise HTTPException(e.status, str(e))
+
+
+@router.get("/api/voice-sources/{source}")
+async def open_voice_source_search(source: str, q: str = "", lang: str = ""):
+    from core import open_voice_sources as ovs
+    try:
+        return {"source": source, "items": await asyncio.to_thread(ovs.search, source, q, lang)}
+    except ovs.SourceError as e:
+        raise HTTPException(e.status, str(e))
+
+
 @router.post("/api/import-source-audio")
 async def import_source_audio(request: Request):
     data = await request.json()
@@ -588,6 +615,16 @@ async def proxy_audio(url: str):
 async def quick_import_voice(request: Request):
     data = await request.json()
     audio_url = _source_import_url(str(data.get("audio_url") or ""))
+    source_kind = str(data.get("source_kind") or "")
+    if source_kind:
+        from core import open_voice_sources as ovs
+        if not ovs.host_ok(audio_url, ovs.AUDIO_HOSTS):
+            raise HTTPException(400, "audio_url host is not allowed for this source")
+        try:
+            kind_prov = ovs.import_provenance_for(
+                source_kind, str(data.get("page_url") or ""), str(data.get("licence") or ""), str(data.get("attribution") or ""))
+        except ValueError as e:
+            raise HTTPException(400, str(e))
     voice_id = re.sub(r"[^A-Za-z0-9_\-\.]", "_", str(data.get("voice_id") or "").strip())[:80]
     if not voice_id:
         raise HTTPException(400, "voice_id is required")
@@ -613,6 +650,17 @@ async def quick_import_voice(request: Request):
                         raise HTTPException(413, "Downloaded audio is too large")
                     f.write(chunk)
         wav = _to_wav_24k(dest)
+        if source_kind:  # sample clip: trim to [start, start+length] (length 3..120 s)
+            from pydub import AudioSegment
+            try:
+                t0 = max(0.0, float(data.get("start") or 0))
+                ln = min(120.0, max(3.0, float(data.get("length") or 30)))
+            except (TypeError, ValueError):
+                raise HTTPException(400, "start/length must be numbers")
+            seg = AudioSegment.from_wav(str(wav))[int(t0 * 1000):int((t0 + ln) * 1000)]
+            if len(seg) < 1000:
+                raise HTTPException(400, "Trim range is outside the audio")
+            seg.export(str(wav), format="wav")
     except HTTPException:
         raise
     except Exception as e:
@@ -646,13 +694,19 @@ async def quick_import_voice(request: Request):
     for field in ("name", "tag", "group", "origin", "note", "source"):
         if data.get(field) is not None:
             meta[field] = str(data.get(field) or "").strip()[:500]
+    from core.provenance import import_provenance
+    if source_kind:
+        meta["provenance"] = kind_prov
+        meta["attribution"] = str(data.get("attribution") or "")[:500]
+    else:
+        meta["provenance"] = import_provenance(str(data.get("page_url") or audio_url))  # basis stays "unknown"
     if auto_prepare and not transcript:
         meta["reference_transcript_status"] = "pending"
         meta["import_preparation"] = "queued"
     _save_meta(wav_dest, meta)
     await asyncio.to_thread(upsert_voice_in_index, settings, wav_dest)
     if auto_prepare and not transcript:
-        asyncio.create_task(_prepare_imported_voice(wav_dest, settings))
+        spawn(_prepare_imported_voice(wav_dest, settings))
     return {
         "voice_id": final_id,
         "loudness": loudness,
@@ -715,6 +769,34 @@ async def download_yt(url: str):
                              headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
 
 
+@router.post("/api/isolate-vocals")
+async def isolate_vocals_route(request: Request):
+    """Remove background music from a registered temp audio id; the original id stays valid."""
+    from core import vocal_isolation as vi
+    data = await request.json()
+    fid = data.get("id") if isinstance(data, dict) else None
+    if not isinstance(fid, str) or not fid:
+        raise HTTPException(400, "id required")
+    src = _registry_get(fid)
+    if src is None or not src.exists():
+        raise HTTPException(404, "Source file not found")
+    cancel = threading.Event()
+    task = asyncio.create_task(asyncio.to_thread(vi.isolate_vocals, src, cancel))
+    try:
+        while not task.done():
+            await asyncio.wait({task}, timeout=1.0)
+            if not task.done() and await request.is_disconnected():
+                cancel.set()
+        wav = task.result()
+    except vi.VocalIsolationError as e:
+        raise HTTPException(e.status, str(e))
+    except Exception:
+        raise HTTPException(500, "Vocal isolation failed")
+    nid = uuid.uuid4().hex
+    _registry_put(nid, wav)
+    return {"id": nid, "duration": _duration(wav)}
+
+
 @router.get("/api/elevenlabs/voices")
 async def elevenlabs_shared_voices(request: Request):
     settings = _load_settings()
@@ -793,7 +875,7 @@ async def fishaudio_voices(request: Request):
         params["tag"] = tags
     import hashlib
     cache_dir = CONFIG_DIR / "fishaudio_cache"
-    cache_key = hashlib.md5(json.dumps(params, sort_keys=True, default=str).encode()).hexdigest()
+    cache_key = hashlib.md5(json.dumps(params, sort_keys=True, default=str).encode(), usedforsecurity=False).hexdigest()
     cache_file = cache_dir / f"{cache_key}.json"
     try:
         r = await asyncio.to_thread(
@@ -1094,7 +1176,7 @@ async def movie_poster(title: str = ""):
     clean = re.sub(r"\s*\(.*?\)\s*$", "", title).strip()
     result = {"poster": "", "year": "", "title": title}
     try:
-        url = f"http://www.omdbapi.com/?t={_q(clean)}&type=movie&apikey=trilogy"
+        url = f"https://www.omdbapi.com/?t={_q(clean)}&type=movie&apikey=trilogy"
         r = await asyncio.to_thread(lambda: requests.get(url, timeout=8))
         if r.ok:
             d = r.json()

routes/stt.py

@@ -12,6 +12,7 @@ from pathlib import Path
 import requests
 from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
 
+from core.tasks import spawn
 from core.config import _load_settings
 from core.constants import (
     _WHISPER_DEFAULT, _FASTER_WHISPER_DEFAULT, _WHISPER_CPP_DEFAULT,
@@ -579,7 +580,7 @@ async def transcribe(request: Request):
         }
         background_job_create(job_id, "transcription", created=now)
         _stt_jobs_trim()
-        asyncio.create_task(_run_stt_job(job_id, src, settings, backend))
+        spawn(_run_stt_job(job_id, src, settings, backend))
         return {"job_id": job_id}
     try:
         text, used_backend = await _bounded_stt_call(_transcribe_audio, src, settings, backend)

routes/tts.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 import io
 import json
 import logging
@@ -18,6 +19,7 @@ import requests
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
 
+from core.tasks import spawn
 from core.config import _load_settings, _clean_preview_backend, _preview_backend_base_url
 from core.constants import (
     _VOICES_DIR_DEFAULT, _TTS_CONTAINER, _TTS_CONTAINERS_RAW,
@@ -38,6 +40,7 @@ from core.voice import (
 )
 from core.voice_index import indexed_voices, refresh_voice_index_background
 from core.validation import _validate_http_url
+from core import ssml_lite
 from core.provider_health import probe_provider
 from core.registry import _registry_put, TEMP_DIR
 from core.tts_helpers import (
@@ -85,6 +88,17 @@ async def _bounded_tts_call(fn, *args):
         _TTS_GENERATION_SLOTS.release()
 
 
+async def _generate_with_tags(text: str, language: str, settings: dict, gen_one):
+    """Run `gen_one(text)` (async, one synthesis) through inline-tag rendering when the flag is on."""
+    if not (settings.get("inline_tags_enabled") and ssml_lite.has_tags(text)):
+        return await gen_one(text)
+    loop = asyncio.get_running_loop()
+    return await asyncio.to_thread(
+        ssml_lite.render_with_tags, text,
+        lambda t: asyncio.run_coroutine_threadsafe(gen_one(t), loop).result(), language, True,
+    )
+
+
 def _voice_design_job_set(job_id: str, **fields) -> None:
     job = _VOICE_DESIGN_JOBS.get(job_id)
     if job is not None:
@@ -827,11 +841,15 @@ async def tts_preview(request: Request):
 
     try:
         if backend == "voice_clone" and data.get("seed_finder") and "seed" in _overrides:
+            if settings.get("inline_tags_enabled"):
+                text = ssml_lite.plain_text(text, str(data.get("language") or "auto"))
             audio, media_type = await _bounded_tts_call(
                 _seed_finder_request_audio, text, voice, settings, int(_overrides["seed"])
             )
         else:
-            audio, media_type = await _bounded_tts_call(_preview_request_audio, text, voice, settings, instruct, backend)
+            async def _one(t):
+                return await _bounded_tts_call(_preview_request_audio, t, voice, settings, instruct, backend)
+            audio, media_type = await _generate_with_tags(text, str(data.get("language") or "auto"), settings, _one)
     except HTTPException:
         raise
     except Exception as e:
@@ -941,7 +959,7 @@ async def voice_design(request: Request):
         }
         background_job_create(job_id, "voice_design", created=_VOICE_DESIGN_JOBS[job_id]["created"])
         _voice_design_job_trim()
-        asyncio.create_task(_run_voice_design_job(job_id, job_data, idempotency_key, request_fingerprint))
+        spawn(_run_voice_design_job(job_id, job_data, idempotency_key, request_fingerprint))
         return {"job_id": job_id, "stage": "queued"}
     return await _voice_design_execute(data, idempotency_key, request_fingerprint)
 
@@ -1013,7 +1031,7 @@ async def tts_route_test(request: Request):
         "detected_language": str(route.get("detected_language", _detect_text_language(text))) if route else _detect_text_language(text),
         "matched": bool(route),
         "route": route,
-        "voice_health": _voice_health(routed_audio) if routed_audio else None,
+        "voice_health": _voice_health(routed_audio, analyze=True) if routed_audio else None,
         "sounds": sound_status,
     }
     _routing_log_add(
@@ -1134,6 +1152,8 @@ async def openai_speech_proxy(request: Request):
     route_has_speed = abs(_route_speed(route) - 1.0) > 0.01
 
     if backend == "streaming" and not virtual and response_format == "wav" and not route_has_sounds and not route_has_speed:
+        if settings.get("inline_tags_enabled"):
+            text = ssml_lite.plain_text(text, explicit_lang or "auto") or text   # streaming: tags stripped, never spoken
         try:
             resp = await _bounded_tts_call(_open_tts_stream_response, text, voice, settings, style_instruction)
         except HTTPException:
@@ -1168,7 +1188,7 @@ async def openai_speech_proxy(request: Request):
             },
         )
 
-    try:
+    async def _gen_one(text):
         if virtual:
             _name, preset = virtual
             instruct = str(preset.get("description", "")).strip()
@@ -1211,6 +1231,11 @@ async def openai_speech_proxy(request: Request):
             audio, media_type = await _bounded_tts_call(
                 _tts_request_audio, text, voice, settings, style_instruction,
             )
+        return audio, media_type
+
+    try:
+        audio, media_type = await _generate_with_tags(
+            text, str(data.get("language") or data.get("lang") or "auto"), settings, _gen_one)
     except HTTPException:
         raise
     except Exception as e:
@@ -1314,6 +1339,92 @@ async def tts_voice_seed(request: Request):
         raise HTTPException(e.response.status_code, detail or str(e))
 
 
+_AUTOPICK_CANDIDATE_TIMEOUT_S = 240
+
+
+def _autopick_score_audio(audio: bytes, text: str, settings: dict, stt_ok: bool) -> dict:
+    """Blocking: write the sample to a temp WAV, run ASR (if available) + loudness + problems."""
+    from core.audio import _loudness_info, audio_problems
+    from core import seed_score as sc
+    tmp = TEMP_DIR / f"autopick_{uuid.uuid4().hex}.wav"
+    tmp.write_bytes(audio)
+    try:
+        accuracy, stt_error = None, None
+        if stt_ok:
+            from routes import stt as _stt  # lazy: avoids import-order coupling
+            try:
+                transcript, _ = _stt._transcribe_audio(tmp, settings)
+                accuracy = _stt._word_accuracy(text, transcript)
+            except Exception as exc:
+                stt_error = str(exc)[:200]
+        loud = _loudness_info(tmp)
+        problems = audio_problems(tmp)
+    finally:
+        tmp.unlink(missing_ok=True)
+    loud_s, prob_s = sc.loudness_score(loud), sc.problems_score(problems)
+    return {
+        "score": sc.combine(accuracy, loud_s, prob_s),
+        "accuracy": None if accuracy is None else round(accuracy, 1),
+        "loudness_score": round(loud_s, 1), "problems_score": round(prob_s, 1),
+        "loudness": loud, "problems": problems, "stt_error": stt_error,
+    }
+
+
+@router.post("/api/seed-autopick")
+async def seed_autopick(request: Request):
+    """Generate N seed candidates sequentially, score them, return all plus the winner.
+
+    Body: {"voice", "text", "seeds": [..] | "count": 1-16 (default 8)}. Never saves a seed;
+    the UI confirms via /api/tts-voice-seed. Stops early if the client disconnects.
+    """
+    from core import seed_score as sc
+    data = await request.json()
+    if not isinstance(data, dict):
+        raise HTTPException(400, "JSON object expected")
+    voice, text = data.get("voice"), data.get("text")
+    if not isinstance(voice, str) or not voice.strip() or len(voice) > 200:
+        raise HTTPException(400, "voice required")
+    if not isinstance(text, str) or not text.strip() or len(text) > 1500:
+        raise HTTPException(400, "text required (max 1500 characters)")
+    try:
+        seeds = sc.seed_list(data.get("seeds"), data.get("count"))
+    except ValueError as exc:
+        raise HTTPException(400, str(exc))
+    settings = _load_settings()
+    stt_ok, stt_note, cancelled = True, "", False
+    candidates: list[dict] = []
+    for seed in seeds:
+        if await request.is_disconnected():
+            cancelled = True
+            break
+        cand: dict = {"seed": seed}
+        try:
+            audio, media_type = await asyncio.wait_for(
+                asyncio.to_thread(_seed_finder_request_audio, text.strip(), voice, settings, seed),
+                _AUTOPICK_CANDIDATE_TIMEOUT_S)
+            cand.update(await asyncio.to_thread(_autopick_score_audio, audio, text.strip(), settings, stt_ok))
+            if stt_ok and cand["accuracy"] is None:
+                stt_ok, stt_note = False, cand["stt_error"] or "speech-to-text unavailable"
+            cand["media_type"] = media_type
+            cand["audio_b64"] = base64.b64encode(audio).decode("ascii")
+        except asyncio.TimeoutError:
+            # The worker thread still holds the voices.json lock and restores it when done;
+            # starting another candidate now would only queue behind it.
+            candidates.append({**cand, "error": "timeout"})
+            break
+        except Exception as exc:
+            logger.warning("Seed auto-pick seed %s failed: %s", seed, exc)
+            cand["error"] = str(exc)[:200] or "generation failed"
+        candidates.append(cand)
+    return {
+        "voice": voice, "winner": sc.pick_winner(candidates), "candidates": candidates,
+        "requested": len(seeds), "cancelled": cancelled,
+        "stt": {"available": stt_ok, "note": stt_note},
+        "degraded": not stt_ok,
+        "weights": {"accuracy": sc.W_ACCURACY, "loudness": sc.W_LOUDNESS, "problems": sc.W_PROBLEMS},
+    }
+
+
 @router.get("/api/seed-samples/{voice_name}")
 async def list_seed_samples(voice_name: str):
     """List pre-generated seed sample numbers for a voice (batch script output)."""

scratch/test_google_imagen.py

@@ -1,20 +0,0 @@
-import requests
-import json
-import base64
-
-API_KEY = "AIzaSyD6aidNxIhr2SKgauZ9zea_FynuCo2DyDo"
-url = f"https://generativelanguage.googleapis.com/v1beta/interactions"
-
-payload = {
-    "model": "gemini-3.1-flash-image",
-    "input": [{"type": "user_input", "content": [{"type": "text", "text": "A beautiful square headshot portrait of Karyla. Style: painterly game concept art."}]}],
-    "response_modalities": ["image"]
-}
-headers = {'x-goog-api-key': API_KEY, 'Content-Type': 'application/json'}
-
-response = requests.post(url, headers=headers, json=payload)
-print(response.status_code)
-if response.ok:
-    print("Success! Got image")
-else:
-    print(response.text[:500])

scratch/test_openai.py

@@ -1,24 +0,0 @@
-import requests
-import json
-
-API_KEY = "sk-proj-jVzNl_bM-oRpR_W1F-W5bLwXQ4e38nS3pQf4eY6k2M6tX-TZA9YmH4lF" # From settings.json wait, I don't know the full key. I'll read it from settings.json
-with open("config/settings.json") as f:
-    settings = json.load(f)
-    api_key = settings.get("engine_api_keys", {}).get("openai_image")
-
-url = "https://api.openai.com/v1/images/generations"
-
-payload = {
-    "model": "dall-e-3",
-    "prompt": "A beautiful square headshot portrait of Karyla. Style: painterly game concept art.",
-    "n": 1,
-    "size": "1024x1024"
-}
-headers = {'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}
-
-response = requests.post(url, headers=headers, json=payload)
-print(response.status_code)
-if response.ok:
-    print("Success! OpenAI generated image.")
-else:
-    print(response.text[:500])

scripts/qa.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Central QA command: `npm run qa [-- --fast] [--sonar] [--only <stage>] [--grep <pat>] [--list]`.
+// Dependency-free; uses only tools that are already installed and reports the rest as SKIPPED.
+// Secrets: SONAR_TOKEN / SONAR_HOST_URL come from the environment only and are never printed or put in argv.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, mkdtempSync, mkdirSync, rmSync, existsSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const flag = n => args.includes(n);
+const opt = n => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+const fast = flag('--fast'), withSonar = flag('--sonar'), only = opt('--only'), grep = opt('--grep');
+
+const sh = (cmd, a, o = {}) => spawnSync(cmd, a, { cwd: root, encoding: 'utf8', maxBuffer: 64 << 20, ...o });
+const have = (bin) => sh('sh', ['-c', `command -v ${bin}`]).status === 0;
+// Fresh isolated HOME/CONFIG_DIR/TMPDIR per call (never touches live data or shared /tmp names); caller must cleanup().
+const isolatedPyEnv = () => {
+  const dir = mkdtempSync(join(tmpdir(), 'qa-'));
+  const tmp = join(dir, 'tmp'); mkdirSync(tmp);
+  return { env: { ...process.env, HOME: dir, CONFIG_DIR: dir, TMPDIR: tmp }, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+};
+const pyMod = (m) => sh('python3', ['-m', m, '--version']).status === 0;
+const tail = (r, n = 15) => ((r.stdout || '') + (r.stderr || '')).trim().split('\n').slice(-n).join('\n');
+// A stage returns {status:'PASS'|'FAIL'|'SKIPPED', note}
+const pass = (note = '') => ({ status: 'PASS', note });
+const skip = (note) => ({ status: 'SKIPPED', note });
+const result = (r, note = '') => {
+  if (r.status === 0) return pass(note);
+  console.log(tail(r, 40));
+  return { status: 'FAIL', note: note || `exit ${r.status}` };
+};
+const inherit = (cmd, a, o = {}) => sh(cmd, a, { stdio: 'inherit', encoding: undefined, ...o });
+
+const tracked = (...pats) => sh('git', ['ls-files', ...pats]).stdout.split('\n').filter(Boolean);
+
+const stages = [
+  ['format', 'formatter check', () => skip('no formatter configured (no prettier/black config)')],
+  ['lint', 'JS syntax + frontend gate + python compile/ruff', () => {
+    for (const f of tracked('static/js/*.js', 'scripts/*.mjs', 'tests/*.mjs')) {
+      const r = sh(process.execPath, ['--check', f]);
+      if (r.status) return result(r, `syntax: ${f}`);
+    }
+    let r = sh('npm', ['run', '--silent', 'check:frontend']);
+    if (r.status) return result(r, 'check:frontend');
+    r = sh('python3', ['-m', 'compileall', '-q', 'core', 'routes', 'scripts', 'server.py', 'ttsvc_cli.py']);
+    if (r.status) return result(r, 'compileall');
+    if (pyMod('ruff')) { r = sh('python3', ['-m', 'ruff', 'check', 'core', 'routes', 'scripts', 'server.py']); if (r.status) return result(r, 'ruff'); return pass('with ruff'); }
+    return pass('ruff not installed, skipped');
+  }],
+  ['types', 'type check', () => skip('no type checker configured')],
+  ['pyunit', 'python unittest', () => {
+    const { env, cleanup } = isolatedPyEnv();
+    try { return result(inherit('python3', ['-m', 'unittest', 'discover', '-s', 'tests', '-p', 'test_*.py'], { env }), 'see unittest output above'); }
+    finally { cleanup(); }
+  }],
+  ['nodeunit', 'node unit tests', () => result(inherit('npm', ['run', '--silent', 'test:unit']))],
+  ['e2e', 'Playwright (desktop + iphone)', () => {
+    if (fast) return skip('--fast');
+    const a = ['playwright', 'test', ...(grep ? ['--grep', grep] : [])];
+    return result(inherit('npx', a));
+  }],
+  ['a11y', 'accessibility (axe-core)', () => {
+    const axe = existsSync(join(root, 'node_modules/@axe-core/playwright')) || existsSync(join(root, 'node_modules/axe-core'));
+    return axe ? skip('axe-core installed but no a11y specs yet') : skip('tool missing: axe-core; recommend `npm i -D @axe-core/playwright` and add tests/a11y.spec.js');
+  }],
+  ['security', 'npm audit, pip-audit, secret scan', () => {
+    const notes = []; let bad = false;
+    const a = sh('npm', ['audit', '--audit-level=high'], { timeout: 60000 });
+    const out = (a.stdout || '') + (a.stderr || '');
+    if (a.status === 0) notes.push('npm audit ok');
+    else if (/ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|network|audit endpoint/i.test(out) || a.error) notes.push('npm audit SKIPPED (offline)');
+    else { bad = true; console.log(tail(a, 20)); notes.push('npm audit FOUND high+'); }
+    if (existsSync(join(root, 'requirements.txt')) && pyMod('pip_audit')) {
+      const p = sh('python3', ['-m', 'pip_audit', '-r', 'requirements.txt', '--progress-spinner', 'off'], { timeout: 120000 });
+      const po = (p.stdout || '') + (p.stderr || '');
+      if (p.status === 0) notes.push('pip-audit ok');
+      else if (/connection|resolve|network|timed out|ConnectionError/i.test(po) || p.error) notes.push('pip-audit SKIPPED (offline)');
+      else { bad = true; console.log(tail(p, 20)); notes.push('pip-audit FOUND vulns'); }
+    } else notes.push('pip-audit SKIPPED (tool/requirements missing)');
+    let hits;
+    if (have('gitleaks')) {
+      const g = sh('gitleaks', ['detect', '--no-banner', '--redact', '--source', '.']);
+      hits = g.status === 0 ? 0 : -1; notes.push(g.status === 0 ? 'gitleaks ok' : 'gitleaks FOUND');
+      if (g.status) bad = true;
+    } else { hits = secretScan(); notes.push(hits ? `secret-scan ${hits} hit(s)` : 'secret-scan ok (built-in regex)'); if (hits) bad = true; }
+    return { status: bad ? 'FAIL' : 'PASS', note: notes.join('; ') };
+  }],
+  ['build', 'minify + bundle freshness', () => {
+    const f = join(root, 'static/dist/main.min.js');
+    const h = () => existsSync(f) ? createHash('sha256').update(readFileSync(f)).digest('hex') : '';
+    const before = h();
+    const r = sh('npm', ['run', '--silent', 'minify']);
+    if (r.status) return result(r, 'minify');
+    if (!existsSync(f) || statSync(f).size === 0) return { status: 'FAIL', note: 'main.min.js missing/empty' };
+    return h() === before ? pass('bundle fresh') : { status: 'FAIL', note: 'bundle was stale; regenerated, review and commit static/dist/main.min.js' };
+  }],
+  ['perf', 'performance budget', () => skip('DOM budget lives in tests/constrained.spec.js (runs in e2e stage)')],
+  ['sonar', 'SonarQube scan (opt-in --sonar)', () => {
+    if (!withSonar) return skip('not requested (--sonar)');
+    const { SONAR_TOKEN: tok, SONAR_HOST_URL: host } = process.env;
+    if (!tok || !host) return skip('set SONAR_HOST_URL and SONAR_TOKEN in the shell or CI secrets');
+    if (!have('sonar-scanner')) return skip('tool missing: sonar-scanner');
+    // Python coverage for new-code gate (optional: only if `coverage` is installed). JS coverage is not collected (see architecture/qa.md).
+    if (sh('python3', ['-c', 'import coverage']).status === 0) {
+      const { env, cleanup } = isolatedPyEnv();
+      try {
+        const c = inherit('python3', ['-m', 'coverage', 'run', '-m', 'unittest', 'discover', '-s', 'tests', '-p', 'test_*.py'], { env });
+        if (c.status === 0) sh('python3', ['-m', 'coverage', 'xml', '-o', 'coverage.xml']);
+      } finally { cleanup(); }
+    } else console.log('coverage: SKIPPED (module missing; `pip install coverage` to report Python coverage to Sonar)');
+    const r = sh('sonar-scanner', ['-Dsonar.qualitygate.wait=true', '-Dsonar.qualitygate.timeout=300'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const log = ((r.stdout || '') + (r.stderr || '')).split(tok).join('***');
+    console.log(log.split('\n').slice(-12).join('\n'));
+    return r.status === 0 ? pass('quality gate passed') : { status: 'FAIL', note: 'scan or quality gate failed' };
+  }],
+];
+
+const PATTERNS = [
+  ['private-key', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ['aws-key', /\bAKIA[0-9A-Z]{16}\b/],
+  ['github-token', /\bgh[pousr]_[A-Za-z0-9]{30,}\b/],
+  ['slack-token', /\bxox[baprs]-[A-Za-z0-9-]{10,}/],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/],
+  ['url-credentials', /\bhttps?:\/\/[^\s/:@'"]+:[^\s/@'"]{3,}@[^\s'"]+/],
+  ['generic-secret', /\b(?:api[_-]?key|secret|token|passw(?:or)?d)\b['"]?\s*[:=]\s*['"][A-Za-z0-9_\-+/=]{20,}['"]/i],
+];
+function secretScan() {
+  let hits = 0;
+  for (const f of tracked()) {
+    if (/^(static\/(dist|vendor)\/|node_modules\/)|\.(png|jpe?g|gif|webp|wav|mp3|ogg|pdf|woff2?|ico|zip|gz|lock)$|package-lock\.json$|\.min\.js$/.test(f)) continue;
+    let text; try { text = readFileSync(join(root, f), 'utf8'); } catch { continue; }
+    if (text.includes('\0')) continue;
+    text.split('\n').forEach((line, i) => {
+      if (line.length > 2000) return;
+      for (const [name, re] of PATTERNS) if (re.test(line)) { console.log(`  ${f}:${i + 1} ${name}`); hits++; break; }   // never print the match
+    });
+  }
+  return hits;
+}
+
+if (flag('--list')) { for (const [id, d] of stages) console.log(id.padEnd(10), d); process.exit(0); }
+if (only && !stages.some(s => s[0] === only)) { console.error(`unknown stage: ${only}`); process.exit(2); }
+
+const base = process.env.BASE_URL || 'http://localhost:7890';
+console.log(`QA  fast=${fast} sonar=${withSonar}`);
+console.log(`NOTE: Playwright baseURL is ${base} (the live container serves static files; tests mock /api routes). --fast skips Playwright.`);
+console.log('NOTE: python tests run with a temporary HOME/CONFIG_DIR.');
+const rows = [];
+for (const [id, desc, fn] of stages) {
+  if (only && only !== id) continue;
+  console.log(`\n=== ${id}: ${desc}`);
+  const t = Date.now(); let r;
+  try { r = fn(); } catch (e) { r = { status: 'FAIL', note: String(e.message || e) }; }
+  rows.push({ id, ...r, secs: ((Date.now() - t) / 1000).toFixed(1) });
+}
+console.log('\n=== QA summary');
+for (const r of rows) console.log(`${r.id.padEnd(10)} ${r.status.padEnd(8)} ${r.secs.padStart(6)}s  ${r.note}`);
+const failed = rows.filter(r => r.status === 'FAIL');
+console.log(failed.length ? `\nQA FAILED: ${failed.map(r => r.id).join(', ')}` : '\nQA OK');
+process.exit(failed.length ? 1 : 0);

scripts/render_archetype_previews.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Pre-render all voice archetype previews into the server-side cache (idempotent; cached ones are skipped).
+
+Usage: python scripts/render_archetype_previews.py [--base http://localhost:7890] [--only ID ...]
+Auth: none needed. The app's API-key gate lets same-origin requests through, so the script sends
+the Origin header of the base URL, like the browser UI. No key is read or printed. Run it on the Spark.
+Each render takes tens of seconds (one at a time); the server enforces timeouts and a blank-audio guard.
+"""
+import argparse
+import json
+import sys
+import urllib.request
+from urllib.parse import urlsplit
+
+
+def call(base, path, method="GET"):
+    req = urllib.request.Request(base + path, method=method, data=b"" if method == "POST" else None,
+                                 headers={"Origin": base})
+    with urllib.request.urlopen(req, timeout=300) as r:
+        return r.read() if method == "POST" else json.load(r)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base", default="http://localhost:7890")
+    ap.add_argument("--only", nargs="*", default=[])
+    a = ap.parse_args()
+    host = urlsplit(a.base).hostname or ""
+    if urlsplit(a.base).scheme != "http" or not (host in ("localhost", "127.0.0.1") or host.startswith(("192.168.", "10."))):
+        sys.exit("refusing non-local base URL")
+    items, off = [], 0
+    while True:
+        d = call(a.base, f"/api/archetypes?limit=100&offset={off}")
+        items += d["items"]; off += 100
+        if off >= d["total"]:
+            break
+    fail = 0
+    for it in items:
+        if a.only and it["id"] not in a.only:
+            continue
+        try:
+            n = len(call(a.base, f"/api/archetypes/{it['id']}/preview", "POST"))
+            print(f"ok   {it['id']} ({n} bytes)")
+        except Exception as e:
+            fail += 1; print(f"FAIL {it['id']}: {e}")
+    sys.exit(1 if fail else 0)
+
+
+if __name__ == "__main__":
+    main()

server.py

@@ -19,7 +19,7 @@ from starlette.datastructures import MutableHeaders
 from core.constants import STATIC_DIR, _BufferHandler, _MAX_JSON_BYTES, _MAX_UPLOAD_BYTES, _MAX_RAW_REQUEST_BYTES, _REQUIRE_EXTERNAL_API_KEY
 from core.config import _load_settings, _ensure_external_api_key
 from core.voice_index import refresh_voice_index_background
-from routes import admin, settings, library, stt, sources, docker, tts, conversation, reader, characters, rehearsals_db, recovery, history, jobs, magazine, magazine_sources
+from routes import admin, settings, library, stt, sources, docker, tts, conversation, reader, characters, rehearsals_db, recovery, history, jobs, magazine, magazine_sources, archetypes
 
 logger = logging.getLogger("uvicorn.error")
 
@@ -348,6 +348,7 @@ app.include_router(history.router)
 app.include_router(jobs.router)
 app.include_router(magazine.router)
 app.include_router(magazine_sources.router)
+app.include_router(archetypes.router)
 
 # ── Static files ──────────────────────────────────────────────────────────────
 

sonar-project.properties

@@ -2,7 +2,7 @@
 # Server: https://sq.martin-bierschenk.de (set as SONAR_HOST_URL in CI, never here)
 # Tokens are supplied only via the SONAR_TOKEN CI secret — never in this file.
 
-sonar.projectKey=tts-voice-creator-clone-and-design-2
+sonar.projectKey=mARTin-B78_tts-voice-creator-clone-and-design-2_2b78a834-b2ae-4292-9363-d41c1254cb7a
 sonar.projectName=TTS Voice Creator (Clone & Design)
 
 # Hand-written source only. Everything excluded below is either generated,
@@ -14,6 +14,8 @@ sonar.tests=tests
 sonar.exclusions=\
   static/dist/**,\
   static/vendor/**,\
+  static/js/tesseract/**,\
+  static/js/pdf/**,\
   node_modules/**,\
   **/__pycache__/**,\
   **/*.min.js,\
@@ -21,6 +23,7 @@ sonar.exclusions=\
   workflows/*.json,\
   config/**,\
   scratch/**,\
+  coverage.xml,\
   venv/**,\
   .venv/**
 
@@ -28,4 +31,8 @@ sonar.exclusions=\
 sonar.cpd.exclusions=static/dist/**,workflows/*.json
 
 sonar.python.version=3.11
+sonar.python.coverage.reportPaths=coverage.xml
 sonar.sourceEncoding=UTF-8
+
+# The JS analyzer runs out of memory at the 4 GB default on this codebase.
+sonar.javascript.node.maxspace=12288

static/css/voice-design.css

@@ -48,3 +48,24 @@
 .preview-match-panel audio { width: 100%; min-width: 0; }
 .preview-match-transcript { background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 10px; color: var(--subtext); font-family: monospace; font-size: 12px; line-height: 1.4; max-height: 88px; overflow: auto; white-space: pre-wrap; }
 @media (max-width: 900px) { .preview-match-panel { grid-template-columns: 1fr; } }
+
+/* Attribute chips (toggle buttons that edit their own phrase in the prompt) */
+.design-chips { display: flex; flex-direction: column; gap: 8px; margin: 12px 0; }
+.design-chip-group { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+.design-chip-label { flex: 0 0 100%; font-size: 12px; font-weight: 600; color: var(--subtext); text-transform: uppercase; letter-spacing: .05em; }
+.design-chip { min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 999px; border: 1px solid var(--border); background: var(--surface); color: var(--text); font: inherit; font-size: 13px; cursor: pointer; }
+.design-chip[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: #fff; }
+.design-chip:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px; }
+
+/* Voice archetype gallery */
+.arch-bar { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0; }
+.arch-bar input, .arch-bar select { min-height: 44px; flex: 1 1 200px; }
+.arch-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 10px; margin: 10px 0; }
+.arch-card { border: 1px solid var(--border); border-radius: 10px; padding: 12px; background: var(--surface); display: flex; flex-direction: column; gap: 6px; }
+.arch-card h3 { margin: 0; font-size: 15px; }
+.arch-card p { margin: 0; font-size: 12px; color: var(--subtext); }
+.arch-facets { font-size: 12px; color: var(--subtext); }
+.arch-actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: auto; }
+.arch-actions button { min-height: 44px; min-width: 44px; }
+.arch-fav[aria-pressed="true"] { color: var(--accent); }
+@media (prefers-reduced-motion: reduce) { .arch-card, .arch-actions button { transition: none; animation: none; } }

static/index.html

@@ -10,7 +10,7 @@
   <meta name="format-detection" content="telephone=no">
   <meta name="color-scheme" content="light dark">
   <meta name="theme-color" content="#2563EB">
-<meta name="app-version" content="1.59.0">
+<meta name="app-version" content="1.60.0">
   <link rel="manifest" href="/manifest.webmanifest">
   <link rel="icon" href="/static/icon.svg" type="image/svg+xml">
   <link rel="apple-touch-icon" href="/static/icon.svg">
@@ -27,12 +27,12 @@
 
   <!-- ── Core styles (local — no CDN dependency for first paint) ────────── -->
   <link rel="stylesheet" href="/static/vendor/mdi/materialdesignicons.min.css">
-<link rel="stylesheet" href="/static/style.css?v=1.59.0">
-<link rel="stylesheet" href="/static/css/resource-diagnostics.css?v=1.59.0">
-<link rel="stylesheet" href="/static/css/background-jobs.css?v=1.59.0">
-<link rel="stylesheet" href="/static/css/voice-design.css?v=1.59.0">
-<link rel="stylesheet" href="/static/css/rehearser.css?v=1.59.0">
-<link rel="stylesheet" href="/static/css/audiobook.css?v=1.59.0">
+<link rel="stylesheet" href="/static/style.css?v=1.60.0">
+<link rel="stylesheet" href="/static/css/resource-diagnostics.css?v=1.60.0">
+<link rel="stylesheet" href="/static/css/background-jobs.css?v=1.60.0">
+<link rel="stylesheet" href="/static/css/voice-design.css?v=1.60.0">
+<link rel="stylesheet" href="/static/css/rehearser.css?v=1.60.0">
+<link rel="stylesheet" href="/static/css/audiobook.css?v=1.60.0">
 
 
   <!-- ── Flag icons — non-blocking (loaded async, icons appear after JS) ── -->
@@ -403,7 +403,7 @@ window.toggleNavTree = function(treeId, chevronId) {
 </script>
 
 <!-- loader.js: fetches sections → loads JS modules → removes skeleton -->
-<script src="/static/loader.js?v=1.59.0"></script>
+<script src="/static/loader.js?v=1.60.0"></script>
 
 </body>
 </html>

static/js/audiobook-preview-export.js

@@ -56,36 +56,6 @@ async function audiobookOpenCurrentInRehearser() {
 
 function audiobookShowPreview() {
   audiobookOpenCurrentInRehearser();
-  return;
-  const segs = _audiobook.segments || [];
-  const roster = _audiobook.roster || [];
-  document.getElementById('audiobook-preview')?.remove();
-  const ov = document.createElement('div');
-  ov.id = 'audiobook-preview';
-  ov.className = 'audiobook-overlay';
-  // datalist = Narrator + LLM roster + any speakers present in the segments (incl. Unknown)
-  const speakerSet = [...new Set(['Narrator', ...roster, ...segs.filter(s => s.type === 'dialogue' && s.speaker).map(s => s.speaker)])];
-  const charCount = speakerSet.filter(n => !/^Unknown|Unbekannt/i.test(n)).length;
-  const opts = speakerSet.map(n => `<option value="${escHtml(n)}">`).join('');
-  ov.innerHTML = `<div class="audiobook-box audiobook-preview-box">
-    <div class="audiobook-title"><span class="mdi mdi-drama-masks"></span> Review cast &amp; lines
-      <span class="audiobook-count">${segs.length} segments · ${charCount} character${charCount !== 1 ? 's' : ''}</span></div>
-    <div class="audiobook-msg">Fix any wrong speaker or emotion, then open in the Script Rehearser to assign voices.${_audiobook.narratedPassages ? ` <span class="audiobook-narr-note">${_audiobook.narratedPassages} passage${_audiobook.narratedPassages !== 1 ? 's' : ''} had no dialogue (narrator).</span>` : ''}${_audiobook.degraded ? ` <span class="audiobook-narr-note">${_audiobook.degraded} passage${_audiobook.degraded !== 1 ? 's' : ''} used quick detection — set the “Unknown” speakers.</span>` : ''}${_audiobook.recoveredGaps ? ` <span class="audiobook-narr-note">${_audiobook.recoveredGaps} dropped sentence/paragraph gap${_audiobook.recoveredGaps !== 1 ? 's' : ''} recovered as Narrator — review placement.</span>` : ''}</div>
-    <datalist id="audiobook-roster">${opts}</datalist>
-    <div class="audiobook-seglist" id="audiobook-seglist"></div>
-    <div class="audiobook-actions">
-      <button class="btn-secondary btn-sm" id="audiobook-preview-cancel">Cancel</button>
-      <button class="btn-primary btn-sm" id="audiobook-preview-open"><span class="mdi mdi-account-music-outline"></span> Open in Rehearser</button>
-    </div>
-  </div>`;
-  document.body.appendChild(ov);
-  ov.querySelector('#audiobook-seglist').innerHTML = segs.map((s, i) => `<div class="audiobook-seg${s.type === 'dialogue' ? ' is-dialog' : ''}">
-    <input class="audiobook-seg-sp" data-i="${i}" list="audiobook-roster" value="${escHtml(s.speaker || 'Narrator')}" aria-label="Speaker">
-    <input class="audiobook-seg-emo" data-i="${i}" value="${escHtml(s.emotion || '')}" placeholder="emotion" aria-label="Emotion"${s.type === 'dialogue' ? '' : ' disabled'}>
-    <div class="audiobook-seg-text">${_abMarkQuotes(highlightText(_abDisplayText(s)))}</div>
-  </div>`).join('');
-  ov.querySelector('#audiobook-preview-cancel').addEventListener('click', () => ov.remove());
-  ov.querySelector('#audiobook-preview-open').addEventListener('click', () => { audiobookApplyPreviewAndOpen(); ov.remove(); });
 }
 
 function audiobookApplyPreviewAndOpen() {

static/js/fishaudio-browser.js

@@ -245,7 +245,7 @@
 (function () {
   const tabs = document.getElementById('gvo-tabs');
   if (!tabs) return;
-  const map = { direct: 'tab-getvoices', fish: 'fa-browser-card', eleven: 'el-browser-card' };
+  const map = { direct: 'tab-getvoices', fish: 'fa-browser-card', open: 'open-sources-card', eleven: 'el-browser-card' };
   function show(src) {
     if (!map[src]) src = 'direct';
     Object.entries(map).forEach(([k, id]) => {

static/js/i18n.js

@@ -21,6 +21,74 @@ const I18N_LANGS = {
 // English for languages that don't have it yet (see window.t / applyI18n).
 const I18N_DICT = {
   de: {
+    // Voice archetype gallery
+    'Voice gallery': 'Stimmengalerie',
+    '40 ready-made German-first voices. Preview, save or open in the editor below.': '40 fertige Stimmen, Deutsch zuerst. Anhören, speichern oder unten im Editor öffnen.',
+    'Favourites only': 'Nur Favoriten',
+    'Use voice': 'Stimme verwenden',
+    'Favourite': 'Favorit',
+    'Open in Design': 'In Design öffnen',
+    'Loading…': 'Lädt…',
+    'No voices match.': 'Keine passende Stimme.',
+    'Could not load the gallery.': 'Galerie konnte nicht geladen werden.',
+    'Rendering preview…': 'Vorschau wird erzeugt…',
+    'Preview ready': 'Vorschau bereit',
+    'Preview failed': 'Vorschau fehlgeschlagen',
+    'Saving voice…': 'Stimme wird gespeichert…',
+    'Voice saved': 'Stimme gespeichert',
+    'Save failed': 'Speichern fehlgeschlagen',
+    'All categories': 'Alle Kategorien',
+    'Category': 'Kategorie',
+    'Load more': 'Mehr laden',
+    
+    
+    'male': 'männlich',
+    'female': 'weiblich',
+    'neutral': 'neutral',
+    
+    
+    
+    
+    
+    'high': 'hoch',
+    'mid': 'mittel',
+    'low': 'tief',
+    'none': 'ohne',
+    'british': 'britisch',
+    'american': 'amerikanisch',
+    'australian': 'australisch',
+    'irish': 'irisch',
+    'german': 'deutsch',
+    'southern': 'südlich',
+    'German': 'Deutsch',
+    'English': 'Englisch',
+    
+    
+    
+    
+    
+    
+    
+    // Seed Finder auto-pick
+    'Generates up to 8 candidates, scores them and highlights the best. Nothing is saved until you click Use seed.': 'Erzeugt bis zu 8 Kandidaten, bewertet sie und hebt den besten hervor. Gespeichert wird erst nach Klick auf „Seed verwenden“.',
+    'Auto-pick best': 'Besten automatisch wählen',
+    'Enter a test sentence.': 'Testsatz eingeben.',
+    'Scoring': 'Bewerte',
+    'candidates… this can take a few minutes.': 'Kandidaten … das kann einige Minuten dauern.',
+    'words': 'Wörter',
+    'audio problems': 'Audioprobleme',
+    'score': 'Wertung',
+    'level': 'Pegel',
+    'Best': 'Bester',
+    'Best seed': 'Bester Seed',
+    'Listen, then click Use seed to save.': 'Anhören, dann „Seed verwenden“ zum Speichern.',
+    'No candidate could be generated.': 'Es konnte kein Kandidat erzeugt werden.',
+    'Speech-to-text unavailable: scored by level and audio problems only.': 'Sprache-zu-Text nicht verfügbar: Wertung nur nach Pegel und Audioproblemen.',
+    'Auto-pick failed': 'Automatische Wahl fehlgeschlagen',
+    // Inline text tags
+    'Inline text tags': 'Inline-Texttags',
+    'Off by default. When on, tags shape the speech in Try It Out, Read Aloud, the speech API and audiobooks; streaming and magazine audio only remove them.': 'Standardmäßig aus. Wenn aktiv, steuern Tags die Sprache in „Ausprobieren“, „Vorlesen“, der Sprach-API und Hörbüchern; Streaming und Magazin-Audio entfernen sie nur.',
+    'Inline tags (enable in Settings → General):': 'Inline-Tags (aktivieren unter Einstellungen → Allgemein):',
     // Brand / sidebar groups
     'Voice Creator': 'Voice Creator',
     'Clone · Design · Deploy': 'Klonen · Entwerfen · Bereitstellen',
@@ -77,6 +145,8 @@ const I18N_DICT = {
     'Open rehearsal': 'Probe öffnen', 'Fetch voices': 'Stimmen abrufen',
     'Name your voice': 'Benenne deine Stimme', 'Reference transcript': 'Referenz-Transkript',
     'Preview': 'Vorschau', 'Trim your sample': 'Probe zuschneiden', 'Language': 'Sprache',
+    // Voice-design attribute chips
+    'Pitch': 'Tonhöhe', 'Pace': 'Tempo', 'Age': 'Alter', 'Accent / region': 'Akzent / Region', 'Tone / timbre': 'Klang / Timbre', 'Emotion': 'Emotion', 'male voice': 'männliche Stimme', 'female voice': 'weibliche Stimme', 'neutral voice': 'neutrale Stimme', 'child': 'Kind', 'teenager': 'Teenager', 'young adult': 'junger Erwachsener', 'middle-aged': 'mittleren Alters', 'elderly': 'älter', 'high pitch': 'hohe Tonlage', 'mid pitch': 'mittlere Tonlage', 'low pitch': 'tiefe Tonlage', 'fast pace': 'schnell', 'moderate pace': 'mittleres Tempo', 'slow pace': 'langsam', 'British accent': 'britischer Akzent', 'American accent': 'amerikanischer Akzent', 'Australian accent': 'australischer Akzent', 'Irish accent': 'irischer Akzent', 'German accent': 'deutscher Akzent', 'Southern accent': 'Südstaaten-Akzent', 'warm': 'warm', 'husky': 'rauchig', 'crisp': 'klar', 'smooth': 'weich', 'rich': 'voll', 'magnetic': 'magnetisch', 'authoritative': 'autoritär', 'cheerful': 'fröhlich', 'calm': 'ruhig', 'serious': 'ernst', 'gentle': 'sanft', 'enthusiastic': 'begeistert', 'sad': 'traurig',
     'Gender': 'Geschlecht', 'Voice': 'Stimme', 'Speaking style · voice-design prompt': 'Sprechstil · Voice-Design-Prompt',
     // Common placeholders
     'Search voices…': 'Stimmen suchen…', 'Search voices...': 'Stimmen suchen...',

static/js/library-characters.js

@@ -1259,7 +1259,7 @@ function _lcdField(label, value, multiline) {
   if (!v) return '';
   return '<div class="lcd-field">'
     + '<div class="lcd-field-label">' + label + '</div>'
-    + '<div class="lcd-field-value">' + (multiline ? escHtml(v) : escHtml(v)) + '</div>'
+    + '<div class="lcd-field-value">' + escHtml(v) + '</div>'
     + '</div>';
 }
 

static/js/magazine.js

@@ -1543,18 +1543,42 @@ async function magGenerateAllAudio(force = false) {
   if (!$('mag-playlist')?.hidden) renderPlaylistTracks();
 }
 
+// Provenance tags on exported audio: per-export checkboxes, default from the saved setting.
+let _magProvInit = false;
+function magProvQuery() {
+  const on = $('mag-prov-tags')?.checked !== false;
+  return '?provenance=' + (on ? '1' : '0') + ($('mag-prov-voice')?.checked ? '&voice=1' : '');
+}
+function magProvChanged() {
+  magUpdateAudioZipLink();
+  fetch('/api/settings', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ export_provenance_default: $('mag-prov-tags')?.checked !== false }) }).catch(() => {});
+}
+async function magProvInit() {
+  if (_magProvInit) return;
+  _magProvInit = true;
+  try {
+    const s = await fetch('/api/settings').then((r) => r.json());
+    const box = $('mag-prov-tags');
+    if (box) box.checked = s.export_provenance_default !== false;
+  } catch (e) { /* default stays on */ }
+  magUpdateAudioZipLink();
+}
+
 function magUpdateAudioZipLink() {
+  magProvInit();
   const link = $('mag-audio-zip-link');
   if (!link) return;
+  const q = magProvQuery();
   const any = state.articles.some((a) => a.has_audio);
   link.hidden = !any;
-  if (any) link.href = '/api/magazine/' + state.doc.id + '/audio.zip';
+  if (any) link.href = '/api/magazine/' + state.doc.id + '/audio.zip' + q;
   // The EPUB carries only approved articles that have audio.
   const epub = $('mag-epub-link');
   if (epub) {
     const ready = state.articles.some((a) => a.has_audio && a.status === 'approved');
     epub.hidden = !ready;
-    if (ready) epub.href = '/api/magazine/' + state.doc.id + '/epub';
+    if (ready) epub.href = '/api/magazine/' + state.doc.id + '/epub' + q;
   }
 }
 
@@ -4828,7 +4852,7 @@ function renderArticle() {
         : '';
       return '<span class="mag-w" data-w="' + j + '">' + esc(w) + '</span>' + marker;
     }).join(' ');
-    return '<' + tag + ' class="mag-s' + (open === 'span' ? '' : '') + '" data-i="' + i + '" ' +
+    return '<' + tag + ' class="mag-s" data-i="' + i + '" ' +
       'onclick="magSeek(' + i + ')">' + wordsHtml + '</' + open + '> ' + (asidesAfter.get(i) || '');
   }).join('');
   highlight(state.idx);
@@ -6965,6 +6989,7 @@ root.magChecksToggled = magChecksToggled;
 root.magAcrSave = magAcrSave;
 root.magAcrResolve = magAcrResolve;
 root.magInit = magInit;
+root.magProvChanged = magProvChanged;
 MAG.magazineApi = { load: magLoadLibrary, refresh: magRefreshArticles, splitSentences, fmtPages };
 
 if (document.readyState === 'loading') {

static/js/routing.js

@@ -394,6 +394,10 @@ function renderRouteTestResult(d) {
   if (warnings.length) {
     parts.push('Warning: ' + warnings.map(escHtml).join('; '));
   }
+  const problems = Array.isArray(health.problems) ? health.problems : [];
+  if (problems.length) {
+    parts.push('Audio problems: ' + escHtml(fmtAudioProblems(problems)));
+  }
   const sounds = d.sounds || {};
   for (const [key, sound] of Object.entries(sounds)) {
     const label = key === 'before_sound' ? 'before sound' : 'after sound';

static/js/seed-finder.js

@@ -21,6 +21,8 @@ const SEED_FINDER_TEXT_DE = 'Die dreitausendfünfhundertsiebenundsechzig neuen G
 const SEED_FINDER_TEXT_EN = 'The new devices for the update required exceptionally strong cooling and regular maintenance to guarantee performance under heavy load. Make a note for the twenty-first of June at two in the afternoon. It is a genuine waste of time to do something mediocre! Dreams begin with a positive mindset.';
 const SEED_FINDER_TEXT_TORTURE = 'Die 3.567 neuen High-End Geräte für das Server-Update benötigen eine außergewöhnlich starke Kühlung und regelmäßige Maßnahmen, um die Performance bei großer Last zu gewährleisten. - The system administrator successfully configured the customized Docker stacks and benchmarked the inference engines at exactly 8:45 AM. - Notiere dir an Midsummer 21.06. um 14 Uhr - Es ist reine Zeitverschwendung, etwas Mittelmäßiges zu tun! Schöne Grüße! — Madonna - Träume beginnt mit einem positiven Mindset.';
 
+const _sfT = s => (typeof window.t === 'function' ? window.t(s) : s);
+
 function _seedFinderDefaultText(voiceId) {
   if (window._appSettings && window._appSettings.seed_finder_text) {
     return window._appSettings.seed_finder_text;
@@ -114,10 +116,12 @@ function attachSeedFinder(voiceId, body) {
         </div>
         <div class="seed-finder-actions">
           <button class="btn-primary seed-finder-run-btn">▶ Run Seed Finder</button>
+          <button class="btn-secondary seed-finder-autopick-btn" title="${_sfT('Generates up to 8 candidates, scores them and highlights the best. Nothing is saved until you click Use seed.')}">✨ ${_sfT('Auto-pick best')}</button>
           <button class="btn-secondary seed-finder-cancel-btn" style="display:none">✕ Cancel</button>
           <button class="btn-secondary seed-finder-clear-btn" style="display:none" title="Delete the saved samples cached for this voice">🗑 Clear saved</button>
           <span class="seed-finder-status"></span>
         </div>
+        <div class="seed-finder-autopick-status" role="status" aria-live="polite" style="min-height:1.2em"></div>
         <div class="seed-finder-row seed-finder-pin">
           <label class="seed-finder-label">Or fix this voice to a specific seed</label>
           <div class="seed-finder-pin-controls">
@@ -168,6 +172,8 @@ function attachSeedFinder(voiceId, body) {
   const progCount   = panel.querySelector('.seed-finder-progress-count');
   const progBar     = panel.querySelector('.seed-finder-bar');
   const resultsEl   = panel.querySelector('.seed-finder-results');
+  const autoBtn     = panel.querySelector('.seed-finder-autopick-btn');
+  const autoStatus  = panel.querySelector('.seed-finder-autopick-status');
 
   textEl.value = _seedFinderDefaultText(voiceId);
 
@@ -313,6 +319,7 @@ function attachSeedFinder(voiceId, body) {
     if (data.genSec) parts.push(`gen ${data.genSec.toFixed(1)}s`);
     if (data.rtf) parts.push(`${data.rtf.toFixed(2)}x`);
     if (data.cached) parts.push('saved');
+    if (data.note) parts.push(data.note);
     return parts.join(' · ');
   }
 
@@ -431,6 +438,62 @@ function attachSeedFinder(voiceId, body) {
     if (seedRows.size) clearBtn.style.display = '';
   }
 
+
+  // ── Auto-pick best: server generates + scores N candidates; the user confirms ──
+  let _autoAbort = null;
+  function _b64Blob(b64, type) {
+    const bin = atob(b64), u8 = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) u8[i] = bin.charCodeAt(i);
+    return new Blob([u8], { type: type || 'audio/wav' });
+  }
+  async function _runAutoPick() {
+    const text = textEl.value.trim();
+    if (!text) { autoStatus.textContent = _sfT('Enter a test sentence.'); return; }
+    const seedFrom = Math.max(0, parseInt(fromEl.value, 10) || 1);
+    const seedTo = Math.max(seedFrom, parseInt(toEl.value, 10) || 8);
+    const seeds = [];
+    for (let s = seedFrom; s <= Math.min(seedTo, seedFrom + 15); s++) seeds.push(s);
+    _autoAbort = new AbortController();
+    autoBtn.disabled = runBtn.disabled = true;
+    cancelBtn.style.display = '';
+    cancelBtn.onclick = () => { _cancelled = true; if (_autoAbort) _autoAbort.abort(); };
+    resultsEl.innerHTML = ''; seedRows.clear();
+    autoStatus.textContent = `${_sfT('Scoring')} ${seeds.length} ${_sfT('candidates… this can take a few minutes.')}`;
+    try {
+      const r = await fetch('/api/seed-autopick', {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ voice: voiceId, text, seeds }), signal: _autoAbort.signal,
+      });
+      if (!r.ok) { const e = await r.json().catch(() => ({})); throw new Error(e.detail || r.statusText); }
+      const res = await r.json();
+      for (const c of res.candidates) {
+        if (c.error) { _renderSeed(c.seed, { err: c.error }); continue; }
+        const acc = c.accuracy === null ? '' : `${_sfT('words')} ${Math.round(c.accuracy)}% · `;
+        const probs = c.problems && c.problems.length ? ` · ${c.problems.length} ${_sfT('audio problems')}` : '';
+        _renderSeed(c.seed, { blob: _b64Blob(c.audio_b64, c.media_type), dur: 0, note: `${_sfT('score')} ${c.score}/100 (${acc}${_sfT('level')} ${Math.round(c.loudness_score)}${probs})` });
+      }
+      const wRow = res.winner !== null ? seedRows.get(res.winner) : null;
+      if (wRow) {
+        wRow.classList.add('sfr-winner');
+        wRow.style.outline = '2px solid var(--accent, #4caf50)';
+        wRow.querySelector('.sfr-seed').insertAdjacentHTML('afterend', `<strong class="sfr-badge">★ ${_sfT('Best')}</strong>`);
+        wRow.querySelector('.sfr-play-btn').focus();
+      }
+      let msg = res.winner !== null
+        ? `${_sfT('Best seed')}: ${res.winner} (${_sfT('score')} ${res.candidates.find(c => c.seed === res.winner).score}/100). ${_sfT('Listen, then click Use seed to save.')}`
+        : _sfT('No candidate could be generated.');
+      if (res.degraded) msg += ` ${_sfT('Speech-to-text unavailable: scored by level and audio problems only.')}`;
+      if (res.cancelled) msg += ` ${_sfT('Cancelled.')}`;
+      autoStatus.textContent = msg;
+      if (seedRows.size) clearBtn.style.display = '';
+    } catch (e) {
+      autoStatus.textContent = e.name === 'AbortError' ? _sfT('Cancelled.') : `${_sfT('Auto-pick failed')}: ${e.message}`;
+    } finally {
+      autoBtn.disabled = runBtn.disabled = false; cancelBtn.style.display = 'none'; _autoAbort = null; cancelBtn.onclick = null;
+    }
+  }
+  autoBtn.addEventListener('click', _runAutoPick);
+
   runBtn.addEventListener('click', _runFinder);
   cancelBtn.addEventListener('click', () => { _cancelled = true; });
   clearBtn.addEventListener('click', async () => {

static/js/settings.js

@@ -579,6 +579,12 @@ async function loadSettings() {
   restoreEngineApiKeyInputs();
   const extKeyInp = $('s-external-api-key');
   if (extKeyInp) { extKeyInp.value = ''; extKeyInp.placeholder = s.external_api_key === '__configured__' ? 'Configured — regenerate to replace' : ''; }
+  const inlineTags = $('s-inline-tags-enabled');
+  if (inlineTags) inlineTags.checked = !!s.inline_tags_enabled;
+  if (inlineTags && !inlineTags.dataset.wired) {
+    inlineTags.dataset.wired = '1';
+    inlineTags.addEventListener('change', () => _patchSettings({ inline_tags_enabled: inlineTags.checked }));
+  }
   const extKeyReq = $('s-external-api-key-required');
   if (extKeyReq) extKeyReq.checked = !!s.external_api_key_required;
   if (extKeyReq && !extKeyReq.dataset.wired) {

static/js/tts-preview.js

@@ -61,6 +61,18 @@ function previewVoiceWarnings(v) {
   return warnings;
 }
 
+async function showVoiceProblems(id) {
+  const el = $('preview-match-problems');
+  if (!el) return;
+  el.textContent = '';
+  try {
+    const h = await fetch(`/api/voices/${encodeURIComponent(id)}/health`).then(r => r.ok ? r.json() : null);
+    const text = h ? fmtAudioProblems(h.problems) : '';
+    if ($('tts-voice-select')?.value === id) el.textContent = text ? 'Audio problems: ' + text : '';
+  } catch (_) { /* advisory only */ }
+}
+window.showVoiceProblems = showVoiceProblems;
+
 function updatePreviewVoiceMatchPanel() {
   const panel = $('preview-match-panel');
   if (!panel) return;
@@ -73,6 +85,7 @@ function updatePreviewVoiceMatchPanel() {
   const dur = v.duration ? fmtDuration(v.duration) : '-';
   $('preview-match-title').textContent = v.id;
   $('preview-match-detail').textContent = `${lang} · ${gender} · ${dur} · ${db} dBFS`;
+  showVoiceProblems(v.id);
   const warnings = previewVoiceWarnings(v);
   $('preview-match-warning').textContent = warnings.length ? warnings.join(' ') : 'For a fair voice match check, play the WAV and synthesize the exact saved reference text.';
   const transcript = cleanReferenceText(v.transcript || '');

static/js/utils.js

@@ -1455,3 +1455,10 @@ Object.assign(root.TTVC.utils, {
   memory: { isLow: ttvcIsLowMemoryDevice },
 });
 })(window);
+
+// Human-readable, timestamped audio problems (text only, no colour cue).
+function fmtAudioProblems(problems) {
+  return (Array.isArray(problems) ? problems : []).slice(0, 8).map(q =>
+    `${String(q.kind).replace('_', ' ')} at ${q.start_s}s` + (q.end_s > q.start_s ? `\u2013${q.end_s}s` : '') + ` (${q.detail})`).join('; ');
+}
+window.fmtAudioProblems = fmtAudioProblems;

static/js/vocal-isolation.js

@@ -0,0 +1,34 @@
+// Optional "Remove background music" for URL/YouTube imports. Button appears only when the
+// server reports features.vocal_isolation. Original stays loadable via the toggle (before/after).
+function setupVocalIsolation({ btn, toggle, msg, getId, getDur, apply }) {
+  const b = $(btn), t = $(toggle), m = $(msg);
+  let pair = null, showing = 'clean';
+  const say = text => { m.textContent = text; status(text); };
+  fetch('/api/version').then(r => r.json()).then(v => { if (v?.features?.vocal_isolation) b.hidden = false; }).catch(() => {});
+  const label = () => { t.textContent = showing === 'clean' ? 'Play original' : 'Play without music'; };
+  b.addEventListener('click', async () => {
+    const id = getId();
+    if (!id) { say('Load audio first, then remove the background music.'); return; }
+    b.disabled = true; t.hidden = true;
+    say('Removing background music. This can take a few minutes.');
+    try {
+      const r = await fetch('/api/isolate-vocals', { method:'POST', headers:{'Content-Type':'application/json'}, body:JSON.stringify({ id }) });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok) throw new Error(d.detail || r.statusText);
+      pair = { orig:id, origDur:getDur(), clean:d.id, cleanDur:d.duration };
+      showing = 'clean'; apply(d.id, d.duration);
+      t.hidden = false; label();
+      say('Background music removed. Use the button next to it to compare with the original.');
+    } catch (e) {
+      say('Could not remove background music: ' + e.message);
+      toast('Vocal isolation failed: ' + e.message, 'error');
+    } finally { b.disabled = false; }
+  });
+  t.addEventListener('click', () => {
+    if (!pair) return;
+    showing = showing === 'clean' ? 'orig' : 'clean';
+    if (showing === 'clean') apply(pair.clean, pair.cleanDur); else apply(pair.orig, pair.origDur);
+    label();
+    say(showing === 'clean' ? 'Playing the version without background music.' : 'Playing the original audio.');
+  });
+}

static/js/voice-archetypes.js

@@ -0,0 +1,153 @@
+// -- Voice archetype gallery (Design a Voice) ---------------------------------
+// Lazy: nothing is fetched or rendered until the <details> is opened.
+(function () {
+const det = document.getElementById('archetype-gallery');
+if (!det) return;
+const tr = s => (window.t ? window.t(s) : s);
+const $a = id => document.getElementById(id);
+const PAGE = 24, FAV_KEY = 'ttsvc-archetype-favs';
+const FACETS = [
+  ['gender', 'Gender', ['male', 'female', 'neutral']],
+  ['age', 'Age', ['child', 'teenager', 'young adult', 'middle-aged', 'elderly']],
+  ['pitch', 'Pitch', ['high', 'mid', 'low']],
+  ['accent', 'Accent / region', ['none', 'british', 'american', 'australian', 'irish', 'german', 'southern']],
+  ['language', 'Language', ['German', 'English']],
+];
+const st = { gender: '', age: '', pitch: '', accent: '', language: '', category: '', q: '', favOnly: false, offset: 0, total: 0 };
+let favs = new Set(), booted = false, token = 0, objUrl = '';
+try { favs = new Set(JSON.parse(localStorage.getItem(FAV_KEY) || '[]')); } catch (_) {}
+const saveFavs = () => { try { localStorage.setItem(FAV_KEY, JSON.stringify([...favs])); } catch (_) {} };
+const archSay = m => { $a('arch-status').textContent = m; };
+const lang = () => (window.__APP_LANG__ === 'de' ? 'de' : 'en');
+
+function buildChips() {
+  const box = $a('arch-chips');
+  FACETS.forEach(([key, label, vals]) => {
+    const g = document.createElement('div');
+    g.className = 'design-chip-group'; g.setAttribute('role', 'group'); g.setAttribute('aria-label', tr(label));
+    const l = document.createElement('span'); l.className = 'design-chip-label'; l.textContent = tr(label); g.appendChild(l);
+    vals.forEach(v => {
+      const b = document.createElement('button');
+      b.type = 'button'; b.className = 'design-chip'; b.dataset.k = key; b.dataset.v = v;
+      b.setAttribute('aria-pressed', 'false'); b.textContent = tr(v);
+      g.appendChild(b);
+    });
+    box.appendChild(g);
+  });
+  const f = document.createElement('button');
+  f.type = 'button'; f.className = 'design-chip'; f.id = 'arch-fav-only'; f.setAttribute('aria-pressed', 'false');
+  f.textContent = tr('Favourites only'); box.appendChild(f);
+  box.addEventListener('click', e => {
+    const b = e.target.closest('button'); if (!b) return;
+    if (b.id === 'arch-fav-only') st.favOnly = !st.favOnly;
+    else st[b.dataset.k] = st[b.dataset.k] === b.dataset.v ? '' : b.dataset.v;
+    box.querySelectorAll('[data-k]').forEach(x => x.setAttribute('aria-pressed', String(st[x.dataset.k] === x.dataset.v)));
+    f.setAttribute('aria-pressed', String(st.favOnly));
+    load(true);
+  });
+}
+
+function card(a) {
+  const name = lang() === 'de' ? a.name_de : a.name_en;
+  const el = document.createElement('article');
+  el.className = 'arch-card'; el.dataset.id = a.id;
+  const h = document.createElement('h3'); h.textContent = name;
+  const f = document.createElement('div'); f.className = 'arch-facets';
+  f.textContent = [a.language, ...Object.values(a.facets)].map(tr).join(' · ');
+  const p = document.createElement('p'); p.textContent = a.category;
+  const row = document.createElement('div'); row.className = 'arch-actions';
+  const mk = (cls, text, label) => {
+    const b = document.createElement('button'); b.type = 'button'; b.className = cls;
+    b.textContent = text; if (label) b.setAttribute('aria-label', label + ': ' + name); row.appendChild(b); return b;
+  };
+  mk('btn-primary arch-play', tr('Preview'), tr('Preview'));
+  mk('btn-secondary arch-use', tr('Use voice'), tr('Use voice'));
+  const fav = mk('btn-secondary arch-fav', favs.has(a.id) ? '★' : '☆', tr('Favourite'));
+  fav.setAttribute('aria-pressed', String(favs.has(a.id)));
+  el.append(h, f, p, row);
+  return el;
+}
+
+async function load(reset) {
+  const my = ++token;
+  if (reset) { st.offset = 0; $a('arch-grid').textContent = ''; }
+  const q = new URLSearchParams({ offset: st.offset, limit: st.favOnly ? 100 : PAGE });
+  ['gender', 'age', 'pitch', 'accent', 'language', 'category', 'q'].forEach(k => st[k] && q.set(k, st[k]));
+  archSay(tr('Loading…'));
+  try {
+    const r = await fetch('/api/archetypes?' + q);
+    if (!r.ok) throw new Error(r.statusText);
+    const d = await r.json();
+    if (my !== token) return;
+    if (!$a('arch-category').options.length) {
+      const sel = $a('arch-category');
+      [['', tr('All categories')], ...d.categories.map(c => [c, c])].forEach(([v, t]) => sel.add(new Option(t, v)));
+    }
+    const items = st.favOnly ? d.items.filter(a => favs.has(a.id)) : d.items;
+    const grid = $a('arch-grid');
+    items.forEach(a => grid.appendChild(card(a)));
+    st.offset += d.items.length; st.total = d.total;
+    $a('arch-more').hidden = st.favOnly || st.offset >= d.total;
+    archSay(grid.children.length ? grid.children.length + ' / ' + (st.favOnly ? grid.children.length : d.total) : tr('No voices match.'));
+  } catch (e) { if (my === token) archSay(tr('Could not load the gallery.')); }
+}
+
+async function play(a, btn) {
+  btn.disabled = true; archSay(tr('Rendering preview…'));
+  try {
+    const r = await fetch('/api/archetypes/' + encodeURIComponent(a) + '/preview', { method: 'POST' });
+    if (!r.ok) { const e = await r.json().catch(() => ({})); throw new Error(e.detail || r.statusText); }
+    if (objUrl) URL.revokeObjectURL(objUrl);
+    objUrl = URL.createObjectURL(await r.blob());
+    const au = $a('arch-audio'); au.src = objUrl; await au.play().catch(() => {});
+    archSay(tr('Preview ready'));
+  } catch (e) { archSay(tr('Preview failed') + ': ' + e.message); }
+  finally { btn.disabled = false; }
+}
+
+async function use(id, btn) {
+  btn.disabled = true; archSay(tr('Saving voice…'));
+  try {
+    const r = await fetch('/api/archetypes/' + encodeURIComponent(id) + '/use', { method: 'POST' });
+    if (!r.ok) { const e = await r.json().catch(() => ({})); throw new Error(e.detail || r.statusText); }
+    const d = await r.json();
+    archSay(tr('Voice saved') + ': ' + d.voice_id);
+    if (typeof toast === 'function') toast(tr('Voice saved') + ': ' + d.voice_id, 'success');
+    if (!btn.parentNode.querySelector('.arch-open')) {
+      const o = document.createElement('button'); o.type = 'button'; o.className = 'btn-secondary arch-open';
+      o.textContent = tr('Open in Design'); o.dataset.instruct = d.instruct; o.dataset.language = d.language;
+      btn.parentNode.insertBefore(o, btn.nextSibling); o.focus();
+    }
+    if (typeof loadVoiceLibrary === 'function') loadVoiceLibrary().catch(() => {});
+  } catch (e) { archSay(tr('Save failed') + ': ' + e.message); if (typeof toast === 'function') toast(e.message, 'error'); }
+  finally { btn.disabled = false; }
+}
+
+function boot() {
+  if (booted) return; booted = true;
+  buildChips();
+  let t;
+  $a('arch-q').addEventListener('input', e => { clearTimeout(t); t = setTimeout(() => { st.q = e.target.value.trim(); load(true); }, 250); });
+  $a('arch-category').addEventListener('change', e => { st.category = e.target.value; load(true); });
+  $a('arch-more').addEventListener('click', () => load(false));
+  $a('arch-grid').addEventListener('click', e => {
+    const b = e.target.closest('button'); if (!b) return;
+    const id = b.closest('.arch-card').dataset.id;
+    if (b.classList.contains('arch-play')) play(id, b);
+    else if (b.classList.contains('arch-use')) use(id, b);
+    else if (b.classList.contains('arch-fav')) {
+      favs.has(id) ? favs.delete(id) : favs.add(id); saveFavs();
+      b.textContent = favs.has(id) ? '★' : '☆'; b.setAttribute('aria-pressed', String(favs.has(id)));
+    } else if (b.classList.contains('arch-open')) {
+      const ta = $a('design-instruct');
+      ta.value = b.dataset.instruct; ta.dispatchEvent(new Event('input', { bubbles: true }));
+      const sel = $a('d-lang'); if (sel) for (const o of sel.options) if (o.value === b.dataset.language) sel.value = o.value;
+      ta.scrollIntoView({ behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth', block: 'center' });
+      ta.focus();
+    }
+  });
+  load(true);
+}
+det.addEventListener('toggle', () => { if (det.open) boot(); });
+if (det.open) boot();
+})();

static/js/voice-clone.js

@@ -815,6 +815,67 @@ $('design-preset-delete').addEventListener('click', () => {
   if (id === 'design-sample-text') $('d-transcript').value = $('design-sample-text').value;
 }));
 
+// ── Attribute chips: each chip owns one phrase in #design-instruct ───────────
+// Toggling edits only that phrase; free text stays authoritative (any description works).
+const DESIGN_CHIPS = [
+  ['Gender', true, ['male voice', 'female voice', 'neutral voice']],
+  ['Age', true, ['child', 'teenager', 'young adult', 'middle-aged', 'elderly']],
+  ['Pitch', true, ['high pitch', 'mid pitch', 'low pitch']],
+  ['Pace', true, ['fast pace', 'moderate pace', 'slow pace']],
+  ['Accent / region', false, ['British accent', 'American accent', 'Australian accent', 'Irish accent', 'German accent', 'Southern accent']],
+  ['Tone / timbre', false, ['warm', 'husky', 'crisp', 'smooth', 'rich', 'magnetic', 'authoritative']],
+  ['Emotion', false, ['cheerful', 'calm', 'serious', 'gentle', 'enthusiastic', 'sad']],
+];
+const _chipRe = p => new RegExp('(^|[,.;]\\s*)' + p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?=\\s*(?:[,.;]|$))', 'i');
+const chipHas = (text, p) => _chipRe(p).test(text);
+function chipRemove(text, p) {
+  return text.replace(_chipRe(p), '').replace(/^\s*[,;]\s*/, '');
+}
+function chipAdd(text, p) {
+  const t = text.trimEnd();
+  return !t ? p : /[.,;]$/.test(t) ? t + ' ' + p : t + ', ' + p;
+}
+function syncDesignChips() {
+  const v = $('design-instruct').value;
+  document.querySelectorAll('#design-chips [data-phrase]').forEach(b =>
+    b.setAttribute('aria-pressed', String(chipHas(v, b.dataset.phrase))));
+}
+function renderDesignChips() {
+  const tr = window.t || (x => x), box = $('design-chips');
+  DESIGN_CHIPS.forEach(([label, exclusive, phrases], i) => {
+    const g = document.createElement('div');
+    g.className = 'design-chip-group'; g.setAttribute('role', 'group');
+    g.setAttribute('aria-label', tr(label));
+    g.innerHTML = '<span class="design-chip-label"></span>';
+    g.firstChild.textContent = tr(label);
+    phrases.forEach(p => {
+      const b = document.createElement('button');
+      b.type = 'button'; b.className = 'design-chip'; b.dataset.phrase = p; b.dataset.group = i;
+      b.setAttribute('aria-pressed', 'false'); b.textContent = tr(p);
+      g.appendChild(b);
+    });
+    box.appendChild(g);
+  });
+  box.addEventListener('click', e => {
+    const b = e.target.closest('[data-phrase]'); if (!b) return;
+    const ta = $('design-instruct'); let v = ta.value;
+    const on = chipHas(v, b.dataset.phrase);
+    if (on) v = chipRemove(v, b.dataset.phrase);
+    else {
+      if (DESIGN_CHIPS[b.dataset.group][1])
+        DESIGN_CHIPS[b.dataset.group][2].forEach(o => { v = chipRemove(v, o); });
+      v = chipAdd(v, b.dataset.phrase);
+    }
+    ta.value = v; ta.dispatchEvent(new Event('input', { bubbles: true }));
+  });
+  // Programmatic value changes (presets, samples) don't fire input; resync on focus/hover.
+  box.addEventListener('focusin', syncDesignChips);
+  box.addEventListener('pointerenter', syncDesignChips);
+  $('design-instruct').addEventListener('input', syncDesignChips);
+  syncDesignChips();
+}
+renderDesignChips();
+
 document.querySelectorAll('.qwen-sample').forEach(card => {
   const sample = QWEN_DESIGN_SAMPLES[card.dataset.qwenSample];
   const state = card.querySelector('.qwen-state');
@@ -1072,3 +1133,6 @@ Object.assign(root.TTVC.voiceClone, {
   design: { run: runVoiceDesign, buildPayload: voiceDesignPayload },
 });
 })(window);
+
+setupVocalIsolation({ btn:'yt-iso-btn', toggle:'yt-iso-toggle', msg:'yt-iso-msg',
+  getId:() => currentFileId, getDur:() => parseFloat($('trim-end').value) || 0, apply:(id, dur) => loadAudioId(id, dur) });

static/js/voice-inspector.js

@@ -118,6 +118,7 @@ function selectVoice(wrap) {
             </span>
             <span class="insp-gender-label" title="Click to cycle gender">${escHtml(genderLabelHtml)}</span>
             <span class="vl-type-label ${isClone ? 'vl-type-clone' : 'vl-type-design'}">${isClone ? 'Clone' : 'Design'}</span>
+            ${window.provenanceBadge ? window.provenanceBadge(v) : ''}
             ${inspBenchText !== '-' ? `<span class="insp-bench-chip ${escHtml(inspBenchCls)}" title="${escHtml(inspBenchTitle)}"><span class="mdi mdi-timer-outline"></span> ${escHtml(inspBenchText)}</span>` : ''}
             <span class="insp-stars-wrap">
               <span class="insp-stars">${makeStars(rating)}</span>
@@ -490,6 +491,9 @@ function selectVoice(wrap) {
     } catch(e) { toast('Save failed: ' + e.message, 'error'); }
   });
 
+  // ── Source & consent (provenance) ─────────────────────────────────────────
+  attachProvenancePanel(v, voiceId, body);
+
   const maintTitle = body.querySelector('.opt-maintenance .opt-group-title');
   if (maintTitle) {
     maintTitle.innerHTML = `<span class="opt-chevron"></span><span class="opt-title-text">Loudness <span class="opt-group-meta">Current ${escHtml(dbfs)} dBFS</span></span>`;
@@ -518,6 +522,95 @@ function selectVoice(wrap) {
 
 }
 
+const PROV_BASES = [['unknown', 'Unknown'], ['own_voice', 'My own voice'], ['consented', 'Speaker consented'],
+  ['licensed', 'Licensed'], ['public_domain', 'Public domain']];
+
+// Warning chip for voices whose consent/source is not recorded (list rows + inspector).
+root.provenanceBadge = v => ((v && v.provenance && v.provenance.basis) || 'unknown') === 'unknown'
+  ? '<span class="vl-prov-badge" title="Source and consent not recorded - open the voice to set them"><span class="mdi mdi-alert-outline" aria-hidden="true"></span> Source unknown</span>'
+  : '';
+
+function attachProvenancePanel(v, voiceId, body) {
+  const p = v.provenance || {};
+  const id = 'prov-' + voiceId.replace(/[^A-Za-z0-9_-]/g, '_');
+  const panel = document.createElement('section');
+  panel.className = 'insp-persona-panel insp-prov-panel';
+  panel.setAttribute('aria-labelledby', id + '-h');
+  panel.innerHTML = `
+    <div class="insp-persona-head">
+      <h4 class="insp-persona-title" id="${id}-h">Source &amp; consent</h4>
+      <span class="insp-persona-hint">Where this voice comes from and why you may use it. Stored locally in this voice's metadata only; nothing is sent anywhere. Generation is not blocked by this.</span>
+    </div>
+    <label for="${id}-basis">Basis</label>
+    <select id="${id}-basis" class="insp-prov-input">${PROV_BASES.map(([k, l]) =>
+      `<option value="${k}"${(p.basis || 'unknown') === k ? ' selected' : ''}>${l}</option>`).join('')}</select>
+    <label for="${id}-source">Source (URL or description, no passwords)</label>
+    <input id="${id}-source" class="insp-prov-input" type="text" maxlength="500" autocomplete="off" value="${escHtml(p.source || '')}">
+    <label for="${id}-licence">Licence</label>
+    <input id="${id}-licence" class="insp-prov-input" type="text" maxlength="300" autocomplete="off" value="${escHtml(p.licence || '')}">
+    <label for="${id}-note">Consent statement or note (typed alternative to a recording)</label>
+    <textarea id="${id}-note" class="insp-persona-input" rows="2" maxlength="1000">${escHtml(p.note || '')}</textarea>
+    <div class="insp-prov-rec">
+      <button type="button" class="btn-secondary insp-prov-rec-btn" aria-pressed="false">Record spoken consent</button>
+      <audio class="insp-prov-audio" controls ${p.recorded_consent ? `src="/api/voices/${encodeURIComponent(voiceId)}/consent-recording"` : 'hidden'} aria-label="Recorded consent statement"></audio>
+    </div>
+    <div class="insp-persona-actions">
+      <button type="button" class="btn-primary btn-sm insp-prov-save">Save source &amp; consent</button>
+      <span class="insp-persona-status" role="status" aria-live="polite"></span>
+    </div>`;
+  body.appendChild(panel);
+  const q = sel => panel.querySelector(sel);
+  const status = q('.insp-persona-status');
+  const say = (msg, err) => { status.textContent = msg; status.style.color = err ? 'var(--danger, #dc2626)' : ''; };
+  q('.insp-prov-save').addEventListener('click', async () => {
+    try {
+      const r = await fetch(`/api/voices/${encodeURIComponent(voiceId)}/provenance`, {
+        method: 'PUT', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ basis: q(`#${id}-basis`).value, source: q(`#${id}-source`).value,
+          licence: q(`#${id}-licence`).value, note: q(`#${id}-note`).value }) });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok) throw new Error(d.detail || r.statusText);
+      v.provenance = d.provenance;
+      if (typeof window.invalidateVoiceLibraryCache === 'function') window.invalidateVoiceLibraryCache();
+      say('Saved.');
+    } catch (e) { say('Save failed: ' + e.message, true); }
+  });
+  const btn = q('.insp-prov-rec-btn');
+  let rec = null;
+  btn.addEventListener('click', async () => {
+    if (rec) { rec.stop(); return; }
+    if (!navigator.mediaDevices || !window.MediaRecorder) {
+      say('Recording is not supported in this browser. Type the consent statement in the note field instead.', true); return;
+    }
+    let stream;
+    try { stream = await navigator.mediaDevices.getUserMedia({ audio: true }); }
+    catch (e) {
+      say(e && e.name === 'NotAllowedError'
+        ? 'Microphone permission was denied. Allow it in the browser, or type the consent statement in the note field.'
+        : 'No usable microphone found. Type the consent statement in the note field instead.', true); return;
+    }
+    const chunks = [];
+    rec = new MediaRecorder(stream);
+    rec.ondataavailable = ev => { if (ev.data.size) chunks.push(ev.data); };
+    rec.onstop = async () => {
+      stream.getTracks().forEach(t => t.stop());
+      rec = null; btn.textContent = 'Record spoken consent'; btn.setAttribute('aria-pressed', 'false');
+      try {
+        const fd = new FormData();
+        fd.append('file', new Blob(chunks, { type: 'audio/webm' }), 'consent.webm');
+        const r = await fetch(`/api/voices/${encodeURIComponent(voiceId)}/consent-recording`, { method: 'POST', body: fd });
+        const d = await r.json().catch(() => ({}));
+        if (!r.ok) throw new Error(d.detail || r.statusText);
+        v.provenance = d.provenance;
+        const a = q('.insp-prov-audio'); a.src = `/api/voices/${encodeURIComponent(voiceId)}/consent-recording?t=${Date.now()}`; a.hidden = false;
+        say('Consent recording saved.');
+      } catch (e) { say('Upload failed: ' + e.message, true); }
+    };
+    rec.start(); btn.textContent = 'Stop recording'; btn.setAttribute('aria-pressed', 'true');
+    say('Recording... say who you are, that you consent to this voice being cloned, and for what use.');
+  });
+}
+
 root.selectVoice = selectVoice;
 root.TTVC = root.TTVC || {};
 root.TTVC.voiceInspector = root.TTVC.voiceInspector || {};

static/js/voice-library.js

@@ -720,6 +720,56 @@ async function loadVoiceLibrary(options = {}) {
 }
 
 $('refresh-voices-btn').addEventListener('click', () => { _vlCacheClear(); loadVoiceLibrary({ refresh: true }); });
+// ── Voice bundles (export / import .voice.zip) ───────────────────────────────
+async function exportVoiceBundles(ids) {
+  let ok = 0;
+  for (const id of ids) {
+    try {
+      const r = await fetch('/api/voices/' + encodeURIComponent(id) + '/export');
+      if (!r.ok) { const e = await r.json().catch(() => ({})); throw new Error(e.detail || r.statusText); }
+      const url = URL.createObjectURL(await r.blob());
+      const a = document.createElement('a');
+      a.href = url; a.download = id + '.voice.zip';
+      document.body.appendChild(a); a.click(); a.remove();
+      setTimeout(() => URL.revokeObjectURL(url), 10000);
+      ok++;
+    } catch (e) { toast(`Export of ${id} failed: ${e.message}`, 'error'); }
+  }
+  if (ok) toast(`Exported ${ok} voice bundle${ok === 1 ? '' : 's'}`, 'success');
+  return ok;
+}
+async function importVoiceBundles(files) {
+  const msgs = []; let failed = 0;
+  for (const f of files) {
+    try {
+      const fd = new FormData(); fd.append('file', f);
+      const r = await fetch('/api/voices/import', { method: 'POST', body: fd });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok) throw new Error(d.detail || r.statusText);
+      msgs.push(d.status === 'unchanged' ? `${d.voice_id} already present` : d.status === 'renamed' ? `${d.voice_id} (name was taken)` : d.voice_id);
+    } catch (e) { failed++; toast(`Import of ${f.name} failed: ${e.message}`, 'error'); }
+  }
+  if (msgs.length) {
+    if (typeof window.invalidateVoiceLibraryCache === 'function') window.invalidateVoiceLibraryCache();
+    await loadVoiceLibrary({ refresh: true });
+    toast('Imported: ' + msgs.join(', '), failed ? 'error' : 'success');
+  }
+  return msgs.length;
+}
+window.exportVoiceBundles = exportVoiceBundles;
+window.importVoiceBundles = importVoiceBundles;
+$('export-voices-btn').addEventListener('click', async () => {
+  if (!_bulkSelected.size) { toast('Check one or more voices first', 'error'); return; }
+  $('export-voices-btn').disabled = true;
+  try { await exportVoiceBundles([..._bulkSelected]); } finally { $('export-voices-btn').disabled = false; }
+});
+$('import-voices-btn').addEventListener('click', () => $('import-voices-input').click());
+$('import-voices-input').addEventListener('change', async ev => {
+  const files = [...ev.target.files]; ev.target.value = '';
+  if (!files.length) return;
+  $('import-voices-btn').disabled = true;
+  try { await importVoiceBundles(files); } finally { $('import-voices-btn').disabled = false; }
+});
 $('sync-voice-folders-btn').addEventListener('click', async () => {
   $('sync-voice-folders-btn').disabled = true;
   status('Syncing active_voices and hidden_voices…');
@@ -1596,6 +1646,9 @@ $('lib-add-url-btn').addEventListener('click', () => {
   };
 });
 
+setupVocalIsolation({ btn:'lib-iso-btn', toggle:'lib-iso-toggle', msg:'lib-iso-msg',
+  getId:() => libAddState.id, getDur:() => libAddState.duration, apply:(id, dur) => loadLibAddAudio(id, dur, 'Audio') });
+
 $('lib-add-rec-start').addEventListener('click', async () => {
   try {
     await ensureLibAddMicMonitor();

static/js/voice-sources.js

@@ -192,6 +192,82 @@ $('getvoices-reset-sources-btn')?.addEventListener('click', () => {
   renderGetVoices();
   $('getvoices-status').textContent = 'Source list reset.';
 });
+// -- LibriVox / Wikimedia Commons (server-side official-API search) ----------
+let _osItems = [];
+function osDuration(sec) { sec = Math.round(sec || 0); return sec ? `${Math.floor(sec / 60)}:${String(sec % 60).padStart(2, '0')}` : ''; }
+function renderOpenSources() {
+  $('os-list').innerHTML = _osItems.map((it, i) => `<div class="voice-source-card">
+    <div class="voice-source-title"><strong>${escHtml(it.title)}</strong><span>${escHtml([it.reader, it.language, osDuration(it.duration)].filter(Boolean).join(' · '))}</span></div>
+    <div class="voice-source-desc">Licence: ${it.licence_url ? `<a href="${escHtml(it.licence_url)}" target="_blank" rel="noopener">${escHtml(it.licence)}</a>` : escHtml(it.licence)}</div>
+    ${it.audio_url
+      ? `<audio controls preload="none" aria-label="Preview ${escHtml(it.title)}" src="/api/proxy-audio?url=${encodeURIComponent(it.audio_url)}"></audio>`
+      : `<button class="btn-secondary os-load" type="button" data-i="${i}">Load preview</button>`}
+    <div class="voice-source-actions">
+      <a class="btn-secondary" href="${escHtml(it.source_url)}" target="_blank" rel="noopener">Source page</a>
+      <button class="btn-primary os-import" type="button" data-i="${i}">Import clip</button>
+    </div></div>`).join('');
+}
+async function searchOpenSources(ev) {
+  ev?.preventDefault();
+  const st = $('os-status'), btn = $('os-search-btn');
+  const q = ($('os-q').value || '').trim();
+  if (!q) { st.textContent = 'Enter a search term.'; return; }
+  btn.disabled = true; st.textContent = 'Searching...';
+  try {
+    const p = new URLSearchParams({q, lang: $('os-lang').value});
+    const r = await fetch(`/api/voice-sources/${encodeURIComponent($('os-source').value)}?${p}`);
+    const d = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(d.detail || r.statusText);
+    _osItems = d.items || [];
+    renderOpenSources();
+    st.textContent = `${_osItems.length} result${_osItems.length === 1 ? '' : 's'}.`;
+  } catch (e) {
+    _osItems = []; renderOpenSources(); st.textContent = 'Search failed: ' + e.message;
+  } finally { btn.disabled = false; }
+}
+// LibriVox list items carry only book_id; the first chapter's audio is fetched on demand.
+async function resolveOpenSource(it) {
+  if (it.audio_url || !it.book_id) return;
+  const r = await fetch(`/api/voice-sources/librivox/book/${encodeURIComponent(it.book_id)}`);
+  const d = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(d.detail || r.statusText);
+  Object.assign(it, {audio_url: d.audio_url, reader: d.reader || it.reader, duration: d.duration || it.duration,
+    title: d.section ? `${it.title} - ${d.section}` : it.title});
+}
+async function importOpenSource(it) {
+  const st = $('os-status');
+  st.textContent = 'Looking up audio...';
+  try { await resolveOpenSource(it); } catch (e) { st.textContent = 'Lookup failed: ' + e.message; return; }
+  const lang = sourceLanguageCode(it.language || $('os-lang').value || 'English');
+  const body = {
+    audio_url: it.audio_url, voice_id: suggestedVoiceIdFromSourceName(it.title, lang, 'N'), transcript: '', lang,
+    source_kind: it.source, page_url: it.source_url, licence: it.licence, attribution: it.attribution || '',
+    name: it.title, group: it.source, origin: 'cloned', start: +$('os-start').value || 0, length: +$('os-len').value || 30,
+    note: `${it.reader || ''} ${it.licence}`.trim(),
+  };
+  st.textContent = 'Importing...';
+  try {
+    const r = await fetch('/api/quick-import-voice', {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(body)});
+    const d = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(d.detail || r.statusText);
+    st.textContent = `Saved as ${d.voice_id} (source and licence stored).`;
+    toast(`Saved as ${d.voice_id}`, 'success');
+    _libraryLoadPromise = null;
+  } catch (e) { st.textContent = 'Import failed: ' + e.message; toast('Import failed: ' + e.message, 'error'); }
+}
+$('os-form')?.addEventListener('submit', searchOpenSources);
+$('os-list')?.addEventListener('click', async e => {
+  const l = e.target.closest('.os-load');
+  if (l && _osItems[+l.dataset.i]) {
+    l.disabled = true; $('os-status').textContent = 'Loading preview...';
+    try { await resolveOpenSource(_osItems[+l.dataset.i]); renderOpenSources(); $('os-status').textContent = 'Preview ready.'; }
+    catch (err) { l.disabled = false; $('os-status').textContent = 'Preview failed: ' + err.message; }
+    return;
+  }
+  const b = e.target.closest('.os-import');
+  if (b && _osItems[+b.dataset.i]) importOpenSource(_osItems[+b.dataset.i]);
+});
+
 const SOURCE_LANGUAGE_CODES = {
   english:'EN', german:'DE', deutsch:'DE', french:'FR', spanish:'ES', japanese:'JA', korean:'KO',
   italian:'IT', portuguese:'PT', russian:'RU', arabic:'AR', polish:'PL', dutch:'NL', swedish:'SV',
@@ -304,7 +380,7 @@ Object.assign(root, {
   sourceTextareaValueFromDefaults, initGetVoiceSourcesEditor, getEditableVoiceSourceUrls,
   getVoiceSourceItems, voiceSourceSearchText, setOptions, renderGetVoices, loadGetVoices,
   SOURCE_LANGUAGE_CODES, sourceLanguageCode, sourceGenderCode, suggestedVoiceIdFromSourceName,
-  setLibAddSourcePreview, getSourceVoiceInLibrary,
+  setLibAddSourcePreview, getSourceVoiceInLibrary, searchOpenSources, importOpenSource,
 });
 root.TTVC = root.TTVC || {};
 root.TTVC.voiceSources = root.TTVC.voiceSources || {};

static/module-manifest.json

@@ -11,7 +11,9 @@
     "image-cache",
     "integrations",
     "routing",
+    "vocal-isolation",
     "voice-clone",
+    "voice-archetypes",
     "voice-library",
     "tts-preview",
     "generation",

static/sections/s-clone.html

@@ -83,6 +83,11 @@
                 <button class="btn-primary" id="yt-btn">Download</button>
               </div>
               <div id="yt-progress"></div>
+              <div class="btn-row">
+                <button class="btn-secondary" id="yt-iso-btn" hidden>Remove background music</button>
+                <button class="btn-secondary" id="yt-iso-toggle" hidden></button>
+              </div>
+              <div class="note" id="yt-iso-msg" role="status" aria-live="polite"></div>
             </div>
 
           </div><!-- /clone-srcpanel -->

static/sections/s-design.html

@@ -21,6 +21,24 @@
           </details>
         </div>
 
+        <div class="card">
+          <details id="archetype-gallery" class="design-samples-details">
+            <summary>
+              <span>Voice gallery</span>
+              <span class="note">40 ready-made German-first voices. Preview, save or open in the editor below.</span>
+            </summary>
+            <div class="arch-bar">
+              <input type="search" id="arch-q" class="section-search" placeholder="Search voices&#x2026;" aria-label="Search voices" autocomplete="off">
+              <select id="arch-category" class="lang-select" aria-label="Category"></select>
+            </div>
+            <div id="arch-chips" class="design-chips"></div>
+            <p id="arch-status" class="note" role="status" aria-live="polite"></p>
+            <div id="arch-grid" class="arch-grid"></div>
+            <button type="button" id="arch-more" class="btn-secondary" hidden>Load more</button>
+            <audio id="arch-audio" hidden></audio>
+          </details>
+        </div>
+
         <div class="card">
           <h2>Describe the voice</h2>
           <p class="card-subtitle">Describe the voice you want. Qwen3-TTS VoiceDesign will synthesise it from the description and sample text.</p>
@@ -50,6 +68,7 @@
             </div>
             <button class="btn-secondary" id="design-preset-save">Save Voice Design Preset</button>
           </div>
+          <div id="design-chips" class="design-chips"></div>
           <textarea id="design-instruct" placeholder="e.g. A calm, deep male voice with a slight British accent and authoritative tone.&#10;&#10;Or: Young female, high-pitched, enthusiastic and slightly breathless.&#10;&#10;Or: Speak in an incredulous tone, with a hint of panic creeping into your voice."></textarea>
           <table class="design-hints">
             <thead><tr><th>Dimension</th><th>Examples</th></tr></thead>

static/sections/s-magazine.html

@@ -159,6 +159,12 @@
              title="An EPUB 3 book whose text highlights while the audio plays (Media Overlays). Approved articles that already have audio.">
             <span class="mdi mdi-book-open-page-variant-outline" aria-hidden="true"></span> EPUB with audio
           </a>
+          <label class="muted" for="mag-prov-tags" title="Writes tags into the exported copy (stored audio is unchanged): synthetic speech, generator, version, date. No names or paths.">
+            <input type="checkbox" id="mag-prov-tags" checked onchange="magProvChanged()"> Mark as synthetic speech (tags)
+          </label>
+          <label class="muted" for="mag-prov-voice" title="Also write the voice name into the tags.">
+            <input type="checkbox" id="mag-prov-voice" onchange="magProvChanged()"> include voice name
+          </label>
           <span class="mag-audio-export-progress-wrap" hidden id="mag-audio-export-progress-wrap">
             <progress id="mag-audio-export-progress" max="1" value="0"></progress>
             <span id="mag-audio-export-count" class="muted"></span>

static/sections/s-reader.html

@@ -79,6 +79,7 @@
                 <div><strong>Paste text</strong><span>Plain text, Markdown, chapters, notes, or draft prose.</span></div>
               </div>
               <textarea id="reader-paste-text" class="reader-paste-text" rows="5" placeholder="Paste text here..." aria-label="Paste text to read aloud"></textarea>
+              <span class="s-hint tag-syntax-hint"><span>Inline tags (enable in Settings → General):</span> <code>[pause 500ms]</code> <code>[spell]USA[/spell]</code> <code>[slow]…[/slow]</code> <code>[fast]…[/fast]</code></span>
               <div class="reader-paste-actions">
                 <button class="btn-primary btn-sm" id="reader-paste-load" type="button"><span class="mdi mdi-text-box-check-outline"></span> Use pasted text</button>
               </div>

static/sections/s-settings.html

@@ -34,6 +34,14 @@
                 <textarea id="s-seed-finder-text" placeholder="Leave empty for language-specific defaults..." style="min-height:60px; font-family:inherit; resize:vertical;"></textarea>
                 <span class="s-hint">Custom test sentence used when opening the Seed Finder.</span>
               </div>
+              <label class="s-toggle-row" style="grid-column: 1 / -1">
+                <input type="checkbox" role="switch" id="s-inline-tags-enabled">
+                <div>
+                  <span class="s-toggle-title">Inline text tags</span>
+                  <span class="s-hint">Off by default. When on, tags shape the speech in Try It Out, Read Aloud, the speech API and audiobooks; streaming and magazine audio only remove them.</span>
+                  <span class="s-hint"><code>[pause 500ms]</code> <code>[spell]USA[/spell]</code> <code>[slow]…[/slow]</code> <code>[fast]…[/fast]</code></span>
+                </div>
+              </label>
             </div>
             <div class="s-page-actions">
               <button class="btn-primary s-save-btn">Save settings</button>

static/sections/s-studio.html

@@ -10,6 +10,7 @@
       <div class="gvo-tabs" id="gvo-tabs" role="tablist">
         <button class="gvo-tab active" data-src="direct" role="tab"><span class="mdi mdi-link-variant"></span> Direct sources <span class="gvo-tab-sub">scrape URLs</span></button>
         <button class="gvo-tab" data-src="fish" role="tab"><span class="mdi mdi-fishbowl-outline"></span> Fish.audio <span class="gvo-tab-sub">2M+ clonable</span></button>
+        <button class="gvo-tab" data-src="open" role="tab"><span class="mdi mdi-book-open-variant"></span> LibriVox &amp; Wikimedia <span class="gvo-tab-sub">open licences</span></button>
         <button class="gvo-tab" data-src="eleven" role="tab"><span class="gvo-eleven-logo">11</span> ElevenLabs <span class="gvo-tab-sub">12k shared</span></button>
       </div>
 
@@ -43,6 +44,21 @@
         </div>
       </div><!-- /tab-getvoices -->
 
+      <div class="card" id="open-sources-card" style="display:none">
+        <h2>LibriVox &amp; Wikimedia Commons</h2>
+        <p class="note">Official APIs only. Searching sends your query to librivox.org and archive.org (audio) or commons.wikimedia.org and upload.wikimedia.org; nothing else leaves this server. LibriVox recordings are public domain (USA); check the reader's licence on the LibriVox page. Wikimedia files carry their own licence; CC BY / CC BY-SA need attribution (saved with the voice). LibriVox searches match the start of a title; the language filter applies to LibriVox only. A search can take about 15 seconds.</p>
+        <form class="getvoices-toolbar" id="os-form">
+          <select id="os-source" aria-label="Source"><option value="librivox">LibriVox</option><option value="wikimedia">Wikimedia Commons</option></select>
+          <input type="search" id="os-q" maxlength="80" aria-label="Search term" placeholder="Title or search term" autocomplete="off" required>
+          <select id="os-lang" aria-label="Language (LibriVox)"><option value="">Language: any</option><option value="en">English</option><option value="de">German</option><option value="fr">French</option><option value="es">Spanish</option><option value="it">Italian</option><option value="nl">Dutch</option></select>
+          <label>Clip start (s) <input type="number" id="os-start" min="0" value="0" style="width:5em"></label>
+          <label>Length (s) <input type="number" id="os-len" min="3" max="120" value="30" style="width:5em"></label>
+          <button class="btn-primary" type="submit" id="os-search-btn">Search</button>
+        </form>
+        <p class="note" id="os-status" role="status" aria-live="polite"></p>
+        <div class="getvoices-grid" id="os-list"></div>
+      </div>
+
       <!-- ElevenLabs Voice Library Browser -->
       <div class="card el-browser" id="el-browser-card">
 

static/sections/s-tryout.html

@@ -42,6 +42,7 @@
               <div class="preview-match-title" id="preview-match-title">Reference voice</div>
               <div class="preview-match-detail" id="preview-match-detail"></div>
               <div class="preview-match-warning" id="preview-match-warning"></div>
+              <div class="preview-match-problems" id="preview-match-problems" role="status" aria-live="polite"></div>
               <div class="preview-match-actions">
                 <button class="btn-secondary" id="preview-ref-play" type="button">Play reference WAV</button>
                 <button class="btn-secondary" id="preview-ref-use-text" type="button">Use reference text</button>
@@ -60,6 +61,7 @@
           <h2><span class="mdi mdi-text-long"></span> Text to synthesize</h2>
           <div class="field">
             <textarea id="preview-text-area" placeholder="Enter the text you want to synthesize…" style="min-height:120px">Hello! This is a voice preview from TTS Voice Creator - Clone and Design.</textarea>
+            <span class="s-hint tag-syntax-hint"><span>Inline tags (enable in Settings → General):</span> <code>[pause 500ms]</code> <code>[spell]USA[/spell]</code> <code>[slow]…[/slow]</code> <code>[fast]…[/fast]</code></span>
           </div>
           <div class="field" style="margin-top:10px">
             <label style="display:flex;align-items:center;gap:8px">

static/sections/s-voices.html

@@ -136,6 +136,9 @@
             <div class="vl-toolbar">
               <button class="btn-secondary vl-tb-btn" id="refresh-voices-btn" title="Refresh voice list"><span class="mdi mdi-refresh"></span> Refresh</button>
               <button class="btn-secondary vl-tb-btn" id="sync-voice-folders-btn" title="Sync active/hidden folders">Sync</button>
+              <button class="btn-secondary vl-tb-btn vl-tb-bundle" id="export-voices-btn" title="Export the checked voices as .voice.zip bundles (backup / share)"><span class="mdi mdi-export" aria-hidden="true"></span> Export selected</button>
+              <button class="btn-secondary vl-tb-btn vl-tb-bundle" id="import-voices-btn" title="Import a .voice.zip bundle; an existing voice is never overwritten"><span class="mdi mdi-import" aria-hidden="true"></span> Import bundle</button>
+              <input type="file" id="import-voices-input" accept=".zip,application/zip" multiple hidden>
               <button class="btn-secondary vl-tb-btn" id="calculate-db-btn" title="Calculate dBFS">Calc dB</button>
               <button class="btn-secondary vl-tb-btn" id="benchmark-voices-btn" title="Benchmark TTS speed">Benchmark</button>
               <button class="btn-secondary vl-tb-btn" id="copy-active-voices-btn" title="Copy selected voices (or all active if none checked)">Copy selected</button>
@@ -229,6 +232,11 @@
                       <input type="text" id="lib-add-url" placeholder="Paste a direct MP3/WAV, YouTube, or Aiartes URL">
                       <button class="btn-primary" id="lib-add-url-btn">Download URL</button>
                     </div>
+                    <div class="btn-row">
+                      <button class="btn-secondary" id="lib-iso-btn" hidden>Remove background music</button>
+                      <button class="btn-secondary" id="lib-iso-toggle" hidden></button>
+                    </div>
+                    <div class="note" id="lib-iso-msg" role="status" aria-live="polite"></div>
                   </div>
                 </div>
                 <div class="lib-add-source-box lib-add-record-box">

static/style.css

@@ -2325,6 +2325,7 @@ code { background: var(--panel); border-radius: 4px; padding: 1px 5px; font-fami
   padding: 8px 10px 7px; border-bottom: 1px solid var(--border);
 }
 .vl-tb-btn { padding: 3px 8px !important; font-size: 12px !important; flex: 0 0 auto; }
+.vl-tb-bundle { min-height: 44px; min-width: 44px; }
 .vl-filters {
   display: flex; align-items: center; gap: 5px; flex-wrap: wrap;
   padding: 7px 10px; border-bottom: 1px solid var(--border);
@@ -6015,3 +6016,18 @@ html[data-mag-night] #toast.success { color: var(--green); } html[data-mag-night
 .lib-chars-scope-prompt p { margin:0 0 14px; color:var(--subtext); line-height:1.5; }
 .lib-chars-scope-actions { display:flex; flex-wrap:wrap; gap:8px; }
 #lib-chars-list { min-width:0; max-width:100%; }
+
+/* ── Voice provenance (source & consent) ─────────────────────────────────── */
+.vl-prov-badge { display: inline-flex; align-items: center; gap: 3px; font-size: 11px; font-weight: 600;
+  color: var(--warning, #b45309); border: 1px solid currentColor; border-radius: 10px; padding: 1px 7px; }
+.insp-prov-panel label { font-size: 12px; font-weight: 600; color: var(--subtext); }
+.insp-prov-input { width: 100%; min-height: 44px; font-size: 13px; padding: 8px 10px; font-family: var(--font);
+  border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text); }
+.insp-prov-input:focus-visible, .insp-prov-panel button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.insp-prov-panel button { min-height: 44px; min-width: 44px; }
+.insp-prov-rec { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
+
+/* LibriVox / Wikimedia Commons search card: 44px touch targets */
+#open-sources-card .getvoices-toolbar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+#open-sources-card button, #open-sources-card input, #open-sources-card select { min-height: 44px; }
+#open-sources-card .voice-source-actions a { display: inline-flex; align-items: center; min-height: 44px; }

tests/archetype-gallery.spec.js

@@ -0,0 +1,55 @@
+// @ts-check
+// Voice archetype gallery; every /api route is mocked (no live writes, no generation).
+const { test, expect } = require('@playwright/test');
+
+const items = Array.from({ length: 24 }, (_, i) => ({
+  id: 'v' + i, name_de: 'Stimme ' + i, name_en: 'Voice ' + i, instruct: 'Tiefe Stimme ' + i,
+  category: 'Narration & Story', language: 'German',
+  facets: { gender: i % 2 ? 'female' : 'male', age: 'elderly', pitch: 'low', accent: 'none', tone: 'warm' },
+}));
+
+test('gallery lazy-renders, filters, previews, uses and opens in design', async ({ page }) => {
+  const calls = [];
+  await page.route('**/api/archetypes**', route => {
+    const req = route.request(), url = new URL(req.url());
+    calls.push(req.method() + ' ' + url.pathname + url.search);
+    if (req.method() === 'GET') {
+      const g = url.searchParams.get('gender');
+      const rows = g ? items.filter(i => i.facets.gender === g) : items;
+      return route.fulfill({ json: { total: 30, offset: 0, limit: 24, items: rows, categories: ['Narration & Story'], cached: [] } });
+    }
+    if (url.pathname.endsWith('/preview')) return route.fulfill({ status: 502, json: { detail: 'mocked engine down' } });
+    return route.fulfill({ json: { voice_id: 'archetype_v0', created: true, instruct: 'Tiefe Stimme 0', language: 'German' } });
+  });
+  await page.route(/\/api\/(?!archetypes)/, route => route.request().method() === 'GET'
+    ? route.fulfill({ json: [] }) : route.fulfill({ json: { ok: true } }));
+  await page.route('**/static/dist/main.min.js*', r => r.abort());
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => typeof window.navTo === 'function', null, { timeout: 15_000 });
+  await page.waitForSelector('#app-skeleton', { state: 'detached', timeout: 15_000 });
+  await page.evaluate(() => window.navTo('s-design'));
+
+  await expect(page.locator('.arch-card')).toHaveCount(0); // lazy: nothing before opening
+  expect(calls).toEqual([]);
+  await page.locator('#archetype-gallery > summary').click();
+  await expect(page.locator('.arch-card')).toHaveCount(24);
+
+  await page.locator('#arch-chips [data-k="gender"][data-v="female"]').click();
+  await expect(page.locator('.arch-card')).toHaveCount(12);
+  await expect(page.locator('#arch-chips [data-v="female"]')).toHaveAttribute('aria-pressed', 'true');
+
+  const play = page.locator('.arch-play').first();
+  const box = await play.boundingBox();
+  expect(box && box.height).toBeGreaterThanOrEqual(44);
+  await play.click();
+  await expect(page.locator('#arch-status')).toContainText('mocked engine down');
+
+  await page.locator('.arch-fav').first().click();
+  const stored = await page.evaluate(() => localStorage.getItem('ttsvc-archetype-favs'));
+  expect(JSON.parse(stored || '[]')).toHaveLength(1);
+
+  await page.locator('.arch-use').first().click();
+  await expect(page.locator('.arch-open').first()).toBeVisible();
+  await page.locator('.arch-open').first().click();
+  await expect(page.locator('#design-instruct')).toHaveValue(/Tiefe Stimme/);
+});

tests/audiobook-emotion.spec.js

@@ -0,0 +1,65 @@
+// @ts-check
+// Audiobook emotion path: span-cast segment emotion -> script -> rehearser line -> instruct -> /api/tts-preview.
+// Routes are mocked; nothing here reaches the live TTS API.
+const { test, expect } = require('@playwright/test');
+
+const WAV = Buffer.from('UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=', 'base64');
+
+async function openReader(page) {
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForSelector('#app-skeleton', { state: 'detached', timeout: 15_000 });
+  await page.waitForFunction(() => typeof window.navTo === 'function', null, { timeout: 15_000 });
+  await page.evaluate(() => window.navTo('s-reader'));
+  await page.waitForFunction(() => typeof window.audiobookBuildScript === 'function' && typeof window.fetchTtsPreviewBlob === 'function', null, { timeout: 15_000 });
+}
+
+test('span-cast emotion reaches the tts-preview instruct for dialogue only; export shares the path', async ({ page }) => {
+  const bodies = [];
+  await page.route('**/api/tts-preview', route => { bodies.push(route.request().postDataJSON()); return route.fulfill({ status: 200, contentType: 'audio/wav', body: WAV }); });
+  await page.route('**/api/attribute-dialogue', route => route.fulfill({ json: { segments: [] } }));
+  await openReader(page);
+
+  // segments exactly as audiobook-cast-spans.js builds them (emotion from the LLM, narration always '')
+  const res = await page.evaluate(async () => {
+    const segs = [
+      { speaker: 'Narrator', type: 'narration', text: 'Der Zwerg schneuzte sich.', emotion: '', spanId: 'N0' },
+      { speaker: 'Linosch', type: 'dialogue', text: 'Na los!', emotion: 'wütend', spanId: 'D1' },
+      { speaker: 'Alrik', type: 'dialogue', text: 'Vielen Dank.', emotion: '', spanId: 'D2' },
+    ];
+    const { script, emotions } = window.audiobookBuildScript(segs);
+    rehState.lines = window.parseScript(script);
+    rehState.cast = { LINOSCH: { voice: 'DE_M_test', instruct: '' }, ALRIK: { voice: 'DE_M_test2', instruct: '' } };
+    rehState.narratorVoice = 'DE_F_narr';
+    let k = 0;
+    rehState.lines.forEach(l => { if (l.type === 'dialog') { const e = emotions[k++]; if (e) l.emotion = e; } });
+    const out = [];
+    for (const l of rehState.lines) {
+      const { voice, instruct } = window.audiobookLineVoice(l);
+      await window.fetchTtsPreviewBlob(voice, l.text, 'wav', instruct, 'voice_design');
+      out.push({ text: l.text, type: l.type, emotion: l.emotion || '' });
+    }
+    return { out, exportUsesIt: /audiobookLineVoice\(/.test(window.audiobookExport.toString()) };
+  });
+  expect(res.exportUsesIt).toBe(true);        // the export loop builds its instruct via the same helper
+  expect(bodies).toHaveLength(3);
+  const byText = Object.fromEntries(bodies.map(b => [b.text, b.instruct]));
+  expect(byText['Der Zwerg schneuzte sich.']).toBe('');
+  expect(byText['Na los!']).toContain('angry');          // German "wütend" translated to the English tag
+  expect(byText['Na los!']).not.toContain('wütend');
+  expect(byText['Vielen Dank.']).not.toMatch(/angry/);   // empty emotion: no emotion clause
+});
+
+test('changing the emotion changes the line cache key (no stale flat audio)', async ({ page }) => {
+  await openReader(page);
+  const keys = await page.evaluate(async () => {
+    window.rehState.cast = { LINOSCH: { voice: 'DE_M_test', instruct: '' } };
+    const k = async (emo) => {
+      const { instruct } = window.audiobookLineVoice({ type: 'dialog', speaker: 'LINOSCH', text: 'Na los!', emotion: emo });
+      return window._lineAudioCacheKey('Na los!', 'DE_M_test', instruct);
+    };
+    return [await k(''), await k('wütend'), await k('wütend'), await k('traurig')];
+  });
+  expect(keys[0]).not.toBe(keys[1]);
+  expect(keys[1]).toBe(keys[2]);
+  expect(keys[1]).not.toBe(keys[3]);
+});

tests/design-chips.spec.js

@@ -0,0 +1,30 @@
+// @ts-check
+// Design-prompt attribute chips; all /api routes are mocked (no live writes).
+const { test, expect } = require('@playwright/test');
+
+test('chips edit only their own phrase', async ({ page }) => {
+  await page.route('**/api/**', route => route.request().method() === 'GET'
+    ? route.fulfill({ json: [] }) : route.fulfill({ json: { ok: true } }));
+  await page.route('**/static/dist/main.min.js*', r => r.abort()); // test the source modules
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => typeof window.navTo === 'function', null, { timeout: 15_000 });
+  await page.waitForSelector('#app-skeleton', { state: 'detached', timeout: 15_000 });
+  await page.evaluate(() => window.navTo('s-design'));
+  const ta = page.locator('#design-instruct');
+  const chip = n => page.locator('#design-chips [data-phrase="' + n + '"]');
+  await ta.fill('Gravelly pirate captain');
+  await chip('male voice').click();
+  await chip('calm').focus();
+  await page.keyboard.press('Enter');
+  await expect(ta).toHaveValue('Gravelly pirate captain, male voice, calm');
+  await expect(chip('calm')).toHaveAttribute('aria-pressed', 'true');
+  await chip('female voice').click(); // exclusive group swaps only gender
+  await expect(ta).toHaveValue('Gravelly pirate captain, calm, female voice');
+  await chip('calm').click();
+  await expect(ta).toHaveValue('Gravelly pirate captain, female voice');
+  await expect(chip('male voice')).toHaveAttribute('aria-pressed', 'false');
+  const box = await chip('warm').boundingBox();
+  expect(box && box.height).toBeGreaterThanOrEqual(44);
+  await ta.fill('typed by hand, warm');
+  await expect(chip('warm')).toHaveAttribute('aria-pressed', 'true');
+});

tests/inline-tags.spec.js

@@ -0,0 +1,44 @@
+// @ts-check
+// Inline-tags settings switch + syntax hints (all /api routes mocked).
+const { test, expect } = require('@playwright/test');
+
+async function boot(page, lang) {
+  /** @type {any[]} */ const patches = [];
+  await page.route('**/api/**', route => route.request().method() === 'GET' ? route.fulfill({ json: {} }) : route.fulfill({ json: { ok: true } }));
+  await page.route('**/api/settings', route => {
+    if (route.request().method() === 'GET') return route.fulfill({ json: { inline_tags_enabled: false } });
+    patches.push(route.request().postDataJSON());
+    return route.fulfill({ json: { ok: true } });
+  });
+  await page.route('**/static/dist/main.min.js*', r => r.abort());
+  if (lang) await page.addInitScript(l => { try { localStorage.setItem('app-lang', l); } catch (e) {} }, lang);
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => typeof window.navTo === 'function', null, { timeout: 15_000 });
+  await page.waitForSelector('#app-skeleton', { state: 'detached', timeout: 15_000 });
+  return patches;
+}
+
+test('switch is labelled, keyboard-operable and saves the flag', async ({ page }) => {
+  const patches = await boot(page);
+  await page.evaluate(() => window.navSettingsCat('general'));
+  const sw = page.getByRole('switch', { name: /Inline text tags/ });
+  await expect(sw).not.toBeChecked();
+  await sw.focus();
+  await page.keyboard.press('Space');
+  await expect(sw).toBeChecked();
+  await expect.poll(() => patches.some(p => p && p.inline_tags_enabled === true)).toBe(true);
+});
+
+test('syntax hint sits under the Try It Out text box', async ({ page }) => {
+  await boot(page);
+  await page.evaluate(() => window.navTo('s-tryout'));
+  await expect(page.locator('#preview-text-area ~ .tag-syntax-hint')).toContainText('[pause 500ms]');
+});
+
+test('German labels', async ({ page }) => {
+  await boot(page, 'de');
+  await page.evaluate(() => window.navSettingsCat('general'));
+  await expect(page.getByText('Inline-Texttags')).toBeVisible();
+  await page.evaluate(() => window.navTo('s-tryout'));
+  await expect(page.locator('#preview-text-area ~ .tag-syntax-hint')).toContainText('Inline-Tags');
+});

tests/magazine.spec.js

@@ -122,6 +122,8 @@ async function mockBackend(page, { articleStatus = 'detected', hasAudio = false,
   await page.route('**/api/voices*', route => route.fulfill({
     json: [{ id: 'smoke_voice', name: 'Smoke voice', enabled: true, tag: 'Magazine' }],
   }));
+  // The export-provenance default is read and saved through /api/settings; never let a spec reach the live one.
+  await page.route('**/api/settings', route => route.fulfill({ json: { export_provenance_default: true } }));
 }
 
 test.describe('Magazine reader', () => {
@@ -1610,7 +1612,13 @@ test('the EPUB link appears only when an approved article has audio', async ({ p
   await page.locator('#mag-library-list .mag-card').first().click();
   const link = page.getByRole('link', { name: /EPUB with audio/ });
   await expect(link).toBeVisible();
-  await expect(link).toHaveAttribute('href', `/api/magazine/${DOC_ID}/epub`);
+  await expect(link).toHaveAttribute('href', `/api/magazine/${DOC_ID}/epub?provenance=1`);
+  // Provenance tags: on by default, voice opt-in, choice is carried by the export links and saved as the default.
+  await expect(page.locator('#mag-prov-tags')).toBeChecked();
+  await page.locator('#mag-prov-voice').evaluate(el => el.click());
+  await expect(link).toHaveAttribute('href', `/api/magazine/${DOC_ID}/epub?provenance=1&voice=1`);
+  await page.locator('#mag-prov-tags').evaluate(el => el.click());
+  await expect(page.locator('#mag-audio-zip-link')).toHaveAttribute('href', `/api/magazine/${DOC_ID}/audio.zip?provenance=0&voice=1`);
 });
 
 test('no EPUB link for an approved article without audio', async ({ page }) => {
@@ -1791,6 +1799,8 @@ test.describe('Share link and deep link into driving mode', () => {
     const bad = `/#s-magazine?doc=${DOC_ID}&article=%22%3E%3Cimg%20src%3Dx%20onerror%3Dwindow.__xss%3D1%3E&mode=drive`;
     await openLink(page, bad);
     await navTo(page, 's-magazine');
+    // The magazine module loads lazily: wait for it, so the checks below run against the loaded parser.
+    await page.waitForFunction(() => typeof window.magParseDeepLink === 'function', null, { timeout: 15_000 });
     await expect(page.locator('#mag-driving')).toBeHidden();
     expect(await page.evaluate(() => window.__xss)).toBeUndefined();
     const { parse } = await page.evaluate(() => ({ parse: [

tests/seed-autopick.spec.js

@@ -0,0 +1,39 @@
+// @ts-check
+// Seed Finder "Auto-pick best": all /api routes mocked, nothing is ever saved or generated for real.
+const { test, expect } = require('@playwright/test');
+
+const WAV = 'UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA='; // empty 16-bit wav
+
+test('auto-pick highlights the winner; saving needs an explicit click', async ({ page }) => {
+  const saves = [];
+  const cand = (seed, score) => ({ seed, score, accuracy: 90, loudness_score: 80, problems_score: 100, problems: [], audio_b64: WAV, media_type: 'audio/wav' });
+  await page.route('**/api/**', route => route.request().method() === 'GET'
+    ? route.fulfill({ json: [] }) : route.fulfill({ json: { ok: true } }));
+  await page.route('**/api/seed-autopick', route => route.fulfill({ json: {
+    winner: 2, degraded: true, cancelled: false, stt: { available: false, note: 'down' },
+    candidates: [cand(1, 60), cand(2, 88), { seed: 3, error: 'boom' }] } }));
+  await page.route('**/api/tts-voice-seed', route => { saves.push(route.request().postData()); route.fulfill({ json: { ok: true } }); });
+  await page.route('**/static/dist/main.min.js*', r => r.abort());
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => typeof window.attachSeedFinder === 'function', null, { timeout: 15_000 });
+  await page.evaluate(() => {
+    const host = document.createElement('div'); host.id = 'sf-host'; document.body.prepend(host);
+    window.attachSeedFinder('DE_test', host);
+    host.querySelector('.seed-finder-group').classList.add('open');
+  });
+  const btn = page.getByRole('button', { name: /Auto-pick best/ });
+  await btn.focus();
+  await page.keyboard.press('Enter');
+  const status = page.locator('.seed-finder-autopick-status');
+  await expect(status).toHaveAttribute('aria-live', 'polite');
+  await expect(status).toContainText('Best seed: 2');
+  await expect(status).toContainText('level and audio problems only');
+  await expect(page.locator('.sfr-winner')).toContainText('Best');
+  await expect(page.locator('.sfr-winner')).toContainText('score 88/100');
+  await expect(page.locator('.seed-finder-result-error')).toContainText('boom');
+  expect(saves).toHaveLength(0);
+  await page.locator('.sfr-winner .sfr-use-btn').click();
+  await expect(page.locator('.sfr-winner .sfr-saved')).toContainText('Saved');
+  expect(saves).toHaveLength(1);
+  expect(JSON.parse(saves[0])).toEqual({ voice: 'DE_test', seed: 2 });
+});

tests/test_audio_problems.py

@@ -0,0 +1,70 @@
+"""audio_problems: silence gap, clipped burst, level jump, clean signal."""
+import sys
+from pathlib import Path
+import unittest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from pydub import AudioSegment
+from pydub.generators import Sine, Square
+
+from core.audio import audio_problems
+
+SR = 24000
+
+
+def tone(ms, gain=-20):
+    return Sine(300, sample_rate=SR).to_audio_segment(ms).apply_gain(gain)
+
+
+def kinds(seg):
+    return {p["kind"] for p in audio_problems(seg)}
+
+
+class AudioProblemTests(unittest.TestCase):
+    def test_clean(self):
+        self.assertEqual(audio_problems(tone(4000, -18).set_frame_rate(SR)), [])
+
+    def test_silence_gap(self):
+        seg = tone(2000) + AudioSegment.silent(2000, frame_rate=SR) + tone(2000)
+        p = [x for x in audio_problems(seg) if x["kind"] == "silence"]
+        self.assertEqual(len(p), 1)
+        self.assertAlmostEqual(p[0]["start_s"], 2.0, delta=0.1)
+
+    def test_edge_silence_ignored(self):
+        seg = AudioSegment.silent(3000, frame_rate=SR) + tone(2000) + AudioSegment.silent(3000, frame_rate=SR)
+        self.assertNotIn("silence", kinds(seg))
+
+    def test_clipping(self):
+        burst = Square(300, sample_rate=SR).to_audio_segment(400).apply_gain(+10)
+        seg = tone(2000) + burst + tone(2000)
+        p = [x for x in audio_problems(seg) if x["kind"] == "clipping"]
+        self.assertTrue(p)
+        self.assertAlmostEqual(p[0]["start_s"], 2.0, delta=0.1)
+
+    def test_level_jump(self):
+        seg = tone(2000, -40) + tone(2000, -10)
+        p = [x for x in audio_problems(seg) if x["kind"] == "level_jump"]
+        self.assertEqual(len(p), 1)
+        self.assertAlmostEqual(p[0]["start_s"], 2.0, delta=0.1)
+
+
+class VoiceHealthTests(unittest.TestCase):
+    def test_analyze_and_stored(self):
+        import tempfile
+        from core.voice import _voice_health, _validate_voice_meta
+        with tempfile.TemporaryDirectory() as d:
+            wav = Path(d) / "EN_F_test.wav"
+            (tone(2000) + AudioSegment.silent(2000, frame_rate=SR) + tone(2000)).export(str(wav), format="wav")
+            h = _voice_health(wav, meta={}, transcript="hi", duration=6.0, analyze=True)
+            self.assertEqual([p["kind"] for p in h["problems"]], ["silence"])
+            self.assertIn("Long silence in reference audio", h["warnings"])
+            stored = _voice_health(wav, meta={"audio_problems": h["problems"]}, transcript="hi", duration=6.0)
+            self.assertEqual(stored["problems"], h["problems"])
+            self.assertEqual(_voice_health(wav, meta={}, transcript="hi", duration=6.0)["problems"], [])
+            with self.assertRaises(ValueError):
+                _validate_voice_meta({"audio_problems": "x"})
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_epub_export.py

@@ -279,6 +279,13 @@ class EndpointTests(unittest.TestCase):
             self.assertEqual(z.namelist()[0], "mimetype")
             self.assertIn("exact", z.read("OEBPS/content.opf").decode())
 
+    def test_provenance_tag_failure_ships_untagged_file(self):
+        from unittest import mock
+        self.seed()
+        with mock.patch("core.export_provenance.apply_tags", side_effect=RuntimeError("tagging failed")):
+            r = self.client.get(f"/api/magazine/{self.doc}/epub?provenance=1")
+        self.assertEqual(r.status_code, 200, r.text[:200])
+
     def test_unapproved_or_silent_articles_are_not_packaged(self):
         self.seed(approved=False)
         self.assertEqual(self.client.get(f"/api/magazine/{self.doc}/epub").status_code, 404)

tests/test_guided_installer.py

@@ -0,0 +1,31 @@
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+try:
+    from guided_installer import run_command
+except ImportError:  # no tkinter on this host
+    run_command = None
+
+
+@unittest.skipIf(run_command is None, "tkinter unavailable")
+class RunCommandTest(unittest.TestCase):
+    def test_success_logs_output(self):
+        out = []
+        self.assertTrue(run_command([sys.executable, "-c", "print('hi')"], out.append))
+        self.assertIn("hi", "".join(out))
+
+    def test_nonzero_exit(self):
+        out = []
+        self.assertFalse(run_command([sys.executable, "-c", "raise SystemExit(3)"], out.append))
+        self.assertIn("exited with 3", out[-1])
+
+    def test_missing_binary(self):
+        out = []
+        self.assertFalse(run_command(["/nonexistent-binary-xyz"], out.append))
+        self.assertTrue(out[0].startswith("Failed:"))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_inline_tags_paths.py

@@ -0,0 +1,137 @@
+"""Inline tags in the generate, /v1/audio/speech, conversation and magazine paths (fake synth, no network)."""
+import io
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="itp-cfg-"))   # routes.* would otherwise mkdir /home/app
+
+from pydub import AudioSegment
+from pydub.generators import Sine
+
+from core import ssml_lite as S
+
+SPOKEN: list[str] = []
+
+
+def fake_synth(text, *_a, **_k):
+    SPOKEN.append(text)
+    buf = io.BytesIO()
+    Sine(440).to_audio_segment(duration=10 * len(text)).export(buf, format="wav")
+    return buf.getvalue(), "audio/wav"
+
+
+def wav_ms(data: bytes) -> int:
+    return len(AudioSegment.from_file(io.BytesIO(data), format="wav"))
+
+
+class HelperTests(unittest.TestCase):
+    def setUp(self):
+        SPOKEN.clear()
+
+    def test_flag_off_passes_text_through(self):
+        S.render_with_tags("A [pause 1s] B", fake_synth, "en", False)
+        self.assertEqual(SPOKEN, ["A [pause 1s] B"])
+
+    def test_flag_on_renders_pause_and_never_speaks_tags(self):
+        audio, _ = S.render_with_tags("Aaaa [pause 1s] Bbbb [laughs]", fake_synth, "en", True)
+        self.assertFalse(any("[" in t for t in SPOKEN))
+        self.assertGreaterEqual(wav_ms(audio), 1000 + 40 + 40 - 5)
+
+
+class RouteTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+        import routes.tts as T
+        cls.T = T
+        app = FastAPI()
+        app.include_router(T.router)
+        cls.client = TestClient(app)
+
+    def setUp(self):
+        SPOKEN.clear()
+
+    def _post(self, url, body, flag):
+        T = self.T
+        settings = {"inline_tags_enabled": flag}
+        with mock.patch.object(T, "_load_settings", return_value=settings), \
+             mock.patch.object(T, "_preview_request_audio", side_effect=fake_synth), \
+             mock.patch.object(T, "_tts_request_audio", side_effect=fake_synth), \
+             mock.patch.object(T, "_resolve_tts_route", side_effect=lambda app, v, t, l: (v, None)), \
+             mock.patch.object(T, "_route_backend", return_value="customvoice"), \
+             mock.patch.object(T, "_apply_route_sounds", side_effect=lambda a, m, r, s: (a, m, [])):
+            return self.client.post(url, json=body)
+
+    def test_speech_proxy_flag_on_has_pause_and_no_tag_text(self):
+        r = self._post("/v1/audio/speech", {"input": "Aaaa [pause 1s] Bbbb", "voice": "v", "response_format": "wav"}, True)
+        self.assertEqual(r.status_code, 200, r.text)
+        self.assertFalse(any("[" in t for t in SPOKEN), SPOKEN)
+        self.assertGreaterEqual(wav_ms(r.content), 1000)
+
+    def test_speech_proxy_flag_off_unchanged(self):
+        r = self._post("/v1/audio/speech", {"input": "Aaaa [pause 1s] Bbbb", "voice": "v", "response_format": "wav"}, False)
+        self.assertEqual(r.status_code, 200, r.text)
+        self.assertEqual(SPOKEN, ["Aaaa [pause 1s] Bbbb"])
+
+    def test_tts_preview_flag_on(self):
+        r = self._post("/api/tts-preview", {"text": "Aaaa [pause 500ms] Bbbb", "voice": "v", "backend": "customvoice"}, True)
+        self.assertEqual(r.status_code, 200, r.text)
+        self.assertFalse(any("[" in t for t in SPOKEN), SPOKEN)
+        self.assertGreaterEqual(wav_ms(r.content), 500)
+
+
+class MagazineTests(unittest.TestCase):
+    """Magazine path strips tags (never speaks them) so recorded timings equal the audio actually joined."""
+
+    def _render(self, flag):
+        import core.magazine as M
+        SPOKEN.clear()
+        blocks = [{"text": "First line here. [pause 5s] Second line here.", "type": "paragraph"}]
+        with tempfile.TemporaryDirectory() as d, \
+             mock.patch.object(M, "article_text", return_value=blocks), \
+             mock.patch("core.tts_helpers._tts_request_audio", side_effect=fake_synth), \
+             mock.patch.object(M, "tag_article_mp3"):
+            doc = Path(d)
+            try:
+                out = M.synthesize_article_audio(doc, {"id": "a1"}, {}, "v", {"inline_tags_enabled": flag})
+            except Exception as e:                                  # mp3 export needs ffmpeg
+                self.skipTest(f"magazine render unavailable here: {e}")
+            t = M.read_audio_timings(out)
+            return t, wav_ms_of(out)
+
+    def test_flag_on_strips_tags_and_timings_match_audio(self):
+        t, total = self._render(True)
+        self.assertFalse(any("[" in s or "pause" in s for s in SPOKEN), SPOKEN)
+        self.assertLess(abs(t["duration_ms"] - total), 150)         # mp3 frame padding only; no 5 s hole
+        self.assertLess(t["duration_ms"], 2000)
+
+    def test_flag_off_keeps_legacy_text(self):
+        self._render(False)
+        self.assertTrue(any("[pause 5s]" in s for s in SPOKEN))
+
+
+def wav_ms_of(path):
+    return len(AudioSegment.from_file(path))
+
+
+class ConversationTests(unittest.TestCase):
+    def test_chat_reply_chunk_strips_tags_when_on(self):
+        import asyncio
+        import routes.conversation as C
+        SPOKEN.clear()
+
+        async def both():
+            for flag in (True, False):
+                with mock.patch.object(C, "_preview_request_audio", side_effect=fake_synth):
+                    await C._make_tts_task("Hello [pause 1s] there.", "v", {"inline_tags_enabled": flag}, "customvoice", None)
+                await asyncio.sleep(0.05)
+        asyncio.run(both())
+        self.assertEqual(SPOKEN, ["Hello there.", "Hello [pause 1s] there."])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_magazine.py

@@ -819,6 +819,69 @@ class InterviewVoiceTests(unittest.TestCase):
         self.assertTrue(all(s["speaker"] is None for s in interview_tts_segments(blocks)))
 
 
+class InterviewJournalistTests(unittest.TestCase):
+    @staticmethod
+    def _ct_blocks(label="c't"):
+        return [
+            {"text": "Interview mit Michael Gerlich", "type": "heading"},
+            {"text": "Einleitung zum Gespräch.", "type": "body"},
+            {"text": f"{label}: Was ist kognitives Offloading?"},
+            {"text": "Michael Gerlich: Wir lagern Denken an KI aus."},
+            {"text": "Ein zweiter Absatz der Antwort ohne Label."},
+            {"text": f"{label}: Ist das gefährlich?"},
+            {"text": "Michael Gerlich: Teilweise."},
+        ]
+
+    def test_ct_variants_map_journalist_to_narrator_and_guest_to_second_voice(self):
+        for label in ("c't", "c’t", "ct", "C't", "Cc't"):
+            with self.subTest(label=label):
+                segs = interview_tts_segments(self._ct_blocks(label))
+                self.assertEqual([s["slot"] for s in segs], [0, 0, 0, 1, 1, 0, 1])
+                self.assertEqual(segs[2]["text"], "Was ist kognitives Offloading?")
+                self.assertEqual(segs[4]["speaker"], "Michael Gerlich")
+                self.assertEqual(segs[4]["text"], "Ein zweiter Absatz der Antwort ohne Label.")
+                self.assertIsNone(segs[0]["speaker"])
+
+    def test_multiple_guests_all_use_second_voice(self):
+        blocks = [{"text": "c't: Frage eins?"}, {"text": "Anna Meyer: A."}, {"text": "c't: Frage zwei?"},
+                  {"text": "Anna Meyer: B."}, {"text": "c't: Frage drei?"}, {"text": "Tom Schulz: C."},
+                  {"text": "c't: Frage vier?"}, {"text": "Tom Schulz: D."}]
+        self.assertEqual([s["slot"] for s in interview_tts_segments(blocks)], [0, 1, 0, 1, 0, 1, 0, 1])
+
+    def test_two_plain_labels_keep_first_appearance_rule(self):
+        blocks = [{"text": "Zed Alpha: Eins."}, {"text": "Bob Beta: Zwei."}, {"text": "Zed Alpha: Drei."},
+                  {"text": "Bob Beta: Vier."}]
+        self.assertEqual([s["slot"] for s in interview_tts_segments(blocks)], [0, 1, 0, 1])
+
+    def test_single_colon_labels_are_not_speakers_and_keep_their_text(self):
+        blocks = [{"text": "Hinweis: Das gilt nur für Version 2."}, {"text": "Fazit: Es lohnt sich."},
+                  {"text": "Hinweis: Noch einmal."}]
+        segs = interview_tts_segments(blocks)
+        self.assertTrue(all(s["speaker"] is None and s["slot"] == 0 for s in segs))
+        self.assertEqual(segs[0]["text"], "Hinweis: Das gilt nur für Version 2.")
+
+    def test_one_journalist_label_alone_is_not_enough(self):
+        segs = interview_tts_segments([{"text": "c't: Einmal."}, {"text": "Text."}])
+        self.assertTrue(all(s["speaker"] is None for s in segs))
+
+    def test_timings_record_voice_and_speaker_and_stay_backward_compatible(self):
+        import tempfile
+        import json
+        from pathlib import Path
+        from core.magazine import write_audio_timings
+        segs = interview_tts_segments(self._ct_blocks())
+        for s in segs:
+            s["voice"] = "B" if s["slot"] else "A"
+        with tempfile.TemporaryDirectory() as d:
+            mp3 = Path(d) / "x.mp3"
+            write_audio_timings(mp3, segs, list(range(len(segs))), [(i, i + 1) for i in range(len(segs))], interview=True)
+            rec = json.loads((Path(d) / "x.timings.json").read_text())
+        self.assertEqual(rec["version"], 1)
+        self.assertEqual({s["voice"] for s in rec["segments"]}, {"A", "B"})
+        self.assertTrue(all("chars" in s and "times" in s for s in rec["segments"]))
+        self.assertEqual(rec["segments"][3]["speaker"], "Michael Gerlich")
+
+
 class OcrQualityScoreTests(unittest.TestCase):
     """Grounded in real output from both OCR paths on a scanned c't magazine.
 

tests/test_magazine_rotation.py

@@ -408,7 +408,7 @@ class EndpointTests(unittest.TestCase):
         async def fake_task(coro):
             created.append(coro)
         with mock.patch.object(self.routes, "_load_settings", return_value=settings), \
-                mock.patch.object(self.routes.asyncio, "create_task", side_effect=lambda c: (c.close(), created.append(1))[1]):
+                mock.patch.object(self.routes.asyncio, "create_task", side_effect=lambda c: (c.close(), created.append(1), mock.MagicMock())[2]):
             return self.client.post(f"/api/magazine/{self.doc}/pages/{page}/rotate", json={"degrees": degrees}), created
 
     def test_a_valid_request_starts_a_job(self):

tests/test_seed_autopick.py

@@ -0,0 +1,111 @@
+"""Seed auto-pick: scoring, selection and the endpoint with all I/O mocked."""
+import asyncio
+import os
+import tempfile
+import io
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="ttvc-autopick-test-"))
+
+from fastapi import HTTPException
+from pydub.generators import Sine
+
+from core import seed_score as sc
+import routes.tts as tts
+
+
+def wav(gain=-20, gap=False):
+    seg = Sine(300, sample_rate=24000).to_audio_segment(1500).apply_gain(gain)
+    if gap:
+        seg = seg + seg.__class__.silent(2000, 24000) + seg
+    buf = io.BytesIO()
+    seg.export(buf, format="wav")
+    return buf.getvalue()
+
+
+class FakeReq:
+    def __init__(self, body, disconnect_after=None):
+        self.body, self.calls, self.after = body, 0, disconnect_after
+
+    async def json(self):
+        return self.body
+
+    async def is_disconnected(self):
+        self.calls += 1
+        return self.after is not None and self.calls > self.after
+
+
+def run(req, gen, stt):
+    with mock.patch.object(tts, "_seed_finder_request_audio", side_effect=gen), \
+         mock.patch.object(tts, "_load_settings", return_value={}), \
+         mock.patch("routes.stt._transcribe_audio", side_effect=stt):
+        return asyncio.run(tts.seed_autopick(req))
+
+
+class ScoringTests(unittest.TestCase):
+    def test_combine_and_degraded(self):
+        self.assertEqual(sc.combine(100, 100, 100), 100.0)
+        self.assertEqual(sc.combine(None, 100, 50), 70.0)  # (0.2*100+0.3*50)/0.5
+        self.assertLess(sc.loudness_score({"dbfs": -5, "peak_dbfs": 0, "target_dbfs": -20}), 20)
+        self.assertEqual(sc.loudness_score({"dbfs": None}), 0.0)
+        self.assertEqual(sc.problems_score([{"kind": "silence"}] * 5), 0.0)
+
+    def test_winner_tiebreak_and_errors(self):
+        c = [{"seed": 3, "score": 80}, {"seed": 2, "score": 80}, {"seed": 1, "error": "x"}]
+        self.assertEqual(sc.pick_winner(c), 2)
+        self.assertIsNone(sc.pick_winner([{"seed": 1, "error": "x"}]))
+
+    def test_seed_list_bounds(self):
+        self.assertEqual(sc.seed_list(None, None), list(range(1, 9)))
+        self.assertEqual(sc.seed_list([5, 5, 7], None), [5, 7])
+        for bad in ((None, 17), (None, 0), ([], None), ([-1], None), (list(range(17)), None), (["a"], None)):
+            with self.assertRaises(ValueError):
+                sc.seed_list(*bad)
+
+
+class EndpointTests(unittest.TestCase):
+    body = {"voice": "DE_x", "text": "hallo welt", "seeds": [1, 2, 3]}
+
+    def test_picks_best_and_never_saves(self):
+        audios = {1: wav(-20, gap=True), 2: wav(-20), 3: wav(-3)}
+        gen = lambda text, voice, settings, seed: (audios[seed], "audio/wav")
+        stt = lambda *a, **k: ("hallo welt", "x")
+        out = run(FakeReq(self.body), gen, stt)
+        self.assertEqual(out["winner"], 2)
+        self.assertFalse(out["degraded"])
+        self.assertEqual([c["seed"] for c in out["candidates"]], [1, 2, 3])
+        self.assertTrue(all("audio_b64" in c and "problems" in c for c in out["candidates"]))
+        self.assertGreater(out["candidates"][1]["score"], out["candidates"][0]["score"])
+
+    def test_stt_down_degrades(self):
+        def stt(*a, **k):
+            raise RuntimeError("no stt")
+        out = run(FakeReq(self.body), lambda *a: (wav(), "audio/wav"), stt)
+        self.assertTrue(out["degraded"])
+        self.assertIn("no stt", out["stt"]["note"])
+        self.assertIsNotNone(out["winner"])
+        self.assertIsNone(out["candidates"][0]["accuracy"])
+
+    def test_error_candidate_and_cancel(self):
+        def gen(text, voice, settings, seed):
+            if seed == 1:
+                raise RuntimeError("boom")
+            return wav(), "audio/wav"
+        out = run(FakeReq(self.body, disconnect_after=2), gen, lambda *a, **k: ("hallo welt", "x"))
+        self.assertEqual(out["candidates"][0]["error"], "boom")
+        self.assertEqual(out["winner"], 2)
+        self.assertTrue(out["cancelled"])
+        self.assertEqual(len(out["candidates"]), 2)
+
+    def test_invalid_input(self):
+        for body in ({"voice": "", "text": "a"}, {"voice": "v", "text": " "}, {"voice": "v", "text": "a", "count": 99}):
+            with self.assertRaises(HTTPException):
+                run(FakeReq(body), lambda *a: (wav(), "audio/wav"), lambda *a, **k: ("", ""))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_ssml_lite.py

@@ -0,0 +1,84 @@
+import io
+import unittest
+
+from pydub import AudioSegment
+from pydub.generators import Sine
+
+from core import ssml_lite as S
+from core.magazine import split_sentences_for_tts
+
+
+def texts(segs):
+    return [(s["text"], s["speed"], s["pause_ms"]) for s in segs]
+
+
+class ParseTests(unittest.TestCase):
+    def test_plain_text_is_one_segment(self):
+        self.assertEqual(texts(S.parse("Hello there.")), [("Hello there.", 1.0, 0)])
+
+    def test_pause_units_and_split(self):
+        self.assertEqual(texts(S.parse("A [pause 500ms] B [pause 1.2s] C")),
+                         [("A ", 1.0, 0), ("", 1.0, 500), (" B ", 1.0, 0), ("", 1.0, 1200), (" C", 1.0, 0)])
+
+    def test_pause_caps(self):
+        self.assertEqual(S.parse("A[pause 99s]B")[1]["pause_ms"], 10_000)
+        many = "A" + "[pause 10s]B" * 10
+        self.assertEqual(sum(s["pause_ms"] for s in S.parse(many)), 60_000)
+
+    def test_bad_pause_is_stripped_not_spoken(self):
+        self.assertEqual(S.plain_text("A [pause soon] B"), "A B")
+
+    def test_speed_nesting_innermost_wins(self):
+        segs = S.parse("a [slow]b [fast]c[/fast] d[/slow] e")
+        self.assertEqual([(s["text"].strip(), s["speed"]) for s in segs],
+                         [("a", 1.0), ("b", 0.85), ("c", 1.15), ("d", 0.85), ("e", 1.0)])
+
+    def test_unclosed_runs_to_paragraph_end(self):
+        segs = S.parse("[slow]one\n\ntwo")
+        self.assertEqual([(s["text"].strip(), s["speed"]) for s in segs], [("one", 0.85), ("two", 1.0)])
+
+    def test_unknown_control_tags_stripped_citations_kept(self):
+        self.assertEqual(S.plain_text("Hi [laugh] there [/emphasis] [sic] cited [1]."), "Hi there [sic] cited [1].")
+        self.assertNotIn("[", S.plain_text("[whisper]psst[/whisper]"))
+
+    def test_spell_english_and_german(self):
+        self.assertEqual(S.plain_text("[spell]USA[/spell]", "en"), "U S A")
+        self.assertEqual(S.plain_text("[spell]USA[/spell]", "de"), "Uh Ess Ah")
+        self.assertEqual(S.plain_text("[spell]ZDF[/spell] Nachrichten über Straße"), "Zett De Eff Nachrichten über Straße")
+        self.assertEqual(S.plain_text("[spell]ab", "en"), "a b")
+
+    def test_segments_never_contain_tags_and_chunker_keeps_them_whole(self):
+        text = "[slow]First. Second sentence here.[/slow] Third. [pause 1s] Fourth."
+        for seg in S.parse(text):
+            self.assertNotIn("[", seg["text"])
+        slow = [s for s in S.parse(text) if s["speed"] != 1.0][0]
+        self.assertEqual(slow["speed"], 0.85)
+        self.assertIn("First.", slow["text"])
+        self.assertIn("Second", slow["text"])
+        self.assertGreaterEqual(len(split_sentences_for_tts(slow["text"])), 1)
+
+    def test_has_tags(self):
+        self.assertTrue(S.has_tags("a [pause 1s]"))
+        self.assertFalse(S.has_tags("see [1] and [sic]"))
+
+
+class RenderTests(unittest.TestCase):
+    def test_render_joins_with_silence_and_stretch(self):
+        tone = Sine(440).to_audio_segment(duration=1000).set_frame_rate(24000)
+        buf = io.BytesIO()
+        tone.export(buf, format="wav")
+        wav = buf.getvalue()
+
+        def tempo(b, speed):                       # fake: just trims, proves it was called with the factor
+            tempo.calls.append(speed)
+            return b
+        tempo.calls = []
+        out, media = S.render("A [pause 500ms] [slow]B[/slow]", lambda t: (wav, "audio/wav"), tempo, "en")
+        dur = len(AudioSegment.from_file(io.BytesIO(out), format="wav"))
+        self.assertEqual(media, "audio/wav")
+        self.assertEqual(tempo.calls, [0.85])
+        self.assertAlmostEqual(dur, 2500, delta=30)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tasks.py

@@ -0,0 +1,40 @@
+import asyncio
+import gc
+import logging
+import unittest
+
+from core import tasks
+
+
+class SpawnTests(unittest.IsolatedAsyncioTestCase):
+    async def test_survives_gc_and_set_emptied(self):
+        base = len(tasks._BACKGROUND)  # other tests may leave tasks from closed loops
+        done = asyncio.Event()
+
+        async def work():
+            await asyncio.sleep(0.01)
+            done.set()
+
+        tasks.spawn(work())
+        gc.collect()
+        self.assertEqual(len(tasks._BACKGROUND), base + 1)
+        await asyncio.wait_for(done.wait(), 1)
+        await asyncio.sleep(0)
+        self.assertEqual(len(tasks._BACKGROUND), base)
+
+    async def test_exception_logged_without_message(self):
+        base = len(tasks._BACKGROUND)
+
+        async def boom():
+            raise ValueError("secret-token")
+
+        with self.assertLogs("core.tasks", "ERROR") as cm:
+            tasks.spawn(boom())
+            await asyncio.sleep(0.02)
+        self.assertIn("ValueError", cm.output[0])
+        self.assertNotIn("secret-token", cm.output[0])
+        self.assertEqual(len(tasks._BACKGROUND), base)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tts_instruct_payload.py

@@ -0,0 +1,29 @@
+"""Emotion -> instruct passthrough in the TTS payload builders (core/tts_helpers.py)."""
+import os
+import tempfile
+import unittest
+
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="tip-cfg-"))
+
+from core.tts_helpers import _tts_request_config, _tts_stream_request_config
+
+S = {"tts_url": "http://localhost:9999", "tts_backend": "openai"}
+
+
+class InstructPayloadTests(unittest.TestCase):
+    def test_instruct_is_sent_stripped(self):
+        _, p, _ = _tts_request_config("Hi", "DE_M_x", S, instruct="  Speak in an angry tone.  ")
+        self.assertEqual(p["instruct"], "Speak in an angry tone.")
+        _, p, _ = _tts_stream_request_config("Hi", "DE_M_x", S, "  angry  ")
+        self.assertEqual(p["instruct"], "angry")
+
+    def test_empty_instruct_is_omitted(self):
+        for ins in ("", "   "):
+            _, p, _ = _tts_request_config("Hi", "DE_M_x", S, instruct=ins)
+            self.assertNotIn("instruct", p)
+            _, p, _ = _tts_stream_request_config("Hi", "DE_M_x", S, ins)
+            self.assertNotIn("instruct", p)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_vocal_isolation.py

@@ -0,0 +1,119 @@
+"""vocal isolation: flag off, unavailable, success, timeout, cleanup (Demucs mocked)."""
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from pydub import AudioSegment
+from pydub.generators import Sine
+
+from core import vocal_isolation as vi
+from core.registry import TEMP_DIR
+
+
+def wav(path, ms=1000):
+    Sine(300).to_audio_segment(ms).export(str(path), format="wav")
+    return path
+
+
+class FakeProc:
+    """Stands in for demucs: writes <out>/htdemucs/<stem>/vocals.wav, then exits."""
+    def __init__(self, args, **kw):
+        self.never_ends = FakeProc.never_ends
+        out = Path(args[args.index("-o") + 1])
+        if not self.never_ends and FakeProc.write:
+            d = out / "htdemucs" / Path(args[-1]).stem
+            d.mkdir(parents=True)
+            wav(d / "vocals.wav")
+        self.returncode = None if self.never_ends else FakeProc.rc
+    never_ends = False
+    write = True
+    rc = 0
+    def poll(self):
+        return self.returncode
+    def kill(self):
+        self.returncode = -9
+    def wait(self):
+        return self.returncode
+
+
+def env(**kw):
+    base = {"VOCAL_ISOLATION": "1", "VOCAL_ISOLATION_CMD": "/bin/true"}
+    base.update(kw)
+    return mock.patch.dict(os.environ, base)
+
+
+class VocalIsolationTests(unittest.TestCase):
+    def setUp(self):
+        self.src = wav(Path(tempfile.mkdtemp()) / "in.wav")
+        FakeProc.never_ends, FakeProc.write, FakeProc.rc = False, True, 0
+        self.w = mock.patch.object(vi, "_weights_present", return_value=True)
+        self.w.start()
+        self.addCleanup(self.w.stop)
+
+    def test_flag_off(self):
+        with mock.patch.dict(os.environ, {"VOCAL_ISOLATION": ""}):
+            self.assertFalse(vi.available())
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+            self.assertEqual(c.exception.status, 503)
+
+    def test_unavailable_without_weights_or_binary(self):
+        with env(), mock.patch.object(vi, "_weights_present", return_value=False):
+            self.assertFalse(vi.available())
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+            self.assertEqual(c.exception.status, 503)
+        with env(VOCAL_ISOLATION_CMD=""), mock.patch("shutil.which", return_value=None):
+            self.assertFalse(vi.available())
+
+    def test_success_and_cleanup(self):
+        with env(), mock.patch("subprocess.Popen", FakeProc):
+            self.assertTrue(vi.available())
+            out = vi.isolate_vocals(self.src)
+        self.assertTrue(out.exists())
+        self.assertEqual(AudioSegment.from_file(str(out)).frame_rate, 24000)
+        self.assertTrue(self.src.exists())  # original untouched
+        self.assertEqual(list(TEMP_DIR.glob("vocal_*")), [])
+        self.assertEqual(list(TEMP_DIR.glob("*_vocals.*")), [])
+
+    def test_timeout_kills_and_cleans(self):
+        FakeProc.never_ends = True
+        with env(VOCAL_ISOLATION_TIMEOUT="0.3"), mock.patch("subprocess.Popen", FakeProc):
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+        self.assertEqual(c.exception.status, 504)
+        self.assertEqual(list(TEMP_DIR.glob("vocal_*")), [])
+
+    def test_cancel(self):
+        import threading
+        FakeProc.never_ends = True
+        ev = threading.Event(); ev.set()
+        with env(), mock.patch("subprocess.Popen", FakeProc):
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src, ev)
+        self.assertEqual(c.exception.status, 499)
+
+    def test_too_long_and_failure_and_busy(self):
+        with env(VOCAL_ISOLATION_MAX_SECONDS="0.5"):
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+            self.assertEqual(c.exception.status, 413)
+        FakeProc.write, FakeProc.rc = False, 1
+        with env(), mock.patch("subprocess.Popen", FakeProc):
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+            self.assertEqual(c.exception.status, 500)
+        self.assertEqual(list(TEMP_DIR.glob("vocal_*")), [])
+        with env(), vi._busy:
+            with self.assertRaises(vi.VocalIsolationError) as c:
+                vi.isolate_vocals(self.src)
+            self.assertEqual(c.exception.status, 409)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_voice_archetypes.py

@@ -0,0 +1,109 @@
+"""Archetype catalog validity, filtering, cache key, idempotent /use (generation mocked, temp dirs)."""
+import asyncio
+import io
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="ttvc-arch-config-"))
+from core import voice_archetypes as va
+import routes.archetypes as ra
+from fastapi import HTTPException
+
+
+def wav_bytes(ms=1000, amp=True):
+    from pydub import AudioSegment
+    from pydub.generators import Sine
+    seg = Sine(220).to_audio_segment(duration=ms) if amp else AudioSegment.silent(ms)
+    buf = io.BytesIO(); seg.export(buf, format="wav"); return buf.getvalue()
+
+
+class Catalog(unittest.TestCase):
+    def test_valid(self):
+        self.assertGreaterEqual(len(va.ARCHETYPES), 40)
+        self.assertEqual(len(va.BY_ID), len(va.ARCHETYPES))
+        for a in va.ARCHETYPES:
+            self.assertIn(a["category"], va.CATEGORIES)
+
+    def test_bad_facet_and_duplicate_rejected(self):
+        row = va._ROWS[0]
+        for rows in ([row[:6] + ("ancient",) + row[7:]], [row, row]):
+            with mock.patch.object(va, "_ROWS", rows):
+                with self.assertRaises(ValueError):
+                    va._build()
+
+    def test_filter_and_paging(self):
+        r = va.list_archetypes(gender="female", language="German", limit=5)
+        self.assertTrue(r["total"] >= 5 and len(r["items"]) == 5)
+        self.assertTrue(all(i["facets"]["gender"] == "female" for i in r["items"]))
+        self.assertEqual(va.list_archetypes(q="drache")["total"], 1)
+        self.assertEqual(va.list_archetypes(limit=9999)["limit"], va.MAX_LIMIT)
+        self.assertEqual(va.list_archetypes(gender="x")["total"], 0)
+
+    def test_cache_key_stable(self):
+        a = va.ARCHETYPES[0]
+        self.assertEqual(va.preview_key(a, "m"), va.preview_key(dict(a), "m"))
+        self.assertNotEqual(va.preview_key(a, "m"), va.preview_key(a, "m2"))
+        self.assertNotEqual(va.preview_key(a, "m"), va.preview_key(a, "m", 7))
+
+
+    def test_language_filter_codes_and_names(self):
+        n = lambda l: va.list_archetypes(language=l)["total"]
+        de = n("German")
+        self.assertGreater(de, 0)
+        self.assertEqual(n("de"), de)
+        self.assertEqual(n("DE"), de)
+        self.assertEqual(n("german"), de)
+        self.assertEqual(n("en"), n("English"))
+        self.assertGreater(n("en"), 0)
+        self.assertEqual(n("xx"), 0)
+        self.assertEqual(n("French"), 0)
+
+
+class UseRoute(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory(); self.addCleanup(self.tmp.cleanup)
+        t = Path(self.tmp.name)
+        self.settings = {"output_dir": str(t / "voices"), "voices_scan_dir": str(t / "voices")}
+        for p in (mock.patch.object(ra, "cache_dir", lambda: t / "cache"),
+                  mock.patch.object(ra, "_load_settings", lambda: self.settings),
+                  mock.patch.object(ra, "upsert_voice_in_index", lambda *a, **k: {})):
+            p.start(); self.addCleanup(p.stop)
+        self.calls = 0
+
+    def render(self, audio):
+        def f(a, s):
+            self.calls += 1; return audio
+        return mock.patch.object(ra, "_render", f)
+
+    def test_use_idempotent_and_cached(self):
+        async def go():
+            r1 = await ra.archetype_use("drachen_alt")
+            r2 = await ra.archetype_use("drachen_alt")
+            return r1, r2
+        with self.render(wav_bytes()), mock.patch("routes.tts._bounded_tts_call", lambda fn, *a: asyncio.to_thread(fn, *a)):
+            r1, r2 = asyncio.run(go())
+        self.assertTrue(r1["created"]); self.assertFalse(r2["created"]); self.assertEqual(self.calls, 1)
+        wav = Path(self.settings["output_dir"]) / "archetype_drachen_alt.wav"
+        self.assertTrue(wav.exists())
+        from core.voice import _load_meta
+        m = _load_meta(wav)
+        self.assertEqual(m["origin"], "designed"); self.assertEqual(m["provenance"]["basis"], "unknown")
+        self.assertEqual(m["provenance"]["source"], "archetype/drachen_alt")
+
+    def test_blank_audio_rejected_and_unknown_404(self):
+        with self.render(wav_bytes(amp=False)), mock.patch("routes.tts._bounded_tts_call", lambda fn, *a: asyncio.to_thread(fn, *a)):
+            with self.assertRaises(HTTPException) as c:
+                asyncio.run(ra.archetype_preview("drachen_alt"))
+        self.assertEqual(c.exception.status_code, 502)
+        with self.assertRaises(HTTPException) as c:
+            asyncio.run(ra.archetype_preview("nope"))
+        self.assertEqual(c.exception.status_code, 404)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_voice_bundle.py

@@ -0,0 +1,156 @@
+"""Voice export/import bundles: roundtrip and hostile-input rejection (temp dirs only)."""
+import hashlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+import wave
+import zipfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="ttvc-bundle-test-config-"))
+
+from core import voice_bundle as vb
+from core.voice import _load_meta, _save_meta
+
+
+def _wav(path: Path):
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1); w.setsampwidth(2); w.setframerate(8000); w.writeframes(b"\x01\x00" * 800)
+
+
+def _decode(p: Path):
+    with wave.open(str(p), "rb") as w:
+        assert w.getnframes() > 0
+
+
+def _zip(files: dict, manifest=None, voice_id="EN_F_a"):
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for n, d in files.items():
+            zf.writestr(n, d)
+        if manifest is not False:
+            m = manifest or {"format": 1, "voice_id": voice_id,
+                             "files": {n: hashlib.sha256(d).hexdigest() for n, d in files.items()}}
+            zf.writestr("manifest.json", json.dumps(m))
+    return buf.getvalue()
+
+
+class BundleTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp(prefix="ttvc-bundle-"))
+        self.src, self.dst = self.tmp / "src", self.tmp / "dst"
+        self.src.mkdir(); self.dst.mkdir()
+        self.wav_bytes = self._wav_bytes()
+
+    def tearDown(self):
+        import shutil; shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _wav_bytes(self):
+        p = self.tmp / "x.wav"; _wav(p); return p.read_bytes()
+
+    def _install(self, data: bytes, **kw):
+        z = self.tmp / "in.zip"; z.write_bytes(data)
+        return vb.import_bundle(z, self.dst, self.dst, decode_check=_decode)
+
+    def _good(self, **extra):
+        files = {"audio.wav": self.wav_bytes, "meta.json": json.dumps({"rating": 4, "seed": 7, **extra}).encode()}
+        return files
+
+    def test_roundtrip_all_parts(self):
+        wav = self.src / "EN_F_a.wav"; _wav(wav)
+        wav.with_suffix(".reference.txt").write_text("hello")
+        wav.with_suffix(".png").write_bytes(b"\x89PNG fake")
+        wav.with_suffix(".consent").write_bytes(b"consentaudio")
+        _save_meta(wav, {"rating": 3, "voice_design_prompt": "warm", "audio_problems": [],
+                         "provenance": {"basis": "consented", "source": "https://x.org", "recorded_consent": "EN_F_a.webm"}})
+        _, members = vb.export_members(wav)
+        data = b"".join(vb.stream_bundle("EN_F_a", members))
+        self.assertTrue(zipfile.is_zipfile(io.BytesIO(data)))
+        res = self._install(data)
+        self.assertEqual(res["status"], "imported")
+        out = self.dst / "EN_F_a.wav"
+        self.assertEqual(out.read_bytes(), wav.read_bytes())
+        self.assertEqual((self.dst / "EN_F_a.reference.txt").read_text(), "hello")
+        self.assertEqual((self.dst / "EN_F_a.consent").read_bytes(), b"consentaudio")
+        self.assertTrue((self.dst / "EN_F_a.png").exists())
+        meta = _load_meta(out)
+        self.assertEqual(meta["voice_design_prompt"], "warm")
+        self.assertEqual(meta["provenance"]["basis"], "consented")
+        self.assertEqual(meta["provenance"]["recorded_consent"], "EN_F_a.webm")
+        self.assertEqual([p.name for p in self.dst.iterdir() if p.name.startswith(".import")], [])
+
+    def test_collision_suffix_and_idempotent(self):
+        data = _zip(self._good())
+        self.assertEqual(self._install(data)["status"], "imported")
+        self.assertEqual(self._install(data)["status"], "unchanged")  # same audio again: no duplicate
+        self.assertEqual(len(list(self.dst.glob("*.wav"))), 1)
+        other = _zip({**self._good(), "audio.wav": self.wav_bytes + b"\x00\x00"})
+        r = self._install(other)
+        self.assertEqual((r["status"], r["voice_id"]), ("renamed", "EN_F_a_2"))
+        self.assertTrue((self.dst / "EN_F_a.wav").exists())  # original untouched
+
+    def test_missing_optional_parts(self):
+        r = self._install(_zip({"audio.wav": self.wav_bytes}))
+        self.assertEqual(r["status"], "imported")
+        self.assertFalse((self.dst / "EN_F_a.consent").exists())
+
+    def test_tampered_hash(self):
+        files = self._good()
+        m = {"format": 1, "voice_id": "EN_F_a", "files": {n: hashlib.sha256(d).hexdigest() for n, d in files.items()}}
+        files["audio.wav"] = self.wav_bytes + b"tamper"
+        with self.assertRaisesRegex(vb.BundleError, "Hash mismatch"):
+            self._install(_zip(files, manifest=m))
+        self.assertEqual(list(self.dst.iterdir()), [])
+
+    def test_zip_slip_and_unknown_members(self):
+        for bad in ("../evil.wav", "/etc/passwd", "sub/audio.wav", "run.sh", "audio.exe"):
+            with self.assertRaises(vb.BundleError, msg=bad):
+                self._install(_zip({**self._good(), bad: b"x"}))
+        self.assertEqual(list(self.dst.iterdir()), [])
+
+    def test_bad_voice_id_in_manifest(self):
+        for vid in ("../x", "a/b", ".hidden", "", "a" * 200):
+            with self.assertRaises(vb.BundleError, msg=vid):
+                self._install(_zip(self._good(), voice_id=vid))
+
+    def test_zip_bomb(self):
+        files = {**self._good(), "reference.txt": b"a" * (vb.MAX_TEXT_BYTES + 1)}
+        with self.assertRaises(vb.BundleError):
+            self._install(_zip(files))
+        files = {"audio.wav": b"\x00" * (20 * 1024 * 1024)}  # extreme ratio
+        with self.assertRaises(vb.BundleError):
+            self._install(_zip(files))
+
+    def test_lying_declared_size_still_capped(self):
+        orig = vb.MAX_TEXT_BYTES
+        try:
+            data = _zip({**self._good(), "reference.txt": b"b" * 5000})
+            vb.MAX_TEXT_BYTES = 2000
+            with self.assertRaises(vb.BundleError):
+                self._install(data)
+        finally:
+            vb.MAX_TEXT_BYTES = orig
+
+    def test_invalid_meta_and_provenance(self):
+        for meta in ({"rating": 99}, {"provenance": {"basis": "pirated"}}, {"provenance": {"source": "ftp://u:p@h"}}):
+            with self.assertRaises(vb.BundleError):
+                self._install(_zip({"audio.wav": self.wav_bytes, "meta.json": json.dumps(meta).encode()}))
+
+    def test_undecodable_audio_and_not_zip(self):
+        with self.assertRaises(vb.BundleError):
+            self._install(_zip({"audio.wav": b"not audio at all"}))
+        with self.assertRaises(vb.BundleError):
+            self._install(b"garbage")
+        self.assertEqual(list(self.dst.iterdir()), [])
+
+    def test_missing_manifest(self):
+        with self.assertRaises(vb.BundleError):
+            self._install(_zip(self._good(), manifest=False))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_voice_provenance.py

@@ -0,0 +1,99 @@
+"""Voice consent/provenance: validation, defaults, persistence, upload route (temp dirs only)."""
+import asyncio
+import io
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="ttvc-prov-test-config-"))
+from fastapi import HTTPException, UploadFile
+from starlette.datastructures import Headers
+
+from core.provenance import import_provenance, validate_provenance
+from core.voice import _load_meta, _save_meta, _voice_package_paths
+import routes.library as lib
+
+
+class ValidationTests(unittest.TestCase):
+    def test_defaults_and_cleaning(self):
+        p = validate_provenance({})
+        self.assertEqual(p["basis"], "unknown")
+        p = validate_provenance({"basis": "licensed", "licence": " CC-BY\x00 4.0 ", "source": "https://x.org/a"})
+        self.assertEqual(p["licence"], "CC-BY 4.0")
+        self.assertTrue(p["set_at"])
+
+    def test_rejects(self):
+        for bad in ({"basis": "stolen"}, {"note": "x" * 1001}, {"source": "javascript:alert(1)"},
+                    {"source": "ftp://x.org/a"}, {"source": "https://u:pw@x.org/"}, {"licence": 5}):
+            with self.assertRaises(ValueError, msg=str(bad)):
+                validate_provenance(bad)
+
+    def test_recording_not_settable_by_client(self):
+        self.assertNotIn("recorded_consent", validate_provenance({"recorded_consent": "../../etc/passwd"}))
+        self.assertEqual(validate_provenance({}, {"recorded_consent": "a.webm"})["recorded_consent"], "a.webm")
+
+    def test_import_prefill_stays_unknown(self):
+        p = import_provenance("https://voices.example/v/1")
+        self.assertEqual((p["basis"], p["source"]), ("unknown", "https://voices.example/v/1"))
+        self.assertEqual(import_provenance("ftp://bad")["source"], "")
+
+
+class RouteTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = Path(self.tmp.name)
+        self.wav = self.dir / "EN_F_Test.wav"
+        self.wav.write_bytes(b"RIFF")
+        patch = mock.patch.object(lib, "_load_settings", return_value={"voices_scan_dir": str(self.dir)})
+        patch.start()
+        self.addCleanup(patch.stop)
+        self.addCleanup(self.tmp.cleanup)
+
+    def _req(self, body):
+        class R:
+            async def json(_):
+                return body
+        return R()
+
+    def test_put_persists_and_validates(self):
+        out = asyncio.run(lib.put_voice_provenance("EN_F_Test", self._req({"basis": "own_voice", "note": "me"})))
+        self.assertEqual(_load_meta(self.wav)["provenance"]["basis"], "own_voice")
+        self.assertEqual(out["provenance"]["note"], "me")
+        with self.assertRaises(HTTPException) as cm:
+            asyncio.run(lib.put_voice_provenance("EN_F_Test", self._req({"basis": "nope"})))
+        self.assertEqual(cm.exception.status_code, 400)
+        with self.assertRaises(HTTPException) as cm:
+            asyncio.run(lib.put_voice_provenance("missing", self._req({})))
+        self.assertEqual(cm.exception.status_code, 404)
+
+    def test_legacy_voice_has_no_provenance(self):
+        self.assertNotIn("provenance", _load_meta(self.wav))  # UI treats absent as unknown
+
+    def _upload(self, name, ctype, data):
+        f = UploadFile(io.BytesIO(data), filename=name, headers=Headers({"content-type": ctype}))
+        return asyncio.run(lib.upload_consent_recording("EN_F_Test", f))
+
+    def test_consent_upload(self):
+        out = self._upload("c.webm", "audio/webm;codecs=opus", b"abc")
+        self.assertEqual(out["provenance"]["recorded_consent"], "EN_F_Test.webm")
+        self.assertTrue(self.wav.with_suffix(".consent").exists())
+        self.assertIn(self.wav.with_suffix(".consent"), _voice_package_paths(self.wav))
+        self.assertEqual(asyncio.run(lib.serve_consent_recording("EN_F_Test")).media_type, "audio/webm")
+        for name, ctype in (("c.exe", "audio/webm"), ("c.webm", "text/html"), ("../c.webm", "audio/webm")):
+            with self.assertRaises(HTTPException, msg=name):
+                self._upload(name, ctype, b"abc")
+
+    def test_consent_too_large(self):
+        with mock.patch("core.provenance.MAX_CONSENT_BYTES", 2), self.assertRaises(HTTPException) as cm:
+            self._upload("c.webm", "audio/webm", b"abcdef")
+        self.assertEqual(cm.exception.status_code, 413)
+        self.assertFalse(self.wav.with_suffix(".consent").exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_voice_sources_new.py

@@ -0,0 +1,191 @@
+"""LibriVox / Wikimedia Commons voice sources: validation, caps, host checks, mapping, provenance, cache/throttle (HTTP mocked)."""
+import asyncio
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+os.environ.setdefault("CONFIG_DIR", tempfile.mkdtemp(prefix="ttvc-vs-test-config-"))
+from core import open_voice_sources as ovs
+import routes.sources as src
+
+
+def book(i=1, lang="English", url="https://www.archive.org/download/x/a.mp3", sections=False):
+    b = {"id": str(i), "title": f"Book {i}", "language": lang, "url_librivox": f"https://librivox.org/b{i}/",
+         "totaltimesecs": 600, "authors": [{"first_name": "Jane", "last_name": "Austen"}]}
+    if sections:
+        b["sections"] = [{"title": "Ch 1", "listen_url": url, "playtime": "600", "readers": [{"display_name": "Ann"}]}]
+    return b
+
+
+def commons(**over):
+    info = {"url": "https://upload.wikimedia.org/a.opus", "descriptionurl": "https://commons.wikimedia.org/wiki/File:A.opus",
+            "mediatype": "AUDIO", "duration": 12.4,
+            "extmetadata": {"LicenseShortName": {"value": "CC BY-SA 4.0"}, "Artist": {"value": "<a href='x'>Bob &amp; Co</a>"},
+                            "LicenseUrl": {"value": "https://creativecommons.org/licenses/by-sa/4.0"}}}
+    info.update(over)
+    return {"query": {"pages": {"1": {"title": "File:A.opus", "index": 1, "imageinfo": [info]}}}}
+
+
+class Base(unittest.TestCase):
+    def setUp(self):
+        ovs._cache.clear()
+        ovs._last_call.clear()
+        p = mock.patch.object(ovs.time, "sleep")
+        p.start()
+        self.addCleanup(p.stop)
+
+
+class ValidationTests(Base):
+    def test_query_and_lang(self):
+        for bad in ("", "   ", "x" * 81):
+            with self.assertRaises(ovs.SourceError):
+                ovs.clean_query(bad)
+        self.assertEqual(ovs.clean_query(" a\x00 \n b "), "a b")
+        with self.assertRaises(ovs.SourceError):
+            ovs.clean_lang("en;rm")
+        with self.assertRaises(ovs.SourceError):
+            ovs.search("evil", "x")
+
+    def test_host_check(self):
+        self.assertTrue(ovs.host_ok("https://ia80.us.archive.org/x.mp3", ovs.AUDIO_HOSTS))
+        for bad in ("http://archive.org/x", "https://evilarchive.org/x", "https://archive.org.evil.com/x",
+                    "https://u:p@archive.org/x", "https://127.0.0.1/x", "file:///etc/passwd"):
+            self.assertFalse(ovs.host_ok(bad, ovs.AUDIO_HOSTS), bad)
+
+
+class MappingTests(Base):
+    def test_librivox_list_is_light_filtered_and_capped(self):
+        books = [book(i) for i in range(15)] + [book(98, lang="German"), dict(book(97), url_librivox="https://evil.example/x/"), dict(book(96), id="x;1")]
+        with mock.patch.object(ovs, "_get_json", return_value={"books": books}) as g:
+            items = ovs.search("librivox", "pride", "en")
+        self.assertEqual(len(items), ovs.MAX_RESULTS)
+        self.assertNotIn("extended", g.call_args[0][1])
+        it = items[0]
+        self.assertEqual((it["author"], it["language"], it["duration"], it["audio_url"], it["book_id"]), ("Jane Austen", "English", 600, "", "0"))
+        self.assertTrue(it["licence_url"].startswith("https://librivox.org/"))
+        self.assertTrue(all(i["language"] == "English" and "evil" not in i["source_url"] for i in items))
+
+    def test_librivox_first_section(self):
+        bad = book(2, url="https://evil.example/a.mp3", sections=True)
+        bad["sections"].append({"title": "Ch 2", "listen_url": "https://ia1.us.archive.org/b.mp3", "playtime": "5", "readers": []})
+        with mock.patch.object(ovs, "_get_json", return_value={"books": [bad]}) as g:
+            r = ovs.librivox_first_section("2")
+        self.assertEqual(g.call_args[0][1]["extended"], 1)
+        self.assertEqual((r["audio_url"], r["section"], r["duration"]), ("https://ia1.us.archive.org/b.mp3", "Ch 2", 5))
+        for badid in ("", "abc", "1;2", "1" * 10):
+            with self.assertRaises(ovs.SourceError):
+                ovs.librivox_first_section(badid)
+        with mock.patch.object(ovs, "_get_json", return_value={"books": [book(3, url="https://evil.example/a")]}):
+            with self.assertRaises(ovs.SourceError) as cm:
+                ovs.librivox_first_section("3")
+        self.assertEqual(cm.exception.status, 404)
+
+    def test_wikimedia_mapping(self):
+        with mock.patch.object(ovs, "_get_json", return_value=commons()):
+            it = ovs.search("wikimedia", "speech")[0]
+        self.assertEqual((it["title"], it["reader"], it["licence"], it["duration"]), ("A", "Bob & Co", "CC BY-SA 4.0", 12))
+        self.assertIn("Bob & Co / A, CC BY-SA 4.0", it["attribution"])
+
+    def test_wikimedia_drops_unsafe_or_unlicensed(self):
+        for over in ({"url": "https://evil.example/a.opus"}, {"mediatype": "VIDEO"}, {"extmetadata": {}}):
+            ovs._cache.clear()
+            with mock.patch.object(ovs, "_get_json", return_value=commons(**over)):
+                self.assertEqual(ovs.search("wikimedia", "speech"), [])
+
+
+class ProvenanceTests(Base):
+    def test_librivox(self):
+        p = ovs.import_provenance_for("librivox", "https://librivox.org/b/", "", "")
+        self.assertEqual(p["basis"], "public_domain")
+        self.assertIn("reader's declared licence", p["note"])
+        self.assertEqual(p["source"], "https://librivox.org/b/")
+
+    def test_wikimedia(self):
+        p = ovs.import_provenance_for("wikimedia", "https://commons.wikimedia.org/wiki/File:A.opus", "CC BY 4.0", "Bob / A")
+        self.assertEqual((p["basis"], p["licence"]), ("licensed", "CC BY 4.0"))
+        self.assertIn("Bob / A", p["note"])
+        self.assertEqual(ovs.import_provenance_for("wikimedia", "https://c.org/", "Public domain", "")["basis"], "public_domain")
+        with self.assertRaises(ValueError):
+            ovs.import_provenance_for("other", "", "", "")
+
+
+class CacheThrottleTests(Base):
+    def test_cache_hit_skips_upstream(self):
+        with mock.patch.object(ovs, "_get_json", return_value={"books": [book()]}) as g:
+            ovs.search("librivox", "Pride"); ovs.search("librivox", "pride")
+        self.assertEqual(g.call_count, 1)
+
+    def test_throttle_sleeps_and_errors_are_generic(self):
+        resp = mock.Mock(status_code=200)
+        resp.raise_for_status.return_value = None
+        resp.iter_content.return_value = [b'{"books": []}']
+        with mock.patch.object(ovs.requests, "get", return_value=resp) as g:
+            ovs._get_json(ovs.LIBRIVOX_API, {}); ovs._get_json(ovs.LIBRIVOX_API, {})
+        self.assertTrue(ovs.time.sleep.called)
+        self.assertFalse(g.call_args.kwargs["allow_redirects"])
+        self.assertIn("User-Agent", g.call_args.kwargs["headers"])
+        with mock.patch.object(ovs.requests, "get", side_effect=OSError("secret host")):
+            with self.assertRaises(ovs.SourceError) as cm:
+                ovs._get_json(ovs.COMMONS_API, {})
+        self.assertNotIn("secret", str(cm.exception))
+
+
+class RetryErrorTests(Base):
+    def setUp(self):
+        super().setUp()
+        ovs._neg.clear()
+
+    def test_timeout_retried_once_then_clear_message_and_negative_cache(self):
+        with mock.patch.object(ovs.requests, "get", side_effect=ovs.requests.Timeout("secret")) as g:
+            with self.assertRaises(ovs.SourceError) as cm:
+                ovs.search("librivox", "Faust")
+            self.assertEqual(g.call_count, 2)
+            self.assertIn("in time", str(cm.exception))
+            self.assertEqual(cm.exception.status, 502)
+            with self.assertRaises(ovs.SourceError):  # remembered: no further upstream call
+                ovs.search("librivox", "Faust")
+            self.assertEqual(g.call_count, 2)
+
+    def test_retry_recovers_and_messages_differ(self):
+        resp = mock.Mock(status_code=200)
+        resp.raise_for_status.return_value = None
+        resp.iter_content.return_value = [b'{"books": []}']
+        with mock.patch.object(ovs.requests, "get", side_effect=[ovs.requests.ConnectionError("x"), resp]):
+            self.assertEqual(ovs._get_json(ovs.LIBRIVOX_API, {}), {"books": []})
+        for exc, text in ((ovs.requests.ConnectionError("x"), "unreachable"), (ValueError("x"), "unreadable")):
+            with mock.patch.object(ovs.requests, "get", side_effect=exc):
+                with self.assertRaises(ovs.SourceError) as cm:
+                    ovs._get_json(ovs.LIBRIVOX_API, {})
+            self.assertIn(text, str(cm.exception))
+
+
+class SettingsTests(unittest.TestCase):
+    def test_export_provenance_default_exposed(self):
+        from core import config
+        self.assertIs(config._load_settings().get("export_provenance_default"), True)
+
+
+class RouteTests(Base):
+    def test_search_route_errors_and_allowlist(self):
+        with self.assertRaises(src.HTTPException) as cm:
+            asyncio.run(src.open_voice_source_search("librivox", ""))
+        self.assertEqual(cm.exception.status_code, 400)
+        self.assertIn("archive.org", src._PROXY_AUDIO_DOMAINS)
+        self.assertIn("upload.wikimedia.org", src._PROXY_AUDIO_DOMAINS)
+
+    def test_quick_import_rejects_foreign_host(self):
+        req = mock.Mock()
+        async def js(): return {"audio_url": "https://example.com/a.mp3", "voice_id": "x", "source_kind": "librivox"}
+        req.json = js
+        with mock.patch.object(src, "_source_import_url", side_effect=lambda u: u):
+            with self.assertRaises(src.HTTPException) as cm:
+                asyncio.run(src.quick_import_voice(req))
+        self.assertEqual(cm.exception.status_code, 400)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_watermark_tags.py

@@ -0,0 +1,51 @@
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+from core import export_provenance as ep
+
+
+class ProvenanceTags(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = Path(self.tmp.name)
+        self.src = self.dir / "secret_user_dir_tone.mp3"
+        subprocess.run(["ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "sine=frequency=440:duration=1",
+                        str(self.src)], check=True)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_tags_present_and_original_untouched(self):
+        out = ep.apply_tags(self.src, self.dir / "out.mp3", ep.build_tags("1.2.3", "narrator", False))
+        tags = ep.read_tags(out)
+        self.assertEqual(tags["synthetic_speech"], "true")
+        self.assertEqual(tags["generator_version"], "1.2.3")
+        self.assertNotIn("voice", tags)
+        self.assertEqual(ep.read_tags(self.src), {})
+
+    def test_voice_only_on_opt_in_and_name_only(self):
+        out = ep.apply_tags(self.src, self.dir / "v.mp3", ep.build_tags("1", "/voices/me/narrator.wav", True))
+        self.assertEqual(ep.read_tags(out)["voice"], "narrator.wav")
+
+    def test_no_path_leakage(self):
+        out = ep.apply_tags(self.src, self.dir / "o.mp3", ep.build_tags("1", "x", True))
+        blob = out.read_bytes()
+        self.assertNotIn(self.tmp.name.encode(), blob)
+        self.assertNotIn(b"secret_user_dir", blob)
+
+    def test_bad_input_raises_without_path(self):
+        with self.assertRaises(RuntimeError) as cm:
+            ep.apply_tags(self.dir / "missing.mp3", self.dir / "x.mp3", {})
+        self.assertNotIn(self.tmp.name, str(cm.exception))
+        self.assertEqual(ep.read_tags(self.dir / "missing.mp3"), {})
+
+    def test_watermark_stub_unavailable(self):
+        self.assertFalse(ep.watermark_available())
+        with self.assertRaises(NotImplementedError):
+            ep.watermark(self.src)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/vocal-isolation.spec.js

@@ -0,0 +1,51 @@
+// @ts-check
+// "Remove background music" in the URL import card (all /api routes mocked).
+const { test, expect } = require('@playwright/test');
+
+async function open(page, available) {
+  await page.route('**/api/**', route => route.request().method() === 'GET' ? route.fulfill({ json: {} }) : route.fulfill({ json: { ok: true } }));
+  await page.route('**/api/voices*', route => route.fulfill({ json: [] }));
+  await page.route('**/api/version', route => route.fulfill({ json: { version: 'x', features: { vocal_isolation: available } } }));
+  await page.route('**/api/audio/*', route => route.fulfill({ status: 404, body: '' }));
+  await page.route('**/static/dist/main.min.js*', r => r.abort());
+  await page.goto('/', { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => typeof window.navTo === 'function', null, { timeout: 15_000 });
+  await page.waitForSelector('#app-skeleton', { state: 'detached', timeout: 15_000 });
+}
+
+test('button hidden when the server cannot isolate', async ({ page }) => {
+  await open(page, false);
+  await expect(page.locator('#lib-iso-btn')).toHaveAttribute('hidden', '');
+  await expect(page.locator('#yt-iso-btn')).toHaveAttribute('hidden', '');
+});
+
+test('isolate, compare with original, and show errors', async ({ page }) => {
+  await open(page, true);
+  /** @type {any[]} */ const calls = [];
+  let fail = false;
+  await page.route('**/api/isolate-vocals', route => {
+    calls.push(route.request().postDataJSON());
+    return fail ? route.fulfill({ status: 503, json: { detail: 'Vocal isolation is turned off' } })
+                : route.fulfill({ json: { id: 'clean1', duration: 4 } });
+  });
+  await page.evaluate(() => window.navTo('s-voices'));
+  const btn = page.locator('#lib-iso-btn');
+  await expect(btn).not.toHaveAttribute('hidden', '');
+  const msg = page.locator('#lib-iso-msg');
+  await expect(msg).toHaveAttribute('aria-live', 'polite');
+  await btn.evaluate(el => el.click());
+  await expect(msg).toContainText('Load audio first');
+  await page.evaluate(() => { libAddState.id = 'orig1'; libAddState.duration = 6; });
+  await btn.evaluate(el => el.click());
+  await expect(msg).toContainText('Background music removed');
+  expect(calls).toEqual([{ id: 'orig1' }]);
+  expect(await page.evaluate(() => libAddState.id)).toBe('clean1');
+  const toggle = page.locator('#lib-iso-toggle');
+  await expect(toggle).toHaveText('Play original');
+  await toggle.evaluate(el => el.click());
+  expect(await page.evaluate(() => libAddState.id)).toBe('orig1');
+  await expect(toggle).toHaveText('Play without music');
+  fail = true;
+  await btn.evaluate(el => el.click());
+  await expect(msg).toContainText('turned off');
+});