SceneWeave SDK Reference

A compact, opinionated SDK for AI-generated short-form video editing.

Getting Started

Install the adapter for your framework, point it at a Scene Graph URL, and wire two callbacks.

bashsceneweave

# Pick one
bun add @sceneweave/react
flutter pub add sceneweave
npm i @sceneweave/angular

textsceneweave

1. Initialize editor    -> editor.initializeEditor({ adapter: "iframe" })
2. Load scene graph     -> editor.loadSceneGraph(sceneGraph)
3. Load timeline        -> editor.loadTimeline(timeline)
4. Subscribe to events  -> editor.subscribeToEvents(handleEvent)
5. Update timeline      -> editor.updateTimeline(timelinePatch)
6. Start export         -> editor.startExport({ resolution: "1080p" })

Universal JSON Contract

Two JSON shapes power the SDK. SceneGraph describes intent; Timeline describes the editable result. The SDK never mutates Scene Graph directly - it derives Timeline.

Scene Graph JSONjson

{
  "contractVersion": "2026-05-21",
  "projectId": "proj_coffee_ad_001",
  "projectName": "Coffee Brand Ad",
  "sceneId": "scene_01",
  "shotId": "shot_01_A",
  "duration": 5,
  "fps": 24,
  "resolution": {
    "width": 1920,
    "height": 1080
  },
  "video": {
    "assetId": "asset_video_001",
    "url": "/mock/coffee-ad-shot.mp4",
    "prompt": "A young professional taking the first sip of coffee at sunrise"
  },
  "dialogue": {
    "character": "Narrator",
    "text": "Start your morning with clarity.",
    "emotion": "warm",
    "language": "English",
    "accent": "Neutral English"
  },
  "subtitle": {
    "text": "Start your morning with clarity.",
    "style": "cinematic_bottom"
  },
  "brand": {
    "name": "BeanCraft Coffee",
    "placement": "coffee cup visible in foreground"
  }
}

Timeline JSONjson

{
  "contractVersion": "2026-05-21",
  "timelineId": "tl_coffee_ad_001",
  "projectId": "proj_coffee_ad_001",
  "sceneId": "scene_01",
  "duration": 5,
  "tracks": [
    {
      "id": "track_video",
      "type": "video",
      "clips": [
        {
          "id": "video-1",
          "assetId": "asset_video_001",
          "start": 0,
          "end": 5
        }
      ]
    },
    {
      "id": "track_voice",
      "type": "audio",
      "clips": [
        {
          "id": "voice-1",
          "assetId": "voice_001",
          "start": 0.4,
          "end": 4.6,
          "source": "tts"
        }
      ]
    },
    {
      "id": "track_subtitle",
      "type": "subtitle",
      "clips": [
        {
          "id": "subtitle-1",
          "text": "Start your morning with clarity.",
          "start": 0.5,
          "end": 4.6,
          "style": "cinematic_bottom"
        }
      ]
    }
  ]
}

tssceneweave

export type AdapterType = "iframe" | "postMessage" | "REST" | "Flutter" | "React";

export interface SdkBridgeCommand {
  contractVersion: "2026-05-21";
  id: string;
  type: "sdk.command";
  adapter: AdapterType;
  name:
    | "initializeEditor"
    | "loadSceneGraph"
    | "loadTimeline"
    | "updateTimeline"
    | "selectClip"
    | "generateVoice"
    | "regenerateShot"
    | "startExport"
    | "subscribeToEvents"
    | "configureAIProvider"
    | "configureRenderBackend"
    | "handleError";
  payload: Record<string, unknown>;
  replyTo?: string;
}

Flutter Web Integration

dartsceneweave

final editor = SceneWeaveEditor(
  projectId: "proj_coffee_ad_001",
  adapter: SceneWeaveBridgeAdapter.iframe,
);
editor.onTimelineChanged(saveTimeline);
editor.onExportCompleted((r) => downloadMp4(r.url));

Timeline Events

timeline.created - Scene Graph successfully derived a Timeline.
timeline.updated - A clip was trimmed, reordered, or replaced.
timeline.clipSelected - A host or user selected an editable clip.
voice.generated - TTS produced a new voice asset.
shot.regenerated - A regeneration job emitted a new shot version.
export.completed - Final MP4 uploaded to CDN.
error - SDK surfaced a contract, bridge, AI, or render error.

SDK Event JSONjson

{
  "contractVersion": "2026-05-21",
  "id": "evt_001",
  "name": "timeline.created",
  "ts": "2026-05-21T09:00:00.305Z",
  "payload": {
    "projectId": "proj_coffee_ad_001",
    "timelineId": "tl_coffee_ad_001",
    "tracks": 3,
    "duration": 5
  }
}

AI Adapter Interface

Host apps configure AI providers through SDK commands while keeping credentials on the backend. The frontend receives only provider metadata and proxy endpoints.

tssceneweave

export interface AiAdapter {
  textToVideo(prompt: string, opts: ShotOptions): Promise<VideoAsset>;
  textToSpeech(text: string, voice: VoiceProfile): Promise<VoiceAsset>;
  lipSync(video: VideoAsset, voice: VoiceAsset): Promise<VideoAsset>;
  subtitles(voice: VoiceAsset, lang: string): Promise<SubtitleAsset>;
  regenerate(shot: ShotRef, prompt: string, preserve: Preserve[]): Promise<ShotVersion>;
}

tssceneweave

await editor.configureAIProvider({
  provider: "example-ai",
  proxyEndpoint: "/api/sceneweave/ai",
  capabilities: ["textToVideo", "textToSpeech", "subtitles"],
});

await editor.configureRenderBackend({
  queueEndpoint: "/api/sceneweave/render-jobs",
  webhookUrl: "https://host.example/sceneweave/render-events",
  outputs: ["mp4", "mov", "webm"],
});

AI Generation Requestjson

{
  "contractVersion": "2026-05-21",
  "requestId": "ai_req_001",
  "projectId": "proj_coffee_ad_001",
  "sceneId": "scene_01",
  "action": "regenerate",
  "prompt": "Make the lighting warmer while preserving the same character and coffee cup.",
  "preserve": [
    "character",
    "brand",
    "duration",
    "subtitleTiming"
  ],
  "inputs": {
    "shotId": "shot_01_A",
    "timelineId": "tl_coffee_ad_001"
  }
}

AI Generation Responsejson

{
  "contractVersion": "2026-05-21",
  "requestId": "ai_req_001",
  "status": "succeeded",
  "assets": [
    {
      "assetId": "asset_video_001_v3",
      "type": "video",
      "url": "/mock/coffee-ad-shot-v3.mp4",
      "duration": 5
    }
  ]
}

Render Job API

Timeline JSON

Render Manifest

Asset Fetch

Audio Mix

Subtitle Burn

MP4 Encode

CDN Upload

Export Job Lifecyclejson

{
  "contractVersion": "2026-05-21",
  "id": "exp_9F2A",
  "projectId": "proj_coffee_ad_001",
  "project": "Coffee Brand Ad",
  "status": "Completed",
  "resolution": "1080p",
  "started": "2026-05-21T09:02:00.000Z",
  "duration": "00:00:12",
  "output": "coffee-ad-v3.mp4",
  "lifecycle": [
    "queued",
    "manifest.created",
    "assets.fetched",
    "audio.mixed",
    "encoded",
    "uploaded"
  ]
}

Security & Permissions

Bearer tokens scope each project. The iframe bridge enforces origin allow-lists. Webhook callbacks are HMAC-signed with a per-project secret.

Bridge Command Envelopejson

{
  "contractVersion": "2026-05-21",
  "id": "cmd_001",
  "type": "sdk.command",
  "adapter": "postMessage",
  "name": "initializeEditor",
  "payload": {
    "projectId": "proj_coffee_ad_001",
    "sceneGraphUrl": "/api/projects/proj_coffee_ad_001/scene-graph",
    "timelineUrl": "/api/projects/proj_coffee_ad_001/timeline",
    "aiProvider": {
      "provider": "example-ai",
      "proxyEndpoint": "/api/sceneweave/ai"
    },
    "renderBackend": {
      "queueEndpoint": "/api/sceneweave/render-jobs"
    }
  },
  "replyTo": "https://app.beancraft.coffee"
}

Versioning Strategy

SemVer with an additional contractVersion field on every Scene Graph and Timeline. The SDK negotiates the highest compatible contract per project.

Architecture

App Layer

SDK Adapter

SceneWeave Core

AI Providers

Render Worker

Output Asset