zundamon-kaisetsu — ずんだもん解説 (掛け合い動画) を HTML / mp4 で作る

仕組み

1. 台本の各セリフを VOICEVOX エンジンの HTTP API で wav にする (/audio_query → /synthesis)
2. セリフの wav を無音を挟んで 1 本に連結し、AAC (m4a) に圧縮する
3. 連結のときに各セリフの開始・終了秒を記録し、口の開き (0/1/2) を audio_query のモーラ (音の単位) の母音から 30fps で作る (a・o は開き、i・u・e は半開き、ん・っ・無音・m/b/p の子音は閉じ)。それをもとに、各フレームの見た目の状態 (字幕の行・話し中か・口の開き) を変わり目だけの列にする。まばたき (目を閉じているキャラ) も時刻から決めて別の列に入れる
4. HTML は音声 (base64) と状態の列を埋め込む。ブラウザは new Audio() で再生し、requestAnimationFrame で audio.currentTime から状態を引いて描く。シーク・速度変更をしても音とずれない
5. mp4 は、同じプレイヤーのまとめ撮りモード (#sheet=行,話し中,口,まばたき,区切りのカード;…) で「見た目の状態」を 20 個ずつ縦に並べて描かせ、 ヘッドレス Chrome で 1 回に 1 枚撮って ffmpeg で切り分ける。それを状態の列どおりに並べて音声と合わせる。 撮るのは状態の種類の数 (行数 × 口の段階 程度) だけで、Chrome の起動はその 1/20 回で済む (実測: 27 行・194 秒・109 状態で Chrome 6 回、mp4 の build 全体 11.6 秒。M3 Max)。まばたきで状態は 2 倍弱に増える (実測: 107 行・572 秒の台本で 429 → 760 状態、Chrome 22 → 38 回、撮影を含む build 45 → 約 57 秒。1 回ずつの計測)。 チャプターの区切りのカードで状態は少し増える (実測: 73 行・406 秒・6 チャプターの台本で 550 → 568 状態、Chrome 28 → 29 回。 カードを 1.5 秒出していたときの計測で、1 行目の終わりまで出すようにしてから (issue 745) は未実測)

出力	向いている用途	必要なもの
html	社内共有・静的ホスティング。シーク・速度変更・書き起こし・チャプターがある (音声 64kbps なら 10 分で約 5MB)	ffmpeg か afconvert
mp4	動画サイト・チャットへの投稿、プレイヤーの無い場所での再生	ffmpeg (H.264) と Chrome

各フレームの状態 (字幕の行・話し中か・口の開き・まばたき) は build が 1 回だけ計算してデータに入れ、HTML の再生と mp4 の両方がそれを使う。 2 つの見た目は同じになる。

音声の調達 (VOICEVOX エンジン)

声のモデルはエンジンに同梱されている (無料)。エンジンは 127.0.0.1:50021 で待たせる。 起動と停止は自動: synth / kana / speakers は、そのポートで誰も待ち受けていなければ自分で起動し、見張りのプロセスを 1 つ残す。 見張りは、最後にエンジンを使ってから 10 分たったら止めて終わる (コマンドが途中で死んでも止まる。止め忘れが起きない。起動し直しは 2 秒程度)。 up で明示的に起動したエンジンとデスクトップアプリには触らない (up で起動したものは down まで動き続ける)。 起動のしかたは次の優先順で、自動起動と up が同じ規則で選ぶ。どれで起動しても API は同じ。

1. container (Apple のコンテナ CLI): あれば最優先で使う。サービスが止まっていれば container system start が要る (初回はカーネルを入れるか対話で聞かれる。非対話で入れるなら --enable-kernel-install。どちらもユーザーに確認してから打つ)
2. docker: container が無いときに使う。Docker Desktop 等が起動している必要がある
3. VOICEVOX のデスクトップアプリ: どちらも無いとき。起動している間、同じエンジンが 50021 番で動く

イメージは voicevox/voicevox_engine:cpu-latest (arm64 版あり)。初回は取得に数分かかる。 別ホストのエンジンを使うときは --engine URL か環境変数 VOICEVOX_URL (up / down は手元のエンジン専用)。 非公式の Web API は台本を外部へ送るので既定では使わない。

利用規約 (作る前にユーザーへ確認する)

• クレジット表記が必須: VOICEVOX:ずんだもん の形。登場したキャラクターの分を build が自動で入れる (HTML の「クレジット」に出る。mp4 の映像には入らないので、build が mp4 を書いたときに標準出力へ出す一覧を概要欄などに貼る)
• 商用利用の可否・禁止用途はキャラクターごとの規約で決まる。VOICEVOX 公式サイトの各キャラクターのページで確かめる
• 立ち絵は声とは別の作者の素材で、規約も別。配布元の規約を確認し、表記は表情の定義ファイルの credit に書く (自動で入る)

手順

パスはすべて この skill のディレクトリ (SKILL.md のある場所) からの相対で書く。呼び出し時に示される skill の base directory を S に入れてから使う (skill の外のパスを決め打ちしない)。

S=<この skill の base directory>
DV=zundamon-kaisetsu    # dotfiles の bin/ のコマンド (Go 製。ソースは dotfiles の src/zundamon-kaisetsu)。圧縮に ffmpeg か afconvert

zundamon-kaisetsu は、この skill のディレクトリ (テンプレートと立ち絵の既定の置き場) を bin/zundamon-kaisetsu から 環境変数 ZUNDAMON_KAISETSU_SKILL_DIR で受け取る。PATH 上の古いバイナリを直接起動すると止まるので、必ず bin/ の入口を通す。

初めて使う環境の準備 (エンジン・立ち絵の入手) は README.md の Setup にある。

0. 出力を html / mp4 / 両方 のどれにするかユーザーに聞く (指定済みなら聞かない)。迷っているなら上の表で用途を示す。 長さを決める設定は無く、尺は台本の量で決まる (1 行あたり約 5.5 秒。実測: 99 行で 539 秒)。尺の指定があれば行数に換算して台本を書く。 同じ問いで、右上の作成日を画面に出すかも聞く (指定済みなら聞かない)。出さないなら台本の overlays から date を外す ("overlays": ["title", "topic"])。左上のタイトル・上部中央のトピック名も、外したいと言われたら同じキーで外す。 資料の語り方のモード (下節「資料の語り方」の「資料を明かす」か「独自調査」) も同じ問いで聞く (指定済みなら聞かない)。 社内向けなら資料を明かす、不特定多数に公開するなら独自調査、と見る人で勧める。選んだモードは台本の source_mode に書く (手順 3 の lint が見る)
1. 必要なコマンドを確かめる (足りなければ rc=1 で、何が足りないかと次の手を出す)

   $DV check
   # OK  音声の圧縮 / 立ち絵の書き出し: uv / mp4 用: Chrome / mp4 用: H.264 / コンテナ (container を優先) / そのサービス / VOICEVOX エンジン
   

   NG の行は表示された手で直す (mp4 用の 2 行は html だけ作るなら無視してよい)。インストールやサービスの起動 (brew install・container system start) はユーザーに確認してから行う
2. 使う声のスタイル ID を調べる (エンジンは自動で起動し、使わなくなると止まる (「音声の調達」)。up は打たない)

   $DV speakers      # 例: 四国めたん: ノーマル=2, ... / ずんだもん: ノーマル=3, ...
   

   ID はエンジンの版で増減しうるので、台本に書く前に毎回この出力で確かめる
3. 台本を書く。作業ディレクトリはユーザーの指定先 (無ければ最初に 1 回 skill-tmpdir zundamon-kaisetsu を打ち、出たパスの下の <名前>/ をリテラルで使い回す。<本体 checkout>/tmp/zundamon-kaisetsu/<session-id>/<名前>/。完成物の場所はユーザーに絶対パスで伝える)。書く前と書いた後に 1 体ずつ、計 2 体のサブエージェントを走らせる (Agent ツール・model: "sonnet"・読み取りのみ。資料の取得手段 (CLI・URL・ファイル) と視聴者の前提をプロンプトに渡す)
   • 資料が PDF なら、先にテキストにして作業ディレクトリに置く (pdftotext は macOS に無い): uv run -q --with pypdf python -I -c 'import sys,pypdf; open(sys.argv[2],"w").write("\n".join(p.extract_text() for p in pypdf.PdfReader(sys.argv[1]).pages))' 資料.pdf src/source.txt。 表は欄がばらばらの行に崩れる (年表の日付・出来事・出典が別の行に出る) ので、表から拾った事実は本文の記述でも確かめ、 サブエージェントにも「表の行が崩れている」と添える。このテキストを lint --source にも渡す
   • サブエージェントを起こせないとき (ユーザーが止めた・5h 枠が足りない): main が自分で、手順 3-1 は下の箇条を、手順 3-3 は 少なくとも lint・kana --check・読み分け候補の grep (手順 5 の 3)・図解と資料の突き合わせ (手順 3-3 の図解の観点) を見る。 その場合も工程を黙って省かず、サブエージェントの確認を飛ばしたことを、台本を見せるとき (手順 3-4) と完了の報告でユーザーに伝える
   1. 書く前: 資料のリンクを辿る + 主題の事実の裏取り (1 体のサブエージェントでまとめて行う。指示は templates/review-3-1.md を埋めて渡す)
      • 資料にリンクが無く、裏取りする主張が数件 (目安 5 件まで) なら、サブエージェントを起こさず main が行ってよい (リンクの無い 8.5KB の記事でも、1 体で約 19 万トークン使った。issue 745)。下の箇条のうちリンクを辿る以外を同じように見る
      • 資料の本文にあるリンク (同じサービスの記事・issue・PR・ドキュメント) を、資料と同じ取得手段で 1 段辿って読ませ、 台本に取り込める詳細 (背景・定義・経緯・数値) を出典つきで要約させる。main agent はその要約を使って台本を書く
      • 取得できないリンク (認証の要る外部サービス・ファイル置き場・ダッシュボード) は飛ばし、飛ばしたものを一覧で返させる
      • リンク先は資料本体より古いことが多い。食い違ったら資料本体を正とし、食い違いはユーザーへ伝える
      • 資料の主張を、資料が指す一次情報 (リンク先・issue・PR・コード・公式ドキュメント) と突き合わせ、 主張ごとに「確認できた / 食い違う / 確認できない」と出典を返させる。食い違いは、台本に入れる前にユーザーへ伝える
      • 資料の中での食い違い (同じ事柄の日付・数値・状態が章によって違う箇所) も行番号つきで挙げさせる。計画書・設計書は 表と図と本文で値がずれていることが多い。台本では片方を断定しない (下節「守ること」)
   2. 台本 JSON を書く (形式は下節。見本は examples/script.json)。図 (image) を使うなら、画像もこの段で用意する (下節「図」の基準で、言いたいことだけを描き直す)。書いたら、読み間違えやすい語の辞書 $S/readings.json を 台本の readings に合流させる (台本に既にある語は台本の方を残す)

      jq --slurpfile d "$S/readings.json" '.readings = ($d[0] + (.readings // {}))' script.json > script.json.new && mv script.json.new script.json
      

      辞書の語は全行の音声に当たるので、その台本で別の読みにしたい語 (stg を識別子として読ませたい等) は台本の readings か行の read で上書きする
   3. 書いた後: 機械の校正 ($DV lint script.json --source 資料) を通してから、確認を 1 体のサブエージェントにまとめて行う
      • lint は、文字列と台本の構造だけで決まる校正を出す: 字幕の 60 字超・ずんだもんの「のだ」2 回・一人称の取り違え (ずんだもんの「わたくし」、めたんの「ぼく」)・図を名指しして指す言い方 (「この図」「上の図」等)・チャプターをまたいで残る図解・ 同じ話者で前の行と同じ字幕・図解の中の文 (「。」で終わる補足や項目)。 警告があれば rc=1 なので、直してから先へ進む (めたんの「ぼく」はずんだもんの引用なら無視してよい)。 「目安」は rc に効かない (場面によっては許容してよい): 助数詞の付いた漢数字・めたんの 3 行連続・1 セリフ 3 文以上・口調の語尾の取り違え・ 長い行の声のスタイル・読み辞書の語が台本の readings に無い (手順 3-2 の合流漏れ)・チャプターの数・ --source (資料のテキストのパス) を付けたときの資料との突き合わせ (資料に無い数字・資料に無い英字の語・導入の終わりに本題へ移る言葉が無い)・2 つ目以降のチャプターの最初の行がずんだもんの質問でない・1 チャプターの図解が 3 回以上・独自調査のモード (source_mode: "public") で資料の存在が分かる語 (「資料」「レポート」「回答」「文書」「記事」「AI の分析」等。字幕・読み上げ・タイトル・概要・クレジット・チャプター名・図解の文字を見る。公開された文献を名前で引く行と字面で区別できないので目安にしている。確認役に渡し、元の資料のことを言っている行を直す。言い換えは見ない)
      • 確認役は、lint が見ない校正と、事実・図解・読みの 4 観点を見る。指示は templates/review-3-3.md を埋めて渡す (観点は下の箇条が正本で、テンプレートはそれを読むよう指すだけ。lint の結果も渡して重複させない)。先に手順 4 の synth と 手順 5 の 1 (kana --script の書き出し) を回し、台本・資料・kana.tsv のパスと、手順 3-1 で確認済みの資料の外の事実を渡す。 観点を順に見て、問題のある行だけを「観点 / 行番号 / 問題 / 直し方」で返させる
      • 体数を 1 にする理由: サブエージェントは仕事の量によらず 1 体あたり約 15 万トークン使い (起動時の固定分が大半)、 観点ごとに分けた 4〜5 体では 1 本で約 74 万になった。1 体にまとめた試験 (欠陥を 12 個仕込んだ台本) では、sonnet は 11 個、 haiku は 10 個を見つけ、トークンは約 16〜18 万だった (haiku に替えてもトークンは減らない。issue 673 の進捗)。 まとめると読み (漢字の読み分け) が手薄になるので、手順 5 の 2 (機械の検査) と 3 (main) で補う
      • 校正 (lint が見ない分): 誤字・脱字・文法・不自然な言い回し、用語と表記の揺れ、 キャラの口調 (下節の「役割と口調」) の語尾の取り違え、説明の行に style_id を書いてノーマル以外の声にしている行、 lint の一覧に無い言い方で画面のものを指す行 (「これ」「ここ」「こちら」「左の」「上の」で図解を指す)、 書き起こしだけでは意味が取れない行 (下節の「声・図解・字幕の役割」の 2 つの点検)、 資料の語り方のモードから外れた行 (下節「資料の語り方」。独自調査なら、元の資料・レポート・回答の存在が分かる行と、 公開された文献を出典を言わずに使っている行。title と description も見る)
      • 事実: 各行を「資料・一次情報で裏付けあり / 前提知識の一般的な説明 / 推測 / 誤り」に分け、誤りと、資料のぼかし (推論・場合による・案) を断定に強めた行を、根拠つきで返させる
      • 図解 (show を使った台本だけ): 図解はセリフと別の場所に要約を書くので、食い違いの入口が増える。次の 2 つを両方見させる
        • セリフとの対応: 図解ごとに出ている区間 (show の行から、次に show を持つ行の手前まで) を挙げさせ、 図解の語がその区間のセリフで話されているか、話題やチャプターが移っても図解が残っていないか (消すなら null)、 図解と字幕で用語・表記が揃っているかを見る。コードの図解は識別子を読み上げないので、語ではなく、その区間のセリフが 強調した行 (highlight) の役割を説明しているかを見る。段のある図解は段ごとに (出した行と "next" の各行で)、 その段で現れた項目・強調した行を、その行のセリフが話しているかを見る (先の段の項目を前の行で話していないか)
        • 資料との整合: 図解の中身だけを資料・一次情報と突き合わせ、セリフに無い主張・数字が図解にだけ無いか、 要約して断定が強まっていないか (「案」が図解では決定に見える等) を見る。コードは資料のコードと 1 行ずつ同じか (… の行は省いた印なので、その前後が資料で続いているか。幅に収めるための改行と字下げの違いは除き、字句が同じかを見る) を見る。コードの中の識別子・数字はセリフに無くてよい。 図は画像を開いて、描かれた関係・順番が資料と合っているか、alt と食い違っていないか、要素が多すぎないか (5〜7 個まで) を見る
      • 読み: kana.tsv で字幕と読みが食い違う行 (観点と表記の約束は手順 5 の 3 と同じ)
      • 指摘は main agent が資料と台本で確かめてから直す (無検閲で採用しない)。台本の行は行番号 (添字) ではなく字幕の文の一致で指し、 一致が 1 件であることを確かめてから書き換える (行を足したり分けたりした後は添字がずれ、別の行を上書きする。2026-10-08 に実際に起きた)。 直したら synth し直し (変わった行だけ合成される)、 kana --script で kana.tsv を書き出し直してから手順 5 の 2 へ進む
   4. ユーザーに見せる。資料の外から足した行 (一般的な説明・推測) と、図解の一覧 (出す行と中身) を挙げて確認をもらう (lint --source の「資料に無い数字」「資料に無い英字の語」の一覧を下書きに使う)。 図は画像そのものも見せる (小さい図・複雑すぎる図はここで外すか描き直す)。 台本そのものは $DV view script.json の一覧 (チャプター・話者 (表情)・字幕と、図解を出す・段を進める・消す行。合成は要らない) をファイルに書いて、そのパスを渡す
4. 合成: $DV synth script.json
   • 初回 (キャッシュが無い) は 1 行あたり 1.5 秒ほどかかり、90 行で Bash ツールの既定の上限 (2 分) を超える (実測: 87 行で超えた。1 回の計測)。 timeout を長く取るか、背景で走らせて完了を待つ
   • セリフごとの wav と audio_query の結果が script.work/ に入る。ファイル名は合成入力 (文・声・話速等) のハッシュなので、 台本を直して再実行すると、行の挿入・削除・並べ替えを含めて変わった行だけ合成し直す
   • style_id がエンジンに無いか、そのキャラ以外の声なら止まる
   • 最後に、字幕が速くて読み切れないおそれのある行を警告する (rc は 0。build は書き出す前に止まるので、手順 6 の直し方をこの時点で当てておく)
   • エンジンの版やユーザー辞書を変えたら --force (これらはキャッシュの鍵に入らない)。台本から外れた古いキャッシュの件数が 出たら、script.work/ の中の使われていない *.wav / *.query.json を消してよい (script.work/ ごと消すと mermaid/ の図も描き直しになる)
   • 辞書以外の読みを最初から足さない。英字の固有名詞も、そのままで正しく読まれることが多い (読みは次の手順 5 で、合成の結果を見て直す)
5. 読みの見直し: 合成した音声の読みを、手順 3-3 の統合確認と main agent で確かめて直す
   1. $DV kana --script script.json > kana.tsv で全行の 行番号 / 話者 / 字幕 / 読み を書き出す (音声を差し替えた行には *)
   2. 機械の検査: $DV kana --script script.json --check で、英字の語を 1 文字ずつ読んだ行 (SOLIDWORKS を「エスオーエル…」) を 警告し (あれば rc=1)、台本に出る英字の語の一覧 (語だけを読ませた読みつき) を出す。警告の行は誤読なので直す (手順 5 の 4〜5)。 ただし 1 文字ずつ読むのが正しい略語なら、一般の語 (技術用語) は $S/acronyms.json (1 文字ずつ読む略語の一覧) に足し、 その台本だけの語 (社内の略語・製品の略称。公開の skill に置けないもの) は台本の acronyms (["QRO"]) に書く。 この検査が見るのは 1 文字ずつ読んだ形だけで、崩れた読み (SIer を「エスイアー」) と漢字の読み分けは見ない。通っても誤読が無いことにはならない
   3. main agent が、検査で決められない誤読を自分で見る (手順 3-3 の統合確認の読みの指摘に加えて。サブエージェントは起こさない)
      • 英字の語の一覧 (手順 5 の 2 の出力の後半): 語ごとの読みに崩れが無いか (数十語)。一覧の読みは語だけを読ませたもので、 行の中では読みが変わることがある (Next.js の js)。語だけの読みが行の読みに現れない行は「行の中では別の読み: N 行目」と 印が付くので、その行は kana.tsv で読みを見る
      • 同じ字で読みが違う語を含む行: grep -F -f "$S/kanji-candidates.txt" kana.tsv (1 行 1 語の候補の一覧)。正しく読めている行も混ざる (候補の一覧)。 1 体にまとめた確認は、この種類を見落とした (試験で「Boot Camp の上」を「じょう」と読んだ行。issue 673 の進捗)
      • 読みの表記: ' はアクセントの位置、/ と 、 は区切り、_ は無声化。助詞の「は」「を」は ワ オ、長音は エエ オオ のように母音を重ねて書かれる (セエス'ウ = 整数)。これらは誤読ではない
      • 見る観点: 英字の略語・識別子 (1 文字ずつ読まれる・英語として読まれない)、数字と助数詞 (「8件」→「はっけん」)、 同じ字で読みが違う語 (「空を返す」→「そら」、「親」→「しん」、「値を返す」→「ね」)、固有名詞、記号を含む語 (eql?)。 辞書 readings.json に載っている語は確認済みなので除く
      • 人名・書名・引用 (歌詞・題名) は誤読しやすい。人名の読みは、フルネームだけでなく台本に出る形 (姓 + さん) でも readings に書く (「合田道人」を書いても「合田さん」は「あいださん」と読まれた)。書名は「日本」が「にっぽん」、題名の「星」が「ほし」(いちばんぼし)、 歌詞の「こわれて消えた」が「ぎえた」(連濁) になった。引用は字幕を変えずに readings か read で読みを直す
      • アクセントの高低は指摘しない (読み = 音の並びだけを見る)
   4. 指摘ごとに、直し方の候補を $DV kana "候補1" "候補2" … で合成せずに比べる (--who zundamon で声を変える)。 候補にはカタカナ・ひらがな・英字のままを並べる。カタカナにすると逆に誤読することがある (実例: 「ヘロクの」は文頭の「ヘ」が助詞扱いで「エ ロクノ」。英字の「Herokuの」なら「ヘロクノ」)。指摘が誤り (正しく読めている) なら採らない
   5. 同じ語が何行にも出るなら台本全体の readings ({"datetime": "デートタイム"}) で直し、その行だけの直しは行の read で直す
   6. synth し直し (変わった行だけ合成される)、kana --script で直した行の読みを確かめる
   7. 直した語のうち、どの文脈でも同じ読みになる語は辞書 $S/readings.json に足す。足す前に $DV kana "<語>" "<読み>" で、 語のままでは誤読し、読みにすれば正しく読まれることを確かめる。文脈で読みが変わる語 (値 = ね / あたい、親、空) は辞書に入れず、 その台本の readings か read で直す (辞書は全行に当たる)。文脈で読みが変わる語を誤読していたら、その語を $S/kanji-candidates.txt に 1 行で足す (次の台本から手順 5 の 3 の候補に載る)。固有名詞は、公開してよい一般の語 (製品名・技術用語) だけを足す。 置き換えは大文字小文字を区別した部分一致 (長い語から先) なので、他の語の一部に現れる短い語は足さない (RAM は PARAM・FRAME に当たる)。足すなら、その語を含む派生語も一緒に足して守る (cache には cached・caches、queue には enqueue・dequeue・queues)
6. 組み立て: $DV build script.json -o out --format html|mp4|both (拡張子は形式に合わせて付く)
   • mp4 を書いたら、mp4 に入らないクレジット (声・立ち絵・台本の credits) を 1 行ずつ標準出力に出す。概要欄に貼るようユーザーに渡す
   • --bitrate 96k で音質を上げられる (既定 64k)。mp4 は 1280x720 (720p) 固定
   • 「字幕が速くて読み切れないおそれのある行」があると、build は音声の圧縮と書き出し (mp4 の撮影) の前に止まる (rc=1)。 その行を分けて synth → build し直すか、行の pause_after で次の行までの間を足して build し直す (pause_after は合成の鍵に 入らないので synth は要らない)。分かったうえでそのまま書き出すなら --allow-fast-captions (字幕が出ている間 = その行の開始から次の行の開始まで に 1 秒 7.5 字を超える行。英字も 1 字ずつ数えるので、英字の多い行は出やすい)
   • ラベル (左上のタイトル・トピック名・区切りのカード・図解の欄) に意図しない改行・はみ出しがあっても、同じ所で止まる (rc=1)。 mp4 と同じ 1280x720 の舞台を Chrome で描いて測る (Chrome が無ければ、確かめていないと出して続ける)。止まる形は、1 行で出す欄 (タイトル・トピック名・見出し) が折り返す、語の途中で改行する、1 字だけの行ができる、箱か舞台からはみ出して隠れる (箇条書きの項目・コードは折り返さないので長すぎるとこれになる。改行の位置が無い長い英字も)、の 4 つ。 出た欄の語を短くするか、文節が 1 行に収まる言い方に直して build し直す (合成の鍵に入らないので synth は要らない。タイトルは全角 30 字ほどまで)。 分かったうえでそのまま書き出すなら --allow-label-wraps
   • mp4 は撮影の前に CPU の負荷を見る。1 分平均の load がコア数の 8 割以上なら、空くまで最大 20 分待つ (1 分ごとに状況を出す)。 20 分で空かなければそのまま撮る。bash ツールの timeout を 20 分以上に取って起動する (足りなければ背景で起動して完了を待つ)
7. 確認: open out.html / open out.mp4 で再生し、ユーザーに見てもらう。図を使ったなら、その前に図の行を表示して ラベルが読めるかを自分の目で確かめる (読めなければ描き直すか外す。字の小ささは build では測れない)。HTML は URL 末尾の #t=12.3 でその秒から開く (一時停止すると URL に書かれる)。 行の開始秒は $DV times script.json (行番号 / 開始秒 / 終了秒 / 話者 / チャプター / 図解 / 字幕 の TSV) で引く。mp4 なら図解の列が空でない行の 開始秒の少し後を ffmpeg -ss <秒> -i out.mp4 -frames:v 1 frame.png で切り出して見る
8. 片付け: 自動で起動したエンジンは見張りが止めるので (「音声の調達」)、何もしなくてよい (すぐ止めたいなら $DV down)。 ただし、エンジンを使うコマンド (synth / kana / speakers) が動いている間は止めない (Ctrl-Z で止めたままのものも含む。 止めたままにしたら、再開して終わらせるか、$DV down で止める)。 up を打っていたら $DV down で止める (この skill 専用の名前 zundamon-kaisetsu-voicevox-<ポート> のコンテナ (旧版が起こした固定名 zundamon-kaisetsu-voicevox と、 自動起動の印が別のポートを指していればそのポートのものも) だけを、container と docker の両方で止める。デスクトップアプリは止めない)。 手順 1 で container system start を打った (このセッションでサービスを起こした) なら、container system stop で止めるかをユーザーに聞く (他の用途でコンテナを使っていることがあるので、聞かずに止めない)

立ち絵と表情

キャラクターは 四国めたん (metan、左) とずんだもん (zundamon、右) に固定。2 人が向き合うよう、めたんの立ち絵は左右反転して表示する (素材は画面の左向きに描かれているため。castOrder の Mirror)。名前・既定の声 (めたん 2 / ずんだもん 3)・色は dotfiles の src/zundamon-kaisetsu/internal/script/script.go の CastOrder が正本で、台本では変えない。立ち絵が無いキャラは名前入りの丸アバターで出る。

立ち絵は、PSDTool 形式の PSD (!口 !目 のような排他グループを持つもの) から表情ごとに書き出して使う。

立ち絵の置き場は $S/assets/zundamon-kaisetsu/ (faces/<キャラ>/ に書き出した表情、psd/ に元の素材)。 台本で cast.<キャラ>.faces を省くと faces/<キャラ>/ を読み、無ければ丸アバターで出る (build は止まらない)。 素材は公開リポジトリに置けない (素材ファイルの再配布になる) ので、skill には同梱しない。用意の仕方は README の Setup。

• dotfiles では、非公開リポジトリ jiikko/assets を assets/ にサブモジュールとして置いている。空なら git -C "$S" submodule update --init assets で取得する (権限のあるアカウントでだけ取れる)

表情を変える・素材を差し替えるときは、PSD から書き出し直す:

1. 素材の規約 (同梱の readme・公式ガイドライン) を読む
2. 表情の定義 faces/<キャラ>.json を直す。表情ごとに使うレイヤーと、口の 閉じ / 半開き / 開き の 3 枚を書く。 まばたきの閉じ目は全体の blink に 1 つ書き、目を閉じた表情を足したらその表情に "blink": false を書く。 素材の版でレイヤー名が変わったら、無いレイヤーを名指しして止まるので定義を直す
3. 書き出す: README の Setup「3. 立ち絵」の 4 のコマンドを $S で実行する (psd-tools を uv run --with で使う。1 キャラ 1〜2 分)。 --preview の画像 (全表情 × 口 3 段階の一覧。閉じ目の版も並ぶ) をユーザーに見せて確認する
4. dotfiles のサブモジュールなら、assets 側で commit & push してから、dotfiles のサブモジュールの参照を更新して commit & push する

表情の語彙 (全キャラ共通。定義ファイルはこの 8 つを全部持つ)。台本を書くときに、セリフの内容と場面に合わせて行ごとに選ぶ:

表情	使う場面	ずんだもん (立ち絵素材 2.3)	めたん (立ち絵素材 2.1・白ロリ服)
通常	相づち・中立 (省略時)	普通の目・眉、口 むふ/ほあ/ほあー	ほほえみ、口 ほほえみ/▽/わあー
笑顔	納得・喜び・締め	にっこり目・上がり眉・赤いほっぺ	目閉じ・赤面
説明	解説・要点の提示	カメラ目線・指差し	カメラ目線・指差す
驚き	意外な事実・強い疑問	〇〇目・両手を挙げる、口 お/△/おほお	○○目・手をかざす、口 お/△/わあー
困り	問題・制約・不安	困り眉・汗・口元に手、口 んー/んへー/んあー	こまり眉・汗・口元に指、口 もむー/いー/うえー
考え中	問いかけ・迷い	目逸らし・あごに手	目そらし・手をあごに (ひそひそ)
怒り	不満・ツッコミ	ジト目・怒り眉・腰に手	おこ眉・腕を抱える
悲しみ	残念・落胆	閉じ目・涙・しおれた枝豆	目閉じ・涙・青ざめ

話す行はその行の face (省略は 通常) で口パクし、話していない側は最後に話したときの表情のまま。 表情が 驚き / 怒り / 悲しみ のあいだは、立ち絵に止まった演出が重なる (驚き = 後ろに集中線、怒り = 頭の内側の上に怒りマーク、 悲しみ = 顔に青い縦線)。台本に書くことは無く、表情で決まる。絵はプレイヤーが SVG で描く自前のもので、クレジットは要らない。 表情は見た目の状態に含まれるので、mp4 の撮る枚数は増えない (揺れ・跳ねのような動く演出は撮る枚数が増えるので入れていない)

まばたき: 2 人とも 2〜6 秒おきに 0.12 秒、目だけを閉じる (話している間も。キャラごとに時刻をずらす)。台本に書くことは無い。 閉じ目の絵は表情の定義の blink (閉じ目のレイヤー。ずんだもんは なごみ目、めたんは 目閉じ2) で書き出した <表情>_blink_<口>.webp で、 もともと目を閉じている表情 (両者の 笑顔・悲しみ) は定義に "blink": false を書いてまばたかせない。 書き出した立ち絵の faces.json の blink に載る表情だけがまばたく (載っていない古い書き出しなら、まばたかずにそのまま動く)。 閉じ目の絵のぶん HTML が大きくなる (実測: 572 秒・6 表情を使う台本で 10.2MB → 12.9MB)

台本の書き方 (キャラの役割と流れ)

元の資料 (記事・設計書・議事録など) を、めたんがずんだもんに教える掛け合いに書き直す。

役割と口調

	四国めたん (metan)	ずんだもん (zundamon)
役割	解説役。資料を読んだ側として、事実を順に説明する	聞き手。視聴者の代わりに質問し、素朴な誤解を口にし、理解したことを自分の言葉で言い直す
口調	一人称「わたくし」。お嬢様口調 (「〜わ」「〜のよ」「〜かしら」)。落ち着いて丁寧	一人称「ぼく」。語尾は「〜のだ」「〜なのだ」。素直で反応が大きい。「のだ」は 1 行に 1 回まで (合成の声だと語尾の繰り返しが耳につく)。短い反応 (「6 倍も！」) は「のだ」を落としてよい
主な表情	説明 と 通常。問題点は 困り、締めは 笑顔	考え中 (質問)、驚き (意外な点)、笑顔 (納得)。誤解を正されたら 困り
割合	セリフの 6〜7 割	3〜4 割。めたんが 3 行以上続けて話さないよう、間に質問か相づちを挟む

声のスタイル (行の style_id): 既定はノーマル。ノーマル以外は、全体の 5〜8% の行 (短い動画で 2〜3 行、12 分で 7〜10 行) の 1 行の反応や一言にだけ使い、説明の行には使わない (ノーマル以外は聞き取りにくい)。使いどころの例:

キャラ	スタイル	使う場面
ずんだもん	なみだめ	やられた・小さな敗北 (表情 悲しみ か 困り と合わせる)
ずんだもん	ヘロヘロ	疲れた・情報が多すぎて参った
ずんだもん / めたん	ツンツン	すねる (ずんだもん)・鋭いツッコミやツンデレの褒め言葉 (めたん)
ずんだもん / めたん	ささやき・ヒソヒソ	「ここだけの話」の前置き

スタイルの ID はキャラとエンジンの版で決まるので、手順 2 の speakers の出力で名前から引く (台本には ID を書く)。 そのキャラ以外の声の ID を書くと synth が止まる

流れ (チャプターは 4〜6 個。尺が長い (8 分を超える程度) なら増やしてよい。各チャプターはずんだもんの質問で始めると区切りが伝わる)

1. 導入: めたんが今日の話題を言い、ずんだもんが「何の話なのだ？」や「誰向けなのだ？」のように位置づけを聞く
   • 話題を言うときに、資料の結論の一部か意外な点を 1 つ先に見せ、「なぜ？」「じゃあ何が起きているのだ？」という問いを残す (例: 「応答がずれる？」「そう見えることがある。でも、本当に間違った結果が返っているとは限らないの」)。煽らない。 残した問いは本題で必ず回収する
   • 導入の終わりと本題の始まりを、会話ではっきり区切る。導入の最後の行でめたんが「それじゃあ、本題に入るわね」のように 本題へ移ることを言い、ずんだもんが「お願いするのだ」のように応じてから、本題の最初のチャプターを始める。チャプター名 (画面上部のトピック) が切り替わるだけでは、話が前触れなく本題へ移ったように聞こえる
2. 背景: なぜその話が出てきたのか。数字・期限・現状はここで出す
3. 本題: 中身を 2〜3 チャプターに分けて説明する。各チャプターで、めたんの説明 → ずんだもんの質問 → めたんの答え を回す
   • 重要なトピックでは、ずんだもんが深掘りする。重要なトピックとは、資料の結論・前提や制約・判断の理由・リスクのように、 視聴者が誤解すると後の話が分からなくなるもの。めたんの説明を受け流さず、次のように問いかけて理解を一段深める
     • 核心を突く質問: 「なぜそうするのだ？」「それが守れなかったらどうなるのだ？」「〇〇と何が違うのだ？」「誰が決めるのだ？」
     • 詳しい説明を求める: 「もっと詳しく教えてほしいのだ」「具体的にはどういうことなのだ？」
     • 理解の確認: 「つまり〇〇ということなのだ？」と言い直し、めたんが正しければ認め、ずれていれば補う
   • 深掘りは、答えが資料 (と辿ったリンク先) にある問いだけにする。答えの無い問いを立てると、めたんが推測で答えることになる。 資料に書いていない点が核心なら、めたんが分からないこと・未決であること自体を伝える (言い方は下節「資料の語り方」のモードに合わせる)
   • 答えの前に、ずんだもんに予想させる。めたんが状況を出し、ずんだもんが「〇〇すれば解決なのだ？」と素朴に予想して、めたんが 資料に基づいて正す (「普通はそう思うわよね。でも〜」)。視聴者も一度答えを考えることになる。予想は外れる前提で、正す内容は資料にあること
   • 具体例は資料にあるものを使う。資料に無い例を足すなら、めたんが「一般的な例だけれど」と断り、資料の外から足した行として手順 3 で挙げる (作った例は誤解を生むことがある)
   • 同じ型を長く続けない。「説明 → 質問」が 3 往復続いたら、予想・誤解・具体例・言い直しのどれかを挟む
   • 尺が長い (8 分を超える程度) ときは、チャプターの終わりにずんだもんが「ここまでを整理すると〜なのだ」と 1〜2 文で言い直し、 めたんが認めるか補う (途中から見ても迷わないように)
   • 図解 (show): 舞台の中央にカードを出す。図解を 1 つでも使う台本では、最初から最後まで立ち絵が縮んで左右の端に寄り、 中央が空く (図解の出し入れで立ち絵が動かないように)。話題が移ったら {"show": null} で消す (次のチャプターに持ち越さない。機械は止めないので、手順 3-3 の統合確認 (図解) で見る)。種類を合わせて 1 チャプターに 1〜2 回まで (出しっぱなしにすると、話と関係の無いカードが残る)。下の「合わせて 1〜2 個」とは別に数える。 字数の上限は 1 字で何字分も幅を取る特殊な記号 (﷽ ⸻ 等) を想定していないので、それらは上限内でも切れる。普通の全角・半角の文字で書く
     • 重要語 (keyword): チャプターの鍵になる語を、その語を初めて説明する行で大きく出す。語は全角 9 字で 1 行に収まり、 16 字までは文節の切れ目で 2 行に折り返して出る。長いカタカナの複合語 (「サプライチェーン攻撃」) は 1 つの文節として扱われ、 9 字を超えると語の途中で切れるので、2 行になる語は文節が 9 字以内になるように選ぶ (切れると build が止まる)。補足 (sub) は全角 24 字ほどで折り返し、 40 字まで書ける (超えると止まる)
     • 比較 (compare): 2 つのもの (修正前と修正後・案 A と案 B など) の違いを、めたんが説明する行で左右に並べる。 見出しは 8 字まで、項目は 1 列に 1〜3 個で 16 字まで (1 列は全角 8 字ほどで折り返す)。項目は資料にある違いだけを短く書き、 左右で同じ観点を同じ順に並べる (1 つ目どうし・2 つ目どうしが対になるように)。 "build": true を書くと、最初は 1 つ目どうしだけを出し、後の行の "show": "next" ごとに次の対を出す (左右の項目の数を揃え、2 個以上あるときだけ。まだ出していない項目も場所は取るので、カードの大きさは変わらない)。 1 つの対を 1〜2 行のセリフで説明してから次へ進める
     • コード (code): 資料にあるコードの要点を、めたんがその行を説明するところで出す。折り返さずに出すので、1 行は幅 44 まで (半角 1・全角 2 で数える)、11 行まで。言語名 (lang) も幅 12 まで。話の中心の行を highlight (1 始まりの行番号) で強調する。資料のコードを写すときは 省いた行を … の行で示し、字下げはスペースで書く (タブは止まる)。資料の 1 行が幅 44 に収まらないなら、改行と字下げを変えて 複数の行に分けてよい (字句は変えない。確認の観点の「1 行ずつ同じか」はこの改行を除いて見る)。字幕でコードを読み上げない (図解に任せ、セリフは何をしている行かを言う)。 処理の順に何行かを説明するなら、highlight の代わりに "steps": [[2], [3, 4], [6]] (段ごとの強調行。2 段以上で、続く段は違う行にする) を書き、 後の行の "show": "next" で強調を次の段へ動かす (highlight と steps は同時に書けない)
     • 箇条書き (list): 「理由が 4 つある」のような並びを、めたんが数を言う行で出す。項目は 2〜5 個・14 字まで (折り返さない)、 見出し (title) は省略可で 16 字まで。コードの図解で並びを代用しない (等幅の小さい文字になる)。 1 つずつ説明するなら "build": true を書き、後の行の "show": "next" ごとに強調を次の項目へ進める (最初は 1 つ目を強調。説明済みの項目は濃く、まだの項目は薄く出しておく)
     • 段を進める ("show": "next"): 段のある図解 (比較の build・コードの steps・箇条書きの build) を出している間に、図解を変えずに次の段を見せる。 見せるのは行の頭からで、セリフの途中では変わらない。図解が無い・段の無い図解・最後の段を出した後に書くと、合成の前に止まる
     • 図 (image): 構造や流れ (処理の順番・データの行き来・関係) を、セリフだけでは追いにくいところで出す。 小さい図・複雑すぎる図は理解の邪魔になるので入れない。入れてよいのは次を全部満たす図だけ:
       • 言いたいことが 1 つ (「B は A を待つ」など)。要素 (箱・矢印の先) は 5〜7 個まで、文字は短いラベルだけ
       • PNG か JPEG で、図の箱 (569×354 px) の 2 倍の 1138×708 で書き出すのを勧める。文字は 1138×708 なら 48px 以上 (569×354 なら 24px 以上)。 build は次の画像を止める: 幅 569 にも高さ 354 にも届かない (引き伸ばさないので小さく表示されて読みにくい) / 幅 1138 か高さ 708 を超える (縮められて 文字が読めない) / 表示したときに箱の縦横それぞれ半分に届かない細長い形 (縦横比はおよそ 4:5〜16:5 まで) / 向きの情報 (EXIF の Orientation) を持つ JPEG / 壊れた画像
       • 資料の図をそのまま貼らない (資料の図は小さく、要素も多い)。言いたいことだけを描き直す。描き直せないほど複雑なら、図を使わずにセリフで分けて説明する
       • alt に図が言っていることを 1 文で書く (40 字まで。手順 3-3 の統合確認は、これと画像を資料と突き合わせる)
       • build の後に HTML を開いて図の行を表示し、ラベルが読めるかを目で確かめる (手順 7)
     • mermaid の図 (mermaid): 箱と矢印だけの図は、画像を用意せずに mermaid の記法 (code に 1 行ずつ、15 行まで) で書ける。 build が mermaid-cli で 2 倍の大きさの PNG に描き、画像の図と同じ検査に通す。止まるのは描いた図の大きさと形だけで、 要素の数は見ない (実測: 要素 3 個の横一列は細長いので止まり、12 個の格子は通る)。複雑すぎないか (要素 5〜7 個まで) は 上の「図」の基準で自分で判断し、手順 3-3 の統合確認と、手順 3-4・7 の確認で見る。止まったときの案内: 小さい → 図にせずセリフで 説明する / 細長い → 向き (flowchart LR と TD) を変えるか、セリフで説明する / 大きすぎる → 要素を減らすか図を分ける。 形の実測 (大きさはラベルの長さで変わる): 箱 5 つ・4 段 (途中で 2 つに分かれて合流) の図は、横向きで幅を (ラベルを短くしても 1388×348)、縦向きで高さを (628×764) 超えた。箱 4 つ・縦 3 段 (A --> B、B --> C、B --> D。ラベルは 2〜7 字) は 628×556 で 収まった。段の多い図は、描く前に箱を減らすか分けることを考える 入れてよい図の基準は上の「図」と同じ (言いたいことが 1 つ・短いラベル・alt を書く・build 後に目で確かめる)。 描くのに Chrome と npx (Node) が要る (初回に版を固定した mermaid-cli を取りに行く。Chrome は手元のものを使う)。 描いた PNG は script.work/mermaid/ に記法ごとにキャッシュされる。キャッシュの鍵は mermaid-cli の版と記法と倍率で、Chrome やフォントは入らないので、 それらを変えたときに描き直したければ、そのディレクトリを消す
   • 深掘り・予想・具体例・言い直しは、合わせて 1 チャプターに 1〜2 個まで。全部の説明に入れると型が透けて退屈になり、要点もぼやけ、 尺も延びる。視聴の続きやすさより理解を優先する
4. 誤解と懸念: ずんだもんがありがちな誤解 (「〇〇すれば解決なのだ」) を口にし、めたんが資料に基づいて正す。資料に Q&A があればここで使う
5. まとめ: ずんだもんが要点を 1〜2 文で言い直し (笑顔)、めたんが締める
6. 締めの言葉: 台本の最後は必ず締めの挨拶で終える。めたんが解説の終わりを告げて見てくれた人にお礼を言い、ずんだもんが一言で応じる (例: めたん「今日の解説はここまでよ。最後まで見てくれてありがとう」/ ずんだもん「また見てほしいのだ！」。どちらも 笑顔)

声・図解・字幕の役割 (同じことを声と画面の文字で同時に出すと、読むのと聞くのが競合して理解の邪魔になる。役割を分ける)

	運ぶもの	書き方
声 (セリフ)	理由と流れ (なぜ・だから・その結果どうなるか)	ものは名前で呼ぶ。「この図」「これを見て」「ここ」「こちら」で図解を指さない (音だけで聞く人・字幕を消す人・図解の無い区間でも通じるように)
図解 (show)	構造 (何と何が対になるか・どの行の話か・どう変わるか)	語・ラベル・短い句だけを書き、セリフの文をそのまま載せない。重要語の sub も文にしない
字幕	セリフの全文	図解の代わりにしない (図解にしか無い情報を作らない。手順 3-3 の図解の「資料との整合」と同じ)

台本を書いたら、次の 2 つが成り立つかを確かめる (手順 3 の校正で見る):

• 書き起こしだけで筋が通る: 字幕の文だけを順に読んで、話が追える。図解を見ないと意味が取れない行 (「左の方が速いの」だけで、何が左かを言っていない等) が無い
• 図解の並びだけで構造が追える: 図解だけを順に見て、何の話の構造かが分かる。図解の中身が文になっていない

資料の語り方 (2 つのモード。手順 0 で選ぶ)

台本の元にした資料 (レポート・設計書・AI の回答など) をセリフでどう扱うかを決める。元の資料は非公開になることがあるので、 公開する動画では資料の存在を出さない。どちらのモードでも、資料に無い事実を足さない (下の「守ること」) のは同じで、変わるのは言い方だけ。

	資料を明かす (社内向け)	独自調査 (不特定多数に公開)
めたんの立場	資料を読んだ人として紹介する	自分で調べた人として話す
言い方の例	「資料によると」「資料は〜と言っているわ」「資料自身も反論を挙げているわ」	「わたくしが調べたところでは」「〜と言われているわ」「反対の見方もあるの」
分からない点・推測	「資料には書いていないけれど」	「調べた範囲では分からなかったの」「ここはわたくしの推測だけれど」
資料・レポート・回答の存在	出してよい (下書きなら宣言する)	出さない。「資料」「レポート」「回答」「この文書」「AI の分析」と言わない。title と description にも書かない

• 公開された文献 (公式の統計・調査・論文・製品の公式ページ) から引くときは、どちらのモードでも出典を名前で言う (「IPA が公開している調査によると」「Steam の 2026 年 9 月の調査では」)。独自調査のモードで出典を言わずに数字を出すと、 めたんが自分で測った値に聞こえる。出典を言えるのは、手順 3 の裏取りで公開されていると確かめた文献だけ (資料が引用しているだけで 元を確かめられなかったものは、出典の名前を出さずに「〜と言われているわ」と言うか、使わない)
• 資料の結論・決定と検討中の区別・不確かさは、独自調査のモードでもそのまま保つ (資料を隠すために断定を強めない)

守ること

• 資料に無い事実を足さない。めたんが話すのは資料に書いてあることだけ。推測を言うなら推測だと断る (言い方は上の「資料の語り方」)
  • 視聴者の前提知識を補う一般的な説明 (例: ヒープとは何か) は、資料に無くても足してよい。足した行と推測の行は、 台本をユーザーに見せるときに挙げる (手順 3)
• 資料の結論を変えない。決定事項か検討中かの区別 (たたき台・案・決定) を、台本でもその通りに言う
• 資料が下書き (WIP・未公開・案の段階) なら、導入の最初の方でめたんがそう宣言する (例: 「最初にお断りしておくわ。この資料はまだ 下書きで、内容はこれから変わりうるのよ」)。下書きかどうかは、資料のメタ情報 (公開状態・WIP の印) と本文 (「案」「要確認」) で見る。 独自調査のモードでは資料に触れず、話題そのものが未確定であることを言う (「まだ決まっていない話で、これから変わりうるのよ」)
• 資料の中で値が食い違う事柄は片方を断定しない。「〜までの計画」「仮置き」「まだ要確認」のように、資料が持つ不確かさのまま言う
• 馴染みの薄い名称は、初めて出たところでずんだもんが「〇〇って何なのだ？」と聞く。対象は、特定の製品・サービス (専門的なデータベース・業界向けの SaaS など)、業界や社内の略語、契約・業務の用語 (準委任など)。めたんが 1〜2 文で答える
  • 答えは資料の説明を優先し、資料に無ければ一般的な説明を足す。製品・サービスの説明は公式の説明で裏を取り、足した行として手順 3 でユーザーに挙げる
  • 広く知られた名称 (Slack・Google など) と、資料の中で既に説明した名称には聞かない。2 回目以降に出たときも聞かない
• 個人名は、話の理解に必要なときだけにする。役割 (PM・開発リーダー等) で言えるなら役割で言う
• 1 セリフは 1〜2 文、字幕 2 行 (60 字程度) まで。長い説明は同じ話者の行に分けるか、ずんだもんの相づちを挟む。 字幕は次の行が始まるまで出ているので、その間に読み切れる長さにする (目安は 1 秒 7.5 字まで。超えた行があると build が書き出す前に止まる。手順 6。lint は音声の長さを知らないので、この速さは見ない)
• 数は半角の算用数字 (0〜9) で書く (字幕に漢数字を出さない)。日付・年・人数・個数・範囲はすべて数字: 10月1日 2027年3月末 4人 5〜7本。数を表さない慣用的な語 (一番の・一緒に・一般・統一) は漢字のまま
• 英字の略語・数字・固有名詞は、synth の後に読みを確かめる (手順 5)。誤読なら字幕の text は そのままにして、行の read か台本全体の readings で音声だけを直す (例: "text": "5〜7本", "read": "ごほんからななほん")
• 書いた台本は、校正と裏取りを通してから、build の前にユーザーに見せる (事実の取り違えは音声にしてからだと直しにくい)

台本 JSON

{
  "title": "タイトル", "description": "概要 (改行可)",
  "lead_in": 0.4, "gap": 0.35, "speed": 1.0,
  "cast": { "metan": { "speed": 1.05 } },
  "readings": { "datetime": "デートタイム", "UPDATE": "アップデート" },
  "lines": [
    { "who": "metan", "face": "説明", "text": "セリフ", "chapter": "ここから新しい章", "pause_after": 0.8 },
    { "who": "zundamon", "face": "驚き", "text": "そうなのだ？", "speed": 1.1,
      "show": { "type": "keyword", "text": "排他ロック", "sub": "同じ行を同時に書かない" } },
    { "who": "metan", "text": "直す前と後を並べるわね。",
      "show": { "type": "compare", "left": { "title": "修正前", "items": ["ロックなしで読む"] },
                "right": { "title": "修正後", "items": ["待ってから書く"] } } },
    { "who": "metan", "text": "次の話に移るわ。", "show": null }
  ]
}

キー	意味
title	動画・HTML の舞台の左上に出る (HTML ではページの見出しにも出る)。省くと台本のファイル名
date	動画・HTML の舞台の右上に「作成日 …」として出る文字列。省くと build した日 (YYYY-MM-DD)。作り直しても日付を変えたくないときに書く
source_mode	資料の語り方のモード (下節「資料の語り方」)。"internal" (資料を明かす。省略時) か "public" (独自調査)。"public" なら lint が資料の存在が分かる語を目安として出す。見た目は変わらない
overlays	舞台に重ねて出すメタデータを選ぶ配列。title (左上のタイトル)・date (右上の作成日)・topic (上部中央のチャプター名) から出すものを書く。省くと 3 つとも出し、[] なら何も出さない。HTML の見出し・概要欄・チャプター一覧には効かない
lead_in / gap	冒頭の無音 / セリフ間の無音 (秒)。行ごとの pause_after が gap より優先
speed pitch intonation volume	VOICEVOX の話速・音高・抑揚・音量。行 → cast → 台本全体 の順で優先 (pitch 等は行か cast のみ)
style_id	声のスタイル (ささやき等) を変えるとき。行か cast に書く。そのキャラ以外の声の ID なら synth が止まる
cast.*.faces	立ち絵の dir (psd_faces.py の出力。台本からの相対パスか ~ 始まり)。省くと assets の既定を使い、それも無ければ丸アバター
face	行の表情。上の語彙のどれか
read	その行の音声だけを差し替える文 (読み違いの修正用)。字幕は text のまま
readings	台本全体の読みの置き換え表 ({"字幕の語": "読ませたい語"})。read の無い全行の音声に当てる (長い語から先に置き換える)
acronyms	1 文字ずつ読むのが正しい英字の語の配列 (["QRO"])。kana --check が警告しない。一般の技術語は skill の acronyms.json に足し、ここにはその台本だけの語 (社内の略語) を書く。音声は変えない
chapter	その行から新しいチャプター。概要欄のチャプター一覧から飛べる。チャプターが 2 つ以上あると (overlays で topic を外していなければ)、その行から次のチャプターまで、画面の上部中央にチャプター名 (トピック) が出る。チャプターの頭は、1 行目の音声が終わるまで (最短 1.5 秒・最長 4 秒。1 行目に図解が出ていれば 1.5 秒)、舞台の中央に「CHAPTER 番号」とチャプター名を大きく出す (区切りのカード。その間はトピック名と図解を隠す)
show	舞台の中央に出す図解。この行から、次に show を持つ行の手前まで出し続け、null で消す。"next" は図解を変えずに段を進める (比較の "build": true・コードの "steps": [[行番号…], …]・箇条書きの "build": true)。重要語 ({"type": "keyword", "text": "語 (16 字まで)", "sub": "補足 (省略可。40 字まで)"}) と比較 ({"type": "compare", "left": {"title": "見出し (8 字まで)", "items": ["項目 (16 字まで)", …1〜3 個]}, "right": {…同じ形}, "build": 1 つずつ見せるなら true (省略可。左右の項目の数を揃える)}) と箇条書き ({"type": "list", "title": "見出し (省略可。16 字まで)", "items": ["項目 (14 字まで)", …2〜5 個], "build": 1 つずつ強調するなら true (省略可)}) とコード ({"type": "code", "lang": "言語名 (省略可。幅 12 まで)", "lines": ["1 行 (幅 44 まで)", …1〜11 行], "highlight": [強調する行番号 (省略可)], "steps": [[段ごとの強調する行番号], …2 段以上。続く段は違う行にし、何も強調しない段は []] (highlight の代わりに。省略可)}) と図 ({"type": "image", "src": "画像のパス (台本からの相対か ~ 始まり。.png / .jpg / .jpeg)", "alt": "図が言っていること (40 字まで)"}。画像は build のときに読んで HTML に埋め込む。欠け・大きさの範囲外・2MB 超は build で止まる) と mermaid の図 ({"type": "mermaid", "code": ["flowchart LR", " A --> B", …1〜15 行], "alt": "…"}。build が PNG にしてから図と同じ検査に通す)。書けないキー・空の欄・長すぎる欄・項目の数の誤りは synth / kana / build の前に止まる。行の show 自体の綴り違い (shows 等) は検出しない
credits	追加のクレジット。声 (VOICEVOX:<キャラ>) と立ち絵 (定義ファイルの credit) は自動で入る

制約・注意

• 出力は mono / 16bit / 24kHz に揃える (build が違う wav を拒否する)。synth --force で作り直せる
• 口パクのタイミングはモーラ長から作った推定で、wav の実際の長さに合わせて全体を伸縮している。音とのずれが目立つなら、 wav の音量から作る方式に差し替える (dotfiles の src/zundamon-kaisetsu/internal/build/build.go の MouthTrack)
• mp4 の絵は Chrome の描画なので、HTML と同じフォントになる。配色は OS の設定によらず明るい方に固定している
• mp4 の映像は H.264 (libx264 の -tune stillimage。libx264 の無い ffmpeg では h264_videotoolbox)。AV1 は採らない: Apple シリコンに AV1 のハードウェアエンコーダは無く (再生だけ)、libsvtav1 で書き出すと静止画中心のこの動画ではむしろ大きく (実測: 194 秒の動画で H.264 5.78MB / AV1 6.51〜7.01MB)、 古い端末で再生できない。HEVC のハードウェア (hevc_videotoolbox) は 13.27MB
• mp4 の撮影は Chrome の起動 (1 回 1 秒強) が律速。--jobs で並列数を変えられる (既定 4)。--user-data-dir を付けると 撮影後も Chrome が終わらないので付けていない
• CPU が混んでいるときに、撮影中の Chrome が own watchdog expired (rc=2) で落ちたことがある (同じ条件の再実行で通った)。 負荷との関係は仮説で、撮影前の待機 (waitForIdleCPU) はそのために入れている。待った後でも落ちたら、--jobs を下げて build し直す

改善点を挙げるとき

動画を作り終えたときや「改善点を挙げて」と言われたときは、improving.md の観点 (生成コスト・台本の精度・見た目・保守) と 測り方で振り返る。新しい観点が見つかったら、その文書を更新する。