papercut-explainer

Papercut Explainer

レイヤー状の工作用紙に命が吹き込まれたような、約20〜45秒の縦型解説動画です。ドロップシャドウのあるざらついた紙の小道具、硬い切り抜きアニメーション、ストップモーション特有の紙の揺らぎを伴うゆっくりとしたカメラのプッシュイン、各ビートに貼られた見出しバナー、単語ごとに表示される破れた紙のキャプションタグで構成されます。Remotion、任意のAI生成テクスチャ素材、任意のTTSを使用して制作します。

各ビートは3つのトラックで進行します。

• ナレーションでストーリーを伝えます
• テープで貼ったバナーで、ナレーションでは触れない確かな事実を補足します
• ナレーションの言葉を表現する新しい紙のセットを用意し、製品UIを大まかに切り紙で再現してデモを行います

完成した例の内容ではなく、スタイルとストーリーテリングを再利用してください。例に登場する製品、会社、数値はすべて架空のものです。スタイルルールは references/style-guide.md にあります（セクション2がStyle DNAです）。

事前確認

• ライブラリ。 $PAPERCUT_LIB を確認し、なければ ${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env の PAPERCUT_LIB= 行を確認し、それもなければ一度だけ尋ねます。マシンのパスをハードコードしないでください。ステージ1〜4ではライブラリは不要です。
• インストールモード。 ステージを約束する前に確認します（下記のインストールモードを参照）。
• シリーズ。 シリーズフォルダーを見つけます（episodes/ が含まれています）。SERIES.md があれば読みます。

実行モード（最初に尋ねる）

1. フルリール：アイデアからmp4まで。ステージ1〜8を実行し、投稿後にステージ9を実行します。
2. スクリプトのみ：戦略、フック、スクリプトを作成します（ステージング表の後で停止）。
3. 既存スクリプトからストーリーボードを作成：papercut-storyboard を実行します。スクリプト、事実、HOOKブロックを尋ねます。
4. 別のツール向けスタイルプロンプト：references/style-prompt.md の適切なブロックを提示して終了します。
5. 1つのシーンを修正または再構築：papercut-build（scenesステップ）、続いて papercut-qa を実行します。

事前ヒアリング（不足している情報だけを尋ねる）

• ソース：通常はリンク（リポジトリ、製品サイト、発表）です。それ以外の情報はすべて、そこから調査します。
• 動画で証明する唯一の主張と、トピック。
• 役割の位置付け：誰または何が作業を行い、誰が助言または承認するのか。ユーザーに確認し、製品の動作を決して創作しないでください。
• CTAキーワードと、視聴者が受け取るもの（成果物）。
• 長さ：デフォルトは22〜30秒です。
• 視聴者のレベル（SERIES.md を参照）と、アクセントカラーまたはマスコットの有無。

回答は episodes/NN-slug/research/facts.md の先頭にBRIEFブロックとして記述します（形式は papercut-strategy を参照）。

ステージ

#	ステージ	スキル	読み込むもの	書き込むもの
1	戦略	papercut-strategy	SERIES.md、ソース	research/facts.md のBRIEF、SERIES.md
2	フック	papercut-hook	BRIEF	papercut/STORYBOARD.md の先頭にあるHOOKブロック
3	スクリプト	papercut-script	BRIEF、HOOK	research/facts.md、narration/script.json、STORYBOARD.md のステージング表
4	ストーリーボード	papercut-storyboard	script.json、STORYBOARD.md	STORYBOARD.md のカメラ／カット表、シーンブロック、SFXプラン
5	足場の構築と計画	papercut-build	STORYBOARD.md	プロジェクト、episode.json
6	音声とタイミング	papercut-voice	script.json、voice/voice.json	narration/ のテイク、public/vo/captions.json、src/plan.json
7	シーン、サウンド、レンダリング	papercut-build	plan.json、STORYBOARD.md	src/scenes/*、tools/cues.json、out/*.mp4
8	QA	papercut-qa	静止画、STORYBOARD.md	修正、納品サマリー
9	投稿後	papercut-strategy（分析）、papercut-build（収穫）	プラットフォームの数値、プロジェクト	research/analytics/、ライブラリへの追加

プロジェクトファイル

パイプラインはチャットではなく、ファイルにあります。各ステージは上記のファイルを読み込み、独自のファイルを書き出すため、新しいセッションでもどのステージからでも再開できます。

<series>/
  SERIES.md                  optional: audience, voice, palette, mascot, keyword log
  voice/voice.json           optional: voice settings (copy library/voice/voice.example.json)
  papercut-assets/           optional: overlay textures and props
  research/analytics/        optional: competitor studies and autopsies
  episodes/NN-slug/
    research/facts.md        BRIEF + facts with sources
    narration/script.json    [{"id": "l1_hook", "text": "..."}, ...]
    papercut/
      episode.json           scenes, banners, hook, gaps, bed, cuts
      STORYBOARD.md          HOOK, staging table, Camera/Cut table, scene blocks

ライブラリカタログ：library/papercut/CATALOG.md（すべてのキットコンポーネント）とlibrary/audio/CATALOG.md（すべてのSFXとベッド音源）です。これらは生成されるため、新しくチェックアウトした環境には存在しないか、古い内容のままの場合があります。再生成するには、python3 $PAPERCUT_LIB/tools/catalog.pyを実行してください。エージェントはキットのソースではなく、カタログを読み込みます。

作成する前に再利用しましょう。新たに描画コードを書くより、キットコンポーネント、プロップセット、シーンテンプレートを優先してください。SFXとベッド音源は名前で選びます。

インストールモード

• 最小構成（スキルのみ）：戦略、フック、スクリプト、ストーリーボード、スタイルプロンプト。レンダリングは行いません。
• 標準構成：最小構成に加え、プレースホルダー音声（無音、またはmacOSのsay）を使ったビルドとレンダリングを行います。library/tools/placeholder_vo.py、静止画のQA、SFXとベッド音源、完成版mp4が含まれます。
• フル構成：標準構成に加え、ローカルのQwen3-TTSによるナレーションと、実際の音声に基づく単語単位のタイミング付き字幕を利用できます。

読み取り専用の確認：

. "$(grep '^PAPERCUT_LIB=' "${XDG_CONFIG_HOME:-$HOME/.config}/papercut-explainer/config.env" | cut -d= -f2-)/env.sh"   # fills PAPERCUT_PY, QWEN_TTS_PY
node -v; ffmpeg -version | head -1
"$PAPERCUT_PY" -c 'import numpy, PIL, soundfile'
"$QWEN_TTS_PY" -c 'import qwen_tts'

最初の3行がすべて成功すれば、標準構成です。さらにqwen_ttsのインポートも成功すれば、フル構成です。あるステージでインストール済みの内容を超えるものが必要な場合は、その旨を1行で伝え、リポジトリのルートから./install.sh --doctorを実行して、即興で補わずにpapercut-setupへ引き継いでください。ルートは、インストールされたスキルフォルダー（.claude/skills、.agents/skills、.config/opencode/skills、または別のハーネスのスキルフォルダー）の場所をreadlinkで確認するか、設定ファイル内のPAPERCUT_HOMEから探してください。

ステージ共通のルール

• スタイルのメモより戦略のメモを優先します。長さは22～30秒とし、ニュース仕立てのフックは使いません。
• 独立した作業（シーングループ、背景と小道具、再レンダリング）は、エージェントを使って一度に並行して進めます。
• レンダリングは依頼された場合にのみ行います。プレビューはRemotion Studioで確認してください。

共通の参照資料

• references/style-guide.md：スタイルのDNA、ペーパーカットの描画方法、パレット、フォント、質感、カメラと揺れ、動きのタイミング、字幕、サウンド。
• references/style-prompt.md：ほかのエージェントや生成ツールで使える、汎用的なプロンプト。
• references/motion-principles.md：アニメーションの12原則をキットコンポーネントとヘルパーに対応づけた資料。各ステージでの使用メモもあります。
• references/remotion-recipes.md：ライブラリがない場合に使うRemotionコンポーネントのスケッチ。
• references/asset-prompts.md：生成するものとコードで構築するものの区別、およびプロンプトのテンプレート。
• references/frame-breakdown.md：0.2秒単位で示した約28秒の作業例です。内容ではなく、イベントの密度を参考にしてください。

引き継ぎ

リール全体を作成する場合はステージ1から、実行モードで指定されている場合はそのステージから開始します。インテークの後にpapercut-strategyを実行します。これはSERIES.mdとBRIEFを読み込み、papercut-hookに引き継ぎます。各ステージのスキルには、次のステージが記載されています。