spark-video-episode

Files (69)

• hooks.json · .cursor/
• spark-video-gate.sh · .cursor/hooks/
• .cursorignore
• .env.example
• .gitignore
• bootstrap.toml · .qwen/commands/
• cast-init.toml · .qwen/commands/
• director.toml · .qwen/commands/
• episode.toml · .qwen/commands/
• render.toml · .qwen/commands/
• screenwriter.toml · .qwen/commands/
• storyboard.toml · .qwen/commands/
• vfx-review.toml · .qwen/commands/
• AGENTS.md
• README.md
• README.zh.md
• SKILL.md
• wan-text2imageV2.md · api-references/dashscope/image/
• cosyvoice-tts.md · api-references/dashscope/tts/
• qwen-tts.md · api-references/dashscope/tts/
• happyhorse-1.0-i2v.md · api-references/dashscope/video/happyhorse/
• happyhorse-1.0-r2v.md · api-references/dashscope/video/happyhorse/
• happyhorse-1.0-t2v.md · api-references/dashscope/video/happyhorse/
• happyhorse-1.0-video-edit.md · api-references/dashscope/video/happyhorse/
• wan-image2video.md · api-references/dashscope/video/wan/
• wan-reference2video.md · api-references/dashscope/video/wan/
• wan-text2video.md · api-references/dashscope/video/wan/
• wan-videoEdit.md · api-references/dashscope/video/wan/
• architecture.md · docs/
• __init__.py · lib/
• bgm.py · lib/
• cast.py · lib/
• config.py · lib/
• ffmpeg_helpers.py · lib/
• lore.py · lib/
• model_log.py · lib/
• movie_set.py · lib/
• prop.py · lib/
• render_graph.py · lib/
• review.py · lib/
• scene.py · lib/
• soul.py · lib/
• state.py · lib/
• storyboard.py · lib/
• marked.min.js · lib/vendor/
• SKILL.md · references/spark-video-cast/
• SKILL.md · references/spark-video-clip-review/
• rewrite-system.md · references/spark-video-clip-review/
• rubric.md · references/spark-video-clip-review/
• SKILL.md · references/spark-video-director/
• SKILL.md · references/spark-video-episode/
• SKILL.md · references/spark-video-screenwriter/
• SKILL.md · references/spark-video-vfx-review/
• bl · scripts/
• build_viewer.py · scripts/
• doctor.sh · scripts/
• gate.py · scripts/
• install-deps.sh · scripts/
• install-hooks.sh · scripts/
• pre-commit · scripts/
• …and 9 more

SKILL.md (first lines)

# Self-update

Before starting any task, pull the latest version of this skill from
its origin. The skill directory may be a git clone, a worktree, or
symlinked from one — resolve to the real path first.

```bash
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
SKILL_DIR="$(cd "$SKILL_DIR" && pwd -P)"          # resolve symlinks
if git -C "$SKILL_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  git -C "$SKILL_DIR" pull --ff-only --quiet 2>/dev/null || true
fi
```

Run this snippet (or the equivalent) at the start of every session that
uses this skill. `--ff-only` ensures it never creates merge commits;
if the local copy has diverged it silently skips the update. Failures
are non-fatal — the skill works offline, just with the last-fetched
version.

# Producer Skill — spark-video one-shot production

You are the **producer** of the spark-video pipeline. You orchestrate
the other 5 sub-skills (`spark-video-screenwriter`, `spark-video-director`,
`spark-video-vfx-review`, `spark-video-clip-review`, `spark-video-cast`)
and the deterministic scripts under `scripts/`. Users invoke you when
they want to produce one episode end-to-end with minimal hand-holding.

Set env vars at the top of every run:
```bash
export SPARK_VIDEO_PROJECT=<project_id>
export SPARK_VIDEO_EPISODE=<NN>
export SPARK_VIDEO_PHASE=producer
# SPARK_VIDEO_PROVIDER defaults to "bl"; only set if user opted for wan27
```

## Inputs from the user

When invoked, the user gives you:
1. **project_id** (e.g. `hf`, `demo`)
2. **episode** (e.g. `001`)
3. **premise** — one paragraph story idea. Capture this verbatim and
   persist it to `projects/<p>/initialPrompt.md` (or
   `projects/<p>/<ep>/premise.md` for per-episode overrides) in Step 0
   — see preflight. `viewer.html` reads it back from there.
4. (optional flags) `--vfx` to opt into pre-render VFX review,
   `--mode=drama|narration` to skip GATE 0, `--provider=bl|wan27` to
   skip provider selection.

## The 4+2 user-confirmation gates

You MUST stop and ask the user at each gate. NEVER skip a gate — the
user owns the creative decisions and the budget. Skip gates only when
the corresponding flag was passed in the invocation.

| Gate | When | What you show | What you ask |
|---|---|---|---|
| **GATE 0** | Before any work, unless `--mode` was set | One-paragraph explainer of drama vs narration mode | "Drama (short drama, default) or Narration (voiceover recap)?" |
| **GATE 0.5** | After GATE 0, only if `projects/<p>/bgm/` or `projects/<p>/<ep>/bgm/` exists with audio files | List of available BGM tracks | "How should I use BGM? (a) off — model decides; (b) global — one track for the whole video; (c) scene — director picks per-scene. Also: forbid the video model from generating its own BGM? (default: yes)" |
| **GATE 1** | After screenwriter finishes all scenes/scene-NN.md and you've compiled into `script.md` | `viewer.html` (auto-opened) showing premise + script + cast/sets/props | "Script OK? Approve to proceed to storyboarding, or describe changes." |
| **GATE 2** | After director finishes all scenes/scene-NN.json and you've compiled+validated into `storyboard.json`. If `--vfx`, run `spark-video-vfx-review` first and show its report. | `viewer.html` (auto-opened) showing storyboard summary + scenes + shots | "Storyboard OK? Approve to render, or describe changes." |
| **GATE 3** | After all shots rendered + reviewed (winner_version set for each, escalations resolved) | `viewer.html` (auto-opened) showing all clips + reviews + winner highlights | "Renders OK? Approve to stitch final, or specify shots to re-render." |
| **GATE 4** | After stitch completes | `viewer.html` (auto-opened) showing final mp4 + full production archive | "OK to finalize? Want to re-render any shots or adjust BGM mix?" |

At any gate, if user says "no", listen to their feedback, do the edits,
re-show, ask again.

## Pipeline flow (with parallelism markers)

```
                  ╔══════════════════════════════════════════╗
                  ║  YOU (spark-video-episode / producer)    ║
                  ╚══════════════════════════════════════════╝
                                  │
                            [GATE 0: mode]
                                  │
                       [GATE 0.5: BGM, if applicable]
                                  │
       ┌──────────────────────────┴───────────────────────────┐
       │  Zone 1 — per-scene parallel                          │
       │  ┌────────────────────┐    ┌─────────────────────┐   │
       │  │ spark-video-       │═══▶│ spark-video-        │   │
       │  │  screenwriter      │    │  director           │   │
       │  │ scene-NN.md        │    │ scene-NN.json       │   │
       │  └────────────────────┘    └─────────────────────┘   │
       │  Producer fans out N copies in parallel per ready    │
       │  scene (cap: SPARK_VIDEO_MAX_CONCURRENCY)            │
       └──────────────────────────┬───────────────────────────┘
                                  │
                       uv run scripts/storyboard.py compile
                                  │
                            [GATE 1: script.md]
                                  │
                            [GATE 2: storyboard.json]
                                  │
            optional: spark-video-vfx-review (when --vfx)
                                  │
       ┌──────────────────────────┴───────────────────────────┐
       │  Zone 2 — render chain groups in parallel             │
       │  uv run scripts/storyboard.py graph                  │
       │    → [[S01-001,S01-002], [S02-001], ...]              │
       │  Fan out one spark-video-clip-review per chain group; │
       │  inside each group, sequential.                       │
       │                                                       │
       │  Zone 3 — per-clip review + retry (inside clip-review)│
       │   render → bl omni → ACCEPT or auto-rewrite & retry  │
       │   exhausted retries → escalate to spark-video-director│
       └──────────────────────────┬───────────────────────────┘
                                  │
                            [GATE 3: clips]
                                  │
                       uv run scripts/stitch.py
                                  │
                            [GATE 4: final mp4]
```

## Step-by-step procedure

### Step 0 — preflight

From modelstudioai/skills, Apache-2.0.

More from modelstudioai/skills