Building an AI Video Editor: Reviewable Commands, State Tokens, and Browser Export

Description and use

Timeline Studio’s architecture delivers a safe, consistent AI‑video editing workflow by unifying command contracts, performing semantic validation, managing concurrency with state tokens, and sharing execution logic across browser, CLI, and MCP interfaces.

Problem

Integrating AI‑generated media and agent‑assisted operations into a browser‑based multitrack video editor while ensuring edit validity, concurrency safety, and consistent rule application across transports.

Outcome

The architecture provides a robust, agent‑friendly workflow that separates source assets from timeline clips, validates edits semantically, manages concurrency with state tokens, and unifies editing rules across multiple transports, enabling safe integration of AI‑generated media.

Workflow

• Inspect project via agent command
• Generate JSON plan with schemaVersion, project path, baseRevision, operations, and output
• Perform semantic dry run with project.diff to preview changes
• Review diff and approve plan
• Apply plan with project.run, ensuring state token matches inspected state
• Handle concurrency by rejecting stale plans and replanning if necessary
• Commit generation results to assets without auto‑insertion
• Export final timeline using deterministic offline rendering

Evidence

The local workflow is: npm run agent -- project.inspect /projects/input.timeline npm run agent -- project.diff /projects/plan.json npm run agent -- project.run /projects/plan.json

Source

We separate transport‑shape validation from project‑aware validation. A semantic dry run uses the shared command registry and state transformations to predict the actual result without writing an archive.

Source

The browser interface uses a state token to bind preparation to the inspected state. A reviewed edit receives a preview ID. Applying it checks that the editor still matches the reviewed snapshot; otherwise, the agent must inspect again and replan.

Source