Scenes & Variables

Overview

Templates in Hooked use a powerful scene-based system that allows you to create personalized videos at scale. Understanding scenes and variables is key to leveraging templates effectively.

What are Scenes?

Scenes are individual segments of your video, each with its own script and customizable overlay elements. Think of them as slides or sections in your video presentation.

Scene Structure

{
  "script": "Hello! Welcome to our presentation.",
  "variables": [
    { "key": "name", "value": "John Doe" },
    { "key": "company", "value": "Acme Corp" },
    { "key": "title", "value": "Marketing Director" }
  ]
}

Each scene contains:

script: The narration text that the avatar will speak
variables: Array of key-value pairs for text overlays displayed on the slide (names, titles, company names, etc.)

What are Variables?

Variables are dynamic text elements that appear as overlays on your video slides. They allow you to personalize each video by replacing placeholder text with specific values. Common uses:

Names and titles
Company names
Product information
Dates and numbers
Custom messages

Variable Names

✅ Valid Variable Names:

name
first_name
customer_id
subscription_plan
trial_days
product_name
company
title

Rules:

Lowercase letters
Use underscores for spaces
Descriptive names
No special characters

❌ Invalid Variable Names:

Name              // Capital letters
first name        // Spaces
customer-id       // Hyphens
1st_customer      // Starts with number
special!char      // Special characters

Creating Multi-Scene Templates

Templates can have multiple scenes, each with different overlay text:

const scenes = [
  {
    // Scene 1: Introduction slide
    script: "Hello! Thank you for joining our platform.",
    variables: [
      { key: 'name', value: 'Sarah Johnson' },
      { key: 'company', value: 'TechStart Inc' },
      { key: 'title', value: 'Marketing Director' }
    ]
  },
  {
    // Scene 2: Product information slide
    script: "Let me tell you about our product features and pricing.",
    variables: [
      { key: 'plan_name', value: 'Professional Plan' },
      { key: 'price', value: '$99/month' },
      { key: 'features', value: 'Unlimited videos, Priority support' }
    ]
  },
  {
    // Scene 3: Call to action slide
    script: "Ready to get started? Let's connect!",
    variables: [
      { key: 'website', value: 'www.techstart.com' },
      { key: 'email', value: 'sarah@techstart.com' },
      { key: 'phone', value: '+1 (555) 123-4567' }
    ]
  }
];

Variable Rules

1. Template Defines Required Variables

The template creator defines which variables are needed for each scene. When generating a video, you must provide values for all required variables.

// ❌ Will fail - template requires 'company' but it's missing
{
  script: "Welcome to our presentation!",
  variables: [
    { key: 'name', value: 'John' }
    // Missing 'company' variable that the template expects
  ]
}

// ✅ Correct - all required variables provided
{
  script: "Welcome to our presentation!",
  variables: [
    { key: 'name', value: 'John Doe' },
    { key: 'company', value: 'Acme Corp' },
    { key: 'title', value: 'Sales Director' }
  ]
}

2. Variables Are Case-Sensitive

Variable names must match exactly:

// ❌ Wrong - case mismatch
{
  variables: [
    { key: 'name', value: 'John' }  // lowercase 'name'
  ]
}
// But template expects 'Name' (capital N)

// ✅ Correct - exact match
{
  variables: [
    { key: 'Name', value: 'John' }  // matches template's 'Name'
  ]
}

3. Variables Appear as Text Overlays

Variables are displayed as text elements on the slide, not spoken in the narration:

{
  // This is what the avatar says
  script: "Let me introduce our featured product.",
  
  // These appear as text on the slide
  variables: [
    { key: 'product_name', value: 'Pro Analytics Dashboard' },
    { key: 'price', value: '$99/month' },
    { key: 'tagline', value: 'Data-driven decisions made easy' }
  ]
}

4. Empty Values Are Allowed

Variables can have empty strings if the template allows it:

{
  script: "Here's our contact information.",
  variables: [
    { key: 'phone', value: '' },  // Empty if not available
    { key: 'email', value: 'contact@company.com' },
    { key: 'website', value: 'www.company.com' }
  ]
}

Complete Example

Here’s a full example of generating a video from a template with multiple scenes:

const videoRequest = {
  type: "class",
  templateId: "template_abc123",
  title: "Onboarding Video for Sarah",
  aspectRatio: "ratio_16_9",
  caption: {
    enabled: true,
    preset: "wrap1",
    alignment: "bottom"
  },
  scenes: [
    {
      script: "Welcome to {{company}}, {{name}}!",
      variables: [
        { key: "company", value: "TechStart" },
        { key: "name", value: "Sarah" }
      ]
    },
    {
      script: "You're on the {{plan}} plan with {{feature_count}} features.",
      variables: [
        { key: "plan", value: "Professional" },
        { key: "feature_count", value: "50+" }
      ]
    },
    {
      script: "Your account manager is {{manager}}. Reach out at {{email}}!",
      variables: [
        { key: "manager", value: "Mike Chen" },
        { key: "email", value: "mike@techstart.com" }
      ]
    }
  ],
  webhook: "https://myapp.com/webhook?user=sarah"
};

// Make API request
const response = await fetch('https://api.hooked.so/v1/project/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.HOOKED_API_KEY
  },
  body: JSON.stringify(videoRequest)
});

const result = await response.json();
console.log('Project ID:', result.data.projectId);

Best Practices

Use Descriptive Variable Names

// ❌ Bad - unclear
{{x}}, {{val}}, {{a}}

// ✅ Good - self-documenting
{{customer_name}}, {{product_price}}, {{discount_percentage}}

Keep Scripts Natural

// ❌ Awkward - too many variables close together
"Hi {{title}} {{first_name}} {{last_name}} from {{company_name}} in {{city}}, {{state}}!"

// ✅ Natural - well-spaced
"Hi {{name}}! I see you're from {{company}} in {{location}}."

Validate Before Sending

Always check that:

All required variables are present
Variable names match exactly (case-sensitive)
Values are properly formatted (strings, numbers, etc.)
No extra variables are provided that don’t exist in the script

function validateScene(scene) {
  // Extract variables from script
  const scriptVars = [...scene.script.matchAll(/\{\{(\w+)\}\}/g)]
    .map(match => match[1]);
  
  // Get provided variable keys
  const providedKeys = scene.variables.map(v => v.key);
  
  // Check for missing variables
  const missing = scriptVars.filter(v => !providedKeys.includes(v));
  if (missing.length > 0) {
    throw new Error(`Missing variables: ${missing.join(', ')}`);
  }
  
  return true;
}

// Usage
try {
  validateScene(myScene);
  // Proceed with API call
} catch (error) {
  console.error('Validation failed:', error.message);
}

Common Patterns

Personalized Greeting

{
  script: "Hi {{first_name}}! Great to see you again.",
  variables: [
    { key: "first_name", value: "Sarah" }
  ]
}

Product Information

{
  script: "The {{product_name}} costs {{price}} and includes {{features}}.",
  variables: [
    { key: "product_name", value: "Pro Plan" },
    { key: "price", value: "$99/month" },
    { key: "features", value: "unlimited videos and priority support" }
  ]
}

Call to Action

{
  script: "Ready to get started? Visit {{website}} or call {{phone}}.",
  variables: [
    { key: "website", value: "www.yoursite.com" },
    { key: "phone", value: "1-800-555-0123" }
  ]
}

Troubleshooting

Error: “Variable not found in script”

Problem: You provided a variable that doesn’t exist in the script. Solution: Remove unused variables or add them to the script.

// ❌ Error - 'age' variable not in script
{
  script: "Hello {{name}}!",
  variables: [
    { key: "name", value: "John" },
    { key: "age", value: "30" }  // Not used
  ]
}

// ✅ Fixed
{
  script: "Hello {{name}}!",
  variables: [
    { key: "name", value: "John" }
  ]
}

Error: “Missing required variable”

Problem: A {{variable}} in the script doesn’t have a value. Solution: Provide all required variables.

// ❌ Error - missing 'company'
{
  script: "Hello {{name}} from {{company}}!",
  variables: [
    { key: "name", value: "John" }
  ]
}

// ✅ Fixed
{
  script: "Hello {{name}} from {{company}}!",
  variables: [
    { key: "name", value: "John" },
    { key: "company", value: "Acme Corp" }
  ]
}

Next Steps

Complete Workflow

See scenes and variables in action

Personalization

Advanced variable strategies

Bulk Generation

Generate at scale with templates

Template Example

Complete code example

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

What are Scenes?

Scene Structure

What are Variables?

Variable Names

Creating Multi-Scene Templates

Variable Rules

1. Template Defines Required Variables

2. Variables Are Case-Sensitive

3. Variables Appear as Text Overlays

4. Empty Values Are Allowed

Complete Example

Best Practices

Use Descriptive Variable Names

Keep Scripts Natural

Validate Before Sending

Common Patterns

Personalized Greeting

Product Information

Call to Action

Troubleshooting

Error: “Variable not found in script”

Error: “Missing required variable”

Next Steps

Complete Workflow

Personalization

Bulk Generation

Template Example

​Overview

​What are Scenes?

​Scene Structure

​What are Variables?

​Variable Names

​Creating Multi-Scene Templates

​Variable Rules

​1. Template Defines Required Variables

​2. Variables Are Case-Sensitive

​3. Variables Appear as Text Overlays

​4. Empty Values Are Allowed

​Complete Example

​Best Practices

​Use Descriptive Variable Names

​Keep Scripts Natural

​Validate Before Sending

​Common Patterns

​Personalized Greeting

​Product Information

​Call to Action

​Troubleshooting

​Error: “Variable not found in script”

​Error: “Missing required variable”

​Next Steps

Complete Workflow

Personalization

Bulk Generation

Template Example

Overview

What are Scenes?

Scene Structure

What are Variables?

Variable Names

Creating Multi-Scene Templates

Variable Rules

1. Template Defines Required Variables

2. Variables Are Case-Sensitive

3. Variables Appear as Text Overlays

4. Empty Values Are Allowed

Complete Example

Best Practices

Use Descriptive Variable Names

Keep Scripts Natural

Validate Before Sending

Common Patterns

Personalized Greeting

Product Information

Call to Action

Troubleshooting

Error: “Variable not found in script”

Error: “Missing required variable”

Next Steps