Ustream JavaScript SDK

JavaScript wrapper for Ustream's REST API.

• Installation

• Basic Usage

  • Paging Results

• Authentication API

  • Resource Owner Password Credentials Flow
  • Client Credentials Flow
  • Oauth Implicit Authentication Flow
  • Oauth Authorization Code Authentication Flow
  • Changing Authentication Credentials Workflow
  • Oauth Demo App

• Video API

  • Upload Video
  • Video Upload Status
  • List Videos
  • Get Video Details
  • Delete Video

• Channel API

  • Get Channel
  • Create Channel
  • Edit Channel
  • Delete Channel
  • List Channels
  • Check Password Protection Status
  • Enable Password Protection
  • Disable Password Protection
  • Get Embed Lock Status
  • Edit Embed Lock Status
  • Get Whitelisted URLs
  • Add URL to Whitelist
  • Remove URLs from Whitelist
  • Sharing Control
  • Change Branding Type

• Playlist API

  • Is Enabled
  • List Playlists
  • List Videos in Playlist
  • Create Playlist
  • Get Playlist Details
  • Add Video to Playlist
  • Delete Playlist

• Todo

• Testing

• Issues & Contributing

Installation

NPM

npm install ustream-sdk

Yarn

yarn add ustream-sdk

Basic Usage

All methods that access API resources, such as ustream.video.* or ustream.channel.* will return a Promise.

let Ustream = require('ustream-sdk')

// Set up instance using password authentication
let ustream = new Ustream({
    username: "...",
    password: "...",
    client_id: "...",
    client_secret: "...",
    token_type: "...", // Optional, default is bearer
    type: "password"
})

ustream.video.get(videoId).then((video) => {
    // Use video
}).catch((err) => {
    // Handle error
})

Paging Results

Some methods return data that is divided into many pages. These methods will return an object with helper methods to allow for easy access to both your data and next pages.

// Get list of channels
ustream.channel.list().then((pageableResult) => {
    // Access the list of channels
    let channels = pageableResult.data
    
    // Check if result set has a next page
    if (pageableResult.hasNextPage()) {
        // Retrieve the next page of channels
        pageableResult.next().then((nextPageResults) => {
            // Use next page's results
        })
    }
}).catch((err) => {
    console.warn(err)
})

Method	Returns	Description
next()	Promise<PageableResult>	Retrieves the next page of results. Returns null if a next page does not exist.
data()	array<Object>	Returns the data for a given page.
hasNextPage()	boolean	If true, next() will return a new page of data. If false, no next page exists.

Authentication API

Resource Owner Password Credentials Flow

let ustream = new Ustream({
    type: 'password',
    username: '...',
    password: '...',
    client_id: '...',
    client_secret: '...',
    token_type: "..." // Optional, default is bearer
})

Client Credentials Flow

let ustream = new Ustream({
    type: 'client_credentials',
    device_name: '...',
    scope: '...', // "broadcaster" or empty
    client_id: '...',
    client_secret: '...',
    token_type: "..." // Optional, default is bearer
})

Oauth Implicit Authentication Flow

let ustream = new Ustream({
  type: 'oauth_token',
  access_token: '...',
  token_type: 'bearer',
  expires_in: 86400
})

Oauth Authorization Code Authentication Flow

let ustream = new Ustream({
  type: 'oauth_code',
  client_id: '...',
  client_secret: '...',
  code: '...',
  redirect_uri: '...'
})

Password Credentials Flow for Analytics API

let ustream = new Ustream({
    type: 'password',
    username: '...',
    password: '...',
    client_id: '...',
    client_secret: '...',
    token_type: "jwt",
    endpoint: 'https://analytics-api.video.ibm.com',
    version: 'v1'
})

Note: The Analytics API uses only the jwt token type with a different API endpoint, and the targetted version is required.

Oauth Demo App

View Demo

Changing Authentication Credentials Workflow

If you choose to change your authentication workflow or swap out credentials after initializing Ustream, you can utilize the setAuthCredentials method.

ustream.setAuthCredentials({
    type: "<new authentication workflow>",
    ...
})

Video API

Upload Video

ustream.video.upload(channelId, file, opts)

Parameter	Type	Description
channelId	int	ID of an existing channel.
file.originalname	string	Name of file.
file.stream	ReadStream	File stream.
opts.title	string	Title of video.
opts.description	string	Description of video.
opts.protect	"public" "private"	Default is "private". If set to true, video will be published upon end of upload.

Video Upload Status

ustream.video.getStatus(channelId, videoId)

Parameter	Type	Description
channelId	int	ID of an existing channel.
videoId	int	ID of an existing video.

List Videos

ustream.video.list(channelId, pageSize, page)

Promise returns a Pageable result. See "Paging Results" section for details.

Parameter	Type	Description
channelId	int	Id of a channel.
pageSize	int	(optional) Default: 100. The number of results to show per page.
page	int	(optional) Default: 1. The page to retrieve.

Get Video Details

ustream.video.get(videoId)

Parameter	Type	Description
videoId	int	ID of an existing video.

Delete Video

ustream.video.remove(videoId)

Parameter	Type	Description
videoId	int	ID of an existing video.

Channel API

Get Channel

ustream.channel.get(channelId, opts)

Parameter	Type	Description
channelId	int	ID of an existing channel.
opts.detail_level	string	Default is null. If set to "minimal", the result set is limited to id, title, picture, owner and locks data. If the channel is protected, only minimal data can be retrieved without valid access token.

Create Channel

ustream.channel.create(channelId, opts)

Parameter	Type	Description
title	string	Channel title.
opts.description	string	Description of channel.

Edit Channel

ustream.channel.edit(channelId, title, opts)

Parameter	Type	Description
channelId	int	ID of an existing channel.
title	string	Title of channel.
opts.description	string	Description of channel.
opts.tags	string	Comma delimited list of channel tags

Delete Channel

ustream.channel.remove(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

List Channels

ustream.channel.list(pageSize, page)

Promise returns a Pageable result. See "Paging Results" section for details.

Parameter	Type	Description
pageSize	int	(optional) Default: 100. The number of results to show per page.
page	int	(optional) Default: 1. The page to retrieve.

Check Password Protection Status

ustream.channel.getPasswordProtectionStatus(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

Enable Password Protection

ustream.channel.enablePasswordProtection(channelId, password)

Parameter	Type	Description
channelId	int	ID of an existing channel.
password	string	The password used to access the channel.

Disable Password Protection

ustream.channel.disablePasswordProtection(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

Get Embed Lock Status

ustream.channel.getEmbedLockStatus(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

Edit Embed Lock Status

ustream.channel.setEmbedLock(channelId, isEmbedLocked)

Parameter	Type	Description
channelId	int	ID of an existing channel.
isEmbedLocked	boolean	Default is false. True to enable restricted embed access. False to disable.

Get Whitelisted URLs

ustream.channel.getUrlWhiteList(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

Add URL to Whitelist

ustream.channel.addUrlToWhiteList(channelId, url)

Parameter	Type	Description
channelId	int	ID of an existing channel.
url	string	URL to whitelisted domain.

Remove URLs from Whitelist

The API currently does not support removing a single URL from the whitelist. All URLs must be removed, then added.

ustream.channel.emptyUrlWhiteList(channelId, url)

Parameter	Type	Description
channelId	int	ID of an existing channel.
url	string	URL to whitelisted domain.

Sharing Control

ustream.channel.setSharingControl(channelId, canShare)

Parameter	Type	Description
channelId	int	ID of an existing channel.
canShare	boolean	If true, users will be able to share a channel's content.

Change Branding Type

ustream.channel.setBrandingType(channelId, type)

Parameter	Type	Description
channelId	int	ID of an existing channel.
type	string	The branding type.

Playlist API

Is Enabled

You can check whether playlists are enabled or disabled on the channel page.

ustream.isEnabled(channelId)

Parameter	Type	Description
channelId	int	ID of an existing channel.

Promise returns a boolean result stating if playlists are enabled for the channel or not.

List Playlists

Allows for the retrieval of the list of the playlists in the channel.

ustream.playlist.list(channelId, pageSize, page, includeEmptyLists)

Parameter	Type	Description
channelId	int	ID of an existing channel.
pageSize	int	How many entries to return in one request. Default is 50 and max is 50.
page	int	Starting page number. Default is 1.
includeEmptyLists	boolean	If the value is true then empty playlists will be returned (false by default).

Promise returns a Pageable result. See "Paging Results" section for details.

List Videos in Playlist

This service retrieves a list of videos that are in a specific playlist.

ustream.playlist.listVideos(playlistId, pageSize, page)

Parameter	Type	Description
playlistId	int	ID of an existing playlist.
pageSize	int	How many entries to return in one request. Default is 200 and max is 200.
page	int	Starting page number. Default is 1.

Promise returns a Pageable result. See "Paging Results" section for details.

Create Playlist

Create a new playlist in the channel.

ustream.playlist.create(channelId, title, options)

Parameter	Type	Description
channelId	int	ID of an existing channel.
title	string	The title of the playlist.
isEnabled	int	Whether the playlist is enabled or not. Possible values are 1 (enabled), 0 (disabled). The default is 1 (enabled).

Get Playlist Details

This entry point retrieves the details of a playlist.

ustream.playlist.get(playlistId)

Parameter	Type	Description
playlistId	int	ID of an existing playlist.

Add Video to Playlist

Add an already uploaded video in the channel to the playlist.

ustream.playlist.addVideo(playlistId)

Parameter	Type	Description
playlistId	int	ID of an existing playlist.
videoId	int	ID of an existing video.

Delete Playlist

Remove a playlist from a channel.

ustream.playlist.remove(channelId)

Parameter	Type	Description
playlistId	int	ID of an existing playlist.

Todo

• Authentication
  • Oauth implicit flow
  • Oauth authorization code flow
• Device passwords
  • Get device passwords
  • Create device password
  • Delete device password
• Playlists
  • List the user's playlists
  • Create a playlist
  • Playlist details
  • Modify a playlist
  • Delete a playlist
  • Playlist videos
  • Playlist video
  • Channel playlists
• Video (new endpoints)
  • Download video
  • Set up viewer authentication
  • Video expiration
  • Video thumbnail
  • Video labels
    • List all labels
    • Create label
    • Modify label
    • Delete label
    • List a video's labels
    • Add labels to video
    • Remove label from video
    • Edit video details
  • Video metadata
    • List all video metadata values
    • Set video metadata value
    • Remove video metadata value
  • Video caption
    • List captions
    • Show caption details
    • Modify caption details
    • Download captions
    • Upload captions
    • List supported caption languages
  • Video trim
  • Video copy
    • Check copy status
  • Video chapters
• Channel
  • List featured videos
  • Update featured videos
  • Get channel managers
  • Set up viewer authentication
  • Channel metadata
    • List metadata values
    • set metadata value
    • remove metadata value
    • List metadata display settings
    • set metadata display setting
    • remove metadata display setting
  • Recording broadcasts
    • Get recording status
    • Start recording
    • Stop recording
    • Auto-record
    • Get record time limit
• Stream settings
  • Multi quality streaming
• Custom metadata
  • List metadata fields
  • Create new metadata field
  • Delete metadata field
• Ingest settings
  • Get ingest settings
• User
  • List channels
  • List videos
  • Create label
  • Update label
  • List labels
  • Delete label
• Analytics
  • List of unique viewers for all contents
  • List of unique viewers for a specific content type
  • Raw view export for a given time period
  • Raw view export for a specific content type for a given time period
  • [] Sum total view number for a given period for all contents
  • [] Sum total view number for a given period and a specific content type
  • [] Number of sum unique devices for a given period and all contents
  • [] Number of sum unique devices for a given period and a specific content type
  • ...
• Other
  • Improve test coverage

Testing

All tests are located in the /test directory. To execute the testing suite, or check for style guide violations, run the following command.

npm run test

Issues and Contributing

Have a feature request or bug report? Create an entry in the issue tracker, and include as much detail as possible. I usually reply within 12 hours.

Code contributions must adhere to the contribution guidelines.