Introduction

The Video Studio SDK ("VSDK") is an embeddable, composable React video editor. You mount one provider in your app, optionally pass it a saved project bundle and a few callbacks, and you get the full editor — timeline, player, inspector, animation, undo/redo, transitions, masking — running inside your product. Everything else (asset storage, persistence, server-side rendering) is yours to wire up through callbacks and plugins.

What VSDK ships

Under the hood: Zustand + Immer for state, mitt for events, Remotion 4 for rendering, dnd-kit for timeline drag-and-drop, react-moveable for transform handles, Tailwind v4 for styles, Base UI + Radix for primitives.

What's actually in the editor

• Timeline: tracks, items, transitions, markers, regions, snap engine, zoom & pan, ruler, drag-and-drop, ripple insert/delete, split, trim, nudge, multi-selection.
• Inspector: properties for transform / style / filters / animation / masks, with plugin-contributed sections that can target a specific itemType (text, image, video, audio, captions, overlay, adjustment).
• Player: Remotion-backed preview, playback rate, mute, scrubbing, frame-accurate seek, live animation playback.
• Animation system: per-property keyframes with easing functions, animatable properties for image / video / text plus a registry so plugins can add their own.
• Transitions: built-in fade / wipe / push primitives + a registry so plugins can add custom transitions.
• Masking system: rectangle, ellipse, polygon, split, and filmstrip masks with feather, expansion, and combine modes — on image and video items.
• History: 100-entry command-based undo/redo, batch commands, deterministic replay.
• Save & Export: serialize the entire project to a ProjectBundle JSON; an onExport callback that drives the SDK's progress UI while your backend renders.
• Theming: a 12-step studio gray palette + accent + semantic surface/border/text tokens that flow into Shadcn semantic tokens, all overridable at runtime per-mode.
• Icons: a complete StudioIconMap (~60 keys) every icon in the editor resolves through. Override one or all; plugin icons join the map.
• Hotkeys: SDK-wide defaults (Space, Cmd+Z, Delete, …) plus a plugin-registration API.
• License: a license overlay system gated on a runtime licenseKey prop, with a host-overridable validation server URL.
• Responsive: desktop / mobile layout with dedicated mobile shell, bottom sheets, swipe gestures, all switched automatically by viewport width.

What you bring

• A React 19 (or ≥ 18) application. The example app under examples/nextjs uses Next.js App Router and is the reference setup.
• A ProjectBundle to load — or let the editor create an empty one.
• Persistence: implement onSave(bundle) to write to your backend.
• Export: implement onExport(payload) to start a render job and call back into the store actions (setExportProgress, setExportCompleted, setExportFailed) as your backend reports progress.
• A license key for production use (set via licenseKey on the provider).

Everything else is optional — adapters for stock media, GIFs, fonts; plugins for filters, masking, typography; your own panels and inspector sections.

Mental model in one screen

Every UI surface — including plugin-contributed panels, inspector sections, toolbar buttons, context menu items, and hotkeys — runs inside that provider tree and has access to the store through hooks.

How a user action flows through the SDK

A button click, a drag-and-drop, a keystroke — they all funnel through the same path. Internalising this is the single highest-leverage thing you can do as an SDK consumer:

User action (click / drag / hotkey)
        │
        ▼
Store action (addItem / moveItem / updateItemProperties / …)
        │
        ▼
Command object built (execute fn + undo fn)
        │
        ▼
executeCommand(command)
   ├── runs execute(draft) inside Immer
   ├── pushes the command onto the undo stack (max 100)
   ├── clears the redo stack
   └── sets project.isDirty = true
        │
        ▼
Event emitted on the typed event bus (item:added, item:moved, …)
        │
        ▼
React components re-render via useStudioStore selectors
Plugin code listening on the bus runs side effects (analytics, autosave, …)
        │
        ▼
User clicks Save → onSave(bundle) → your backend persists
User clicks Export → onExport(payload) → your backend renders → callbacks drive the UI

Every page in this section is some slice of that flow. Read in the order below for a top-down tour, or jump to whichever piece you're working on.

A 0-to-100 reading order

The SDK is big enough that "read everything" isn't realistic. Here's a staged reading order that gets you productive at each level.

Stage 1 — Mount the editor (15 minutes)

You'll have a working editor with default settings.

Stage 2 — Configure it for your product (1–2 hours)

You'll have an editor branded for your app, wired to your backend.

Stage 3 — Read state and react to changes (half a day)

You'll be able to inspect, mutate, and react to anything inside the editor.

Stage 4 — Extend it with your own surfaces (1–2 days)

You'll have your own panels, inspectors, toolbar actions, and hotkeys.

Stage 5 — Push the boundary (week+)

You'll deploy a renderer, ship a published plugin, contribute to the catalog.

Where this leaves you

By the end of Stage 1 you have an editor. By the end of Stage 2 your users can't tell it isn't yours. By Stage 3 you're reacting to and mutating the editor like a native developer. By Stage 4 you're extending the editor's UI surface. By Stage 5 you're shipping infrastructure (cloud rendering, catalog plugins) alongside the editor itself.

The sections that follow take it from here.