Documentation

Complete configuration reference for DemoDSL v2.7.0

Overview

DemoDSL is a DSL-driven automated product demo video generator. You describe your demo in a single YAML or JSON configuration file covering browser automation, voice narration, visual effects, video editing, audio mixing, and multi-format export. DemoDSL then orchestrates the full pipeline to produce a polished video.

A configuration file has 10 top-level sections. Only metadata is required — every other section is optional and has sensible defaults.

metadata:        # REQUIRED — title, description, author, version
voice:           # TTS engine configuration
audio:           # Background music, voice processing, effects
device_rendering: # 3D device mockup settings
video:           # Intro, outro, transitions, watermark
subtitle:        # Subtitle overlay styles and timing
scenarios:       # Browser automation steps
pipeline:        # Post-processing chain
output:          # Export filenames, formats, social presets
analytics:       # Engagement tracking

Config Format

DemoDSL accepts both YAML (.yaml / .yml) and JSON (.json) configuration files. The format is auto-detected from the file extension.

metadata:
  title: "My Demo"
scenarios:
  - name: "Tour"
    url: "https://example.com"
    steps:
      - action: "navigate"
        url: "https://example.com"

{
  "metadata": {
    "title": "My Demo"
  },
  "scenarios": [{
    "name": "Tour",
    "url": "https://example.com",
    "steps": [{
      "action": "navigate",
      "url": "https://example.com"
    }]
  }]
}

scenarios:
  - name: "Tab Switching"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    viewport: { width: 1280, height: 720 }
    steps:
      - action: "scroll"
        direction: "down"
        pixels: 1800
        narration: "Scroll to the code example section."
        wait: 2.0
      - action: "click"
        locator:
          type: "text"
          value: "JSON"
        narration: "Click JSON tab to see JSON format."
        wait: 2.5
      - action: "click"
        locator:
          type: "text"
          value: "YAML"
        narration: "Switch back to YAML."
        wait: 2.0

metadata

The only required top-level section. Provides descriptive information about the demo.

metadata:
  title: "My Demo"

voice

Configures the Text-to-Speech engine used to generate narration audio from the narration field in steps.

voice:
  engine: "elevenlabs"
  voice_id: "josh"
  speed: 1.0
  pitch: 0

Supported Engines

Voice IDs by Engine

Each engine uses its own voice naming convention. Set voice_id to a valid identifier for your chosen engine:

voice:
  engine: "gtts"
  voice_id: "en"
  speed: 1.0

scenarios:
  - name: "Narrated Tour"
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: >
          Welcome to DemoDSL. Every step can include
          a narration field converted to speech.
        wait: 3.0
      - action: "scroll"
        direction: "down"
        pixels: 600
        narration: >
          DemoDSL supports twelve voice engines,
          from ElevenLabs to local Piper and eSpeak.
        wait: 3.0

voice:
  engine: "custom"
  voice_id: "my-voice"
  speed: 1.0

# Environment variables:
#   CUSTOM_TTS_URL=https://my-tts-server.com/synthesize
#   CUSTOM_TTS_API_KEY=sk-...          (optional)
#   CUSTOM_TTS_RESPONSE_FORMAT=mp3     (mp3 or wav)

Voice Cloning (reference_audio)

Set reference_audio to a path to your own voice recording (.wav or .mp3) and DemoDSL will clone your voice on engines that support it. This way, the narration uses your voice instead of a stock voice.

voice:
  engine: "coqui"
  voice_id: "default"
  reference_audio: "samples/my_voice.wav"
  speed: 1.0

voice:
  engine: "elevenlabs"
  voice_id: "josh"          # fallback if cloning fails
  reference_audio: "samples/my_voice.wav"
  speed: 1.0

audio

Controls background music, voice processing, and audio effects applied during the mix_audio pipeline stage.

audio.background_music

Ducking modes control how much the background music volume drops when narration is playing:

audio.voice_processing

audio.effects

audio.effects.compression

audio:
  background_music:
    file: "audio/bg.mp3"
    volume: 0.3
    ducking_mode: "moderate"
    loop: true
  voice_processing:
    normalize: true
    target_dbfs: -20
    noise_reduction: true
  effects:
    eq_preset: "podcast"
    reverb_preset: "small_room"
    compression:
      threshold: -20
      ratio: 3.0
      attack: 5
      release: 50

device_rendering Beta

Wraps the captured browser video inside a 3D device mockup frame, processed during the render_device_mockup pipeline stage.

device_rendering:
  device: "iphone_15_pro"
  orientation: "portrait"
  quality: "high"
  render_engine: "eevee"
  camera_animation: "orbit_smooth"
  lighting: "studio"

video

Controls video editing: intro/outro sequences, transitions between steps, watermark overlay, and output optimization. Processed during the edit_video pipeline stage.

video.intro

video.transitions

video.watermark

video.outro

video.optimization

video:
  intro:
    duration: 3.0
    type: "fade_in"
    text: "Product Name"
    subtitle: "v2.0"
    font_size: 60
    font_color: "#FFFFFF"
    background_color: "#1a1a1a"
  transitions:
    type: "crossfade"
    duration: 0.5
  watermark:
    image: "logo.png"
    position: "bottom_right"
    opacity: 0.7
    size: 100
  outro:
    duration: 4.0
    type: "fade_out"
    text: "Try it today!"
    cta: "Get Started"
  optimization:
    target_size_mb: 50
    web_optimized: true
    compression_level: "balanced"

Recording Quality

DemoDSL uses two recording backends depending on the browser. When browser: "chrome" is set, a high-quality CDP screenshot pipeline captures frames via a direct DevTools Protocol connection — completely bypassing Playwright's low-bitrate VP8 screencast. For WebKit and Firefox, an spp + hqdn3d deblocking filter is applied during export to smooth VP8 artefacts.

subtitle

Burns styled subtitles into the video, synced word-by-word to narration timing. Subtitles are generated as ASS files and composited via ffmpeg. Can be set at the top level (applies to all scenarios) or per-scenario.

Subtitle Styles

Each style preset configures defaults for font size, position, colors, and animation. User values always override the preset.

Style Demos

Each video below shows a subtitle style in action on short sample narration text.

subtitle:
  style: "classic"
  speed: "normal"
  font_size: 42
  position: "bottom"

subtitle:
  style: "tiktok"
  speed: "fast"
  font_size: 64
  position: "center"
  highlight_color: "#FFD700"

subtitle:
  style: "color"
  speed: "normal"
  highlight_color: "#00FF88"

subtitle:
  style: "word_by_word"
  speed: "normal"
  font_size: 56
  position: "center"

subtitle:
  style: "typewriter"
  font_color: "#00FF00"
  background_color: "rgba(0,0,0,0.8)"

subtitle:
  style: "karaoke"
  highlight_color: "#FF4444"
  position: "bottom"

subtitle:
  style: "bounce"
  font_size: 60
  position: "center"

subtitle:
  style: "cinema"
  font_family: "Georgia"
  font_size: 38

subtitle:
  style: "highlight_line"
  highlight_color: "#FFFFFF"
  font_color: "#888888"

subtitle:
  style: "fade_word"
  font_size: 50
  position: "center"

subtitle:
  style: "emoji_react"
  font_size: 52
  highlight_color: "#FFD700"

Speed Presets

subtitle:
  enabled: true
  style: "tiktok"
  speed: "fast"
  font_size: 64
  highlight_color: "#FFD700"
  position: "center"

scenarios:
  - name: "Demo"
    url: "https://myapp.com"
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "This text becomes a subtitle!"

pipeline:
  - generate_narration: {}
  - burn_subtitles: {}
  - edit_video: {}

scenarios:
  - name: "Intro"
    url: "https://myapp.com"
    subtitle:
      enabled: true
      style: "cinema"
      speed: "slow"
      font_family: "Georgia"
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "An elegant introduction."
  - name: "Features"
    subtitle:
      style: "bounce"
      speed: "fast"
    steps:
      - action: "scroll"
        direction: "down"
        pixels: 500
        narration: "Fast-paced feature showcase!"

languages

Generate multi-track audio narration and multi-language subtitles in a single render. The same scenario is recorded once, then narration is synthesised in every requested language and either embedded as additional tracks in the final MP4 or written as sidecar files (narration_{lang}.mp3, subtitles_{lang}.ass).

overview

metadata:
  title: Multilang demo

voice:
  engine: gtts
  voice_id: fr

languages:
  default: fr
  targets: [en, de]
  embed: true
  voices:
    en: { engine: gtts, voice_id: en }
    de: { engine: gtts, voice_id: de }

scenarios:
  - name: tour
    url: https://example.com
    steps:
      - narration: Bienvenue sur notre site.
        narrations:
          en: Welcome to our website.
          de: Willkommen auf unserer Website.
        action: scroll
        amount: 400

per-step translations

Each step gains an optional narrations mapping. Keys are BCP-47 language codes; values are the translated narration text. When a translation is missing, the engine falls back to the basenarration field so a partial translation never blocks the render.

steps:
  - narration: Cliquez ici pour commencer.
    narrations:
      en: Click here to get started.
      de: Klicken Sie hier, um zu beginnen.
    action: click
    target: "#start"

per-language voices

The languages.voices map lets each language use its own TTS engine, voice id, speed, etc. Any field omitted in the override inherits from the top-level voice block.

voice:
  engine: elevenlabs
  voice_id: french_voice_id

languages:
  default: fr
  targets: [en, ja]
  voices:
    en:
      engine: elevenlabs
      voice_id: english_voice_id
    ja:
      engine: openai
      voice_id: nova

embedded vs sidecar

With embed: true (default), the final MP4 contains one AAC audio track per language (with proper language= metadata, default-disposition on the source language) and one mov_text subtitle track per language. Players such as VLC, QuickTime, YouTube and Vimeo expose them as selectable tracks.

With embed: false, the engine still produces a single MP4 (default-language audio burnt-in) plus sidecar files:narration_en.mp3, subtitles_en.ass, and so on for each target language. Useful when uploading to platforms that require external caption files.

CLI usage

# Standard render — picks up languages: from the YAML
demodsl run demo_multilang.yaml

# Inspect the planned tracks without rendering
demodsl run demo_multilang.yaml --dry-run

scenarios

A list of browser automation scenarios. Each scenario captures a recording from a web application. Multiple scenarios are concatenated in the final video.

scenarios:
  - name: "Landing Page Overview"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "Scenario one: the landing page."
        wait: 2.0
      - action: "scroll"
        direction: "down"
        pixels: 800
        narration: "Scroll through features."
        wait: 2.0

  - name: "Docs Deep Dive"
    url: "https://fran-cois.github.io/demodsl/docs"
    browser: "webkit"
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/docs"
        narration: "Scenario two: the docs page."
        wait: 2.0

scenarios[].viewport

scenarios:
  - name: "Main Demo"
    url: "https://myapp.com"
    browser: "chrome"
    viewport:
      width: 1920
      height: 1080
    steps:
      - action: "navigate"
        url: "https://myapp.com"

scenarios[].cursor

Injects a visible fake cursor overlay captured in the recorded video. The cursor animates towards each target element before click/type actions and plays a visual effect on click.

scenarios:
  - name: "Cursor Showcase"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    cursor:
      visible: true
      style: "dot"
      color: "#ef4444"
      size: 20
      click_effect: "ripple"
      smooth: 0.4
    steps:
      - action: "click"
        locator:
          type: "text"
          value: "Get Started"
        narration: "Cursor moves to the button and clicks."
        wait: 2.0
      - action: "click"
        locator:
          type: "text"
          value: "Documentation"
        narration: "Smooth animation to each target."
        wait: 2.0

scenarios[].glow_select

Apple Intelligence-style animated gradient glow that highlights elements before click and type actions. The glow pulses with a rotating hue and fades out after the action.

scenarios:
  - name: "Glow Select Showcase"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    cursor:
      style: "dot"
      color: "#a855f7"
    glow_select:
      enabled: true
      colors: ["#a855f7","#6366f1","#ec4899","#a855f7"]
      duration: 0.8
      padding: 8
      border_radius: 12
    steps:
      - action: "click"
        locator:
          type: "text"
          value: "Get Started"
        narration: "Glow appears around the button."
        wait: 2.0
      - action: "click"
        locator:
          type: "text"
          value: "Documentation"
        narration: "Each element gets the glow treatment."
        wait: 2.0

scenarios[].popup_card

The popup_card mode injects styled overlay cards that appear synced with narration. When a step has a card field with a list of items, they are revealed progressively — each bullet appears one by one, timed to match the narrator.

Each step can include a card object with:

scenarios:
  - name: "Card Overlay Tour"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    popup_card:
      enabled: true
      position: "bottom-right"
      theme: "glass"
      animation: "slide"
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "Welcome to DemoDSL."
        card:
          title: "DemoDSL"
          body: "A DSL-driven automated demo generator."
          icon: "🎬"
      - action: "scroll"
        direction: "down"
        pixels: 600
        narration: "Six integrated phases."
        card:
          title: "Six Phases"
          icon: "⚡"
          items:
            - "Browser Automation"
            - "Voice Narration"
            - "Visual Effects"
            - "Video Composition"
            - "Audio Mixing"
            - "Multi-format Export"

scenarios[].avatar

An animated avatar overlay that reacts to narration audio in real time. The avatar lip-syncs to TTS amplitude and is composited on top of the video at the chosen corner. Two provider types are available: animated (free, Pillow-generated) and API-based (D-ID, HeyGen, SadTalker — paid or self-hosted).

Animation Styles (free)

These styles are available with the animated provider. Each generates a different visual animation from the narration audio waveform.

scenarios:
  - name: "Demo with Avatar"
    url: "https://myapp.com"
    avatar:
      enabled: true
      provider: "animated"
      style: "equalizer"
      position: "bottom-right"
      size: 100
      shape: "circle"
      background: "rgba(0,0,0,0.6)"
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "The avatar reacts to this narration."
        wait: 2.0

scenarios:
  - name: "Demo with Custom Avatar"
    url: "https://myapp.com"
    avatar:
      enabled: true
      provider: "animated"
      image: "https://avatars.githubusercontent.com/u/22380190?v=4"
      style: "bounce"
      position: "bottom-right"
      size: 120
      shape: "circle"
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "My avatar uses an image loaded from a URL."
        wait: 2.0

scenarios:
  - name: "Demo with Talking Head"
    url: "https://myapp.com"
    avatar:
      enabled: true
      provider: "d-id"
      image: "presenter.jpg"
      position: "bottom-left"
      size: 200
      api_key: "${D_ID_API_KEY}"
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "A real talking-head avatar powered by D-ID."
        wait: 3.0

scenarios:
  - name: "Demo with Avatar Subtitles"
    url: "https://myapp.com"
    avatar:
      enabled: true
      provider: "animated"
      style: "clippy"
      position: "bottom-right"
      size: 100
      show_subtitle: true
      subtitle_font_size: 16
    steps:
      - action: "navigate"
        url: "https://myapp.com"
        narration: "Narration text appears right below the avatar."
        wait: 2.0

subtitle:
  enabled: true
  style: "cinema"
  speed: "normal"

scenarios:
  - name: "Site Tour"
    url: "https://fran-cois.github.io/demodsl/"
    avatar:
      enabled: true
      provider: "animated"
      style: "clippy"
      position: "bottom-right"
      size: 100
      shape: "circle"
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "The avatar pulses to each narration."
        wait: 2.0
      - action: "scroll"
        direction: "down"
        pixels: 600
        narration: "Subtitles appear in cinema style."
        wait: 2.0

pipeline:
  - composite_avatar: {}
  - burn_subtitles: {}
  - edit_video: {}
  - mix_audio: {}
  - optimize: {}

steps

Steps define individual browser actions within a scenario. Each step has an action type and action-specific fields. All steps also support optional narration, wait, and effects.

Common Fields (all actions)

action: "navigate"

Navigate the browser to a URL.

- action: "navigate"
  url: "https://myapp.com/dashboard"
  narration: "Let's visit the dashboard."
  wait: 2.0

action: "click"

Click on an element identified by a locator.

- action: "click"
  locator:
    type: "css"
    value: "#submit-btn"
  narration: "Click submit."
  effects:
    - type: "highlight"
      color: "#FFD700"

scenarios:
  - name: "Click Interactions"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    viewport: { width: 1280, height: 720 }
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "Open the documentation site."
        wait: 2.0
      - action: "click"
        locator:
          type: "text"
          value: "Get Started"
        narration: "Click Get Started via text locator."
        wait: 1.5
      - action: "click"
        locator:
          type: "text"
          value: "GitHub →"
        narration: "Click the GitHub link."
        wait: 2.0

action: "type"

Type text into an input field.

- action: "type"
  locator:
    type: "id"
    value: "email"
  value: "user@example.com"
  effects:
    - type: "typewriter"
      speed: 0.1

action: "scroll"

Scroll the page in a direction.

- action: "scroll"
  direction: "down"
  pixels: 500
  narration: "Scrolling to see more features."

scenarios:
  - name: "Navigate and Scroll"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    viewport: { width: 1280, height: 720 }
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "Navigate to the target URL."
        wait: 2.0
      - action: "scroll"
        direction: "down"
        pixels: 400
        narration: "Scroll down 400 pixels."
        wait: 1.5
      - action: "scroll"
        direction: "down"
        pixels: 600
        narration: "Continue scrolling."
        wait: 1.5
      - action: "scroll"
        direction: "up"
        pixels: 300
        narration: "Scroll back up."
        wait: 1.5

action: "wait_for"

Wait for an element to appear in the DOM.

- action: "wait_for"
  locator:
    type: "css"
    value: ".dashboard-loaded"
  timeout: 10.0
  narration: "Waiting for the dashboard to load."

steps:
  - action: "navigate"
    url: "https://fran-cois.github.io/demodsl/docs"
    narration: "Navigate to the docs page."
    wait: 2.0
  - action: "wait_for"
    locator:
      type: "css"
      value: "nav a"
    timeout: 5.0
    narration: "Wait for the sidebar nav to load."
    wait: 1.5
  - action: "click"
    locator:
      type: "css"
      value: "a[href='#effects']"
    narration: "Click the effects link."
    wait: 2.0
  - action: "wait_for"
    locator:
      type: "css"
      value: "#effects"
    timeout: 5.0
    narration: "Wait for effects heading to appear."
    wait: 1.5

action: "screenshot"

Capture a screenshot of the current page.

- action: "screenshot"
  filename: "final_state.png"
  narration: "Here's the final result."

scenarios:
  - name: "Mobile Capture"
    url: "https://fran-cois.github.io/demodsl/"
    browser: "webkit"
    viewport:
      width: 390
      height: 844
    steps:
      - action: "navigate"
        url: "https://fran-cois.github.io/demodsl/"
        narration: "Load in mobile viewport, 390x844."
        wait: 2.0
      - action: "scroll"
        direction: "down"
        pixels: 400
        narration: "See the responsive layout."
        wait: 1.5
      - action: "screenshot"
        filename: "mobile_capture.png"
        narration: "Take a screenshot."
        wait: 1.0

Locator Types

Four locator strategies are available for identifying elements:

steps:
  - action: "click"
    locator:
      type: "text"
      value: "Get Started"
    narration: "Text locator: click by visible text."
    wait: 2.0
  - action: "click"
    locator:
      type: "text"
      value: "Documentation"
    narration: "Text locator: click Documentation."
    wait: 2.0
  - action: "click"
    locator:
      type: "css"
      value: "a[href='#pipeline']"
    narration: "CSS locator: jump to pipeline."
    wait: 2.0
  - action: "scroll"
    direction: "down"
    pixels: 400
    narration: "Supports css, id, xpath, and text."
    wait: 1.5

effects

43 visual effects are available, split into five categories: browser effects (11 — injected as CSS/JS during capture), cursor trail variants (6 — animated trails following the cursor), fun / celebration effects (6 — confetti-style canvas overlays), post-processing effects (7 — applied to the rendered video via MoviePy), and camera & cinematic effects (13 — advanced camera movements and cinematic post-processing). Effects are attached to individual steps.

Browser Effects (real-time JS injection)

These effects inject CSS/JavaScript into the browser during capture, creating real-time visual overlays.

effects:
  - type: "spotlight"
    intensity: 0.8
    duration: 2.0

effects:
  - type: "highlight"
    color: "#FFD700"
    intensity: 0.9
    duration: 2.0

effects:
  - type: "confetti"
    duration: 2.0
    count: 200
    colors: ["#FF6B6B", "#4ECDC4", "#45B7D1", "#FFA07A"]
    speed_min: 2.0

effects:
  - type: "typewriter"
    duration: 2.0

effects:
  - type: "glow"
    color: "#6366f1"
    duration: 2.0

effects:
  - type: "shockwave"
    duration: 1.0
    color: "#FF5722"
    max_size: 800
    glow: 20

effects:
  - type: "sparkle"
    duration: 2.0
    count: 100
    color: "#FFD700"
    max_size: 10

effects:
  - type: "cursor_trail"
    duration: 2.0
    color: "#a855f7"
    size: 22
    glow: 14
    max_dots: 80

effects:
  - type: "ripple"
    duration: 2.0

effects:
  - type: "neon_glow"
    color: "#FF00FF"
    duration: 2.0

effects:
  - type: "success_checkmark"
    duration: 2.0

Cursor Trail Variants

Six animated cursor trail styles — each follows mouse movement with a unique visual style. All are browser-injected effects.

effects:
  - type: "cursor_trail_rainbow"
    duration: 3.0
    size: 22
    hue_step: 15
    glow: 16

effects:
  - type: "cursor_trail_comet"
    duration: 3.0
    color: "rgba(168,85,247,1)"
    layers: 5
    size: 26

effects:
  - type: "cursor_trail_glow"
    color: "#00BFFF"
    duration: 3.0

effects:
  - type: "cursor_trail_line"
    duration: 3.0
    color: "rgba(168,85,247,1)"
    max_points: 80
    max_width: 10

effects:
  - type: "cursor_trail_particles"
    duration: 3.0
    count: 8
    spread: 45
    hue_base: 200
    hue_range: 80

effects:
  - type: "cursor_trail_fire"
    duration: 3.0
    sparks: 8
    hue_base: 0
    hue_range: 50

Fun / Celebration Effects

Six celebration-style canvas overlays for joyful moments. All auto-cleanup after their animation completes.

effects:
  - type: "emoji_rain"
    duration: 4.0
    count: 80
    emojis: ["🎉", "🔥", "❤️", "⭐", "🚀", "💯", "🎊"]
    speed_min: 2.0

effects:
  - type: "fireworks"
    duration: 5.0
    initial_rockets: 12
    particles_per_rocket: 80
    launch_interval: 800

effects:
  - type: "bubbles"
    duration: 4.0

effects:
  - type: "snow"
    duration: 6.0
    count: 150
    min_radius: 2
    max_radius: 10
    speed_min: 0.5
    speed_max: 3.0

effects:
  - type: "star_burst"
    duration: 3.0
    count: 100
    hue_base: 0
    hue_range: 360

effects:
  - type: "party_popper"
    duration: 4.0
    count: 80
    gravity: 0.15
    colors: ["#FF6B6B", "#4ECDC4", "#45B7D1", "#FFA07A"]

Post-Processing Effects (MoviePy)

These effects are applied to the video during the apply_effects pipeline stage.

steps:
  - action: "click"
    locator: { type: "css", value: "#cta" }
    narration: "Click the call to action!"
    effects:
      - type: "highlight"
        color: "#FFD700"
        duration: 1.5
      - type: "confetti"
        duration: 2.0
      - type: "zoom_pulse"
        scale: 1.2
        duration: 1.0

steps:
  - action: "navigate"
    url: "https://fran-cois.github.io/demodsl/"
    narration: "Effects are injected via JS during capture."
    wait: 2.0
    effects:
      - type: "spotlight"
        duration: 2.0
        intensity: 0.8
  - action: "scroll"
    direction: "down"
    pixels: 500
    narration: "Highlight adds a glowing box-shadow."
    effects:
      - type: "highlight"
        duration: 2.0
        color: "#FFD700"
  - action: "scroll"
    direction: "down"
    pixels: 500
    narration: "Glow creates an inner glow."
    effects:
      - type: "glow"
        duration: 2.0
        color: "#6366f1"
  - action: "scroll"
    direction: "down"
    pixels: 500
    narration: "Neon glow adds a vivid border."
    effects:
      - type: "neon_glow"
        duration: 2.0
        color: "#FF00FF"
  - action: "screenshot"
    narration: "Success checkmark overlay."
    effects:
      - type: "success_checkmark"
        duration: 2.0

Camera & Cinematic Effects

13 advanced camera and cinematic effects for professional-looking demos. These are all post-processing effects applied via MoviePy — they simulate real camera movements and cinematic grading on the rendered video.

Camera Movement Effects

effects:
  - type: "drone_zoom"
    scale: 1.4
    target_x: 0.5   # center horizontally
    target_y: 0.3   # focus on upper third

effects:
  - type: "ken_burns"
    scale: 1.15
    direction: "right"  # left, right, up, down

effects:
  - type: "zoom_to"
    scale: 1.8
    target_x: 0.5
    target_y: 0.4

effects:
  - type: "dolly_zoom"
    intensity: 0.3

effects:
  - type: "elastic_zoom"
    scale: 1.3

effects:
  - type: "camera_shake"
    intensity: 0.3
    speed: 8.0

effects:
  - type: "whip_pan"
    direction: "right"  # left, right, up, down

effects:
  - type: "rotate"
    angle: 3.0    # degrees
    speed: 1.0    # oscillations per clip

Cinematic Effects

effects:
  - type: "letterbox"
    ratio: 2.35   # cinemascope

effects:
  - type: "film_grain"
    intensity: 0.3

effects:
  - type: "color_grade"
    preset: "cinematic"  # warm, cool, desaturate, vintage, cinematic

effects:
  - type: "focus_pull"
    direction: "out"   # in = blur→sharp, out = sharp→blur
    intensity: 0.5

effects:
  - type: "tilt_shift"
    intensity: 0.6
    focus_position: 0.5  # 0.0=top, 0.5=center, 1.0=bottom

steps:
  - action: "navigate"
    url: "https://example.com"
    narration: "A cinematic reveal of our product."
    effects:
      - type: "drone_zoom"
        scale: 1.4
        target_x: 0.5
        target_y: 0.3
      - type: "letterbox"
        ratio: 2.35
      - type: "color_grade"
        preset: "cinematic"
      - type: "film_grain"
        intensity: 0.2
      - type: "vignette"
        intensity: 0.4

pipeline

The pipeline defines the post-processing chain using a Chain of Responsibility pattern. Each stage is a single-key dictionary. Stages execute in order, passing context to the next.

Each stage is either critical (failure stops the pipeline) or optional (failure is logged and skipped).

pipeline:
  # Each stage is a single-key dict
  - restore_audio:
      denoise: true
      normalize: true
  - restore_video:
      stabilize: true
      sharpen: true
  - apply_effects: {}
  - generate_narration: {}
  - composite_avatar: {}
  - burn_subtitles: {}
  - render_device_mockup: {}
  - edit_video: {}
  - mix_audio: {}
  - fit_duration:
      target_duration: 60
      strategy: "any"
  - optimize:
      format: "mp4"
      codec: "h264"
      quality: "high"
      target_size_mb: 50

optimize stage parameters

fit_duration stage parameters

Automatically adjusts video playback speed so that the final video matches a given target_duration in seconds. Useful when you need to produce a demo that fits a specific time slot (e.g. a 60-second social clip or a 3-minute explainer).

pipeline:
  - generate_narration: {}
  - edit_video: {}
  - mix_audio: {}
  - fit_duration:
      target_duration: 60       # make the video exactly 60 seconds
      strategy: "any"            # speed up or slow down as needed
      min_speed: 0.5             # never slower than 0.5x
      max_speed: 3.0             # never faster than 3x

output

Defines output filenames, formats, thumbnail generation, and social media export presets.

output.thumbnails

output.social

Generate platform-optimized versions automatically. Each preset re-encodes the video with platform-specific constraints.

output:
  filename: "demo.mp4"
  directory: "output/"
  formats:
    - "mp4"
    - "webm"
    - "gif"
  thumbnails:
    - timestamp: 0.0
    - timestamp: 5.0
    - timestamp: 10.0
  social:
    - platform: "youtube"
      resolution: "1920x1080"
      bitrate: "8000k"
    - platform: "instagram"
      resolution: "1080x1080"
      aspect_ratio: "1:1"
      max_duration: 60
    - platform: "twitter"
      resolution: "1280x720"
      max_duration: 140
      max_size_mb: 15

analytics Beta

Optional engagement tracking metadata embedded in the output.

analytics:
  track_engagement: true
  heatmap: true
  click_tracking: true

Pre-flight Checks

Before launching the recording browser, DemoDSL probes the URLs your scenario depends on so you find out why a recording shows a challenge or empty page before waiting for the full render. All pre-flight checks are advisory: they never abort the demo. Network failures (DNS, timeout, offline) are treated as "passing" so demos still run on locked-down machines.

Page accessibility (anti-bot / WAF detection)

Many production sites are fronted by anti-bot or WAF services that serve a JavaScript challenge or a 403/429/503 to non-browser clients. Recording such a page captures the challenge instead of your real UI. DemoDSL fetches each scenario.url and everynavigate step URL with a short GET probe (only the first 16 KB of the body) and inspects the response for known fingerprints. When a block is detected a WARNINGis logged with the protection name, the HTTP status and the matching signal — the demo still runs so the recording acts as documentation of the issue.

Detected protections include:

Sample log output for a Cloudflare-protected URL:

WARNING [page-precheck] https://example.com → not accessible · protected by cloudflare · HTTP 403 · cf-mitigated: challenge — the recorded demo is likely to show a challenge or error page. Consider using a different URL, a fixture/screenshot, or running the demo on an allow-listed network.

Recommended workarounds when a URL is blocked:

• Run the demo from an IP that is on the site's allow-list (office network, VPN).
• Replace the live URL with a static fixture, a local mirror, or a pre-recorded screenshot.
• For partner sites, ask for a User-Agent / IP exemption for the demo runner.
• If the page is only blocked for the precheck (HEAD/GET) but loads in a real browser, the warning is harmless — the recording will still succeed.

You can call the probe programmatically:

from demodsl.page_precheck import probe_page_accessible, precheck_urls

result = probe_page_accessible("https://example.com")
if not result.accessible:
    print(result.format_warning())
    # → "https://example.com → not accessible · protected by cloudflare · HTTP 403 · cf-mitigated: challenge"

# Batch probe with built-in WARNING logging
precheck_urls(["https://a.example", "https://b.example"])

Iframe embeddability (secondary windows)

When a scenario uses background.secondary_windows[].urlto embed a live site behind the main browser, DemoDSL probes each URL for headers that block iframing:

• X-Frame-Options: DENY or SAMEORIGIN
• Content-Security-Policy: frame-ancestors with a restrictive value (other than *, http:, https:)

When a window's URL is blocked, DemoDSL automatically records a short headless clip of the page in an isolated Playwright instance and substitutes a muted, looping <video> overlay for the iframe. If recording fails (or the helper is disabled), the window falls back to its background_color /screenshot. This step happens before the main browser is launched to avoid running two Chromium processes concurrently on memory-constrained hosts.

Recordings are cached on disk (keyed by URL + dimensions), so repeat runs are fast.

CLI Reference

demodsl run

Parse and execute a DemoDSL config file.

demodsl run <config> [OPTIONS]

Arguments:
  config    Path to the YAML or JSON config file.

Options:
  -o, --output-dir PATH  Output directory (default: output/)
  --dry-run              Validate and log all steps without executing
  --skip-voice           Skip TTS generation (development mode)
  --turbo                Fast preview: minimal waits, skip heavy post-processing
  -v, --verbose          Enable debug logging

Turbo mode

Add --turbo to generate a fast preview. All browser waits are clamped to 50 ms, and heavy post-processing passes are skipped: avatar compositing, 3D device rendering, subtitle burning, post-effects (freeze frames, speed ramps), global speed re-encode, and watermark overlay.

demodsl run demo.yaml --turbo

The YAML config itself does not change — turbo is purely a runtime flag. Define avatars, subtitles, and effects as usual, then iterate quickly with --turbo and remove it for the final high-quality render.

demodsl validate

Validate a config file without executing any actions.

demodsl validate <config> [OPTIONS]

Arguments:
  config    Path to the YAML or JSON config file.

Options:
  -v, --verbose    Enable debug logging

Outputs a summary: title, version, number of scenarios, total steps, and pipeline stage count. Exits with code 1 on validation failure.

demodsl init

Generate a minimal config template.

demodsl init [OPTIONS]

Options:
  -o, --output PATH   Output file (default: demo.yaml)
                      Use .json extension for JSON output.

Examples:
  demodsl init                    # Creates demo.yaml
  demodsl init -o my-demo.yaml   # Custom filename
  demodsl init -o demo.json      # JSON format

Edge Cases & Gotchas

Minimal Config

The smallest valid config requires only metadata.title. Everything else has defaults or is optional:

metadata:
  title: "Empty Demo"

This will validate successfully but produce no output (no scenarios, no pipeline).

YAML vs JSON Detection

File format is detected by file extension only: .json → JSON parser, anything else → YAML parser. If you name a JSON file config.yaml, it will fail to parse.

Voice Provider Fallback

If the configured TTS engine's API key is missing, DemoDSL falls back to DummyVoiceProvider which generates silent audio clips. The dummy calculates duration from word count at ~150 words per minute. This is intentional behavior for local development.

Pipeline Stage Format

Each pipeline entry must be a single-key dictionary. Multiple keys in one entry will raise a validation error:

pipeline:
  - restore_audio: { denoise: true }
    restore_video: { sharpen: true }  # Error!

pipeline:
  - restore_audio: { denoise: true }
  - restore_video: { sharpen: true }

Critical vs Optional Stages

If a critical stage fails (generate_narration, edit_video, mix_audio, optimize), the entire pipeline stops and raises an error. If an optional stage fails (restore_audio, restore_video, apply_effects, render_device_mockup), it logs a warning and the pipeline continues.

Effect Execution Order

Browser effects are injected before the step action and execute sequentially. If an effect has a duration, the engine sleeps for that duration before the next effect. All effects complete before the browser action fires.

Required Fields by Action

Viewport and Recording

The browser records video at the viewport resolution. For high-quality social media exports, set the scenario viewport to the maximum resolution you need — downscaling social presets is better than upscaling.

Ducking Without Music

If audio.background_music is not set or the file doesn't exist, the mix_audio stage skips music mixing entirely. Narration-only audio still works.

Empty Pipeline

If pipeline is an empty list or omitted, no post-processing runs. Raw browser recordings are copied directly to the output directory.

Multiple Scenarios

Multiple scenarios are executed sequentially. Each gets its own browser instance. Currently, the pipeline processes only the first scenario's video. Multi-scenario concatenation is handled by the edit_video stage.

Dry Run Behavior

With --dry-run, the engine validates the config, logs every step and effect with [DRY-RUN] prefix, but does not:

• Launch a browser
• Call any TTS API
• Execute pipeline stages
• Produce any output files

Environment Variables

If the required environment variable for the selected engine is not set, DemoDSL automatically falls back to DummyVoiceProvider which generates silent audio clips. This allows development without API credentials.