Document scoped quality-reranked inference

README.md

@@ -127,6 +127,35 @@ python scripts/generate_tts.py \
   --out long.wav
 ```
 
+## Quality-First Short and Medium Text
+
+The optional offline quality path generates multiple candidates and uses ASR
+plus speaker verification to select one. It is slower than ordinary generation
+and does not change the checkpoint weights:
+
+```bash
+python scripts/generate_tts_quality.py \
+  --checkpoint /path/to/model-snapshot \
+  --mode speaker-reference-audio-only \
+  --speaker-reference-wav /path/to/rights-cleared-reference.wav \
+  --text "這是離線品質優先的語音合成測試。" \
+  --candidates 10 \
+  --asr-backend whisper \
+  --asr-model /path/to/compatible-asr-checkpoint \
+  --candidate-speaker-weight 0.05 \
+  --candidate-boundary-speaker-weight 0.1 \
+  --candidate-max-boundary-speaker-drop 0.03 \
+  --target-chars-per-sec 4.2 \
+  --out quality.wav
+```
+
+The candidate count and score weights are measured project heuristics, not
+universal TTS defaults. The command fails closed when no candidate passes the
+speaker-boundary gate. `--allow-boundary-fallback` is available for research,
+but is outside the measured contract. This quality policy is promoted only for
+speaker-reference short/medium synthesis; centroid and strict long-form gates
+did not pass.
+
 ## Evaluation
 
 Numbers below are from an internal held-out evaluation set. The eval set and
@@ -144,6 +173,17 @@ reaches 6.25 chars/sec and early-stop classification exceeds 50%. Controlled
 pace is therefore part of the current production contract, not an optional
 benchmark optimization.
 
+The opt-in short/medium quality policy was measured on 30 texts with ten
+candidates per text. The full candidate pool reached 9.35% CER / 9.51% WER;
+the selected outputs reached 1.14% / 1.86%, with zero early stops, overruns,
+final truncations, or speaker-boundary fallbacks. Across-text speaker
+similarity was 0.511, reference-similarity P10 was 0.444, and median/P95 pace
+was 4.04/4.17 chars/sec. A second ASR that did not participate in selection
+measured 6.83% CER / 6.78% WER; on matched target recordings it measured
+9.20% / 8.76%. The same single code-switch item was the only outlier in both.
+These are test-time selection results and must not be described as a trained
+checkpoint improvement.
+
 The selected long-form contract was repeated in four independent processes,
 each with three multi-sentence texts and five request seeds. It uses
 80-character chunks, 4.0 target chars/sec, no retry selection, one reference
@@ -168,6 +208,12 @@ chunk consistently worsened CER, pace variance, and speaker drift, so
 `--continuation-context-sec 0` remains the production default. Raw reference
 tokens are not represented by these production metrics.
 
+A separately frozen 12-text long-form holdout reached 4.00% selected CER and
+4.91% WER under the selection ASR, but one numeric/ASCII-heavy request had no
+candidate below the 0.03 speaker-boundary gate. Independent-ASR CER was 15.25%
+with one cross-chunk outlier. The quality-reranked long-form path is therefore
+not promoted; use the standard measured 80-character/no-context command above.
+
 ## Limitations
 
 - Metrics are not a public benchmark and should be used only for internal model
@@ -179,6 +225,8 @@ tokens are not represented by these production metrics.
   target pace, stop hysteresis, and chunking contract; inspect important output.
 - Raw reference tokens remain a separately gated research backend.
 - Very long passages should be chunked to avoid stop-token and prosody drift.
+- Quality reranking is currently promoted only for speaker-reference
+  short/medium synthesis; it is not the default centroid or long-form path.
 - Generated-audio continuation context is experimental and disabled by default.
 - Generated speech may be incorrect; do not use it as a real-world notification
   without human review.

USAGE.md

@@ -123,6 +123,31 @@ python scripts/generate_tts.py \
   --out long.wav
 ```
 
+Quality-first short or medium text:
+
+```bash
+python scripts/generate_tts_quality.py \
+  --checkpoint /path/to/model-snapshot \
+  --mode speaker-reference-audio-only \
+  --speaker-reference-wav /path/to/rights-cleared-reference.wav \
+  --text "這是離線品質優先的語音合成測試。" \
+  --candidates 10 \
+  --asr-backend whisper \
+  --asr-model /path/to/compatible-asr-checkpoint \
+  --candidate-speaker-weight 0.05 \
+  --candidate-boundary-speaker-weight 0.1 \
+  --candidate-max-boundary-speaker-drop 0.03 \
+  --target-chars-per-sec 4.2 \
+  --out quality.wav
+```
+
+This opt-in path is approximately proportional to the candidate count in
+latency. It fails closed if no candidate passes the speaker-boundary gate.
+`--allow-boundary-fallback` is a research override, not part of the measured
+contract. The quality policy is promoted only for speaker-reference
+short/medium text; keep using `generate_tts.py` for centroid and long-form
+production requests.
+
 This path extracts the windowed speaker embedding once and reuses it for every
 chunk. Each request gets a new random seed that is reused inside that request;
 the release gate varies request seeds, so stability does not depend on one

release_metadata.json

@@ -26,6 +26,23 @@
       "raw-reference-tokens"
     ]
   },
+  "inference_policies": {
+    "standard": {
+      "scope": [
+        "centroid-only",
+        "speaker-reference-embedding"
+      ]
+    },
+    "quality_rerank": {
+      "scope": [
+        "speaker-reference-embedding-short-medium"
+      ],
+      "candidate_count": 10,
+      "fail_closed_on_boundary_fallback": true,
+      "centroid_status": "not_promoted",
+      "longform_status": "not_promoted"
+    }
+  },
   "evaluation": {
     "scope": "internal held-out evaluation",
     "centroid_only": {
@@ -48,6 +65,29 @@
       "speaker_across_texts_median": 0.4557993102947186,
       "speaker_reference_p10": 0.3619180113077164
     },
+    "speaker_reference_quality_rerank": {
+      "release_role": "opt_in_short_medium",
+      "profile": "controlled_30_texts_10_candidates",
+      "candidate_pool_cer": 0.09351897921002666,
+      "candidate_pool_wer": 0.0950508473008473,
+      "selected_cer": 0.011402486402486402,
+      "selected_wer": 0.018602693602693603,
+      "independent_asr_selected_cer": 0.06834166650343122,
+      "independent_asr_selected_wer": 0.06783609908609908,
+      "chars_per_second_median": 4.044117647058823,
+      "chars_per_second_p95": 4.166666666666667,
+      "early_stop_rate": 0.0,
+      "overrun_rate": 0.0,
+      "sentence_final_truncation_rate": 0.0,
+      "boundary_fallback_count": 0,
+      "speaker_across_texts_median": 0.5111590030378309,
+      "speaker_reference_p10": 0.4438544690608978,
+      "begin_end_speaker_drop_max": 0.029450446367263794
+    },
+    "quality_rerank_non_promoted": {
+      "centroid": "speaker boundary and duration-variance gates failed",
+      "longform": "one of twelve holdout requests failed the speaker boundary gate"
+    },
     "natural_stop": {
       "status": "pace_gate_failed",
       "speaker_reference_cer": 0.1285453712953713,