Parameters

type (String) — The string identifying the type of event. See TB events.

listener (Function) — The function to be invoked when the Session object dispatches the event.

See

Session events

removeEventListener()

ConnectionEvent

SessionConnectEvent

SessionDisconnectEvent

SignalEvent

StreamEvent

Events dispatched

streamDestroyed (StreamEvent) — Dispatched when a stream is destroyed as a result of the call to this method.

Example

The following example calls the cleanup method in response to a sessionDisconnected event:

var sessionID = "1690446fcddb5a4e6dd5ec1fcd1415312a18aae38";
apiKey = 1234;

var session = TB.initSession(sessionID);
session.addEventListener("sessionDisconnected", sessionDisconnectHandler);
session.connect(apiKey, token);

function sessionDisconnectHandler(sessionDisconnectEvent) {
    session.cleanUp();
}

See

unpublish()

unsubscribe()

Parameters

archive (Archive) — The archive to close.

Events dispatched

archiveClosed (ArchiveEvent) — The archive is closed successfully. The first element of the archives property of the event object is the Archive object that was closed.

Parameters

apiKey (String) — The API key that TokBox provided you when you registered for the OpenTok API.

token (String) — The session token. You generate a session token by connecting to the TokBox server using the OpenTok server-side libraries. While using the staging environment, you can use the 'devtoken' or 'moderator_token' test token strings token in place of a proper server-generated token. Use the 'devtoken' test string to assign the role of a publisher. Use the 'moderator_token' test token string to assign the role of a moderator. (The 'moderator_token' string was added in OpenTok v0.91.5.) For more information, see Connection token creation, Moving from testing to production, and OpenTok server-side libraries reference.

properties (Object) — (Optional) This object contains the following properties:

• connectionData (String) — A string containing metadata describing the connection. For example, you can pass the user ID, name, or other data describing the connection. Set this string only when testing with the staging environment and using a test token string (such as 'devtoken') as the token parameter value. The length of the string is limited to 1000 characters.

Important: When you generate a user token string (as in the production environment), pass the connection data string to the generateToken() method of the OpenTok server-side library. Passing the data on the server prevents a client from sending data insecurely. The connectionData string passed to the client-side Session.connect() method is ignored.

The data property of the Connection object is set to the connection data string.

Clients can access the Connection object in event listeners for the sessionConnected event, the connectionCreated event, and the streamCreated event. The sessionCreated and connectionCreated events each have a connections property, which is an array of Connection objects. The sessionCreated and streamCreated events each have a streams property, which is an array of Stream objects. (Each Stream object has a connection property, which is a Connection object.)

Added in OpenTok v0.91.20.

• detectConnectionQuality (Number) — A value of either 0 or 1, which determines whether the connectionQuality property of the connection property of the Session object will be set (1) or not (0). The connectionQuality property of the connection property of the Session object includes information about the downstream bandwidth, the upstream bandwidth, and the latency at the time of the connection. (See the connection property.)

Events dispatched

exception (ExceptionEvent) — Dispatched locally in the event of an error.

connectionCreated (ConnectionEvent) — Dispatched on other clients.

sessionConnected (SessionConnectEvent) — Dispatched locally when the connection is established.

Example

The following code initializes a session and sets up an event listener for when the session connects:

var sessionID = "123456789abcdef0123456789abcdef012345678"; // replace with your session ID
var apiKey = 1234; // replace with your API key
var token = "devtoken"; // replace with your connection token

var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectHandler);
session.connect(apiKey, token);

function sessionConnectHandler(sessionConnectEvent) {
    // 
}

The event listener for the sessionConnect event can process the SessionConnectEvent object. (In this example, the sessionConnectHandler() function is the event listener.) For instance, it can loop through the array of the current streams in the session and present them on the page.

See

TB.initSession()

Parameters

apiKey (String) — Your API key.

type (String) — The type of archive to create.

• "perSession" — Defines an archive that records all streams in a session.
• "perStream" — Defines an archive that can be used to record selected streams in a session.

title (String) — The title for the archive (such as "Recording D — Nov. 22"). This parameter is optional.

Events dispatched

archiveCreated (ArchiveEvent) — The archive is created successfully. The first element of the archives property of the event object is the Archive object that was created. Note that you should store a record of the archive IDs of archives you create, so that you can reference them later when loading the archive for playback.

exception (ArchiveEvent) — The OpenTok library could not load the archive. The TB object dispatches this event. The event object includes these properties:

See

Session.startRecording()

Stream.startRecording()

Events dispatched

sessionDisconnected (SessionDisconnectEvent) — Dispatched locally when the connection is disconnected.

connectionDestroyed (ConnectionEvent) — Dispatched on other connections, along with the streamDestroyed event (as warranted).

streamDestroyed (StreamEvent) — Dispatched if streams are lost as a result of the session disconnecting.

See

cleanup()

SessionDisconnectEvent

StreamEvent

Parameters

connection (Object) — The connection to be disconnected from the session. This value can either be a Connection object or a connection ID (which can be obtained from the connectionId property of the Connection object).

Events dispatched

connectionDestroyed (ConnectionEvent) — On clients other than which had the connection terminated.

exception (ExceptionEvent) — The user's role does not allow forcing other user's to disconnect.

sessionDisconnected (SessionDisconnectEvent) — On the client which has the connection terminated.

streamDestroyed (StreamEvent) — If streams are stopped as a result of the connection ending.

Parameters

stream (Stream) — The stream to be unpublished.

Events dispatched

exception (ExceptionEvent) — The user's role does not allow forcing other users to unpublish.

streamDestroyed (StreamEvent) — The stream has been unpublished. The Session object dispatches this on all clients subscribed to the stream, as well as on the publisher's client.

Parameters

stream (Stream) — The stream for which you want to find the Publisher.

Returns

Publisher — A Publisher object for the specified stream. Returns null if there is no local Publisher object for the stream.

See

forceUnpublish()

Subscriber

StreamEvent

Returns

StateManager — The StateManager object for the Session.

See

StateManager

Parameters

stream (Stream) — The stream for which you want to find subscribers.

Returns

Array[Subscriber] — An array of Subscriber objects for the specified stream.

See

unsubscribe()

Subscriber

StreamEvent

Parameters

archiveId (String) — The archive ID of the archive to be loaded.

Events dispatched

archiveLoaded (ArchiveEvent) — The archive is loaded successfully. The first element of the archives property of the event object is the loaded Archive object. Dispatched by the Session object.

exception (ExceptionEvent) — The OpenTok library could not load the archive. The TB object dispatches this event. The code and title properties of the event object can be set to the following:

Parameters

replaceElementId (String) — The id attribute of the existing DOM element that the Publisher video replaces. If you do not specify a replaceElementId, the application appends a new DOM element to the HTML body. Note: Set the height and width properties of the properties parameter to set the dimensions of the publisher video; do not set the height and width of the container element (using CSS).

properties (Object) — Optional. This is an optional object that contains the following properties (each of which are optional):

• cameraName (String) — The name of a camera to use. You can obtain an array of Camera objects by calling the DeviceManager.detectDevices() method. The DeviceManager dispatches a devicesDetected event, which includes an array of Camera objects. Each Camera object has a name property. If you specify an invalid camera name, the Publisher object dispatches an invalidDeviceName event. The event is a DeviceEvent object, with the camera.name property set to the invalid name and the camera.status property set to "invalid".
• encodedHeight (Number) — The desired height, in pixels, of the resolution of the encoded video stream. Specify a number from 1 to 640. Use this value, along with the encodedWidth property of the properties parameter, to set the desired encoded resolution of the video stream. If you do not specify a value, the height of the encoded video stream is 264 pixels. If the client's bandwidth does not support the desired encoding resolution, OpenTok will encode using the nearest supported resolution. When the actual encoded resolution is determined, the Session object dispatches a streamPropertyChanged event. The changedProperty property of the StreamPropertyChangedEvent object is set to "quality". The encodedHeight property of the newValue property of the event is set to the height of the resolution of the encoded video stream. (Note: use the height property of the properties parameter to set the height of the Publisher video on the page.) Added in OpenTok v0.91.35.
• encodedWidth (Number) — The desired width, in pixels, of the resolution of the encoded video stream. Specify a number from 1 to 640. Use this value, along with the encodedHeight property of the properties parameter, to set the desired encoded resolution of the video stream. If you do not specify a value, the height of the encoded video stream is 198 pixels. If the client's bandwidth does not support the desired encoding resolution, OpenTok will encode using the nearest supported resolution. When the actual encoded resolution is determined, the Session object dispatches a streamPropertyChanged event. The changedProperty property of the StreamPropertyChangedEvent object is set to "quality". The encodedWidth property of the newValue property of the event is set to the width of the resolution of the encoded video stream. (Note: use the width property of the properties parameter to set the width of the Publisher video on the page.) Added in OpenTok v0.91.35.
• height (Number) — The desired height, in pixels, of the displayed Publisher video stream (default: 198). Note: Use the height and width properties to set the dimensions of the publisher video; do not set the height and width of the container element (using CSS).
• microphoneEnabled (Boolean) — Deprecated in OpenTok v0.91.9. Use the publishAudio property instead.
• microphoneGain (Number) — The desired microphone gain, between 0 and 100, when the Publisher is first published (default: 50). After you publish the stream, you can adjust the microphone gain by calling the setMicrophoneGain() method of the Publisher object. Added in OpenTok v0.91.19.
• microphoneName (String) — The name of a microphone to use. You can obtain an array of Microphone objects by calling the DeviceManager.detectDevices() method. The DeviceManager dispatches a devicesDetected event, which includes an array of Microphone objects. Each Microphone object has a name property. If you specify an invalid microphone name, the Publisher object dispatches an invalidDeviceName event. The event is a DeviceEvent object, with the microphone.name property set to the invalid name and the microphone.status property set to "invalid".
• mirror (Boolean) — Whether the publisher's video image is mirrored in the publisher's page. The default value is true (the video image is mirrored). This property does not affect the display on other subscribers' web pages .
• name (String) — The name for this stream. The name appears at the bottom of Subscriber videos. The default value is "" (an empty string). Setting this to a string longer than 1000 characters results in an runtime exception.
• publishAudio (Boolean) — Whether to initially publish audio for the stream (default: true). Added in OpenTok v0.91.9. Note: Prior to calling the publsh() method, set the showMicSettings property of a DeviceManager object to false if you are publishing in video-only mode.
• publishVideo (Boolean) — Whether to initially publish video for the stream (default: true). Added in OpenTok v0.91.9. Note: Prior to calling the publsh() method, set the showVideoSettings property of a DeviceManager object to false if you are publishing in audio-only mode.
• reportMicLevels (Boolean) — Whether the Session object will dispatch microphoneLevelChanged events for the Publisher's stream. (See the documentation for the microphoneLevelChanged event). The Session object for all clients connected clients will dispatch this event for the stream (if you set this property to true). Added in OpenTok v0.91.51.
• style (Object) — An object containing properties that define the initial appearance of some user interface controls of the Publisher. Added in OpenTok v0.91.19. The style object includes the following properties:
  
  
  • backgroundImageURI (String) — A URI for an image to display as the background image when a video is not displayed. (A video may not be displayed if you call publisherVideo(false) on the Publisher object). You can pass an http or https URI to a PNG, JPEG, or non-animated GIF file location. You can also use the data URI scheme (instead of http or https) and pass in base-64-encrypted PNG data, such as that obtained from the Publisher.getImgData() method. For example, you could set the property to "data:VBORw0KGgoAA...", where the portion of the string after "data:" is the result of a call to Publisher.getImgData(). If the URL or the image data is invalid, the property is ignored (the attempt to set the image fails silently). Added in OpenTok v0.91.33.
  • buttonDisplayMode (String) — How to display the microphone controls and settings button. Possible values are: "auto" (controls are displayed when the stream is first displayed and when the user mouses over the display), "off" (controls are not displayed), and "on" (controls are displayed). The showMicButton and showSettingsButton properties define whether each individual control is displayed.
  • nameDisplayMode (String) — Whether to display the stream name. Possible values are: "auto" (the name is displayed when the stream is first displayed and when the user mouses over the display), "off" (the name is not displayed), and "on" (the name is displayed).
  • showMicButton (Boolean) — Whether to display the microphone controls.
  • showSettingsButton (Boolean) — Whether to display the settings buttons.
• width (Number) — The desired width, in pixels, of the displayed Publisher video stream (default: 264). Note: Use the height and width properties to set the dimensions of the publisher video; do not set the height and width of the container element (using CSS).
• wmode (String) — Set this property to set the transparency of the SWF object used to display the stream. Possible values match the wmode values for the object and embed tags for a SWF file: "opaque", "transparent" (the default), or "window". (For more information, see Flash OBJECT and EMBED tag attributes (at adobe.com).

Returns

Publisher — The Publisher object for this stream.

Events dispatched

exception (ExceptionEvent) — The user's role does not allow publishing.

streamCreated (StreamEvent) — The stream has been published. The Session object dispatches this on all clients subscribed to the stream, as well as on the publisher's client.

Example

The following example publishes a video once the session connects:

var sessionID = "1690446fcddb5a4e6dd5ec1fcd1415312a18aae38";
var apiKey = 4444;
var token = "Replace with the TokBox token string provided to you."
var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectHandler);
session.connect(apiKey, token);

function sessionConnectHandler(event) {
    var div = document.createElement('div');
    div.setAttribute('id', 'publisher');
    var publisherContainer = document.getElementById('publisherContainer');
    publisherContainer.appendChild(div);
    var divProps = {width: 400, height:300, name:"Bob's stream"};
    publisher = session.publish('publisher', divProps);
}

See

connect()

publishers

unpublish()

Publisher

Parameters

type (String) — The string identifying the type of event.

listener (Function) — The event listener function to remove.

See

addEventListener()

Events dispatched

exception (ExceptionEvent) — The user's role does not permit signalling.

signalReceived (SignalEvent) — The signal is received. (Dispatched on all subscribing clients.)

See

SignalEvent

Parameters

archive (Archive) — The archive to record to.

Events dispatched

exception (ExceptionEvent) — The OpenTok library could not load the archive. The TB object dispatches this event. The code and title properties of the event object can be set to the following:

sessionRecordingStarted (Event) — The session has started archiving.

Errors thrown

The application throws an error if the archive is a loaded archive (used for playback), rather than a created archive (used for recording).

An error is also thrown if the archive type is not "perSession".

See

stopRecording()

Parameters

archive (Archive) — The archive to stop recording to.

Events dispatched

exception (ExceptionEvent) — The OpenTok library could not load the archive. The TB object dispatches this event. The event object includes these properties:

sessionNotRecording (Event) — The stream is not currently being recorded. (Calling this method has no effect.) The first element of the streams property of the StreamEvent object is the Stream object representing the stream object. The Session object dispatches this event.

sessionRecordingStopped (Event) — The session has stopped archiving.

Errors thrown

The application throws an error if the archive is a loaded archive (used for playback), rather than a created archive (used for recording).

An error is also thrown if the archive type is not "perSession".

See

startRecording()

Parameters

stream (Stream) — Stream object representing the stream to which we are trying to subscribe.

replaceElementId (String) — String ID of the existing DOM element that the Subscriber replaces. If you do not specify a replaceElementId, the application appends a new DOM element to the HTML body.

properties (Object). This is an optional object that contains the following properties:

• audioEnabled (Boolean) — Deprecated in OpenTok v0.91.9. Use the subscribeToAudio property instead.
• audioVolume (Number) — The desired audio volume, between 0 and 100, when the Subscriber is first opened (default: 50). After you subscribe to the stream, you can adjust the volume by calling the setAudioVolume() method of the Subscriber object. This volume setting affects local playback only; it does not affect the stream's volume on other clients. Added in OpenTok v0.91.19.
• height (Number) — The desired height, in pixels, of the displayed Subscriber video stream (default: 198).
• style (Object) — An object containing properties that define the initial appearance of some user interface controls of the Subscriber. Added in OpenTok v0.91.19. The style object includes the following properties:
  
  
  • backgroundImageURI (String) — A URI for an image to display as the background image when a video is not displayed. (A video may not be displayed if you call subscribeToVideo(false) on the Subscriber object, or if the publisher does not publish video). You can pass an http or https URI to a PNG, JPEG, or non-animated GIF file location. You can also use the data URI scheme (instead of http or https) and pass in base-64-encrypted PNG data, such as that obtained from the Subscriber.getImgData() method. For example, you could set the property to "data:VBORw0KGgoAA...", where the portion of the string after "data:" is the result of a call to the Subscriber.getImgData() method. If the URL or the image data is invalid, the property is ignored (the attempt to set the image fails silently). Added in OpenTok v0.91.33.
  • buttonDisplayMode (String) — How to display the speaker controls. Possible values are: "auto" (controls are displayed when the stream is first displayed and when the user mouses over the display), "off" (controls are not displayed), and "on" (controls are displayed).
  • nameDisplayMode (String) — Whether to display the stream name. Possible values are: "auto" (the name is displayed when the stream is first displayed and when the user mouses over the display), "off" (the name is not displayed), and "on" (the name is displayed).
• subscribeToAudio (Boolean) — Whether to initially subscribe to audio (if available) for the stream (default: true). Added in OpenTok v0.91.9.
• subscribeToVideo (Boolean) — Whether to initially subscribe to video (if available) for the stream (default: true). Added in OpenTok v0.91.9.
• width (Number) — The desired width, in pixels, of the displayed Subscriber video stream (default: 264).
• wmode (String) — Set this property to set the transparency of the SWF object used to display the stream. Possible values match the wmode value for the object and embed tags for a SWF file: "opaque", "transparent" (the default), or "window". (For more information, see Flash OBJECT and EMBED tag attributes (at adobe.com).

Returns

Subscriber — The Subscriber object for this stream. Stream control functions are exposed through the Subscriber object.

Example

The following code subscribes to available streams at the time that a session is connected

var sessionID = "1690446fcddb5a4e6dd5ec1fcd1415312a18aae38";
apiKey = 1234;
var streams = [];

var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectHandler);
session.connect(apiKey, token);

function sessionConnectHandler(event) {
    for (var i = 0; i < event.streams.length; i++) {
        var stream = event.streams[i];
        displayStream(stream);
    }
    streams = event.streams;
}

function displayStream(stream) {
    var div = document.createElement('div');
    div.setAttribute('id', 'stream' + stream.streamId);
    var streamsContainer = document.getElementById('streamsContainer');
    streamsContainer.appendChild(div);
    var divProps = {width: 400, height:300};
    subscriber = session.subscribe(stream, 'stream' + stream.streamId, divProps);
}

You can also add an event listener for the streamCreated event. The Session object dispatches this event when a new stream is created.

session.addEventListener("streamCreated", streamCreatedHandler);

function streamCreatedHandler(event) {
    for (var i = 0; i < event.streams.length; i++) {
        var stream = event.streams[i];
        displayStream(stream);
        streams.push(stream);
    }
}

Parameters

publisher (Publisher) — The Publisher object to stop streaming.

Events dispatched

streamDestroyed (StreamEvent) — The stream associated with the Publisher has been destroyed. Dispatched on the Publisher's browser and on the browser for all connections subscribing to the publisher's stream.

Example

The following example publishes a stream to a session and adds a Disconnect link to the web page. Clicking this link causes the stream to stop being published.

<script>
    var sessionID = "1690446fcddb5a4e6dd5ec1fcd1415312a18aae38";
    var apiKey = 4444;
    var token = "Replace with the TokBox token string provided to you."
    var session = TB.initSession(sessionID);
    session.addEventListener("sessionConnected", sessionConnectHandler);
    session.connect(apiKey, token);
    var publisher;
    
    function sessionConnectHandler(event) {
        var div = document.createElement('div');
        div.setAttribute('id', 'publisher');
        var publisherContainer = document.getElementById('publisherContainer');
        publisherContainer.appendChild(div);
        var divProps = {width: 400, height:300, name:"Bob's stream"};
        publisher = session.publish('publisher', divProps);
    }
    function unpublsh() {
        session.unpublish(publisher);
    }
</script>

<body>

    <div id="publisherContainer/>
    <br/>

    <a href="javascript:unpublish()">Disconnect</a>

</body>

See

publish()

streamDestroyed event

Parameters

subscriber (Subscriber) — The Subscriber object to unsubcribe.

Example

The following code subscribes to available streams at the time that a session is connected. For each stream, the code also adds an Unsubscribe link.

var sessionID = "1690446fcddb5a4e6dd5ec1fcd1415312a18aae38";
apiKey = 1234;
var streams = [];

var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectHandler);
session.connect(apiKey, token);

function sessionConnectHandler(event) {
    for (var i = 0; i < event.streams.length; i++) {
        var stream = event.streams[i];
        var div = document.createElement('div');
        div.setAttribute('id', 'stream' + stream.streamId);
        
        var aLink = document.createElement('a');
        aLink.setAttribute('href', 'javascript: unsubscribe(' + stream.streamId + ')');
        aLink.innerHTML = "Unsubscribe";
        
        var streamsContainer = document.getElementById('streamsContainer');
        streamsContainer.appendChild(div);
        streamsContainer.appendChild(aLink);
        
        var divProps = {width: 400, height:300};
        var subscriber = session.subscribe(stream, 'stream' + stream.streamId, divProps);
        streams = event.streams;
    }
}
function unsubscribe(streamId) {
    for (var i = 0; i < streams.length; i++) {
        var stream = streams[i];
        if (stream.streamId == streamId) {
            session.unsubscribe(stream);
        }
    }
}

See

subscribe()