OpenTok's Accelerator Core JS provides easy integration for OpenTok libraries. Whether you've already built your application using the OpenTok platform or are just getting started, Accelerator Core JS helps you implement:
- Multi-Party Audio/Video Communication
- Text Chat
- Screen Sharing
- Annotation
- Archiving
##Quickstart
To start using audio/video communication with OpenTok's libraries go to Using Accelerator Core. To implement a more granular and complex management for OpenTok's session you can check Using Accelerator Core JS with SDK Wrapper.
##Using Accelerator Core
OpenTok Accelerator Core JS
provides a simple way to integrate real-time audio/video into your web application using the OpenTok Platform. It also integrates with, manages, and provides a single API for the following accelerator packs:
##Sample Applications
There are two sample applications for Core
. The React sample application was built with Create React App and uses webpack to transpile code. The other sample application is built with vanilla JavaScript.
##Installation
$ npm i --save opentok-accelerator-core
const otCore = require('opentok-accelerator-core');
<script src="path/to/browser/opentok-accelerator-core.js"></script>
###Configuration
Core
can be configured in a number of ways, but the only required options property is credentials
, which includes an OpenTok API Key, Session ID, and Token. These can be obtained from the developer dashboard or generated with one of the OpenTok Server SDKs.
const options = {
credentials: {
apiKey: yourOpenTokApiKey,
sessionId: yourOpenTokSessionId,
token: yourOpenTokToken,
},
Other properties are the following.
####Packages
The packages
property specifies which accelerator packs should be included in the application. If using a bundler like webpack
or Browserify
, you'll need to install the additional packages using npm
. Otherwise Core
will look for them in global scope.
packages: ['textChat', 'screenSharing', 'annotation', 'archiving'],
####Containers
The streamContainers
property is a function that specifies which DOM element should be used as a container for a video stream. The controlsContainer
property specifies the element to be used as the container for the local audio/video and accelerator pack controls. These elements can either be query selectors or references to DOM elements. The default containers are specified below. If these containers do not exist in the DOM, Core
will be append new elements to the body
.
/**
* @param {String} pubSub - 'publisher' or 'subscriber'
* @param {String} type - 'camera' or 'screen'
* @param {*} data - Parsed connection data associated with the stream
*/
streamContainers(pubSub, type, data){
return {
publisher: {
camera: '#cameraPublisherContainer',
screen: '#screenPublisherContainer',
},
subscriber: {
camera: '#cameraSubscriberContainer',
screen: '#screenSubscriberContainer',
},
}[pubSub][type];
},
controlsContainer: '#videoControls',
####Communication Options
The communication
properties relate to the multi-party communication provided by Core
. autoSubscribe
dictates whether or not Core
automatically subscribes to new streams and is set to true
by default. connectionLimit
limits the number of parties that may publish/subscribe to the session. callProperties
allows for customization of the UI.
communication: {
autoSubscribe: true,
connectionLimit: null,
callProperties: myCallProperties,
},
See more on manually subscribing to streams below.
####Accelerator Pack Properties The remainder of the options properties are specific to individual accelerator packs.
textChat: {
name: `David`,
waitingMessage: 'Messages will be delivered when other users arrive',
container: '#chat',
alwaysOpen: true,
},
screenSharing: {
extensionID: 'yourChromeExtensionId',
extensionPathFF: 'yourFireFoxExtensionURL',
annotation: true, // 'true' required if sharing current browser window
externalWindow: false,
dev: true, // Allow http in development(localhost)
screenProperties: null,
},
annotation: {
items: myToolbarItems,
colors: myColorPalette,
onScreenCapture: myScreenCaptureCallback,
absoluteParent: {
publisher: '#videoWrapper',
subscriber: '#videoWrapper',
}
},
archiving: {
startURL: 'https://yourapi.com/startArchive',
stopURL: 'https://yourapi.com/stopArchive',
}
};
##Usage
Initialize Core
:
otCore.init(options);
Connect to the session:
otCore.connect().then(() => this.setState({ connected: true }));
Core
also internally maintains the state of your OpenTok session for you. Calling otCore.state()
returns an object containing:
streams => All current streams
streamMap => The map of stream ids to publisher/subscriber ids
publishers => All current publishers
subscribers => All current subscribers
meta => The count of all current publishers and subscribers by type
See an example of the publisher, subscriber, and meta data below.
##Exploring the code
Aside from the connect
method the other Core
API methods include:
getAccPack => Get a reference to an individual accelerator pack
startCall => Publish audio/video and subscribe to streams
endCall => Stop publishing and unsubscribe from all streams
getSession => Get the OpenTok Session Object
forceDisconnect => Force a remote connection to leave the session
forceUnpublish => Force the publisher a stream to stop publishing
getPublisherForStream => Get the local publisher object for a stream
getSubscribersForStream => Get the local subscriber objects for a stream
toggleLocalAudio => Toggle publishing local audio
toggleLocalVideo => Toggle publishing local video
toggleRemoteAudio => Toggle subscribing to remote audio
toggleRemoteVideo => Toggle subscribing to remote video
signal => Send a signal using the OpenTok signaling API [1]
state => Get the OpenTok session state
subscribe => Manually subscribe to a stream
Full documentation for the Core
API can be found here.
###Events
Core
exposes a number of events, including all OpenTok session events, which can be accessed using the on
method:
otCore.on('streamCreated', callback);
The data passed to the callback for the following events . . .
const events = [
'subscribeToCamera',
'unsubscribeFromCamera',
'subscribeToScreen',
'unsubscribeFromScreen',
'startScreenShare',
'endScreenShare',
];
will always include the current publishers
, subscribers
, and a meta
object which provides a count of the current publishers
and subscribers
, making it easy to keep your UI in sync. If subscribing to a new stream, the subscriber
object will be included as well.
meta: {
publishers: {
camera: 1,
screen: 0,
total: 1,
},
subscribers: {
camera: 2,
screen: 1,
total: 3,
},
},
publishers: {
camera: {
'OT_d18d5027-21eb-093f-8c18-e3959f3e7585': OTPublisherObject,
},
screen: {}
},
subscribers: {
camera: {
'OT_d18nd82s-21eb-4b3f-82n8-e3nd723e7585': OTSubscriberObject,
'OT_d38n82s-9n2b-4sdf-82n8-eadnfdf92nf90': OTSubscriberObject,
},
screen: {
'OT_nd872bd9s-0d82-n431-809l-k1kdjd72mdks': OTSubscriberObject,
},
}
The full list of events can be seen here.
There may be situations where you need to manually subscribe to streams. For example, you need to call setState
in your React component, wait for the update to finish and your component to re-render so that the container for the new stream is available before subscribing. In this case, you can set autoSubscribe
to false
, listen for new streams, update your state, and subscribe once the update is complete:
otCore.on('streamCreated', ({ stream }) => {
this.setState({ streams: streams.concat(stream) }, () => {
otCore.subscribe(stream);
});
});
Default icons and styling for accelerator pack components are provided by opentok-solutions-css
, which is available as an npm module or from our CDN. To customize the layout and styling in your application, simply override these CSS rules with your own.
##Using Accelerator Core JS with SDK Wrapper
Accelerator Core
will cover the use cases for most projects. If you have a special use case, your first course of action should be to open a Github issue. If there is a way that we can add functionality or increase the flexibility of core or one of the accelerator packs while maintaining backwards compatibility, we’re happy to do so. Another option is to use the OpenTok JS SDK Wrapper. The SDK Wrapper
extends the functionality of the OpenTok JS Client library with the same state management provided by Accelerator Core
. Some use cases for the SDK Wrapper may be:
- Creating a messaging or signaling layer using OpenTok sessions.
- Running multiple sessions simultaneously in the same application instance.
- Managing presence without any audio/video, using OpenTok sessions.
You can also use Accelerator Core and the SDK Wrapper in conjunction with each other. While Core is a singleton, the SDK Wrapper provides a constructor, meaning that multiple instances may be created and used at the same time.