Added ability to notify about available media device list changes

JitsiMediaDevices.js

@@ -0,0 +1,74 @@
+var EventEmitter = require("events");
+var RTCEvents = require('./service/RTC/RTCEvents');
+var RTC = require("./modules/RTC/RTC");
+var JitsiMediaDevicesEvents = require('./JitsiMediaDevicesEvents');
+
+var eventEmitter = new EventEmitter();
+
+RTC.addListener(RTCEvents.DEVICE_LIST_CHANGED,
+    function (devices) {
+        eventEmitter.emit(JitsiMediaDevicesEvents.DEVICE_LIST_CHANGED, devices);
+    });
+
+var JitsiMediaDevices = {
+    /**
+     * Executes callback with list of media devices connected.
+     * @param {function} callback
+     */
+    enumerateDevices: function (callback) {
+        RTC.enumerateDevices(callback);
+    },
+    /**
+     * Checks if its possible to enumerate available cameras/micropones.
+     * @returns {boolean} true if available, false otherwise.
+     */
+    isDeviceListAvailable: function () {
+        return RTC.isDeviceListAvailable();
+    },
+    /**
+     * Returns true if changing the input (camera / microphone) or output
+     * (audio) device is supported and false if not.
+     * @params {string} [deviceType] - type of device to change. Default is
+     *      undefined or 'input', 'output' - for audio output device change.
+     * @returns {boolean} true if available, false otherwise.
+     */
+    isDeviceChangeAvailable: function (deviceType) {
+        return RTC.isDeviceChangeAvailable(deviceType);
+    },
+    /**
+     * Returns currently used audio output device id, '' stands for default
+     * device
+     * @returns {string}
+     */
+    getAudioOutputDevice: function () {
+        return RTC.getAudioOutputDevice();
+    },
+    /**
+     * Sets current audio output device.
+     * @param {string} deviceId - id of 'audiooutput' device from
+     *      navigator.mediaDevices.enumerateDevices(), '' is for default device
+     * @returns {Promise} - resolves when audio output is changed, is rejected
+     *      otherwise
+     */
+    setAudioOutputDevice: function (deviceId) {
+        return RTC.setAudioOutputDevice(deviceId);
+    },
+    /**
+     * Adds an event handler.
+     * @param {string} event - event name
+     * @param {function} handler - event handler
+     */
+    addEventListener: function (event, handler) {
+        eventEmitter.addListener(event, handler);
+    },
+    /**
+     * Removes event handler.
+     * @param {string} event - event name
+     * @param {function} handler - event handler
+     */
+    removeEventListener: function (event, handler) {
+        eventEmitter.removeListener(event, handler);
+    }
+};
+
+module.exports = JitsiMediaDevices;

JitsiMediaDevicesEvents.js

@@ -0,0 +1,17 @@
+/**
+ * Enumeration with the events for the media devices.
+ * @type {{string: string}}
+ */
+var JitsiMediaDevicesEvents = {
+    /**
+     * Indicates that the list of available media devices has been changed. The
+     * event provides the following parameters to its listeners:
+     *
+     * @param {MediaDeviceInfo[]} devices - array of MediaDeviceInfo or
+     *  MediaDeviceInfo-like objects that are currently connected.
+     *  @see https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo
+     */
+    DEVICE_LIST_CHANGED: "mediaDevices.devicechange"
+};
+
+module.exports = JitsiMediaDevicesEvents;

JitsiMeetJS.js

@@ -1,7 +1,9 @@
 var logger = require("jitsi-meet-logger").getLogger(__filename);
 var JitsiConnection = require("./JitsiConnection");
+var JitsiMediaDevices = require("./JitsiMediaDevices");
 var JitsiConferenceEvents = require("./JitsiConferenceEvents");
 var JitsiConnectionEvents = require("./JitsiConnectionEvents");
+var JitsiMediaDevicesEvents = require('./JitsiMediaDevicesEvents');
 var JitsiConnectionErrors = require("./JitsiConnectionErrors");
 var JitsiConferenceErrors = require("./JitsiConferenceErrors");
 var JitsiTrackEvents = require("./JitsiTrackEvents");
@@ -40,7 +42,8 @@ var LibJitsiMeet = {
     events: {
         conference: JitsiConferenceEvents,
         connection: JitsiConnectionEvents,
-        track: JitsiTrackEvents
+        track: JitsiTrackEvents,
+        mediaDevices: JitsiMediaDevicesEvents
     },
     errors: {
         conference: JitsiConferenceErrors,
@@ -48,6 +51,7 @@ var LibJitsiMeet = {
         track: JitsiTrackErrors
     },
     logLevels: Logger.levels,
+    mediaDevices: JitsiMediaDevices,
     /**
      * Array of functions that will receive the GUM error.
      */
@@ -146,9 +150,12 @@ var LibJitsiMeet = {
     /**
      * Checks if its possible to enumerate available cameras/micropones.
      * @returns {boolean} true if available, false otherwise.
+     * @deprecated use JitsiMeetJS.mediaDevices.isDeviceListAvailable instead
      */
     isDeviceListAvailable: function () {
-        return RTC.isDeviceListAvailable();
+        logger.warn('This method is deprecated, use ' +
+            'JitsiMeetJS.mediaDevices.isDeviceListAvailable instead');
+        return this.mediaDevices.isDeviceListAvailable();
     },
     /**
      * Returns true if changing the input (camera / microphone) or output
@@ -156,30 +163,22 @@ var LibJitsiMeet = {
      * @params {string} [deviceType] - type of device to change. Default is
      *      undefined or 'input', 'output' - for audio output device change.
      * @returns {boolean} true if available, false otherwise.
+     * @deprecated use JitsiMeetJS.mediaDevices.isDeviceChangeAvailable instead
      */
     isDeviceChangeAvailable: function (deviceType) {
-        return RTC.isDeviceChangeAvailable(deviceType);
+        logger.warn('This method is deprecated, use ' +
+            'JitsiMeetJS.mediaDevices.isDeviceChangeAvailable instead');
+        return this.mediaDevices.isDeviceChangeAvailable(deviceType);
     },
     /**
-     * Returns currently used audio output device id, '' stands for default
-     * device
-     * @returns {string}
+     * Executes callback with list of media devices connected.
+     * @param {function} callback
+     * @deprecated use JitsiMeetJS.mediaDevices.enumerateDevices instead
      */
-    getAudioOutputDevice: function () {
-        return RTC.getAudioOutputDevice();
-    },
-    /**
-     * Sets current audio output device.
-     * @param {string} deviceId - id of 'audiooutput' device from
-     *      navigator.mediaDevices.enumerateDevices(), '' is for default device
-     * @returns {Promise} - resolves when audio output is changed, is rejected
-     *      otherwise
-     */
-    setAudioOutputDevice: function (deviceId) {
-        return RTC.setAudioOutputDevice(deviceId);
-    },
     enumerateDevices: function (callback) {
-        RTC.enumerateDevices(callback);
+        logger.warn('This method is deprecated, use ' +
+            'JitsiMeetJS.mediaDevices.enumerateDevices instead');
+        this.mediaDevices.enumerateDevices(callback);
     },
     /**
      * Array of functions that will receive the unhandled errors.

doc/API.md

@@ -65,18 +65,24 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
         5. minFps - the minimum frame rate for the video stream (passed to GUM)
         6. maxFps - the maximum frame rate for the video stream (passed to GUM)
 
-* ```JitsiMeetJS.enumerateDevices(callback)``` - returns list of the available devices as a parameter to the callback function. Every device is a object with the following format:
-    - label - the name of the device
-    - kind - "audioinput" or "videoinput"
-    - deviceId - the id of the device.
-
-* ```JitsiMeetJS.isDeviceListAvailable()``` - returns true if retrieving the device list is support and false - otherwise.
-* ```JitsiMeetJS.isDeviceChangeAvailable(deviceType)``` - returns true if changing the input (camera / microphone) or output (audio) device is supported and false if not. ```deviceType``` is a type of device to change. Undefined or 'input' stands for input devices, 'output' - for audio output devices.
-* ```JitsiMeetJS.setAudioOutputDevice(deviceId)``` - sets current audio output device. ```deviceId``` - id of 'audiooutput' device from ```JitsiMeetJS.enumerateDevices()```, '' is for default device.
-* ```JitsiMeetJS.getAudioOutputDevice()``` - returns currently used audio output device id, '' stands for default device.
+* ```JitsiMeetJS.enumerateDevices(callback)``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.enumerateDevices(callback)``` instead.
+* ```JitsiMeetJS.isDeviceListAvailable()``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.isDeviceListAvailable()``` instead.
+* ```JitsiMeetJS.isDeviceChangeAvailable(deviceType)``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.isDeviceChangeAvailable(deviceType)``` instead.
 * ```JitsiMeetJS.isDesktopSharingEnabled()``` - returns true if desktop sharing is supported and false otherwise. NOTE: that method can be used after ```JitsiMeetJS.init(options)``` is completed otherwise the result will be always null.
 * ```JitsiMeetJS.getGlobalOnErrorHandler()``` - returns function that can be used to be attached to window.onerror and if options.enableWindowOnErrorHandler is enabled returns the function used by the lib. (function(message, source, lineno, colno, error)).
 
+* ```JitsiMeetJS.mediaDevices``` - JS object that contains methods for interaction with media devices. Following methods are available:
+    - ```isDeviceListAvailable()``` - returns true if retrieving the device list is supported and false - otherwise
+    - ```isDeviceChangeAvailable(deviceType)``` - returns true if changing the input (camera / microphone) or output (audio) device is supported and false if not. ```deviceType``` is a type of device to change. Undefined or 'input' stands for input devices, 'output' - for audio output devices.
+    - ```enumerateDevices(callback)``` - returns list of the available devices as a parameter to the callback function. Every device is a MediaDeviceInfo object with the following properties:
+        - label - the name of the device
+        - kind - "audioinput", "videoinput" or "audiooutput"
+        - deviceId - the id of the device
+        - groupId - group identifier, two devices have the same group identifier if they belong to the same physical device; for example a monitor with both a built-in camera and microphone
+    - ```setAudioOutputDevice(deviceId)``` - sets current audio output device. ```deviceId``` - id of 'audiooutput' device from ```JitsiMeetJS.enumerateDevices()```, '' is for default device.
+    - ```getAudioOutputDevice()``` - returns currently used audio output device id, '' stands for default device.
+    - ```addEventListener(event, handler)``` - attaches an event handler.
+    - ```removeEventListener(event, handler)``` - removes an event handler.
 
 
 * ```JitsiMeetJS.events``` - JS object that contains all events used by the API. You will need that JS object when you try to subscribe for connection or conference events.
@@ -120,6 +126,9 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
         event can be fired when ```dispose()``` method is called or for other reasons.
         - TRACK_AUDIO_OUTPUT_CHANGED - indicates that audio output device for track was changed (parameters - deviceId (string) - new audio output device ID).
         
+    4. mediaDevices
+        - DEVICE_LIST_CHANGED - indicates that list of currently connected devices has changed (parameters - devices(MediaDeviceInfo[])).
+        
 
 * ```JitsiMeetJS.errors``` - JS object that contains all errors used by the API. You can use that object to check the reported errors from the API
     We have two error types - connection and conference. You can access the events with the following code ```JitsiMeetJS.errors.<error_type>.<error_name>```.

doc/example/example.js

@@ -147,6 +147,13 @@ function onConnectionSuccess(){
  */
 function onConnectionFailed(){console.error("Connection Failed!")};
 
+/**
+ * This function is called when the connection fail.
+ */
+function onDeviceListChanged(devices) {
+    console.info('current devices', devices);
+}
+
 /**
  * This function is called when we disconnect.
  */
@@ -189,7 +196,7 @@ function switchVideo() {
 }
 
 function changeAudioOutput(selected) {
-    JitsiMeetJS.setAudioOutputDevice(selected.value);
+    JitsiMeetJS.mediaDevices.setAudioOutputDevice(selected.value);
 }
 
 $(window).bind('beforeunload', unload);
@@ -231,6 +238,8 @@ JitsiMeetJS.init(initOptions).then(function(){
     connection.addEventListener(JitsiMeetJS.events.connection.CONNECTION_FAILED, onConnectionFailed);
     connection.addEventListener(JitsiMeetJS.events.connection.CONNECTION_DISCONNECTED, disconnect);
 
+    JitsiMeetJS.mediaDevices.addEventListener(JitsiMeetJS.events.mediaDevices.DEVICE_LIST_CHANGED, onDeviceListChanged);
+
     connection.connect();
     JitsiMeetJS.createLocalTracks({devices: ["audio", "video"]}).
         then(onLocalTracks).catch(function (error) {
@@ -241,8 +250,8 @@ JitsiMeetJS.init(initOptions).then(function(){
 });
 
 
-if (JitsiMeetJS.isDeviceChangeAvailable('output')) {
-    JitsiMeetJS.enumerateDevices(function(devices) {
+if (JitsiMeetJS.mediaDevices.isDeviceChangeAvailable('output')) {
+    JitsiMeetJS.mediaDevices.enumerateDevices(function(devices) {
         var audioOutputDevices = devices.filter(function(d) { return d.kind === 'audiooutput'; });
 
         if (audioOutputDevices.length > 1) {

modules/RTC/RTCUtils.js

@@ -19,6 +19,8 @@ var VideoType = require("../../service/RTC/VideoType");
 
 var eventEmitter = new EventEmitter();
 
+var AVAILABLE_DEVICES_POLL_INTERVAL_TIME = 3000; // ms
+
 var devices = {
     audio: true,
     video: true
@@ -30,6 +32,19 @@ var featureDetectionAudioEl = document.createElement('audio');
 var isAudioOutputDeviceChangeAvailable =
     typeof featureDetectionAudioEl.setSinkId !== 'undefined';
 
+var currentlyAvailableMediaDevices = [];
+
+// TODO: currently no browser supports 'devicechange' event even in nightly
+// builds so no feature/browser detection is used at all. However in future this
+// should be changed to some expression. Progress on 'devicechange' event
+// implementation for Chrome/Opera/NWJS can be tracked at
+// https://bugs.chromium.org/p/chromium/issues/detail?id=388648, for Firefox -
+// at https://bugzilla.mozilla.org/show_bug.cgi?id=1152383. More information on
+// 'devicechange' event can be found in spec -
+// http://w3c.github.io/mediacapture-main/#event-mediadevices-devicechange
+// TODO: check MS Edge
+var isDeviceChangeEventSupported = false;
+
 var rtcReady = false;
 
 function setResolutionConstraints(constraints, resolution) {
@@ -217,6 +232,57 @@ function setAvailableDevices(um, available) {
     eventEmitter.emit(RTCEvents.AVAILABLE_DEVICES_CHANGED, devices);
 }
 
+/**
+ * Checks if new list of available media devices differs from previous one.
+ * @param {MediaDeviceInfo[]} newDevices - list of new devices.
+ * @returns {boolean} - true if list is different, false otherwise.
+ */
+function compareAvailableMediaDevices(newDevices) {
+    if (newDevices.length !== currentlyAvailableMediaDevices.length) {
+        return true;
+    }
+
+    return newDevices.map(mediaDeviceInfoToJSON).sort().join('') !==
+        currentlyAvailableMediaDevices.map(mediaDeviceInfoToJSON).sort().join('');
+
+    function mediaDeviceInfoToJSON(info) {
+        return JSON.stringify({
+            kind: info.kind,
+            deviceId: info.deviceId,
+            groupId: info.groupId,
+            label: info.label,
+            facing: info.facing
+        });
+    }
+}
+
+/**
+ * Periodically polls enumerateDevices() method to check if list of media
+ * devices has changed. This is temporary workaround until 'devicechange' event
+ * will be supported by browsers.
+ */
+function pollForAvailableMediaDevices() {
+    RTCUtils.enumerateDevices(function (devices) {
+        if (compareAvailableMediaDevices(devices)) {
+            onMediaDevicesListChanged(devices);
+        }
+
+        window.setTimeout(pollForAvailableMediaDevices,
+            AVAILABLE_DEVICES_POLL_INTERVAL_TIME);
+    });
+}
+
+/**
+ * Event handler for the 'devicechange' event.
+ * @param {MediaDeviceInfo[]} devices - list of media devices.
+ * @emits RTCEvents.DEVICE_LIST_CHANGED
+ */
+function onMediaDevicesListChanged(devices) {
+    currentlyAvailableMediaDevices = devices;
+    eventEmitter.emit(RTCEvents.DEVICE_LIST_CHANGED, devices);
+    logger.info('list of media devices has changed:', devices);
+}
+
 // In case of IE we continue from 'onReady' callback
 // passed to RTCUtils constructor. It will be invoked by Temasys plugin
 // once it is initialized.
@@ -224,6 +290,14 @@ function onReady (options, GUM) {
     rtcReady = true;
     eventEmitter.emit(RTCEvents.RTC_READY, true);
     screenObtainer.init(options, GUM);
+
+    if (isDeviceChangeEventSupported && RTCUtils.isDeviceListAvailable()) {
+        navigator.mediaDevices.addEventListener('devicechange', function () {
+            RTCUtils.enumerateDevices(onMediaDevicesListChanged);
+        });
+    } else if (RTCUtils.isDeviceListAvailable()) {
+        pollForAvailableMediaDevices();
+    }
 }
 
 /**

service/RTC/RTCEvents.js

@@ -7,7 +7,8 @@ var RTCEvents = {
     AVAILABLE_DEVICES_CHANGED: "rtc.available_devices_changed",
     FAKE_VIDEO_TRACK_CREATED: "rtc.fake_video_track_created",
     TRACK_ATTACHED: "rtc.track_attached",
-    AUDIO_OUTPUT_DEVICE_CHANGED: "rtc.audio_output_device_changed"
+    AUDIO_OUTPUT_DEVICE_CHANGED: "rtc.audio_output_device_changed",
+    DEVICE_LIST_CHANGED: "rtc.device_list_changed"
 };
 
 module.exports = RTCEvents;