Live Playout Profiles

All POST and PUT calls require the Content-Type header to be set to application/json

All actions require the appropriate Live Playout Profile feature permissions

Live Playout Profile object

Property Type Notes
id GUID string  
configurationJson string Escaped JSON
name string  

Origin Manifest Sync Result object

Property Type Notes
profileId GUID  
eventId GUID  
success bool  
errors string[]  

Updating or deleting a Live Playout Profile will perform a sync operation for Events associated with the Profile where the Event’s state is any one of the Playout States.

The sync operation creates/updates/removes playout manifests on the origin server(s) specified in each Event’s Channel configuration.

Any actions which perform these operations return an array of Origin Manifest Sync Result objects, indicating which Profile/Event combinations had a sync operation performed and whether each operation succeeded or not.

Failure to sync origin manifests do not fail the request, and will still yield a 200 OK status code to indicate that the data in the VIS successfully updated. Callers should check the response bodies of these requests to know about partial or total failures of these sync operations.

Event Playout States

  • LIVE_UNPUBLISHED
  • LIVE_PUBLISHED
  • STOPPED
  • SUSPENDED
  • INSTANT_VOD
  • INSTANT_VOD_BACKUP

These EventStates are considered “Playout States”, where the Publishing Point should exist for the Event on the origin server(s) specified in the Event’s Channel configuration.

When an Event transitions into any of these states, playout manifests are created on the origin server(s) for the collection of Live Playout Profiles associated with the Event.

When an Event is in any of these states, the playout manifests for the collection of associated Live Playout Profiles should exist on the origin server(s) and any updates to such Live Playout Profiles are reflected automatically in the playout manifests.

When an Event transitions out of these states, the playout manifests created for the associated Live Playout Profiles are automatically removed.

Playout Profile configuration JSON

This is an example using only DRM CENC and limiting the tracks available in the stream manifests.

{
  "manifestFile": "/playout/pc01/{0}/cenc.isml",
  "allowedPublishingPoints": [
    "/live/pc01/{0}/{0}.isml"
  ],
  "mp4splitOptions": "--archive_segment_length=600 --archiving=0 --dvr_window_length=30 --restart_on_encoder_reconnect --iss.disable --hds.disable --hls.disable",
  "drm": {
    "drm_provider": "VUALTO",
    "drm_data": [
      {
        "name": "CENC"
      }
    ]
  },
  "tracks": [
    {
      "kind": "video",
      "criteria": {
        "MaxWidth": 416,
        "MaxHeight": 234
      }
    },
    {
      "kind": "video",
      "criteria": {
        "MaxWidth": 480,
        "MaxHeight": 270
      }
    },
    {
      "kind": "video",
      "criteria": {
        "MaxWidth": 640,
        "MaxHeight": 360
      }
    },
    {
      "kind": "video",
      "criteria": {
        "MaxWidth": 764,
        "MaxHeight": 432
      }
    },
    {
      "kind": "video",
      "criteria": {
        "MaxWidth": 960,
        "MaxHeight": 540
      }
    },
    {
      "kind": "audio"
    },
    {
      "kind": "textstream"
    }
  ],
  "outputUrls": [
    {
      "streamProtocol": "DASH",
      "liveCdnPrimaryUrl": "https://{CDN-Address}/playout/pc01/{0}/cenc.isml/.mpd",
      "liveCdnSecondaryUrl": "https://{CDN-Address2}.vualto.com/playout/pc01/{0}/cenc.isml/.mpd",
      "liveOriginPrimaryUrl": "https://{Origin1}.vualto.com/playout/pc01/{0}/cenc.isml/.mpd",
      "liveOriginSecondaryUrl": "https://{Origin2}.vualto.com/playout/pc01/{0}/cenc.isml/.mpd"
    }
  ]
}
Field Description
manifestFile The name of the server manifest file. This can be a relative or absolute path.
allowedPublishingPoints Targets specific publishing points. If not specified it will target all by default.
mp4splitOptions The parameters for MP4Split.
drm Configure the DRM settings. It uses the standard DRM JSON configuration.
tracks Configure the tracks available in the stream manifest.
outputUrls Configure the available output URLs to be returned via the API.

DRM

At minimum if using DRM provided by Vualto you can specify like so. We also support other providers so please contact us if you want more information.

  "drm": {
    "drm_provider": "VUALTO"
  }

If using another DRM provider not supported natively, you can specify the keys manually like so:

  "drm": {
    "drm_provider": "THIRDPARTY",
    "drm_data": [
      {
        "key_id": "",
        "key_iv": "",
        "name": "CENC",
        "content_id": "",
        "playready_laurl": "",
        "widevine_laurl": "",
        "widevine_drmspecific": ""
      },
      {
        "key_id": "",
        "key_iv": "",
        "name": "FAIRPLAY",
        "laurl": "",
        "ask": ""
      }
    ]
  }

Track Kind and Criteria properties

Kind

Field Description
video Specify that the Video tracks should be available.
audio Specify that the Audio tracks should be available.
textstream Specify that the text tracks should be available. e.g. Captions.

Criteria

Specify no criteria to not filter.

Field Description
MaxWidth Filter by the Max Width. e.g. 640
MaxHeight Filter by the Max Height. e.g. 360
systemBitrate Filter by the bitrate in bps. e.g. 64000
FourCC Filter by codec. e.g. AVC1, HEV1, AACH, AACL

Bad Request object

Property Type Notes
message string Explanation of the error

Supported Actions

GET /playoutprofile

Get all Live Playout Profiles, or all Live Playout Profile IDs if idsOnly=true

Query Parameters

Name Type Required
idsOnly bool No (default: false)

Responses

Scenario Code Body
idsOnly=false 200 Array of Live Playout Profile objects
idsOnly=true 200 Array of GUID strings

Example Request

/playoutprofile

Example Response 

[
    {
        "id": "a782bfee-5609-40da-94b6-8e92295c8da4",
        "configurationJson": "{\"manifestFile\":\"clear_profile.isml\", ...}"
        "name": "Clear Profile"
    },
    {
        "id": "053ee005-13ba-4278-b36a-c75c835cfb80",
        "configurationJson": "{\"manifestFile\":\"drm_profile.isml\", ...}"
        "name": "DRM Profile"
    }
]

Example Request

/playoutprofile?idsOnly=true

Example Response 

[
    "a782bfee-5609-40da-94b6-8e92295c8da4",
    "053ee005-13ba-4278-b36a-c75c835cfb80"
]

GET /playoutprofile/{id}

Get the Live Playout Profile with the specified ID

Responses

Scenario Code Body
Success 200 A Live Playout Profile object
Invalid ID 404  

Example Request

/playoutprofile/24bd0ed9-bc1d-42c2-a111-824e18265514

Example Response 

{
    "id": "a782bfee-5609-40da-94b6-8e92295c8da4",
    "configurationJson": "{\"manifestFile\":\"clear_profile.isml\", ...}"
    "name": "Clear Profile"
}

GET /playoutprofile/{id}/events

Get the Events associated with the Live Playout Profile with the specified ID. Requires the Event Get permission.

Query Parameters

Name Type Required
idsOnly bool No (default: false)

Responses

Scenario Code Body
idsOnly=false 200 Array of Event objects
idsOnly=true 200 Array of GUID strings
Invalid ID 404  

Example Request

/playoutprofile/24bd0ed9-bc1d-42c2-a111-824e18265514/events

Example Response

See Event object

POST /playoutprofile

Add a new Live Playout Profile

Request Body

A Live Playout Profile object. Required properties: configurationJson, name. The id property if specified is ignored.

Responses

Scenario Code Body
Success 201 The newly added Live Playout Profile object
Missing or invalid properties 400 Bad Request object

Example Request

/playoutprofile

{
    "name": "My New Profile",
    "configurationJson": "{\"manifestFile\":\"live_profile.isml\",\"outputUrls\":[{\"streamProtocol\":\"HLS\",\"liveCdnPrimaryUrl\":\"https://mycdn.net/live/{0}/live_profile.isml/.m3u8\", ... }]}"
}

Example Response 

{
    "id": "bc8d6a88-f7ea-44d5-903b-38b3f01c1c74",
    "name": "My New Profile",
    "configurationJson": "{\"manifestFile\":\"live_profile.isml\",\"outputUrls\":[{\"streamProtocol\":\"HLS\",\"liveCdnPrimaryUrl\":\"https://mycdn.net/live/{0}/live_profile.isml/.m3u8\", ... }]}"
}

PUT /playoutprofile/{id}

Update the Live Playout Profile with the specified ID. Any Events associated with the Profile which are in a playable state will have the playout manifest for the Profile updated on each Event Channel’s origin server(s).

Request Body

A Live Playout Profile object. Only include properties to update. id is ignored.

Note that because configurationJson is a string, it cannot be partially updated and the complete JSON object must be serialised.

Responses

Scenario Code Body
Success 200 Array of Origin Manifest Sync Result objects
Invalid properties 400 Bad Request object
Invalid ID 404  

Example Request

Update the Configuration JSON of a Playout Profile, keeping the existing Name

/playoutprofile/0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7

{
    "configurationJson": "{\"manifestFile\":\"updated_profile.isml\",\"outputUrls\":[{\"streamProtocol\":\"HLS\",\"liveCdnPrimaryUrl\":\"https://mycdn.net/live/{0}/live_profile.isml/.m3u8\", ... }]}"
}

Example Response 

[
    {
        "profileId": "0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7",
        "eventId": "434628b6-054a-4786-bf2b-09b4bbb977e8",
        "success": true
    },
    {
        "profileId": "0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7",
        "eventId": "5f8e4481-33ce-4785-9974-9f16f10b2e66",
        "success": false,
        "errors": [
            "Example error"
        ]
    }
]

DELETE /playoutprofile/{id}

Remove the Live Playout Profile with the specified ID. Any Events associated with the Profile which are in a playable state will have the playout manifest for the Profile removed on each Event Channel’s origin server(s).

Responses

Scenario Code Body
Success 200 Array of Origin Manifest Sync Result objects
Invalid ID 404  

Example Request

/playoutprofile/0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7

Example Response 

[
    {
        "profileId": "0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7",
        "eventId": "434628b6-054a-4786-bf2b-09b4bbb977e8",
        "success": true
    },
    {
        "profileId": "0eb38086-7f83-47a0-aefc-8d8cd7e9b5a7",
        "eventId": "5f8e4481-33ce-4785-9974-9f16f10b2e66",
        "success": false,
        "errors": [
            "Example error"
        ]
    }
]