papermorph

Papermorph

Papermorph は、1台のマシンで4種類の本を作成します。

• レッスン：教科書の PDF から作成します。各章は短いアニメーション教材動画で、絵が説明を担い、ナレーションが内容を伝え、絵の中で簡単な確認問題や練習問題に取り組めます。
• 絵本：物語、ジョーク、童話から作成します。紙人形を舞台セットの前で動かす短編動画で、セットはコードで描くことも、画像モデルで描くこともできます。音声、効果音、音楽も加えられます。
• ドキュメンタリー：本やアイデアから作成します。パブリックドメインの画像を集め、ナレーションに合わせて言葉や地図を動かす、音楽付きの映像です。
• ショート動画：ユーザーが概要をまとめた主張から作成します。スマートフォンのフィード向けの縦型動画で、3分以内に1つの要点を伝えます。

どれも SVG のステージ（1600×900、ショート動画の場合は900×1600）とプレーヤーで構成されます。ビートは、ナレーションのクリップとタイミングを指定した動作を組み合わせたものです。良い作品とは、生き生きとしている（動きに重みとタイミングがあり、ものが動いて変化する）、構成が整っている（どの瞬間も1枚の絵として伝わり、テキストはそれが指すものの隣にある）、正確である（動き、ラベル、数値がどの瞬間も一致している）、そして滑らかである（Firefox を含め、途切れず再生できる）ことです。

どのような絵にするかは、本とユーザーによって異なります。そのため、作業は会話から始まり、その内容を style.json にまとめます。そこには、ユーザーの言葉、選んだ見た目、音声、各工程を担当するモデル、そして後から承認された章が含まれます。すべての章はこのファイルに基づいて作成します。各ビートのレイアウトや振り付けは、style.json と承認済みの章に照らして判断してください。ユーザーの要望はデフォルト設定より優先されます。説明、例、図を新たに作成してください。ソース PDF、ページ画像、抽出したテキストは静的出力フォルダーの外に置き、バージョン管理の対象外にしてください（.gitignore：*.pdf、books/*/pages/）。ローカルでのプレビュー手順を含めた、自己完結型の本フォルダーを納品してください。

どの制作経路を選ぶか

ユーザーが持ち込むもの	制作経路	参照資料
教科書の PDF	レッスン	intake.md、続いて diagrams.md（ティア1）または scenes.md（ティア2）、authoring.md、assets.md、review.md
物語、ジョーク、童話、または物語の本の PDF	絵本	stories.md、puppets.md、sound.md。絵画風にする場合は painting.md
ナレーション付きの映像で解説する本、アイデア、または歴史の一時期	ドキュメンタリー	documentary.md、音楽については sound.md
スマートフォンのフィード（YouTube Shorts、TikTok、Reels）向けの、3分以内の縦型動画で伝える要点	ショート動画	shorts.md、音声、画像、レビューについては documentary.md
教材（引用文献、レビュー済みの問題、LMS を含む）	オプションを使ったレッスン	courses.md。本で必要とされる場合のみ

どの制作経路でも、site.md（本のフォルダー、表紙またはシリーズページ、プレビュー、動画の書き出し）、engine.md（プレーヤーと描画 API）、team.md（サブエージェントを使った章の制作）、および intake.md のモデル工程を共通で使用します。現在の工程に必要な資料だけを読んでください。

プロジェクト構成

books/<book>/
  book.pdf, sections.json      source and page map (private)
  pages/chNN/text.md, *.png    extracted reference material (private)
  style.json                  the agreed style every chapter anchors to (assets/templates/style.json)
  chapters.md                 chapter map and status
  chapters/chNN.md            storyboard, errata, feedback
  images/                     inbox, SOURCES.md (where each image came from), image-requests.md, processing scripts
  review/chNN/                storyboard sheets, strips, check output
content/<book>/chNN/           narration.<lang>.json and TTS cache
tools/<book>/                 tests and evidence scripts
site/<book>/                   the static book (only this is delivered)
  index.html, unit-art.js      cover + contents, unit sketches
  lib/engine.*, math.js,       the engine (player, maths helpers, cover/contents, unit headers), copied into
      volume.*, contents.*,      the book by scripts/engine.py
      units.*
  lib/book.css                 this book's engine settings and style overrides
  lib/*.js, img/               the book's element library and images
  chNN/index.html, audio/<lang>/   a lesson, its beat MP3s + timings.js

絵本では、books/<book>/story.md（ユーザーの語りをそのまま記録）、storyboard.md、art/（セットのスケッチを含むsets.js、生成した画像、painted.json、costs.tsv）を追加します。site/<book>/lib/にはペーパーキット（assets/templates/picture-book/からのpaper.js、cast.js、shared.js。エンジン内にsfx()とmusic()があるため、engine-v2.2以降が必要です）を置き、img/には焼き付けたセット、小道具、パペットのパーツを置きます。各エピソードのchNN/には、シーンごとに1つのスクリプトと、audio/<lang>/、audio/sfx/、audio/bgm/を置きます。

ドキュメンタリーでは、books/<book>/storyboard.md、art/（ダウンロードした画像を含むfound/、prep.pyのリスト、生成したクリップ、costs.tsv）、およびmusic/を追加します。music/では、commons.pyがダウンロードしたファイルと並べてSOURCES.tsvを保持します。site/<book>/lib/には、assets/templates/documentary/からのfilm.js、fonts.css、fonts/（映画の色に合わせたbook.cssも）を置き、映画で使用する場合はlines.js（trace.py）も置きます。img/には、加工した画像とart.js（prep.py）、およびクリップシートとframes.js（frames.py）を置きます。index.htmlはクレジットを記載したシリーズページです。各映画のchNN/にはaudio/<lang>/とaudio/bgm/を置きます。

短編シリーズでは、books/<book>/chNN-script.md（アウトライン、見えるものを記したビート、出典）、art/（生成画像および既存画像、costs.tsv）、およびmusic/を追加します。site/<book>/lib/には、assets/templates/shorts/からのshorts.js、book.css、icons.jsを、ドキュメンタリーキットのフォントとともに置き、シリーズ独自のパーツを記したファイルをもう1つ作成して、shorts.jsの後に読み込みます。各エピソードのchNN/にはaudio/<lang>/、audio/sfx/、audio/bgm/を置きます。

SKILLはこのスキルの絶対パスを表し、<book>は本のスラッグ、<lang>はその主要言語のコードです。必要なもの：uv、ffmpeg／ffprobe、Edge TTSのネットワークアクセス（またはローカルのKokoro：uv run --python 3.12 --with kokoro）、リポジトリにengine/フォルダーがない場合はengine.py用のgithub.com、ユーザーが選択した有料手順（paint.py、eleven.py、video.py）でのみ必要なOpenRouterキー（paint_openai.pyにはOpenAIキーが必要）、およびPlaywrightブラウザー（uv run --with playwright playwright install chromium firefox。PlaywrightのChromiumが動作しない場合は、インストール済みのChrome、Chromium、Brave、またはEdgeをCHROMEに設定します）。プレビュー：python3 SKILL/scripts/serve.py 8765 site（ブラウザーキャッシュなし）。

教訓

パイプライン

books/<book>/style.json がまだ存在しない場合は、必ずインテークから始めます。すでに得られている回答や承認は再利用します。

1. インテーク（intake.md）。短い会話を通じて、ユーザーとPDFを見つけます（物語の場合はstories.mdを参照）。分割し、その本がどのようなものか説明し、試す章を1つとティアを決め、ブックフォルダーを作成します。そのティアに必要な見た目を決め、各ステップをどのモデルが担当するか合意して、style.json を作成します。
   • 分割：uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf。章の深さで分割するには、--level N -o books/<book>/sections.json を使います。隣接する章の範囲外を指す章のブックマークは、タイトルがあるページに移動するか、警告を出して削除されます。その章のページを確認してください。有効な章のブックマークがないPDFの場合は、split_pages.py … --pages 1-12 --out books/<book>/pages を調べ、内容からマップを作成します（スキーマ：outline.py --help）。split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only で章のテキストを抽出します。
   • ユーザーにフレームを見せる前に、site.mdに従ってブックフォルダーを作成します。合意した共有コンポーネントは一度だけブックのライブラリに作成し（assets.md）、style.json に記載します。
2. パイロット。選んだ章を章のループに沿って作成し、ユーザーの評価を受けられるように提出します。フィードバックをstyle.jsonに反映し、その章をapprovedに記録します。
3. 残りの章と仕上げ。ユーザーが本全体を希望する場合は、chapters.mdを作成し、章を順番に制作します（「コンテキスト」を参照）。表紙のテキスト、目次、ユニットのスケッチをsite.mdに従って完成させます。静的なブックフォルダー、ローカルプレビュー用のエントリーURL、未解決の問題があればそれも提出します。

コースブックでは、検証済みの引用リンク、レビュー済みの問題バンク、またはLMS向けのSCORMパッケージも必要になる場合があります。必要な場合に限り提案してください（courses.md）。

章のループ

1. 読む：この章のpages/chNN/text.mdを読みます。図やテキストの欠落を画像で確認する必要がある場合は、split_pages.py … --only chNNでページをレンダリングします。教えるアイデア、例、セクションを選びます。
2. ビートとナレーション：chapters/chNN.mdに各ビートの内容と、どの単語がどのアクションを起動するかを列挙します（authoring.md）。content/<book>/chNN/narration.<lang>.jsonを作成し、次にuv run --with edge-tts SKILL/scripts/tts.py content/<book>/chNN/narration.<lang>.json site/<book>/chNN/audio/<lang>を実行します（"engine": "kokoro"の場合：uv run --python 3.12 --with kokoro …）。
3. ストーリーボード、まずレイアウト：実際のページに、各ビートの重要な瞬間を1〜3つ選び、それぞれに必要な要素をすべて実際のサイズで配置します。まだ動きはつけません。strip.pyでシートにまとめてキャプチャし、各フレームについて、内容と視線の向かう先を1行で記します。そのシートがストーリーボードです。ライブラリ以外に章で必要なものを記し、描画するか、画像リクエストに追加します。
4. 動き：動き、カメラ、質問を追加します。APIとリプレイの不変条件についてはengine.mdを参照してください。
5. 提出前の確認：ストーリーボードと照らし合わせながら、視聴者の視点で出力の動きを見て評価し、その後review.mdのチェックを実行します。見つかった問題を修正して再確認し、提出します。未解決の問題があれば報告します。
6. 登録：目次（index.htmlのContents.bookにあるunits）に章を追加し、前の章のCHAPTER.nextを設定して、chapters.mdとchapters/chNN.mdを更新します。新たに決まった共有事項や繰り返し使う要素をstyle.jsonとライブラリに反映します。サブエージェントを使う場合、この手順はコーディネーターが担当します。

絵本

books/<book>/style.json がまだ存在しない場合は、stories.md のストーリーの聞き取りから始めます。モデルについて合意し（intake.md）、style.json を作成します。その後、作業の順序に従います。まず、ユーザーに脚本とストーリーボードを見せてから、ブックフォルダー（site.md）、音声、セット、シーン、レビューラウンドへと進み、最後にユーザーに初版を見てもらいます。各エピソードは章（chNN）で、シリーズではキャスト、セット、シリーズページを共有します。

ドキュメンタリー

books/<book>/style.json がまだ存在しない場合は、documentary.md の聞き取りから始めます。その後、作業の順序に従います。リサーチ、ユーザーに見せる脚本とストーリーボード、assets/templates/documentary/ のフォルダー（site.md）、写真の収集と加工、ナレーション、音楽、ビート、レビューラウンドを経て、ユーザーに見てもらいます。書棚にある Madness and Civilization が承認済みの参考例です。Shooting an Elephant（site/shooting-an-elephant/）は、読者がライフルを撃つインタラクティブ版です（インタラクティブな場面）。

ショート動画

books/<book>/style.json がまだ存在しない場合は、shorts.md の質問から始めます。脚本を書く前に、ユーザーのアウトラインを作成します（長編映画をショート動画に再編集する場合は、その長編映画がアウトラインになります：長編映画から）。その後、作業の順序に従います。ユーザーとビートごとに脚本を書き、ストーリーボードと画像を作成し、縦型のステージに assets/templates/shorts/ のフォルダーを用意します。ナレーションと音楽の音量レベルを調整し、ビートを整え、監督の確認を経て、ユーザーに見てもらいます。その後、export.py で 1080 × 1920 の動画を書き出します。Madness and Civilization のエピソード 1、The Ship（site/madness-shorts/）が作業例です。

スクリプト

すべて SKILL/scripts/ にあります。各スクリプトは --help で使い方を表示します（docstring に記載された uv run --with … を付けて実行します）。

用途	スクリプト
すべての本	serve.py キャッシュなしのプレビュー · engine.py エンジンを本に同期 · tts.py ナレーションと単語ごとのタイミング · lint.py 静的チェック · shot.py ビートのスクリーンショット · strip.py ストーリーボードのシートとモーションストリップ · still.py 動きのない箇所の尺を伸ばす · perf.py Firefox のフレーム時間 · export.py MP4 と .srt · level.py 音量を均一化
レッスン	outline.py と split_pages.py ページマップと章のテキスト · check_blank.py 空の冒頭部分 · overlap.py テキスト上を通る矢印 · sprites.py 画像処理の手順
絵本	mouths.py 口の形 · join.py シーンごとに 1 つのクリップ · sfx.py 合成効果音 · playlog.py 画像に合わせた音声とキャプション · bake_sets.py セットレイヤー · bake_puppets.py パペットのビットマップ · paint.py / paint_openai.py 画像モデルによる画像生成 · painted.py 生成画像を本に配置
ドキュメンタリー	commons.py ライセンス付きのパブリックドメインの画像と録音 · prep.py 印刷および線画の加工 · trace.py 自分で描き込まれていくイラスト · video.py 静止画からクリップを作成 · frames.py 加工したフレームからクリップを作成 · eleven.py ElevenLabs によるナレーションと単語ごとのタイミング · music.py 映画に合わせて編集した音楽トラックと、ナレーションの合間に流す音楽 · safe.py 縦型映画のセーフエリア外にある単語
コースのオプション	refs.py 検証済みの引用 · items.py 問題バンク · scorm.py LMS パッケージ

silence.py、ledger.py、browsers.py は、ほかのスクリプトからインポートされるヘルパーです。

コンテキスト

• メインの会話でユーザーとやり取りし、パイロットの受付、すべてのシートと選択を進めます。サブエージェントが利用できる場合、章はチームで作成します。章のループの各ステップで新しいワーカーを起動し、そのステップ用にユーザーが選んだモデル（style.json の models）を使用して、章を順番に作成します。絵本はシーンごとに、ドキュメンタリーは映像のパートごとに分割します。ユーザーがシートを見るため、メインの会話がパイロットの進行を調整します。以降の章の調整には、新しいセッションを使うのが最適です（team.md）。サブエージェントが利用できない場合は、ファイルベースの状態管理を使って、現在のエージェントで同じループを実行します。
• ワーカーに必要なものは、この Skill と style.json 以外にはほとんどありません。具体的には、ユーザーの言葉、見た目、確認済みで参照すべき章、要素ライブラリです。ブリーフには、章、そのページ、ステップの入力と出力、および現在のユーザーリクエストを記載します。ワーカーは数行で返信し、コーディネーターが章を登録します。
• エンジン API を使用し、必要に応じて個々の関数を確認します。アセットは、ソース全体を指示として読み込むのではなく、コピーして使用します。
• style.json は最新の状態に保ち、簡潔にします。章のステータス、正誤表、過去のフィードバックは chapters.md と chapters/chNN.md に記載します。