Agents Writing Video: `@scenerok/sdk` vs VidScript

People ask a practical question once the demo lands: should my agent write VidScript or TypeScript?

The honest answer is the one on the public @scenerok/sdk README, expanded into engineering judgment:

Use	Language
Short promos, human edits, templates	VidScript (.vid)
Loops, branches, computed timing, agents	TypeScript + @scenerok/sdk

Both emit the same intermediate timeline for preview and render. That sameness is the feature. This essay is how to choose without cargo-culting either side.

VidScript: readable intent

VidScript is for when the video wants to look like a script.

Imports pull generative providers. Inputs declare footage you already have. Time ranges place layers on a clock. Compile-time slots resolve model calls before composition. Output sets container and destination.

Why humans like it:

• You can review a diff in PR like copy, not like a graph of objects.
• Brand and motion designers can learn the shape without adopting a full TS toolchain.
• Templates stay legible: slots and parameters are obvious.

Why agents like it sometimes:

• For linear launch reels, a DSL is less rope to hang yourself.
• Fewer syntactic degrees of freedom means fewer invalid programs.
• Diagnostics map cleanly onto lines of intent.

If the job is "15s reel, hero clip, VO, end card," start in VidScript. Do not open with a framework.

SDK: when the timeline is a program

@scenerok/sdk exists because some videos are data.

Examples that outgrow a tidy .vid:

• 40 SKUs → 40 end cards with computed durations from probed media
• Branching explainer paths assembled from a CMS JSON
• Grid layouts with areas filled by loop
• Agent refactors that rearrange dozens of markers arithmetically

In TypeScript you get real control flow, real tests, real module imports, and the same toIR() exit. Public surface includes timeline construction, loadVideo / loadAudio probing helpers, text/audio factories, grid areas, transitions — see the npm README for the current API. Stay on that surface in articles; do not invent private methods for blog flair.

Agents already live in TypeScript. Giving them a first-class authoring SDK is how "write the launch video too" stops being a metaphor.

The meeting point: one IR, two authoring DX

If VidScript and the SDK drifted into different semantics, you would fork the product: preview lies depending on path; templates refuse to migrate; agents and humans cannot hand off.

So the rule is strict: authoring is plural; timeline meaning is singular.

Operational consequences:

1. Features land in IR semantics first, then in both frontends when relevant.
2. Validate before render — scenerok validate style checks apply to both (public CLI behavior).
3. Showcase examples can ship as .vid or .ts folders; forks should not surprise you at render.

This is the same lesson compilers learned decades ago: multiple languages, one machine model — here the "machine" is the timeline + render contract.

Decision guide for agent builders

Use VidScript when:

• Duration is small and mostly linear.
• A human must regularly edit the source.
• You are parameterizing a template with a handful of slots.
• You want the fewest ways to be wrong.

Use @scenerok/sdk when:

• You are generating many related scenes from data.
• Timing depends on probed media durations or arithmetic.
• You need loops, conditionals, shared libraries.
• The agent must unit-test pieces of assembly.

Use both in one shop when:

• Humans tune a VidScript template for taste.
• Agents expand parameterized campaigns in TS.
• CI validates IR equivalence on golden fixtures (qualitative goal: same structure for same intent).

Pitfalls we see (and how to avoid them)

Pitfall: SDK for everything.

You get enterprise-shaped code for a six-second bumper. Prefer the DSL until it hurts.

Pitfall: VidScript with pretend-loops.

Copy-pasting twenty near-identical blocks is a smell. Migrate that scene to TS.

Pitfall: Generative calls without pins.

Either language will burn money if every agent pass re-resolves assets. Make pinning part of the workflow, not an afterthought.

Pitfall: Teaching agents only prompts, not validate/render.

The loop is edit → validate → preview → (maybe) final. Wire MCP/CLI skills to that loop; do not stop at "emit text."

Public example shape

From the SDK README, the flavor is intentional: build a timeline, assign clips to ranges, return toIR(). From the site, VidScript shows timed ranges and compile-time generative functions side by side with brand inputs. Cloneable showcase material lives in the public GitHub showcase — fork, change a string, re-render. That loop is the pedagogy.

How agents should navigate the choice

A good agent skill does not always emit TypeScript because TypeScript is familiar. It classifies the job:

1. Parse the brief for cardinality (one video vs N variants).
2. Detect computed timing needs (probe durations, arithmetic, branches).
3. Choose VidScript for linear single-shots; SDK for data-shaped campaigns.
4. Run validate; fix type/timeline errors before preview.
5. Pin generative results before proposing a final.

If your skill always scaffolds the SDK, you will get correct-but-heavy programs. If it always scaffolds VidScript, you will get unmaintainable copy-paste. The classifier is the product.

Hand-off between humans and agents

The sweet spot we see:

• Human designs a VidScript template with clear parameters and brand constraints.
• Agent fills parameters, generates variants, opens PRs with diffs.
• Human reviews prompts and pins, not raw frames only.
• Final renders happen on accepted revisions.

When the template outgrows declarative form, a human (or agent with a migration brief) ports the skeleton to @scenerok/sdk once — then the campaign scales in TS. Migration is a deliberate event, not a surprise rewrite mid-flight.

Testing video programs

You cannot unit-test taste. You can test structure:

• Duration bounds and required layers present.
• Brand lockup occupies the right window.
• Forbidden models absent from compile plan.
• Golden IR snapshots for template fixtures (high-level idea: same authoring intent → stable structure).

Keep tests on the IR/validate layer so VidScript and SDK share them. That reinforces the peace treaty: two frontends, one meaning.

What "public surface" means for this post

Everything above stays within what you can learn from scenerok.com, the npm README for @scenerok/sdk, and the public showcase. If an API is not documented there, do not teach it in GTM essays. Longevity beats insider flex.

Closing

Agents should not "prompt a video." They should author a program that compiles into one.

Pick VidScript when clarity wins. Pick @scenerok/sdk when computation wins. Refuse a world where those choices fork your renderer.

Install the SDK from npm, open the editor or CLI path on scenerok.com, and let the IR be the peace treaty between humans and agents.