VideoBook：一つの動画を図入り電子書籍に変換
ユーザーが YouTube / Bilibili のリンクを渡すと、オンラインで読める技術電子書籍を生成します。
output/<video_id>/book.md + book.html（埋め込みプレイヤーカード、クリックで拡大するスクリーンショット、Mermaid 図）、
オプションで transcript.corrected.txt（字幕校訂対照稿）を生成し、GitHub Pages に公開することも可能です。
本スキルはオーケストレーション層であり、自己完結型です。エージェントに必要な指示はすべてこのディレクトリ（SKILL.md + references/）に格納されています。
リポジトリの instructions.md / README.md には依存しません（これらは人間の読者向けであり、本スキルでは更新しません）。
唯一の外部依存はパイプラインの実行可能コード src/*.py です。コマンドや引数はすべてスクリプトの --help 出力に従い、スクリプトのロジックを再実装しないでください。
可変データ（例：src/make_corrected.py 内の誤単語マップ）はスキル内にコピーせず、ルールだけを記述してソースファイルを参照します。
唯一の例外はステップ 2 の整形指示で、このディレクトリに同一ソースのコピー references/stitcher-prompt.md を置きます（リポジトリ版が優先）。
前提条件（初回実行時必読）
- 作業ディレクトリ = videobook リポジトリルート（確認方法：
src/dump_transcript.pyとprompts/が存在すること）。 すべての相対パス（output/<video_id>/...）はここからの相対パスで解決されます。リポジトリがローカルにない場合は、まずgit clone https://github.com/Luke-Evan/videobook.gitをユーザーのコード用ディレクトリ（テンポラリや新規 projects ディレクトリではなく）にクローンし、cdで移動してください。 - Python >= 3.10（推奨 3.12）。依存関係のインストール：
uv sync（uv 使用時）またはpip install -r requirements.txt。 実行はすべてリポジトリ環境のインタプリタを使用：uv run python src/xxx.pyまたは.venv/Scripts/python.exe src/xxx.py。 - 一度だけログイン：
python src/capture_frames.py --setup-profileで専用 Chrome（データディレクトリ.capture-profile/）を起動し、 B 站 / YouTube に QR コードログイン後、ウィンドウを閉じます。ログイン状態は長期間再利用可能。ログインアカウントの会員ランクがスクリーンショット画質の上限を決めます。 - 海外動画の場合：ターミナルにプロキシ（字幕取得用）、ブラウザにもグローバルプロキシが必要（そうしないと生成ページ内の YouTube iframe が真っ黒になります）。
- サンドボックス外 / 権限昇格が必要なコマンドは概要表の最終列を参照。純ローカルステップはサンドボックス内で実行可能。
パイプライン概要
| ステップ | 処理内容 | コマンド | 詳細 | 権限昇格 |
|---|---|---|---|---|
| 1 | 字幕抽出 | python src/dump_transcript.py "<URL>" | references/transcript.md | B 站で必要 |
| 1b | プラットフォームに字幕がない場合、ローカル ASR で補完 | python src/asr_transcript.py <video_id> | references/transcript.md | 不要（処理時間長） |
| 1.5 | 講義公式資料 + 4K スライド（デフォルト実行、講義にホームページがない場合のみスキップ） | python src/course_assets.py <video_id> --course-url <講義ホームページ> | references/course-assets.md | レンダリングで必要 |
| 2 | 大規模言語モデルで字幕を book.md にリライト | 整形指示に従う（references/stitcher-prompt.md、リポジトリ prompts/stitcher_system.md が存在する場合はそれを優先） | references/writing.md | 不要 |
| 2b | 字幕校訂対照稿（オプション） | python src/make_corrected.py <video_id> | references/correction.md | 不要 |
| 3 | フレームキャプチャとプレースホルダーの実画像への置換 | python src/capture_frames.py <video_id> "<URL>" | references/capture.md | 必要 |
| 4 | HTML レンダリング + ローカルプレビュー起動 | python src/post_process.py "<URL>" output/<id>/book.md その後 python -m http.server 8080 --directory output/<id> | — | 不要 |
| 5 | 結果をユーザーに通知、大ファイル削除の確認 | — | 下記「成果物の受け渡し」を参照 | — |
| 6 | 成果物を pages ブランチに公開（オプション） | python src/publish.py <video_id> その後 git push origin pages | references/publish.md | 不要（push はネットワークが必要） |
エラー、画質不良、字幕取得失敗、ASR 中断などの問題は、まず references/troubleshooting.md を確認してください。
絶対ルール（交渉不可）
- 字幕カバレッジ 50% 未満（終了コード 3）の場合はステップ 2 に進まない：ログイン状態 / プロキシを修正するか、ASR 補完に切り替えてください。
- スクリーンショットは必ずログイン済みブラウザ上のプラットフォームプレイヤーから取得し、ステップ 3 ではいかなる方法でも動画/音声ファイルをダウンロードしてはいけません（ffmpeg フレーム抽出は最後の手段）。禁止手段の一覧は
references/capture.mdを参照。 - cookies はシステムテンポラリディレクトリにのみ書き込み、使用後すぐに削除。リポジトリに残したり、ワークスペースに手動で
cookies.txtを置いたりしないでください。 output/は git 操作の影響を受けません。成果物は orphan ブランチpagesにのみ公開し、mainはコードのみを保持します。- 校訂稿の忠実性：段落ごとに講師の原語と順序を維持し、ASR 誤単語の置換と口癖の除去のみを行います。段落削除、複数行の変更、大幅なリライトは禁止（検証レイヤーが直接拒否します）。
- 書籍化の忠実性の下限：文語体化は要約化を意味しません。比喩、ケーススタディ、導出の連鎖は保持してください。編集者による補足は「編集者注」として明記する必要があります。
- 講義資料の著作権：講義資料とスライドは講師に帰属します（一般的に CC BY-NC）。書籍の先頭情報ブロックと末尾に、出典リンク、著者名、ライセンス名を必ず残してください。
- スライドカバレッジの絶対ルール：
slides_text.mdの各ページは書籍内に正確に 1 回出現する必要があり、納品前の--auditは PASS しなければなりません。 - 大ファイル（
audio.m4a、video_source.mp4など）の削除前に必ずユーザーに確認をとり、承諾を得てから削除してください。 - HTML 生成または修正時、テキストと背景のコントラスト比は WCAG AA の 4.5:1 以上を維持してください。
- 各ステップは冪等で再実行可能：プレースホルダー実画像化の前にスクリプトが自動で
book.tagged.mdをバックアップするため、それがあればステップ 3 を再実行するだけでスクリーンショットを復元できます。
成果物の受け渡し（ステップ 5 で一度に説明）
output/<video_id>/book.mdの場所；- プレビュー URL
http://localhost:8080/book.html、サーバー停止はターミナルでCtrl+C； - YouTube 動画の場合ブラウザが YouTube にアクセスできる必要あり（プロキシ）、B 站動画は直接視聴可能；
- スクリーンショットの画質は
.capture-profile/にログインしたアカウントのランクに依存。より高画質にするにはアカウントを変更してログインし、ステップ 3 を再実行； - 講義公式資料を使用した場合、説明書にスライドの挿絵は公式 4K レンダリング画像である旨を記載（書籍先頭にソースと CC ライセンスを記載済み）、デモフレームは動画フレームのまま、
course/ディレクトリは丸ごと削除しても閲覧に影響なし； - パイプライン中に生成された大メディアファイルの削除についてユーザーに確認（絶対ルール 9）。
ディレクトリ内容（必要に応じて読み取り、一度に全部読まないでください）
| ファイル | いつ読むか |
|---|---|
references/transcript.md | ステップ 1 の字幕取得時；プラットフォームに字幕がなくローカル ASR に切り替える場合 |
references/writing.md | ステップ 2 で字幕を book.md にリライトする時 |
references/stitcher-prompt.md | ステップ 2 の整形指示原文（リポジトリ prompts/stitcher_system.md が存在する場合はリポジトリ版を優先） |
references/course-assets.md | 講義に公式ホームページがある場合のステップ 1.5、カバレッジ絶対ルール、スライドアップグレード |
references/correction.md | 字幕校訂対照稿の生成と AI 行レベルの訂正提案 |
references/capture.md | ステップ 3 のフレームキャプチャ：優先順位、明示的に禁止された方法、QA の習慣 |
references/publish.md | ステップ 6 の pages ブランチへの公開 |
references/troubleshooting.md | エラー、画質異常、字幕取得失敗、権限昇格拒否が発生した場合 |
メンテナンスの取り決め
- 本スキルはパイプラインコードと同じリポジトリでバージョン管理：
src/*.pyのパラメータ、ステップ順序、絶対ルールを変更した場合は、このディレクトリも同期して変更する必要があります。 - リポジトリの
instructions.mdとREADME.mdは人間の読者向けであり、本スキルでは更新しません。スキルを有効にするためにこれらを変更しないでください。内容がこのディレクトリと重複する場合、エージェントはこのディレクトリを優先します。 references/stitcher-prompt.mdの同期時には、ファイル先頭のソース注記にコミットハッシュを更新してください。- 他者のインストール：
skill-installerで--repo Luke-Evan/videobook --path skills/videobookを使用するか、クローン後にこのディレクトリを~/.codex/skills/（Codex のみ）または~/.agents/skills/（クロスエージェント）にコピー/シンボリックリンクしてください。 - このディレクトリには cookies、ログイン状態、
output/の生成物、メディアファイルは一切含まれず、安全に公開配布できます。