Session class

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

Example

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

var apiKey = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects
var sessionID = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects

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

function sessionDisconnectHandler(sessionDisconnectEvent) {
    event.preventDefault();
    // Do other things, such as remove and adjust other DOM elements
    // before calling the following:
    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 signed up for an OpenTok account.

token (String) — The session token. You generate a session token using the OpenTok server-side libraries or the Dashboard page. For more information, see Connection token creation.

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

• connectionData (String) — Deprecated in OpenTok v0.91.59.

When you generate a user token string pass the connection data string to the generate_token() method of the OpenTok server-side libraries. You can also generate a token and define connection data on the Dashboard page.

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.)

• detectConnectionQuality (Number) — A value of either 0 or 1, which determines whether the connection.connectionQuality property of the Session object will be set (1) or not (0). The connection.connectionQuality 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.)
  
  Important: Setting this parameter to 1 will delay the connection to a session by 15 seconds. And the connection.connectionQuality property of a Session object is only available once the Session object dispatches the sessionConnected event. As an alternative, if you do not need to know the connection quality before publishing, you can leave this property set to 0 (the default), and check the quality property of the Stream object corresponding to a Stream the client publishes (see Stream.quality property). However, you may want to have the connection quality information before you publish a stream; in this case, set detectConnectionQuality to 1 and check the the connection.connectionQuality property of the Session object once the Session dispatches the sessionConnected event.

Events dispatched

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

connectionCreated (ConnectionEvent) — Dispatched by the Session object on all clients connected to the session.

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

Example

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

var apiKey = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects
var sessionID = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects
var token = ""; // Replace with a generated token that has been assigned the moderator role.
                // See https://dashboard.tokbox.com/projects

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. You get an API key when you sign up for an OpenTok account.

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 (event.code = 1530), or the specified stream is not publishing to the session (event.code = 1535).

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) — Optional. Pass in this parameter only if you are not passing in a Publisher object to the Session.publish() method. This parameter is the id attribute of the existing DOM element that the new 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. Pass in this parameter only if you are not passing in a Publisher object to the Session.publish() method. This is an optional object that contains properties defining the publisher. For a description of these properties, see the description of the properties parameter of the TB.initPublisher() method.

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 apiKey = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects
var sessionId = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects
var token = ""; // Replace with a generated token that has been assigned the moderator role.
                // See https://dashboard.tokbox.com/projects
var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectHandler);
session.connect(apiKey, token);

function sessionConnectHandler(event) {
    var divProps = {width: 400, height:300, name:"Bob's stream"};
    publisher = TB.initPublisher(API_KEY, 'publisher', divProps);
                       // This assumes that there is a DOM element with the ID 'publisher'.
    session.publish(publisher);
}

See

Publisher

TB.initPublisher()

Session.connect()

Session.unpublish()

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.
• 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. 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).
  • 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).
• subscribeToVideo (Boolean) — Whether to initially subscribe to video (if available) for the stream (default: true).
• 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 = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects
var token = ""; // Replace with a generated token that has been assigned the moderator role.
                // See https://dashboard.tokbox.com/projects

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);
    }
}

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);
    }
}

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 = ""; // Replace with your own session ID.
                        // See https://dashboard.tokbox.com/projects
    var token = ""; // Replace with a generated token that has been assigned the moderator role.
                    // See https://dashboard.tokbox.com/projects
    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 = TB.initPublisher(API_KEY, 'publisher', divProps);
        session.publish(publisher);
    }
    function unpublsh() {
        session.unpublish(publisher);
    }
</script>

<body>

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

    <a href="javascript:unpublish()">Stop Publishing</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 = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects
var token = ""; // Replace with a generated token that has been assigned the moderator role.
                // See https://dashboard.tokbox.com/projects
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()