ワンクリック動画レンダラー
機能説明
ワンクリックで Chanjing API を呼び出し、ナレーションTTS、デジタルヒューマン合成、テキストからの動画生成、ローカルでのカプセル化を実行します。ffmpeg / ffprobe を統合し、結合、トランスコード、トラックの位置合わせを行います。編成とセキュリティの詳細は §3–§8 と templates/ を参照してください。完成動画コマンドは §5 にあります。
実行依存関係
使用可能なバイナリまたは同等のカプセル化が必要です(具体的な呼び出し方法は §5、run_render.py を参照)。
- ffmpeg:結合、トランスコード、カプセル化
- ffprobe:長さ、解像度、回転などのメタデータ(デジタルヒューマントラックとの位置合わせに使用)
- chan-skill(または同一リポジトリ内で直接
pythonによりサブスキルスクリプトを呼び出し):chanjing-tts、chanjing-video-compose、chanjing-ai-creationなどのCLIを駆動
環境変数と機械可読宣言
- オプションの環境変数オーバーライド(すべてデフォルト値またはパス推論があり、実行前に必須ではありません):
scripts/run_render.py上部とサブスキルソースコードを参照。認証情報パスはmanifest.yamlcredentialsを参照。 - 準拠する
permissions、clientPermissions、agentPolicy、認証情報モデル:manifest.yaml
§3.2 と run_render.py は整合しています。manifest.yaml と競合する場合は、manifest.yaml が優先されます。
使用コマンド
- ClawHub(スラッグはレジストリに依存し、通常はスキルパッケージ名と同じ):
clawhub run chanjing-one-click-video-creation - このリポジトリに直接接続:
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1(スキルディレクトリ、またはSKILLS_DIR/CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT/CHAN_SKILLS_DIRと組み合わせて使用)
クイックリファレンス
| 内容 | 場所 |
|---|---|
ワークフロー、duration_sec、null/マージ、テーマ検証 | §4.1 |
セグメント分割、奇遇ミラー、scenes[]、scene_count/video_type;最初のシーンの voiceover は≤20文字(ハード) | storyboard_prompt.md 冒頭「テキストセグメント分割」;script_prompt.md 最初のシーンのナレーション;video_brief_plan.md |
レンダリング技術、ステータス、partial/success、ハード制約 | render_rules.md §1–§4;§7、§8 |
ref_prompt / テキストからのプロンプト | storyboard_prompt.md + history_storyboard_prompt.md;§4.2 ポインター |
| リクエストボディフィールドとデフォルト | §6 |
run_render.py、子プロセス CLI | §5 |
| セキュリティ、認証情報、信頼境界、ポリシー | manifest.yaml + §3.1(§3.1 は manifest テーブルを繰り返さない) |
| 環境変数、バイナリ、副作用、ディスク書き込み | §3.2 |
競合:レンダリング実装は render_rules.md が優先されます。ref_prompt の条文は storyboard_prompt.md / history_storyboard_prompt.md が優先されます(§4.2 は集約ポインター)。run_render.py は §5 と render_rules.md のみを実装し、ビジネスルールを追加しません。実行方法:手動でサブスキルを編成、run_render のみを使用、またはそれらを混在させることができます。
1. 何をするか
- テーマまたは全文 →
video_plan、ナレーション全文、絵コンテ - TTS:全体セグメント優先。長すぎる場合は絵コンテごとに少数のバッチにまとめて結合(詳細と文字数制限は
render_rules.md§3·C.4 を参照) - シーンごとにオーディオを分割
- デジタルヒューマンシーン:
chanjing-video-compose(オーディオ駆動) - AI シーン:
ref_prompt→chanjing-ai-creation→ シーン内のオーディオと合成 - カプセル化:共通のデジタルヒューマントラックを位置合わせ → ffmpeg concat → ローカル mp4
2. いつ使うか / いつ使わないか
| 適しているケース | 完成動画が必要な場合。ナレーションと映像のミックス編集。ユーザーが明示的にショート動画生成を希望する場合。 |
| 適さないケース | 台本やタイトルのみが必要な場合。動画を要求していない場合。既存の素材のみを編集する場合。 |
3. 前提条件
- 認証:
chanjing-credentials-guard。認証情報のパスとフィールドはmanifest.yaml、§3.1 を参照。認証情報がない場合、子プロセスはopen_login_page.pyを呼び出せる。 - 計画/台本/絵コンテ:ローカルエージェントロジック。外部の LLM API キーは不要(このスキルの必須パスは外部 LLM に依存しない)。
- ローカルバイナリとリポジトリレイアウト:§3.2(
ffmpeg/ffprobe、SKILLS_DIRなど) - デジタルヒューマンと音色:環境変数やリポジトリ内のキャッシュファイルを使用して、タスク間で「デフォルト」の
audio_man/person_id/figure_typeを保存しないこと。毎回タスクのworkflow.jsonのルートレベルに明示的に記述すること。エージェントはvideo_plan(video_typeなど)、ナレーションのペルソナ、テーマのセマンティクスに従い、list_voices.pyとlist_figures.py(--sourceでcommon/customisedなど今回のタスクと一致するソースを指定)を呼び出して選択後に書き込むこと。audio_manは選択したキャラクターのaudio_man_idと一致することが望ましい。 - パブリックデジタルヒューマンの選択(「リストの最初の数項目のみを取得する」は禁止):
list_figures.py --source common --jsonを使用して候補を取得し(必要に応じて--page-sizeを増やすかページをめくり、十分なエントリをカバーすること)、候補内で項目ごとに比較してから最終決定すること:name、figures[].type(→figure_type)、figures[].width/height(アスペクト比が D.1c と一致しているか)、audio_man_id、audio_name(ある場合)がvideo_plan/ナレーションペルソナ(性別、雰囲気、業界、年齢感)と一致しているか。デフォルトでは若くて活気のあるキャラクターを優先:名前またはaudio_nameに「青年」「少女」「お兄さん」「お姉さん」「学生」「元気」「青春」「若い」などのポジティブな信号が含まれている場合に優先。テーマまたはユーザーが明示的に成熟、権威、中高年などの雰囲気を要求する場合にのみ、対応するペルソナを選択すること。カスタマイズソースcustomisedも同様にname、width/height、audio_man_idなどを比較し、比較せずにページの先頭を直接取得しないこと。
3.1 セキュリティ、認証情報、信頼境界
環境変数とバイナリは manifest.yaml と §3.2 に基づきます。レビュー時には description と manifest.yaml(agentPolicy を含む)を照合してください。
- 機能とパイプライン:ステップレベルの説明は §1 を参照。
run_renderの責務と子プロセスは §5 を参照(ここではチェーンを繰り返さない)。 - 主要認証情報 / パス / primaryEnv:
manifest.yamlを参照。パスと書き戻し動作については、§3.2 の永続性テーブル「認証情報ステータス」およびCHANJING_OPENAPI_CREDENTIALS_DIR(CHANJING_CONFIG_DIRと互換性あり)を参照。 - 機密性とコンプライアンス:完全なキーを表示しないこと。
credentials.jsonをバージョン管理にコミットしないこと。権限は0700/0600を推奨(設定スクリプトで可能な限り設定すること)。 - 信頼とアウトバウンド動作:HTTPS、返されたURLからのメディア取得、
--output-dirへのディスク書き込みなどの詳細は §3.2「代表的な副作用」と永続性テーブルを参照。蝉鏡ホストとリンクを信頼するかどうかは各自で判断する必要がある。 - ブラウザ:認証情報がない場合の
webbrowser.open/open_login_page.pyについては、§3.2 の同じテーブルを参照。 - エージェントポリシー:
manifest.yamlのagentPolicy(always ではなく、他のスキルを変更しない)。
3.2 ランタイム契約(環境変数、バイナリ、副作用、ディスク書き込み)
scripts/run_render.py および同一リポジトリ内のサブスキルの動作と整合します。ページ上部のYAML、manifest.yaml と一致します。他の製品ドキュメントと並列して記載する場合、このリポジトリのソースコード、manifest.yaml、およびこの文書が優先されます。
環境変数(オプションのオーバーライド)
命名はリポジトリルートの 合规规则.md §3 に従います。リストはオプション変数を1つ1つ列挙していません。設定しなくても実行可能です。認証情報ディレクトリは manifest.yaml credentials(directoryEnv、defaultPath)を参照。run_render.py 内の openapi_base_url、one_click_skills_repository_root、one_click_ref_prompt_max_chars、one_click_ai_creation_model_code および子プロセス環境は、このスキルのオプションのオーバーライドと旧名との互換性の実装場所です。
注:一部の外部ドキュメントにある
FIRST_DIGITAL_HUMAN_MAX_CHARSなどの変数は、現在のrun_render.pyでは読み取られません。
外部バイナリ
| バイナリ | 必須性 | 用途 |
|---|---|---|
ffmpeg | ワンクリック動画生成 run_render.py 実行時に必須 | 動画・音声の結合、トランスコード、カプセル化など。純粋にAPIを編成し、このレンダリングスクリプトを実行しない場合はインストール不要。 |
ffprobe | 同上 | メディアの解像度、長さ、回転メタデータなどを読み取り、デジタルヒューマントラックとの位置合わせに使用。 |
スクリプト実行時の代表的な副作用(カテゴリ別)
| カテゴリ | 説明 |
|---|---|
| アウトバウンド HTTPS | 蝉鏡 Open API(CHANJING_OPENAPI_BASE_URL / CHANJING_API_BASE と互換性あり)、およびインターフェース/CDN から返される video_url / オーディオ URL などの素材取得。 |
| ローカルファイル | run_render.py --output-dir 配下に作成される一般的なもの:final_one_click.mp4、workflow_result.json、work/(中間オーディオ、分割動画、concat リストなど)。具体的な内容は、その時のコマンドと templates/render_rules.md に依存。 |
| 子プロセス | ffmpeg / ffprobe。run_render は subprocess を介して、同一リポジトリ内の skills/chanjing-tts、chanjing-video-compose、chanjing-ai-creation などのディレクトリにある Python CLI を呼び出す。 |
| ブラウザ | 認証情報がない場合やログインを促す場合、認証チェーンは webbrowser.open を行うか、chanjing-credentials-guard の open_login_page.py を実行する可能性がある(各スキルの _auth.py の動作と一致)。 |
永続的変更の範囲とユーザーによる制御可能性
以下は、このスキルにとって予期された副作用です。書き込み場所はパスと環境変数によって制御でき、無関係なディレクトリを暗黙的に汚染することはありません。
| カテゴリ | 書き込まれるもの | 代表的な場所 | ユーザーの制御方法 |
|---|---|---|---|
| 認証情報ステータス | 設定によって書き込まれた app_id / secret_key、更新後の access_token、 expire_in など | CHANJING_OPENAPI_CREDENTIALS_DIR/credentials.json(デフォルトは ~/.chanjing/credentials.json;CHANJING_CONFIG_DIR と互換性あり) | 推奨名または旧名を設定する。または、そのファイルを移動/削除する。秘密鍵をバージョン管理にコミットしないこと。 |
| ワンクリック動画生成アーティファクト | final_one_click.mp4、workflow_result.json、work/ など | run_render.py --output-dir で指定(通常は特定のタスクの outputs/<タスク名>/ 配下) | 明確な --output-dir を選択する。タスク終了後、必要に応じてディレクトリを保持または削除する。 |
| その他のダウンロード系スクリプト(サブスキル) | 合成結果などをローカルに保存 | 各スキルの download_result.py など。デフォルトでは多くの場合、現在の作業ディレクトリの outputs/<プロダクトライン>/ か、--output の絶対パスに保存。 | 期待される cwd で実行するか、常に --output を渡す。詳細は対応するスキルの SKILL.md を参照。 |
| 一時的/中間ファイル | TTS マージ、セグメント分割、アップロード前のキャッシュなど | 多くは上記 output-dir 配下の work/ か、スクリプトで規定されたサブディレクトリに保存。 | 出力ディレクトリと一緒に管理する。 |
認証情報ファイル:パスと読み書きのセマンティクスは上記の表の「認証情報ステータス」行を参照。初回設定については skills/chanjing-credentials-guard/SKILL.md を参照。
4. ルール集
4.1 ワークフロー編成
マージ:null = 上書きしない。順序:デフォルトで下地 → null 以外で上書き → ブール値/整数の修正。フィールドのデフォルトは §6 を参照。テーブルに展開されていないデフォルトは、run_render.py(および子プロセス)が実装と環境変数に従って読み取ります(音色/デジタルヒューマンは含まない:audio_man、person_id/avatar_id、figure_type は workflow.json からのみ取得。§3 参照)。
duration_sec:企画の参考値であり、ffmpeg の上限ではありません。完成動画の長さは TTS + ffprobe を基準とします。scene_count は video_brief_plan.md を参照。セグメント分割と AI 動画の数は、実際の測定値と字幕軸に依存します(render_rules.md §3·C.5)。ユーザーが要求した場合を除き、長さを合わせるために確定済みのナレーションをカットすることは禁止されています。
テーマ:空白除去後 <5文字、プレースホルダー文字列(「こんにちは」「test」など)は拒否。拡張書き込みは可能。厳格モードで曖昧な場合は失敗。
手順:1) 計画 → video_brief_plan(失敗ならすべて失敗。テンプレートは video_brief_plan.md を参照)2) 台本(フック / 最初の段落と最初のシーンを合わせる:≤20文字のハード上限。script_prompt.md を参照)3) 絵コンテ:意味による分割。storyboard_prompt.md(最初の絵コンテの voiceover も上記と同じハード上限)。非現代ものは history_storyboard_prompt.md。DH は chanjing-video-compose、AI は chanjing-ai-creation。TTS/複数AIセグメント/mux は render_rules.md §3、§5 を参照。4) レンダリング:render_rules.md §3(§3·C.6 を含む)、§4(表 4–6)。ref_prompt の品質チェックは storyboard_prompt.md / history_storyboard_prompt.md を参照(§4.2)。リトライ/partial は render_rules.md §1 を参照。5) 成功:render_rules.md §1
レンダリングのみ:run_render.py + full_script + scenes[]。順序:計画 → 台本 → 絵コンテ → レンダリング(各フェーズで使用するテンプレートは上記の手順を参照)。
4.2 テキストからの動画生成プロンプト(ref_prompt)— ポインター
唯一の条文の真値(修正はテンプレートが優先され、本文では D.1–D.4 の表文を繰り返さない):
| 範囲 | テンプレート |
|---|---|
現代向け、D.0 コンテキストのデフォルトと文明圏の推定、D.1 長さ、D.1a、D.1b(幻覚を起こしやすい、スキル全体で共有)、D.2 現代、手動 visual_prompt、D.3、D.4 現代のアセンブリと7要素 / テーマクラスター / 単一ショットの組み立て / 自己チェック | templates/storyboard_prompt.md → 「テキストからの動画生成プロンプト(現代向け真値)」 |
| D.2 非現代ルーティング、歴史プロセス層、文明圏と国の自己無撞着、プレースホルダー規律、D.3/D.4 との接続説明 | templates/history_storyboard_prompt.md |
| 民族、歴史的/非現代的な中国風スタイルと登場人物がいる場合の英語フレーズ | templates/visual_prompt_people_constraint.md(明示的な民族アンカー、歴史的 / 非現代セクション。render_rules.md §4 の表4–6も兼ねる) |
ここでのみ索引付けされます:長いオーディオの複数セグメントは render_rules.md §3·C.6。文字数上限は CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS(AI_VIDEO_PROMPT_MAX_CHARS と互換性あり)。テンプレートと render_rules.md の実装が競合する場合は render_rules.md が優先されます。
5. 自動化編成(run_render.py)
依存関係:認証。SKILLS_DIR / CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT / CHAN_SKILLS_DIR(§3)。chanjing-tts / chanjing-video-compose / chanjing-ai-creation
責務:① TTS + audio_task_state。バッチマージとバッチあたりの文字数上限は render_rules.md §3·C.4(TTS_BATCH_MAX)を参照。② セグメント分割(render_rules.md §3·C.5)③ AI シーンがある場合、最初に最初のデジタルヒューマンを完了し ffprobe(rotate を含む)→ その後、マッピングに従ってテキストからの aspect_ratio/clarity を送信(render_rules.md §3·C.6、debug.ai_video_submit_params を参照)④ 他の DH/AI と並行してポーリング⑤ AI トラックをその参照 ffprobe に位置合わせ⑥ ffmpeg concat⑦ 複数セグメントのテキスト生成は ref_prompt の後に英語の階層を追加。総長は CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS(AI_VIDEO_PROMPT_MAX_CHARS と互換性あり)によって制約される
行わないこと:plan/script/storyboard を生成しない。非現代/現代を自動判定しない。list_tasks.py を現代で使用しない(render_rules.md §4 表項目8)。
手動編成:それでも render_rules.md §3、§4 と §5 を満たす必要があります。§3 の詳細(silencedetect、minterpolate、参照トラックのビットレート、同じセグメント分割オーディオでのキャラクター変更、TTS バッチ間の無音など)はすべて保持されます。
入力 MVP
| フィールド | 必須 | 説明 |
|---|---|---|
full_script | はい | 各シーンの voiceover を scene_id で結合し、norm を一致させる |
scenes | はい | scene_id、voiceover、use_avatar。AI シーンには ref_prompt(storyboard_prompt.md / history_storyboard_prompt.md;§4.2)。オプションで subtitle |
audio_man | はい | 選択したデジタルヒューマンキャラクターの audio_man_id と一致させることが望ましい |
person_id/avatar_id | 条件付き | DH シーンがある場合は必須 |
figure_type | いいえ | その時の list_figures.py で選択したキャラクター行の figure_type と一致させる(パブリックで複数バリエーションがある場合は必須) |
subtitle_required | いいえ | デフォルト false。true の場合、デジタルヒューマンシーンに字幕を書き込む(--subtitle show) |
speed/pitch | いいえ | デフォルト 1/1 |
ai_video_duration_sec | いいえ | 5 または 10、デフォルト 10 |
model_code | いいえ | デフォルトは CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE(AI_VIDEO_MODEL と互換性あり)または Doubao-Seedance-1.0-pro。creation_type=4。ref_img_url は送信しない |
max_retry_per_step | いいえ | デフォルト 1(§6) |
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1
出力:final_one_click.mp4;workflow_result.json;work/
6. 入力(リクエストボディ)
norm:\r、先頭/末尾の空白を除去。空→空文字列。run_render.py と一致。ナレーション:最初に full_script、次に script→copy_text→input_script→content で最初の非空のものを使用。topic がない場合:最初の文をテーマとして代用(40文字以内で文末句読点で区切り、それ以外は24文字)。null/マージは §4.1。
| フィールド | 必須 | 説明 |
|---|---|---|
topic | 条件付き | ない場合は最初の文ルールを参照。推奨5文字以上 |
industry/platform/style | いいえ | industry は空。platform/style:DEFAULT_* または douyin/意見型ナレーション |
duration_sec | いいえ | DEFAULT_DURATION または 60。企画の参考値 |
use_avatar | いいえ | デフォルト true |
avatar_id/voice_id | いいえ | 空。環境変数で音色やデジタルヒューマンのデフォルトを補ってはならない。workflow.json に audio_man/person_id(および DH シーンがある場合は figure_type)を明記しなければならない。エージェントはそのタスクに応じて list_voices.py と list_figures.py(ソースは video_plan / ユーザー指定と一致)を呼び出し、name、形状、アスペクト比、audio_name などを比較した後に選択すること。比較せずにリストの最初の数項目を取得することは禁止。デフォルトでは若いデジタルヒューマンを優先(§3 参照) |
subtitle_required | いいえ | デフォルト false(デジタルヒューマン完成動画には字幕を書き込まない。run_render は hide を渡す) |
cover_required | いいえ | デフォルト true |
strict_validation/allow_auto_expand_topic/max_retry_per_step | いいえ | true/false/1 |
full_script | いいえ | デフォルト空 |
script_title/script_hook/script_cta | いいえ | デフォルト空 |
script/… | いいえ | 上記ナレーションの順序を参照 |
7. 出力 JSON
| キー | 意味 |
|---|---|
status | success / partial / failed |
video_plan | 計画 |
script_result | title、hook、full_script、cta |
storyboard_result.scenes[] | scene_id、duration_sec、voiceover、subtitle、visual_prompt、use_avatar |
render_result | video_file、scene_video_urls、render_path、degrade_log |
| その他 | error、debug… |
レンダリング時のデグレードはありません:いずれかのステップが失敗した場合、即座に中断し、自動的に DH のみまたは AI のみの完成動画に変更することはありません。partial:success に至らなかった場合(run_render が異常終了しても workflow_result.json は書き込まれます)。上記のデグレードを許可することを意味するわけではありません。storyboard_prompt.md·D.1b のような品質チェックを免除するものではありません。成功時 degrade_log=[]。失敗時は可能な限り、作成済みの文案と絵コンテを保持します。
8. ハード制約
表は templates/render_rules.md §4 にあります。ref_prompt との相互参照は storyboard_prompt.md / history_storyboard_prompt.md を参照(§4.2 ポインター)。このセクションはアンカーポイントです。
9. 制限事項
- ローカル mp4。アップロードは行いません。
- AI セグメントは通常 5–10秒。長いナレーションは複数セグメントに分割されます。
- 完成動画の長さ = TTS 全体のトラック長。
duration_secと一致しない場合があります。 - TTS:全体トラックを優先。長すぎる場合は少数のバッチにまとめて結合。バッチあたりの上限と結合戦略(
TTS_BATCH_MAXを含む)はrender_rules.md§3·C.4 が優先されます。 - テキストからの動画生成が失敗する場合は、プラットフォーム/モデルが原因の可能性があります。
max_retry_per_stepを増やす、ref_promptを短くする、シーンを分割する、workflow_result.jsonを確認するなどの対処を試みてください。