Start playback on a layer. Supports video, videoPlaylist, and audioPlaylist layers.

Request Body by Layer Type

Video layers (type: "video"): Use VideoPlayRequest schema

• No file identifier needed (single file)
• Optional startFrom to seek to position
• Optional switchScene to auto-switch scenes

{ "startFrom": 30, "switchScene": false }

Playlist layers (type: "videoPlaylist" or "audioPlaylist"): Use PlaylistPlayRequest schema

• Requires exactly one file identifier: playlistItemId, fileId, or index
• The playlistItemId is recommended for precise targeting. For simple cases like playing the first file, you can use index: 0
• Optional startFrom to seek to position (video playlists only, ignored for audio)
• Optional switchScene to auto-switch scenes

{ "playlistItemId": "file_1706123456789_42", "startFrom": 30 }

File Identifiers (Playlist Layers Only)

Ambiguous Files

If a file appears multiple times in the playlist (e.g., same intro video repeated), using fileId returns a 409 AMBIGUOUS_FILE error with details about which playlistItemId values to use instead.

Scene Switching

If the layer is in a different scene than the currently active scene:

• Without switchScene: true: Returns 409 LAYER_NOT_IN_ACTIVE_SCENE with scene details
• With switchScene: true: Automatically switches to the layer's scene, then plays

Pinned layers (visible on all scenes) bypass this check entirely.

Playback Position

Use startFrom to seek to a specific position (in seconds). Works for both video and videoPlaylist layers. Ignored for audioPlaylist. Default is 0 (start from beginning).

Auto-sync

If the project has auto-sync enabled and is live, the playback change is automatically pushed to the stream.

{
  "playlistItemId": "file_1706123456789_42",
  "fileId": "507f1f77bcf86cd799439011",
  "startFrom": 30
}