updated api doc, additional comments

doc/API.md

@@ -84,6 +84,9 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
 * ```JitsiMeetJS.enumerateDevices(callback)``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.enumerateDevices(callback)``` 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.getActiveAudioDevice()``` - goes through all audio devices on the system and returns information about one that is active, i.e. has audio signal. Returns a Promise resolving to an Object with the following structure:
+    - deviceId - string containing the device ID of the audio track found as active.
+    - deviceLabel - string containing the label of the audio device.
 * ```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:
@@ -132,6 +135,8 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
         - ENDPOINT_MESSAGE_RECEIVED - notifies that a new message
         from another participant is received on a data channel.
         - TALK_WHILE_MUTED - notifies that a local user is talking while having the microphone muted.
+        - NO_AUDIO_INPUT - notifies that the current selected input device has no signal.
+        - AUDIO_INPUT_STATE_CHANGE - notifies that the current conference audio input switched between audio input states i.e. with or without audio input.
 
     2. connection
         - CONNECTION_FAILED - indicates that the server connection failed.

modules/detection/ActiveDeviceDetector.js

@@ -66,8 +66,7 @@ export default function getActiveAudioDevice() {
                         if (audioLevel > 0.008) {
                             stopActiveDevices(availableDevices);
                             resolve({ deviceId: device.deviceId,
-                                deviceLabel: device.track.label,
-                                audioLevel });
+                                deviceLabel: device.track.label });
                         }
                     });
                 }
@@ -76,8 +75,7 @@ export default function getActiveAudioDevice() {
                 setTimeout(() => {
                     stopActiveDevices(availableDevices);
                     resolve({ deviceId: '',
-                        deviceLabel: '',
-                        audioLevel: 0 });
+                        deviceLabel: '' });
                 }, DETECTION_TIMEOUT);
 
             });

modules/detection/DetectionEvents.js

@@ -1,7 +1,7 @@
 /** Event triggered by NoAudioSignalDetector when the local audio device associated with a JitsiConference goes silent
  * for a period of time, meaning that the device is either broken or hardware/software muted.
  * @event
- * @type {Object} - empty
+ * @type {void}
  */
 export const NO_AUDIO_INPUT = 'no_audio_input_detected';
 

modules/detection/NoAudioSignalDetection.js

@@ -11,6 +11,8 @@ const SILENCE_PERIOD_MS = 4000;
 /**
  * Detect if there is no audio input on the current TraceAblePeerConnection selected track. The no audio
  * state must be constant for a configured amount of time in order for the event to be triggered.
+ * @fires DetectionEvents.AUDIO_INPUT_STATE_CHANGE
+ * @fires DetectionEvents.NO_AUDIO_INPUT
  */
 export default class NoAudioSignalDetection extends EventEmitter {
     /**
@@ -41,6 +43,7 @@ export default class NoAudioSignalDetection extends EventEmitter {
      * Generated event triggered by a change in the current conference audio input state.
      *
      * @param {*} audioLevel
+     * @fires DetectionEvents.AUDIO_INPUT_STATE_CHANGE
      */
     _handleAudioInputStateChange(audioLevel) {
         // Current audio input state of the active local track in the conference, true for audio input false for no
@@ -58,6 +61,13 @@ export default class NoAudioSignalDetection extends EventEmitter {
 
         if (shouldTrigger) {
             this._hasAudioInput = status;
+
+            /**
+             * Event fired when the audio input state of the conference changes, true for audio input false otherwise.
+             *
+             * @event DetectionEvents.AUDIO_INPUT_STATE_CHANGE
+             * @type {boolean}
+             */
             this.emit(DetectionEvents.AUDIO_INPUT_STATE_CHANGE, this._hasAudioInput);
         }
     }
@@ -66,6 +76,7 @@ export default class NoAudioSignalDetection extends EventEmitter {
      * Generate event triggered by a prolonged period of no audio input.
      *
      * @param {number} audioLevel - The audio level of the ssrc.
+     * @fires DetectionEvents.NO_AUDIO_INPUT
      */
     _handleNoAudioInputDetection(audioLevel) {
         if (this._eventFired) {
@@ -75,6 +86,13 @@ export default class NoAudioSignalDetection extends EventEmitter {
         if (audioLevel === 0 && !this._timeoutTrigger) {
             this._timeoutTrigger = setTimeout(() => {
                 this._eventFired = true;
+
+                /**
+                 * Event fired when there is no audio input for a predefined period of time.
+                 *
+                 * @event DetectionEvents.AUDIO_INPUT_STATE_CHANGE
+                 * @type {void}
+                 */
                 this.emit(DetectionEvents.NO_AUDIO_INPUT);
             }, SILENCE_PERIOD_MS);
         } else if (audioLevel !== 0 && this._timeoutTrigger) {
@@ -92,7 +110,7 @@ export default class NoAudioSignalDetection extends EventEmitter {
      * @param {boolean} isLocal - true for local/send streams or false for remote/receive streams.
      */
     _audioLevel(tpc, ssrc, audioLevel, isLocal) {
-        // We are interested in the local audio stream if the event was not triggered on this device.
+        // We are interested in the local audio streams
         if (!isLocal || !this._audioTrack) {
             return;
         }

modules/detection/VADTalkMutedDetection.js

@@ -1,8 +1,8 @@
 import { EventEmitter } from 'events';
-import { VAD_SCORE_PUBLISHED, VAD_TALK_WHILE_MUTED } from './DetectionEvents';
+import * as JitsiConferenceEvents from '../../JitsiConferenceEvents';
 import { getLogger } from 'jitsi-meet-logger';
+import { VAD_SCORE_PUBLISHED, VAD_TALK_WHILE_MUTED } from './DetectionEvents';
 import TrackVADEmitter from './TrackVADEmitter';
-import * as JitsiConferenceEvents from '../../JitsiConferenceEvents';
 
 const logger = getLogger(__filename);