dengyie/onevideo

onevideo は何をしますか？

OneVideo は「動画を作る」を 10 のステージに分解します。各ステージには監督用ドキュメント（stages/<id>.md）、成果物（plan/*.json）、および機械的なゲート制御があります。人間の承認が必要なステージは承認を必要とし、承認によって成果物のハッシュがロックされます。共有のレンダリングエンジンは template/ にあり、プロジェクトディレクトリにはデータのみを配置します。

動作方法

1. onevideo status で各ステージの状態と、次に読むべき監督用ドキュメントが表示されます。各ステージに入ったら、まず対応する stages/<id>.md を読んでから作業を開始してください。
2. 創作ステージ（research、proposal、script、storyboard）では、あなたが JSON / Markdown を作成し、onevideo validate を実行した後、成果物をユーザーに見せます。ユーザーが確認したら onevideo approve <stage> を実行します。ユーザーから明示的に許可されていない限り、ユーザーに代わって承認しないでください。
3. 非創作ステージは CLI で実行します：tts、music、assets fetch、depth、timeline、render、qc。また、build を使用すると QC まで一気に実行できます（不足している素材は自動ダウンロード、depth ツールがあれば深度マップと輝度グリッドも自動生成）。publish には review の承認が必要です。
4. 構成は視聴者の疑問に沿って整理します（proposal では質問チェーンを書き、script の各シーンには question を記述）。映像は 3 つのラインで役割分担します：ナレーションで説明、画面上のテキストはキーワードのみ、映像は証拠を表示（storyboard.md）。
5. ストーリーボードはモーションエンジンに従って記述し、1ページ1カード方式にはしません：まず references/motion-rules.md を読み、examples/spacex-motion を参考にしてください。実写は主役を中心に（footage の速度変更、タイトルは被写体の後ろに配置）、デジタル素材は canvas で連続フライ表示、各シーンに shots を設定し、フックと結論では各セリフに word キーワードを設定、音楽がある場合は music.offset: "auto" を記述します。onevideo timeline が報告するリズム警告（4.5秒以上新しい要素がない、同じトランジションの連続など）は処理するか、またはユーザーに保持理由を説明してください。
6. レンダリング後は必ず onevideo qc を実行し、1フレームずつ out/qc/frames/ を確認して問題がないことを確認してから approve review を行ってください。

あなたは監督

リズムはあなたがコントロールします：各ショットがなぜここにあるのか、どのくらいの長さで止めるのか、どのようにカットするのかは、すべてあなたが決定し、ストーリーボードに記述します。CLI とモデルは単なるツールであり、それらが出した結論はあなたが検証してから採用してください。

• 映像が足りなければ自分で作成：assets.json に generate と記述すると、画像生成（variants: 2–4 で複数枚生成し、ビジュアルモデルが brief に従って1枚を選択、すべての候補は public/assets/<id>.take<k>.* に残ります。選択が適切でないと判断した場合は pick で変更可能）、または動画生成（kind: "video"、from: <画像 id> で画像を最初のフレームとして動かす）が可能です。生成に失敗した場合は、同じエントリの url / query にフォールバックするため、重要な素材には予備のソースを用意しておくことをお勧めします。実際のソースが見つかる場合はそちらを優先し、生成素材は補完的なショット、雰囲気作り、コンセプト映像にのみ使用し、ニュースの実写を偽装してはいけません。
• 試写：onevideo sheet で完成動画を1秒ごとにコンタクトシートとして出力します（out/qc/sheet-NN.jpg、各シーンの開始フレームも同時に出力）。Read を使ってコンタクトシートを確認すると、フレーム単位で見るよりはるかに速く確認できます。onevideo look でビジュアルモデルに編集基準でチェックさせ、結果を out/qc/look.json に出力します。各コメントにはタイムコードとシーンが含まれます。これはあくまでセカンドオピニオンです：まずコンタクトシートや stills で問題が実際に存在することを確認してから、ストーリーボードを修正してください。
• まず15秒のサンプルを作成：全体をレンダリングする前に、まず render --draft --scenes hook,ipo（または --from 0 --to 15）で冒頭部分をレンダリングし、スタイル、ナレーション、フォントサイズ、リズムが適切かを確認してから、全体をレンダリングします。
• 反復：ストーリーボードを修正 → timeline（rhythm / echo 警告を処理）→ render --draft [--scenes …] --note "何を変更したか" → sheet --vs prev で前バージョンと比較 / look → さらに修正。各ラウンドでは1つのことだけを変更し、変更後に比較して改善されたことを確認してから次の変更に進みます。確認済みの内容は handoff --lock "…" で記録し、以降は触らないでください。
• 引き継ぎ：セッションを切り替える、サブエージェントに渡す前に onevideo handoff を実行します。これにより、ステージ、確定パラメータ、素材品質チェック、最近のレンダリングバージョン、試写コメント、未処理の警告が plan/handoff.md に書き込まれ、手書きの「ロック / 次回のみ変更 / 備考」の3セクションが保持されます。既存のプロジェクトを引き継ぐ場合は、まず plan/handoff.md を読んでください。
• 並列処理：リサーチ、素材検索、素材生成は互いに独立しているため、サブエージェントに並列で依頼できます。ストーリーボードとリズムはあなた自身が書き、外部に委託しないでください。

ハードルール

• ナレーション内のすべての数字は、plan/research.json の facts 内に見つけられる必要があり、facts にはソースが必要です（numbers ゲート制御）。ゲート制御を通すためにソースを捏造しないでください。
• 素材はホワイトリストで許可されたもののみを使用します（references/licensing.md）。CC BY 素材には作者とソースを明記してください。
• API キーは環境変数またはローカル設定からのみ読み取り、印刷したりプロジェクトファイルに書き込んだりしないでください。共有キー（MANGO_API_KEY など）は api.mangoqwq.com にのみ送信します。baseUrl を変更する場合は、専用の keyEnv を設定する必要があります。~/.zcode のプロバイダ設定は、明示的に ONEVIDEO_ZCODE_PROVIDER=1 が設定されている場合にのみ読み取られます。
• 承認済みの成果物が変更されると、そのステージは stale と表示され、再度ユーザーに表示して approve する必要があります。script を変更した後は必ず tts を再実行する必要があります。そうしないと timings ゲート制御でエラーが発生し、レンダリングがブロックされます。timeline.json を手動で変更しないでください。

コマンド

onevideo init <dir> --pipeline data-explainer|documentary|shorts|promo [--style midnight-data] [--aspect 16:9] [--example spacex-motion|spacex-ipo|promo-demo]
onevideo status | validate [--strict] | approve <stage> [--note …]
onevideo tts [--sample|--dry|--force|--only a,b]   # 文ごとに合成 → plan/timings.json（ラウドネス正規化を含む）
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # generateを含む：AI画像生成/動画生成
onevideo depth [asset ids] [--step N]               # 深度マップ + 輝度グリッド：被写体の移動、キーワード回避、自動影付け、字幕回避
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # 実際のインターフェーススクリーンショット（ヘッドレスChrome自動起動）
onevideo screen <asset> [--at s] [--threshold 40]   # 実写内の黒画面の四隅を検出 → footage.screen セグメント
onevideo stems                                     # ステムごとにグループ化してトラックWAVをエクスポート → out/publish/stems/
onevideo timeline | stills [--scene id] [--at 0.3,0.7] | studio
onevideo render [--draft] [--scenes a,b | --from s --to s] [--note …]   # 毎回1バージョン → out/versions/vN
onevideo versions                                   # レンダリング履歴：バージョン、範囲、タイムラインハッシュ、備考
onevideo handoff [--lock …] [--next …]              # 引き継ぎページ → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # 効果音 / Lottie / ショットレシピ
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # コンタクトシート → out/qc/sheet-NN.jpg；--vs 新旧比較
onevideo look [--focus "字幕の可読性"] [--models a,b]   # ビジュアルモデルによる試写 → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

グローバルインストールされていない場合は、node <repo>/cli/onevideo.mjs … を使用して呼び出します。

参考

• パイプライン定義：pipelines/*.json；ビジュアルスタイル：styles/*.json
• ライティング：references/writing-ja.md · 発音：references/tts-pronunciation.md
• シーンとモーション：references/motion-rules.md（最初に読む）· references/scene-catalog.md
• データとライセンス：references/data-integrity.md · references/licensing.md
• 品質チェック：references/qc-thresholds.md
• 例：examples/spacex-motion/（モーションエンジンデモ、36秒）· examples/spacex-ipo/（データグラフ版、85秒）· examples/promo-demo/（プロモーションパイプライン：captureスクリーンショット + deviceシーン、20秒）；onevideo init demo --example spacex-motion