@oh-story/dsh 0.1.9 → 0.1.10

package/lib/drama/skills/short-drama-edit/scripts/edit_tool.py

@@ -91,6 +91,10 @@ PICTURE_LIMITS = {
     "warmth": (-30.0, 30.0),
 }
 TOLERANCE = 0.005
+# ffmpeg's `noise` strength runs to 100, which is snow, not grain. The useful
+# band for a finished film is single digits; the cap keeps a typo from shipping
+# a broken-signal look that measures perfectly fine.
+GRAIN_LIMIT = 20.0
 
 
 class EditError(Exception):
@@ -116,6 +120,7 @@ class Delivery(NamedTuple):
     burn_subtitles: bool
     frame_size: Optional[tuple[int, int]]
     fps: Optional[float]
+    grain: Optional[float]
 
 
 def _seconds(raw: str, *, field: str, line: int) -> float:
@@ -131,6 +136,7 @@ def _parse_delivery(lines: Sequence[str]) -> Delivery:
     burn = True
     frame_size: Optional[tuple[int, int]] = None
     fps: Optional[float] = None
+    grain: Optional[float] = None
     for raw in lines:
         match = FIELD.match(raw)
         if not match:
@@ -146,6 +152,23 @@ def _parse_delivery(lines: Sequence[str]) -> Delivery:
                 loudness = float(found.group(0))
         elif name == "字幕":
             burn = "无" != value.strip() and "不烧" not in value
+        elif name == "颗粒":
+            # Grain belongs to the delivery spec rather than to a cut, for the
+            # same reason loudness does: applied per cut it would become one
+            # more thing that differs between segments, which is the defect it
+            # is here to cover.
+            if value.strip() in {"无", "不加"}:
+                grain = None
+            else:
+                found = re.search(r"[0-9]+(?:\.[0-9]+)?", value)
+                if found:
+                    amount = float(found.group(0))
+                    if not 0.0 <= amount <= GRAIN_LIMIT:
+                        raise EditError(
+                            f"{CUT_LIST_NAME}: 颗粒 {amount} 超出 0–{GRAIN_LIMIT:g}；"
+                            "这一档以上不再像胶片，像信号故障"
+                        )
+                    grain = amount or None
         elif name == "画幅与帧率":
             size = re.search(r"([0-9]{2,5})\s*[×x*]\s*([0-9]{2,5})", value)
             if size:
@@ -153,7 +176,7 @@ def _parse_delivery(lines: Sequence[str]) -> Delivery:
             rate = re.search(r"([0-9]+(?:\.[0-9]+)?)\s*fps", value, re.I)
             if rate:
                 fps = float(rate.group(1))
-    return Delivery(target, loudness, burn, frame_size, fps)
+    return Delivery(target, loudness, burn, frame_size, fps, grain)
 
 
 def parse_cut_list(path: Path) -> tuple[Delivery, list[Cut], list[str]]:
@@ -371,8 +394,31 @@ def probe_stream(media: Path) -> dict[str, Any]:
     }
 
 
+def _unaccounted_shots(known: set[str], cuts: Sequence[Cut], unused: Sequence[str]) -> list[str]:
+    """Require each source to be used or explicitly omitted with a reason."""
+
+    used = {cut.motion for cut in cuts}
+    excused = set()
+    for note in unused:
+        match = re.fullmatch(r"(MOTION-[\w-]+)\s*[（(]理由[：:]\s*(.+?)[）)]", note.strip())
+        if match and match.group(2).strip():
+            excused.add(match.group(1))
+    missing = sorted(known - used - excused)
+    if not missing:
+        return []
+    return [
+        f"{CUT_LIST_NAME}: 以下镜头未采用，且缺少「未采用镜头」及理由："
+        + "、".join(missing)
+    ]
+
+
 def check_cuts(
-    episode: Path, cuts: Sequence[Cut], project_root: Path, *, probe: bool
+    episode: Path,
+    cuts: Sequence[Cut],
+    project_root: Path,
+    *,
+    probe: bool,
+    unused: Sequence[str] = (),
 ) -> list[str]:
     """Every mechanical cross-check the cut list can be held to. Returns findings."""
 
@@ -403,6 +449,7 @@ def check_cuts(
                     f"{CUT_LIST_NAME}:{cut.line_number}: {cut.cut_id} 的来源 "
                     f"{cut.motion} 不在《{MOTION_DOCUMENT}》中"
                 )
+        findings.extend(_unaccounted_shots(known, cuts, unused))
     else:
         findings.append(f"没有 {motion_path}，来源 MOTION 无法核对")
 
@@ -411,6 +458,7 @@ def check_cuts(
     if screenplay_path.is_file():
         screenplay = screenplay_path.read_text(encoding="utf-8")
 
+    media_format: Optional[tuple[Any, Any, float]] = None
     for cut in cuts:
         span = cut.end - cut.start
         if cut.start < 0:
@@ -430,7 +478,17 @@ def check_cuts(
                 f"{CUT_LIST_NAME}:{cut.line_number}: {cut.cut_id} 的素材不存在: {cut.media}"
             )
         elif probe:
-            available = probe_duration(media)
+            stream = probe_stream(media)
+            available = stream["duration"]
+            current_format = (stream["width"], stream["height"], stream["fps"])
+            if media_format is None:
+                media_format = current_format
+            elif current_format != media_format:
+                findings.append(
+                    f"{CUT_LIST_NAME}:{cut.line_number}: {cut.cut_id} 的画幅或帧率 "
+                    f"{current_format} 与首段 {media_format} 不一致；"
+                    "先在外部统一素材规格，再更新来源路径与入出点"
+                )
             if cut.end > available + TOLERANCE:
                 findings.append(
                     f"{CUT_LIST_NAME}:{cut.line_number}: {cut.cut_id} 出点 {cut.end:.2f} "
@@ -598,6 +656,17 @@ def render(
                 )
                 filters.append(f"ass='{escaped}'")
 
+        # Grain goes on last, over the whole assembled film, so one texture sits
+        # across every cut. `t` makes it move frame to frame — static noise reads
+        # as dirt on the lens, not as film.
+        grain = (
+            f"noise=alls={delivery.grain:g}:allf=t+u"
+            if delivery.grain is not None
+            else None
+        )
+        if grain is not None:
+            filters.append(grain)
+
         final = output_root / "成片.mp4"
         command = [ffmpeg, "-hide_banner", "-loglevel", "error", "-y", "-i", str(joined)]
         if overlay_path is not None:
@@ -605,9 +674,15 @@ def render(
             # to be named: the default one drops it and the overlay arrives as
             # an opaque black rectangle.
             command += ["-c:v", "libvpx", "-i", str(overlay_path)]
+            # The overlay branch owns its own chain, so grain is spliced in
+            # after the composite rather than left in `filters`, which this
+            # branch never reads.
+            chain = "[0:v][1:v]overlay=0:0:format=auto"
+            if grain is not None:
+                chain += f",{grain}"
             command += [
                 "-filter_complex",
-                "[0:v][1:v]overlay=0:0:format=auto,format=yuv420p[v]",
+                f"{chain},format=yuv420p[v]",
                 "-map", "[v]", "-map", "0:a",
                 "-c:v", "libx264", "-preset", "medium", "-crf", "18",
             ]
@@ -618,7 +693,7 @@ def render(
             command += ["-c:v", "copy"]
         if delivery.loudness_lufs is not None:
             command += ["-af", _loudnorm_filter(ffmpeg, joined, delivery.loudness_lufs)]
-            command += ["-c:a", "aac", "-b:a", "192k"]
+            command += ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"]
         else:
             command += ["-c:a", "copy"]
         command.append(str(final))
@@ -663,11 +738,10 @@ def _shot_match_filter(cut: Cut) -> str:
 
 
 def _loudnorm_filter(ffmpeg: str, media: Path, target: float) -> str:
-    """Two-pass EBU R128.
+    """Measure EBU R128 before normalization; verify the encoded output afterward.
 
-    One pass is a dynamic normalizer that lands several dB from the target; the
-    delivered loudness would then be a number nobody chose. Measure first, feed
-    the measurement back, and the second pass is linear.
+    FFmpeg can fall back to dynamic processing when linear gain would exceed
+    the peak or loudness-range target. Two passes do not guarantee target LUFS.
     """
 
     common = f"I={target}:TP=-1.5:LRA=11"
@@ -894,6 +968,40 @@ def _timecode(seconds: float) -> str:
     return f"{hours:02d}:{minutes:02d}:{whole:02d},{milliseconds:03d}"
 
 
+def _segment_colour(ffmpeg: str, path: Path) -> Optional[tuple[float, float]]:
+    """Mean luma and blue-red difference of one segment, on a 0-255 scale."""
+
+    result = subprocess.run(
+        [ffmpeg, "-v", "error", "-i", str(path), "-vf", "fps=2,scale=96:-1",
+         "-pix_fmt", "rgb24", "-f", "rawvideo", "-"],
+        capture_output=True,
+    )
+    raw = result.stdout
+    if result.returncode != 0 or len(raw) < 3:
+        return None
+    count = len(raw) // 3
+    red = sum(raw[i * 3] for i in range(count)) / count
+    green = sum(raw[i * 3 + 1] for i in range(count)) / count
+    blue = sum(raw[i * 3 + 2] for i in range(count)) / count
+    return 0.299 * red + 0.587 * green + 0.114 * blue, blue - red
+
+
+def _segment_colours(ffmpeg: str, output_root: Path, cuts: Sequence[Cut]) -> list[dict[str, Any]]:
+    """Report current cut segments individually, without imposing a shared grade."""
+
+    rows: list[dict[str, Any]] = []
+    for cut in cuts:
+        path = output_root / SEGMENT_DIRECTORY / f"{cut.cut_id}.mp4"
+        colour = _segment_colour(ffmpeg, path) if path.is_file() else None
+        row: dict[str, Any] = {"分段": path.name}
+        if colour is None:
+            row["测量"] = "未测（分段缺失或不可读）"
+        else:
+            row.update({"平均亮度": round(colour[0], 1), "蓝减红": round(colour[1], 1)})
+        rows.append(row)
+    return rows
+
+
 def verify(episode: Path, cuts: Sequence[Cut], delivery: Delivery) -> dict[str, Any]:
     """Measure the rendered film. Every entry is a number or an honest 未测."""
 
@@ -931,6 +1039,10 @@ def verify(episode: Path, cuts: Sequence[Cut], delivery: Delivery) -> dict[str,
     else:
         measurements["实测响度 LUFS"] = "未测（loudnorm 没有返回可解析的测量结果）"
     measurements["交付响度目标"] = delivery.loudness_lufs
+    measurements["分段色彩观测"] = _segment_colours(ffmpeg, episode / OUTPUT_DIRECTORY, cuts)
+    measurements["画内可读文字"] = (
+        "未测（抽有画内文字的帧，逐字对《剧本.md》的「画面文字」与提示词声明的内容）"
+    )
     measurements["台词完整性"] = "未测（本工具不做转写；在成片上转写后逐句对《剧本.md》原文）"
     measurements["边界帧"] = "未测（抽剪辑点前后各一帧目视核对黑场/白场/半渲染帧）"
     return measurements
@@ -1004,7 +1116,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         delivery, cuts, unused = parse_cut_list(episode / CUT_LIST_NAME)
         if arguments.command == "check":
             findings = check_cuts(
-                episode, cuts, project_root, probe=_which("ffprobe") is not None
+                episode, cuts, project_root,
+                probe=_which("ffprobe") is not None, unused=unused,
             )
             payload: dict[str, Any] = {
                 "段数": len(cuts),
@@ -1018,7 +1131,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             _emit(payload)
             return 1 if findings else 0
         if arguments.command == "render":
-            findings = check_cuts(episode, cuts, project_root, probe=True)
+            findings = check_cuts(
+                episode, cuts, project_root, probe=True, unused=unused
+            )
             if findings:
                 _emit({"findings": findings, "已渲染": False})
                 return 1

package/lib/drama/skills/short-drama-edit/scripts/selftest.py

@@ -15,6 +15,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from edit_tool import (  # noqa: E402
+    _unaccounted_shots,
     DEFAULT_REMOTION_CONCURRENCY,
     REMOTION_SOURCE,
     REMOTION_SOURCE_FILES,
@@ -377,6 +378,67 @@ def check_remotion_concurrency_is_capped() -> None:
     require("--concurrency=" in source, "render 必须显式传 --concurrency，不能用 Remotion 的默认值")
 
 
+def check_grain_is_a_delivery_wide_decision() -> None:
+    """Grain is declared once for the film, and refused when it is not grain.
+
+    Per cut it would become one more thing that differs between segments, which
+    is the defect it exists to cover.
+    """
+
+    with tempfile.TemporaryDirectory() as scratch:
+        root = Path(scratch)
+        episode = build(root, CUT_LIST)
+        path = episode / "剪辑单.md"
+        baseline = path.read_text(encoding="utf-8")
+
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain is None, "没声明颗粒时应当是 None")
+
+        anchor = "- 交付响度："
+        require(anchor in baseline, "夹具里应当有交付响度那一行")
+        path.write_text(baseline.replace(anchor, "- 颗粒：6\n" + anchor, 1), encoding="utf-8")
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain == 6.0, f"颗粒没有解析出来: {delivery.grain}")
+
+        path.write_text(baseline.replace(anchor, "- 颗粒：无\n" + anchor, 1), encoding="utf-8")
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain is None, "「无」应当解析成不加颗粒")
+
+        path.write_text(baseline.replace(anchor, "- 颗粒：80\n" + anchor, 1), encoding="utf-8")
+        try:
+            parse_cut_list(path)
+        except EditError as error:
+            require("超出" in str(error), f"越界报错没说清: {error}")
+        else:
+            raise AssertionError("颗粒 80 应当被拒绝")
+
+
+def check_missing_shots_are_reported() -> None:
+    """A shot absent from the film must be absent on purpose.
+
+    Absence is invisible in a finished film — nobody watching can tell that an
+    episode's opening seven shots were never made. The only place it can be
+    caught is here, against the document that lists them.
+    """
+
+    known = {f"MOTION-EP006-{i:03d}" for i in range(1, 5)}
+
+    class Stub:
+        def __init__(self, motion): self.motion = motion
+
+    used = [Stub("MOTION-EP006-003"), Stub("MOTION-EP006-004")]
+    findings = _unaccounted_shots(known, used, [])
+    require(findings, "少了两镜却没有任何 finding")
+    require("001" in findings[0] and "002" in findings[0], f"没点名缺的镜头: {findings}")
+
+    excused = _unaccounted_shots(
+        known, used, ["MOTION-EP006-001（理由：质量不可用）", "MOTION-EP006-002（理由：文件缺失）"]
+    )
+    require(not excused, f"写进未采用的镜头不该再报: {excused}")
+
+    require(not _unaccounted_shots(known, [Stub(m) for m in known], []), "全采用时不该报")
+
+
 def main() -> int:
     with tempfile.TemporaryDirectory() as scratch:
         root = Path(scratch)
@@ -446,6 +508,8 @@ def main() -> int:
     check_ass_escaping()
     check_multi_subtitle()
     check_stale_window()
+    check_missing_shots_are_reported()
+    check_grain_is_a_delivery_wide_decision()
     check_remotion_sources_all_shipped()
     check_remotion_concurrency_is_capped()
     print("short-drama-edit self-tests passed")

package/lib/drama/skills/short-drama-image-prompts/SKILL.md

@@ -20,6 +20,8 @@ license: MIT
 
 有当前视觉设定即可直接开始；剧本只在提示词需要确认剧情状态时读取。Look Development 是可选分支。
 先确认用途：身份板、造型/状态变体、地点板、道具板、组合 production sheet 或比较风格帧。
+分镜需要生产尾帧时，可把已接受的「收尾关键帧提示词」落实为独立 `IMG-...` 状态图条目：
+说明来源 SHOT 与终点，沿用视觉事实和参考范围，不重新设计动作。实际生成以该 IMG 条目为来源。
 
 创作者可读说明跟随项目语言；可复制正文跟随 `short-drama.json#/format/prompt_language`。没有
 `short-drama.json` 时正文默认

package/lib/drama/skills/short-drama-image-prompts/references/common-recipe.md

@@ -203,6 +203,17 @@
 - **`taste_option`**：写实度、媒介、颗粒、色调和镜头感由视觉风格或创作者决定。
 - 禁止用固定词表或形容词比例阻断交付；描述是否空泛，由审查者指出具体缺了什么。
 
+### 光学与表面描述
+
+**`craft_default`**：对需要明确透视或写实质感的画面，写明机位、取景距离和可见表面特征。
+焦段可辅助表达，但不能据此承诺模型会精确模拟光学。
+
+根据画面尺度选择毛孔、布料折痕或金属使用痕迹；「干净」不必等同于没有任何纹理和折痕。
+不要给每张图添加相同的相机参数、瑕疵清单或排除词。
+
+**`taste_option`**：表面是否平滑、是否修饰，以及写实程度由已接受的视觉风格决定。
+结果用对照图检查；像素纹理指标只作辅助，不能代替人物与材质的视觉判断。
+
 ## 5. 输出、常见问题与检查
 
 ### 输出

package/lib/drama/skills/short-drama-produce/SKILL.md

@@ -16,7 +16,8 @@ license: MIT
 取出本次提示词，建立一个有边界的运行 job。creator-first job 的 `source` 必须指向拥有这条提示词的
 当前 Markdown，`source_entry` 必须点名该文档允许的二级标题：`图片提示词.md` 用 `IMG-*`，
 `视频提示词.md` 用 `MOTION-*`，`分镜.md` 用 `SHOT-*`（modality 为 `image`，正文取该镜的
-`### 冻结关键帧提示词`）。分镜这一路是本套件里唯一能把某一镜的起始画面渲染成文件的入口，但不是创作者获得起始帧的唯一办法——
+`### 冻结关键帧提示词`）。此选择器只提取首帧；尾帧需先由图片提示词阶段建立独立 `IMG-*` 状态图条目，
+再从 `图片提示词.md` 准备 image job。创作者也可以提供已有起始帧——
 在自己的工具里出图再放进项目同样成立，图片始终不进项目时走分镜的 `PLAN-...`；
 产出落在 `剧集/<EP>/制作成果/images/` 后，分镜 owner 才能把它绑成 `用途：起始帧` 的 `REF-...`。存在真实参考图时，
 还必须逐张填写 `reference_bindings` 的槽位、顺序、路径、中文名、用途以及允许/禁止控制范围；
@@ -126,6 +127,9 @@ adapter 配置必须在项目外，只包含 argv 命令和超时；凭据由 ad
   固定高保真引用并校验尺寸、格式与透明背景限制。
 - [MiniMax Music](references/providers/minimax-music.md)：使用 `music-3.0` 与 hex 结果，区分主题曲
   和纯配乐，不伪造时长请求字段。
+- [MiniMax 语音](references/providers/minimax-speech.md)：`tts` 模态；模型与 `voice_id` 都必须
+  由账号与文档显式给出，不内置音色清单。只从预置音色合成，不做声音克隆——克隆是授权问题，
+  创作者授权的参考录音按普通创作者输入走 `输入/`。
 - [MiniMax H3 视频](references/providers/minimax-h3-video.md)：模型 ID、分辨率集合与时长区间必须
   由账号显式配置；提示词进 `content` 的 text 项，参考图按显式 role 绑定，本地参考在没有可信上传时
   fail closed。该模型与画面同一次生成声音，写法影响见视频提示词技能的目标模型能力档案。

package/lib/drama/skills/short-drama-produce/references/adapter-contract.md

@@ -99,6 +99,12 @@ Keep this file outside the project:
 `command` is an argv array, never a shell string. Timeout is 1–3600 seconds. Do not put credentials in this file;
 let the adapter read its environment or operating-system credential store.
 
+## Capability sources
+
+Use the provider's current API reference for roles, limits and supported combinations.
+A relay can expose a different subset, reject inputs itself or transform requests.
+Record the tested execution path and distinguish its observations from the native API contract.
+
 ## Adapter stdin
 
 The adapter receives one UTF-8 JSON document as raw stdin bytes. Read the
@@ -121,26 +127,14 @@ on the machine locale. The document contains the confirmed job plus:
   adapter must **not submit anything**; it polls and downloads that existing
   task and returns its outputs as usual.
 
-## Why the handle exists
-
-A video task is billed the moment it is submitted, not when its result is
-collected. Everything after submission — polling for minutes, downloading — can
-be interrupted by a killed process, a dropped connection, or a sleeping laptop.
-Without a durable id the attempt record says `failed` while the provider's task
-is alive and already paid for, and the only way forward is to submit again and
-pay a second time for the same shot.
-
-So: write the handle before the first poll, and treat failing to write it as
-non-fatal — a submitted task must never be failed because its id could not be
-recorded locally. The tool copies the handle onto the attempt record on both the
-success and the failure path, `audit` reports any unfinished attempt that
-carries one as `orphaned_provider_job` with `action: collect_before_retry`, and
-`production_tool.py collect` fetches it.
-
-`collect` deliberately sits outside the confirmation gate. That gate exists to
-prevent an unintended charge; collecting spends nothing because the charge
-already happened. Requiring a fresh confirmation would make paying again the
-cheapest way out of an interruption — the exact outcome the gate is for.
+## Recovering a submitted task
+
+Record the provider task ID before polling so an interrupted task can be collected without resubmission.
+A local handle-write failure is non-fatal after submission. The tool copies the handle into the attempt
+record on success or failure; `audit` reports unfinished tasks as `orphaned_provider_job` with
+`action: collect_before_retry`.
+
+`production_tool.py collect` retrieves the existing task without new submission or confirmation.
 
 It may translate provider-neutral parameters into its chosen SDK/API. Optional
 provider adapters under `scripts/` document and implement known translations;

package/lib/drama/skills/short-drama-produce/references/providers/minimax-h3-video.md

@@ -74,31 +74,13 @@ structured: base/first-frame/first-last-frame tasks use `integrated_multimodal_d
 form. Chinese dialogue remains exact inside `<d>[Chinese] ...</d>`. Full details live in the
 video-prompt skill's `references/minimax-h3.md`.
 
-Audio generation is a **capability**, not a style:
-what changes upstream is only which axes of the target-model profile a project declares — see the
-video-prompt skill's target-model profile. Two consequences are worth stating here because they
-show up as production defects rather than as API errors:
-
-- an unstated **music** channel is not a silent one. Probing this suite's own prompts against H3, a
-  body carrying `non_diegetic_music: N/A` came back without a score in 14 of 14 runs, while a body
-  that said nothing about music came back with an invented score in 2 of 3. State the music intent.
-- the **speech** channel did not behave the same way in those probes: no run invented dialogue,
-  including 8 runs whose body carried a contradictory `No dialogue` exclusion. Treat "an unstated
-  vocal channel gets filled" as unverified rather than as a known failure, and write the shot's
-  sound intent because the body should say what this shot sounds like — not on the strength of a
-  mechanism this suite has not observed.
-- readable on-screen text was **not** produced unmasked in those probes either: across 44 sampled
-  frames from 11 clips — including dialogue clips carrying no exclusion sentence, on H3 and on
-  Seedance 2.0/2.5 — no burned-in subtitle or caption appeared. The exclusion sentence this suite
-  mandates is therefore precautionary **for video** rather than evidence-driven. Keep writing it:
-  a one-line exclusion costs nothing, these probes are small enough that they only show the failure
-  was not produced here, and generator behaviour changes between versions. What should change is the
-  justification — do not defend it as a fix for an observed defect. Note the asymmetry before carrying this reasoning anywhere else:
-  the same probe run against `gpt-image-2` found the opposite — an unconstrained still came back
-  covered in invented readable text, and the exclusion sentence cleaned it up. The image stages
-  keep their text policy on evidence; only the video stage's copy of it is precautionary.
-
-Neither is written here as a fixed phrase, and this suite never injects one. The wording belongs to
-the shot and to the project's declared prompt language.
+State the intended sound layers in the prompt. For no non-diegetic music, the
+H3 dialect uses `non_diegetic_music: N/A`; small probes observed unwanted music
+when this layer was omitted. They did not establish that omitted speech or
+negative clauses cause extra dialogue.
+
+Follow the project's subtitle and in-scene-text policy. Prompt wording belongs
+to the video-prompt skill and the declared language, not to adapter-generated
+boilerplate.
 
 Protocol reference: [MiniMax video generation API](https://platform.minimax.io/docs/api-reference/video-generation-v2-create).

package/lib/drama/skills/short-drama-produce/references/providers/minimax-speech.md

@@ -0,0 +1,41 @@
+# MiniMax Speech adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "minimax-speech"], "timeout_seconds": 600}
+```
+
+Required environment: `MINIMAX_API_KEY`. `MINIMAX_BASE_URL` optionally overrides the default
+`https://api.minimax.io/v1` and must remain HTTPS.
+
+The job uses the suite's `tts` modality and must have exactly one output. The production prompt is the
+line to be spoken, verbatim — not a description of it. Supported public parameters are `model`,
+`voice_id`, `emotion`, `speed`, `vol`, `pitch`, `sample_rate`, `bitrate`, and `format`. The requested
+format must match the target extension and be `mp3` or `wav`.
+
+`model` and `voice_id` are both required and neither has a default. The model is an account-enabled
+endpoint, exactly as for the video providers. The voice is a creative decision recorded in
+`视觉设定.md` under the character's 声音方向, and it reaches the adapter through the confirmed job.
+
+## Voice selection
+
+Read the provider's voice listing and confirm availability for the chosen model and account.
+The adapter validates the ID format, not catalogue membership. Record the selected ID in the
+character's 声音方向 and pass it through the confirmed job.
+
+This workflow selects preset voices. The adapter does not enrol or clone a voice;
+any supplied recording retains its documented authorization and usage scope.
+
+## Request shape
+
+The request is non-streaming with `output_format: hex`, `POST /t2a_v2`, and carries
+`voice_setting` (`voice_id`, and any of `emotion`, `speed`, `vol`, `pitch`) alongside `audio_setting`
+(`sample_rate`, `bitrate`, `format`). The adapter validates `base_resp.status_code`, decodes
+`data.audio` as hexadecimal bytes, and writes it to a private temporary file.
+
+`emotion` accepts the provider's seven values: `happy`, `sad`, `angry`, `fearful`, `disgusted`,
+`surprised`, `neutral`. Anything outside that set is refused rather than passed through — a rejected
+emotion is a typo caught before it is paid for.
+
+Protocol reference: [MiniMax Text to Speech](https://platform.minimax.io/docs/api-reference/speech-t2a-http).