Update layer properties and settings. All fields are optional — send only what you want to change.

Supports three layer types: video, videoPlaylist, and audioPlaylist.

Settings by Layer Type

Not all settings fields apply to every layer type. Use this table to see what's available:

See the schema below for full field details, types, and constraints.

Behavior Notes

Partial updates: Only send fields you want to change. Existing values are preserved — including nested textStyles.

Changing a video file (fileId): The file must be a video owned by you. Playback state is reset (isPlaying, duration, etc.).

Replacing playlist files (files): Updating the files array resets all playback state. Behavior depends on whether the layer is currently active:

• Active scene (currently playing): Playback stops immediately. Call the Play endpoint to resume (e.g., { "index": 0 } for the first file).
• Inactive scene (not currently playing): Playback will auto-start from the first file when the stream switches to that scene. No additional action needed.

loop vs nextScene: These are mutually exclusive. Setting nextScene auto-disables loop. Enabling loop while nextScene is set returns LOOP_NEXT_SCENE_CONFLICT — set nextScene: null first.

Position coordinates: Use the project's current resolution — full frame is format.resolution from Get project details (for example 1920x1080 for 16:9_1080p).

Auto-sync: If the project has auto-sync enabled and is live, changes are automatically pushed to the stream. The response includes synced: true/false.

{
  "settings": {
    "fileId": "507f1f77bcf86cd799439012",
    "adPlaceholder": {
      "fileId": "507f1f77bcf86cd799439012"
    }
  }
}

{
  "layer": {
    "id": "507f1f77bcf86cd799439011",
    "type": "videoPlaylist",
    "name": "My Video Playlist",
    "hide": false,
    "pinned": false,
    "locked": false,
    "position": {
      "x": 0,
      "y": 0,
      "width": 1920,
      "height": 1080
    },
    "settings": {
      "volume": 10,
      "loop": true,
      "nextScene": null,
      "showFileName": true,
      "showProgressBar": false,
      "shuffle": false,
      "namePosition": "bottom left",
      "adPlaceholder": {
        "enabled": true,
        "fileId": "507f1f77bcf86cd799439012",
        "fileName": "placeholder.mp4",
        "duration": 30
      },
      "files": [
        {
          "playlistItemId": "file_1706123456789_0",
          "fileId": "507f1f77bcf86cd799439012",
          "name": "video1.mp4",
          "duration": 60.5,
          "isPlaying": true
        },
        {
          "playlistItemId": "file_1706123456789_1",
          "fileId": "507f1f77bcf86cd799439013",
          "name": "video2.mp4",
          "duration": 45,
          "isPlaying": false
        }
      ]
    }
  }
}