Yari-tuber/math-rap-video

口诀解説動画（数学ラップ）

ある知識ポイントを約1分の解説動画にします。覚えやすい理由は、3つの要素が重なり、かつ全てが同じオーディオトラックに同期しているからです：

• 耳：固定リズム、1フレーズ1小節、韻が通しで踏まれているので、口ずさみやすい
• 言語：8～10文字の口诀を2～3回繰り返し、画面上部に常時表示
• 目：歌詞の文字に合わせて図形が段階的に動くため、学習者は「なぜ正しいのか」を視覚的に理解できる

ナレーションの構成は固定です：問題提示 → 罠（愚直な方法では混乱する）→ 口诀提示 → デモ → 原理説明 → まとめ。

役割分担：誰が何を提供するか

部分	担当	説明
口诀、歌詞、絵コンテ	あなた（AI）が書き、ユーザーが確認	ルールは references/lyrics.md 参照
オーディオ（音声＋音楽）	ユーザーまたはクライアント自身が提供	どのモデル、誰の声を使うかは彼らが決定します。references/audio.md の「クライアントへの要求」を渡してください。このスキルはユーザーに代わってプラットフォームを選択したり、デフォルトで費用を発生させたりしません
字幕タイミング	スクリプトが計算	どのツールで出力されたSRTでもよく、誤字があっても問題ありません
背景映像	素材ライブラリから自動選択	assets/backgrounds/ にあり、用途別にタグ付けされています。自分で追加することも可能です
図形、口诀、数式、字幕	スクリプトがフレームごとに描画	あなたはその問題専用の storyboard.json と graphics.py のみを書きます

環境

初回使用時はまず自己診断を実行し、不足しているものとそのインストール方法を確認します：

python $SKILL/scripts/check_env.py

必要なもの：Python 3.10+（pip install pillow numpy librosa pypinyin）、ffmpeg / ffprobe、中国語の太字フォント（一般的なシステムフォントが自動検出されます）、背景素材ライブラリ。素材ライブラリは以下の優先順位で検索されます：環境変数 MATH_RAP_LIBRARY → スキル内の assets/backgrounds/ → 共有場所 ~/.math-rap-video/backgrounds/。素材ライブラリがない場合は python $SKILL/scripts/install.py --library <素材ライブラリ圧縮ファイル.zip> を実行します。

以降、$SKILL はこのスキルが配置されているディレクトリ（この SKILL.md が置かれているフォルダ）を指します。これは事前定義された環境変数ではありません。コマンドを実行する際は実際のパスに置き換えるか、事前に設定してください（bash：export SKILL="/パス/math-rap-video"；PowerShell：$SKILL="C:\パス\math-rap-video"）。パスにスペースや中国語が含まれる場合は引用符で囲んでください。全てのスクリプトは通常のコマンドラインプログラムであり（--help をサポート）、コマンドを実行できるAIや人間であれば、特定のツールに依存せずに使用できます。

フロー

1 作詞と絵コンテ作成 ──→ 2 ユーザーからオーディオ提供 ──→ 3 prepare_audio でタイミング計算と検証
                                        │
4 storyboard.json + graphics.py を作成 ←────┘
        │
5 チェック + プレビュー画像（確認）──→ 6 build_video で動画出力 ──→ 7 チェックと納品

各ステップが完了したら、簡潔な結果をユーザーに伝えます。ステップ1と5では、ユーザーの確認を得てから次のステップに進みます。

ユーザーが完成した歌詞とオーディオを持っている場合（歌詞が確定し、オーディオがそれに合わせて作成されている場合）：歌詞は一字も変更しないでください。変更すると映像と歌詞が一致しなくなります。ステップ1では以下の3つのことだけを行います：新しいプロジェクトを作成し、歌詞をそのまま lyrics.md に配置し、最後に絵コンテテーブルを追加します。check_lyrics.py の結果は参考程度とし、これに基づいて歌詞を変更しません。その後、ステップ3から続行します。

1. 新しいプロジェクトを作成し、口诀、歌詞、絵コンテを作成する

python $SKILL/scripts/new_project.py <作品ディレクトリ>          # サンプル（数直線）をコピーして開始
python $SKILL/scripts/new_project.py <作品ディレクトリ> --blank  # または空のテンプレートから開始

references/lyrics.md に従って lyrics.md を記述します：1フレーズ = 1小節、各フレーズ11～15文字（原理説明の段落は9～11文字）、韻は通して踏むこと。構造は Verse 1（14フレーズ）+ Hook（2フレーズ、口诀は独立して歌う）+ Verse 2（8フレーズ）です。

絵コンテは lyrics.md の末尾の ## 絵コンテ セクションに記述します（表形式：フレーズ番号、映像アクション、歌詞のどの文字でトリガーするか）。これはユーザー確認用であり、ステップ4でコードを書く際の根拠となります。スクリプトはこれを読み込みません。

書き終えたら歌詞の検査を実行し、「修正必須」なものを全て修正し、「推奨」は一つずつ確認します：

python $SKILL/scripts/check_lyrics.py <作品ディレクトリ>     # 構造、各フレーズの文字数、韻、聞き間違えやすい表記

例題の数字は全て手動で検算してください（スクリプトでは数学的な検証はできません）。その後、口诀、歌詞、絵コンテをユーザーに確認してもらいます。

2. ユーザーがオーディオを提供する

確認済みの歌詞と references/audio.md の「クライアントへの要求」をユーザーに渡します。ユーザーは任意の方法でオーディオを作成できます：AI音楽プラットフォーム、人間のラップ、TTSや人間のナレーションに伴奏を加えるなど。返ってくるものは：

• 1つまたは複数のオーディオファイル（mp3 / wav）、音声を含むもの。AI生成の場合は、比較のために2～3バージョン用意することを推奨
• 可能であれば字幕ファイル（SRT）。ない場合は、お手持ちの音声認識ツールでオーディオを認識し、SRTをエクスポートしてください

ユーザーがあなたに代わりに曲を生成するよう明確に要求し、かつElevenLabsのAPIキーを提供した場合、scripts/gen_music.py を使用できます（使用方法は references/audio.md を参照）。これはオプションであり、バージョンごとにユーザーのクレジットを消費するため、生成前にその旨を説明してください。

3. オーディオの処理：タイミングを計算し、このバージョンが使用可能か判断する

python $SKILL/scripts/prepare_audio.py <作品ディレクトリ> --audio 歌.mp3 --srt 認識.srt --bpm 90 --intro-bars 2

認識結果を歌詞にマッピングし（誤字や区切りの違いは問題ありません）、速度と拍を検出し、timing.json を書き出し、オーディオを作品ディレクトリにコピーします（動画出力時にここから読み込むため、作品ディレクトリにオーディオファイルが追加されるのは正常です）。最後の行で結論を出力します：

• 使用可能：続行します。「マッチ率が低い」フレーズがある場合は記録し、納品時にユーザーにそのフレーズを確認するよう伝えます
• 別のバージョンを推奨（終了コード3）：理由がリストアップされます。よくあるのは、特定のフレーズが歌われていない、ボーカルの入りが遅い、全体的に圧縮されている、などです。別のバージョンのオーディオを使用し、無理に使い続けないでください

複数のオーディオバージョンがある場合は、それぞれ異なるファイルに書き出して比較し、選択したものを timing.json としてコピーします：

python $SKILL/scripts/prepare_audio.py <ディレクトリ> --audio 生成_01.mp3 --srt 01.srt --bpm 90 --intro-bars 2 --out timing_01.json
python $SKILL/scripts/prepare_audio.py <ディレクトリ> --audio 生成_02.mp3 --srt 02.srt --bpm 90 --intro-bars 2 --out timing_02.json
cp <ディレクトリ>/timing_02.json <ディレクトリ>/timing.json

選択方法は references/audio.md のセクション3を参照。簡単に言うと：まず「別のバージョンを推奨」を除外し、次に口诀の2フレーズのマッチ率が最も高いものを選び、最後にリズムの整い方を確認します。2つが競合する場合は口诀の明瞭さをリズムの整い方より優先します：視聴者が覚えるのは口诀だからです。

その他の場合：純粋な解説ナレーション、拍のないオーディオには --no-beat を追加；SRTがない場合の代替手段は --grid --entry <ボーカル開始秒数> で、1フレーズ1小節として推定します；--intro-bars はクライアントと合意したイントロの小節数を指定します（上記の例の2はクライアントへのデフォルト要求）、合意がない場合は指定しないでください。WindowsのPowerShellでは cp も使用できます；cmdの場合は copy に置き換えてください。

オーディオを変更する場合はこのステップを再実行するだけでよく、絵コンテを修正する必要はありません。

4. 絵コンテと問題専用のグラフィックを作成する

references/visuals.md を読み、作品ディレクトリ内の2つのファイルを編集します：

• storyboard.json：口诀バナー、数式、弾き文字（ポップアップ文字）、矢印、背景切り替えの計画
• graphics.py：この問題専用のグラフィックで、setup(ctx) と draw(canvas, t, ctx) を実装します

最も重要なルール：時間は常に歌詞を基準とした相対式で記述し、絶対秒数でハードコードしないこと。

記述方法	意味
L(6) / E(6)	6番目のフレーズの開始 / 終了
W(9,'四') / W(9,'四',2)	9番目のフレーズの「四」という文字（2番目の「四」）が歌われる時間
B、L(6)+2*B	1拍；6番目のフレーズ開始から2拍後

これにより、映像が実際の歌詞に同期し、クライアントがオーディオのバージョンを変更しても、ステップ3を再実行するだけで直接動画を出力できます。

グラフィックは最も手間のかかるステップです。エンジンには既に一般的な描画メソッド（点、線、弧、扇形の角度、直角記号、数字ブロック、括線、1行複数色の数式、ブロック全体の回転・平行移動、経路に沿った移動、等間隔配置）が用意されているので、まず references/visuals.md のセクション4で既存のものを探し、ゼロから作成しないでください。少し書いては画像を確認し（次のステップ）、全て書き終えてから確認しないでください。

実際の使用で最もよくある2つの問題は、作成時に避けるべきです：

• グラフィックが小さすぎる、細すぎる。これはモバイル画面向けです：メインのグラフィックは画面幅の半分以上（幅 ≥ 800 もしくは高さ ≥ 400）を占め、1行の要素は ctx.spread(n) で幅を埋め尽くし、線幅は ≥ 9、フォントサイズは ≥ 44 にします。サイズの参考は references/visuals.md のセクション1を参照
• 全てのフレーズに映像が必要。グラフィック、弾き文字、数式のうち少なくとも1つが画面中央に存在し、あるフレーズで背景と字幕だけにならないようにしてください

5. チェックとプレビュー

python $SKILL/scripts/overlay_engine.py <作品ディレクトリ> check          # 必須：絵コンテの問題0件、レンダリングエラー0件。「レイアウト注意」は一つずつ確認
python $SKILL/scripts/overlay_engine.py <作品ディレクトリ> sheet          # 絵コンテプレビュー.jpg：フレーズごとの1コマ概要
python $SKILL/scripts/overlay_engine.py <作品ディレクトリ> sheet --pages  # 追加で 絵コンテプレビュー_p1.jpg…：大きな図をページ分割。テキストが端にかかっていないか確認（概要図も同時に更新される）
python $SKILL/scripts/overlay_engine.py <作品ディレクトリ> frames "L(18)" "L(19)" 0.2   # 絵コンテフレーム.jpg：アニメーションの一部をフレームごとに並べる

自分で画像を開いて、コマごとに絵コンテと照合します：

• 概要図：各フレーズに必要な要素が表示されているか、空のコマがないか
• 大きな図のページ分割：テキストが互いに重なっていないか、口诀バナーや字幕に干渉していないか、グラフィックが十分に太く大きく描かれているか
• 移動、回転、フェードインがある場所は、frames で途中で他の要素と衝突していないか確認
• check の「レイアウト注意」で指摘された時間を一つずつ確認します（バナーに干渉、字幕に重なる、数式と重なる、エッジに接触、グラフィックが小さい、画面中央が空、テキスト同士が重なる、などを報告します）
• check では検出できないもの：テキストが線や色ブロックに隠れて見えない、グラフィックの数が間違っている、色が不十分で目立たない。これらは大きな図を見て初めて発見できます

問題があればステップ4に戻って修正し、再度確認します。問題がなければ、概要図をユーザーに確認してもらい、動画を出力します。

6. 動画出力

python $SKILL/scripts/build_video.py <作品ディレクトリ> bg            # 背景を選択して結合、各セグメントでどの素材を使ったか表示
python $SKILL/scripts/build_video.py <作品ディレクトリ> final 20 30   # オプション：最初に10秒の断片を出力して確認
python $SKILL/scripts/build_video.py <作品ディレクトリ> final         # 全編、約6～12分（PCの性能による）、バックグラウンドで実行
python $SKILL/scripts/build_video.py <作品ディレクトリ> sheet         # 完成_概要.jpg
python $SKILL/scripts/make_vertical.py <作品ディレクトリ> --title "タイトル"   # オプション：縦向き版（TikTok、快手、WeChat Video用）

bg は各セグメントに問題固有のグラフィックが含まれているか自動的に判断し、含まれている場合は「静かな」セグメント（明るい顔のクローズアップがないもの）のみを選択し、プリントアウトされたリストにその旨を記載します。プレビューを全て確認した後、build_video.py <作品ディレクトリ> all でチェック + bg + final + 概要図を1つのコマンドで実行することもできます。縦向き版は、横向きの完成動画を1080×1920の画面の中央に配置し、上部にタイトル、下部に小さな文字を追加し、背景はぼかして拡大した映像で埋めます。グラフィックを縦向きに再配置するわけではありません。縦向きタイトルを --title で指定しない場合、storyboard.json 内の vertical.title を読み、それもなければ歌詞ファイルのタイトルを使用します。

7. チェックと納品

完成_概要.jpg を確認します：背景は十分に暗いか、グラフィックと文字ははっきりしているか、背景の明るい顔が弾き文字や説明文の背後にちょうど重なっていないか（もしあれば、背景計画でそのフレーズに :quiet を追加するか、特定のセグメントを指定し、bg と final を再実行します）。その後、完成.mp4 をユーザーに渡し、以下の説明を添えます：

• 映像とタイミングはスクリプトによって検証されていますが、音声は人が確認する必要があります：特に、口诀のポップアップ、結果の数字の出現が、歌詞と（タイミング的に）一致しているかを重点的に確認してください
• ステップ3でマッチ率が低かったフレーズについては、特にその部分を確認するように伝えてください

参考ファイル

ファイル	読むタイミング
references/lyrics.md	口诀、歌詞、絵コンテを作成する前
references/audio.md	ユーザーが「音楽/ナレーションは何を使う？」と尋ねた時；オーディオの要求をクライアントに送る必要がある時；オーディオの検収と選択時
references/visuals.md	storyboard.json と graphics.py を作成する前（レイアウト、フィールド、描画ツール、よくある問題の描画方法）
references/library.md	素材ライブラリにセグメントを追加したり、新しい背景を生成したり、背景の選択が適切でない時
references/troubleshooting.md	どのステップでもエラーが発生したり、結果が期待通りでない時
references/teaching.md	ユーザーが原理を理解したい、他の人に作り方を教えたい、またはコードを書きたくない（剪映（Jianying）を使いたい）時
references/compatibility.md	ユーザーが「他のAI / 他のモデルでもできる？」と尋ねた時；このスキルを他の人に渡す時
examples/shuxianduan/	完全なサンプル：歌詞、絵コンテ、グラフィック。新しい問題を書き始める前にまず読む

スクリプト一覧

スクリプト	役割
check_env.py	環境自己診断
new_project.py	新しい作品ディレクトリを作成
check_lyrics.py	歌詞の検査
prepare_audio.py	オーディオ + 字幕 → timing.json、および使用可能か別バージョン推奨かの結論を出力
overlay_engine.py	チェック、プレビュー、オーバーレイのレンダリング
build_video.py	背景選択、動画合成、概要図出力
make_vertical.py	横向き完成動画 → 縦向き版
library_tool.py	背景素材ライブラリの管理（追加、削除、タグ変更、概要図）
gen_music.py	オプション：ElevenLabsを使用して楽曲を生成
install.py	このスキルを他のAIツール（Codex、Gemini CLI、opencodeなど）にインストールし、素材ライブラリを配置
chat_pack.py	チャット専用AI用に、プロンプトパッケージを生成（作詞用／画面作成用／チェック結果に基づく修正用）