node-brightcove

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

Please excuse the mess while I write up documentation and finish the MediaApi Write calls!

• Installation
• Media API
  • Calls
  • Options
  • Events
• Analytics API (not yet implemented)

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

• (not yet implemented)

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 (not yet implemented)

• 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());

Analytics API

Brightcove's analytics API is currently in beta. Expect it here, soon!

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