Compose Playlists

Compose Playlists are playlists of content which should be played out in order. Each Playlist Item can be sourced in multiple ways, for example, it could reference an Event in the system, or it could be a direct URL to the content. Support for a given Playlist Item Type is defined in more detail below.

There are two mechanisms for Composing a Playlist, either via a Workflow or via an Encoder. For this API reference, use of a Workflow is referred to a “Standard Composition” and use of an Encoder is “Encoder Composition”. Standard Composition will require a generation stage before the content is available for streaming, whereas Encoder Composition produces a Live Event and must follow normal Live Event operations. Crucially, Encoder Composition behaves differently and produces a different Event type, therefore separate endpoints and settings are available.

Note: The following API supports a “DateOrTime” concept, which indicates the value can be either a full DateTime (ISO8601) or just a Time (hh:mm:ss.fff).

Compose Playlist Object 

{
    "id": "3a582b0c-1632-4afc-978b-d19c8cae1cc2",
    "name": "My Playlist",
    "items": [
        {
            "type": 0,
            "value": "a7945075-a400-497d-896e-ce2163f60305",
            "properties": {},
            "markers": null
        }
    ],
    "looped": false,
    "liveStreamStart": null
}

Note: Playlist structure is generic, and therefore includes properties that may be specific to a type of Composition.

Playlist Item Type

The system supports different sources for a Playlist Item:

  • 0 = EVENT
  • 1 = DIRECT_FULL_MP4
  • 2 = DIRECT_DREF_MP4

The support for using each type does vary though, with currently standard Compose only supporting EVENT Playlist Items, and Composing via an Encoder supporting both DIRECT_FULL_MP4 and EVENT Playlist Items. Currently support for DIRECT_DREF_MP4 is not available.

Playlist Item Properties

Playlist Items can support a Properties object, which can be used to provide additional settings, and information on each item. Any properties that are not “supported” are simply returned from the API as-is.

Standard Composition Properties:

Property Supported By Value Type Notes
start EVENT DateOrTime Optional. Allows trimming of content.
end EVENT DateOrTime Optional. Allows trimming of content.
frameAccurate EVENT bool Optional. Specifies to use FrameAccuracy or not. The default is client specific.
outputDescription EVENT bool Optional.

Note: No specific Property support for Encoder Composition, although custom properties are supported.

Playlist Item Markers

Playlist Items can support a markers array, which can be used to insert SCTE-35 markers where supported.

{
  "startAt": "DateOrTime",
  "duration": "00:00:30",
  "frameAccurate": null,
  "type": 0
}

Where Type can be:

  • 0 = INSERTION - marker indicates insertion of content.
  • 1 = REPLACEMENT - marker indicates replacement of content.

Additionally, frameAccurate as in the Properties section, will match the client-specific default if not provided.

Note: Not supported by Encoder Composition.

Supported Actions

POST /compose/

Adds a standard Composition Event + Playlist.

Request Body:

{
  "event": {
    "id": null,
    "workflowId": null,
    "roomId": null,
    "eventTypeId": null,
    "categoryIds": [],
    "title": "Compose Event",
    "description": null,
    "refId": null,
    "externalId": null,
    "setPrivateAFterGeneration": false,
    "vodDrm": false
  },
  "playlist": {
    "name": "My Playlist",
    "liveStreamStart": null,
    "items": [
      {
        "type": 0,
        "value": "a7945075-a400-497d-896e-ce2163f60305",
        "properties": {},
        "markers: []
      }
    ]
  }
}

Notes:

  • id is optional but can be provided if you have a desired GUID for the Event.
  • Supported Playlist Item Types: EVENT only.
  • Providing a liveStreamStart time in the future will have the Event enter a COMPOSE_WAITING state until the stream is available.
  • liveStreamStart is something your underlying license needs to support, and if not licensed then generation will fail.

Response: 201 Created and the created Event’s GUID.

POST /compose/encoder/

Adds an Encoder Composition Event + Playlist.

Request Body:

{
  "event": {
    "id": null,
    "channelId": "54a40084-9c01-44c0-a28d-9785815e761b",
    "roomId": null,
    "eventTypeId": null,
    "categoryIds": [],
    "infrastructureProfileId": null,
    "title": "Compose Event w/ Encoder",
    "description": null,
    "refId": null,
    "externalId": null,
    "scheduledStart": null,
    "scheduledEnd": null,
    "scheduledChannelStart": null,
    "scheduledChannelEnd": null,
    "scheduledProvisionAt": null,
    "scheduledTerminateAt": null,
    "autoStart": false,
    "autoEnd": false,
    "autoPublish": false,
    "autoStartPublications": false,
    "autoProvision": false,
    "autoTerminate": false,
    "drmJson": null
  },
  "playlist": {
    "name": "My Playlist",
    "looped": false,
    "items": [
      {
        "type": 0,
        "value": "a7945075-a400-497d-896e-ce2163f60305",
        "properties": {},
        "markers: []
      }
    ]
  }
}

Notes:

  • id is optional but can be provided if you have a desired GUID for the Event.
  • channelId is required in order to validate the playlist, and that the chosen Encoder supports Composition.
  • Supported Playlist Item Types: EVENT and DIRECT_FULL_MP4.

Response: 201 Created and the created Event’s GUID.

PUT /compose/event/{eventId}

Updates a standard Composition Playlist for a Compose Event.

Request Body:

{
    "name": "My Playlist",
    "looped": false,
    "items": [
      {
        "type": 0,
        "value": "a7945075-a400-497d-896e-ce2163f60305",
        "properties": {},
        "markers: []
      }
    ]
  }

Notes:

  • Supported Playlist Item Types: EVENT only.

Response: 200 OK and the JSON containing the Compose Playlist.

PUT /compose/encoder/event/{eventId}

Adds or Updates an Encoder Composition Playlist for a Live Event.

Request Body:

{
    "name": "My Playlist",
    "looped": false,
    "items": [
      {
        "type": 0,
        "value": "a7945075-a400-497d-896e-ce2163f60305",
        "properties": {},
        "markers: []
      }
    ]
  }

Notes:

  • Supported Playlist Item Types: EVENT and DIRECT_FULL_MP4.

Response: 200 OK and the JSON containing the Compose Playlist.

PUT /compose/event/{eventId}/drm/

Set’s the DRM for the standard Compose Event.

Notes:

  • DRM for Encoder Composition is not supported here.

Response: 200 OK

GET /compose/{eventId}

Gets a Compose Playlist by Event ID.

Response: 200 OK and JSON containing the Compose Playlist object

GET /compose/clone/{sourceEventId}

Clones a Compose Playlist from a source Event to a target Event.

Query Parameters:

Name Type Required Description
targetEventId Guid Yes The target Event’s ID.

Response: 201 Created and JSON containing the Compose Playlist object

DEL /compose/{eventId}

Remove a Live Compose Playlist by Event ID.

Response: 200 OK or 400 Bad Request if the Playlist or Event does not exist.