brightcove v0.5.0

ATTENTION

There is a new API offered by Brightcove that is going to become de facto by the end of 2017, with existing endpoints that this library uses retiring.

The new API is of significant difference to the endpoints used by this library that myself and the main contributors feel like a shift is needed. Rather than having this library break compatibility, we have opted to retire this library as well and work towards a new one.

A link will be provided here soon.

A bit of our thinking can be found here.

In the meantime, this isn't going anywhere and I will continue to merge any contributions you have to offer.

Cheers! - nick

node-brightcove

This humble library aims to be a simple facade over Brigthcove's server APIs. As the mob demands additional functionality, it will be added here.

• Installation
• Media API - Calls - Options - Events
• OAuth API
• Policy API

Installation

Installation is handled via npm:

$ npm install brightcove

Brightcove offers several response formats, but this library demands JSON responses and, wherever possible, passes them through to you.

Media API

The MediaApi object acts as the facade for all of the Media API's calls and options.

It is instance-based, allowing you to juggle more than one Brightcove Token, if needed.

var brightcove = require('brightcove');
var	mediaApi = new brightcove.MediaApi('myTokenOfAwesomeness');

MediaApi Calls

Brightcove breaks up its Media API calls between Videos (read/write) and Playlists (read/write). For organizational purposes, that's how they're listed here:

Video Read API

• findAllVideos (options, callback)

• findVideoById (videoId, options, callback) + videoId Brightcove-assigned ID

• findVideosByIds (videoIds, options, callback) + videoIds is a simple array of brightcove video IDs

• findRelatedVideos (videoId, referenceId, options, callback) + videoId (optional) Brightcove-assigned ID of the video we'd like to find related videos for + referenceId (optional) User-assigned ID of the video we'd like to find related videos for

• findVideoByReferenceId (referenceId, options, callback) + referenceId User-assigned, optional ID attached to a video

• findVideosByReferenceIds (referenceIds, options, callback) + referenceIds is a simple array of brightcove video IDs

• searchVideos (all, any, none, exact, options, callback) + all, any, none Array of strings. At least one argument must be set. Others are optional. + all Videos must contain all of the specified tags + any Videos can contain any of the specified tags + none Videos must not contain any of the specified tags + exact Boolean value. If true, disables fuzzy search and requires tags to match exactly.

Video Write API

• createVideo (video, callback, progressCallback)

• updateVideo (video, callback) + video Use the brightcove.Video facade to build this object.

• deleteVideoById (id, options, callback)

• deleteVideoByReferenceId (referenceId, options, callback)

• addThumbnailImage (image, callback, progressCallback)

• addVideoStillImage (image, callback, progressCallback) + image Use the brightcove.Image facade to build this object.

Playlist Read API

• findAllPlaylists (options, callback)

• findPlaylistById (playlistId, options, callback) + playlistId Brightcove-assigned ID

• findPlaylistsByIds (playlistIds, options, callback) + playlistIds is a simple array of brightcove playlist IDs

• findPlaylistByReferenceId (referenceId, options, callback) + referenceId User-assigned, optional ID attached to a playlist

• findPlaylistsByReferenceIds (referenceIds, options, callback) + referenceIds is a simple array of brightcove playlist IDs

Playlist Write API

• createPlaylist (playlist, callback) + playlist Use the brightcove.Playlist facade to build this object.

MediaApi Options

Most of the read calls require an options parameter which wraps up all of the available options Brightcove offers for its responses via the Options object.

These options govern:

• what fields are returned for each video/playlist in the response from Brightcove
• pagination of returned videos/playlists
• sorting of returned videos/playlists
• which video streaming delivery type to use
• etc.

The Options object is created via the MediaApi instance. A convenience method is included to quickly create the usually included fields, paging, and sorting options:

var options = mediaApi.withDefaultOptions();

However, you're likely going to define your own. To do that, a fluent interface was created to make things easier:

var options = mediaApi.withOptions
					.havingPageSizeOf(10).atPage(2)
					.sortingBy().creationDate().inAscendingOrder();

Notice that the return chain is context-aware. If you're rocking intellisense in your editor, this should be a breeze.

Here's a crazy example:

var options = mediaApi.withOptions()
					.includingCountOfItems()
					.havingPageSizeOf(10).atPage(2)
					.sortingBy().totalPlays().inDescendingOrder()
					.includingVideoField().videoId()
					.includingVideoField().title()
					.includingVideoField().shortDescription()
					.includingVideoField().longDescription()
					.includingVideoField().creationDate()
					.includingVideoField().publishedDate()
					.includingVideoField().lastModifiedDate()
					.includingVideoField().linkUrl()
					.includingVideoField().linkText()
					.includingVideoField().tags()
					.includingVideoField().videoStillUrl()
					.includingVideoField().thumbnailUrl()
					.includingVideoField().referenceId()
					.includingVideoField().duration()
					.includingVideoField().economics()
					.includingVideoField().playsTotal()
					.includingVideoField().playsTrailingWeek()
					.includingVideoField().videoUrl()
					.includingVideoField().renditions()
					.includingVideoField().iOSRenditions()
					.includingVideoField().FLVFullLength()
					.includingVideoField().videoFullLength()
					.httpMediaDelivery();

mediaApi.findAllVideos(options);

MediaApi Events

The MediaApi object also inherits from node's Event Emitter, allowing you to more easily manage callbacks.

// Abstracted handler
var findAllVideosHandler = function(err, jsonResponse) {
	console.log(jsonResponse);
}

// Register the handler
// Note the specific event name: 'find_all_videos'
mediaApi.on('find_all_videos', findAllVideosHandler);

// Make the call.
mediaApi.findAllVideos(mediaApi.withDefaultOptions());

All events are emitted with two arguments: err, jsonResponse.
Following node convention, the err argument will be null if no error occurred as will jsonResponse if an error did occur.

Emitted events will have a name in congruence with Brightcove's own command names:

• Video Read API - find_all_videos - find_video_by_id - find_videos_by_ids - find_related_videos - find_video_by_reference_id - find_videos_by_reference_ids - search_videos

• Playlist Read API - find_all_playlists - find_playlist_by_id - find_playlists_by_ids - find_playlist_by_reference_id - find_playlists_by_reference_ids

• Video Write API - create_video - update_video - delete_video

• Playlist Write API - create_playlist - update_playlist - delete_playlist

If you'd like programmatic or intellisense-friendly access to these, they can be accessed with the commands property:

// Register the handler 
// Specify the event name using the 'commands' enum
mediaApi.on(mediaApi.commands.find_all_videos, findAllVideosHandler);

// Make the call.
mediaApi.findAllVideos(mediaApi.withDefaultOptions());

OAuth API

How to use :

var brightcove = require('brightcove');
var	oauthApi = new brightcove.OAuthApi('myClientId', 'myClientSecret');

• getAccessToken (callback)

• createClientCredential (callback) (not yet implemented)

• deleteClientCredential (callback) (not yet implemented)

• getClientCredentialById (callback) (not yet implemented)

• getClientCredential (callback) (not yet implemented)

• updateClientCredential (callback) (not yet implemented)

Policy API

How to use :

var brightcove = require('brightcove');
var	oauthApi = new brightcove.OAuthApi('myClientId', 'myClientSecret');
var	policyApi = new brightcove.PolicyApi('myAccountId', oauthApi);

• getPolicyKey (callback)

• getPolicy (keyString, callback) + keyString Policy key string returned by getPolicyKey()

Proxy configuration

How to use :

var brightcove = require('brightcove');
var	mediaApi = new brightcove.MediaApi('myTokenOfAwesomeness', { proxy: 'xx.xx.xx.xx' });

Support / Fixes / Comments

Issues and comments should go through github. I'll do my best to manage them.

Any help is appreciated, too. I'll respond as quickly as I can to all pull requests and comments.

Useful Links

• Brightcove Media API Reference
• Brightcove Video Cloud Analytics API Reference