Class: Session

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

Note that upon connecting to the session, the Session object dispatches a sessionConnected event in addition to calling the completionHandler . The SessionConnectEvent object, which defines the sessionConnected event, includes connections and streams properties, which list the connections and streams in the session when you connect.

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

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

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

• includeServers (String) — Set this to 'custom' and client will use only the custom TURN servers you provide in the customServers property of the newIceConfig parameter. Set this to 'all' and the client will use both the custom TURN servers you provide along with OpenTok TURN servers.
• transportPolicy (String) — Set this to 'all' (the default) and the client will use all ICE transport types (such as host, srflx, and TURN) to establish media connectivity. Set this to 'relay' to force connectivity through TURN always and ignore all other ICE candidates.

• customServers (Array) — Set this to an array of objects defining your custom TURN servers. Each object corresponds to one custom TURN server, and it includes the following properties:

  • urls (String or Array of Strings) — A string or an array of strings, where each string is a URL supported by the TURN server (and this may be only one URL).
  • username (String, optional) — The username for the TURN server defined in this object.
  • credential (String, optional) — The credential string for the TURN server defined in this object.

• data — (String) The data to send. The limit to the length of data string is 8kB. Do not set the data string to null or undefined .
• retryAfterReconnect — (Boolean) Upon reconnecting to the session, whether to send any signals that were initiated while disconnected. If your client loses its connection to the OpenTok session, due to a drop in network connectivity, the client attempts to reconnect to the session, and the Session object dispatches a reconnecting event. By default, signals initiated while disconnected are sent when (and if) the client reconnects to the OpenTok session. You can prevent this by setting the retryAfterReconnect property to false . (The default value is true .)
• to — (Connection) A Connection object corresponding to the client that the message is to be sent to. If you do not specify this property, the signal is sent to all clients connected to the session.
• type — (String) The type of the signal. You can use the type to filter signals when setting an event handler for the signal:type event (where you replace type with the type string). The maximum length of the type string is 128 characters, and it must contain only letters (A-Z and a-z), numbers (0-9), '-', '_', and '~'.

Each property is optional. If you set none of the properties, you will send a signal with no data or type to each client connected to the session.

• code — (Number) An error code, which can be one of the following:

  400	One of the signal properties is invalid.
  404	The client specified by the to property is not connected to the session.
  413	The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB).
  500	You are not connected to the OpenTok session.

• message — (String) A description of the error.

Note that the completionHandler success result ( error == null ) indicates that the options passed into the Session.signal() method are valid and the signal was sent. It does not indicate that the signal was successfully received by any of the intended recipients.

• 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.
• fitMode (String) — Determines how the video is displayed if the its dimensions do not match those of the DOM element. You can set this property to one of the following values:
  • "cover" — The video is cropped if its dimensions do not match those of the DOM element. This is the default setting for videos that have a camera as the source (for Stream objects with the videoType property set to "camera" ).
  • "contain" — The video is letterboxed if its dimensions do not match those of the DOM element. This is the default setting for screen-sharing videos (for Stream objects with the videoType property set to "screen" ).
• height (Number or String) — The desired initial height of the displayed video in the HTML page (default: 198 pixels). You can specify the number of pixels as either a number (such as 300) or a string ending in "px" (such as "300px"). Or you can specify a percentage of the size of the parent element, with a string ending in "%" (such as "100%"). Note: To resize the video, adjust the CSS of the subscriber's DOM element (the element property of the Subscriber object) or (if the height is specified as a percentage) its parent DOM element (see Resizing or repositioning a video ).
• insertDefaultUI (Boolean) — Whether to use the default OpenTok UI ( true , the default) or not ( false ). The default UI element contains user interface controls, a video loading indicator, and automatic video cropping or letterboxing, in addition to the video. (If you leave insertDefaultUI set to true , you can control individual UI settings using the fitMode , showControls , and style options.)

  If you set this option to false , OpenTok.js does not insert a default UI element in the HTML DOM, and the element property of the Subscriber object is undefined. The Subscriber object dispatches a videoElementCreated event when the video element (or in Internet Explorer the object element containing the video) is created. The element property of the event object is a reference to the Subscriber's video (or object ) element. Add it to the HTML DOM to display the video.

  Set this option to false if you want to move the Publisher's video element (or its object element in Internet Explorer) in the HTML DOM.

  If you set this to false , do not set the targetElement parameter. (This results in an error passed into to the OT.initPublisher() callback function.) To add the video to the HTML DOM, add an event listener for the videoElementCreated event, and then add the element property of the event object into the HTML DOM.

• insertMode (String) — Specifies how the Subscriber object will be inserted in the HTML DOM. See the targetElement parameter. This string can have the following values:
  • "replace" — The Subscriber object replaces contents of the targetElement. This is the default.
  • "after" — The Subscriber object is a new element inserted after the targetElement in the HTML DOM. (Both the Subscriber and targetElement have the same parent element.)
  • "before" — The Subscriber object is a new element inserted before the targetElement in the HTML DOM. (Both the Subscriber and targetElement have the same parent element.)
  • "append" — The Subscriber object is a new element added as a child of the targetElement. If there are other child elements, the Subscriber is appended as the last child element of the targetElement.

• preferredFrameRate (Number) — The preferred frame rate of the subscriber's video. Lowering the preferred frame rate lowers video quality on the subscribing client, but it also reduces network and CPU usage. You may want to use a lower frame rate for subscribers to a stream that is less important than other streams.

  This property only applies when subscribing to a stream that uses the scalable video feature . Scalable video is available:

  • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video: clients that use the OpenTok iOS SDK (on certain devices), the OpenTok Android SDK (on certain devices), or OpenTok.js in Chrome and Safari.

  In streams that do not use scalable video, setting this property has no effect.

  Note: The frame rate for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not call this method. Call this method if you want to set a maximum frame rate for this subscriber.

  Not every frame rate is available to a subscriber. When you set the preferred frame rate for the subscriber, OpenTok.js picks the best frame rate available that matches your setting. The frame rates available are based on the value of the Subscriber object's stream.frameRate property, which represents the maximum value available for the stream. The actual frame rates available depend, dynamically, on network and CPU resources available to the publisher and subscriber.

  You can dynamically change the preferred frame rate used by calling the setPreferredFrameRate() method of the Subscriber object.

• preferredResolution (String | Object) — The preferred resolution of the subscriber's video. Set this to "auto" (a string, recommended) to have OpenTok.js set the resolution based on the subscriber's dimensions in the browser. Or set this to an object with two properties: width and height (both numbers), such as {width: 320, height: 240} . Lowering the preferred video resolution lowers video quality on the subscribing client, but it also reduces network and CPU usage. You may want to use a lower resolution based on the dimensions of subscriber's video on the web page (which is handled automatically with the "auto" setting). Or you may want to use a resolution for subscribers to a stream that is less important (and smaller) than other streams.

  This property only applies when subscribing to a stream that uses the scalable video feature . Scalable video is available:

  • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video: clients that use the OpenTok iOS SDK (on certain devices), the OpenTok Android SDK (on certain devices), or OpenTok.js in Chrome and Safari.

  In streams that do not use scalable video, setting this property has no effect.

  Not every resolution is available to a subscriber. When you set the preferred resolution, OpenTok.js and the video encoder pick the best resolution available that matches your setting. The resolutions available depend on the resolution of the published stream. The Subscriber object's stream.resolution property represents the highest resolution available for the stream. Each of the resolutions available for a stream will use the same aspect ratio. The actual resolutions available depend, dynamically, on network and CPU resources available to the publisher and subscriber.

  You can dynamically change the preferred video resolution used by calling the setPreferredResolution() method of the Subscriber object.

• showControls (Boolean) — Whether to display the built-in user interface controls for the Subscriber (default: true ). These controls include the name display, the audio level indicator, the speaker control button, the video disabled indicator, and the video disabled warning icon. You can turn off all user interface controls by setting this property to false . You can control the display of individual user interface controls by leaving this property set to true (the default) and setting individual properties of the style property.
• style (Object) — An object containing properties that define the initial appearance of user interface controls of the Subscriber. The style object includes the following properties:
  • audioBlockedDisplayMode (String) — Whether to display the default audio blocked icon in Subscribers (in browsers where audio autoplay is blocked). Possible values are: "auto" (the default, icon is displayed when the audio is disabled) and "off" (the icon is not displayed). Set this to "off" if you want to display your own UI element showing that the audio is blocked. In response to an HTML element dispatching a click event, you can call the OT.unblockAudio() method to start audio playback in this and all other blocked subscribers.
  • audioLevelDisplayMode (String) — How to display the audio level indicator. Possible values are: "auto" (the indicator is displayed when the video is disabled), "off" (the indicator is not displayed), and "on" (the indicator is always displayed).
  • 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). 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 a value returned by calling getImgData() on a previous Subscriber object.) 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 always 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 always displayed).
  • videoDisabledDisplayMode (String) — Whether to display the video disabled indicator and video disabled warning icons for a Subscriber. These icons indicate that the video has been disabled (or is at risk of being disabled for the warning icon) due to poor stream quality. This style only applies to the Subscriber object. Possible values are: "auto" (the icons are automatically when the displayed video is disabled or at risk of being disabled due to poor stream quality), "off" (do not display the icons), and "on" (display the icons). The default setting is "auto"
• 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 ).
• testNetwork (Boolean) — Whether, when subscribing to a stream published by the local client, you want to have the stream come from the OpenTok Media Router ( true ) or if you want the DOM to simply to display the local camera's video ( false ). Set this to true when you want to use the Subscriber.getStats() method to check statistics for a stream you publish. This setting only applies to streams published by the local client in a session that uses the OpenTok Media Router (sessions with the media mode set to routed), not in sessions with the media mode set to relayed. The default value is false .
• width (Number or String) — The desired initial width of the displayed video in the HTML page (default: 264 pixels). You can specify the number of pixels as either a number (such as 400) or a string ending in "px" (such as "400px"). Or you can specify a percentage of the size of the parent element, with a string ending in "%" (such as "100%"). Note: To resize the video, adjust the CSS of the subscriber's DOM element (the element property of the Subscriber object) or (if the width is specified as a percentage) its parent DOM element (see Resizing or repositioning a video ).

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