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.)
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
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 callsubscribeToVideo(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 thedataURI 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 theSubscriber.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
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:
- Mouse over the lower-right corner of the subscriber video window.
- Click the
button. - 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).