Bound generated speech outputs

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -57,6 +57,8 @@ The app preloads image descriptions through `/api/image-descriptions`, caches th
 
 Kokoro is still the intended model-backed TTS path. For local resilience, the frontend can use the browser speech engine when Kokoro is unavailable, and the session panel labels that as a browser fallback instead of model audio.
 
+Generated speech outputs are capped by a small retention cleanup. That keeps repeated demo sessions from turning the Space output directory into hidden state.
+
 Reader settings are manifest-backed: the app exposes known Kokoro voices and speed bounds through `/api/article-manifest`, then the custom frontend renders the controls and passes the selected voice to `/api/speak`.
 
 Auto-advance is intentionally opt-in. This keeps the default reader mode user-controlled while still supporting a continuous-reading demo path.

README.md

@@ -100,6 +100,8 @@ Image descriptions are preloaded into a local cache and written into the page's
 
 Kokoro remains the planned tiny-model TTS path. During local demos, if the server-side Kokoro call falls back, the browser speech engine can read the same transcript so screen-reader mode still produces audible feedback.
 
+Generated speech files are pruned automatically so repeated demos do not grow the Space's `outputs` directory without bound.
+
 The reader bar exposes Kokoro voice selection and speaking speed controls. Defaults come from `/api/article-manifest` so the UI, docs, and backend stay aligned.
 
 Auto-advance is available as an opt-in reader control. It stays off by default so users keep manual control unless they choose continuous reading.

app.py

@@ -558,6 +558,22 @@ def _silent_wav(path: Path, seconds: float = 0.35, sample_rate: int = 24000) ->
         wav.writeframes(b"\x00\x00" * frames)
 
 
+def _prune_speech_outputs(keep_path: Path, max_files: int = 24) -> None:
+    speech_files = sorted(
+        OUTPUT_DIR.glob("speech*.wav"),
+        key=lambda path: path.stat().st_mtime,
+        reverse=True,
+    )
+    keep_resolved = keep_path.resolve()
+    for old_path in speech_files[max_files:]:
+        if old_path.resolve() == keep_resolved:
+            continue
+        try:
+            old_path.unlink()
+        except OSError:
+            pass
+
+
 def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
     start = time.perf_counter()
     try:
@@ -577,6 +593,8 @@ def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
         runtime = "fallback"
         warning = f"Kokoro unavailable: {exc.__class__.__name__}"
 
+    _prune_speech_outputs(output_path)
+
     return {
         "ok": True,
         "runtime": runtime,

scripts/verify.py

@@ -139,6 +139,27 @@ def verify_core_fallbacks() -> None:
     assert_true(isinstance(generated["elapsed_ms"], int), "Image generation should include elapsed_ms")
 
 
+def verify_output_retention() -> None:
+    keep_path = app.OUTPUT_DIR / "speech-retention-keep.wav"
+    _ = app.speak_core("Tiny Narrator retention check.", voice="af_heart", speed=1.0)
+    keep_path.write_bytes(b"keep")
+    stale_files = []
+    for index in range(30):
+        stale_path = app.OUTPUT_DIR / f"speech-retention-stale-{index:02d}.wav"
+        stale_path.write_bytes(b"stale")
+        stale_files.append(stale_path)
+
+    app._prune_speech_outputs(keep_path, max_files=4)
+
+    remaining = list(app.OUTPUT_DIR.glob("speech*.wav"))
+    assert_true(keep_path.exists(), "Speech retention should keep the active output")
+    assert_true(len(remaining) <= 5, "Speech retention should prune stale generated audio")
+
+    keep_path.unlink(missing_ok=True)
+    for stale_path in stale_files:
+        stale_path.unlink(missing_ok=True)
+
+
 def verify_routes() -> None:
     client = TestClient(app.app)
 
@@ -308,6 +329,7 @@ def main() -> None:
     verify_static_assets()
     verify_space_metadata()
     verify_core_fallbacks()
+    verify_output_retention()
     verify_routes()
     print("Tiny Narrator verification passed.")