Creating and Modifying Playlists with the Media API

This topic describes how to create, update, or delete playlists using the Media API.

The Media API contains a set of write methods you can use to create, update, or delete playlists:

create_playlist
update_playlist
delete_playlist

These methods work much like create_video and the other write methods that affect videos, images, and logo overlays.

For an introduction to the Media API, read Getting Started with the Media API.
For reference information about these methods, read the Media API Reference.

Video Cloud provides three different approaches to creating and managing playlists:

the Media module
FTP batch provisioning
the Media API, as described in this topic.

create_playlist method

The create_playlist method works much like create_video; you need to set up the JSON that represents your playlist object, along with the Media API method name and write token for your account, and then post it to the URL for the Video Cloud Media API.

The Media API Objects Reference describes the properties of the Playlist object that you create or modify with the Playlist Write methods. The following properties are required when you create a playlist:

name
playlistType

Creating a manual playlist

If the playlistType property in the Playlist object you submit is explicit, that means it's a manual playlist. When you create a manual playlist, you need to include a videoIds parameter, which is a list of the video IDs to include in the playlist. Note that you must refer to videos in the playlist by their video ID, not their reference ID. You may choose to assemble this list with a previous search_videos or find_videos Media API read call.

Creating a smart playlist

If the playlistType property in the Playlist object you submit is not explicit , that means it's a smart playlist. In that case, the playlistType will specify how the videos are ordered. You can optionally use the filterTags and tagInclusionRule parameters to limit the videos on your smart playlist. You can specify that the playlist includes only the videos that contain all the tags listed in the filterTags parameter (by setting the tagInclusionRule parameter to AND), or only the videos that contain at least one of the tags listed in the filterTags parameter (by setting the tagInclusionRule parameter to OR).

create_playlist PHP example

In this PHP example, we are creating a smart playlist that will consist of all videos that have both of the tags crescent and gibbous:

curl -F "json={'method' : 'create_playlist',\
'params':{\
'token':'insertTokenHere.',\
'playlist':{\
'referenceId':'moonshot-1',\
'name':'Phases 3 and 4',\
'shortDescription':'The moon as it wanes from gibbous to crescent.',\
'playlistType':'ALPHABETICAL',\
'filterTags':['crescent','gibbous'],\
'tagInclusionRule': 'AND'}\
}}" http://api.brightcove.com/services/post

update_playlist method

The update_playlist method is useful for modifying playlists that already exist. It is very similar to the create_playlist method. You need to set up the JSON that represents your playlist object, along with the Media API method name and write token for your account, and then post it to the URL for the Video Cloud Media API. Since the playlist already exists, it has a read-only id property (returned by the create_playlist method), and also a referenceId, if you set that optional property. You can refer to the playlist you want to update either by the id property or by the referenceId property. However, if you want to change the referenceId property, you must include the id property. Note that if you refer to videos in the playlist , you must use their video ID, not their reference ID, in the Playlist object's videoIds property.

Any property that you list in your JSON Playlist object will be overwritten with the value you pass in the update_playlist method. Any properties you omit will retain their existing values. For example, if you have a manual playlist that consists of 4 videos, 1234, 1235, 1236, and 1237, and you want to append a new video with the ID 2001 to the end of the playlist, you need to pass the IDs of all 5 videos, in JSON like this:

{"method":"update_playlist",
"params":{
	"token":"insertTokenHere",
	"playlist":{
		"id":"25855448001",
		"videoIds":[1234, 1235, 1236, 1237, 2001]
		}
	}
}

delete_playlist method

The delete_playlist method is quite simple; you just pass the playlist ID or reference ID of the playlist you want to delete, along with your Media API write token. There is also an optional cascade parameter; set this to true if you want to delete this playlist even if it is referenced by players. With cascade="true", the playlist will be removed from all players in which it appears, then deleted.

delete_playlist JavaScript example

This example presents a form that takes the playlist's ID and uses the delete_playlist method to delete the playlist when user clicks the Delete button. It also displays the JSON request that is passed and the response (which is void, if the request succeeds).

function buildJSONRequest(){
	if(document.getElementById('id').value ==""){
		alert("Please enter a playlist ID");
		return;
	}else
    {
		json = document.getElementById('JSONView');
		//Construct the JSON request:
		json.value = '{"method": "delete_playlist", "params":{"playlist_id": 
        '+ document.getElementById('id').value +
		',"token": "'+ document.getElementById("insertTokenHere.").value + '"}}';
	}
}

The doPlaylistDelete function calls the buildJSONRequest function:

function doPlaylistDelete(){
	form = document.getElementById("delete_playlist_sample");
	buildJSONRequest();
	form.action = document.getElementById("yourAPILocation").value;
	form.submit();
}

Click here to see the example in action.
Click here to see the source code for this example.

Video Cloud

App Cloud

Resources