How to use the Linear playlist API

Modified on Mon, 7 Aug, 2023 at 3:04 PM

Change history Version 0.1 01-05-2022 Initial version


PDF version of the document at the end of the article.

Case study:

How to control the Okast Channels playlist without using its interface.

Creating and modifying a playlist.


Overview of how the playlist works


Limitations:

Being an Okast client.

Having an Okast channels instance + credentials.

One call per owned instance.



JSON Payload model for Playlist 

There are 2 models

1. Loop

2. Schedule


JSON payload for mode loop 

No specific body parameters

{
   "uuid":"d7f489ab-fe9e-46a0-a919-0d1dcd11ae7f",
   "mode":"loop",
   "playlist_items":[
      {
         "uuid":"9cc2e369-88e2-401e-a253-edad2a4d31c9",
         "media_uuid":"1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
         "streams":{
            "audios":[
               {
                  "language":"en",
                  "label":"2 - EN"
               },
               {
                  "language":"ru",
                  "label":"1 - RU"
               },
               {
                  "language":"fr",
                  "label":"3 - FR"
               }
            ],
            "subtitles":[
               {
                  "language":"et",
                  "label":"subtitle-42",
                  "url":"<https://example.com/sub/subtitle-42.vtt>"
               },
               {
                  "language":"fr",
                  "label":"subtitle-0",
                  "url":"<https://example.com/sub/subtitle-0.vtt>"
               }
            ]
         }
      },
      {
         "uuid":"9e859308-72af-4339-baba-74a08e78dfc7",
         "media_uuid":"2a45c401-b317-4622-89f5-5f0ee83b204a",
         "streams":{
            "audios":[
               {
                  "language":"fr",
                  "label":"1 - FR"
               }
            ],
            "subtitles":[
               
            ]
         }
      },
      {
         "uuid":"683da042-e570-4cdd-9562-ccb7f69c1e1d",
         "media_uuid":"1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
         "streams":{
            "audios":[
               {
                  "language":"fr",
                  "label":"1 - FR"
               }
            ],
            "subtitles":[
               
            ]
         }
      }
   ]
}

 

JSON payload for mode schedule

By default, returns the list of contents to start playing in the next 24 hours.



Body Parameters

ParameterFormatDescription
today
Returns the list of contents that starts playing today
day"YYYY-MMyDD"Returns the list of contents that starts playing a specific day
period_start"YYYY-MM-DD hh:mm:ss"Defines beginning of period when requesting a time range
period-end"YYYY-MM-DD hh:mm:ss"Defines end of period when requesting a time range
{
     "uuid": "d7f489ab-fe9e-46a0-a919-0d1dcd11ae7f",
     "mode": "schedule",
     "playlist_items": [
         {
             // unique for each playlist item
             "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
             // unique for each media file
             "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
             // scheduled start of the next content
             "scheduled_start": "2021-04-16T17:34:03.000000",
             // scheduled end of the next content
             "scheduled_end": "2021-04-16T19:11:46.000000"
         },
         {
             "uuid": "9e859308-72af-4339-baba-74a08e78dfc7",
             "media_uuid": "2a45c401-b317-4622-89f5-5f0ee83b204a"
             "scheduled_start": "2021-04-16T19:11:46.000000",
             "scheduled_end": "2021-04-16T21:35:01.000000"
         },
         // ... other items
         {
             "uuid": "683da042-e570-4cdd-9562-ccb7f69c1e1d",
             "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1"
             "scheduled_start": "2021-04-17T16:47:51.000000",
             "scheduled_end": "2021-04-17T18:35:27.000000",
         }
     ]
}


playlist_items : object

For both playlists (loop and scheduled) the playlist_items object is an array of content items. Those objects have the ability to have several optionals parameters.


SCTE-35 add insertion

Ability to add SCTE-35 markers for add insertion :


Body Parameters

ParameterFormatDescription
cue-out-idstringSCTE-35 identifier
cue-out-positionstringIndicates if the cue-out event is at the begging or at the end of the content
cue-in-idstringSCTE-35 identifier
cue-in-positionstringIndicates if the cue-out event is at the begging or at the end of the content
{
    "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
    "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
    ...,
    "cue-out-id": "<unique_scte35_identifier>",
    "cue-out-position": "START"|"END",
    "cue-in-id": "<unique_scte35_identifier>",
    "cue-in-position": "START|END"
}

Logo 

Ability to show or not the logo on each content. If missing considered by default as "logo": true :

{
    "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
    "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
    ...,
    "logo": true|false
}


Interlaced content

Ability to deinterlace a content. If missing considered by default as "deinterlace": false

{
    "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
    "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
    ...,
    "deinterlace": true|false
}


Cut a content

Ability to cut a content. If missing considered by default as no cut ( "cut": -1 ), value in milliseconds :

{
    "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
    "media_uuid": "1b1bf470-527a-4c6e-8f19-1d369f2eabf1",
    ...,
    "cut": 42000
}

cut (valeur en millisecondes, défaut=-1) : permet d'indiquer à quelle durée le fichier doit être tronqué (attention ce sont des millisecondes).

Si absent ou valeur <=0, le fichier ne sera pas tronqué.




Declare a LIVE content


Ability to declare a live content, it is a special broadcast element that is not related to a specific media file.


Therefore, a specific identifier must be used, to allow the playout scheduler to recognize it and act as a placeholder for a live event.


When an element is a LIVE element, the media_uuid field must be set to null and an optional field has to be declared live: true .


The uuid field must remain unique within the schedule.


The absence of the live attribute has to be considered as live: false


{
    "uuid": "9cc2e369-88e2-401e-a253-edad2a4d31c9",
    "media_uuid": null,
    "live": true,
    ...,
}