ming-xwolf/create-template-video-zh

Create Template Video (中文版)

Convert a piece of Chinese content into a 9:16 vertical short video. All design and animation are handled by the HyperFrames templates in templates/—you just fill in the text slots and the script.json.

Local Installation Info (DSH Environment, Must Read First)

• PROJECT_DIR = /Users/ming/.agents/skills/create-template-video-zh (skill itself + pipeline + templates; node_modules symlinked to Vietnamese version, dependencies shared)

• Directory structure: SKILL.md, templates/ (11 templates + CATALOG.md), src/ (CLI/pipeline), package.json, .env (Chinese TTS endpoint).

• Tool mapping: The original skill uses Claude Code tool names; here they correspond to DSH: WebFetch → web_fetch, Read → read, Write → write, Bash → bash.

• Environment dependencies: ffmpeg/ffprobe ✓, Chrome ✓, Node ✓.

• Chinese TTS deployed locally: OmniVoice (MPS) + Mandarin cloned voice voice-zh.pt, running on port 8124 (Vietnamese version uses port 8123, they don't interfere):

  bash "$HOME/.agents/skills/create-template-video-zh/scripts/start-tts-zh.sh"
  

  The script checks /health, starts the service in the background, and waits until it's ready (~4s); logs are in /tmp/omnivoice-zh.log. After startup, confirm with a Chinese probe:

  curl -s -X POST http://127.0.0.1:8124/tts -H 'Content-Type: application/json' \
    -d '{"text":"大家好，这是中文配音测试。"}' -o /tmp/zh-probe.mp3 && ls -l /tmp/zh-probe.mp3
  

  000/connection refused = not started; if it fails to start, stop and inform the user, do not fake audio. Service directory and deployment notes: /Users/ming/Documents/dsh_workspace/omnivoice (SETUP.md).

• The first render will download HyperFrames via npx -y [email protected] (requires internet, ~15–20s per scene; 8–10 scenes total 3–5 minutes).

• Language: Full video in Chinese. On-screen text can mix Chinese and English (keep AI, GPT, Apple, Apple as-is), but voiceText must be Chinese; numbers must be written as Chinese characters per the rules below.

Input

1 parameter: a news URL (http:///https://) or a .txt file path.

Workflow (Strictly Sequential)

Step 1–3: Fetch Content + Create Output Directory

• URL → web_fetch to fetch the body, extract title, content (800–2000 characters of main text), ogImage (og:image or null), domain. Failure (paywall/pure JS/4xx) → ask user to save the main text as .txt and re-run, then stop.
• .txt → read to read; title = first line (≤40 characters), content = remaining text, ogImage = null, domain = "local".
• slug: Prefer English or pinyin keywords (≤40 characters, [a-z0-9-]), e.g. xiaomi-17-price, ai-coding-jobs. If the pure Chinese title cannot be converted to ASCII, you write pinyin; if truly impossible, use zh-video (also the fallback in code). timestamp = YYYYMMDD-HHmm; outputDir = <current workspace>/videos/<slug>-<timestamp>/ — inside the workspace: for easy delivery and to avoid polluting the skill directory (DSH sandboxes usually only allow writing to the workspace). mkdir -p. The SFX library location is pointed to by .env's SFX_DIR inside assets/sfx, decoupled from the output directory; if the SFX library is empty, that layer is automatically skipped without affecting the main flow.

Step 4: Read Template Catalog

Read PROJECT_DIR/templates/CATALOG.md to confirm templates and slots. Only use templateId values from the CATALOG. Existing:

HOOK (use only this one): frame-liquid-bg-hero — aurora light spot + big title + CTA.

BODY (choose by content, see Step 5):

• frame-vignelli — 1 number, dark charcoal background + red.
• frame-pentagram-stat — 1 number/benchmark, dark neon (Swiss grid, orange glowing numbers + cyan accents + bar chart).
• frame-bold-poster — multi-line strong statement + large number.
• frame-build-minimal — short punchy line, dark background + one oversized bold word (orange glow, typewriter effect).
• frame-creative-voltage — creative slogan, electric blue split + handwriting style.
• frame-glitch-title — cyberpunk RGB glitch distortion (noise background), suitable for breaking/tech news.
• frame-aicoding-list — list of 2–5 items (each with icon + level tag), dark gradient background.
• frame-aicoding-comparison — A vs B comparison (two gradient cards + WIN badge + data).

OUTRO: frame-logo-outro (default: logo glow + brand + tagline + url); frame-statement-outro (alternative: paper background with red card).

The 11 templates' built-in example values (data-composition-variables) have all been replaced with Chinese samples, so you can see the final effect in previews, or copy them directly into script.json and modify. However, explicitly pass inputs during rendering: if you don't pass parameters, the runtime won't get the variables, and text will be empty.

Step 5: Generate script.json

{
    "version": "1.0",
    "renderer": "hyperframes",
    "aspect": "9:16",
    "metadata": {
        "title": "...",
        "source": { "url": "...", "domain": "...", "image": null },
        "channel": "中文频道名"
    },
    "voice": { "provider": "omnivoice", "speed": 1.0 },
    "scenes": [
        /* 8–12 scenes: 1 hook + 6–10 body + 1 outro */
    ]
}

• provider is fixed to omnivoice (local TTS, no voiceId/API key needed).
• Each scene: { id, type, voiceText, templateId, inputs }; inputs must cover the required slots for that template in the CATALOG.
• scenes[0].type = "hook"; scenes[-1].type = "outro" (frame-logo-outro).
• 8–12 scenes; total voiceText about 350–450 characters (≈90–120s, Chinese speech rate about 4.5 characters/s; final duration is determined by the voiceover, pipeline aligns to that). Each body scene 30–45 characters, covers just one point; if a paragraph has two points, split into two scenes. Goal: each scene stays on screen for 6–10s.

Content → Template Mapping:

• hook → fixed frame-liquid-bg-hero (slots: kicker, headline, subheadline, cta, brand). headline defaults to yellow → purple gradient; use headline_from/headline_to (two hex values) to change colors.
• body → you choose the most suitable template by content, and vary them as much as possible, don't reuse the same one for all body scenes:
  • frame-vignelli: scene has 1 number to emphasize (kicker, number, label, note, brand).
  • frame-pentagram-stat: has 1 benchmark/percentage number + bar chart feel (label, headline=number, subtitle, anchor, footer_left, footer_right).
  • frame-build-minimal: short punchy line / one keyword (eyebrow, hero=single word, desc, side_left, side_right).
  • frame-bold-poster: multi-line strong statement + large number (kicker, date, figure, headline[], standfirst, footer_left, footer_right). Line 2 of headline automatically turns red.
  • frame-creative-voltage: creative slogan (meta, display_lines, accent_index, script, caption).
  • frame-glitch-title: breaking/tech/scary feel (title, subtitle).
  • frame-aicoding-list: list/comparison of 2–5 items (title, accent, accent_from, accent_to, subtitle, items[]). Each item {icon, title, desc, tag, level}: icon you choose from emoji (🚫 ⚠️ ✅ ❌ 📈 💡 🔒 🚀 …); level ∈ danger|warn|good|info determines color; tag uses short Chinese label (高险 / 注意 / 利好 / 稳健); accent_from/accent_to you pick two hex values.
  • frame-aicoding-comparison: exactly for comparing two things (badge, pre, vs, post, left{}, right{}). Each side: {label, from, to, icon?, bullets[], stat?, stat_label?, win?}; from/to are gradient two-color hex (better to contrast warm/cool tones on each side); win: true marks the winner.
  • Rhythm suggestion: when many number scenes, alternate frame-vignelli (charcoal black + red/yellow) with frame-pentagram-stat (dark neon orange/cyan); for non-number scenes, use frame-build-minimal.
• outro → frame-logo-outro (brand_name, tagline, primary_url).

Chinese Typography Rules (On-screen Text inputs)

• Chinese takes up more space than English/Vietnamese: keep one line to 10–14 Chinese characters; if more, wrap or trim; headline at most 3 lines. Better to drop two characters than to cram into two and a half lines.
• Default template fonts are Inter Tight + system-ui; Chinese will fall back to PingFang SC, normally fine; if rendered as boxes/tofu, insert "PingFang SC", "Noto Sans SC", at the beginning of font-family in that template's compositions/portrait.html and re-render.
• Chinese does not need spaces between words; do not manually add negative letter-spacing in Chinese; the template's built-in -3px will make characters stick together. If a title looks too tight, override with letter-spacing: -1px on that class.
• Emoji is allowed in on-screen text, but 0–1 per field; don't put it in fields with typewriter animation (e.g., frame-build-minimal's hero), otherwise the animation will break.
• Keep numbers in a readable format on screen (4499 元, 82.7%, 17), only convert to Chinese characters in voiceText.

Chinese TTS Rules (voiceText Must Comply)

OmniVoice reads text character by character; Arabic digits, decimal points, and currency symbols are often misread or read as English. Therefore, in voiceText, write all numbers as Chinese characters; inputs (on-screen text) keep numbers.

Form	Wrong Example	Correct Writing
Decimal	82.7%	百分之八十二点七
Version number	iOS 18.2	iOS 十八点二
Product model	小米 17	小米十七
Pixels	200MP	两百万像素
Battery	5000mAh	五千毫安时
Magnitude	1M tokens	一百万 token
RMB	¥4499	四千四百九十九元
USD	$5	五美元
Multiple	2x	两倍
Percentage	30%	百分之三十
Duration	60s	六十秒
Ratio	3:1	三比一
Year	2026 年	二零二六年
Trillion	21 万亿	二十一万亿
Ranking	Top 3	前三名

• Probe English abbreviations before deciding: AI, GPT, API, 5G, GPU in Chinese TTS are sometimes read letter by letter ("A-I"), sometimes as English words. Before writing them into the video, use a probe to say both sentences and compare: AI 很强大 vs 人工智能很强大, choose the more natural-sounding writing and keep it consistent throughout the video.
• Keep brand names as-is (Apple, OpenAI, Xiaomi), Chinese brands write directly in Chinese.
• voiceText strictly forbids: emoji/icons, URLs, and symbols like & % $ # + = /; use 。 or ？ at the end of sentences for natural pauses; commas use ，.
• Consistency for "两" vs "二": use "两" for spoken quantifiers (两千, 两万, 两倍), use "二" for ordinals/years (二零二六年, 第二季度).

Step 6: Self-Check

• scenes[0] is hook, last is outro; every templateId is in the CATALOG; every inputs covers required slots;
• Chinese line width ≤14 characters, headline ≤3 lines; voiceText has no Arabic digits/symbols/emoji; emoji appears only in inputs; word usage and abbreviation pronunciation consistent throughout video;
• Total voiceText 350–450 characters. Silent corrections at most 2 rounds.

Step 7: Write script.json

Use the write tool to write to <outputDir>/script.json (first mkdir -p the output directory).

Step 8: Run Pipeline

First start Chinese TTS (see beginning) and confirm probe audio exists, then execute in the foreground:

cd "$HOME/.agents/skills/create-template-video-zh" && npm run pipeline -- "<outputDir>/script.json"

CLI follows renderer: "hyperframes" to go through the template pipeline: TTS → render per template → align to voiceover duration → concatenate + mix audio. On failure, report the error clearly and give the outputDir path (already rendered voice/scene-*.mp3, clips/scene-*.mp4 will be reused; delete them to re-render).

When re-running after changing Chinese copy, first delete the corresponding voice/scene-*.mp3 files, otherwise old dubbing will be reused.

Step 9: Deliver

Copy the three deliverables to the session workspace for easy user access:

mkdir -p "<cwd>/videos/<slug>" && cp "<outputDir>"/{video.mp4,voice.mp3,script.txt} "<cwd>/videos/<slug>/"

Then report (with clickable links):

✓ Video: videos/<slug>/video.mp4
✓ Audio: videos/<slug>/voice.mp3 — for Jianying (auto subtitles/lip sync)
✓ Script: videos/<slug>/script.txt — shot-by-shot text, easy for manual editing
Total duration: XX.Xs

Notes

• Each scene renders ~15–20s (Chromium); 8–10 scenes total ~3–5 minutes.
• TTS is idempotent (preserves voice/scene-*.mp3), clip rendering is also idempotent (preserves clips/scene-*.mp4).
• On M2 Max, Chinese TTS RTF (real-time factor) is about 2.8: 1 minute of finished video takes about 3 minutes of pure TTS. To speed up, set OMNIVOICE_STEPS to 16 on the server (slightly lower quality, half the time) and restart.
• If assets/sfx is empty, the SFX layer is zero and does not affect the main flow; to add SFX, run npm run sfx:download (requires internet) before generating (default downloads to the skill's assets/sfx/, i.e., the location pointed to by SFX_DIR in .env). Semantic keywords already include Chinese (warning/failure/record/first/countdown/epic/suspense…).
• Differences from the Vietnamese create-template-video: TTS port 8124 + Chinese voice, Chinese number pronunciation table, Chinese typography constraints, Chinese SFX keywords, zh-video slug fallback. Code is an independent copy (only node_modules is symlinked to Vietnamese version); modifying templates/pipeline only affects this directory. If deleting the Vietnamese version, remember to run npm ci to rebuild dependencies.
• Adding templates: follow the instructions at the end of templates/CATALOG.md, then add a line to the CATALOG.