Publisher class

addEventListener(type:String, listener:Function)

Registers a method as an event listener for a specific event.

var div = document.createElement('div');
div.setAttribute('id', 'publisher');
var publisherContainer = document.getElementById('publisherContainer');
publisherContainer.appendChild(div);
publisher = TB.initPublisher(API_KEY, 'publisher');
session.publish(publisher);
					
publisher.addEventListener("resize", publisherResizeHandler);

function publisherResizeHandler(event) {
    newWidth = event.widthTo;
    newHeight = event.heightTo;
    // Modify the UI based on the new dimensions of the publisher 
}

var div = document.createElement('div');
div.setAttribute('id', 'publisher');
var publisherContainer = document.getElementById('publisherContainer');
publisherContainer.appendChild(div);
publisher = TB.initPublisher(API_KEY, 'publisher');
session.publish(publisher);
					
publisher.addEventListener("settingsButtonClick", settingsButtonClickHandler);

function settingsButtonClickHandler(event) {
    manageDevices();
}
function manageDevices() {
    deviceManager = TB.initDeviceManager(apiKey);
    deviceManager.displayPanel("deviceManagerContainer", publisher);
}

destroy()

Deletes the Publisher object and removes it from the HTML DOM.

detectDevices()

Has the OpenTok API detect available cameras and microphones. This operation is asynchronous. The Publisher object dispatches a devicesDetected event when it detects the available devices.

The following example uses the detectDevices() method to check for available cameras and microphones.

var cameras;
var mics;

var publisher = TB.initPublisher(API_KEY);
publisher.addEventListener("devicesDetected", devicesDetectedHandler);
publisher.detectDevices();

function devicesDetectedHandler(event) {
    cameras = event.cameras;
    mics = event.microphones;

    if (event.cameras.length < 1) {
        alert ("No camera connected.");
    } else if (event.microphone.length < 1) {
        alert ("No microphone connected.");
    }
    if (event.cameras.length > 0 && event.microphones.length > 0) {
        alert("Selected camera: " + event.selectedCamera.name + "\nSelected microphone: " + selectedMicrophone.name);
    }
}

Your app may use the cameras and microphones properties of the event to build user interface controls (such as a drop-down list) in which the user can select a camera and a microphone to attach to the Publisher object. (See setMicrophone() and setCamera().)

detectMicActivity(value:Boolean)

Causes the Publisher object to start or stop dispatching microphoneActivityLevel events, based on the value you pass in: true (start) or (false (stop). The microphoneActivityLevel event includes a value property which is the representative microphone level, from -1 to 100, at the time of the event. A value of -1 indicates an inactive microphone; 0 indicates a silent microphone, 100 indicates full activity.

Use this method and the microphoneActivityLevel event to adjust the microphone level of the Publisher. For example, you can create an visual display of the value property, and have the client adjust the mic level based on that display.

Important: Calling detectMicActivity(true) while publishing can diminish the frame rate of the displayed video. When you are done detecting the microphone activity level of the Publisher, stop the event by calling detectMicActivity(false).

The following example uses the detectMicActivity() method to get microphone levels.

var publisher = TB.initPublisher(API_KEY);
publisher.addEventListener("microphoneActivityLevel", micActivityHandler);
publisher.detectMicActivity(true);

function micActivityHandler(event) {
    // In this event handler, you might adjust a user interface control
    // to show the user the microphone level, based on the value property
    // of the event object.
}

disableMicrophone()

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

enableMicrophone()

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

getEchoCancellationMode():String

Returns a string corresponding to the echo cancellation mode of the Publisher. The string can be one of the following values:

• "unknown" — The echo cancellation mode is unknown (the initial state).
• "none" — The Publisher is not using acoustic echo cancellation.
• "fullDuplex — The Publisher is using acoustic echo cancellation.

You should call this method after the Publisher dispatches the echoCancellationModeChanged event. Until this event is dispatched, the Publisher will not use echo cancellation; however, the method returns "unknown" (not "none") until the event is dispatched.

The Publisher dispatches the echoCancellationModeChanged event after the Publisher is first created (by calling the publish() method) when the TokBox code can determine the correct echo cancellation mode. After that, the Publisher dispatches the event again whenever the setting changes. The setting may change because of the following reasons:

• The user switches to a microphone that changes the setting. (For example, the user switches from a USB mic, which does not support AEC, to a mic that supports AEC — or vice versa.)
• Device Panel is opened or closed, changing the setting. (For example, the Publisher is using a microphone that supports AEC, and the Device Panel is displayed, which disables AEC for the mic. When the Device Panel is closed, the Publisher dispatches the event again, indicating that the Publisher is once again in AEC mode.)
• A new Publisher that publishes audio is added, which changes the echo cancellation mode to "none" (if it is not already that).
• A Publisher that publishes audio is removed so that there is now only one Publisher, which may change the echo cancellation mode to "fullDuplex" (if acoustic echo suppression is supported).

A Publisher will not use acoustic echo cancellation if any of the following is true:

• The Publisher uses a USB microphone. (Acoustic echo cancellation is not supported for USB microphones.)
• The client is publishing audio in another Publisher.
• The user has prevented storage of Flash Player local shared objects.

If a Publisher does not use acoustic echo cancellation, it may echo back a subscribed audio stream. Use this method, along with the echoCancellationModeChanged, to configure your app in the case where acoustic echo cancellation is not supported.

getImgData():String

Returns a base-64-encoded string of PNG data representing the Publisher 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 = publisher.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);

getMicrophoneGain():Number

Returns the microphone gain, between 0 and 100, of the Publisher.

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

See the setMicrophoneGain() method.

getStyle():Object

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

publishAudio(value:Boolean)

Starts publishing audio (if it is currently not being published) when the value is true; stops publishing audio (if it is currently being published) when the value is false.

Note: Prior to calling the publishAudio() method, set the showAudioSettings property of a DeviceManager object to false if you are publishing in video-only mode.

publishVideo(value:Boolean)

Starts publishing video (if it is currently not being published) when the value is true; stops publishing video (if it is currently being published) when the value is false.

Note: Prior to calling the publishVideo method, set the showVideoSettings property of a DeviceManager object to false if you are publishing in audio-only mode.

removeEventListener(type:String, listener:Function)

Removes an event listener for a specific event.

setCamera(name:String):Publisher

Sets the camera to be used by the Publisher, based on the camera name.

You can get an array of available camera by calling the detectDevices() method; the Publisher object dispatches a devicesDetected event in response to calling this method. The devicesDetected event object includes a cameras property, which is an array of available cameras. Each element in the array has a name property, which you can use to pass into the setCamera() method.

myPublisher.setMicrophone(micName).setCamera(cameraName);

setMicrophone(name:String):Publisher

Sets the microphone to be used by the Publisher, based on the microphone name.

You can get an array of available microphones by calling the detectDevices() method. The Publisher dispatches a devicesDetected event in response to calling this method. The devicesDetected event object includes a microphones property, which is an array of available microphones. Each element in the array has a name property, which you can use to pass into the setMicrophone() method.

myPublisher.setCamera(cameraName).setMicrophone(micName);

setMicrophoneGain(value:Number):Publisher

Sets the microphone gain, between 0 and 100, of the Publisher.

You can set the initial microphone gain when you call the Session.publish() or TB.initPublisher() method. Pass a microphoneGain property of the properties parameter of the method.

myPublisher.setMicrophoneGain(50).setStyle(newStyle);

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

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

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 publisherVideo(false) on the Publisher 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 Publisher.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 Publisher.getImgData(). 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 microphone controls and settings buttons. Possible values are: "auto" (buttons are displayed when the stream is first displayed and when the user mouses over the display), "off" (buttons are not displayed), and "on" (buttons are displayed). The showMicButton and showSettingsButton properties define whether each individual control is 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).
• showMicButton (Boolean) — Whether to display the microphone controls.
• showSettingsButton (Boolean) — Whether to display the settings buttons.

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

var newStyle = {
        buttonDisplayMode: "auto",
        nameDisplayMode: "off",
        showMicButton: true,
        showSettingsButton: true,
        showCameraToggleButton: true
    }
myPublisher.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:

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

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

myPublisher.setStyle(newStyle).setMicGain(50);