JavaScript Media API Examples

The Media API is a REST-based API for accessing the content and metadata in your Video Cloud account. Because the Media API is a REST-based API, it can be accessed from a wide variety of places in your web applications, not just on the client, but in your dynamically-generated web pages or server-side synchronization processes, for example.

To understand these examples, you should be familiar with the Media API and the JavaScript programming language. Be sure to read Getting Started with the Media API and Media API: Getting Started Using JavaScript before continuing.

Note: making Media API calls from the server side is always preferable to client-side calls via JavaScript or ActionScript. The JavaScript examples here are demonstrations of functionality and do not represent best practices. In particular, be aware of the following issues when you run these samples:

• Some browsers such as IE9 will prompt you to download the response rather than show it in the form because the browser doesn't know what to do with the mime type.
• It's not good practice to expose an API token on the form, as noted in the examples' source code.
• Client-side Media API calls are not recommended as a UGC upload solution because of the lack of security.

In this topic, you will learn about making Media API queries from JavaScript through the following examples:

• Examples of querying for content with the Read API
  • find_all_videos
  • find_videos_by_tags
  • find_all_videos, sorted by popularity
• Examples of working with videos with the Write API
  • create_video
  • update_video
  • delete_video
  • add_image
  • add_logo_overlay
  • get_upload_status

For examples of working with playlists with the Write API, read Creating and Modifying Playlists with the Media API.

Examples of querying for content with the Read API

Here are some simple examples of using the Media API read methods to query for content.

• find_all_videos
• find_videos_by_tags
• find_all_videos, sorted by popularity

The find_all_videos example

To query for all videos in your account, your request would look like this:

// Get all videos
  http://api.brightcove.com/services/library?command=find_all_videos&token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

In this example, the method is find_all_videos. In the query parameters, we also pass the token argument with the value of our API token.

Click here to see an example making this call.

The find_videos_by_tags example

To find videos tagged with specific words, make a request like this:

// Get all videos
  http://api.brightcove.com/services/library?command=find_videos_by_tags
  &and_tags=adventure&token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

The and_tags parameter indicates all the following tags must match. Use or_tags if a partial match is what you want.

Click here to see an example making this call.

The find_all_videos, sorted by popularity example

This query finds all videos sorted by descending popularity based on total plays. The query also uses the video_fields parameter to restrict the return object so that the only name field for each record is returned.

// Get all videos
  http://api.brightcove.com/services/library?command=find_all_videos
  &sort_by=plays_total&sort_order=DESC&video_fields=name,playsTotal
  &token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

Click here to see an example making this call.

Examples of working with videos with the Write API

Using the Media API write methods is less straightforward, since creating the JSON Request object is more complicated, in contrast with the read methods, where you just need to set string parameters in a GET call. Here are examples of the following write methods using JavaScript:

• create_video
• update_video
• delete_video
• add_image
• add_logo_overlay
• get_upload_status

Note: These examples expose the Write API token in the HTML page. Exposing the token in this manner in production is a security risk and generally a bad idea. See Media API: Security Best Practices for tips about protecting your token.

The create_video example

This example presents a form that takes the video's name, short description, up to three tags, and path as input and uses the create_video method to upload the video when a user clicks the Upload button. This example also displays the JSON Request that is passed and the response. Note how the JSON Request is sent before before the file input.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the create_video method.

function buildJSONRequest(form){ if(document.getElementById('name').value =="" || document.getElementById('shortDescription').value =="" || form.filePath.value ==""){ alert("Require Name, Short Description and File"); return; }else{ json = form.JSONRPC //Construct the JSON request: json.value = '{"method": "create_video", "params": {"video": {"name": "' + document.getElementById('name').value +  '","tags": ["'+ document.getElementById('tagvalue1').value +'","'+ document.getElementById('tagvalue2').value +'","'+ document.getElementById('tagvalue3').value +'"],"shortDescription": "' + document.getElementById('shortDescription').value +'","itemState": "'+ document.getElementById('itemstate').value+'"},"token": "'+ document.getElementById('yourWriteToken').value + '",  "encode_to":"'+document.getElementById('encodeto').value+'",  "create_multiple_renditions": "'+document.getElementById('rendition').value+'"}}';  form.JSONView.value = json.value; } }

The buildJSONRequest function is called by the doFileUpload function:

function doFileUpload(){
  form = document.getElementById("create_video_sample");
  buildJSONRequest(form);
  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.

The update_video example

This example presents a form that takes the video's ID and uses the update_video method to modify the metadata of the video when user clicks the Upload button. It also displays the JSON Request that is passed and the response.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the update_video method.

function buildJSONRequest(){
  mform = document.getElementById('metaForm');
  json = document.getElementById('JSONView');
  //Construct the JSON request:
  json.value = '{"method": "update_video", "params":{"video": {"id": '+
  document.getElementById("id").value;
  idx = 0;
  for(i = 0; i < mform.elements.length; i++){
  if(mform.elements[i].value != "" && mform.elements[i].type=="text"){
  
  json.value += ','
  //Tags should be a list of strings
  if(mform.elements[i].name == "tags"){
  json.value += '"tags": [';
  tags = mform.elements[i].value.split(',');
  for(k = 0; k < tags.length; k++){
  if(k>0){json.value += ',';}
  json.value += '"' + tags[k] + '"';
  } 
  json.value +=']';
  }else{
  json.value += '"'+mform.elements[i].name+'": 
  "'+mform.elements[i].value+'"';
  }
  idx++;
  }
  }
  //special case for economics select, since type != text
  json.value += ',"economics": "'+document.getElementById("economics").value+'"';  
  json.value += '} ,"token": "'+ document.getElementById("yourWriteToken").value
 + '"}}';
  }

The the doUpdateVideo function calls the buildJSONRequest function:

  function doUpdateVideo(){
  form = document.getElementById("update_video_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.

The delete_video example

This example presents a form that takes the video's ID and uses the delete_video method to modify the metadata of the video when user clicks the Delete button. It also displays the JSON request that is passed and the response.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the delete_video method.

  function buildJSONRequest(){
  if(document.getElementById('id').value ==""){
  alert("Please enter a videoId");
  return;
  }else
  {
  json = document.getElementById('JSONView');
  //Construct the JSON request:
  json.value = '{"method": "delete_video", "params":{"video_id": 
  '+ document.getElementById('id').value +
  ',"token": "'+ document.getElementById("yourWriteToken").value + '"}}';
  }
  }

The doVideoDelete function calls the buildJSONRequest function:

  function doVideoDelete(){
  form = document.getElementById("delete_video_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.

The add_image example

This example presents a form that takes the filename, file size, and path of a thumbnail image and a video's ID as input and uses the add_image method to upload the image and assign it to the video as a thumbnail image when the Upload button is clicked. It also displays the JSON Request that is passed and the response.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the add_image method.

  function buildJSONRequest(form){
  if(document.getElementById('videoRefId').value =="" || form.filePath.value ==""){
  alert("Require Video ID and File");
  return;
  }else{
  json = form.jsonrpc
  //Construct the JSON request:
  json.value = '{"method": "add_image", "params": {"image": 
  {"displayName": "' + document.getElementById('name').value +  
  '", "referenceId": "' + document.getElementById('refId').value + 
  '", "type": "' + document.getElementById('imageType').value +
  '"},"video_reference_id": "'+ document.getElementById("videoRefId").value+ 
  '","token": "'+ document.getElementById("yourWriteToken").value + '"}}';
  form.JSONView.value = json.value;
  }
  }

The doFileUpload function calls the buildJSONRequest function:

  function doFileUpload(){
  form = document.getElementById("add_image_sample");
  buildJSONRequest(form);
  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.

The add_logo_overlay function

This example presents a form that takes the filename, file size, tooltip, click URL, alignment, and path of a logo overlay and a video's ID as input and uses the add_logo_overlay method to upload the image and assign it to the video as a logo overlay when a user clicks the Upload button. It also displays the JSON request that is passed and the response.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the add_logo_overlay method.

  function buildJSONRequest(form){
      if(1 != 1){
          alert("Require Name, Short Description and File");
          return;
  
      }else{
  
          json = form.JSONRPC;
  
          //Construct the JSON request:
          json.value = '{"method":"add_logo_overlay",';
          json.value+= '"params": {';
          json.value+= '"token": "' + document.getElementById('token').value + '",';
          json.value+= '"logooverlay":{';
          json.value+= '"image":{';
          json.value+= '"referenceId":"' + document.getElementById('referenceId').value + '",';
          json.value+= '"displayName":"' + document.getElementById('displayName').value + '",';
          json.value+= '"type":"LOGO_OVERLAY"},';
          json.value+= '"tooltip":"' + document.getElementById('toolTip').value + '",';
          json.value+= '"linkURL":"' + document.getElementById('linkURL').value + '",';
          json.value+= '"alignment":"' + document.getElementById('alignment').value + '"},';        
  
          if(document.getElementById('file_checksum').value != "") {
              json.value += '"file_checksum" : "' + document.getElementById('file_checksum').value + '"';
  
          }
          
          if(document.getElementById('video_id').value != "") {
              json.value+= '"video_id":"' + document.getElementById('video_id').value + '"';    
  
          } else
  
          if(document.getElementById('video_reference_id').value != "") {
              json.value+= '"video_reference_id":"' + document.getElementById('video_reference_id').value + '"';
          } else {
              alert("You must specify either the Video ID or the Video Reference ID to assign this logo overlay");    
          }
  
          json.value += '}}';
  
          document.getElementById("JSONView").innerHTML = json.value;
  
          //console.log(json.value);
      }
  }

The doFileUpload function calls the buildJSONRequest function:

  function doFileUpload(){
  form = document.getElementById("add_logo_overlay");
  buildJSONRequest(form);
  form.action = document.getElementById("apiLocation").value;
  form.submit();
  }

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

The get_upload_status example

This example presents a form that takes the video's ID and uses the get_upload_status method to return the upload status of the video when a user clicks the Get Status button. It also displays the JSON request that is passed and the response. The status returned is one of UPLOADING, PROCESSING, COMPLETE, or ERROR. Note that there is a brief delay from the moment you submit a create_video method call and the moment the transaction for that method call is complete. During that interval, a get_upload_status method call will return an error message saying, "Illegal value - Cannot find any video", because the video has not yet been assigned an ID and begun uploading.

The buildJSONRequest function takes the form inputs and creates the JSON-RPC object that is passed in the get_upload_status method.

  function buildJSONRequest(){
  if(document.getElementById('id').value ==""){
  alert("Please enter a videoId");
  return;
  }else{
  json = document.getElementById('JSONView');
  //Construct the JSON request:
  json.value = '{"method": "get_upload_status", "params":{"video_id": 
  '+ document.getElementById('id').value +
  ',"token": "'+ document.getElementById("yourWriteToken").value + '"}}';
  }
  }

The doVideoStatus function calls the buildJSONRequest function:

  function doVideoStatus(){
  form = document.getElementById("video_status_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.

More examples

Here are some more examples to help you get started:

• Top Videos Sidebar Example (JavaScript)
• VideoManager Example Application (JavaScript)
• Upload Video Example (Java)
• Upload Video Example (PHP)
• Creating and Modifying Playlists with the Media API

Related Topics

• Getting Started with the Media API
• Media API: Getting Started Using JavaScript
• Creating and Modifying Playlists with the Media API