BCMAPI()

__set()

__get()

find()

findAll()

search()

createMedia()

createPlaylist()

update()

createImage()

createOverlay()

deleteOverlay()

delete()

getStatus()

shareMedia()

removeFromPlaylist()

addToPlaylist()

convertTime()

convertTags()

tagsFilter()

sef()

BCMAPICache()

BCMAPIApiError

API error.

This is the most generic error returned from BCMAPI as it is thrown whenever the API returns unexpected data, or an error. The API return data will be included in the error to help you diagnose the problem.

BCMAPIDeprecated

Access to this method or property has been deprecated.

The requested item is no longer supported by Brightcove and/or BCMAPI. Stop using this method as early as possible, as the item could be removed in any future release.

BCMAPIDtoDoesNotExist

The DTO does not exist.

The specified asset does not exist in the Brightcove system. Ensure you're using the correct ID.

BCMAPIIdNotProvided

ID not provided.

An ID has not been passed to the method (usually a "delete" or "share" function). Include the ID parameter to resolve the error.

BCMAPIInvalidFileType

Unsupported file type.

The file being passed to the function is not supported. Try another file type to resolve the error.

BCMAPIInvalidMethod

Requested method not found.

The "find" method being requested is not supported by BCMAPI, or does not exist in the Brightcove API. Remove the method call and check both the BCMAPI and Brightcove API documentation.

BCMAPIInvalidProperty

Requested property not found.

The BCMAPI property you are trying to set or retrieve does not exist. Check the BCMAPI documentation.

BCMAPIInvalidType

Type not specified.

The DTO type (video, playlist, image, etc) you specified is not allowed for the method. Check both the BCMAPI and Brightcove API documentation.

BCMAPIInvalidUploadOption

An invalid media upload parameter has been set

You have specific an upload option that is not available for the filetype being uploaded, or allowed in conjunction with another option. Check both the BCMAPI and Brightcove API documentation.

BCMAPISearchTermsNotProvided

Search terms not provided.

Please specify one or more search parameters. Verify you are passing the parameters in an array.

BCMAPITokenError

Read / Write token not provided.

The read or write token you provided is not recognized by Brightcove. Verify you are using the correct token.

BCMAPITransactionError

Read / Write API transaction failed.

The API could not be accessed, or the API did not return any data. Verify the server has cURL installed, enabled, and able to retrieve remote data. Verify the Brightcove API is currently available.

Instantiation

This example shows how to instantiate, or start, the BCMAPI PHP class. The first token, which is for the Read API, is required. The second token is for the Write API and is optional.

<?php
	
  // Include the BCMAPI SDK
  require('bc-mapi.php');
	
  // Instantiate the class, passing it our Brightcove API tokens (read, then write)
  $bc = new BCMAPI(
    'READ_API_TOKEN',
    'WRITE_API_TOKEN'
  );
  
  // You may optionally include the caching extension provided with BCMAPI...
  require('bc-mapi-cache.php');
  
  // Using flat files
  $bc_cache = new BCMAPICache('file', 600, '/var/www/myWebSite/cache/', '.cache');

  // Using Memcached
  $bc_cache = new BCMAPICache('memcached', 600, 'localhost', NULL, 11211);

?>

Properties

This example shows how to set and retrieve some of the BCMAPI properties that can be used for debugging and additional settings.

<?php

  // Turn on HTTPS mode
  $bc->__set('secure', TRUE);

  // Make our API call
  $videos = $bc->find('allVideos');

  // Determine how many possible results there are
  echo 'Total Videos: ' . $bc->total_count . '<br />';

  // Make our API call
  $videos = $bc->findAll();

  // Determine how many times we called the Brightcove API
  echo 'API Calls: ' . $bc->__get('api_calls');

?>

Regional Support (Internationalization)

This example shows how to change the API URLs for supporting international regions.

<?php

  // Change our region to Japan
  $bc->__set('url_read', 'api.brightcove.co.jp/services/library?');
  $bc->__set('url_write', 'api.brightcove.co.jp/services/post');

?>

Error Handling

This example shows how to utilize the built-in error handling in BCMAPI.

<?php

  // Create a try/catch
  try {
    // Make our API call
    $video = $bc->find('find_video_by_id', 123456789);
  } catch(Exception $error) {
    // Handle our error
    echo $error;
    die();
  }

?>

Find Query

This example shows how to retrieve a video from a Brightcove account.

<?php

  // Make our API call
  $video = $bc->find('find_video_by_id', 123456789);

  // Print the video name and ID
  echo $video->name . ' (' . $video->id . ')';

?>

Find Query - Shorthand

This example shows how you can use shorthand method names to make code easier to write and read.

<?php

  // Make our API call
  $video = $bc->find('videoById', 123456789);

?>

Find Query - Additional Parameters

This example shows how to define additional API call parameters using a key-value array.

<?php

  // Define our parameters
  $params = array(
    'video_id' => 123456789,
    'video_fields' => 'video_id,name,shortDescription'
  );

  // Make our API call
  $video = $bc->find('videoById', $params);

?>

Find Query - True Find All

Brightcove limits the "find_all_videos" call to 100 results, requiring pagination and numerous API calls. This example shows how to use the findAll() method to do this automatically.
WARNING: Use very carefully

<?php

  // Define our parameters
  $params = array(
    'video_fields' => 'id,name'
  );

  // Make our API call
  $videos = $bc->findAll('video', $params);

?>

Search Query

This example shows how to search for a video about "jobs", but not "Steve Jobs".

<?php

  // Define our parameters
  $params = array(
    'video_fields' => 'id,name,shortDescription'
  );

  // Set our search terms
  $terms = array(
    'all' => 'display_name:jobs',
    'none' => 'display_name:steve'
  );

  // Make our API call
  $videos = $bc->search('video', $terms, $params);

?>

Search Query (Multiple-Field Search)

This example shows how to search for a video with "jobs" in the title AND tags.

<?php

  // Define our parameters
  $params = array(
    'video_fields' => 'id,name,shortDescription'
  );

  // Set our search terms
  $terms = array(
    'all' => 'display_name:jobs,tag:jobs'
  );

  // Make our API call
  $videos = $bc->search('video', $terms, $params);

?>

Create - Video

This example details how to upload a video to a Brightcove account. This code is handling data that was passed from a form. Note that we re-name the uploaded movie to its original name rather than the random string generated when it's placed in the "tmp" directory; this is because the tmp_name does not include the file extension. The video name is a required field.

<?php

  // Create an array of meta data from our form fields
  $metaData = array(
    'name' => $_POST['videoName'],
    'shortDescription' => $_POST['videoShortDescription']
  );

  // Move the file out of 'tmp', or rename
  rename($_FILES['videoFile']['tmp_name'], '/tmp/' . $_FILES['videoFile']['name']);
  $file = '/tmp/' . $_FILES['videoFile']['name'];

  // Upload the video and save the video ID
  $id = $bc->createMedia('video', $file, $metaData);

?>

Create - Image

This example details how to upload a image to a Brightcove account. This code is handling data that was passed from a form. Note that we re-name the uploaded image to its original name rather than the random string generated when it's placed in the "tmp" directory; this is because the tmp_name does not include the file extension.

<?php

  // Create an array of meta data from our form fields
  $metaData = array(
    'type' => 'VIDEO_STILL',
    'displayName' => $_POST['imageName']
  );

  // Move the file out of 'tmp', or rename
  rename($_FILES['bcImage']['tmp_name'], '/tmp/' . $_FILES['bcImage']['name']);
  $file = '/tmp/' . $_FILES['bcImage']['name'];

  // Upload the image, assign to a video, and save the image asset ID
  $id = $bc->createImage('video', $file, $metaData, 123456789);

?>

Create - Playlist

This example shows how to create a playlist in a Brightcove account. The code is handling data that was passed from a form. The name, video IDs, and playlist type are all required fields.

<?php

  // Take a comma-separated string of video IDs and explode into an array
  $videoIds = explode(',', $_POST['playlistVideoIds']);

  // Create an array of meta data from our form fields
  $metaData = array(
    'name' => $_POST['playlistName'],
    'shortDescription' => $_POST['playlistShortDescription'],
    'videoIds' => $videoIds,
    'playlistType' => 'explicit'
  );

  // Create the playlist and save the playlist ID
  $id = $bc->createPlaylist('video', $metaData);

?>

Update - Video / Playlist

This example shows how to update a video, but the same method will work for a playlist.

<?php

  // Create an array of the new meta data
  $metaData = array(
    'id' => 123456789,
    'shortDescription' => 'Our new short description.'
  );

  // Update a video with the new meta data
  $bc->update('video', $metaData);

?>

Delete - Video / Playlist

This example shows how to delete a video, but the same method will work for a playlist. Cascaded deletion means that the video will also be removed from all playlists and players.

<?php

  // Delete a 'video' by ID, and cascade the deletion
  $options = array(
  	'cascade' => TRUE
  );
  
  $bc->delete('video', 123456789, NULL, $options);

?>

Status - Video Upload

This example shows how to determine the status of a video being uploaded to a Brightcove account.

<?php

  // Retrieve upload status
  $status = $bc->getStatus('video', 123456789);

?>

Share Video

This example shows how to share a video with another Brightcove account. A list of the new video IDs will be returned. Note that sharing must be enabled between the two accounts.

<?php

  // List the accounts to share the video with
  $ids = array(
    123456789
  );

  // Share the videos, and save the new video IDs
  $new_ids = $bc->shareMedia('video', 123456789, $ids);

?>

Add To / Remove From Playlist

This example shows how to add an asset to a playlist, as well as how to remove an asset from a playlist. You may pass an array of video IDs, or a single video ID.

<?php

  // Add two videos to a playlist
  $bc->addToPlaylist(555555555, array(123456789, 987654321));

  // Remove a video from a playlist
  $bc->removeFromPlaylist(555555555, 987654321);

?>

SEF URLs / Time Formatting

This example shows the BCMAPI convenience methods that convert video titles into a search-engine friendly format and video lengths into formatted strings.

<?php

  // Make our API call
  $video = $bc->find('videoById', 123456789);

  // Print the SEF video name and formatted duration
  echo 'Name: ' . $bc->sef($video->name) . '<br />';
  echo 'Duration:' . $bc->convertTime($video->length) . '<br />';

?>

Automatic Timestamp Conversion

To more seamlessly bridge the Brightcove API into PHP the "from_date" parameter for the "find_modified_videos" call should be provided as seconds since Epoch (UNIX timestamp) instead of minutes since, as the Brightcove Media API documentation states. You can still pass minutes if you prefer.

<?php

  // Set timestamp to 7 days ago (in seconds)
  $time = time() - 604800;

  // Make our API call
  $videos = $bc->find('modifiedVideos', $time);

  // Set timestamp to 7 days ago (in minutes)
  $time = floor((time() - 604800) / 60);

  // Make our API call
  $videos = $bc->find('modifiedVideos', $time);

?>

Tags

This example demonstrates how a tag with a value of "abc=xyz" can easily be parsed into a key-value array pair.

<?php

  // Make our API call
  $video = $bc->find('videoById', 123456789);

  // Parse any key=value tags into array
  $video->tags = $bc->convertTags($video->tags);

  // Print out each tag
  foreach($video->tags as $key => $value)
  {
    echo $key . ': ' . $value . '<br />';
  }

?>

Tag Filter

This example shows how to remove all videos that don't contain any of the listed tags.

<?php

  // Make our API call
  $videos = $bc->find('allVideos');

  // Remove all videos without specified tags
  $videos = $bc->tagsFilter($videos, 'published=true,include=true');

?>