# hyper-animator

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

[![npm](https://img.shields.io/npm/v/hyper-animator)](https://www.npmjs.com/package/hyper-animator)
[![GitHub](https://img.shields.io/badge/github-realpkuasule%2Fhyper--animator--2-blue)](https://github.com/realpkuasule/hyper-animator-2)

## Quick Start

```bash
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`:

```bash
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:
```bash
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:

```json
{
  "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](https://www.npmjs.com/package/@hyperframes/cli) — video rendering
- Python 3.8+ — script execution
- [music-beat-detector](https://pypi.org/project/music-beat-detector/) — BPM/beat analysis (optional, for BGM sync)
- MiniMax API key — music generation + TTS (optional, falls back to local synthesis)

## Contributing

```bash
git clone git@github.com: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