四国めたんとずんだもん (VOICEVOX の声と立ち絵) の掛け合いで解説動画を作る。台本 JSON からセリフを合成して 1 本の音声にまとめ、字幕・立ち絵 (場面に合わせた表情)・口パク付きで、HTML プレイヤー 1 ファイル (書き起こし・チャプター付き) か mp4 動画、またはその両方に書き出す。
「ずんだもん解説を作って」「ずんだもん動画を作って」「VOICEVOX で掛け合い動画」「キャラの音声で解説を読み上げさせたい」「zundamon-kaisetsu」で発火。ブラウザ内のリアルタイム合成 (Web Speech API) が要るときには使わない。
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
/audio_query → /synthesis)audio_query のモーラ (音の単位) の母音から 30fps で作る
(a・o は開き、i・u・e は半開き、ん・っ・無音・m/b/p の子音は閉じ)。それをもとに、各フレームの見た目の状態
(字幕の行・話し中か・口の開き) を変わり目だけの列にする。まばたき (目を閉じているキャラ) も時刻から決めて別の列に入れるnew Audio() で再生し、requestAnimationFrame で
audio.currentTime から状態を引いて描く。シーク・速度変更をしても音とずれない#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 つの見た目は同じになる。
声のモデルはエンジンに同梱されている (無料)。エンジンは 127.0.0.1:50021 で待たせる。
起動と停止は自動: synth / kana / speakers は、そのポートで誰も待ち受けていなければ自分で起動し、見張りのプロセスを 1 つ残す。
見張りは、最後にエンジンを使ってから 10 分たったら止めて終わる (コマンドが途中で死んでも止まる。止め忘れが起きない。起動し直しは 2 秒程度)。
up で明示的に起動したエンジンとデスクトップアプリには触らない (up で起動したものは down まで動き続ける)。
起動のしかたは次の優先順で、自動起動と up が同じ規則で選ぶ。どれで起動しても API は同じ。
container (Apple のコンテナ CLI): あれば最優先で使う。サービスが止まっていれば container system start が要る
(初回はカーネルを入れるか対話で聞かれる。非対話で入れるなら --enable-kernel-install。どちらもユーザーに確認してから打つ)docker: container が無いときに使う。Docker Desktop 等が起動している必要があるイメージは voicevox/voicevox_engine:cpu-latest (arm64 版あり)。初回は取得に数分かかる。
別ホストのエンジンを使うときは --engine URL か環境変数 VOICEVOX_URL (up / down は手元のエンジン専用)。
非公式の Web API は台本を外部へ送るので既定では使わない。
VOICEVOX:ずんだもん の形。登場したキャラクターの分を build が自動で入れる (HTML の「クレジット」に出る。mp4 の映像には入らないので、build が mp4 を書いたときに標準出力へ出す一覧を概要欄などに貼る)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 にある。
overlays から date を外す
("overlays": ["title", "topic"])。左上のタイトル・上部中央のトピック名も、外したいと言われたら同じキーで外す。
資料の語り方のモード (下節「資料の語り方」の「資料を明かす」か「独自調査」) も同じ問いで聞く (指定済みなら聞かない)。
社内向けなら資料を明かす、不特定多数に公開するなら独自調査、と見る人で勧める。選んだモードは台本の source_mode に書く (手順 3 の lint が見る)$DV check
# OK 音声の圧縮 / 立ち絵の書き出し: uv / mp4 用: Chrome / mp4 用: H.264 / コンテナ (container を優先) / そのサービス / VOICEVOX エンジン
brew install・container system start) はユーザーに確認してから行うup は打たない)
$DV speakers # 例: 四国めたん: ノーマル=2, ... / ずんだもん: ノーマル=3, ...
skill-tmpdir zundamon-kaisetsu を打ち、出たパスの下の <名前>/ をリテラルで使い回す。<本体 checkout>/tmp/zundamon-kaisetsu/<session-id>/<名前>/。完成物の場所はユーザーに絶対パスで伝える)。書く前と書いた後に 1 体ずつ、計 2 体のサブエージェントを走らせる
(Agent ツール・model: "sonnet"・読み取りのみ。資料の取得手段 (CLI・URL・ファイル) と視聴者の前提をプロンプトに渡す)
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 にも渡すkana --check・読み分け候補の grep (手順 5 の 3)・図解と資料の突き合わせ (手順 3-3 の図解の観点) を見る。
その場合も工程を黙って省かず、サブエージェントの確認を飛ばしたことを、台本を見せるとき (手順 3-4) と完了の報告でユーザーに伝えるtemplates/review-3-1.md を埋めて渡す)
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 で上書きする$DV lint script.json --source 資料) を通してから、確認を 1 体のサブエージェントにまとめて行う
--source (資料のテキストのパス) を付けたときの資料との突き合わせ (資料に無い数字・資料に無い英字の語・導入の終わりに本題へ移る言葉が無い)・2 つ目以降のチャプターの最初の行がずんだもんの質問でない・1 チャプターの図解が 3 回以上・独自調査のモード (source_mode: "public") で資料の存在が分かる語 (「資料」「レポート」「回答」「文書」「記事」「AI の分析」等。字幕・読み上げ・タイトル・概要・クレジット・チャプター名・図解の文字を見る。公開された文献を名前で引く行と字面で区別できないので目安にしている。確認役に渡し、元の資料のことを言っている行を直す。言い換えは見ない)templates/review-3-3.md を埋めて渡す
(観点は下の箇条が正本で、テンプレートはそれを読むよう指すだけ。lint の結果も渡して重複させない)。先に手順 4 の synth と
手順 5 の 1 (kana --script の書き出し) を回し、台本・資料・kana.tsv のパスと、手順 3-1 で確認済みの資料の外の事実を渡す。
観点を順に見て、問題のある行だけを「観点 / 行番号 / 問題 / 直し方」で返させるstyle_id を書いてノーマル以外の声にしている行、
lint の一覧に無い言い方で画面のものを指す行 (「これ」「ここ」「こちら」「左の」「上の」で図解を指す)、
書き起こしだけでは意味が取れない行 (下節の「声・図解・字幕の役割」の 2 つの点検)、
資料の語り方のモードから外れた行 (下節「資料の語り方」。独自調査なら、元の資料・レポート・回答の存在が分かる行と、
公開された文献を出典を言わずに使っている行。title と description も見る)show を使った台本だけ): 図解はセリフと別の場所に要約を書くので、食い違いの入口が増える。次の 2 つを両方見させる
show の行から、次に show を持つ行の手前まで) を挙げさせ、
図解の語がその区間のセリフで話されているか、話題やチャプターが移っても図解が残っていないか (消すなら null)、
図解と字幕で用語・表記が揃っているかを見る。コードの図解は識別子を読み上げないので、語ではなく、その区間のセリフが
強調した行 (highlight) の役割を説明しているかを見る。段のある図解は段ごとに (出した行と "next" の各行で)、
その段で現れた項目・強調した行を、その行のセリフが話しているかを見る (先の段の項目を前の行で話していないか)… の行は省いた印なので、その前後が資料で続いているか。幅に収めるための改行と字下げの違いは除き、字句が同じかを見る) を見る。コードの中の識別子・数字はセリフに無くてよい。
図は画像を開いて、描かれた関係・順番が資料と合っているか、alt と食い違っていないか、要素が多すぎないか (5〜7 個まで) を見るkana.tsv で字幕と読みが食い違う行 (観点と表記の約束は手順 5 の 3 と同じ)
kana.tsv の読みの列だけを順に読み、字幕を見ずに意味が取れない行も返させる
(書き言葉の漢語・同じ読みの別の語と区別できない漢語。基準は「守ること」の「耳で聞いて分かる言葉で話す」)。
字幕を見ながらだと書き言葉に気づきにくいので、見る対象を音に変えるkana --script で kana.tsv を書き出し直してから手順 5 の 2 へ進むlint --source の「資料に無い数字」「資料に無い英字の語」の一覧を下書きに使う)。
図は画像そのものも見せる (小さい図・複雑すぎる図はここで外すか描き直す)。
台本そのものは $DV view script.json の一覧 (チャプター・話者 (表情)・字幕と、図解を出す・段を進める・消す行。合成は要らない) をファイルに書いて、そのパスを渡す$DV synth script.json
audio_query の結果が script.work/ に入る。ファイル名は合成入力 (文・声・話速等) のハッシュなので、
台本を直して再実行すると、行の挿入・削除・並べ替えを含めて変わった行だけ合成し直すstyle_id がエンジンに無いか、そのキャラ以外の声なら止まる--force (これらはキャッシュの鍵に入らない)。台本から外れた古いキャッシュの件数が
出たら、script.work/ の中の使われていない *.wav / *.query.json を消してよい (script.work/ ごと消すと mermaid/ の図も描き直しになる)$DV kana --script script.json > kana.tsv で全行の 行番号 / 話者 / 字幕 / 読み を書き出す (音声を差し替えた行には *)$DV kana --script script.json --check で、英字の語を 1 文字ずつ読んだ行 (SOLIDWORKS を「エスオーエル…」) を
警告し (あれば rc=1)、台本に出る英字の語の一覧 (語だけを読ませた読みつき) を出す。警告の行は誤読なので直す (手順 5 の 4〜5)。
ただし 1 文字ずつ読むのが正しい略語なら、一般の語 (技術用語) は $S/acronyms.json (1 文字ずつ読む略語の一覧) に足し、
その台本だけの語 (社内の略語・製品の略称。公開の skill に置けないもの) は台本の acronyms (["QRO"]) に書く。
この検査が見るのは 1 文字ずつ読んだ形だけで、崩れた読み (SIer を「エスイアー」) と漢字の読み分けは見ない。通っても誤読が無いことにはならないkana.tsv で読みを見るgrep -F -f "$S/kanji-candidates.txt" kana.tsv (1 行 1 語の候補の一覧)。正しく読めている行も混ざる (候補の一覧)。
1 体にまとめた確認は、この種類を見落とした (試験で「Boot Camp の上」を「じょう」と読んだ行。issue 673 の進捗)' はアクセントの位置、/ と 、 は区切り、_ は無声化。助詞の「は」「を」は ワ オ、長音は エエ オオ
のように母音を重ねて書かれる (セエス'ウ = 整数)。これらは誤読ではないeql?)。
辞書 readings.json に載っている語は確認済みなので除くreadings に書く
(「合田道人」を書いても「合田さん」は「あいださん」と読まれた)。書名は「日本」が「にっぽん」、題名の「星」が「ほし」(いちばんぼし)、
歌詞の「こわれて消えた」が「ぎえた」(連濁) になった。引用は字幕を変えずに readings か read で読みを直す$DV kana "候補1" "候補2" … で合成せずに比べる (--who zundamon で声を変える)。
候補にはカタカナ・ひらがな・英字のままを並べる。カタカナにすると逆に誤読することがある
(実例: 「ヘロクの」は文頭の「ヘ」が助詞扱いで「エ ロクノ」。英字の「Herokuの」なら「ヘロクノ」)。指摘が誤り (正しく読めている) なら採らないreadings ({"datetime": "デートタイム"}) で直し、その行だけの直しは行の read で直すsynth し直し (変わった行だけ合成される)、kana --script で直した行の読みを確かめる$S/readings.json に足す。足す前に $DV kana "<語>" "<読み>" で、
語のままでは誤読し、読みにすれば正しく読まれることを確かめる。文脈で読みが変わる語 (値 = ね / あたい、親、空) は辞書に入れず、
その台本の readings か read で直す (辞書は全行に当たる)。文脈で読みが変わる語を誤読していたら、その語を $S/kanji-candidates.txt に 1 行で足す (次の台本から手順 5 の 3 の候補に載る)。固有名詞は、公開してよい一般の語 (製品名・技術用語) だけを足す。
置き換えは大文字小文字を区別した部分一致 (長い語から先) なので、他の語の一部に現れる短い語は足さない (RAM は PARAM・FRAME
に当たる)。足すなら、その語を含む派生語も一緒に足して守る (cache には cached・caches、queue には enqueue・dequeue・queues)$DV build script.json -o out --format html|mp4|both (拡張子は形式に合わせて付く)
credits) を 1 行ずつ標準出力に出す。概要欄に貼るようユーザーに渡す--bitrate 96k で音質を上げられる (既定 64k)。mp4 は 1280x720 (720p) 固定pause_after で次の行までの間を足して build し直す (pause_after は合成の鍵に
入らないので synth は要らない)。分かったうえでそのまま書き出すなら --allow-fast-captions
(字幕が出ている間 = その行の開始から次の行の開始まで に 1 秒 7.5 字を超える行。英字も 1 字ずつ数えるので、英字の多い行は出やすい)--allow-label-wrapsopen 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 で切り出して見る$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。
jiikko/assets を assets/ にサブモジュールとして置いている。空なら
git -C "$S" submodule update --init assets で取得する (権限のあるアカウントでだけ取れる)表情を変える・素材を差し替えるときは、PSD から書き出し直す:
faces/<キャラ>.json を直す。表情ごとに使うレイヤーと、口の 閉じ / 半開き / 開き の 3 枚を書く。
まばたきの閉じ目は全体の blink に 1 つ書き、目を閉じた表情を足したらその表情に "blink": false を書く。
素材の版でレイヤー名が変わったら、無いレイヤーを名指しして止まるので定義を直す$S で実行する (psd-tools を uv run --with で使う。1 キャラ 1〜2 分)。
--preview の画像 (全表情 × 口 3 段階の一覧。閉じ目の版も並ぶ) をユーザーに見せて確認する表情の語彙 (全キャラ共通。定義ファイルはこの 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 分を超える程度) なら増やしてよい。各チャプターはずんだもんの質問で始めると区切りが伝わる)
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): 構造や流れ (処理の順番・データの行き来・関係) を、セリフだけでは追いにくいところで出す。
小さい図・複雑すぎる図は理解の邪魔になるので入れない。入れてよいのは次を全部満たす図だけ:
alt に図が言っていることを 1 文で書く (40 字まで。手順 3-3 の統合確認は、これと画像を資料と突き合わせる)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 やフォントは入らないので、
それらを変えたときに描き直したければ、そのディレクトリを消す笑顔)、めたんが締める笑顔)声・図解・字幕の役割 (同じことを声と画面の文字で同時に出すと、読むのと聞くのが競合して理解の邪魔になる。役割を分ける)
| 運ぶもの | 書き方 | |
|---|---|---|
| 声 (セリフ) | 理由と流れ (なぜ・だから・その結果どうなるか) | ものは名前で呼ぶ。「この図」「これを見て」「ここ」「こちら」で図解を指さない (音だけで聞く人・字幕を消す人・図解の無い区間でも通じるように) |
図解 (show) | 構造 (何と何が対になるか・どの行の話か・どう変わるか) | 語・ラベル・短い句だけを書き、セリフの文をそのまま載せない。重要語の sub も文にしない |
| 字幕 | セリフの全文 | 図解の代わりにしない (図解にしか無い情報を作らない。手順 3-3 の図解の「資料との整合」と同じ) |
台本を書いたら、次の 2 つが成り立つかを確かめる (手順 3 の校正で見る):
資料の語り方 (2 つのモード。手順 0 で選ぶ)
台本の元にした資料 (レポート・設計書・AI の回答など) をセリフでどう扱うかを決める。元の資料は非公開になることがあるので、 公開する動画では資料の存在を出さない。どちらのモードでも、資料に無い事実を足さない (下の「守ること」) のは同じで、変わるのは言い方だけ。
| 資料を明かす (社内向け) | 独自調査 (不特定多数に公開) | |
|---|---|---|
| めたんの立場 | 資料を読んだ人として紹介する | 自分で調べた人として話す |
| 言い方の例 | 「資料によると」「資料は〜と言っているわ」「資料自身も反論を挙げているわ」 | 「わたくしが調べたところでは」「〜と言われているわ」「反対の見方もあるの」 |
| 分からない点・推測 | 「資料には書いていないけれど」 | 「調べた範囲では分からなかったの」「ここはわたくしの推測だけれど」 |
| 資料・レポート・回答の存在 | 出してよい (下書きなら宣言する) | 出さない。「資料」「レポート」「回答」「この文書」「AI の分析」と言わない。title と description にも書かない |
守ること
read で音声だけ変えずに text を言い換える10月1日 2027年3月末
4人 5〜7本。数を表さない慣用的な語 (一番の・一緒に・一般・統一) は漢字のままtext は
そのままにして、行の read か台本全体の readings で音声だけを直す (例: "text": "5〜7本", "read": "ごほんからななほん"){
"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) は自動で入る |
build が違う wav を拒否する)。synth --force で作り直せるsrc/zundamon-kaisetsu/internal/build/build.go の MouthTrack)-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--jobs で並列数を変えられる (既定 4)。--user-data-dir を付けると
撮影後も Chrome が終わらないので付けていないown watchdog expired (rc=2) で落ちたことがある (同じ条件の再実行で通った)。
負荷との関係は仮説で、撮影前の待機 (waitForIdleCPU) はそのために入れている。待った後でも落ちたら、--jobs を下げて build し直す動画を作り終えたときや「改善点を挙げて」と言われたときは、improving.md の観点 (生成コスト・台本の精度・見た目・保守) と
測り方で振り返る。新しい観点が見つかったら、その文書を更新する。
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
プロジェクト監査。「監査して」「audit」「/audit」で発火。設計/UX/品質/テストなどの観点でコードベース全体を監査し、課題をissuesディレクトリに書き出す。実行ログで重複実行を防止。特定の差分・コミットのレビューには使わない（codex-review / cross-review を使う）。
The English summary is being prepared. Showing the original description.
AVFoundation (AVPlayer / AVPlayerLayer / AVPlayerItemVideoOutput / AVAsset) の落とし穴・文書化されていない実装挙動・debugging チェックリストを集約した reference skill。Swift / Objective-C で AVPlayer を使った動画再生 / seek / scrub / frame stepping を実装・debug するときに発火。VLCKit ではなく **AVFoundation 系** の問題に特化。
The English summary is being prepared. Showing the original description.
このセッションで行った変更をコミットする。「コミットして」「commit」「/c」で発火。push はしない／クレデンシャルは混入させない。
The English summary is being prepared. Showing the original description.
ディレクトリ・レイヤーごとに置いた CLAUDE.md と README.md が実体 (コード・コマンド・構成) とずれていないかを点検し、裏の取れた乖離だけを直す。引数で対象のディレクトリを任意に指定できる (省略時は repo 全体)。「CLAUDE.md を refresh して」「README が古くないか見て」「claude-md-refresh」「/claude-md-refresh」で発火。issues/ の更新漏れは issue-writeback / issue-sync の担当で、この skill は扱わない。
The English summary is being prepared. Showing the original description.
一時領域 (/private/tmp の Claude Code の作業場所・$TMPDIR・dotfiles の tmp/) に溜まったものを bin/tmpclean で数え、消す候補を種類ごとに見せて、ユーザーが承認した plan の古くて使用中でないものだけをゴミ箱へ移す (dotfiles の tmp/ は別の承認を取って make clean-tmp で消す)。「/tmp を掃除して」「一時ファイルを片付けて」「TMPDIR が溜まっていないか見て」「cleanup-tmp-dir」で発火。消す前に必ず承認を取る。
The English summary is being prepared. Showing the original description.
Codex が設計・実装を担い、Claude が要件確定・成果物の検証・反復・commit/push を管理する。「codex に書かせて」「codex メインで実装」「codex-drive」で発火。大きめの機能・移植・プロトコル実装向け。余剰トークンを厚く使う運用も選べる。
The English summary is being prepared. Showing the original description.