One-Click Video Renderer
Function Overview
One-click invocation of the Chanjing API for voiceover TTS, digital human synthesis, text-to-video, and local packaging; integrates ffmpeg / ffprobe for concatenation, transcoding, and track alignment. Orchestration and safety details are in §3–§8 and templates/; the final video command is in §5.
Runtime Dependencies
Must have available binaries or equivalent wrappers (see §5, run_render.py for specific invocation methods):
- ffmpeg: Concatenation, transcoding, packaging
- ffprobe: Metadata for duration, resolution, rotation, etc. (for alignment with digital human tracks)
- chan-skill (or direct
pythoninvocation of sub-skill scripts under the same repository): Drives CLIs likechanjing-tts,chanjing-video-compose,chanjing-ai-creation
Environment Variables & Machine-Readable Declarations
- Optional environment variable overrides (all have defaults or path inference, not required before running): At the top of
scripts/run_render.pyand in sub-skill source code; credential paths are inmanifest.yamlcredentials. - Compliance
permissions,clientPermissions,agentPolicy, credential model:manifest.yaml
§3.2 aligns with run_render.py; if in conflict with manifest.yaml, manifest.yaml takes precedence.
Usage Commands
- ClawHub (slug depends on the registry, often matching the skill package name):
clawhub run chanjing-one-click-video-creation - Direct from this repository:
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1(use from the skill directory or withSKILLS_DIR/CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT/CHAN_SKILLS_DIR)
Quick Reference
| Content | Location |
|---|---|
Workflow, duration_sec, null/merge, topic validation | §4.1 |
Segment splitting, odd/even mirror, scenes[], scene_count/video_type; First scene voiceover ≤20 chars (hard limit) | Beginning of storyboard_prompt.md "Text Segmentation"; First scene voiceover in script_prompt.md; video_brief_plan.md |
Rendering techniques, status, partial/success, hard constraints | render_rules.md §1–§4; §7, §8 |
ref_prompt / text-to-video prompt | storyboard_prompt.md + history_storyboard_prompt.md; §4.2 index |
| Request body fields and defaults | §6 |
run_render.py, subprocess CLI | §5 |
| Security, credentials, trust boundaries, policies | manifest.yaml + §3.1 (§3.1 does not duplicate the manifest table) |
| Environment variables, binaries, side effects, disk writes | §3.2 |
Conflict resolution: Rendering implementation takes precedence from render_rules.md; ref_prompt rules take precedence from storyboard_prompt.md / history_storyboard_prompt.md (pointers summarized in §4.2). run_render.py only implements §5 + render_rules.md, adding no business rules. Execution: manual orchestration of sub-skills, only run_render, or a mix.
1. What It Does
- Topic or full text →
video_plan, full voiceover script, storyboard - TTS: Whole segment preferred; for long text, merge into fewer batches (details and character limits in
render_rules.md§3·C.4) - Split audio per scene
- Digital human scenes:
chanjing-video-compose(audio-driven) - AI scenes:
ref_prompt→chanjing-ai-creation→ synthesize with scene audio - Packaging: Align common digital human track → ffmpeg concat → local mp4
2. When to Use / When Not to Use
| Suitable | Final output needed; mixed voiceover and AI footage; user explicitly wants to create a short video |
| Not suitable | Only script/title needed; no video requested; only editing existing footage |
3. Prerequisites
- Authentication:
chanjing-credentials-guard; credential paths and fields are inmanifest.yaml, §3.1; when no credentials exist, sub-processes can useopen_login_page.py - Plan/Script/Storyboard: Local Agent logic, no external LLM API key required (this skill's mandatory path does not depend on an external LLM)
- Local binaries and repository layout: §3.2 (
ffmpeg/ffprobe,SKILLS_DIR, etc.) - Digital human & voice: Do not use environment variables or cached files in the repository to store cross-task "default"
audio_man/person_id/figure_type. Each task must explicitly specify them at the root ofworkflow.json; the Agent should calllist_voices.pyandlist_figures.py(with--sourceset tocommon/customised, etc., matching the current task) based onvideo_plan(e.g.,video_type), voiceover persona, and topic semantics, select after comparison, and then write them;audio_manshould preferably match the selected figure'saudio_man_id. - Public digital human selection (prohibit "just take the first few items from the list"): Must use
list_figures.py --source common --jsonto fetch candidates (increase--page-sizeor paginate if necessary to cover enough entries), then compare item by item within candidates before finalizing: whethername,figures[].type(→figure_type),figures[].width/height(consistent with frame size in D.1c),audio_man_id,audio_name(if any) match thevideo_plan/voiceover persona (gender, temperament, industry, age feel). Default preference for young, energetic figures: prioritize figures whose name oraudio_namecontains positive signals like youth/girl/guy/student/vibrant/young/etc.; only when the topic or user explicitly requests mature, authoritative, middle-aged/elderly temperaments, then select the corresponding persona. For thecustomisedsource, similarly comparename,width/height,audio_man_id, etc.; do not take the first entry without comparison.
3.1 Security, Credentials, and Trust Boundaries
Environment variables and binaries are based on manifest.yaml and §3.2. When reviewing, cross-reference description and manifest.yaml (including agentPolicy).
- Capabilities & Pipeline: Step-level description in §1;
run_renderresponsibilities and sub-processes in §5 (not repeated here). - Main Credentials / Path / primaryEnv: See
manifest.yaml; paths and write-back behavior are also in §3.2 persistence table "Credential State" andCHANJING_OPENAPI_CREDENTIALS_DIR(compatible withCHANJING_CONFIG_DIR). - Sensitive & Compliance: Do not display full keys, do not commit
credentials.jsonto version control; permission recommended0700/0600(configuration scripts should attempt to set this). - Trust & Outbound Behavior: HTTPS, media pulled from returned URLs,
--output-dirdisk writes, etc. Details in §3.2 "Typical Side Effects" and persistence table; must self-judge whether to trust Chanjing hosts and links. - Browser:
webbrowser.open/open_login_page.pywhen credentials are missing, see §3.2 same table. - Agent Policy:
agentPolicyinmanifest.yaml(notalways, does not modify other skills).
3.2 Runtime Contract (Environment Variables, Binaries, Side Effects & Disk Writes)
Aligns with behavior of scripts/run_render.py and sub-skills in the same repository; consistent with the YAML at the top and manifest.yaml. If in parallel with other product documentation, the source code in this repository, manifest.yaml, and this document take precedence.
Environment Variables (Optional Overrides)
Naming follows Compliance_Rules.md §3 in the repository root. The list does not enumerate each optional variable again: it can run without setting them. Credential directory is in manifest.yaml credentials (directoryEnv, defaultPath). openapi_base_url, one_click_skills_repository_root, one_click_ref_prompt_max_chars, one_click_ai_creation_model_code in run_render.py and sub-process environment are where this skill's optional overrides and backward-compatible old names are implemented.
Note: Variables like
FIRST_DIGITAL_HUMAN_MAX_CHARSfrom some external documentation are currently not read byrun_render.py.
External Binaries
| Binary | Necessity | Purpose |
|---|---|---|
ffmpeg | Required when running run_render.py | Concatenation, transcoding, packaging audio/video, etc. Not needed if only orchestrating pure API calls without running this rendering script. |
ffprobe | Same as above | Reads media resolution, duration, rotation metadata, etc., used for alignment with digital human tracks. |
Typical Side Effects When Running the Script (by Category)
| Type | Description |
|---|---|
| Outbound HTTPS | Chanjing Open API (CHANJING_OPENAPI_BASE_URL / compatible CHANJING_API_BASE), and pulling assets like video_url / audio URLs returned by the API/CDN. |
| Local Files | Under run_render.py --output-dir, common files: final_one_click.mp4, workflow_result.json, work/ (intermediate audio, segmented videos, concat lists, etc.); specifics depend on the current command and templates/render_rules.md. |
| Subprocesses | ffmpeg / ffprobe; run_render calls Python CLIs from directories like skills/chanjing-tts, chanjing-video-compose, chanjing-ai-creation in the same repository via subprocess. |
| Browser | When credentials are missing or login is guided, the authentication chain may webbrowser.open or execute chanjing-credentials-guard's open_login_page.py (consistent with each skill's _auth.py behavior). |
Persistence Change Scope & User Controllability
The following are expected side effects for this skill; write locations can be controlled via paths and environment variables, not implicitly polluting unrelated directories.
| Category | What It Writes | Typical Location | How to Control |
|---|---|---|---|
| Credential State | Configured app_id / secret_key, refreshed access_token, expire_in, etc. | CHANJING_OPENAPI_CREDENTIALS_DIR/credentials.json (default ~/.chanjing/credentials.json; compatible with CHANJING_CONFIG_DIR) | Set the recommended name or old name; or move/delete the file; do not commit secrets to version control. |
| One-Click Video Artifacts | final_one_click.mp4, workflow_result.json, work/, etc. | Specified by run_render.py --output-dir (commonly under outputs/<task_name>/ for a given task) | Choose a clear --output-dir; keep or delete the directory after the task as needed. |
| Other Download Scripts (sub-skills) | Composite results to local disk | Each skill's download_result.py, etc.: by default, usually outputs/<product_line>/ under the current working directory, or an --output absolute path | Execute under the expected cwd, or always pass --output; see the corresponding skill's SKILL.md for details. |
| Temporary / Process Files | TTS merges, segments, pre-upload caches, etc. | Mostly under work/ within the above output-dir or script-conventional subdirectories | Managed together with the output directory. |
Credential file: Path and read/write semantics are in the Credential State row above; first-time setup is in skills/chanjing-credentials-guard/SKILL.md.
4. Rules Compilation
4.1 Workflow Orchestration
Merge: null = no override. Order: default base → non-null override → Boolean/integer correction. Field defaults are in §6; defaults not expanded in the table are read by run_render.py (and sub-processes) from implementation and environment variables (excluding voice/digital human: audio_man, person_id/avatar_id, figure_type only come from workflow.json, see §3).
duration_sec: Planning reference, not an ffmpeg upper limit. Final video duration is determined by TTS + ffprobe. scene_count is in video_brief_plan.md; segment count and AI clip count depend on actual measurements and subtitle axis (render_rules.md §3·C.5). It is forbidden to cut finalized voiceover to fit duration (unless the user requests it).
Topic: Reject blankness <5 characters, placeholder strings (e.g., "Hello", "test"); can be expanded; strict mode fails if ambiguous.
Steps: 1) Plan → video_brief_plan (failure fails everything; template in video_brief_plan.md) 2) Script (hook / first paragraph aligns with first scene: ≤20 char hard limit, see script_prompt.md) 3) Storyboard: semantic segmentation; storyboard_prompt.md (first scene voiceover has the same hard limit); non-contemporary history_storyboard_prompt.md; DH chanjing-video-compose, AI chanjing-ai-creation; TTS/multi-segment AI/mux render_rules.md §3, §5 4) Render: render_rules.md §3 (including §3·C.6), §4 (Tables 4–6); ref_prompt quality check in storyboard_prompt.md / history_storyboard_prompt.md (§4.2**); retry/partial render_rules.md §1 5) Success: render_rules.md §1
Render only: run_render.py + full_script + scenes[]. Order: Plan → Script → Storyboard → Render (which template to use at each stage is in the steps above).
4.2 Text-to-Video Prompt (ref_prompt) — Pointers
Single authoritative truth (revisions follow the templates; this document does not repeat the D.1–D.4 table text):
| Scope | Template |
|---|---|
Contemporary-oriented, D.0 context defaults and civilization-circle inference, D.1 length, D.1a, D.1b (prone to hallucination, shared across the whole skill), D.2 contemporary, manual visual_prompt, D.3, D.4 contemporary assembly and 7 elements / theme clusters / single-shot assembly / self-check | templates/storyboard_prompt.md → "Text-to-Video Prompt (Contemporary-Oriented Truth)" |
| D.2 non-contemporary routing, historical process layer, civilization circle and country consistency, placeholder discipline, and linking instructions with D.3/D.4 | templates/history_storyboard_prompt.md |
| Ethnicity, historical/non-contemporary Chinese styling and English phrases when characters appear | templates/visual_prompt_people_constraint.md (explicit ethnicity anchoring, historical/non-contemporary section; also render_rules.md §4 Tables 4–6) |
Indexed here only: Long audio multi-segment render_rules.md §3·C.6; character limit CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatible with AI_VIDEO_PROMPT_MAX_CHARS). In case of conflict between the template and render_rules.md implementation, render_rules.md takes precedence.
5. Automated Orchestration (run_render.py)
Dependencies: Authentication; SKILLS_DIR / CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT / CHAN_SKILLS_DIR (§3); chanjing-tts / chanjing-video-compose / chanjing-ai-creation
Responsibilities: ① TTS + audio_task_state; batch merging and per-batch character limit in render_rules.md §3·C.4 (TTS_BATCH_MAX) ② Segment splitting (render_rules.md §3·C.5) ③ When AI scenes exist, first complete the first digital human scene and run ffprobe (including rotate) → then submit text-to-video with mapping for aspect_ratio/clarity (see render_rules.md §3·C.6, debug.ai_video_submit_params) ④ Parallel poll remaining DH/AI ⑤ Align AI track to the ffprobe reference ⑥ ffmpeg concat ⑦ For multi-segment text-to-video, append English hierarchical tags after ref_prompt; total length constrained by CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatible with AI_VIDEO_PROMPT_MAX_CHARS)
Does NOT do: Does not produce plan/script/storyboard; does not auto-detect contemporary/non-contemporary; does not use list_tasks.py for contemporary times (render_rules.md §4 Table Item 8)
Manual orchestration: Must still satisfy render_rules.md §3, §4, and §5; §3 details (e.g., silencedetect, minterpolate, reference track bitrate, swapping figure with the same segment audio, TTS inter-batch silence, etc.) are all preserved.
Input MVP
| Field | Required | Description |
|---|---|---|
full_script | Yes | Concatenated from each scene's voiceover by scene_id, with consistent norm |
scenes | Yes | scene_id, voiceover, use_avatar; for AI scenes: ref_prompt (storyboard_prompt.md / history_storyboard_prompt.md; §4.2); optional subtitle |
audio_man | Yes | Should match the selected digital human figure's audio_man_id |
person_id/avatar_id | Conditional | Required if there are DH scenes |
figure_type | No | Must match the figure_type of the figure selected by list_figures.py for this task (required for public multi-form figures) |
subtitle_required | No | Default false; when true, burn subtitles into digital human scenes (--subtitle show) |
speed/pitch | No | Default 1/1 |
ai_video_duration_sec | No | 5 or 10, default 10 |
model_code | No | Default CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE (compatible with AI_VIDEO_MODEL) or Doubao-Seedance-1.0-pro; creation_type=4; do not pass ref_img_url |
max_retry_per_step | No | Default 1 (§6) |
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1
Outputs: final_one_click.mp4; workflow_result.json; work/
6. Input (Request Body)
norm: Strip \r, leading/trailing whitespace; empty → empty string; consistent with run_render.py. Voiceover: first non-empty among full_script, then script → copy_text → input_script → content. No topic: use the first sentence as the topic (truncate at end-of-sentence punctuation within 40 chars, otherwise at 24 chars). null/merge in §4.1.
| Field | Required | Description |
|---|---|---|
topic | Conditional | If absent, use the first sentence rule; recommended ≥5 characters |
industry/platform/style | No | industry can be empty; platform/style: DEFAULT_* or douyin/opinion-style voiceover |
duration_sec | No | DEFAULT_DURATION or 60; planning reference |
use_avatar | No | Default true |
avatar_id/voice_id | No | Can be empty; must not use environment variables as fallback for voice or digital human; must explicitly write audio_man/person_id (and figure_type when DH scenes exist) in workflow.json, selected by the Agent after calling list_voices.py and list_figures.py (source consistent with video_plan / user specification) and comparing name, form, frame size, audio_name, etc.; prohibit taking the first few list items without comparison; default preference for young digital humans (see §3) |
subtitle_required | No | Default false (digital human output does not burn subtitles; run_render passes hide) |
cover_required | No | Default true |
strict_validation/allow_auto_expand_topic/max_retry_per_step | No | true/false/1 |
full_script | No | Default empty |
script_title/script_hook/script_cta | No | Default empty |
script/… | No | See the voiceover priority order above |
7. Output JSON
| Key | Meaning |
|---|---|
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 |
| Others | error, debug… |
No degradation in rendering: Failure in any step aborts the process; does not automatically fall back to DH-only or AI-only output. partial: Indicates success was not achieved (e.g., run_render exception still writes workflow_result.json); does not permit the aforementioned degradation, does not exempt quality checks like storyboard_prompt.md·D.1b. On success, degrade_log=[]; on failure, try to preserve already produced copy and storyboard.
8. Hard Constraints
Table in templates/render_rules.md §4; cross-references with ref_prompt in storyboard_prompt.md / history_storyboard_prompt.md (pointers in §4.2). This section is an anchor.
9. Limitations
- Output is a local mp4; does not upload it anywhere.
- AI clips are typically 5–10s; long voiceovers will use multiple clips.
- Final video duration = total TTS track duration; may not match
duration_sec. - TTS: Full track preferred; for very long text, merge into a few batches; per-batch limit and merging strategy (including
TTS_BATCH_MAX) as defined inrender_rules.md§3·C.4. - Text-to-video failure may be due to platform/model; try increasing
max_retry_per_step, shorteningref_prompt, splitting scenes; checkworkflow_result.json.