一鍵式影片渲染器
功能說明
一鍵呼叫 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頂部及子 skill 原始碼;憑證路徑見manifest.yamlcredentials。 - 合規
permissions、clientPermissions、agentPolicy、憑證模型:manifest.yaml
§3.2 與 run_render.py 對齊;若與 manifest.yaml 衝突,以 manifest.yaml 為準。
使用命令
- ClawHub(slug 以註冊表為準,常與技能包名一致):
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,不增業務規則。執行:手工編排子 skill、僅 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 - Plan/Script/分鏡:本地 Agent 邏輯,無需外部 LLM API key(本 skill 必選路徑不依賴外部 LLM)
- 本機二進位與倉庫佈局:§3.2(
ffmpeg/ffprobe、SKILLS_DIR等) - 數位人與音色:勿用環境變數或倉庫內快取檔案儲存跨任務的「預設」
audio_man/person_id/figure_type。每次任務在workflow.json根級顯式填寫;由 Agent 按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 同表。 - Agent 策略:
manifest.yaml中agentPolicy(非 always、不改其它 skill)。
3.2 執行時期契約(環境變數、二進位、副作用與落盤)
與 scripts/run_render.py 及同倉庫子 skill 行為對齊;與篇首 YAML、manifest.yaml 一致。若與其它產品文件並列,以本倉庫原始碼、manifest.yaml 與本文為準。
環境變數(可選覆蓋)
命名以倉庫根 合規規則.md §3 為準。清單未再逐項列舉可選變數:不設亦可執行。憑證目錄見 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(與各 skill 的 _auth.py 行為一致)。 |
持久性變更範圍與使用者可控性
以下對本 skill 而言屬預期內副作用;可透過路徑與環境變數控制寫入位置,而非隱式污染無關目錄。
| 類別 | 寫入什麼 | 典型位置 | 使用者如何控制 |
|---|---|---|---|
| 憑證狀態 | 經設定寫入的 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;任務結束後按需保留或刪除該目錄。 |
| 其它下載類腳本(子 skill) | 合成結果等到本地 | 各 skill 的 download_result.py 等:預設多在當前工作目錄下 outputs/<產品線>/,或 --output 絕對路徑 | 在預期 cwd 下執行,或始終傳 --output;詳見對應 skill 的 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) Plan → video_brief_plan(敗則全敗;模板見 video_brief_plan.md)2) Script(hook / 首段與首鏡對齊:≤20 字硬上限,見 script_prompt.md)3) Storyboard:語意切分;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: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[]。順序:Plan → Script → Storyboard → Render(各階段用哪份模板見上列步驟)。
4.2 文生影片提示詞(ref_prompt)— 指標
唯一條文真值(修訂以模板為準,本文不重複 D.1–D.4 表文):
| 範圍 | 模板 |
|---|---|
當代向、D.0 語境缺省與文明圈推斷、D.1 長度、D.1a、D.1b(易幻覺,全 skill 共用)、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 並行 poll ⑤ 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),由 Agent 按當次任務呼叫 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 | 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–10s;長口播多段
- 成片時長=TTS 總軌;可與
duration_sec不符 - TTS:整軌優先、超長少批合併;單批上限與合併策略(含
TTS_BATCH_MAX)以render_rules.md§3·C.4 為準 - 文生失敗可能為平台/模型;試增
max_retry_per_step、短ref_prompt、拆鏡;查workflow_result.json