video-production

Files (6)

• SKILL.md
• clip_qa.py
• composition.md
• consistency.md
• failure-modes.md
• tasks.json

SKILL.md (first lines)

# video-production

**Core principle: control is everything.** Every guard-rail you put in front of the engine is drift you do not pay for later. Lock the shape, the cast, the location and the words before spending, then gate every clip on evidence rather than impression.

This skill covers **composing gflow into a finished video**. It does not restate the command surface — that is the [`gflow-cli` skill](../gflow-cli/SKILL.md), which owns per-command syntax, flags and single-shot recipes. Load that one for "how do I call `t2v`", this one for "how do I turn a script into a film that holds together".

## How to read the claims in this skill

Every non-obvious statement is tagged. **This is one calibrated approach, not the only one.** Other people drive this engine with techniques not tracked here; absence from this document means untested, never forbidden.

| Tag | Meaning | You may |
|---|---|---|
| **[CONSTRAINT]** | the engine refuses, fails, or silently drops the request | not deviate |
| **[CALIBRATED]** | measured here, sample size and conditions stated | deviate with evidence |
| **[CONVENTION]** | one shape that works; alternatives exist | deviate freely |
| **[UNEXPLORED]** | known to exist, not tested here | try it, then add a task |

## When NOT to use this skill

A single clip with no continuity requirement, one image, or a pure command-syntax question — use the `gflow-cli` skill. Editing or grading existing footage — this is generation, not post. Any engine that is not Flow.

## Prerequisites

**Everything gflow** — Python 3.11+, `uv`, an installed `gflow`, Playwright Chromium, a signed-in profile, Flow access — belongs to the [`gflow-cli` skill](../gflow-cli/SKILL.md)'s Prerequisites. Run its checks; do not restate them.

This skill adds three:

1. **`ffmpeg` and `ffprobe` on PATH, 5.0 or newer** — `ffmpeg -version`. The assembly step uses `-fps_mode`, which does not exist before 5.0.
2. **An ffmpeg carrying `libass` and `libfreetype`** — the same banner lists enabled libraries. Burned subtitles (`subtitles`) and title cards (`drawtext`) are absent from minimal or "essentials" builds. Usual Windows trip.
3. **`faster-whisper`, only if you want the transcript gate** — `python -c "import faster_whisper"`. **Nothing in gflow installs it.** First run pulls `base.en`, ~75 MB, once. Without it you lose the word-hit check and keep every other gate.

`clip_qa.py`, beside this file, needs **only ffmpeg, ffprobe and the standard library** — so the fluidity, lip-sync and A/V-drift gates still run where the transcript gate cannot.

## Step 1 — intake, before anything else

The plan changes completely with the answers. Ask, or read them from the brief; do not assume.

| Question | Why it changes the plan |
|---|---|
| What is the deliverable, and who watches it? | a rehearsal reference tolerates flaws a client cut does not |
| Does anyone speak **on camera**? | decides dialogue budgeting, lip-sync gating, and i2v-vs-r2v |
| Is audio generated, added later, or discarded? | Veo always generates audio **[CONSTRAINT]** — see below |
| Captions: none, burned-in, or a sidecar file? | burned-in needs `libass` and a timing source |
| One location or several? How many camera angles each? | drives the plate-chaining work in `consistency.md` |
| Recurring people? How many in frame at once? | one face-bearing reference per generation **[CONSTRAINT]** |
| A prop that must not change? | needs its own sheet with a scale anchor |
| Aspect, total length, credit ceiling | 16:9 or 9:16; clips are 4/6/8, or 10 on omni-flash |
| One-off, or a repeatable pipeline? | decides the production shape in `composition.md` |

**Veo always generates audio [CONSTRAINT].** There is no silent mode and omitting sound from the prompt does not produce silence. A "silent" montage returns invented room tone under every shot. If the audio is unwanted, strip it at assembly (`-an`) rather than hoping for a quiet clip.

## Step 2 — check the host, or the whole plan is dead

Load `https://labs.google/fx/tools/flow/project/<id>` in the profile's Chrome and read the **final** URL.

| Lands on | Lane | What runs there |
|---|---|---|
| `labs.google/fx/…` | **A, full** | everything |
| `flow.google.com/project/…` | **B, partial** | `video t2v --project`, `video i2v --initial-frame <local file> --project`, **`video r2v --ref <local file> --project`** (ported in v0.70.0, #683; a named character with `--reference-entity` + `--reference-entity-name` since v0.91.0, #723), and **`image t2i` / `image i2i` with local `--ref` files (#639)**, and **`video extend` for ONE segment** (#882; `-n` > 1, `--scene`/`--resume-from`, `--seed` and an `--aspect` other than the source's exit 36). `character create` worked there from v0.70.0 until its labs route was retired: since 2026-10-14 it exits 7 on a profile served flow.google.com. Everything else — `image batch`, multi-segment `extend`, `scene create`, `movie run`, r2v by `@Name` or `--reference-entity`, i2v by media UUID / `@Name`, and Imagen 4 — exits 36 **[CONSTRAINT]**. A **local** `--end-frame` IS ported (start+end interpolation, #639) |

Lane B grows as forms are ported, so **confirm the row rather than trusting it**: the
maintained list is [CONFIGURATION § `GFLOW_CLI_FLOW_HOST`](https://github.com/ffroliva/gflow-cli/blob/main/docs/CONFIGURATION.md#gflow_cli_flow_host)
and the [#639 entry in KNOWN_ISSUES](https://github.com/ffroliva/gflow-cli/blob/main/KNOWN_ISSUES.md). Exit 36 on a form the table
says is ported is a regression worth filing, not the environment.

An unported command on lane B exits **36**, non-retryable, with a message naming the
migration. A `RecaptchaError` instead means one of two other things: on gflow ≤ 0.68.0 the
migration guard ran *after* the reCAPTCHA mint on the image path, so image commands died
as exit 1 there (gflow-cli#673, fixed); on any build, a `RecaptchaError` right after
`gflow auth login` is the cookie harvest keyed on the old host (gflow-cli#644). Either
way the first move is the same: **read the final host URL before anything else.** Do not
plan entities or plates before this check.

**There is a `gflow project create` [CONSTRAINT].** `gflow project create --name <piece> --json > out.json`, redirected to a file, never piped through `head`, which truncates the process before the JSON prints. Do not mint a project by burning a placeholder generation, and do not scrape the id from a browser URL.

## Step 3 — the production shape

Pick one; each has a worked command chain in **[`composition.md`](composition.md)**.

| Shape | When | Driver |
|---|---|---|
| One-off sequence | a scene, an audition, a montage | shell, clip per beat |
| Manifest-driven | a script that will be re-run as it is edited | `movie run` with a stable scene id per slot |
| Continuous shot | one camera move longer than 8 s | `video extend` |
| Deliberate cut with continuity | a new angle that must match the last frame | `video chain` |
| Assembly only | clips already exist | `scene create` (free) |

## Step 4 — lock the assets before spending

### 4a. The identity resolution ladder — deterministic, and you record the rung

A person in a shot is anchored by exactly one of these. **Take the highest rung the host
and path allow, and write down which rung you used and what blocked the one above.** This
is not a preference order, it is the production record: a film whose log does not say how
each shot was anchored cannot be debugged when a face drifts.

| # | Anchor | What it carries | Use when |
|---|---|---|---|
| **1** | **Character entity** — `@Name` or `--reference-entity <id>` | face **and** wardrobe **and** voice, server-side, durable | always, unless a rung-1 blocker is recorded |
| **2** | **That entity's own generated plate** — `--ref <its portrait or body crop>` | face and wardrobe, as a flat image | rung 1 refused by the host/path |
| **3** | **A plate cut from an approved take** — `--ref <frame>` | face, plus that take's grade, light and artefacts | no entity exists |
| **4** | **Prose canon only** | a *type*, never an identity | nothing else is available |

**Rung 4 does not hold a person.** Each generation invents someone new who merely matches
the description. Two shots on rung 4 are two different actors. Never plan a multi-shot
piece on it and never let it be the silent default.

**Rung 3 carries contamination.** v1's opening take came back with 72 px letterbox bars and
its plate carried those bars into every shot that referenced it. A rung-2 plate is generated
clean by the character editor; a rung-3 plate is only as clean as the take it was cut from.

**Descending a rung is a decision that gets written down**, in `production.json` next to the
shot, naming the blocker. "I used an image" is not a record; "rung 2, because
`--reference-entity` on t2v exits 36 on this host (#716)" is.

> **Written from a run that skipped its own ladder.** On 2026-09-07 a five-shot film created
> two real character entities and then anchored every shot on rung 2, because gflow refuses
> entity references on the migrated host. The refusal was never questioned — and a $0 probe
> the same day showed the host takes an entity mention perfectly well

From ffroliva/gflow-cli, MIT.

More from ffroliva/gflow-cli