deploy(midcuts): per-clip style+language labels + CC restyle (contract v1.3.0)

docs/contracts/narrated-scene.schema.json

@@ -0,0 +1,223 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/macayaven/small-cuts/docs/contracts/1.3.0/narrated-scene.schema.json",
+  "title": "NarratedScene",
+  "description": "One narrated scene, produced by the engine. The SAME object is the viewer's live SSE event (D7) and the library's stored entry (D6); media fields are engine-served URLs.",
+  "type": "object",
+  "required": [
+    "captured_at",
+    "contract_version",
+    "created_at",
+    "media",
+    "moment_id",
+    "narration",
+    "scene_id",
+    "seq",
+    "session_id",
+    "style_key",
+    "title",
+    "visibility"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "enum": ["1.1.0", "1.2.0", "1.3.0"]
+    },
+    "scene_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "moment_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "style_key": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 80,
+      "description": "Model-generated short title for the slate/thumbnail text; engines may fall back to derive_title for legacy or malformed model output."
+    },
+    "narration": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "visibility": {
+      "enum": [
+        "private",
+        "shared",
+        "public"
+      ],
+      "default": "private"
+    },
+    "media": {
+      "type": "object",
+      "required": [
+        "frame_url"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "frame_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "card_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "audio_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "clip_url": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "Short viewer clip for library revisit/share, either uploaded or assembled by the engine from timestamped capture frames."
+        }
+      }
+    },
+    "persona": {
+      "type": "string",
+      "description": "Narrator persona key (e.g. nature_doc). Additive in v1.3.0; optional. Display derives the style label from it."
+    },
+    "language": {
+      "type": "string",
+      "description": "Spoken narration language (e.g. English). Additive in v1.3.0; optional."
+    },
+    "engine": {
+      "type": "object",
+      "description": "Provenance + latency breakdown (the inference team's scoreboard).",
+      "additionalProperties": false,
+      "properties": {
+        "narrator_model": {
+          "type": "string"
+        },
+        "narrator_backend": {
+          "enum": [
+            "llama_cpp",
+            "transformers",
+            "mock"
+          ]
+        },
+        "tts_model": {
+          "type": "string"
+        },
+        "latency_ms": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "queue": {
+              "type": "integer"
+            },
+            "narration": {
+              "type": "integer"
+            },
+            "tts": {
+              "type": "integer"
+            },
+            "total": {
+              "type": "integer"
+            }
+          }
+        }
+      }
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic engine event id - SSE id: field; clients resume with Last-Event-ID."
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "From the source MomentEnvelope - the library's chronology key (created_at is engine time)."
+    },
+    "owner": {
+      "type": "string",
+      "description": "Reserved for multi-user: identity that owns the scene. v1 single-user engines emit a constant."
+    },
+    "share_token": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Reserved: capability token for visibility=shared links. Enforcement spec lands with the library milestone."
+    },
+    "duration": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Authoritative playback duration in seconds — the narration/voice audio length, which is the single-clock player's clock (NOT the source-clip length). Additive in v1.2.0; optional."
+    },
+    "keyframe_time": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Offset in seconds from the start of the source clip of the producer-selected poster frame (the image itself is media.frame_url). Poster provenance, not a codec keyframe. Additive in v1.2.0; optional."
+    },
+    "timed_captions": {
+      "type": "array",
+      "description": "Speech-relative caption cues (aligner-produced) for the viewer CC track + accessibility. Times are relative to the trimmed narration audio. Additive in v1.2.0; optional.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "t_start",
+          "t_end",
+          "text"
+        ],
+        "properties": {
+          "t_start": {
+            "type": "number",
+            "minimum": 0
+          },
+          "t_end": {
+            "type": "number",
+            "minimum": 0
+          },
+          "text": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "description": "Version-truth: a v1.2.0 field requires contract_version >= 1.2.0.",
+      "if": {
+        "anyOf": [
+          { "required": ["duration"] },
+          { "required": ["keyframe_time"] },
+          { "required": ["timed_captions"] }
+        ]
+      },
+      "then": {
+        "properties": {
+          "contract_version": { "enum": ["1.2.0", "1.3.0"] }
+        }
+      }
+    },
+    {
+      "description": "Version-truth: a v1.3.0 field forces contract_version 1.3.0.",
+      "if": {
+        "anyOf": [
+          { "required": ["persona"] },
+          { "required": ["language"] }
+        ]
+      },
+      "then": {
+        "properties": {
+          "contract_version": { "const": "1.3.0" }
+        }
+      }
+    }
+  ]
+}

src/small_cuts/narrate_v2.py

@@ -24,7 +24,7 @@ from pathlib import Path
 from typing import Any, Protocol
 from uuid import uuid4
 
-CONTRACT_VERSION = "1.2.0"
+CONTRACT_VERSION = "1.3.0"
 TITLE_MAX = 80
 NARRATION_MAX = 2000
 MAX_CONTEXT_CHARS = 280
@@ -457,6 +457,8 @@ def build_narrated_scene(
     keyframe_time: float | None = None,
     scene_id: str | None = None,
     moment_id: str | None = None,
+    persona: str | None = None,
+    language: str | None = None,
 ) -> dict[str, Any]:
     """Build a NarratedScene that validates against narrated-scene.schema.json by construction.
 
@@ -486,6 +488,10 @@ def build_narrated_scene(
         scene["keyframe_time"] = keyframe_time
     if timed_captions is not None:
         scene["timed_captions"] = timed_captions
+    if persona is not None:
+        scene["persona"] = persona
+    if language is not None:
+        scene["language"] = language
     return scene
 
 

src/small_cuts/viewer.py

@@ -53,7 +53,7 @@ from .hf_relay import (
     BucketSceneClient as _BucketSceneClient,
 )
 from .modal_upload import ModalUploadClient, ModalUploadError
-from .narrate_v2 import PERSONA_DEFAULT_KEY, persona_choices, resolve_persona_steer
+from .narrate_v2 import PERSONA_DEFAULT_KEY, PERSONA_LABELS, persona_choices, resolve_persona_steer
 from .observability import capture_exception
 from .styles import DEFAULT_STYLE_KEY, STYLES
 from .title_card import derive_title
@@ -189,9 +189,11 @@ footer { display: none !important; }
 /* 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-cc-btn.sc-icbtn { color: #1a1a1f !important; font-size: .66rem !important; font-weight: 700;
+  letter-spacing: .06em; display: flex !important; align-items: center; justify-content: center;
+  -webkit-mask-image: none !important; mask-image: none !important; }
+body.sc-cc-on .sc-cc-btn.sc-icbtn { background-color: #D4AF37 !important;
+  color: #1a1a1f !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;
@@ -790,6 +792,7 @@ def format_stage(
             "visibility": None,
             "source_icon": None,
             "timed_captions": None,
+            "language": None,
         }
     base = engine_url.rstrip("/")
 
@@ -802,7 +805,10 @@ def format_stage(
     return {
         "scene_id": scene.get("scene_id"),
         "title": scene.get("title") or "Untitled Scene",
-        "style_label": _style_label(scene.get("style_key", "")),
+        "style_label": (
+            persona_display(scene.get("persona"))[1] or _style_label(scene.get("style_key", ""))
+        ),
+        "language": scene.get("language"),
         "caption": scene.get("narration", ""),
         "frame_src": scene.get("frame_src") or _absolute(media.get("frame_url")),
         "clip_src": scene.get("clip_src") or _absolute(media.get("clip_url")),
@@ -937,6 +943,7 @@ def render_header_html(
     style_label: str,
     live: bool,
     notice: str | None = None,
+    language: str | None = None,
 ) -> str:
     # One unnamed signature voice — the channel is Small Cuts, not a per-cut director.
     # style_label is retained in the call signature for future per-owner channels.
@@ -949,10 +956,15 @@ def render_header_html(
         )
     else:
         headline = '<span class="sc-live-dot"></span>Happening now' if live else html.escape(title)
+    abbr = lang_abbr(language)
+    if abbr and style_label and not live:
+        right = f"{abbr} · {html.escape(style_label)}"
+    else:
+        right = "Small Cuts"
     return (
         f'<div class="sc-header sc-{state}">'
         f'<span class="sc-header-title">{headline}</span>'
-        '<span class="sc-header-channel">Small Cuts</span>'
+        f'<span class="sc-header-channel">{right}</span>'
         "</div>"
     )
 
@@ -1048,10 +1060,31 @@ def _gallery_media_src(src: str) -> str:
     return src
 
 
+_LANG_ABBR = {"English": "EN", "Spanish": "ES", "French": "FR"}
+
+
+def lang_abbr(language: str | None) -> str:
+    """Two-letter abbreviation for a known language; "" otherwise."""
+    return _LANG_ABBR.get(language or "", "")
+
+
+def persona_display(persona: str | None) -> tuple[str, str]:
+    """(archetype, full label) for a persona key; ("", "") if unknown."""
+    label = PERSONA_LABELS.get(persona or "")
+    if not label:
+        return ("", "")
+    return (label.split(" · ", 1)[0], label)
+
+
 def _shelf_caption(scene: dict[str, Any]) -> str:
     title = scene.get("title", "")
     source_icon = _source_icon(scene)
-    return f"{_SOURCE_SHELF_PREFIXES.get(source_icon, '')}{title}"
+    caption = f"{_SOURCE_SHELF_PREFIXES.get(source_icon, '')}{title}"
+    abbr = lang_abbr(scene.get("language"))
+    archetype, _ = persona_display(scene.get("persona"))
+    if abbr and archetype:
+        caption = f"{caption} · {abbr} · {archetype}"
+    return caption
 
 
 def _scene_with_media_urls(
@@ -1122,7 +1155,11 @@ def poll_engine(
     notice = "New cut available" if channel_live and not on_air else None
 
     header = render_header_html(
-        payload["title"], payload["style_label"], live=channel_live, notice=notice
+        payload["title"],
+        payload["style_label"],
+        live=channel_live,
+        notice=notice,
+        language=payload.get("language"),
     )
     stage = render_stage_html(
         payload["frame_src"],
@@ -1248,7 +1285,9 @@ def _go_live_handler(
     return (
         # An upload is a finished, processed cut — show its auto-title, not "Happening now"
         # (that headline is reserved for live engine-mode capture).
-        render_header_html(payload["title"], payload["style_label"], live=False),
+        render_header_html(
+            payload["title"], payload["style_label"], live=False, language=payload.get("language")
+        ),
         render_stage_html(
             payload["frame_src"],
             payload["caption"],
@@ -1363,7 +1402,12 @@ def _engine_scene_control_outputs(
     else:
         audio_update = gr.skip()
     return (
-        render_header_html(payload["title"], payload["style_label"], payload["live"]),
+        render_header_html(
+            payload["title"],
+            payload["style_label"],
+            payload["live"],
+            language=payload.get("language"),
+        ),
         render_stage_html(
             payload["frame_src"],
             payload["caption"],
@@ -1413,6 +1457,11 @@ def _effective_upload_context(
     return scene_hint
 
 
+def _effective_style_key(persona_key: str, style_key: str, *, is_v2: bool) -> str:
+    """v2 carries the persona key in style_key (for display); v1 keeps its director style."""
+    return persona_key if is_v2 else style_key
+
+
 def _submit_modal_upload(
     video_path: str | None,
     style_key: str,
@@ -1473,7 +1522,9 @@ def _submit_modal_upload(
     payload = format_stage(scene)
     scene_id = payload["scene_id"]
     return (
-        render_header_html(payload["title"], payload["style_label"], live=False),
+        render_header_html(
+            payload["title"], payload["style_label"], live=False, language=payload.get("language")
+        ),
         render_stage_html(
             payload["frame_src"],
             payload["caption"],
@@ -2195,7 +2246,9 @@ def build_viewer_app() -> gr.Blocks:
         boot_audio = _audio_html(None)
     else:
         boot = format_stage(seed[-1] if seed else None)
-        boot_header = render_header_html(boot["title"], boot["style_label"], live=False)
+        boot_header = render_header_html(
+            boot["title"], boot["style_label"], live=False, language=boot.get("language")
+        )
         boot_stage = render_stage_html(
             boot["frame_src"],
             boot["caption"],
@@ -2510,7 +2563,7 @@ def build_viewer_app() -> gr.Blocks:
                     try:
                         result = _submit_modal_upload(
                             video_path,
-                            style_key,
+                            _effective_style_key(persona_key, style_key, is_v2=_modal_api_is_v2()),
                             effective_hint,
                             state,
                             engine,
@@ -2535,7 +2588,10 @@ def build_viewer_app() -> gr.Blocks:
                             payload = format_stage(saved_scene)
                             result = (
                                 render_header_html(
-                                    payload["title"], payload["style_label"], live=False
+                                    payload["title"],
+                                    payload["style_label"],
+                                    live=False,
+                                    language=payload.get("language"),
                                 ),
                                 render_stage_html(
                                     payload["frame_src"],
@@ -2827,7 +2883,12 @@ def build_viewer_app() -> gr.Blocks:
                     payload["scene_id"], liked_ids, reported_ids
                 )
                 return (
-                    render_header_html(payload["title"], payload["style_label"], payload["live"]),
+                    render_header_html(
+                        payload["title"],
+                        payload["style_label"],
+                        payload["live"],
+                        language=payload.get("language"),
+                    ),
                     render_stage_html(
                         payload["frame_src"],
                         payload["caption"],
@@ -2851,7 +2912,12 @@ def build_viewer_app() -> gr.Blocks:
                     payload["scene_id"], liked_ids, reported_ids
                 )
                 return (
-                    render_header_html(payload["title"], payload["style_label"], payload["live"]),
+                    render_header_html(
+                        payload["title"],
+                        payload["style_label"],
+                        payload["live"],
+                        language=payload.get("language"),
+                    ),
                     render_stage_html(
                         payload["frame_src"],
                         payload["caption"],
@@ -2878,7 +2944,12 @@ def build_viewer_app() -> gr.Blocks:
                     payload["scene_id"], liked_ids, reported_ids
                 )
                 return (
-                    render_header_html(payload["title"], payload["style_label"], payload["live"]),
+                    render_header_html(
+                        payload["title"],
+                        payload["style_label"],
+                        payload["live"],
+                        language=payload.get("language"),
+                    ),
                     render_stage_html(
                         payload["frame_src"],
                         payload["caption"],
@@ -2939,7 +3010,12 @@ def build_viewer_app() -> gr.Blocks:
                     scenes = _merge_scene_lists(seed, upload_library.list_scenes(limit=SHELF_LIMIT))
                     payload = format_stage(scene)
                     outputs = (
-                        render_header_html(payload["title"], payload["style_label"], live=False),
+                        render_header_html(
+                            payload["title"],
+                            payload["style_label"],
+                            live=False,
+                            language=payload.get("language"),
+                        ),
                         render_stage_html(
                             payload["frame_src"],
                             payload["caption"],