Merge branch 'tsareg-master'

JitsiMeetJS.js

         return RTC.isDeviceListAvailable();
     },
     /**
-     * Returns true if changing the camera / microphone device is supported and
-     * false if not.
+     * 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 () {
-        return RTC.isDeviceChangeAvailable();
+    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);
     },
     enumerateDevices: function (callback) {
         RTC.enumerateDevices(callback);

JitsiTrackEvents.js

     /**
      * The video type("camera" or "desktop") of the track was changed.
      */
-     TRACK_VIDEOTYPE_CHANGED: "track.videoTypeChanged"
+    TRACK_VIDEOTYPE_CHANGED: "track.videoTypeChanged",
+    /**
+     * The audio output of the track was changed.
+     */
+    TRACK_AUDIO_OUTPUT_CHANGED: "track.audioOutputChanged"
 };
 
 module.exports = JitsiTrackEvents;

doc/API.md

     - 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.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.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.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.
     We have two event types - connection and conference. You can access the events with the following code ```JitsiMeetJS.events.<event_type>.<event_name>```.
     For example if you want to use the conference event that is fired when somebody leave conference you can use the following code - ```JitsiMeetJS.events.conference.USER_LEFT```.
     3. tracks
         - LOCAL_TRACK_STOPPED - indicates that a local track was stopped. This
         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).
+        
 
 * ```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>```.
 9. getParticipantId() - returns id(string) of the track owner
 
    Note: This method is implemented only for the remote tracks.
+   
+10. setAudioOutput(audioOutputDeviceId) - sets new audio output device for track's DOM elements. Video tracks are ignored.
 
 
 Getting Started

doc/example/example.js

             function () {
                 console.log("local track stoped");
             });
+        localTracks[i].addEventListener(JitsiMeetJS.events.track.TRACK_AUDIO_OUTPUT_CHANGED,
+            function (deviceId) {
+                console.log("track audio output device was changed to " + deviceId);
+            });
         if(localTracks[i].getType() == "video") {
             $("body").append("<video autoplay='1' id='localVideo" + i + "' />");
             localTracks[i].attach($("#localVideo" + i)[0]);
         function () {
             console.log("remote track stoped");
         });
+    track.addEventListener(JitsiMeetJS.events.track.TRACK_AUDIO_OUTPUT_CHANGED,
+        function (deviceId) {
+            console.log("track audio output device was changed to " + deviceId);
+        });
     var id = participant + track.getType() + idx;
     if(track.getType() == "video") {
         $("body").append("<video autoplay='1' id='" + participant + "video" + idx + "' />");
         });
 }
 
+function changeAudioOutput(selected) {
+    JitsiMeetJS.setAudioOutputDevice(selected.value);
+}
+
 $(window).bind('beforeunload', unload);
 $(window).bind('unload', unload);
 
     console.log(error);
 });
 
+
+if (JitsiMeetJS.isDeviceChangeAvailable('output')) {
+    JitsiMeetJS.enumerateDevices(function(devices) {
+        var audioOutputDevices = devices.filter(function(d) { return d.kind === 'audiooutput'; });
+
+        if (audioOutputDevices.length > 1) {
+            $('#audioOutputSelect').html(
+                audioOutputDevices.map(function (d) {
+                    return '<option value="' + d.deviceId + '">' + d.label + '</option>';
+                }).join('\n')
+            );
+
+            $('#audioOutputSelectWrapper').show();
+        }
+    })
+}
+
 var connection = null;
 var room = null;
 var localTracks = [];

doc/example/index.html

 <body>
     <a href="#" onclick="unload()">Unload</a>
     <a href="#" onclick="switchVideo()">switchVideo</a>
+    <div id="audioOutputSelectWrapper" style="display: none;">
+        Change audio output device
+        <select id="audioOutputSelect" onchange="changeAudioOutput(this)"></select>
+    </div>
     <!-- <video id="localVideo" autoplay="true"></video> -->
     <!--<audio id="localAudio" autoplay="true" muted="true"></audio>-->
 </body>

modules/RTC/JitsiTrack.js

         }
         addMediaStreamInactiveHandler(stream, streamInactiveHandler);
     }
+
+    RTCUtils.addListener(RTCEvents.AUDIO_OUTPUT_DEVICE_CHANGED, this.setAudioOutput.bind(this));
 }
 
 /**
     return (streamId && trackId) ? (streamId + " " + trackId) : null;
 };
 
+/**
+ * Sets new audio output device for track's DOM elements. Video tracks are
+ * ignored.
+ * @param {string} audioOutputDeviceId - id of 'audiooutput' device from
+ *      navigator.mediaDevices.enumerateDevices(), '' for default device
+ * @emits JitsiTrackEvents.TRACK_AUDIO_OUTPUT_CHANGED
+ * @returns {Promise}
+ */
+JitsiTrack.prototype.setAudioOutput = function (audioOutputDeviceId) {
+    var self = this;
+
+    if (!RTCUtils.isDeviceChangeAvailable('output')) {
+        return Promise.reject(
+            new Error('Audio output device change is not supported'));
+    }
+
+    // All audio communication is done through audio tracks, so ignore changing
+    // audio output for video tracks at all.
+    if (this.isVideoTrack()) {
+        return Promise.resolve();
+    }
+
+    return Promise.all(this.containers.map(function(element) {
+        return element.setSinkId(audioOutputDeviceId)
+            .catch(function (error) {
+                logger.error('Failed to change audio output device on element',
+                    element, error);
+
+                    throw error;
+            });
+    }))
+    .then(function () {
+        self.eventEmitter.emit(JitsiTrackEvents.TRACK_AUDIO_OUTPUT_CHANGED,
+            audioOutputDeviceId);
+    });
+};
+
 module.exports = JitsiTrack;

modules/RTC/RTC.js

 };
 
 /**
- * Returns true if changing the camera / microphone device is supported and
- * false if not.
+ * 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.
+ */
+RTC.isDeviceChangeAvailable = function (deviceType) {
+    return RTCUtils.isDeviceChangeAvailable(deviceType);
+};
+
+/**
+ * Returns currently used audio output device id, '' stands for default
+ * device
+ * @returns {string}
+ */
+RTC.getAudioOutputDevice = function () {
+    return RTCUtils.getAudioOutputDevice();
+};
+
+/**
+ * Sets current audio output device.
+ * @param {string} deviceId - id of 'audiooutput' device from
+ *      navigator.mediaDevices.enumerateDevices()
+ * @returns {Promise} - resolves when audio output is changed, is rejected
+ *      otherwise
  */
-RTC.isDeviceChangeAvailable = function () {
-    return RTCUtils.isDeviceChangeAvailable();
+RTC.setAudioOutputDevice = function (deviceId) {
+    return RTCUtils.setAudioOutputDevice(deviceId);
 };
 
 /**
  * Returns <tt>true<tt/> if given WebRTC MediaStream is considered a valid
  * "user" stream which means that it's not a "receive only" stream nor a "mixed"
  * JVB stream.
- * 
+ *
  * Clients that implement Unified Plan, such as Firefox use recvonly
  * "streams/channels/tracks" for receiving remote stream/tracks, as opposed to
  * Plan B where there are only 3 channels: audio, video and data.
- * 
+ *
  * @param stream WebRTC MediaStream instance
  * @returns {boolean}
  */

modules/RTC/RTCUtils.js

     video: true
 };
 
+var audioOuputDeviceId = ''; // default device
+
+var featureDetectionAudioEl = document.createElement('audio');
+var isAudioOutputDeviceChangeAvailable =
+    typeof featureDetectionAudioEl.setSinkId !== 'undefined';
+
 var rtcReady = false;
 
 function setResolutionConstraints(constraints, resolution) {
                 //add auto devices
                 devices.unshift(
                     createAutoDeviceInfo('audioinput'),
-                    createAutoDeviceInfo('videoinput')
+                    createAutoDeviceInfo('videoinput'),
+                    createAutoDeviceInfo('audiooutput')
                 );
 
                 callback(devices);
                 console.error('cannot enumerate devices: ', err);
 
                 // return only auto devices
-                callback([createAutoDeviceInfo('audioinput'),
-                          createAutoDeviceInfo('videoinput')]);
+                callback([
+                    createAutoDeviceInfo('audioinput'),
+                    createAutoDeviceInfo('videoinput'),
+                    createAutoDeviceInfo('audiooutput')
+                ]);
             });
         });
     };
             return {
                 facing: source.facing || null,
                 label: source.label,
-                kind: kind ? kind + 'input': null,
+                // theoretically deprecated MediaStreamTrack.getSources should
+                // not return 'audiooutput' devices but let's handle it in any
+                // case
+                kind: kind
+                    ? (kind === 'audiooutput' ? kind : kind + 'input')
+                    : null,
                 deviceId: source.id,
                 groupId: source.groupId || null
             };
         //add auto devices
         devices.unshift(
             createAutoDeviceInfo('audioinput'),
-            createAutoDeviceInfo('videoinput')
+            createAutoDeviceInfo('videoinput'),
+            createAutoDeviceInfo('audiooutput')
         );
         callback(devices);
     });
     return res;
 }
 
+/**
+ * Wraps original attachMediaStream function to set current audio output device
+ * if this is supported.
+ * @param {Function} origAttachMediaStream
+ * @returns {Function}
+ */
+function wrapAttachMediaStream(origAttachMediaStream) {
+    return function(element, stream) {
+        var res = origAttachMediaStream.apply(RTCUtils, arguments);
+
+        if (RTCUtils.isDeviceChangeAvailable('output') &&
+            stream.getAudioTracks && stream.getAudioTracks().length) {
+            element.setSinkId(RTCUtils.getAudioOutputDevice())
+                .catch(function (ex) {
+                    logger.error('Failed to set audio output on element',
+                        element, ex);
+                });
+        }
+
+        return res;
+    }
+}
+
 //Options parameter is to pass config options. Currently uses only "useIPv6".
 var RTCUtils = {
     init: function (options) {
                     navigator.mediaDevices.enumerateDevices.bind(navigator.mediaDevices)
                 );
                 this.pc_constraints = {};
-                this.attachMediaStream = function (element, stream) {
+                this.attachMediaStream = wrapAttachMediaStream(function (element, stream) {
                     //  srcObject is being standardized and FF will eventually
                     //  support that unprefixed. FF also supports the
                     //  "element.src = URL.createObjectURL(...)" combo, but that
                     element.play();
 
                     return element;
-                };
+                });
                 this.getStreamID = function (stream) {
                     var id = stream.id;
                     if (!id) {
                     this.getUserMedia = getUserMedia;
                     this.enumerateDevices = enumerateDevicesThroughMediaStreamTrack;
                 }
-                this.attachMediaStream = function (element, stream) {
+                this.attachMediaStream = wrapAttachMediaStream(function (element, stream) {
 
                     // saves the created url for the stream, so we can reuse it
                     // and not keep creating urls
                     element.src = stream.jitsiObjectURL;
 
                     return element;
-                };
+                });
                 this.getStreamID = function (stream) {
                     // streams from FF endpoints have the characters '{' and '}'
                     // that make jQuery choke.
                     self.peerconnection = RTCPeerConnection;
                     self.getUserMedia = window.getUserMedia;
                     self.enumerateDevices = enumerateDevicesThroughMediaStreamTrack;
-                    self.attachMediaStream = function (element, stream) {
+                    self.attachMediaStream = wrapAttachMediaStream(function (element, stream) {
 
                         if (stream.id === "dummyAudio" || stream.id === "dummyVideo") {
                             return;
                         }
 
                         return attachMediaStream(element, stream);
-                    };
+                    });
                     self.getStreamID = function (stream) {
                         return SDPUtil.filter_special_chars(stream.label);
                     };
         return (MediaStreamTrack && MediaStreamTrack.getSources)? true : false;
     },
     /**
-     * Returns true if changing the camera / microphone device is supported and
-     * false if not.
+     * 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 () {
-        return RTCBrowserType.isChrome() ||
-            RTCBrowserType.isFirefox() ||
-            RTCBrowserType.isOpera() ||
-            RTCBrowserType.isTemasysPluginUsed() ||
-            RTCBrowserType.isNWJS();
+    isDeviceChangeAvailable: function (deviceType) {
+        return deviceType === 'output' || deviceType === 'audiooutput'
+            ? isAudioOutputDeviceChangeAvailable
+            : RTCBrowserType.isChrome() ||
+                RTCBrowserType.isFirefox() ||
+                RTCBrowserType.isOpera() ||
+                RTCBrowserType.isTemasysPluginUsed()||
+                RTCBrowserType.isNWJS();
     },
     /**
      * A method to handle stopping of the stream.
      */
     isDesktopSharingEnabled: function () {
         return screenObtainer.isSupported();
-    }
+    },
+    /**
+     * Sets current audio output device.
+     * @param {string} deviceId - id of 'audiooutput' device from
+     *      navigator.mediaDevices.enumerateDevices(), '' for default device
+     * @returns {Promise} - resolves when audio output is changed, is rejected
+     *      otherwise
+     */
+    setAudioOutputDevice: function (deviceId) {
+        if (!this.isDeviceChangeAvailable('output')) {
+            Promise.reject(
+                new Error('Audio output device change is not supported'));
+        }
 
+        return featureDetectionAudioEl.setSinkId(deviceId)
+            .then(function() {
+                audioOuputDeviceId = deviceId;
+
+                logger.log('Audio output device set to ' + deviceId);
+
+                eventEmitter.emit(RTCEvents.AUDIO_OUTPUT_DEVICE_CHANGED,
+                    deviceId);
+            });
+    },
+    /**
+     * Returns currently used audio output device id, '' stands for default
+     * device
+     * @returns {string}
+     */
+    getAudioOutputDevice: function () {
+        return audioOuputDeviceId;
+    }
 };
 
 module.exports = RTCUtils;

service/RTC/RTCEvents.js

     LASTN_ENDPOINT_CHANGED: "rtc.lastn_endpoint_changed",
     AVAILABLE_DEVICES_CHANGED: "rtc.available_devices_changed",
     FAKE_VIDEO_TRACK_CREATED: "rtc.fake_video_track_created",
-    TRACK_ATTACHED: "rtc.track_attached"
+    TRACK_ATTACHED: "rtc.track_attached",
+    AUDIO_OUTPUT_DEVICE_CHANGED: "rtc.audio_output_device_changed"
 };
 
 module.exports = RTCEvents;