alchaincyf/huashu-motion

huashu‑motion – AI‑driven video‑promo generator

What it does

• Turns a short natural‑language request (e.g. “make a 30 s promo for my product, website is …”) into a complete, commercial‑grade product video.
• The agent first reads the product, proposes three storyboard directions, writes a rhythm/beat sheet, composes a musical score, and finally opens an in‑browser editor where you can point‑and‑click on any frame to request a precise edit.
• Supports full‑cycle workflow: storyboard → code‑generated animation (GSAP/Canvas/Three.js/SVG) → sampled instrument music → optional voice‑over → rendering/export to MP4, MOV (with alpha), WebM, GIF or a shareable HTML page.

How it works

1. Skill architecture – The repository ships as an Agent Skill (compatible with Claude Code, Codex, WorkBuddy, Grok Bot, Muse, Dots, etc.). Installing the skill (npx skills add alchaincyf/huashu-motion) drops a bin/om CLI into the agent’s skill directory.
2. Prompt‑to‑code pipeline – The LLM agent writes the HTML/JS that defines the animation. All visual elements are produced by code (GSAP, Canvas, Three.js, SVG); no external video‑generation model is required.
3. Music generation – In composer mode the agent writes an ABC‑notation score. The CLI renders it with real‑instrument samples (or synthetic sound if samples are not built). A library of 12 product‑type music templates provides fallback tracks.
4. Voice‑over & alignment – System TTS or a user‑provided audio file can be aligned word‑by‑word to the timeline using whisper.cpp.
5. Interactive editing – Press C in the browser editor, click a frame, type a comment. The comment (including timestamp, scene, element, source line) is sent back to the agent via om inbox. The agent updates only the affected code block and replies with a human‑readable summary.
6. Rendering – Chrome/Chromium instances render frames in parallel (up to 8 by default). FFmpeg stitches frames and mixes the generated audio. On a 14‑core Mac a 30 s clip renders in ~12‑15 s.

Key components

• cli/om – command‑line interface (project creation, studio editor, inbox handling, sound utilities, quality checks, rendering, export).
• studio/ – in‑browser editor that shows the live preview, a timeline bar, and editable property panels.
• templates/ – ten starter templates (product launch, data‑driven explainer, whiteboard, 3Blue1Brown‑style, etc.).
• references/library/ – 20 curated “motion languages” describing visual styles for different product categories, derived from quantitative analysis of 21 real‑world launch videos.
• fonts/ – 27 open‑source fonts (Chinese heavy, serif, display) bundled for immediate use.
• runtime/ – lightweight runtime helpers (OM.*) used by the generated HTML to drive animation and synchronization.

Installation & requirements

• Node 22+, Chrome/Chromium/Edge, FFmpeg.
• Optional: real‑instrument sample pack (om samples build ~55 MB), Chinese TTS model (Kokoro, ~325 MB), whisper-cli for alignment.
• Currently tested on macOS; other OSes may work with minor adjustments.

Typical workflow

User: "Make a 30‑second promo for my product, website is xyz.com"
→ Agent reads site, proposes 3 storyboard options
→ Agent writes rhythm sheet, ABC score, and full HTML/JS animation
→ `om studio` opens the editable preview
User: click frame, type "Make the opening effect smoother, focus on typing"
→ `om inbox` delivers comment, agent patches only that code block
→ Preview refreshes, user can undo (⌘Z) or edit numeric fields directly
→ `om render` → MP4/WEBM export

Limitations

• Visuals are code‑generated; no photorealistic footage or 3‑D models are created automatically.
• Quality of music and style depends on the underlying LLM (Claude Code, DeepSeek Flash, etc.).
• Requires a local environment capable of running Chrome and FFmpeg; not a pure cloud service.

License – MIT for code and documentation; third‑party assets retain their original licenses (GSAP Standard, SIL OFL fonts, CC0/CC‑BY samples).

Who it’s for

• Product marketers or indie developers who want fast, customizable promo videos without hiring a design agency.
• AI‑agent developers looking for a concrete example of an Agent Skill that bridges LLM prompting, code generation, and media rendering.

---

All information above is taken directly from the repository’s README.