Stream class

Properties Methods

Specifies a stream. A stream is a representation of a published stream in a session. When a client calls the Session.publish() method, a new stream is created. Properties of the Stream object provide information about the stream.

When a stream is added to a session, the Session object dispatches a streamCreatedEvent. When a stream is destroyed, the Session object dispatches a streamDestroyed event. The StreamEvent object, which defines these event objects, has a stream property, which is an array of Stream object. For details and a code example, see StreamEvent.

When a connection to a session is made, the Session object dispatches a sessionConnected event, defined by the SessionConnectEvent object. The SessionConnectEvent object has a streams property, which is an array of Stream objects pertaining to the streams in the session at that time. For details and a code example, see SessionConnectEvent.

Stream properties

A Stream object has the following properties:

connection (Connection) — The Connection object corresponding to the connection that is publishing the stream. You can compare this to to the connection property of the Session object to see if the stream is being published by the local web page.

creationTime (Number) — The timestamp for the creation of the stream. This value is calculated in milliseconds. You can convert this value to a Date object by calling new Date(creationTime), where creationTime is the creationTime property of the Stream object.

hasAudio (Boolean) — Whether the stream has audio published. See Session.publish() and Publisher.publishAudio().

hasVideo (Boolean) — Whether the stream has video published. See Session.publish() and Publisher.publishVideo().

name (String) — The name of the stream. Publishers can specify a name when publishing a stream (using the publish() method of the publisher's Session object).

quality (Object) — An object that provides details about the stream's quality. This property is only set after the Session object dispatches a streamPropertyChanged event for the stream (with the changedProperty property set to "quality"). This object includes the following properties:

• AECEnabled (Boolean) — Whether the publishing client supports acoustic echo cancellation. (Note that on the publishing page, you can determine whether acoustic echo cancellation mode is being used. The Publisher object dispatches an echoCancellationModeChanged, and you can then call the getEchoCancellationMode() method of the Publisher object. See Publisher.getEchoCancellationMode().)
• camLevel (Number) — A number indicating the camera level. Values from 0 through 100 indicate the camera level at the time of the reading; 0 indicates that the camera is detecting little motion, and 100 indicates that the camera is detecting a lot of motion. A value of -1 indicates an inactive camera. Note that this property is set only once, when the Session dispatches the associated streamPropertyChanged event for the the quality property of the stream.
• encodedHeight (Number) — The height of the resolution of the encoded stream, in pixels. You can specify the target height of the stream's resolution by setting the encodedHeight property of the properties parameter when you call the publish() method of the Session object. The encodedHeight property of the quality property of the Stream object reports the actual encoded height of the resolution of the stream, which may be lower than the requested height. (See Session.publish().)
• encodedWidth (Number) — The width of the resolution of the encoded stream, in pixels. You can specify the target height of the stream's resolution by setting the encodedHeight property of the properties parameter when you call the publish() method of the Session object. The encodedWidth property of the quality property of the Stream object reports the actual encoded width of the resolution of the stream, which may be lower than the requested width. (See Session.publish().)
• latency (Number) — The latency of the connection to the OpenTok server, in milliseconds.
• micLevel (Number) — A number indicating the microphone activity level. Values from 0 through 100 indicate the microphone level at the time of the reading; 0 indicates that the microphone is detecting little audio, and 100 indicates that the microphone is detecting a lot of audio. A value of -1 indicates an inactive microphone. Note that this property is set only once, when the Session dispatches the associated streamPropertyChanged event for the the quality property of the stream.
• networkQuality (String) — The network quality: "good", "acceptable", or "poor". The rating indicates the potential connection quality, based on the combination of the upload bandwidth and latency. A moderator may use this indicator to determine whether use a stream in an app (or whether to call the forceDisconnect() method of the Session object).
• readyH264 (Boolean) — Whether the client supports H.264 encoding.
• upBandwidth (Number) — The upstream (publishing) bandwidth, in kbps.

Each property of the quality object is set only once, when the Session object dispatches a streamPropertyChanged. Property values are not dynamically updated.

streamId (String) — The ID of the stream.

type (String) — The type of the stream. This value can be either "basic" or "archive". The value "basic" identifies a stream published by a user connected to the session. The value "archive" identifies an archive stream (from an archive being played back). For example, the following code connects to a session and subscribes to the basic streams only:

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 basicStreams = [];

session = TB.initSession(sessionId); 

session.addEventListener("sessionConnected", sessionConnectedHandler);
session.connect(apiKey, token); 
function sessionConnectedHandler(event) {
    for (var i = 0; i < event.streams.length; i++) {
        if (event.streams[i].type == "basic") {
            subscribeToStream(event.target, event.streams[i]);
            basicStreams[event.streams[i].streamId] = event.streams[i];
        }
    }
}

function subscribeToStream(session, stream) {
    // Create a div for the subscriber to replace
    var parentDiv = document.getElementById("subscribers");
    var subscriberDiv = document.createElement("div");
    subscriberDiv.id = "opentok_subscriber_" + stream.streamId;
    parentDiv.appendChild(subscriberDiv);
    
    session.subscribe(stream, subscriberDiv.id);
}

Note: Stream properties should only be used as read-only entities. The results of using JavaScript to directly change the values of Stream properties will be unpredictable.

Stream methods

Stream objects have the following methods:

Method	Description
startRecording(archive:Archive)	Starts recording the stream to an archive.
stopRecording(archive:Archive)	Stops recording the stream to an archive.