The RenderGraph

The RenderGraph is a JSON document that fully describes a video. It is the output of Workshop's compiler and the input to Workshop's renderer. Everything between the .ws source and the final MP4 passes through this intermediate representation.

Structure

A RenderGraph contains four top-level sections:

json
{
  "version": "rendergraph.v1",
  "meta": { },
  "timeline": [ ],
  "assets": { },
  "globals": { }
}

meta — Video metadata: title, duration in seconds, aspect ratio, pixel dimensions, frame rate, mood name, and ThemePack name.

timeline — An ordered array of scene objects. Each scene contains its start time, duration, background specification, transition configuration, camera settings, and an array of element objects (text, shapes, images, charts) with their resolved positions, styles, animation keyframes, and timing.

assets — A map of asset IDs to file paths for images, logos, audio, and fonts referenced by the video.

globals — Shared settings: frame rate, mood name, tempo, and any ThemePack overrides applied during compilation.

What Gets Resolved

The compiler resolves everything ambiguous in the .ws source into concrete values in the RenderGraph:

  • mood: confident resolves to specific hex colors, font families, spring parameters, and entrance probabilities
  • size: hero resolves to a specific pixel font size at the target resolution
  • enter: rise resolves to a keyframe array with frame-level timing
  • beat 1.2s resolves to a specific frame range
  • Element stacking resolves to explicit z-index ordering
  • Text hold durations resolve from syllable counting and tempo

After compilation, the RenderGraph contains no ambiguity. Every value is concrete, every animation is a keyframe array, every position is in pixels.

Determinism

The same .ws input always produces a byte-identical RenderGraph. There is no randomness, no timestamp dependency, and no external state. This makes RenderGraphs diffable, version-controllable, and suitable for approval workflows.

Renderer Neutrality

The RenderGraph describes what to draw, not how. Workshop's native renderer (Skia + FFmpeg) consumes it, but any renderer that understands the schema could produce video from it. The browser-side preview in Workshop Studio also reads the RenderGraph to display an in-browser preview without server-side rendering.

Inspecting the RenderGraph

The compile endpoint returns the full RenderGraph. Use it to verify scene structure, element positioning, and timing before committing to a render:

bash
curl -X POST https://api.ws.video/api/compile \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{ "source": "Film \"Test\"\n  mood: calm\n\nScene \"Hello\"\n  show \"Testing\"\n    size: hero" }'

Next Steps