Have you explored the newest version of the OpenTok platform? Check out OpenTok 2.0, built on top of WebRTC. Learn more

Subscriber class

The Subscriber object is a representation of the local video element that is playing back a remote stream. The Subscriber object includes methods that let you disable and enable local audio playback for the subscribed stream.

The subscribe() method of the Session object returns a Subscriber object.

See Session.subscribe().

Subscriber properties

The Subscriber objects includes the following properties:

id (String) — The ID of the DOM element through which the Subscriber stream is displayed on the local web page.

stream (Stream) — The stream to which you are subscribing.

Note: This property should only be used as a read-only entity. The results of using JavaScript to directly change the property will be unpredictable.

Subscriber methods

Subscriber objects have the following methods:

Method Description
disableAudio() Deprecated in OpenTok v0.91.9. Use the subscribeToAudio() method.
enableAudio() Deprecated in OpenTok v0.91.9. Use the subscribeToAudio() method.
getAudioVolume():Number Gets the current audio volume, between 0 and 100, of the Subscriber.
getImgData():String Returns a base-64-encoded string of PNG data representing the Subscriber video.
getStyle():Object Gets an object that has properties that define the current appearance of user interface controls of the Publisher.
setAudioVolume(value:Number):Subscriber Sets the desired audio volume, between 0 and 100, of the Subscriber.
setStyle(style:Object, [value:Object]):Subscriber Sets properties that define the appearance of some user interface controls of the Subscriber.
subscribeToAudio(value:Boolean) Starts subscribing to audio (if it is available and currently not being subscribed to) when the value is true; stops subscribing to audio (if it is currently being subscribed to) when the value is false.
subscribeToVideo(value:Boolean) Starts subscribing to video (if it is available and currently not being subscribed to) when the value is true; stops subscribing to video (if it is currently being subscribed to) when the value is false.

disableAudio()

Deprecated in OpenTok v0.91.9. Use the subscribeToAudio() method and set the value parameter to false.

enableAudio()

Deprecated in OpenTok v0.91.9. Use the subscribeToAudio() method and set the value parameter to true.

getAudioVolume():Number

Returns the audio volume, between 0 and 100, of the Subscriber.

Generally you use this method in conjunction with the setAudioVolume() method.

See the setAudioVolume() method.

getImgData():String

Returns a base-64-encoded string of PNG data representing the Subscriber video. Returns an empty string if there is no video.

You can use the string as the value for a data URL scheme passed to the src parameter of an image file, as in the following:

var imgData = subscriber.getImgData();

var img = document.createElement("img");
img.setAttribute("src", "data:image/png;base64," + imgData);
var imgWin = window.open("about:blank", "Screenshot");
imgWin.document.write("<body></body>");
imgWin.document.body.appendChild(img);

getStyle():Object

Returns an object that has the properties that define the current user interface controls of the Subscriber. You can modify the properties of this object and pass the object to the setStyle() method of the Subscriber object. (See the documentation for setStyle() to see the styles that define this object.)

Returns

The object that defines the styles of the Subscriber.

See

setStyle()

setAudioVolume(value:Number):Subscriber

Sets the audio volume, between 0 and 100, of the Subscriber.

You can set the initial volume when you call the Session.subscribe() method. Pass a audioVolume property of the properties parameter of the method.

Parameters

value (Number) — The audio volume, between 0 and 100.

Returns

The Subscriber object. This lets you chain method calls, as in the following:

mySubscriber.setAudioVolume(50).setStyle(newStyle);

See

getAudioVolume()

Session.subscribe()

setStyle(style:Object, [value:String]):Subscriber

Sets properties that define the appearance of some user interface controls of the Subscriber.

You can either pass one parameter or two parameters to this method.

If you pass one parameter, style, it is an object that has the following properties that define the style:

  • 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" (buttons 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).

For example, the following code passes one value to the method:

var newStyle = {
        nameDisplayMode: "off",
        buttonDisplayMode: "auto",
    }
mySubscriber.setStyle(newStyle);

If you pass two parameters, style and value, they are key-value pair that define one property of the display style. For example, the following code passes two parameter values to each call of the method:

mySubscriber.setStyle("buttonDisplayMode", "auto");
mySubscriber.setStyle("nameDisplayMode", "on");

You can set the initial settings when you call the Session.subscribe() method. Pass a style property as part of of the properties parameter of the method.

Parameters

style (Object) — Either an object containing properties that define the style, or a String defining this single style property to set.

value (String) — The value to set for the style passed in. Pass a value for this parameter only if the value of the style parameter is a String.

Returns

The Subscriber object. This lets you chain method calls, as in the following:

mySubscriber.setStyle(newStyle).setAudioVolume(50);

Event

The TB object dispatches an exception event if you pass in an invalid style to the method. The code property of the ExceptionEvent object is set to 1011.

See

getStyle()

Session.subscribe()

subscribeToAudio(value:Boolean)

Starts subscribing audio (if it is available and currently not being subscribed to) when the value is true; stops subscribing to audio (if it is currently being subscribed to) when the value is false.

The application throws an error if it cannot disable audio for the specified subscriber.

The user can also change the volume level of a subscriber's stream:

  1. Mouse over the lower-right corner of the subscriber video window.
  2. Click the button.
  3. Drag the volume control to set the volume.

If server-side echo suppression is applied, only one individual's stream (the current participant) will have audio output at one time. Server-side echo suppression was deprecated in OpenTok v0.91.18.

Note: This method only affects the local playback of audio. It has no impact on the stream's audio for other connections subscribing to the same stream. If the Subscriber stream has had its microphone disabled at the originating Publisher, enabling the Subscriber audio will have no practical effect.

Parameters

value (String) — Whether to start subscribing to audio (true) or not (false).

subscribeToVideo(value:Boolean)

Starts subscribing to video (if it is available and currently not being subscribed to) when the value is true; stops subscribing to video (if it is currently being subscribed to) when the value is false.

Parameters

value (String) — Whether to start subscribing to video (true) or not (false).

IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat