⚡ You are viewing the modern Pirsonal Script Reference & Cookbook (v2).
Switch to Legacy Documentation ↗
Pirsonal Logo Developer Portal Pirsonal Script
Sign In

Pirsonal Script Reference & Production Cookbook

Pirsonal Script is a declarative JSON specification for programmatically orchestrating video scenes, typography, audio layers, camera motions, and procedural transitions. It defines precisely how dynamic assets render along a 2D canvas and temporal timeline.

📐 Canvas Coordinate System

The canvas origin (0,0) sits at the top-left corner. The X-axis extends horizontally to the right, and the Y-axis extends vertically downwards.

(0, 0) Top-Left Origin ───────► +X Width (1920px)
│
▼ +Y Height (1080px)
• Landscape (16:9): 1920 x 1080
• Vertical (9:16): 1080 x 1920
• Square (1:1): 1080 x 1080

⏱️ Relative Timeline Anchors

Elements can start at absolute milliseconds (e.g. 2500) or anchor to other elements dynamically, eliminating hardcoded calculations:

  • "play": "video1.end" (starts immediately when video1 finishes)
  • "play": ["intro.start", 500] (starts 500ms after intro begins)
  • "play": "music.end - 2000" (starts 2 seconds before music ends)

⚠️ Acyclic Rule: Circular references (e.g. A depends on B, and B depends on A) are strictly rejected.

⚡ Media Inputs vs Variables ($)

It is critical to distinguish between content personalization and template structural variables:

1. Runtime Content Personalization: Supplied in the video.inputMedias array when invoking Template_Video_New (using the Barrister http property for media URLs): 
"inputMedias": [
  { "inputID": "text1", "type": "text", "text": "Alexander Hamilton" },
  { "inputID": "image1", "type": "image", "http": "https://cdn.example.com/photo.jpg" }
]
2. Template Structural Variables ($var): Used within Pirsonal Script to control animation math, coordinates, dimensions, or conditional layer visibility: 
"active": "$image1_show"
"position": { "x": "$image1_X", "y": "$image1_Y" }
"size": { "w": "$image1_W", "h": "$image1_H" }
Structural variables are passed at video generation time in the video.inputVariables array (e.g. [{"name": "image1_show", "value": "true"}, {"name": "image1_X", "value": "120"}]) and dynamically evaluated by the compiler.

✍️ Dynamic Text & Forced Line Breaks

When generating personalized text layers via inputMedias[].text, you can explicitly force multiline formatting using newline characters:

  • Use \n in JSON payloads (or \n in raw strings) to split headlines across multiple rows.
  • Text reflows automatically inside the bounding box and alignment defined in Pirsonal Studio.
"inputMedias": [
  {
    "inputID": "headline",
    "type": "text",
    "text": "Hello Sarah,\nWelcome to your Annual Review!"
  }
]

⏳ Omitted Properties & Auto-Calculated Duration

To reduce boilerplate, several properties can be safely omitted in Pirsonal Script:

  • Video & Audio duration: If omitted on video or audio objects, the rendering engine inspects the source media file and automatically calculates its exact length.
  • Dynamic Anchors: Duration can also anchor dynamically to sibling media layers (e.g., "duration": "video1.duration").
  • Default Positions: Coordinates default to {"x": 0.0, "y": 0.0} and opacity defaults to 1.0 when not specified.
🧪 In-Browser Pirsonal Script Linter & Validator

Paste your Pirsonal Script JSON below to perform client-side static analysis matching the production engine validator (VMIX3script.checkScript()). It verifies schema compliance, detects unknown types, and catches cyclic timeline graphs before submitting to the API.

Validates using PirsonalSDK.js (VMIX3script.checkScript & getInputs)

Production-Ready Cookbook Recipes

These recipes use 100% verified engine primitives, matching the canonical production recipes in Pirsonal Studio. Copy them directly into your templates or client payloads.

Text Overlaid on Dynamic Image ID: text-image

Overlays a dynamic typography layer on an image asset, scheduling the text to appear 2000ms after the image begins playback.

[
  {
    "image": {
      "id": "image1",
      "duration": 3000,
      "play": 0
    }
  },
  {
    "text": {
      "id": "text1",
      "duration": 1000,
      "play": [
        "image1.start",
        2000
      ],
      "textLines": 3
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Side-by-Side Dual Video Split Screen ID: two-videos

Plays two video tracks simultaneously side-by-side using normalized relative positioning (x: 0.0 and x: 0.50) and fractional dimensions.

[
  {
    "video": {
      "id": "video1",
      "play": 0,
      "position": {
        "x": 0,
        "y": 0.25
      },
      "size": {
        "w": 0.5,
        "h": 0.5
      }
    }
  },
  {
    "video": {
      "id": "video2",
      "play": 0,
      "position": {
        "x": 0.5,
        "y": 0.25
      },
      "size": {
        "w": 0.5,
        "h": 0.5
      }
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Smooth Coordinate Motion (moveTo Keyframe) ID: move-image

Translates image positions across horizontal coordinates linearly over 3000ms using keyframe moveTo animation events.

[
  {
    "image": {
      "duration": 3000,
      "events": [
        {
          "start": {
            "moveTo": {
              "duration": 3000,
              "x": 1,
              "y": 0.4
            }
          }
        }
      ],
      "id": "image1",
      "play": 0,
      "position": {
        "x": 0,
        "y": 0.4
      },
      "size": {
        "h": -1,
        "w": 0.25
      }
    }
  },
  {
    "image": {
      "duration": 3000,
      "events": [
        {
          "start": {
            "moveTo": {
              "duration": 3000,
              "x": 0,
              "y": 0.4
            }
          }
        }
      ],
      "id": "image2",
      "play": 3000,
      "position": {
        "x": 1,
        "y": 0.4
      },
      "size": {
        "h": -1,
        "w": 0.25
      }
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Dynamic Text Color Change Event ID: text-color

Schedules a keyframe color change at start+1000ms, transitioning typography dynamically with automatic font size fitting.

[
  {
    "text": {
      "duration": 2000,
      "events": [
        {
          "start+1000": {
            "color": "0xFFFF0000"
          }
        }
      ],
      "id": "text1",
      "play": 0,
      "textLines": 2,
      "textSizeFit": "true"
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Multi-Track Video Composition & Overlay Fade ID: video-enrichment

Layers a video background, a translucent rectangle backdrop, auto-scaling typography, and timed video fade-out at end-1000ms.

[
  {
    "rectangle": {
      "color": "0x88009CCC",
      "duration": 4000,
      "id": "lineaTexto",
      "play": 1000,
      "position": {
        "x": 0.25,
        "y": 0.25
      },
      "size": {
        "h": 0.5,
        "w": 0.5
      },
      "zIndex": 4
    }
  },
  {
    "text": {
      "duration": 5000,
      "id": "text1",
      "play": 0,
      "textSizeFit": true,
      "zIndex": 3
    }
  },
  {
    "video": {
      "duration": 4500,
      "events": [
        {
          "end-1000": [
            {
              "imageFadeOut": 1000
            }
          ]
        }
      ],
      "id": "videoInitial",
      "play": 0,
      "zIndex": 2
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Dynamic Video Trim (Final 10 Seconds) ID: video-last-ten-seconds

Trims an input video from the end using a negative time offset (mediaTrim: [{ start: -10000 }]) while preserving aspect ratio.

[
  {
    "video": {
      "id": "video1",
      "play": 0,
      "imageAspect": "preserve",
      "mediaTrim": [
        {
          "start": -10000
        }
      ]
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Dynamic Camera Zoom In / Zoom Out ID: video-zoom

Executes dynamic keyframe camera zoom, scaling into the video for 3000ms and smoothly pulling back at start+3000ms.

[
  {
    "video": {
      "id": "video1",
      "play": 0,
      "position": {
        "x": 0.4,
        "y": 0.4
      },
      "size": {
        "w": 0.2,
        "h": 0.2
      },
      "imageAspect": "preserve",
      "events": [
        {
          "start": {
            "zoom": {
              "duration": 3000,
              "factor": 1
            }
          }
        },
        {
          "start+3000": {
            "zoom": {
              "duration": 3000,
              "factor": -0.5
            }
          }
        }
      ]
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)
Conditional Template Variables & Dynamic Geometry ID: variables-example

Demonstrates template variables driving conditional layer visibility ($image1_show), coordinates ($image1_X, $image1_Y), and dimensions.

[
  {
    "video": {
      "id": "video1",
      "play": 0,
      "zIndex": 1
    }
  },
  {
    "image": {
      "id": "image1",
      "play": "video1.start",
      "duration": "video1.duration",
      "zIndex": 2,
      "active": "$image1_show",
      "position": {
        "x": "$image1_X",
        "y": "$image1_Y"
      },
      "size": {
        "w": "$image1_W",
        "h": "$image1_H"
      }
    }
  }
]
🎬
Sample Rendered Video Preview
Video preview container (MP4 / embed URL can be provided via sampleVideoUrl)

Script Properties Specification

Comprehensive list of all parameters recognized by the Pirsonal rendering compiler across video, audio, image, text, and rectangle elements.

Property Allowed Values Default Applies To Description
id String Any unique string (e.g. "video1", "text1", "image1") Required / None Video, Image, Text, Rectangle, Audio Unique identifier for the element within the script. Used to map dynamic media inputs (inputID) and relative timeline triggers.
play Integer | Array | String Milliseconds (e.g. 0, 3000), relative trigger (e.g. "image1.start", "video1.end"), or offset array (e.g. ["image1.start", 2000]) 0 Video, Image, Text, Rectangle, Audio Defines when the element begins playback along the global video timeline.
duration Integer | String | Omitted Positive integer in milliseconds (e.g. 3000, 5000), relative anchor (e.g. "video1.duration"), or omitted for audio/video Omitted (auto-calculated from source media for audio/video) | Required for static layers Video, Image, Text, Rectangle, Audio Playback duration of the element in milliseconds. For video and audio layers, duration can be safely omitted: the compositor engine automatically inspects and calculates the duration from the source media file. It can also anchor dynamically to another layer (e.g. "video1.duration").
position Object {"x": 0.0 to 1.0 or $var, "y": 0.0 to 1.0 or $var} {"x": 0.0, "y": 0.0} Video, Image, Text, Rectangle Normalized relative coordinates (0.0 to 1.0) originating from the top-left canvas corner.
size Object {"w": 0.0 to 1.0 or $var, "h": 0.0 to 1.0 or $var} (set -1 to auto-preserve aspect ratio) {"w": 1.0, "h": 1.0} Video, Image, Text, Rectangle Normalized width and height relative to canvas dimensions.
imageAspect String "preserve" | "fill" | "stretch" "preserve" Video, Image Controls how media scaling adapts to container size without distortion.
mediaTrim Array of Objects [{"start": ms, "duration": ms}] (negative start trims from end, e.g. [{"start": -10000}]) None Video, Audio Trims source media playback bounds before compositing onto the canvas.
textLines Integer Positive integer (e.g. 1, 2, 3) 1 Text Maximum allowable lines for dynamic text before wrapping.
textSizeFit Boolean | String true | false | "true" | "false" false Text Automatically calculates and fits font size to fit the container bounds.
color String Hex color format (e.g. "0xFF000000", "0xFFFF0000", "0x88009CCC") "0xFF000000" Text, Rectangle ARGB hex color definition for text typography and rectangle backgrounds.
font String PostScript font name from Pirsonal Font Library (e.g. "Lato-Regular", "Montserrat-Bold") "Arial" Text Font family applied to the typography layer.
active Boolean | String true | false | "$variable_name" true Video, Image, Text, Rectangle, Audio Dynamic condition flag. If set to a template variable (e.g. "$image1_show"), the layer only renders when the variable resolves to true.
zIndex Integer Integer >= 0 Layer index Video, Image, Text, Rectangle Visual stacking order. Layers with higher zIndex render in front of layers with lower zIndex.
events Array of Objects [{"start": {...}}, {"start+1000": {...}}, {"end-1000": [...]}] [] Video, Image, Text, Rectangle, Audio Array of procedural animation and keyframe instructions triggered at specific offsets.

Animation & Transition Procedures

Procedural animations triggered within an element's events array (e.g. [{"start": {"imageFadeIn": 500}}]).

Procedure Parameters Applies To Description
moveTo {"duration": ms, "x": float, "y": float} Video, Image, Text, Rectangle Smoothly translates layer coordinates to new (x, y) target position over the specified duration.
zoom {"duration": ms, "factor": float} Video, Image, Text, Rectangle Performs camera zoom animation. Positive factor zooms in (e.g. factor: 1), negative factor zooms out (e.g. factor: -0.5).
imageFadeIn ms (integer) or {"imageFadeIn": ms} Video, Image, Text, Rectangle Gradually ramps layer visual opacity from transparent (0) to fully visible (1).
imageFadeOut ms (integer) or {"imageFadeOut": ms} Video, Image, Text, Rectangle Gradually ramps layer visual opacity down from visible to transparent (0).
color {"color": "0xARGB"} Text, Rectangle Transitions typography or background color dynamically at a scheduled timestamp.
Copied to clipboard!