Playlists

Organizing my Video Content and Livestreams: Playlists

By now, you’ve probably uploaded quite a bit of video on-demand content and you might have created a few livestream channels. You’re probably going to want to organize this into groups of content on your website so end users can watch a series of videos without having to leave the page. Dacast makes this super simple by allowing you to create and manage playlists via the API.

👍
Our PHP SDK and Node SDK make getting embed codes for your content very simple and provide wrapper functions to perform all of the necessary steps from start to finish, only requiring you to set your API key, and pass the ID of the video content to generate the embed code for. If you are using one of these platforms, it is highly recommended to download and integrate the SDK to facilitate integration of all our API services into your application.

You will first need to create a playlist if you haven’t already got one.

If you already have a playlist, you’ll want to make sure to grab the current contents of the playlist unless you want to completely replace them.

The playlist update process is a replace-in-place process, not a delta process, that is to say, any updates you make must take into account current contents and changes to be made, not just changes.

After that, you can then manipulate (add, remove, re-order) the contents you want to have in the playlist, hen you can grab the embed code for the playlist and embed it on your website.

Creating your playlist

Playlists can be created via the API directly, using the following command structure:

curl "https://developer.dacast.com/v2/playlist" \
  -X POST \
  -d "{\n  \"title\": \"My Test Playlist\",\n  \"description\": \"A very first test playlist\"\n}" \
  -H "X-Api-Key: 1633439723WCbRWPz79VsIn9xsD2Kl0wzizzl7QHWK" \
  -H "X-Format: default" \
  -H "Content-Type: application/json"

var myHeaders = new Headers();
myHeaders.append("X-Api-Key", "insertYourApiKeyHere");
myHeaders.append("X-Format", "default");
myHeaders.append("Content-Type", "application/json");

var raw = "{\"title\": \"My Test Playlist\",\"description\": \"A very first test playlist\"}";

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://developer.dacast.com/v2/playlist", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://developer.dacast.com/v2/playlist',
  'headers': {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default',
    'Content-Type': 'application/json'
  },
  body: '{"title": "My Test Playlist","description": "A very first test playlist"}'

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "https://developer.dacast.com/v2/playlist"

payload = "{\"title\": \"My Test Playlist\",\"description\": \"A very first test playlist\"}"
headers = {
  'X-Api-Key': 'insertYourApiKeyHere',
  'X-Format': 'default',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://developer.dacast.com/v2/playlist',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{"title": "My Test Playlist","description": "A very first test playlist"}',
  CURLOPT_HTTPHEADER => array(
    'X-Api-Key: insertYourApiKeyHere',
    'X-Format: default',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"title\": \"My Test Playlist\",\"description\": \"A very first test playlist\"}");
Request request = new Request.Builder()
  .url("https://developer.dacast.com/v2/playlist")
  .method("POST", body)
  .addHeader("X-Api-Key", "insertYourApiKeyHere")
  .addHeader("X-Format", "default")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

As you’ll see, the request takes 2 input parameters: title (the name of the playlist) and description (a brief description of the contents of the playlist).

When the playlist is successfully created, you will get a response similar to the below:

{
	"ads": null,
	"company_url": null,
	"content": {
		"list": null,
		"start_time": "00:00:00"
	},
	"countdown_date": "",
	"countdown_timezone": "",
	"counter_live_limit": -1,
	"countries_id": "",
	"creation_date": "2021-11-09T10:26:11Z",
	"custom_data": null,
	"description": "",
	"enable_payperview": false,
	"enable_subscription": false,
	"external_video_page": "http://",
	"google_analytics": "false",
	"id": "2a287039-89b3-4a79-f2cc-f4950366a7af",
	"logo_url": null,
	"noframe_security": 0,
	"password": "",
	"pictures": {
		"splashscreen": null,
		"thumbnail": null
	},
	"player_height": 0,
	"player_size_id": 10,
	"player_width": 0,
	"publish_on_dacast": true,
	"save_date": "2021-11-09T10:26:11Z",
	"stream_category": 0
}

You’re going to want to:

Grab the ID from the response (line 19 above)
Store it in your database

Then you’ll be able to add, remove, and re-order contents in the playlist now, as well as in future.

curl "https://developer.dacast.com/v2/playlist/insertPlaylistIdHere" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default"

var myHeaders = new Headers();
myHeaders.append("X-Api-Key", "insertYourApiKeyHere");
myHeaders.append("X-Format", "default");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://developer.dacast.com/v2/playlist/insertPlaylistIdHere", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://developer.dacast.com/v2/playlist/insertPlaylistIdHere',
  'headers': {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests

url = "https://developer.dacast.com/v2/playlist/insertPlaylistIdHere"

payload={}
headers = {
  'X-Api-Key': 'insertYourApiKeyHere',
  'X-Format': 'default'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://developer.dacast.com/v2/playlist/insertPlaylistIdHere',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-Api-Key: insertYourApiKeyHere',
    'X-Format: default'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://developer.dacast.com/v2/playlist/insertPlaylistIdHere")
  .method("GET", null)
  .addHeader("X-Api-Key", "insertYourApiKeyHere")
  .addHeader("X-Format", "default")
  .build();
Response response = client.newCall(request).execute();

Grab the contents of the “content” property, for instance:

"content": {
    "list": [
      {
        "id": "09358f90-1fe7-5077-85f7-088cf002b9d7",
        "position": "1",
        "thumbnail_id": "1",
        "title": "test.mp4"
      },
      {
        "id": "798b4ba6-7989-d7a8-f04c-16f7bf687f5f",
        "position": "2",
        "thumbnail_id": "1",
        "title": "wefwefqwefweqf"
      }
    ],
    "start_time": "00:00:00"
  },

If you are giving users the ability to manipulate the playlist, it is suggested to present the list of contents (livestream channels and videos on demand) in one pane on the left-hand side of the page, and the current contents of the playlist in a pane on the right-hand side of the page, with buttons to add, remove and reorder content:

You would Get A List of Your Videos on Demand and Get A List of Your Livestream Channels to display the list of current contents
When you present the list of content available to add to the end-user, ensure that the video ID is the key for each option, and that the content type is noted for each content, as those items are going to need to be fed into the update request.
Present the list of current content in the playlist with the "title" property in the list of content shown above, with the "id" value as the key and the
Iterate through all of the contents in the new list and grab the "id", "position" and "type" values, and store these as an array:

[
  {
    "id": "09358f90-1fe7-5077-85f7-088cf002b9d7",
    "type": "vod",
    "position": "1"
  },
  {
    "id": "798b4ba6-7989-d7a8-f04c-16f7bf687f5f",
    "type": "channel",
    "position": "2"
  }
]

With this array:

to add contents, feed in the content IDs, types and positions of the new contents to add as objects into the array you formed above
to remove contents, delete the object from the array
to change the order of contents, update the position property in each object to reflect the new order of contents
---TBC by Michael---

You can then use this ID to perform further operations, like:

Updating Video Metadata - if you asked for the Video Title in the upload form, you can now set that title using this method.
Uploading a Splashscreen and Thumbnail - we auto-generate these images, but if you want to set your own, or allow your end users to change these, use these methods.
List Content That Belongs to a User - so you can offer drop down selection of content to embed in a CMS, for instance.
Looking Up Video Metadata - so you can grab thumbnails and titles for content, and display your end users' videos on your website, in a gallery, for instance.
Getting Your Embed Code - this is crucial so you can embed the player on your website and show the end users' video content
Adding Your Content to a Playlist - so you can embed series of videos, for instance a lecture series, in one video player on your site