midcuts phase5 steps 1-3: context manner-steer + CC captions + v2 budget (5bd269d)

src/small_cuts/modal_upload.py

@@ -133,18 +133,20 @@ class ModalUploadClient:
         *,
         style_key: str = "deadpan",
         language: str = "English",
+        context: str = "",
     ) -> dict[str, Any]:
         """Upload a clip to the v2 ``/v2/narrate`` pipeline in the chosen narration language.
 
-        Mirrors :meth:`submit_video` but targets the v2 endpoint (``style_key`` + ``language`` form
-        fields, no ``scene_hint``) and polls ``/v2/narrate/{job_id}``. Kept as a separate method so
-        the v1 ``/v1/cuts`` path used by the live Space is untouched.
+        Mirrors :meth:`submit_video` but targets the v2 endpoint (``style_key`` + ``language`` +
+        ``context`` form fields) and polls ``/v2/narrate/{job_id}``. ``context`` is the optional
+        free-text *manner* steer (how the moment is told). Kept as a separate method so the v1
+        ``/v1/cuts`` path used by the live Space is untouched.
         """
         close = self.http_client is None
         client = self.http_client or httpx.Client(timeout=30.0, follow_redirects=True)
         try:
             try:
-                job_id = self._submit_v2(client, Path(video_path), style_key, language)
+                job_id = self._submit_v2(client, Path(video_path), style_key, language, context)
             except ModalUploadError:
                 raise
             except httpx.HTTPError as exc:
@@ -169,12 +171,13 @@ class ModalUploadClient:
         video_path: Path,
         style_key: str,
         language: str,
+        context: str = "",
     ) -> str:
         with video_path.open("rb") as handle:
             response = client.post(
                 f"{self.base_url.rstrip('/')}/v2/narrate",
                 headers={"Authorization": f"Bearer {self.token}"},
-                data={"style_key": style_key, "language": language},
+                data={"style_key": style_key, "language": language, "context": context},
                 files={"video": (video_path.name, handle, "video/mp4")},
             )
         _raise_for_modal_status(response, "request")

src/small_cuts/narrate_v2.py

@@ -25,6 +25,7 @@ from uuid import uuid4
 CONTRACT_VERSION = "1.2.0"
 TITLE_MAX = 80
 NARRATION_MAX = 2000
+MAX_CONTEXT_CHARS = 280
 RELAY_HOOK_TIMEOUT_S = 5.0
 
 # (local file, remote bucket-relative path) -> None. The Modal app binds this to a token-scoped
@@ -32,6 +33,207 @@ RELAY_HOOK_TIMEOUT_S = 5.0
 Uploader = Callable[[Path, str], None]
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Narration language config (the by-ear quality lever — CARLOS tunes these strings).
+#
+# Two knobs feed the Talker's accent (Phase 0.5 finding): (1) the *text* the Thinker writes — a
+# native-language prompt yields cleaner, less-anglophone text than an English "write in {language}"
+# prompt; (2) the autoregressive cold-start ramp — the first ~1s of speech drifts toward the
+# dominant (EN+ZH) manifold before settling, so the Talker speaks a throwaway warm-up *carrier*
+# first and we trim it off (the aligner finds where it ends). Only the by-ear-validated languages
+# (en/es/fr) are configured; any other language degrades to an English-base prompt with NO carrier,
+# so the aligner step is skipped. English is configured too; English-on-Aiden has a mild ramp, so
+# drop "English" from PRIME_CARRIER if the warm-up isn't worth the extra step there.
+# ─────────────────────────────────────────────────────────────────────────────
+
+DEADPAN_SYS = (
+    "You are a film narrator. Watch the clip and write ONE short, flat, factual sentence "
+    "describing the moment. Declarative only. No exclamations, no emphasis, no emotion words, "
+    "no asterisks, brackets, parentheses, or stage directions. Neutral, monotone, deadpan."
+)
+USER_PROMPT = "Narrate this moment."
+
+# Native-language (system, user) narration prompts. English is the canonical deadpan spec; es/fr
+# are faithful ports (peninsular Spanish; standard French).
+NATIVE_PROMPTS: dict[str, tuple[str, str]] = {
+    "English": (DEADPAN_SYS, USER_PROMPT),
+    "Spanish": (
+        "Eres un narrador de cine español. Observa el clip y escribe UNA sola frase corta, plana "
+        "y objetiva que describa el momento. Solo en modo declarativo. Sin exclamaciones, sin "
+        "énfasis, sin palabras emotivas, sin asteriscos, corchetes, paréntesis ni acotaciones "
+        "escénicas. Neutral, monótono e inexpresivo. Escribe la narración en español de España "
+        "(castellano peninsular).",
+        "Narra este momento.",
+    ),
+    "French": (
+        "Tu es un narrateur de cinéma français. Regarde le plan et écris UNE seule phrase courte, "
+        "neutre et factuelle qui décrit le moment. Uniquement au mode déclaratif. Sans "
+        "exclamations, sans emphase, sans mots émotifs, sans astérisques, crochets, parenthèses ni "
+        "didascalies. Neutre, monotone, impassible. Rédige la narration en français.",
+        "Raconte ce moment.",
+    ),
+}
+
+# ~7-8s deadpan warm-up the Talker speaks FIRST, then trimmed off. Two self-contained sentences
+# ending in a full stop (so it can't bleed into the real narration) and content-neutral (so it
+# can't bias what the model describes). ~16-18 words ≈ 7s spoken — the Phase-0 workflow found <5s
+# under-warms the cold-start ramp.
+PRIME_CARRIER: dict[str, str] = {
+    "English": (
+        "Preparing the narrator's voice for this recording in English. "
+        "The description of the scene begins right now."
+    ),
+    "Spanish": (
+        "Preparando la voz del narrador en español de España. "
+        "La descripción de la escena comienza ahora."
+    ),
+    "French": (
+        "Préparation de la voix du narrateur en français pour cet enregistrement. "
+        "La description de la scène commence maintenant."
+    ),
+}
+
+# Per-language instruction (appended to the system prompt) telling the Thinker to open with the
+# carrier verbatim. Written in the target language to keep the model in a native context.
+PRIME_INSTRUCTION: dict[str, str] = {
+    "English": "Begin your answer exactly with the sentence «{carrier}» and then the narration.",
+    "Spanish": (
+        "Comienza tu respuesta exactamente con la frase «{carrier}» y, a continuación, la "
+        "narración."
+    ),
+    "French": "Commence ta réponse exactement par la phrase «{carrier}» puis la narration.",
+}
+
+# Per-language template for the optional free-text *manner* steer (Phase 5 step 1). The upload
+# "Whisper context to the narrator" field steers HOW the moment is told — voice, mood, register —
+# NOT what facts to include; it is allowed to override the neutral deadpan default. Written in the
+# target language to keep the Talker in a native manifold; unknown languages reuse the English one.
+# Appended to the system prompt BEFORE the prime/carrier block so the carrier stays last.
+CONTEXT_INSTRUCTION: dict[str, str] = {
+    "English": (
+        " The person who lived this moment asks you to tell it a particular way: «{context}». "
+        "Let that set the voice, mood, and register of the narration — it overrides the neutral "
+        "monotone above where they conflict. Keep the other rules: one short sentence in "
+        "{language}, declarative, no stage directions, and invent nothing that is not in "
+        "the clip."
+    ),
+    "Spanish": (
+        " La persona que vivió este momento te pide que lo narres de una manera concreta: "
+        "«{context}». Deja que eso marque la voz, el tono y el registro de la narración; prevalece "
+        "sobre el tono neutro y monótono anterior cuando haya conflicto. Mantén las demás reglas: "
+        "una sola frase breve en español, en modo declarativo, sin acotaciones, y no inventes nada "
+        "que no esté en el clip."
+    ),
+    "French": (
+        " La personne qui a vécu ce moment te demande de le raconter d'une manière précise : "
+        "«{context}». Laisse cela définir la voix, l'ambiance et le registre de la "
+        "narration ; cela prime sur le ton neutre et monotone ci-dessus en cas de "
+        "conflit. Garde les autres règles : "
+        "une seule phrase courte en français, au mode déclaratif, sans didascalies, et n'invente "
+        "rien qui ne soit dans le plan."
+    ),
+}
+
+# Text-only (system, user) title prompts — a SEPARATE pass (return_audio=False) so the Talker never
+# speaks JSON braces (the §7 #2 constraint). Output is run through clean_model_title.
+_TITLE_SYS_EN = (
+    "You are a film editor. Watch the clip and give a short, evocative title for this moment, "
+    "between two and five words. Output ONLY the title — no quotation marks, no surrounding "
+    "punctuation, and no explanation."
+)
+TITLE_PROMPTS: dict[str, tuple[str, str]] = {
+    "English": (_TITLE_SYS_EN, "Title this moment."),
+    "Spanish": (
+        "Eres montador de cine. Observa el clip y propón un título breve y evocador para este "
+        "momento, de dos a cinco palabras. Devuelve SOLO el título, sin comillas, sin signos de "
+        "puntuación alrededor y sin explicaciones. Escribe el título en español.",
+        "Titula este momento.",
+    ),
+    "French": (
+        "Tu es monteur de cinéma. Regarde le plan et propose un titre court et évocateur pour ce "
+        "moment, de deux à cinq mots. Renvoie UNIQUEMENT le titre, sans guillemets, sans "
+        "ponctuation autour et sans explication. Rédige le titre en français.",
+        "Donne un titre à ce moment.",
+    ),
+}
+
+
+def has_carrier(language: str) -> bool:
+    """True when a warm-up carrier AND its instruction exist → enable the carrier+cut path;
+    otherwise the narration is published untrimmed (no aligner hop)."""
+    return language in PRIME_CARRIER and language in PRIME_INSTRUCTION
+
+
+def clean_context(context: str) -> str:
+    """Strip and cap the free-text manner steer; collapse internal whitespace.
+
+    Empty/whitespace-only input returns "" so the steer is a true no-op (the deadpan default
+    prompt stays byte-identical). Capped to ``MAX_CONTEXT_CHARS`` to bound this public,
+    anonymous free-text before it reaches the model's instruction context (prompt-injection
+    surface)."""
+    return " ".join((context or "").split())[:MAX_CONTEXT_CHARS]
+
+
+def build_narration_prompts(language: str, *, prime: bool, context: str = "") -> tuple[str, str]:
+    """Return the (system, user) narration prompt for ``language``.
+
+    Native languages use their hand-tuned pair; anything else falls back to the English deadpan
+    base plus "Write the narration in {language}.". A non-empty ``context`` (the upload manner
+    steer) is appended to the system prompt as a HOW-it's-told directive; an empty ``context``
+    leaves the prompt byte-identical to the ear-ratified default. When ``prime`` and a carrier
+    exists, the carrier instruction is appended LAST (after any context) so the Talker still opens
+    with the carrier verbatim and the aligner trim is unaffected.
+    """
+    if language in NATIVE_PROMPTS:
+        system, user = NATIVE_PROMPTS[language]
+    else:
+        system = f"{DEADPAN_SYS} Write the narration in {language}."
+        user = USER_PROMPT
+    steer = clean_context(context)
+    if steer:
+        template = CONTEXT_INSTRUCTION.get(language, CONTEXT_INSTRUCTION["English"])
+        system = f"{system}{template.format(context=steer, language=language)}"
+    if prime and has_carrier(language):
+        system = f"{system} {PRIME_INSTRUCTION[language].format(carrier=PRIME_CARRIER[language])}"
+    return system, user
+
+
+def build_title_prompts(language: str) -> tuple[str, str]:
+    """Return the (system, user) prompt for the text-only title pass.
+
+    Native languages use their hand-tuned pair; anything else falls back to the English title system
+    plus "Write the title in {language}.".
+    """
+    if language in TITLE_PROMPTS:
+        return TITLE_PROMPTS[language]
+    return f"{_TITLE_SYS_EN} Write the title in {language}.", "Title this moment."
+
+
+_TITLE_LABEL_RE = re.compile(r"^(title|titre|t[íi]tulo)\s*[:：\-–—]\s*", re.IGNORECASE)
+_TITLE_WRAPPERS = " \t*_`\"'«»“”‘’#"
+
+
+def clean_model_title(raw: str, *, fallback: str) -> str:
+    """Normalize the text-only title pass into a bare title; fall back on malformed/empty output.
+
+    The model is asked to emit only the title, but we tolerate quotes, markdown bold/headers, a
+    leading "Title:"/"Titre:"/"Título:" label, a trailing parenthetical gloss on a second line, and
+    trailing punctuation. Returns the first line that yields a non-empty title after cleaning; if
+    none does, returns ``fallback`` (the derive_title-of-narration the contract allows). Always
+    capped to TITLE_MAX.
+    """
+    for line in (raw or "").splitlines() or [""]:
+        candidate = line.strip(_TITLE_WRAPPERS)
+        candidate = _TITLE_LABEL_RE.sub("", candidate).strip(_TITLE_WRAPPERS)
+        candidate = " ".join(candidate.split())
+        candidate = candidate.rstrip(".,;:!?·。").strip(_TITLE_WRAPPERS).strip()
+        if candidate:
+            return candidate[:TITLE_MAX]
+    # The contract allows an empty title, but a blank slate reads badly; guarantee non-empty even
+    # when the derive_title fallback is also empty (the empty-narration degenerate case).
+    return (fallback or "").strip()[:TITLE_MAX] or "Untitled"
+
+
 def build_narrated_scene(
     *,
     narration: str,
@@ -101,6 +303,15 @@ def carrier_cut_index(words: list[dict[str, Any]], carrier: str) -> tuple[float,
     return (float(words[-1]["t_end"]), len(words) - 1) if words else (0.0, -1)
 
 
+def has_speech_content(text: str) -> bool:
+    """True when ``text`` has at least one alphanumeric (speech) character.
+
+    Used to reject a punctuation-only carrier-cut tail — if the aligner segments a lone "." as the
+    only word after the carrier, the trim must fall back to the untrimmed take rather than publish a
+    near-empty narration."""
+    return bool(_norm(text or ""))
+
+
 def cues_from_words(
     words: list[dict[str, Any]],
     *,
@@ -126,6 +337,24 @@ def cues_from_words(
     return cues
 
 
+def plan_carrier_cut(
+    words: list[dict[str, Any]], carrier: str
+) -> tuple[float, str, list[dict[str, Any]]]:
+    """Pure planner for the warm-up trim, given an aligned word list.
+
+    Finds where the spoken ``carrier`` ends and returns ``(t_cut, real_text, timed_captions)``:
+    the cut time, the narration with the carrier dropped, and caption cues rebased so t=0 is the
+    trimmed audio. When the post-carrier tail has no speech (a lone aligner punctuation token),
+    returns ``("" , [])`` for text+captions — signalling the caller to publish the untrimmed take
+    with no captions (rebased cues would be misaligned against the untrimmed wav). GPU-free so the
+    Modal aligner's non-model logic is unit-testable."""
+    t_cut, idx = carrier_cut_index(words, carrier)
+    real_text = " ".join(w["word"] for w in words[idx + 1 :]).strip()
+    if not has_speech_content(real_text):
+        return t_cut, "", []
+    return t_cut, real_text, cues_from_words(words, start_index=idx + 1, t_offset=t_cut)
+
+
 def publish_scene(
     uploader: Uploader,
     *,

src/small_cuts/viewer.py

@@ -185,6 +185,12 @@ footer { display: none !important; }
   color: #f3efe4; border-radius: 9px; padding: 11px 16px; font-family: 'Spectral', serif;
   font-size: 1.04rem; line-height: 1.38; text-shadow: 0 1px 2px rgba(0,0,0,.85); }
 .sc-subtitle .sc-sub-line[hidden] { display: none; }
+/* CC captions default OFF (voice-first thesis); shown only when the viewer opts in. The gate lives
+   on <body> so the preference survives the per-scene re-render of #sc-subtitle. */
+body:not(.sc-cc-on) .sc-subtitle { display: none; }
+.sc-cc-btn.sc-icbtn { color: #1a1a1f !important; font-size: .72rem !important; font-weight: 700;
+  letter-spacing: .04em; -webkit-mask-image: none !important; mask-image: none !important; }
+body.sc-cc-on .sc-cc-btn.sc-icbtn { background-color: #D4AF37 !important; }
 
 .sc-rec { position: absolute; top: 12px; left: 12px; display: inline-flex; align-items: center;
   gap: 7px; background: rgba(16,16,20,.78); color: #D4AF37; padding: 4px 11px;
@@ -782,6 +788,7 @@ def format_stage(
             "live": False,
             "visibility": None,
             "source_icon": None,
+            "timed_captions": None,
         }
     base = engine_url.rstrip("/")
 
@@ -803,6 +810,7 @@ def format_stage(
         "live": is_fresh(scene.get("created_at"), now=now),
         "visibility": scene.get("visibility"),
         "source_icon": _source_icon(scene),
+        "timed_captions": scene.get("timed_captions"),
     }
 
 
@@ -867,11 +875,16 @@ def render_stage_html(
     clip_src: str | None = None,
     duration: float | None = None,
     source_icon: str | None = None,
+    timed_captions: list[dict[str, Any]] | None = None,
 ) -> str:
     """The 9:16 stage: the moment (video clip or still frame) + lower-third caption.
 
     `live` is retained for signature stability — the live/finished state now lives in the
     header ("Happening now" vs. the auto-title), not a REC chip on the stage.
+
+    `timed_captions` are the aligner's real word-timed cues (object-shaped {t_start,t_end,text}).
+    When present they are converted to the painter's tuple shape [start,end,text] and preferred
+    over the even-window `caption_cues` derivation (used as the fallback for seed/v1 scenes).
     """
     if clip_src:
         poster = f' poster="{html.escape(frame_src, quote=True)}"' if frame_src else ""
@@ -887,7 +900,11 @@ def render_stage_html(
         body = '<div class="sc-stage-empty">🎬</div>'
     if caption and caption.strip():
         chunks = [chunk for chunk in _subtitle_chunks(caption.strip()) if chunk.strip()]
-        cues = caption_cues(caption, duration)
+        if timed_captions:
+            # Real aligner cues → tuple shape [start, end, text] the JS painter (cue[0/1/2]) reads.
+            cues = [[c["t_start"], c["t_end"], c["text"]] for c in timed_captions]
+        else:
+            cues = caption_cues(caption, duration)
         first_caption = cues[0][2] if cues else (chunks[0] if chunks else caption.strip())
         dur_attr = f' data-duration="{float(duration):.1f}"' if duration else ""
         # Timed cues (when the scene's duration is known server-side) are preferred by the painter;
@@ -1113,6 +1130,7 @@ def poll_engine(
         clip_src=payload["clip_src"],
         duration=payload["duration"],
         source_icon=payload["source_icon"],
+        timed_captions=payload.get("timed_captions"),
     )
     feed = render_feed_html([feed_entry(scene) for scene in scenes[-FEED_LIMIT:]])
 
@@ -1237,6 +1255,7 @@ def _go_live_handler(
             clip_src=payload["clip_src"],
             duration=payload["duration"],
             source_icon=payload["source_icon"],
+            timed_captions=payload.get("timed_captions"),
         ),
         render_feed_html([feed_entry(s) for s in scenes[-FEED_LIMIT:]]),
         local_shelf_items(scenes),
@@ -1351,6 +1370,7 @@ def _engine_scene_control_outputs(
             clip_src=payload["clip_src"],
             duration=payload["duration"],
             source_icon=payload["source_icon"],
+            timed_captions=payload.get("timed_captions"),
         ),
         audio_update,
         _pack_engine_ui_state(
@@ -1417,6 +1437,7 @@ def _submit_modal_upload(
                 video_path,
                 style_key=style_key,
                 language=language,
+                context=scene_hint,
             )
         else:
             raw_scene = _modal_upload_client().submit_video(
@@ -1447,6 +1468,7 @@ def _submit_modal_upload(
             clip_src=payload["clip_src"],
             duration=payload["duration"],
             source_icon=payload["source_icon"],
+            timed_captions=payload.get("timed_captions"),
         ),
         render_feed_html([feed_entry(s) for s in scenes[-FEED_LIMIT:]]),
         _audio_html(payload["audio_src"]) if payload["audio_src"] else gr.skip(),
@@ -1971,6 +1993,19 @@ PLAYBACK_SYNC_JS = """
     togglePlayback(e);
   }, true);
 
+  // CC captions: a persisted, voice-first-OFF toggle. The button has no Gradio handler — flip a
+  // body-level class (which survives the per-scene re-render of #sc-subtitle) and remember the
+  // choice in localStorage. CSS hides .sc-subtitle unless body has .sc-cc-on.
+  const scReadCcPref = () => {
+    try { return window.localStorage.getItem('scCc') === '1'; } catch (e) { return false; }
+  };
+  if (scReadCcPref()) document.body.classList.add('sc-cc-on');
+  document.addEventListener('click', (e) => {
+    if (!(e.target.closest && e.target.closest('.sc-cc-btn'))) return;
+    const on = document.body.classList.toggle('sc-cc-on');
+    try { window.localStorage.setItem('scCc', on ? '1' : '0'); } catch (err) {}
+  }, true);
+
   // R4 + R5: between "Make the cut" and the buffered reveal the user sees ONLY the
   // clapperboard loader. We mount the loader over the stage when the Narrate button is tapped,
   // keep it (re-mounting it when Gradio swaps in the result stage) until the result <video> is
@@ -2155,6 +2190,7 @@ def build_viewer_app() -> gr.Blocks:
             clip_src=boot["clip_src"],
             duration=boot["duration"],
             source_icon=boot["source_icon"],
+            timed_captions=boot.get("timed_captions"),
         )
         boot_audio = _audio_html(boot["audio_src"])
 
@@ -2226,6 +2262,9 @@ def build_viewer_app() -> gr.Blocks:
                         padding=False,
                     )
                     forward_btn = gr.Button("", elem_classes=["sc-icbtn", "sc-ico-forward"])
+                    # CC: soft caption toggle. No Python handler — PLAYBACK_SYNC_JS flips a
+                    # persisted body class (delegated DOM click), like the play gesture.
+                    gr.Button("CC", elem_classes=["sc-icbtn", "sc-cc-btn"])
                     if client is None:
                         # like (honest no-count toggle) + flag now live in the pill, aligned
                         # with the controls (Review-3 #2 — no longer orphaned below).
@@ -2475,6 +2514,7 @@ def build_viewer_app() -> gr.Blocks:
                                     clip_src=payload["clip_src"],
                                     duration=payload["duration"],
                                     source_icon=payload["source_icon"],
+                                    timed_captions=payload.get("timed_captions"),
                                 ),
                                 render_feed_html(
                                     [feed_entry(scene) for scene in scenes[-FEED_LIMIT:]]
@@ -2764,6 +2804,7 @@ def build_viewer_app() -> gr.Blocks:
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
                         source_icon=payload["source_icon"],
+                        timed_captions=payload.get("timed_captions"),
                     ),
                     _audio_html(payload["audio_src"]),
                     payload["scene_id"],
@@ -2787,6 +2828,7 @@ def build_viewer_app() -> gr.Blocks:
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
                         source_icon=payload["source_icon"],
+                        timed_captions=payload.get("timed_captions"),
                     ),
                     _audio_html(payload["audio_src"]),
                     None,
@@ -2813,6 +2855,7 @@ def build_viewer_app() -> gr.Blocks:
                         clip_src=payload["clip_src"],
                         duration=payload["duration"],
                         source_icon=payload["source_icon"],
+                        timed_captions=payload.get("timed_captions"),
                     ),
                     _audio_html(payload["audio_src"]),
                     scene["scene_id"],
@@ -2873,6 +2916,7 @@ def build_viewer_app() -> gr.Blocks:
                             clip_src=payload["clip_src"],
                             duration=payload["duration"],
                             source_icon=payload["source_icon"],
+                            timed_captions=payload.get("timed_captions"),
                         ),
                         render_feed_html([feed_entry(s) for s in scenes[-FEED_LIMIT:]]),
                         local_shelf_items(scenes),