10. Variables#

The address "123 Oak Street" and the price "$849,000" are hard-coded in five different places across our movie. Every new listing means find-and-replace. This chapter moves those values into a variables object and references them with {{name}} placeholders. One JSON, dozens of properties.

Prerequisites: chapter 9. Variables work the same way for AI prompts as they do for plain text strings.

Step 1 — Declare variables at movie level#

The variables object lives at the top level. Keys must use letters, numbers, and underscores. Names starting with ?, $, @, %, &, or _ are reserved.

{
  "variables": {
    "address": "123 Oak Street",
    "price": "$849,000",
    "bedrooms": "4",
    "agent_name": "Jordan Lee"
  }
}

Step 2 — Reference variables in strings#

Any string field in the movie may include {{name}} placeholders that resolve at render time. Update the title card and the voice script:

{
  "type": "component",
  "component": "basic/000",
  "settings": {
    "headline": "FOR SALE",
    "subline": "{{address}}"
  }
}

{
  "type": "voice",
  "text": "Welcome to {{address}} — a {{bedrooms}}-bedroom home, listed at {{price}}.",
  "voice": "en-US-EmmaMultilingualNeural",
  "start": 1.5
}

{
  "type": "html",
  "tailwind": true,
  "wait": 0.5,
  "html": "<div class='inline-flex items-center gap-2 px-6 py-4 rounded-xl bg-emerald-700 text-white text-5xl font-bold shadow-lg'>💰 {{price}}</div>",
  "position": "bottom-right",
  "x": -60,
  "y": -60,
  "start": 4,
  "duration": 12
}

Step 3 — Scene-level variables#

Variables can also live on a scene. Scene variables override movie variables for that scene only. This is useful when the same template needs different captions per scene.

{
  "duration": 4,
  "transition": { "style": "fade", "duration": 0.5 },
  "variables": { "room_name": "Master Bedroom" },
  "elements": [
    { "type": "image", "src": "https://cdn.json2video.com/assets/images/sample-house-bedroom.jpg" },
    { "type": "text", "text": "{{room_name}}", "position": "top-left", "x": 60, "y": 60 }
  ]
}

Resolution order: scene → movie. If the same name is defined in both, the scene wins inside that scene.

Step 4 — Plug in a different property#

Change the property by editing one section, not the whole movie:

{
  "variables": {
    "address": "47 Cedar Avenue, Seattle, WA",
    "price": "$1,200,000",
    "bedrooms": "5",
    "agent_name": "Pat Morgan"
  }
}

Re-submit the same movie — the title card, voice-over, subtitles, and price tag all update.

The complete final JSON#

{
  "resolution": "full-hd",
  "variables": {
    "address": "123 Oak Street",
    "price": "$849,000",
    "bedrooms": "4",
    "agent_name": "Jordan Lee"
  },
  "elements": [
    {
      "type": "audio",
      "src": "https://cdn.json2video.com/assets/audios/uplifting-corporate.mp3",
      "volume": 0.4
    },
    {
      "type": "voice",
      "text": "Welcome to {{address}} — a {{bedrooms}}-bedroom home, listed at {{price}}.",
      "voice": "en-US-EmmaMultilingualNeural",
      "start": 1.5
    },
    {
      "type": "subtitles",
      "language": "en",
      "settings": {
        "style": "boxed-word",
        "font-family": "Inter",
        "font-size": 90,
        "font-color": "#FFFFFF",
        "outline-color": "#000000",
        "position": "bottom-center",
        "all-caps": true,
        "box-color": "#0E7C66"
      }
    },
    {
      "type": "html",
      "tailwind": true,
      "wait": 0.5,
      "html": "<div class='inline-flex items-center gap-2 px-6 py-4 rounded-xl bg-emerald-700 text-white text-5xl font-bold shadow-lg'>💰 {{price}}</div>",
      "position": "bottom-right",
      "x": -60,
      "y": -60,
      "start": 4,
      "duration": 12
    }
  ],
  "scenes": [
    {
      "duration": 4,
      "elements": [
        {
          "type": "component",
          "component": "basic/000",
          "settings": { "headline": "FOR SALE", "subline": "{{address}}" }
        }
      ]
    },
    {
      "duration": 4,
      "transition": { "style": "fade", "duration": 0.5 },
      "variables": { "room_name": "Exterior" },
      "elements": [
        { "type": "image", "src": "https://cdn.json2video.com/assets/images/sample-house-front.jpg" },
        { "type": "text", "text": "{{room_name}}", "position": "top-left", "x": 60, "y": 60 }
      ]
    },
    {
      "duration": 4,
      "transition": { "style": "fade", "duration": 0.5 },
      "variables": { "room_name": "Chef's Kitchen" },
      "elements": [
        { "type": "image", "src": "https://cdn.json2video.com/assets/images/sample-house-kitchen.jpg" },
        { "type": "text", "text": "{{room_name}}", "position": "top-left", "x": 60, "y": 60 }
      ]
    },
    {
      "duration": 4,
      "transition": { "style": "fade", "duration": 0.5 },
      "variables": { "room_name": "Master Bedroom" },
      "elements": [
        { "type": "image", "src": "https://cdn.json2video.com/assets/images/sample-house-bedroom.jpg" },
        { "type": "text", "text": "{{room_name}}", "position": "top-left", "x": 60, "y": 60 }
      ]
    }
  ]
}

Expected output#

The chapter-8 listing, but every appearance of the address or price now resolves from variables. Swap the variables block to generate a video for a completely different property — same JSON, different output. Sample render: tutorial-10.mp4 (placeholder).

What you learned#

• variables is a flat object of key: value pairs at movie or scene level.
• Reference a variable inside any string with {{name}}.
• Scene variables shadow movie variables inside that scene only.
• Variable names cannot start with ?, $, @, %, &, or _.

Previous chapter / Next chapter#

← 9. AI generated images and videos · 11. Templates →