Session

Connects to a Vonage Video API session.

Upon a successful connection, the completion handler (the second parameter of the method) is invoked without an error object passed in. (If there is an error connecting, the completion handler is invoked with an error object.) Make sure that you have successfully connected to the session before calling other methods of the Session object.

The Session object dispatches a connectionCreated event when any client (including your own) connects to the session.

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://tokbox.com/account
 var sessionID = ""; // Replace with your own session ID.
                     // See https://tokbox.com/developer/guides/create-session/.
 var token = ""; // Replace with a generated token.
                 // See https://tokbox.com/developer/guides/create-token/.

 var session = OT.initSession(apiKey, sessionID);
 session.connect(token, function(error) {
   if (error) {
     console.log(error.message);
   } else {
     // You have connected to the session. You could publish a stream now.
   }
 });

Events dispatched:

exception (ExceptionEvent) — Dispatched by the OT 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. However, you can pass a completion handler function in as the second parameter of the connect() and use this function instead of a listener for the sessionConnected event.

session.connect(token, function (error) {
  if (error) {
      console.log(error.message);
  } else {
    console.log("Connected to session.");
  }
});

Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.

After you call to the Session.forceMuteAll() method (or a moderator in another client makes a call to mute all streams), any streams published after the moderation call are published with audio muted. Call the disableForceMute() method to remove the mute state of a session (so that new published streams are not automatically muted).

Calling this method causes the Session object in each connected clients to dispatch a muteForced event, with the active flag set to false.

Check the capabilities.canForceMute property of the Session object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token Creation documentation).

Disconnects from the Vonage Video API session.

Calling the disconnect() method ends your connection with the session. In the course of terminating your connection, it also ceases publishing any stream(s) you were publishing.

Session objects on remote clients dispatch streamDestroyed events for any stream you were publishing. The Session object dispatches a sessionDisconnected event locally. The Session objects on remote clients dispatch connectionDestroyed events, letting other connections know you have left the session. The SessionDisconnectEvent and StreamEvent objects that define the sessionDisconnect and connectionDestroyed events each have a reason property. The reason property lets the developer determine whether the connection is being terminated voluntarily and whether any streams are being destroyed as a byproduct of the underlying connection's voluntary destruction.

If the session is not currently connected, calling this method causes a warning to be logged. See OT.setLogLevel().

Note: If you intend to reuse a Publisher object to publish to different sessions (or the same session) sequentially, add an event listener for the streamDestroyed event dispatched by the Publisher object (when it stops publishing). In the event listener, call the preventDefault() method of the event object to prevent the Publisher's video from being removed from the page.

Events dispatched:

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

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

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

Forces a remote connection to leave the session.

The forceDisconnect() method is normally used as a moderation tool to remove users from an ongoing session.

When a connection is terminated using the forceDisconnect(), sessionDisconnected, connectionDestroyed and streamDestroyed events are dispatched in the same way as they would be if the connection had terminated itself using the disconnect() method. However, the reason property of a ConnectionEvent or StreamEvent object specifies "forceDisconnected" as the reason for the destruction of the connection and stream(s).

While you can use the forceDisconnect() method to terminate your own connection, calling the disconnect() method is simpler.

The OT object dispatches an exception event if the user's role does not include permissions required to force other users to disconnect. You define a user's role when you create the user token (see the Token creation overview). See ExceptionEvent and OT.on().

The application throws an error if the session is not connected.

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.

session.forceDisconnect(connection, function (error) {
  if (error) {
    console.log(error);
  } else {
    console.log("Connection forced to disconnect: " + connection.id);
  }
});

Forces all publishers in the session (except for those publishing excluded streams) to mute audio.

A stream published by the moderator calling the forceMuteAll() method is muted along with other streams in the session, unless you add the moderator's stream (or streams) to the excluded streams array.

If you leave out the excludedStreams parameter, all streams in the session (including those of the moderator) will stop publishing audio:

session.forceMuteAll();

Also, any streams that are published after the call to the forceMuteAll() method are published with audio muted. You can remove the mute state of a session by calling the disableForceMute() method of the Session object.

session.disableForceMute();

After you call the Session.disableForceMute() method, new streams published to the session will no longer have audio muted.

Calling this method causes the Publisher objects in the clients publishing the streams to dispatch muteForced events. Also, the Session object in each client connected to the session dispatches the muteForced event (with the active property of the event object set to true).

Check the capabilities.canForceMute property of the Session object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token Creation documentation).

Forces a the publisher of a specified stream to mute its audio.

Calling this method causes the Publisher object in the client publishing the stream to dispatch a muteForced event.

Check the capabilities.canForceMute property of the Session object to see if you can call this function successfully. This is reserved for clients that have connected with a token that has been assigned the moderator role (see the Token Creation documentation).

Forces the publisher of the specified stream to stop publishing the stream.

Calling this method causes the Session object to dispatch a streamDestroyed event on all clients that are subscribed to the stream (including the client that is publishing the stream). The reason property of the StreamEvent object is set to "forceUnpublished".

The OT object dispatches an exception event if the user's role does not include permissions required to force other users to unpublish. You define a user's role when you create the user token (see the Token creation overview). You pass the token string as a parameter of the connect() method of the Session object. See ExceptionEvent and OT.on().

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.

session.forceUnpublish(stream, function (error) {
  if (error) {
      console.log(error);
    } else {
      console.log("Connection forced to disconnect: " + connection.id);
    }
  });

Returns the local Publisher object for a given stream.

Returns an array of local Subscriber objects for a given stream.

Removes an event handler or handlers.

If you pass in one event name and a handler method, the handler is removed for that event:

obj.off("eventName", eventHandler);

If you pass in multiple event names and a handler method, the handler is removed for those events:

obj.off("eventName1 eventName2", eventHandler);

If you pass in an event name (or names) and no handler method, all handlers are removed for those events:

obj.off("event1Name event2Name");

If you pass in no arguments, all event handlers are removed for all events dispatched by the object:

obj.off();

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.off(
   {
      eventName1: event1Handler,
      eventName2: event2Handler
   });

Adds an event handler function for one or more events.

The following code adds an event handler for one event:

obj.on("eventName", function (event) {
    // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events:

obj.on("eventName1 eventName2",
       function (event) {
           // This is the event handler.
       });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method:

obj.on("eventName",
       function (event) {
           // This is the event handler.
       },
       obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.on(
   {
      eventName1: function (event) {
              // This is the handler for eventName1.
          },
      eventName2:  function (event) {
              // This is the handler for eventName2.
          }
   },
   obj);

If you do not add a handler for an event, the event is ignored locally.

Adds an event handler function for one or more events. Once the handler is called, the specified handler method is removed as a handler for this event. (When you use the on() method to add an event handler, the handler is not removed when it is called.) The once() method is the equivilent of calling the on() method and calling off() the first time the handler is invoked.

The following code adds a one-time event handler for one event:

obj.once("eventName", function (event) {
   // This is the event handler.
});

If you pass in multiple event names and a handler method, the handler is registered for each of those events:

obj.once("eventName1 eventName2"
         function (event) {
             // This is the event handler.
         });

You can also pass in a third context parameter (which is optional) to define the value of this in the handler method:

obj.once("eventName",
         function (event) {
             // This is the event handler.
         },
         obj);

The method also supports an alternate syntax, in which the first parameter is an object that is a hash map of event names and handler functions and the second parameter (optional) is the context for this in each handler:

obj.once(
   {
      eventName1: function (event) {
                 // This is the event handler for eventName1.
          },
      eventName2:  function (event) {
                 // This is the event handler for eventName1.
          }
   },
   obj);

The publish() method starts publishing an audio-video stream to the session. The audio-video stream is captured from a local microphone and webcam. Upon successful publishing, the Session objects on all connected clients dispatch the streamCreated event.

You pass a Publisher object as the one parameter of the method. You can initialize a Publisher object by calling the OT.initPublisher() method. Before calling Session.publish().

This method takes an alternate form: publish(targetElement: String | HTMLElement, properties: Object, completionHandler: Function): Publisher — In this form, you do not pass a Publisher object into the function. Instead, you pass in a targetElement (the target HTML element or the ID of the target HTML element for the Publisher), an optional properties object that defines options for the Publisher (see OT.initPublisher()), and an optional completion handler function. The method returns a new Publisher object, which starts sending an audio-video stream to the session. The remainder of this documentation describes the form that takes a single Publisher object as a parameter.

A local display of the published stream is created on the web page by replacing the specified element in the DOM with a streaming video display. The video stream is automatically mirrored horizontally so that users see themselves and movement in their stream in a natural way. If the width and height of the display do not match the 4:3 aspect ratio of the video signal, the video stream is cropped to fit the display.

If calling this method creates a new Publisher object and the Vonage Video API library does not have access to the camera or microphone, the web page alerts the user to grant access to the camera and microphone.

The OT object dispatches an exception event if the user's role does not include permissions required to publish. For example, if the user's role is set to subscriber, then they cannot publish. You define a user's role when you create the user token (see Token creation overview). You pass the token string as a parameter of the connect() method of the Session object. See ExceptionEvent and OT.on().

The application throws an error if the session is not connected.

Events dispatched:

exception (ExceptionEvent) — Dispatched by the OT object. This can occur when user's role does not allow publishing (the code property of event object is set to 1500); it can also occur if the connection fails to connect (the code property of event object is set to 1013). WebRTC is a peer-to-peer protocol, and it is possible that connections will fail to connect. The most common cause for failure is a firewall that the protocol cannot traverse.

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://tokbox.com/account
var sessionId = ""; // Replace with your own session ID.
                    // /developer/guides/create-session/.
var token = ""; // Replace with a generated token that has been assigned the publish role.
                // See https://tokbox.com/developer/guides/create-token/.
var session = OT.initSession(apiKey, sessionID);
session.connect(token, function(error) {
  if (error) {
    console.log(error.message);
  } else {
    var publisherOptions = {width: 400, height:300, name:"Bob's stream"};
    // This assumes that there is a DOM element with the ID 'publisher':
    publisher = OT.initPublisher('publisher', publisherOptions);
    session.publish(publisher);
  }
});

session.publish(publisher, null, function (error) {
  if (error) {
    console.log(error.message);
  } else {
    console.log("Publishing a stream.");
  }
});

Sets the encryption secret for a session with end-to-end encryption enabled. If this method is called in a session without encryption enabled the function will resolve and no error will be thrown. Users may change their set encryption key at any time. See the end-to-end encryption developer guide.

Sets the ICE configuration for all connections in a session. This replaces any previously set ICE configurations.

This feature is available for projects that use the configurable TURN server add-on.

Sends a signal to each client or a specified client in the session. Specify a to property of the signal parameter to limit the signal to be sent to a specific client; otherwise the signal is sent to each client connected to the session.

The following example sends a signal of type "foo" with a specified data payload ("hello") to all clients connected to the session:

session.signal({
    type: "foo",
    data: "hello"
  },
  function(error) {
    if (error) {
      console.log("signal error: " + error.message);
    } else {
      console.log("signal sent");
    }
  }
);

Calling this method without specifying a recipient client (by setting the to property of the signal parameter) results in multiple signals sent (one to each client in the session). For information on charges for signaling, see the Vonage Video API pricing page.

The following example sends a signal of type "foo" with a data payload ("hello") to a specific client connected to the session:

session.signal({
    type: "foo",
    to: recipientConnection; // a Connection object
    data: "hello"
  },
  function(error) {
    if (error) {
      console.log("signal error: " + error.message);
    } else {
      console.log("signal sent");
    }
  }
);

Add an event handler for the signal event to listen for all signals sent in the session. Add an event handler for the signal:type event to listen for signals of a specified type only (replace type, in signal:type, with the type of signal to listen for). The Session object dispatches these events. (See events.)

Subscribes to a stream that is available to the session. You can get an array of available streams from the streams property of the sessionConnected and streamCreated events (see SessionConnectEvent and StreamEvent).

The subscribed stream is displayed on the local web page by replacing the specified element in the DOM with a streaming video display. If the width and height of the display do not match the 4:3 aspect ratio of the video signal, the video stream is cropped to fit the display. If the stream lacks a video component, a blank screen with an audio indicator is displayed in place of the video stream.

The application throws an error if the session is not connected or if the targetElement does not exist in the HTML DOM.

Example

The following code subscribes to other clients' streams:

var apiKey = ""; // Replace with your API key. See https://tokbox.com/account
var sessionID = ""; // Replace with your own session ID.
                    // See https://tokbox.com/developer/guides/create-session/.
var token = ""; // Replace with a generated token.
                // See https://tokbox.com/developer/guides/create-token/.

var session = OT.initSession(apiKey, sessionID);
session.on("streamCreated", function(event) {
  subscriber = session.subscribe(event.stream, targetElement);
});
session.connect(token);

session.subscribe(stream, "subscriber", null, function (error) {
  if (error) {
    console.log(error.message);
  } else {
    console.log("Subscribed to stream: " + stream.id);
  }
});

Ceases publishing the specified publisher's audio-video stream to the session. By default, the local representation of the audio-video stream is removed from the web page. Upon successful termination, the Session object on every connected web page dispatches a streamDestroyed event.

To prevent the Publisher from being removed from the DOM, add an event listener for the streamDestroyed event dispatched by the Publisher object and call the preventDefault() method of the event object.

Note: If you intend to reuse a Publisher object to publish to different sessions (or the same session) sequentially, add an event listener for the streamDestroyed event dispatched by the Publisher object (when it stops publishing). In the event listener, call the preventDefault() method of the event object to prevent the Publisher's video from being removed from the page.

Events dispatched:

streamDestroyed (StreamEvent) — The stream associated with the Publisher has been destroyed. Dispatched on by the Publisher on on the Publisher's browser. Dispatched by the Session object on all other 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 apiKey = ""; // Replace with your API key. See https://tokbox.com/account
  var sessionID = ""; // Replace with your own session ID.
                   // See https://tokbox.com/developer/guides/create-session/.
  var token = ""; // Replace with a generated token.
                  // See https://tokbox.com/developer/guides/create-token/.
  var publisher;
  var session = OT.initSession(apiKey, sessionID);
  session.connect(token, function(error) {
    if (error) {
      console.log(error.message);
    } else {
      // This assumes that there is a DOM element with the ID 'publisher':
      publisher = OT.initPublisher('publisher');
      session.publish(publisher);
    }
  });

  function unpublish() {
    session.unpublish(publisher);
  }
</script>

<body>

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

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

</body>

Stops subscribing to a stream in the session. the display of the audio-video stream is removed from the local web page.

Example

The following code subscribes to other clients' streams. For each stream, the code also adds an Unsubscribe link.

var apiKey = ""; // Replace with your API key. See See https://tokbox.com/account
var sessionID = ""; // Replace with your own session ID.
                    // See https://tokbox.com/developer/guides/create-session/.
var token = ""; // Replace with a generated token.
                // See https://tokbox.com/developer/guides/create-token/.
var streams = [];

var session = OT.initSession(apiKey, sessionID);
session.on("streamCreated", function(event) {
    var stream = event.stream;
    displayStream(stream);
});
session.connect(token);

function displayStream(stream) {
    var div = document.createElement('div');
    div.setAttribute('id', 'stream' + stream.streamId);

    var subscriber = session.subscribe(stream, div);
    subscribers.push(subscriber);

    var aLink = document.createElement('a');
    aLink.setAttribute('href', 'javascript: unsubscribe("' + subscriber.id + '")');
    aLink.innerHTML = "Unsubscribe";

    var streamsContainer = document.getElementById('streamsContainer');
    streamsContainer.appendChild(div);
    streamsContainer.appendChild(aLink);

    streams = event.streams;
}

function unsubscribe(subscriberId) {
    console.log("unsubscribe called");
    for (var i = 0; i < subscribers.length; i++) {
        var subscriber = subscribers[i];
        if (subscriber.id == subscriberId) {
            session.unsubscribe(subscriber);
        }
    }
}

Dispatched when an archive recording of the session starts.

Dispatched when an archive recording of the session stops.

Dispatched when a new client (including your own) has connected to the session, and for every client in the session when you first connect. (The Session object also dispatches a sessionConnected event when your local client connects.)

A client, other than your own, has disconnected from the session.

The CPU performance state has changed. This can be set to one the following: "nominal", "fair", "serious", or "critical". This is a beta feature.

A moderator has forced clients publishing streams to the session to mute audio (the active property of this MuteForcedEvent object is set to true), or a moderator has disabled the mute audio state in the session (the active property of this MuteForcedEvent object is set to false).

The client has connected to a Vonage Video API session. This event is dispatched asynchronously in response to a successful call to the connect() method of a Session object. Before calling the connect() method, initialize the session by calling the OT.initSession() method. For a code example and more details, see Session.connect().

The client has disconnected from the session. This event may be dispatched asynchronously in response to a successful call to the disconnect() method of the Session object. The event may also be dispatched if a session connection is lost inadvertently, as in the case of a lost network connection.

The default behavior is that all Subscriber objects are unsubscribed and removed from the HTML DOM. Each Subscriber object dispatches a destroyed event when the element is removed from the HTML DOM. If you call the preventDefault() method in the event listener for the sessionDisconnect event, the default behavior is prevented, and you can, optionally, clean up Subscriber objects using your own code.

The reason property of the event object indicates the reason for the client being disconnected.

The local client has reconnected to the Vonage Video API session after its connection was lost temporarily. When the connection is lost, the Session object dispatches a sessionReconnecting event, prior to the sessionReconnected event. If the client cannot reconnect to the session, the Session object dispatches a sessionDisconnected event instead of this event.

Any existing publishers and subscribers are automatically reconnected when client reconnects and the Session object dispatches this event.

Any signals sent by other clients while your client was disconnected are received upon reconnecting. By default, signals initiated by the local client while disconnected (by calling the Session.signal() method) are sent when the client reconnects to the Vonage Video API session. You can prevent this by setting the retryAfterReconnect property to false in the signal object you pass into the Session.signal() method.

The local client has lost its connection to a Vonage Video API session and is trying to reconnect. This results from a loss in network connectivity. If the client can reconnect to the session, the Session object dispatches a sessionReconnected event. Otherwise, if the client cannot reconnect, the Session object dispatches a sessionDisconnected event.

In response to this event, you may want to provide a user interface notification, to let the user know that the app is trying to reconnect to the session and that audio-video streams are temporarily disconnected.

A signal was received from the session. The SignalEvent class defines this event object. It includes the following properties:

• data — (String) The data string sent with the signal (if there is one).
• from — (Connection) The Connection corresponding to the client that sent the signal.
• type — (String) The type assigned to the signal (if there is one).

You can register to receive all signals sent in the session, by adding an event handler for the signal event. For example, the following code adds an event handler to process all signals sent in the session:

session.on("signal", function(event) {
  console.log("Signal sent from connection: " + event.from.id);
  console.log("Signal data: " + event.data);
});

You can register for signals of a specified type by adding an event handler for the signal:type event (replacing type with the actual type string to filter on).

A new stream, published by another client, has been created on this session. For streams published by your own client, the Publisher object dispatches a streamCreated event. For a code example and more details, see StreamEvent.

A stream from another client has stopped publishing to the session.

The default behavior is that all Subscriber objects that are subscribed to the stream are unsubscribed and removed from the HTML DOM. Each Subscriber object dispatches a destroyed event when the element is removed from the HTML DOM. If you call the preventDefault() method in the event listener for the streamDestroyed event, the default behavior is prevented and you can clean up a Subscriber object for the stream by calling its destroy() method. See Session.getSubscribersForStream().

For streams published by your own client, the Publisher object dispatches a streamDestroyed event.

For a code example and more details, see StreamEvent.

Defines an event dispatched when property of a stream has changed. This can happen in in the following conditions:

• A stream has started or stopped publishing audio or video (see Publisher.publishAudio() and Publisher.publishVideo()). Note that a subscriber's video can be disabled or enabled for reasons other than the publisher disabling or enabling it. A Subscriber object dispatches videoDisabled and videoEnabled events in all conditions that cause the subscriber's stream to be disabled or enabled.
• The videoDimensions property of the Stream object has changed (see Stream.videoDimensions).
• The videoType property of the Stream object has changed. This can happen in a stream published by a mobile device. (See Stream.videoType.)

A signal of the specified type was received from the session. The SignalEvent class defines this event object. It includes the following properties:

• data — (String) The data string sent with the signal.
• from — (Connection) The Connection corresponding to the client that sent the signal.
• type — (String) The type assigned to the signal (if there is one).

You can register for signals of a specified type by adding an event handler for the signal:type event (replacing type with the actual type string to filter on). For example, the following code adds an event handler for signals of type "foo":

session.on("signal:foo", function(event) {
  console.log("foo signal sent from connection " + event.from.id);
  console.log("Signal data: " + event.data);
});

You can register to receive all signals sent in the session, by adding an event handler for the signal event.