@remixmate/cli 0.9.44 → 0.9.45

package/skills/template-registry/scripts/payload_hydrator.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Fill a template-declared ``customPayload`` field from a source document, by reference.
+
+问题（2026-09-23 线上 conv_Sesw2g8oM81 的根因）
+---------------------------------------------
+``ppt-to-video`` 要求每个场景都有 ``customPayload.slide`` —— 一整页 PPT 的节点树、
+坐标、配色、beats。这份数据只有一个合法产出方（ab-render 的 ``/extract`` layout 层），
+而它**体积大到不能过模型**：一页带内嵌图标可达几百 KB，23 页就是好几 MB。
+
+于是模板的 llmHint 写着「把返回的 slides[i].slide 整个填进 customPayload.slide」，
+doc-parse 的 SKILL.md 写着「feed slides[i] straight into customPayload.slide」，而实际
+链路是：doc_parse 把全量写进本地文件 → 模型没有任何文件读取工具 → 拿不到 → 
+prepare_video_assets 报 ``customPayload.slide (required)`` ×N。模型无论怎么改都过不了。
+
+解法
+----
+**不让这份数据过模型**。DSL 里只留一个引用（``meta.sourceDocument``），skill 侧在
+校验之前自己去把全量取回来填进每个场景。模型负责的是它真正能负责的东西：旁白、
+场景与页的对应关系、以及 mode 的下压。
+
+这与 ``extractCustomPayloadOverrides`` / ``extractNarrationOverrides`` 是同一类教训的
+第三次：**合并层丢掉了数据，而下游报的错指向模型**。前两次丢的是 slideId 和 items。
+
+模板怎么声明
+-----------
+``template.json`` 的 ``capabilities.payloadHydration``::
+
+    "payloadHydration": {
+      "payloadField": "slide",        # 要填的 customPayload 字段名
+      "source": "doc-extract",        # 数据来源（目前只有这一个）
+      "docKind": "pptx",
+      "fields": "content,layout",     # 传给 /extract 的层
+      "indexField": "slideIndex"      # 场景→页的映射键（写在 customPayload 里）
+    }
+
+不写 ``if template_id == "ppt-to-video"``（AGENTS.md 明令禁止）：任何模板声明了这一段
+就自动获得同样的行为。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Callable, Optional
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from doc_extract import (  # noqa: E402
+    DocExtractError,
+    extract_document,
+    slides_by_index,
+)
+
+SUPPORTED_SOURCES = ("doc-extract",)
+
+DEFAULT_INDEX_FIELD = "slideIndex"
+
+
+class HydrationError(RuntimeError):
+    """注入失败。message 必须直接告诉调用方下一步做什么。
+
+    这个类存在的全部意义是替换掉 ``customPayload.slide (required)`` ×20 那种报错 ——
+    它说的是"某个字段没填"，而真相是"这个字段的数据源没有通路"，两者要采取的行动
+    完全不同，而模型只看得到前者。
+    """
+
+
+def hydration_spec(template_config: Optional[dict]) -> Optional[dict]:
+    """读 ``capabilities.payloadHydration``；未声明 / 声明无效返回 None。
+
+    宽容读取：一个写坏的 template.json 不该让所有模板的渲染一起失败。但
+    ``source`` 认不出来时要报错而不是静默跳过 —— 静默跳过会退回到「必填字段缺失」
+    那条死路，也就是这个模块本来要修掉的东西。
+    """
+    caps = (template_config or {}).get("capabilities")
+    if not isinstance(caps, dict):
+        return None
+    spec = caps.get("payloadHydration")
+    if not isinstance(spec, dict) or not spec:
+        return None
+
+    payload_field = spec.get("payloadField")
+    if not isinstance(payload_field, str) or not payload_field:
+        return None
+
+    source = spec.get("source") or "doc-extract"
+    if source not in SUPPORTED_SOURCES:
+        raise HydrationError(
+            f"template declares capabilities.payloadHydration.source='{source}', which this "
+            f"version of remixmate does not implement (supported: {', '.join(SUPPORTED_SOURCES)}). "
+            "Upgrade @remixmate/cli or fix the template."
+        )
+
+    index_field = spec.get("indexField")
+    return {
+        "payload_field": payload_field,
+        "source": source,
+        "doc_kind": spec.get("docKind") or "pptx",
+        "fields": spec.get("fields") or "content,layout",
+        "index_field": index_field if isinstance(index_field, str) and index_field else DEFAULT_INDEX_FIELD,
+    }
+
+
+def source_document_ref(dsl: dict, override_url: Optional[str] = None) -> Optional[dict]:
+    """取 DSL 里的源文件引用。``override_url`` 优先（CLI 显式传入时）。
+
+    位置是 ``meta.sourceDocument`` 而不是场景级：一条片子对一份源文件，写在场景里
+    会得到 23 份同样的 URL，还得处理它们互相矛盾的情况。
+
+    为什么是 ``meta``：ab-agent 的合并层（``applyNarrationToSkeleton``）以 gen_script
+    骨架为基底，只从模型提交的 DSL 里搬 narration 与 customPayload，``meta`` / ``global``
+    归骨架所有。所以写在 meta 的引用能活着穿过合并层，而模型自己往 dsl_json 里写
+    ``meta.sourceDocument`` 会被丢掉 —— 引用必须在 gen_script 那一步就进骨架。
+    """
+    if override_url:
+        return {"url": override_url}
+    meta = dsl.get("meta")
+    if not isinstance(meta, dict):
+        return None
+    ref = meta.get("sourceDocument")
+    if isinstance(ref, str) and ref.strip():
+        return {"url": ref.strip()}
+    if isinstance(ref, dict) and isinstance(ref.get("url"), str) and ref["url"].strip():
+        return {"url": ref["url"].strip(), "kind": ref.get("kind")}
+    return None
+
+
+def _scene_payload(scene: dict) -> dict:
+    payload = scene.get("customPayload")
+    if not isinstance(payload, dict):
+        payload = {}
+        scene["customPayload"] = payload
+    return payload
+
+
+def hydrate_dsl(
+    dsl: dict,
+    template_config: Optional[dict],
+    *,
+    override_url: Optional[str] = None,
+    log: Optional[Callable[[str], None]] = None,
+) -> list[str]:
+    """把源文件的每一页填进对应场景的 ``customPayload.<payloadField>``。
+
+    返回一份给人看的报告行列表（调用方自己决定打到哪）。什么都没做时返回空列表。
+
+    映射规则：场景的 ``customPayload.<indexField>`` 是 1-based 页号，缺省按场景顺序
+    取第 i 页。显式页号优先 —— 用户可能只讲其中几页，或者把两页并成一个场景。
+
+    已有值不覆盖：场景里已经有 ``customPayload.slide`` 时跳过。直接调 CLI 的调试流程
+    会手动塞一份进去，把它冲掉等于让调试者的输入人间蒸发。
+    """
+    emit = log or (lambda _msg: None)
+
+    spec = hydration_spec(template_config)
+    if not spec:
+        return []
+
+    scenes = [s for s in (dsl.get("scenes") or []) if isinstance(s, dict)]
+    if not scenes:
+        return []
+
+    field = spec["payload_field"]
+    index_field = spec["index_field"]
+
+    pending = [s for s in scenes if _scene_payload(s).get(field) is None]
+    if not pending:
+        return [f"customPayload.{field} already present on all {len(scenes)} scene(s); nothing to hydrate"]
+
+    ref = source_document_ref(dsl, override_url)
+    if not ref:
+        template_id = ((dsl.get("meta") or {}).get("templateId")) or "this template"
+        raise HydrationError(
+            f"{len(pending)} of {len(scenes)} scene(s) need customPayload.{field}, and "
+            f"'{template_id}' builds it from the source document rather than from hand-written JSON — "
+            "but the DSL carries no source document reference.\n"
+            "   This field is intentionally NOT something you author: one page of layout data is "
+            "hundreds of KB, so it never travels through the conversation.\n"
+            f"   Fix: pass the document URL once and the pipeline fills all {len(scenes)} scenes itself.\n"
+            "     • preferred — call gen_script with --source-document-url <url> so the reference is "
+            "recorded in meta.sourceDocument\n"
+            "     • or pass --source-document-url <url> to this call directly\n"
+            "   The URL is the same .pptx you gave doc_parse."
+        )
+
+    kind = ref.get("kind") or spec["doc_kind"]
+    emit(f"🧩 hydrating customPayload.{field} from the source document ({kind}, fields={spec['fields']})")
+
+    try:
+        result = extract_document(
+            ref["url"], kind=kind, fields=spec["fields"], log=emit
+        )
+    except DocExtractError as exc:
+        raise HydrationError(
+            f"could not read the source document needed for customPayload.{field}: {exc}"
+        ) from exc
+
+    pages = slides_by_index(result)
+    if not pages:
+        raise HydrationError(
+            f"the source document extraction returned no pages, so customPayload.{field} "
+            "cannot be filled. Check that the URL points at the .pptx file itself."
+        )
+
+    report: list[str] = []
+    filled = 0
+    missing: list[str] = []
+
+    for position, scene in enumerate(scenes, start=1):
+        payload = _scene_payload(scene)
+        if payload.get(field) is not None:
+            continue
+        declared = payload.get(index_field)
+        page_no = declared if isinstance(declared, int) and declared > 0 else position
+        page = pages.get(page_no)
+        if page is None:
+            missing.append(f"scene {scene.get('id', position)} → page {page_no}")
+            continue
+        payload[field] = page
+        # 把页号写回去，让 RenderPlan 里留下"这一场用的是第几页"的痕迹。
+        payload.setdefault(index_field, page_no)
+        filled += 1
+
+    source_meta = result.get("source") or {}
+    report.append(
+        f"✅ filled customPayload.{field} on {filled}/{len(scenes)} scene(s) from "
+        f"{source_meta.get('slideCount', len(pages))} page(s) of "
+        f"{source_meta.get('name', 'the source document')}"
+    )
+
+    if missing:
+        # 页号对不上不是警告而是错误：少一页 = 成片里一个空白场景，而它渲得出来。
+        raise HydrationError(
+            f"{len(missing)} scene(s) point at a page that the source document does not have "
+            f"({'; '.join(missing[:5])}"
+            f"{f'; … {len(missing)} total' if len(missing) > 5 else ''}).\n"
+            f"   The document has {len(pages)} page(s). Either lower the scene count to match, "
+            f"or fix customPayload.{index_field} on those scenes."
+        )
+
+    # 降级记录要顺着传上来 —— 画面上少一块，这里不说就没人知道为什么。
+    flagged = [
+        f"page {no}: {'; '.join(page.get('flags') or [])}"
+        for no, page in sorted(pages.items())
+        if page.get("flags")
+    ]
+    if flagged:
+        report.append(
+            "⚠️  the extractor refused to reconstruct some elements (they render as an "
+            "approximation): " + " | ".join(flagged[:5])
+        )
+
+    return report

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V18",
+  "version": "V20",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -29,6 +29,35 @@ VALID_RATIOS = {"16:9", "9:16", "1:1", "4:3", "3:4", "21:9"}
 VALID_RESOLUTIONS = {"480p", "720p", "1080p", "4k"}
 VALID_PURPOSES = {"opening", "intro", "point", "example", "explanation", "transition", "highlight", "cta", "ending"}
 VALID_LAYOUTS = {"full-visual", "split-left-right", "split-top-bottom", "picture-in-picture", "text-overlay", "avatar-with-bg", "kenburns"}
+
+# 场景数上限的兜底值。叙事弧类模板的合理上界——20 段以上的短视频必然过碎。
+# "一页素材一个场景"的模板（ppt-to-video）场景数由源文件页数决定，应当用
+# ``capabilities.maxScenes`` 抬高；这个常量只是没声明时的默认。
+DEFAULT_MAX_SCENES = 20
+
+# 声明式上界的上界。模板可以抬高 maxScenes，但不能抬到无限——一次请求排上千个场景
+# 会在下游（TTS 逐场景合成、Remotion 逐场景渲染）变成一次谁也杀不掉的长任务。
+MAX_SCENES_CEILING = 200
+
+
+def max_scenes_for_template(template_config: Optional[dict]) -> int:
+    """模板声明的场景数上限，缺省 ``DEFAULT_MAX_SCENES``。
+
+    单一实现：gen-script 规划场景时用它决定 clamp 到几，dsl_validator 用它做门禁。
+    两边各写一份 ``min(n, 20)`` 正是这个仓库反复栽的那种跟头。
+
+    宽容读取：非正整数、非数字、capabilities 缺失一律回落到默认值，不抛异常——
+    一个写坏的 template.json 不该让所有模板的场景规划一起失败。
+    """
+    caps = (template_config or {}).get("capabilities")
+    if not isinstance(caps, dict):
+        return DEFAULT_MAX_SCENES
+    declared = caps.get("maxScenes")
+    if isinstance(declared, bool) or not isinstance(declared, int):
+        return DEFAULT_MAX_SCENES
+    if declared < 1:
+        return DEFAULT_MAX_SCENES
+    return min(declared, MAX_SCENES_CEILING)
 VALID_ASSET_TYPES = {"image", "video", "audio", "avatar", "subtitle", "bgm"}
 VALID_ASSET_SOURCES = {"existing", "gen-image", "gen-video", "gen-voice", "gen-digital-human"}
 
@@ -245,14 +274,30 @@ def _check_scenes_min(dsl: dict) -> list[ValidationError]:
 
 
 def _check_scenes_max(dsl: dict) -> list[ValidationError]:
-    """Scenes 上限 20。仅 gen-script 历史规则集 + 完整版用——render-video
+    """Scenes 上限。仅 gen-script 历史规则集 + 完整版用——render-video
     历史不查上限,合并时若同时启用此检查会"原本能过的 DSL 现在被拒",
     故只在 ``validate_structural`` / ``validate_dsl`` 启用。
+
+    上限由模板的 ``capabilities.maxScenes`` 声明,缺省 ``DEFAULT_MAX_SCENES``(20)。
+    20 这个数字是给"叙事弧"类模板定的——一条 60 秒短视频排到 20 段已经过碎。但
+    "一页素材一个场景"的模板(ppt-to-video 逐页讲解)的场景数由源文件页数决定,
+    跟叙事节奏无关:2026-09-23 线上一份 23 页 PPT 就是在这里被砍到 20 页,
+    而且砍得毫无声响,直到下游报 ``customPayload.slide (required)`` ×20 才暴露。
+    所以上限改成模板自己声明,并且这里的报错要说清它是谁定的。
     """
     scenes = dsl.get("scenes", [])
-    if isinstance(scenes, list) and len(scenes) > 20:
+    if not isinstance(scenes, list):
+        return []
+    template_id = _pick_template_id(dsl)
+    limit = max_scenes_for_template(_get_template_cfg(template_id))
+    if len(scenes) > limit:
+        source = (
+            f"template '{template_id}' declares capabilities.maxScenes={limit}"
+            if limit != DEFAULT_MAX_SCENES
+            else f"the default limit is {limit}; a template can raise it via capabilities.maxScenes"
+        )
         return [ValidationError(
-            "scenes", f"must contain at most 20 scenes, got {len(scenes)}",
+            "scenes", f"must contain at most {limit} scenes, got {len(scenes)} ({source})",
         )]
     return []
 
@@ -684,6 +729,90 @@ def _check_line_sync_narration(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_step_narration_alignment(dsl: dict) -> list[ValidationError]:
+    """声明「动作与旁白一一对应」的模板：动作条数应当等于旁白句数。
+
+    由模板的 ``capabilities.stepAlignment`` 声明触发,不写死模板名::
+
+        "stepAlignment": {
+          "payloadField": "steps",       # customPayload 里放动作数组的字段
+          "alignTo": "narration-sentences"
+        }
+
+    为什么值得单独查:这一类失配**渲得出来**。动作按句下标对齐,条数不等时多出的
+    句子没有任何动作(画面停住)或多出的动作挤在最后一句上,而退出码是 0、
+    renderJob 是 completed、漏斗记 rendered —— 缺陷只存在于成片里,没有任何
+    自动信号会告状。2026-09-23 线上那条鸡兔同笼就是这么交付的。
+
+    严重度是 **warning**:步数少于句数有时确实是作者的本意(末尾一句总结不配动作)。
+    真正要判断的是"作者以为一一对应、实际不是",只有作者做得了这个判断,所以这里
+    给两个数字,不给结论。但它必须被打出来 —— 上一版连数字都没有。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    caps = tpl.get("capabilities")
+    spec = caps.get("stepAlignment") if isinstance(caps, dict) else None
+    if not isinstance(spec, dict):
+        return []
+    field = spec.get("payloadField")
+    if not isinstance(field, str) or not field:
+        return []
+    if spec.get("alignTo") not in (None, "narration-sentences"):
+        return []
+
+    try:
+        from .timeline_compiler import count_narration_sentences
+    except ImportError:
+        return []
+
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload")
+        if not isinstance(custom, dict):
+            continue
+        steps = custom.get(field)
+        if not isinstance(steps, list) or not steps:
+            continue  # 不给 steps 走模板自己的兜底,不是本检查的事
+
+        # 全部显式写了 atSec 的步骤不参与下标对齐,不该算失配。
+        # 排除 bool:Python 里 True 是 int 的实例,而渲染端用 `typeof === "number"`
+        # 判断,不认 true。两边口径必须一致,否则这里放行的东西那边仍按下标对齐。
+        def _has_explicit_at_sec(step: object) -> bool:
+            if not isinstance(step, dict):
+                return False
+            at = step.get("atSec")
+            return isinstance(at, (int, float)) and not isinstance(at, bool)
+
+        if all(_has_explicit_at_sec(s) for s in steps):
+            continue
+
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        text = narration.get("text")
+        if not isinstance(text, str) or not text.strip():
+            continue
+        sentences = count_narration_sentences(text)
+        if sentences == 0 or len(steps) == sentences:
+            continue
+
+        sid = scene.get("id", f"scenes[{idx}]")
+        tail = (
+            f"最后 {sentences - len(steps)} 句旁白没有对应动作,画面会在那之前走完并停住"
+            if len(steps) < sentences
+            else f"多出的 {len(steps) - sentences} 个动作会挤在最后一句上"
+        )
+        errors.append(ValidationError(
+            f"scenes[{idx}].customPayload.{field}",
+            f"scene '{sid}': {len(steps)} 个动作 vs 旁白 {sentences} 句 —— {tail}。"
+            f"本模板的动作按**句**对齐(第 i 个动作 = 第 i 句的起拍帧),"
+            f"要一一对应就让两者等数;确实想不等就忽略这条(它不阻断渲染)。"
+            f"注意句数按句末标点(。！？；)统计,一句里放两个句末标点会被数成两句。",
+            severity="warning",
+        ))
+
+    return errors
+
+
 def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
     """逐版式校验 ``customPayload.templateData`` 的字段名。
 
@@ -1055,6 +1184,9 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_payload_fields(dsl)
     errors += _check_custom_payload_fields(dsl)
     errors += _check_line_sync_narration(dsl)
+    # warning,不阻断。放在 integrity 里是因为这是 render-video 的入口:失配的后果
+    # 是**渲得出来但错位**,只有在真要渲之前说才来得及。
+    errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     return errors
 
@@ -1088,5 +1220,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_payload_fields(dsl)
     errors += _check_custom_payload_fields(dsl)
     errors += _check_line_sync_narration(dsl)
+    errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     return errors

package/skills/template-registry/video_dsl/runtime/timeline_compiler.py

@@ -171,6 +171,49 @@ def _merge_short(segments: list[str], min_len: int) -> list[str]:
     return merged
 
 
+def assign_sentence_indices(raw_texts: list[str]) -> list[int]:
+    """给每个字幕/TTS 段标注它属于原旁白的第几**句**（0-based）。
+
+    为什么必须单独标：一段 **不等于** 一句。``segment_narration`` 在句末断行之后，
+    还会把超过 ``MAX_SEGMENT_CHARS`` 的长句在逗号处继续切 —— 那是为了让 TTS 按真实
+    停顿返回时间戳，跟"句"没关系。于是 35 字的一句话会变成 3 段。
+
+    靠下标把「第 i 个动作」对齐到「第 i 段字幕」的模板（math-principles-expl 的
+    ``steps``、ppt-to-video 的 ``beats``）因此会整体错位，而且是**静默**的：
+    2026-09-23 线上一条鸡兔同笼成片里 10 句旁白被切成约 19 段，板面 10 步在音频
+    播到一半就走完，之后画面冻结、旁白继续，全程零报错、终态 completed。
+
+    判据：一段是某句的**末段**，当且仅当它以句末标点（``。！？；`` 或换行）结尾。
+    这与 ``_PRIMARY_BREAK`` 是同一个集合 —— 切的时候用它断，标的时候用它认，
+    所以两边不会漂移。
+
+    ⚠️ 必须传**未去尾标点**的原文。``_strip_trailing_punct`` 之后句末标点就没了，
+    那时所有段都会被认成同一句。
+
+    极少数情况下一段会跨句：``_merge_short`` 为了不让 TTS 行短到丢语气，会把一个
+    过短的段向后并（比如整句只有「对吗？」三个字）。这时该段归**它起始的那一句**，
+    因为调用方要的是「这句话从哪一帧开始被说出来」。
+    """
+    indices: list[int] = []
+    sentence = 0
+    for text in raw_texts:
+        indices.append(sentence)
+        if _PRIMARY_TAIL.search(text or ""):
+            sentence += 1
+    return indices
+
+
+def count_narration_sentences(text: str) -> int:
+    """数一段旁白有多少句。与 ``assign_sentence_indices`` 同一判据。
+
+    给校验层用：模板声明「steps 与旁白一一对应」时，用它和 steps 条数比对。
+    """
+    if not text or not text.strip():
+        return 0
+    chunks = [s for s in _PRIMARY_BREAK.split(text.strip()) if s.strip()]
+    return len(chunks)
+
+
 def _plain_len(text: str) -> int:
     """计算去掉 **...** 标记后的纯文本字符数，用于更准确的时间分配。"""
     return len(_EMPHASIS_MARKS.sub("", text))
@@ -232,15 +275,18 @@ def split_subtitle_from_lines(
         max(duration_frames - 2 * padding_frames, fps),
         max(estimated_audio_frames, fps),
     )
+    # 句归属必须在去尾标点**之前**算 —— 去掉「。」之后就认不出句末了。
+    sentence_indices = assign_sentence_indices(segments)
     result: list[dict] = []
     current_frame = padding_frames
-    for seg in segments:
+    for i, seg in enumerate(segments):
         ratio = _plain_len(seg) / total_chars
         frames = max(int(usable_frames * ratio), fps // 2)
         result.append({
             "text": _strip_trailing_punct(seg.strip()),
             "startFrame": current_frame,
             "endFrame": current_frame + frames,
+            "sentenceIndex": sentence_indices[i],
         })
         current_frame += frames
     return result
@@ -262,15 +308,18 @@ def split_subtitle(text: str, duration_frames: int, fps: int, padding_frames: in
         max(duration_frames - 2 * padding_frames, fps),
         max(estimated_audio_frames, fps),
     )
+    # 句归属必须在去尾标点**之前**算（见 assign_sentence_indices）。
+    sentence_indices = assign_sentence_indices(segments)
     result: list[dict] = []
     current_frame = padding_frames
-    for seg in segments:
+    for i, seg in enumerate(segments):
         ratio = _plain_len(seg) / total_plain
         frames = max(int(usable_frames * ratio), fps // 2)
         result.append({
             "text": _strip_trailing_punct(seg.strip()),
             "startFrame": current_frame,
             "endFrame": current_frame + frames,
+            "sentenceIndex": sentence_indices[i],
         })
         current_frame += frames