Your First Video

This guide walks through writing a complete .ws script — a three-scene product launch video. By the end, you will understand Film blocks, scenes, text elements, sequencing, and how mood shapes everything.

The Film Block

Every .ws file starts with a Film block. This sets global properties for the entire video.

text
Film "Product Launch"
  mood: confident

Film "Product Launch" names your video. The mood: confident line selects the visual identity — confident uses dark backgrounds, clean white text, structured animation, and medium energy.

You can also set aspect ratio, tempo, and language:

text
Film "Product Launch"
  mood: confident
  aspect: 16:9
  tempo: measured
  language: en

These are all optional. Workshop defaults to 16:9, measured tempo, and English.

Adding Scenes

Scenes are the screens of your video. Each Scene block becomes a distinct visual moment with its own entrance, hold, and exit.

text
Scene "Problem"
  show "Your tools are slowing you down."
    size: title
    enter: rise

show "text" places a text element on screen. The size modifier controls visual weight (from smallest to largest: caption, body, subhead, title, display, hero). The enter modifier controls how the element appears — rise slides it up from below.

Sequencing Elements

Within a scene, you control when elements appear relative to each other.

Sequential — the default. Each show waits for the previous element to finish.

text
Scene "Solution"
  show "Not anymore."
  show "Meet Apex."
    size: hero

Explicit sequential — then show makes the ordering intention clear.

text
Scene "Solution"
  show "Not anymore."
  then show "Meet Apex."
    size: hero

Simultaneous — with show makes an element appear at the same time as the previous one.

text
Scene "Intro"
  show "Welcome"
    size: hero
  with show "to the future."
    size: subhead

Pauses — beat inserts a timed pause between elements. The audience needs a moment to absorb what they just read.

text
Scene "Solution"
  show "Not anymore."
  beat 1.2s
  show "Meet Apex."
    size: hero

Emphasis and Color

Highlight specific words with emphasis, and use semantic color names to match the mood.

text
show "Meet Apex."
  size: hero
  emphasis: "Apex"

The emphasized word gets a different weight or color treatment, depending on the mood.

For color, use semantic names rather than hex values — they adapt to the mood automatically:

  • primary — the main text color
  • accent — the mood's highlight color
  • muted — subdued secondary text
  • contrast — maximum contrast against the background
text
show "Start free at apex.dev"
  size: display
  color: accent

The Complete Script

Putting it all together — a three-scene product launch video:

text
Film "Product Launch"
  mood: confident

Scene "Problem"
  show "Your tools are slowing you down."
    size: title
    enter: rise

Scene "Solution"
  show "Not anymore."
  beat 1.2s
  show "Meet Apex."
    size: hero
    emphasis: "Apex"

Scene "CTA"
  show "Start free at apex.dev"
    size: display
    color: accent

Compiling and Rendering

Send the script to the API to compile and render:

bash
curl -X POST https://api.ws.video/api/render \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "source": "Film \"Product Launch\"\n  mood: confident\n\nScene \"Problem\"\n  show \"Your tools are slowing you down.\"\n    size: title\n    enter: rise\n\nScene \"Solution\"\n  show \"Not anymore.\"\n  beat 1.2s\n  show \"Meet Apex.\"\n    size: hero\n    emphasis: \"Apex\"\n\nScene \"CTA\"\n  show \"Start free at apex.dev\"\n    size: display\n    color: accent"
  }'

Poll the returned jobId and download the MP4 when complete. See the Quickstart for the full poll-and-download flow.

If you want to inspect the compiled output before rendering, use POST /api/compile instead. This returns the RenderGraph JSON and diagnostics without queuing a render job.

## What the Compiler Did

The confident mood resolved to specific design decisions: Inter font family, -0.02em letter spacing, dark navy background (#0F172A), white primary text, blue accent, 0.5s fade entrances, spring-based physics with medium tension. The timing engine counted syllables in your text and calculated hold durations. The layout solver centered elements. None of this was specified in the script — the mood handled it.

Change mood: confident to mood: playful and you get warm colors, bouncy springs, casual typography, and faster animation. Same script, completely different feel.

Next Steps