Studio Script Reference: General

context.account

Exposes the account currently being used in your project.

Type:

Object {
  id: string,
  hostname: string,
  name: string,
  producerHostname: string,
}

Example:

{
  id: '<your_account_id>',
  name: 'Account Name',
  // for end-users, behind CDN
  hostname: '<your_account_id>.cloud.easelive.tv',
  // for producers, no CDN
  hostnameProducer: '<your_account_id>-producer.cloud.easelive.tv',
}

context.bridge

Shortcut to the permanent Bridge data source. Equivalent to context.sources.Bridge.

context.configuration

Shortcut to the global Configuration data source. Equivalent to context.sources.Configuration.

context.connectivityState

Exposes the Ease Live Server WebSocket connection state.

Type: string

Example:

"connected" | "disconnected" | "connecting"

context.device

Exposes the device that the overlay is running on.

Type: object

Example:

{
    time: 1695931281212,
    width: 1325,
    height: 377,
    orientation: "landscape",
    breakpoint: {
        sm: true,
        md: true,
        lg: true,
        lgAndDown: true
    },
    hasNotch: false,
    ip: "::ffff:0.0.0.0",
    safeArea: {
        top: "0px",
        right: "0px",
        bottom: "0px",
        left: "0px"
    },
    info: {
        active: true,
        type: "desktop",
        os: {
            name: "macos",
            version: "10.15.7"
        },
        keymapping: {},
        orientation: "landscape",
        model: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
        sdk: "web-1.15.6",
    }
}

context.functions

Gives access to all the function sets in a given context, by name.

Example:

context.functions['My functions'].functionName('arg1', 'arg2');

context.getSource()

Allows you to lookup a data source using the name of the source. It's the function equivalent of context.sources.MySource.

Type: object

Example:

context.getSource('MySource').myProp
// => "My value"

context.params

Exposes any query parameters from the Ease Live overlay URL. Query params that have been defined in Settings -> Data sources -> Query parameters will also be type casted and have default values.

Type: Object { [key: string]: string | int | boolean }

Example:

{
  "myCustomProp": "My value",
  // These are built-in query params:
  "accountId": "tutorials",
  "projectId": "6c92994c-6b17-4905-8481-e09cd779a72c",
  "programId": "e6c5b13a-2fd8-40e3-9d65-4d1062da075f",
  "server": "tutorials.cloud.easelive.tv",
  "loaderTimeout": 30,
}

context.player

Exposes everything Ease Live knows about the video player's current state.

Type: object

Example:

{
  time: 0,
  speed: 1,
  volume: 100,
  mute: false,
  state: 'playing',
  controls: 'hidden',
  videoScale: undefined,
}

context.packageConfiguration

Exposes the data from the Package Configuration data source for the current package context. Only available in scripts running inside a published package.

context.programs

Exposes all programs available to the overlay, keyed by program ID. The main program is always available under 'main'.

Type: object

Example:

context.programs.main.id
// => 'e6c5b13a-2fd8-40e3-9d65-4d1062da075f'

// Access a specific program by ID:
context.programs['e6c5b13a-2fd8-40e3-9d65-4d1062da075f'].states

context.project

Exposes the current project's metadata.

Type: object

Example:

{
  id: '6c92994c-6b17-4905-8481-e09cd779a72c',
  name: 'My Project',
  metadata: {
    timecode: {
      offset: 0
    }
  }
}

context.sources

Gives access to all of the data sources in a given context, by name.

Type: object

Example:

// Set a property value:
context.sources.MyState.someProp = 123;

// Data sources with spaces in the name need brackets:
context.sources['Menu state'].state = 'visible';

context.timecode

Exposes the current timecode state for the overlay, driven by the player or an external timecode source.

Type: object

Example:

{
  time: 12500,         // current timecode in ms
  state: 'playing',    // 'playing' | 'stopped'
  speed: 1,            // playback speed
  running: true,       // whether timecode interpolation is active
  hasTimecodes: true,  // whether timecodes have been received
  offset: 0,           // timecode offset in ms (read/write)
  enabled: true,       // whether timecodes are enabled (read/write)
}

The offset and enabled properties can be set directly from a script. Setting them locks their value for the rest of the session, overriding any values from the project or program metadata.

// Read the current offset
const offset = context.timecode.offset;

// Set a custom offset (in ms)
context.timecode.offset = 5000;

// Disable timecodes
context.timecode.enabled = false;

context.use()

To avoid conflicts, installing a package places its contents in a separate context. context.use() lets you access them, using their unique namespace.

To find a package's namespace, select any of its data sources or functions. The full syntax for accessing the selected data source or function will be displayed at the top.

Example:

// Activate the Watch Party package's sidebar:
context.use('packages.wp').functions.Sceenic.Activate();

context.user

Exposes the info we have about the end-user loading in the overlays.

Type: object

Example:

{
  // It can be passed to the overlay with the `userId`
  // query param, or be auto generated by Ease Live if missing.
  id: '3ac5d0fc-bbb7-4513-9f2a-99093e95598f',
  // Set to `true` if the user has interacted with
  // anything that has a click/gesture trigger on it.
  isActive: true | false,
  // The timezone configured in the user's browser.
  timezone: 'Europe/Oslo'
}

List of available tz database time zones.

context.utils

Provides utility helpers scoped to the current context. See Response utilities for the full API reference.

Example:

// Check if the user can respond to a poll
const canVote = context.utils.responses.canRespond('My poll', context.event?.id);

context.setUser

Sets a new User ID. It will be persisted, and be the new User ID across sessions from now on.

Type: function

Example:

context.setUser('my-custom-user-id');

console.log(context.user.id);
// Outputs: my-custom-user-id