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

DeviceManager class

The DeviceManager class lets you select the camera and microphone to use for a publisher stream. Calling the TB.initDeviceManager() method returns a DeviceManager object.

For a code example that uses the DeviceManager object, see DeviceManager Example.

See

DevicePanel

DeviceEvent

TB.initDeviceManager()

DeviceManager properties

The DeviceManger class includes the following properties:

showMicSettings (Boolean) — Whether to show microphone settings in device panels created by calling the displayPanel() method (true) or not (false). The default value is true.

showCamSettings (Boolean) — Whether to show camera settings in device panels created by calling the displayPanel() method (true) or not (false). The default value is true.

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

DeviceManager methods

The DeviceManager object has the following methods.

Method Description
addEventListener(eventType:String, listener:Function) Registers a method as an event listener for a specific event.
detectDevices() Has the OpenTok API detect connected cameras and microphones.
displayPanel([replaceElementId:String, publisher:Publisher, properties:Object]):DevicePanel Displays a device panel for selecting a camera and microphone.
removeEventListener(eventType:String, listener:Function) Removes an event listener for a specific event.
removePanel(panel:DevicePanel) Removes the specified device panel from the HTML DOM.

addEventListener(type:String, listener:Function)

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

Parameters

type (String) — This string identifying the type of event. See DeviceManager events.

listener (Function) — The function to be invoked when the DeviceManager object dispatches the event.

Example

The following example registers a function, devicesDetectedHandler(), as the event handler for devicesDetected events. After calling the detectDevices() method, the DeviceManager object dispatches this event when it detects the cameras and microphones connected to the computer.

var API_KEY = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects
var deviceManager = TB.initDeviceManager(API_KEY);
deviceManager.addEventListener("devicesDetected", devicesDetectedHandler);
deviceManager.detectDevices();

function devicesDetectedHandler(event) {
    if (event.cameras.length > 0 && event.microphones.length > 0) {
        alert("You have cameras and microphones connected!");
    }
}

For another code example that uses the devicesDetected event, see DeviceManager Example.

detectDevices()

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

Note: This method was deprecated in OpenTok v0.91.57. Use the Publisher.detectDevices() method instead.

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

var cameras;
var mics;
var API_KEY = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects

var deviceManager = TB.initDeviceManager(API_KEY);
deviceManager.addEventListener("devicesDetected", devicesDetectedHandler);
deviceManager.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: " + event.selectedMicrophone.name);
    }
}

displayPanel([replacementElementId:String, publisher, properties:Object]):DevicePanel

Displays a device panel for selecting a camera and microphone for the specified publisher. Calling this method returns a DevicePanel object.

You do not need to specify a value for the replacementElementId. If you do not specify this value, the call to the displayPanel() method creates the device panel in a new DOM element, which is a child of the document's body tag. The new DOM element is centered in the web page. By default, the method adds the device panel to a z-index layer above the existing HTML DOM elements (although you can specify a specific z-index layer).

If you specify a replacementElementID value and the specified element does not exist in the HTML DOM, the application throws an error.

For a code example that uses the the displayPanel() method, see Example.

Parameters

replaceElementId (String) — (Optional) The String ID of the existing DOM element that the device panel replaces. If you do not specify a replacement element ID, the call to the displayPanel() method adds the device panel in a new DOM element, which is a child of the document's body tag.

publisher (Publisher) — Optional. The publisher for which the device panel settings apply. If no publisher is specified, the device panel settings apply to all upcoming publishers.

properties (Object) — (Optional) An object that contains the following properties (each optional):

  • showCloseButton (a Boolean value) — Set this property to false if you do not want the device panel to display a close button. The default value is true. Note that the dimensions of the device panel differ depending on whether you display the close button. With the close button displayed, the device panel is 360 pixels wide by 270 pixels high. Without the close button displayed, it is 340 pixels wide by 230 pixels high.
  • wmode (a String value) — Set this property to set the transparency of the SWF object used to display the device panel. Possible values match the wmode values for the object and embed tags for a SWF file: "opaque", "transparent" (the default), or "window". (For more information, see Flash OBJECT and EMBED tag attributes (at adobe.com).
  • zIndex (a Numeric value) — (Optional) Set this property to assign the device panel to a specific z-index layer in the HTML DOM. If you do not specify this value, the device panel is added to a z-index layer above the existing HTML DOM elements.

    This property only applies if the replacementElementId parameter is set to null. If you specify a replacementElementId value, the Device Panel replaces the specified replacement DOM element. You can set the z-index layer of the parent DOM element containing the replacement element. For example, the following HTML code sets the z-index setting of the parent DOM element:

    <div id="deviceManagerDIVParent" style="position:absolute; z-index:1337">
        <div id="deviceManagerReplacementElement"></div>
    </div>

    However, if you do not specify a value for the replacementElementId parameter (or if it set to null) and you do not specify a zIndex value, then the call to the method assigns the new DOM element (for the device panel) to the top z-index layer of the DOM.

Returns

DevicePanel — The DevicePanel object.

removeEventListener(type:String, listener:Function)

Removes an event listener for a specific event.

Parameters

type (String) — The string identifying the type of event.

listener (Function) — The event listener function to remove.

The application throws an error if the listener name is invalid.

See

addEventListener()

removePanel(panel:DevicePanel)

Removes the specified device panel from the HTML DOM.

Parameters

panel (DevicePanel) — The device panel to remove.

The application throws an error if the device panel does not exist in the HTML DOM.

DeviceManager events

A DeviceManager object can dispatch events of the following type:

Event type Event class Description
"devicesDetected" DeviceStatusEvent A DeviceManger dispatches a devicesDetected event in response to calling the detectDevices() method.

Note: The status property of each Camera or Microphone object for this event is always set to "unknown". To determine when the user has clicked the Allow button in the Flash Player Settings dialog box, add an event listener for the streamCreated event, and check the connection.connectionId property to see that if it corresponds to the connection.connectionId of your Session object. If they match, it indicates that the user has allowed access to the camera and microphone. (See Session events.)

To check whether a user has available cameras and other requirements for publishing, check the capabilities property of the Session object.

For an example of using this event, see DeviceManager.detectDevices().

DeviceManager Example

The following example shows the functionality of the DeviceManager and DevicePanel classes:

<script type="text/javascript">
var session;
var API_KEY = ""; // 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 publisher;
var devicePanel;
var deviceManager;

session = TB.initSession(sessionId);

function init() {
    session.addEventListener("sessionConnected", sessionConnectedHandler);
    session.connect(API_KEY, token);
}

function sessionConnectedHandler(event) {
    publishMe();
    addDeviceManager();
}

function addDeviceManager() {
    deviceManager = TB.initDeviceManager(API_KEY);
    deviceManager.addEventListener("devicesDetected", devicesDetectedHandler);
    deviceManager.detectDevices();
}

function devicesDetectedHandler(event) {
    reportDevices(event.selectedCamera, event.selectedMicrophone);
}

function publishMe() {
    var publisherContainer = document.getElementById("publisherContainer");
    publisher = TB.initPublisher(API_KEY, publisherContainer.id);
    session.publish(publisher);
    publisher.addEventListener("settingsButtonClick", settingsButtonClickHandler);
}

function settingsButtonClickHandler() {
    var newDiv = document.createElement("div");
    newDiv.id = "devicePanel";
    document.getElementById("devicePanelContainer").appendChild(newDiv);
    devicePanel = deviceManager.displayPanel("devicePanel", publisher);
    devicePanel.addEventListener("devicesSelected", devicesSelectedHandler);
    document.getElementById("closeButton").style.visibility = "visible";
}

function devicesSelectedHandler(event) {
    reportDevices(event.camera, event.microphone);
}

function reportDevices(camera, mic) {
    document.getElementById("cameraNameDiv").innerHTML = "Camera: " + camera.name;
    document.getElementById("micNameDiv").innerHTML = "Microphone: " + mic.name;
}

function closePanel() {
    deviceManager.removePanel(devicePanel);
    document.getElementById("closeButton").style.visibility = "hidden";
}
</script>
</head>
<body onLoad="init()">
    <div id="publisherContainer"></div>
    <div id="cameraNameDiv"></div>
    <div id="micNameDiv"></div>
    <div id="devicePanelContainer"></div>
    <div>
        <input id="closeButton" type="button" onclick="closePanel()" value="Close panel" style="visibility:hidden">
    </div>
</body>

IRC Live Chat

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