hyper-animator

Claude Code skill for the HyperFrames animation pipeline — natural language to rendered video.

Quick Start

npm install -g hyper-animator

Then in any directory, run inside Claude Code:

/hyper-animator

Describe what you want — the skill walks you through purpose, format, style, audio preferences, and generates the animation.

/hyper-animator

"做一个 AI 产品发布视频，Apple 风，横屏 16:9，展示 App 界面"

What It Does

From a single natural language request, hyper-animator produces:

• Render HTML — Pure composition for HyperFrames rendering
• Preview HTML — Browser-previewable with progress bar, page navigation, audio sync
• Rendered Video — MP4 output via hyperframes render
• BGM + SFX — Generated via Minimax API or Python wave synthesis
• Narration TTS — Per-scene voiceover with voice cloning support
• SRT Subtitles — Timed subtitle file from narration script

Pipeline

Step 0: Git workspace setup + file detection (outline/narration)
Step 1-2: Intent extraction + AskUserQuestion Round 1 (purpose/format)
Step 3: Catalog scoring — 133-item HyperFrames catalog w/ 7-factor weighted scoring
Step 4-5: Candidate plan selection + generation mode decision
Step 6: AskUserQuestion Round 2 (style/motion)
Step 6.5: AskUserQuestion Round 3 (SFX/BGM/voice/emotion/subtitles/volumes)
Step 6.6a: Audio generation (Minimax API → Python wave fallback)
Step 6.6b: Beat detection for music-synced animation
Step 6.6c: Narration TTS (Minimax `/v1/t2a_v2`, voice cloning support)
Step 7-8: HTML generation (assemble catalog items or generate new)
Step 9: Quality gates (16 checks)
Step 10-11: User validation + revision loop
Step 12: Render via HyperFrames CLI

Scripts

| Script | Purpose | |--------|---------| | minimax-gen.py | Generate BGM via Minimax music-2.6 API (3-retry, HTTP/1.1, workaround for CN server bugs) | | wave-gen.py | Fallback BGM synthesis (drum loop + SFX via Python wave module) | | tts-gen.py | Narration TTS with voice listing (--list-voices) and per-scene emotion support | | preview-gen.py | Generate preview HTML from render HTML (progress bar, page nav, multi-audio sync) | | subtitle-gen.py | Generate SRT file + HTML subtitle layer from narration JSON | | sync-catalog.py | Sync source cache + merge catalog-map.json from live HyperFrames registry | | validate-quality.sh | 16 quality gate checks on generated HTML |

Configuration

MiniMax API Keys

Set up automatically on install. Edit ~/.claude/skills/hyper-animator/.env:

MINIMAX_API_KEY=sk-api-...    # Music + TTS generation
MINIMAX_GROUP_ID=...          # Your group ID (optional)
# MINIMAX_API_HOST=api.minimax.io  # International (default: CN domestic)

Or export environment variables:

export MINIMAX_API_KEY=sk-api-...

Without keys, audio falls back to Python wave synthesis — no account needed.

Narration Script Format

Create narration.json alongside your content outline:

{
  "voice": "XiaoR_001",
  "emotion": "calm",
  "language": "zh",
  "style": "formal",
  "subtitle_style": { "font_size": 36, "color": "#fff", "background": "rgba(0,0,0,0.6)", "position": "bottom" },
  "scenes": [
    {
      "scene": 1,
      "title": "开场",
      "sync_hint": "intro",
      "narration": "欢迎来到我们的产品发布。",
      "duration_estimate": 5,
      "subtitles": [{"text": "欢迎来到", "start": 0.0, "end": 2.0}]
    }
  ]
}

Architecture

SKILL.md (~62KB, pipeline + decisions)  ← LLM context
references/                             ← loaded on demand
  scoring.json          — formula + prompt mappings + taxonomies
  checklist.md          — Step 8 critical checklist
  quality-gates.yaml    — authoritative gate contract
  catalog-map.json      — 133 catalog items (auto-synced from live registry)
  patterns-codex.md     — 778-line generation patterns
  source-cache/         — 133 downloaded HyperFrames HTML source files
scripts/                                ← deterministic execution

Output Structure

hyperframes-output/
├── <name>.html            # Render file (pure composition)
├── <name>-preview.html    # Preview file (with controls)
├── <name>.mp4             # Rendered video
├── <name>-beat.json       # Beat detection data
├── subtitles.srt          # Subtitle file
└── assets/
    ├── bgm-full.mp3/wav   # Background music
    ├── scene-*.wav        # Narration audio clips
    └── sfx-*.wav          # Sound effects

Requirements

• HyperFrames CLI — video rendering
• Python 3.8+ — script execution
• music-beat-detector — BPM/beat analysis (optional, for BGM sync)
• MiniMax API key — music generation + TTS (optional, falls back to local synthesis)

Contributing

git clone [email protected]:realpkuasule/hyper-animator-2.git
cd hyper-animator-2
python3 -m pytest tests/ -v         # Run tests
python3 scripts/sync-catalog.py     # Sync source cache
python3 scripts/sync-catalog.py --sync-catalog-map  # Sync catalog map

License

MIT