Script Structure | Realsee Developer Platform

Info

The Realsee 3D-space script player plays back and performs script data, while VreoUnit is the smallest unit of the script data structure, used to describe audio/video, the script keyframe sequence, and other information.

Structure Composition

The basic composition of a VreoUnit is as follows:

/**
 * Script structure
 */
export interface VreoUnit {
  categoryId: string;
  categoryText: string;
  frontRequestId: string;
  index: string | number;
  keyframes: VreoKeyframe[]; // Collection of script keyframes
  video: VreoVideo; // Virtual video presenter
}

Caution

The video material must have a green-screen background.

Tip

For the detailed script structure definition: click to view.

Script Keyframes

Vreo script behavior is executed according to the script keyframes: based on the audio/video playback time sequence, once a script keyframe is hit, actions such as camera moves, panorama tags, and model effects are executed according to the keyframe's type.

A script keyframe must strictly conform to the script keyframe structure declaration in order to be correctly recognized by the player.

Info

Multiple types of script keyframes are currently supported, and new script keyframe types will continue to be refined and added to cover more behaviors.

Vreo has built-in UI and action behavior for every script keyframe. Using vreoplayer.on(), you can listen for when the corresponding script keyframe is hit and add business logic as needed.

export interface VreoKeyframe {
  uuid?: string; // Keyframe `uuid`.
  type: VreoKeyframeEnum; // Keyframe type enum
  start: number; // Trigger timestamp.
  end: number; // End timestamp
  parsed?: boolean; // Parse state
  data: Record<string, any>; // Data dependency for the current keyframe type
}

Tip

For the detailed script keyframe structure definition: click to view.

Example Data

{
  "categoryId": "257ac7a8-b00a-4a1b-88b8-76f93362c0dc",
  "categoryText": "Explaining the property floorplan",
  "video": {
    "duration": 106278, // Video length
    "start": 0, // Start timestamp
    "end": 106278, // End timestamp
    "url": "//url-host/***/xxx.mp4" // Video address
  },
  "keyframes": [
    {
      "uuid": "ac70621b-4e00-442e-311c-befb5bd3f87f",
      "type": "PanoTextLabel",
      "start": 27060,
      "end": 42351,
      "parsed": false,
      "data": {
        "text": "Drama of Life",
        "vertex": {
          "x": -0.8879207391906447,
          "y": 0.3829881941156301,
          "z": -1.8068334368800785
        },
        "fontSize": 16
      }
    }
    // ...
  ]
}