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
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.
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:
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.
npm i --save opentok-accelerator-coreconst AccCore = require('opentok-accelerator-core');<script src="path/to/browser/opentok-accelerator-core.js"></script>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.
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'],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 stream connection data (subscriber only)
* @param {Object} stream - The new stream (subscriber only)
*/
streamContainers(pubSub, type, data, stream){
return {
publisher: {
camera: '#cameraPublisherContainer',
screen: '#screenPublisherContainer',
},
subscriber: {
camera: '#cameraSubscriberContainer',
screen: '#screenSubscriberContainer',
},
}[pubSub][type];
},
controlsContainer: '#videoControls',If you need to support an OpenTok session with more than 300 connections, set largeScale to true. This option is set to false by default.
largeScale: false,The communication properties relate to the multi-party communication provided by Core:
autoSubscribedictates whether or notCoreautomatically subscribes to new streams and is set totrueby default.subscribeOnly, which is set tofalseby default, allows users to join an OpenTok session and subscribe to streams without publishing any audio or video.connectionLimitlimits the number of parties that may publish/subscribe to the session.callPropertiesallows for customization of the UI.
communication: {
autoSubscribe: true,
subscribeOnly: false,
connectionLimit: null,
callProperties: myCallProperties,
},See more on manually subscribing to streams below.
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',
}
};Initialize Core:
const otCore = new AccCore(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 typeSee an example of the publisher, subscriber, and meta data below.
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 streamFull documentation for the Core API can be found here.
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,
custom: 0,
total: 1,
},
subscribers: {
camera: 2,
screen: 1,
custom: 0,
total: 3,
},
},
publishers: {
camera: {
'OT_d18d5027-21eb-093f-8c18-e3959f3e7585': OTPublisherObject,
},
screen: {},
custom: {},
},
subscribers: {
camera: {
'OT_d18nd82s-21eb-4b3f-82n8-e3nd723e7585': OTSubscriberObject,
'OT_d38n82s-9n2b-4sdf-82n8-eadnfdf92nf90': OTSubscriberObject,
},
screen: {
'OT_nd872bd9s-0d82-n431-809l-k1kdjd72mdks': OTSubscriberObject,
},
custom: {
'OT_d38n82s-21eb-8dn8-8c18-eadnfdf92nf90': 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.
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.
- Managing presence without any audio/video, using OpenTok sessions.
You can also use Accelerator Core and the SDK Wrapper in conjunction with each other since multiple instances of each may be created and used simultaneously.
Interested in contributing? We ❤️ pull requests! See the Contribution guidelines.
We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:
- Open an issue on this repository
- See https://support.tokbox.com/ for support options
- Tweet at us! We're @VonageDev on Twitter
- Or join the Vonage Developer Community Slack
- Check out the Developer Documentation at https://tokbox.com/developer/