Fill in and tidy Audio API JSDoc

interface/src/scripting/Audio.h

@@ -40,24 +40,40 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable {
      * @hifi-server-entity
      * @hifi-assignment-client
      *
-     * @property {boolean} muted - <code>true</code> if the audio input is muted, otherwise <code>false</code>.
+     * @property {boolean} muted - <code>true</code> if the audio input is muted for the current user context (desktop or HMD), 
+     *     otherwise <code>false</code>.
+     * @property {boolean} desktopMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
+     * @property {boolean} hmdMuted - <code>true</code> if the HMD input is muted, otherwise <code>false</code>.
+     * @property {boolean} warnWhenMuted - <code>true</code> if the "muted" warning is enabled, otherwise <code>false</code>.
+     *     When enabled, a "muted" warning is displayed when you try to speak while your microphone is muted.
      * @property {boolean} noiseReduction - <code>true</code> if noise reduction is enabled, otherwise <code>false</code>. When
      *     enabled, the input audio signal is blocked (fully attenuated) when it falls below an adaptive threshold set just
      *     above the noise floor.
-     * @property {number} inputLevel - The loudness of the audio input, range <code>0.0</code> (no sound) &ndash;
-     *     <code>1.0</code> (the onset of clipping). <em>Read-only.</em>
-     * @property {boolean} clipping - <code>true</code> if the audio input is clipping, otherwise <code>false</code>.
      * @property {number} inputVolume - Adjusts the volume of the input audio; range <code>0.0</code> &ndash; <code>1.0</code>.
      *     If set to a value, the resulting value depends on the input device: for example, the volume can't be changed on some
      *     devices, and others might only support values of <code>0.0</code> and <code>1.0</code>.
-     * @property {boolean} isStereoInput - <code>true</code> if the input audio is being used in stereo, otherwise
+     * @property {number} inputLevel - The loudness of the audio input, range <code>0.0</code> (no sound) &ndash;
-     *     <code>false</code>. Some devices do not support stereo, in which case the value is always <code>false</code>.
+     *     <code>1.0</code> (the onset of clipping). <em>Read-only.</em>
+     * @property {boolean} clipping - <code>true</code> if the audio input is clipping, otherwise <code>false</code>.
      * @property {string} context - The current context of the audio: either <code>"Desktop"</code> or <code>"HMD"</code>.
      *     <em>Read-only.</em>
      * @property {object} devices <em>Read-only.</em> <strong>Deprecated:</strong> This property is deprecated and will be
      *     removed.
-     * @property {boolean} isSoloing <em>Read-only.</em> <code>true</code> if any nodes are soloed.
+     * @property {boolean} pushToTalk - <code>true</code> if push-to-talk is enabled for the current user context (desktop or 
-     * @property {Uuid[]} soloList <em>Read-only.</em> Get the list of currently soloed node UUIDs.
+     *     HMD), otherwise <code>false</code>.
+     * @property {boolean} pushToTalkDesktop - <code>true</code> if desktop push-to-talk is enabled, otherwise 
+     *     <code>false</code>.
+     * @property {boolean} pushToTalkHMD - <code>true</code> if HMD push-to-talk is enabled, otherwise <code>false</code>.
+     * @property {boolean} pushingToTalk - <code>true</code> if the user is currently pushing to talk, otherwise 
+     *     <code>false</code>.
+     *
+     * @comment The following properties are from AudioScriptingInterface.h.
+     * @property {boolean} isStereoInput - <code>true</code> if the input audio is being used in stereo, otherwise
+     *     <code>false</code>. Some devices do not support stereo, in which case the value is always <code>false</code>.
+     * @property {boolean} isSoloing - <code>true</code> if audio soloing, i.e., playing audio from only specific avatars. 
+     *     <em>Read-only.</em>
+     * @property {Uuid[]} soloList - The list of currently soloed avatar IDs. Empty list if not currently audio soloing. 
+     *     <em>Read-only.</em>
      */
 
     Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
@@ -131,7 +147,7 @@ public:
     Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD);
 
     /**jsdoc
-     * Enable or disable reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options
+     * Enables or disables reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options
      * come from either the domain's audio zone if used &mdash; configured on the server &mdash; or as scripted by
      * {@link Audio.setReverbOptions|setReverbOptions}.
      * @function Audio.setReverb
@@ -164,69 +180,65 @@ public:
     Q_INVOKABLE void setReverb(bool enable);
 
     /**jsdoc
-     * Configure reverberation options. Use {@link Audio.setReverb|setReverb} to enable or disable reverberation.
+     * Configures reverberation options. Use {@link Audio.setReverb|setReverb} to enable or disable reverberation.
      * @function Audio.setReverbOptions
      * @param {AudioEffectOptions} options - The reverberation options.
      */
     Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options);
 
     /**jsdoc
-     * Sets the avatar gain at the server.
+     * Sets the volume (gain) that avatar's voices are played at. This gain is used at the server.
-     * Units are Decibels (dB)
      * @function Audio.setAvatarGain
-     * @param {number} gain (in dB)
+     * @param {number} Avatar gain (dB) at the server.
-    */
+     */
     Q_INVOKABLE void setAvatarGain(float gain);
 
     /**jsdoc
-     * Gets the avatar gain at the server.
+     * Gets the volume (gain) that avatar's voices are played at. This gain is used at the server.
      * @function Audio.getAvatarGain
-     * @returns {number} gain (in dB)
+     * @returns {number} Avatar gain (dB) at the server.
-    */
+     */
     Q_INVOKABLE float getAvatarGain();
 
     /**jsdoc
-     * Sets the injector gain at the server.
+     * Sets the volume (gain) that the environment is played at, for sounds from the server.
-     * Units are Decibels (dB)
      * @function Audio.setInjectorGain
-     * @param {number} gain (in dB)
+     * @param {number} Injector gain (dB) at the server.
-    */
+     */
     Q_INVOKABLE void setInjectorGain(float gain);
 
     /**jsdoc
-     * Gets the injector gain at the server.
+     * Gets the volume (gain) that the environment is played at, for sounds from the server.
      * @function Audio.getInjectorGain
-     * @returns {number} gain (in dB)
+     * @returns {number} Injector gain (dB) at the server.
-    */
+     */
     Q_INVOKABLE float getInjectorGain();
 
     /**jsdoc
-     * Sets the local injector gain in the client.
+     * Sets the volume (gain) that the environment is played at, for sounds from the client.
-     * Units are Decibels (dB)
      * @function Audio.setLocalInjectorGain
-     * @param {number} gain (in dB)
+     * @param {number} Local injector gain (dB) in the client.
-    */
+     */
     Q_INVOKABLE void setLocalInjectorGain(float gain);
 
     /**jsdoc
-     * Gets the local injector gain in the client.
+     * Gets the volume (gain) that the environment is played at, for sounds from the client.
      * @function Audio.getLocalInjectorGain
-     * @returns {number} gain (in dB)
+     * @returns {number} Local injector gain (dB) in the client.
-    */
+     */
     Q_INVOKABLE float getLocalInjectorGain();
 
     /**jsdoc
-     * Sets the injector gain for system sounds.
+     * Sets the volume (gain) that system sounds are played at.
-     * Units are Decibels (dB)
      * @function Audio.setSystemInjectorGain
-     * @param {number} gain (in dB)
+     * @param {number} System injector gain (dB) in the client.
-    */
+     */
     Q_INVOKABLE void setSystemInjectorGain(float gain);
 
     /**jsdoc
-     * Gets the injector gain for system sounds.
+     * Gets the volume (gain) that system sounds are played at.
      * @function Audio.getSystemInjectorGain
-     * @returns {number} gain (in dB)
+     * @returns {number} System injector gain (dB) in the client.
     */
     Q_INVOKABLE float getSystemInjectorGain();
 
@@ -252,13 +264,13 @@ public:
     Q_INVOKABLE bool startRecording(const QString& filename);
 
     /**jsdoc
-     * Finish making an audio recording started with {@link Audio.startRecording|startRecording}.
+     * Finishes making an audio recording started with {@link Audio.startRecording|startRecording}.
      * @function Audio.stopRecording
      */
     Q_INVOKABLE void stopRecording();
 
     /**jsdoc
-     * Check whether an audio recording is currently being made.
+     * Checks whether an audio recording is currently being made.
      * @function Audio.getRecording
      * @returns {boolean} <code>true</code> if an audio recording is currently being made, otherwise <code>false</code>.
      */
@@ -274,9 +286,10 @@ signals:
     void nop();
 
     /**jsdoc
-     * Triggered when the audio input is muted or unmuted.
+     * Triggered when the audio input is muted or unmuted for the current context (desktop or HMD).
      * @function Audio.mutedChanged
-     * @param {boolean} isMuted - <code>true</code> if the audio input is muted, otherwise <code>false</code>.
+     * @param {boolean} isMuted - <code>true</code> if the audio input is muted for the current context (desktop or HMD), 
+     *     otherwise <code>false</code>.
      * @returns {Signal}
      * @example <caption>Report when audio input is muted or unmuted</caption>
      * Audio.mutedChanged.connect(function (isMuted) {
@@ -286,47 +299,47 @@ signals:
     void mutedChanged(bool isMuted);
 
     /**jsdoc
-    * Triggered when desktop audio input is muted or unmuted.
+     * Triggered when desktop audio input is muted or unmuted.
-    * @function Audio.desktopMutedChanged
+     * @function Audio.desktopMutedChanged
-    * @param {boolean} isMuted - <code>true</code> if the audio input is muted for desktop mode, otherwise <code>false</code>.
+     * @param {boolean} isMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void desktopMutedChanged(bool isMuted);
 
     /**jsdoc
-    * Triggered when HMD audio input is muted or unmuted.
+     * Triggered when HMD audio input is muted or unmuted.
-    * @function Audio.hmdMutedChanged
+     * @function Audio.hmdMutedChanged
-    * @param {boolean} isMuted - <code>true</code> if the audio input is muted for HMD mode, otherwise <code>false</code>.
+     * @param {boolean} isMuted - <code>true</code> if HMD audio input is muted, otherwise <code>false</code>.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void hmdMutedChanged(bool isMuted);
 
-    /**
+    /**jsdoc
-    * Triggered when Push-to-Talk has been enabled or disabled.
+     * Triggered when push-to-talk is enabled or disabled for the current context (desktop or HMD).
-    * @function Audio.pushToTalkChanged
+     * @function Audio.pushToTalkChanged
-    * @param {boolean} enabled - <code>true</code> if Push-to-Talk is enabled, otherwise <code>false</code>.
+     * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled, otherwise <code>false</code>.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void pushToTalkChanged(bool enabled);
 
-    /**
+    /**jsdoc
-    * Triggered when Push-to-Talk has been enabled or disabled for desktop mode.
+     * Triggered when push-to-talk is enabled or disabled for desktop mode.
-    * @function Audio.pushToTalkDesktopChanged
+     * @function Audio.pushToTalkDesktopChanged
-    * @param {boolean} enabled - <code>true</code> if Push-to-Talk is emabled for Desktop mode, otherwise <code>false</code>.
+     * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for desktop mode, otherwise <code>false</code>.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void pushToTalkDesktopChanged(bool enabled);
 
-    /**
+    /**jsdoc
-    * Triggered when Push-to-Talk has been enabled or disabled for HMD mode.
+     * Triggered when push-to-talk is enabled or disabled for HMD mode.
-    * @function Audio.pushToTalkHMDChanged
+     * @function Audio.pushToTalkHMDChanged
-    * @param {boolean} enabled - <code>true</code> if Push-to-Talk is emabled for HMD mode, otherwise <code>false</code>.
+     * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for HMD mode, otherwise <code>false</code>.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void pushToTalkHMDChanged(bool enabled);
 
     /**jsdoc
-     * Triggered when the audio input noise reduction is enabled or disabled.
+     * Triggered when audio input noise reduction is enabled or disabled.
      * @function Audio.noiseReductionChanged
      * @param {boolean} isEnabled - <code>true</code> if audio input noise reduction is enabled, otherwise <code>false</code>.
      * @returns {Signal}
@@ -378,11 +391,11 @@ signals:
     void contextChanged(const QString& context);
 
     /**jsdoc
-    * Triggered when pushing to talk.
+     * Triggered when push-to-talk changes.
-    * @function Audio.pushingToTalkChanged
+     * @function Audio.pushingToTalkChanged
-    * @param {boolean} talking - <code>true</code> if broadcasting with PTT, <code>false</code> otherwise.
+     * @param {boolean} talking - <code>true</code> if started pushing to talk, <code>false</code> if stopped pushing to talk.
-    * @returns {Signal}
+     * @returns {Signal}
-    */
+     */
     void pushingToTalkChanged(bool talking);
 
 public slots:

libraries/script-engine/src/AudioScriptingInterface.h

@@ -41,25 +41,27 @@ public:
     }
 
     /**jsdoc
-     * Add nodes to the audio solo list
+     * Adds avatar to the audio solo list. If the audio solo list is non-empty, only audio from the avatars in the list is 
+     * played.
      * @function Audio.addToSoloList
-     * @param {Uuid[]} uuidList - List of node UUIDs to add to the solo list.
+     * @param {Uuid[]} ids - Avatar IDs to add to the solo list.
      */
     Q_INVOKABLE void addToSoloList(QVector<QUuid> uuidList) {
         _localAudioInterface->getAudioSolo().addUUIDs(uuidList);
     }
 
     /**jsdoc
-     * Remove nodes from the audio solo list
+     * Removes avatars from the audio solo list. If the audio solo list is non-empty, only audio from the avatars in the list 
+     * is played.
      * @function Audio.removeFromSoloList
-     * @param {Uuid[]} uuidList - List of node UUIDs to remove from the solo list.
+     * @param {Uuid[]} ids - Avatar IDs to remove from the solo list.
      */
     Q_INVOKABLE void removeFromSoloList(QVector<QUuid> uuidList) {
         _localAudioInterface->getAudioSolo().removeUUIDs(uuidList);
     }
 
     /**jsdoc
-     * Reset the list of soloed nodes.
+     * Clears the audio solo list.
      * @function Audio.resetSoloList
      */
     Q_INVOKABLE void resetSoloList() {
@@ -67,33 +69,51 @@ public:
     }
 
     /**jsdoc
+     * Gets whether echoing microphone audio back to your from the server is enabled. When enabled, microphone audio is echoed 
+     * only if you're unmuted or are pushing-to-talk.
      * @function Audio.getServerEcho
+     * @returns {boolean} <code>true</code> if echoing microphone audio back to you from the server is enabled, 
+     *     <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool getServerEcho();
 
     /**jsdoc
+     * Sets whether echoiing microphone audio back to your from the server is enabled. When enabled, microphone audio is echoed 
+     * only if you're unmuted or are pushing-to-talk.
      * @function Audio.setServerEcho
-     * @parm {boolean} serverEcho
+     * @parm {boolean} serverEcho - <code>true</code> to enable echoing microphone back to you from the server, 
+     *     <code>false<code> to disable.
      */
     Q_INVOKABLE void setServerEcho(bool serverEcho);
 
     /**jsdoc
+     * Toggles the echoing of microphone audio back to you from the server. When enabled, microphone audio is echoed only if 
+     * you're unmuted or are pushing-to-talk.
      * @function Audio.toggleServerEcho
      */
     Q_INVOKABLE void toggleServerEcho();
 
     /**jsdoc
+     * Gets whether echoing microphone audio back to your by the client is enabled. When enabled, microphone audio is even if 
+     * you're muted or not pushing-to-talk.
      * @function Audio.getLocalEcho
+     * @returns {boolean} <code>true</code> if echoing microphone audio back to you from the client is enabled, 
+     *     <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool getLocalEcho();
 
     /**jsdoc
+     * Sets whether echoing microphone audio back to your by the client is enabled. When enabled, microphone audio is even if
+     * you're muted or not pushing-to-talk.
      * @function Audio.setLocalEcho
-     * @parm {boolean} localEcho
+     * @parm {boolean} localEcho - <code>true</code> to enable echoing microphone audio back to you from the client, 
+     *     <code>false</code> to disable.
      */
     Q_INVOKABLE void setLocalEcho(bool localEcho);
 
     /**jsdoc
+     * Toggles the echoing of microphone audio back to you from the client. When enabled, microphone audio is echoed even if 
+     * you're muted or not pushing-to-talk.
      * @function Audio.toggleLocalEcho
      */
     Q_INVOKABLE void toggleLocalEcho();
@@ -129,7 +149,7 @@ protected:
     Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions());
 
     /**jsdoc
-     * Start playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling 
+     * Starts playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling 
      * {@link Audio.playSound} with {@link AudioInjector.AudioInjectorOptions} <code>localOnly</code> set <code>true</code> and 
      * the specified <code>position</code>.
      * @function Audio.playSystemSound
@@ -140,15 +160,15 @@ protected:
     Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound);
 
     /**jsdoc
-     * Set whether or not the audio input should be used in stereo. If the audio input does not support stereo then setting a 
+     * Sets whether the audio input should be used in stereo. If the audio input doesn't support stereo then setting a value 
-     * value of <code>true</code> has no effect.
+     * of <code>true</code> has no effect.
      * @function Audio.setStereoInput
      * @param {boolean} stereo - <code>true</code> if the audio input should be used in stereo, otherwise <code>false</code>.
      */
     Q_INVOKABLE void setStereoInput(bool stereo);
 
     /**jsdoc
-     * Get whether or not the audio input is used in stereo.
+     * Gets whether the audio input is used in stereo.
      * @function Audio.isStereoInput
      * @returns {boolean} <code>true</code> if the audio input is used in stereo, otherwise <code>false</code>. 
      */

libraries/script-engine/src/ScriptAudioInjector.h

@@ -17,7 +17,9 @@
 #include <AudioInjectorManager.h>
 
 /**jsdoc
- * Plays &mdash; "injects" &mdash; the content of an audio file. Used in the {@link Audio} API.
+ * Plays &mdash; "injects" &mdash; the content of an audio file.
+ *
+ * <p>Create using {@link Audio} API methods.</p>
  *
  * @class AudioInjector
  *
@@ -45,13 +47,13 @@ public:
 public slots:
 
     /**jsdoc
-     * Stop current playback, if any, and start playing from the beginning.
+     * Stops current playback, if any, and start playing from the beginning.
      * @function AudioInjector.restart
      */
     void restart() { DependencyManager::get<AudioInjectorManager>()->restart(_injector); }
 
     /**jsdoc
-     * Stop audio playback.
+     * Stops audio playback.
      * @function AudioInjector.stop
      * @example <caption>Stop playing a sound before it finishes.</caption>
      * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
@@ -71,28 +73,28 @@ public slots:
     void stop() { DependencyManager::get<AudioInjectorManager>()->stop(_injector); }
 
     /**jsdoc
-     * Get the current configuration of the audio injector.
+     * Gets the current configuration of the audio injector.
      * @function AudioInjector.getOptions
      * @returns {AudioInjector.AudioInjectorOptions} Configuration of how the injector plays the audio.
      */
     AudioInjectorOptions getOptions() const { return DependencyManager::get<AudioInjectorManager>()->getOptions(_injector); }
 
     /**jsdoc
-     * Configure how the injector plays the audio.
+     * Configures how the injector plays the audio.
      * @function AudioInjector.setOptions
      * @param {AudioInjector.AudioInjectorOptions} options - Configuration of how the injector plays the audio.
      */
     void setOptions(const AudioInjectorOptions& options) { DependencyManager::get<AudioInjectorManager>()->setOptions(_injector, options); }
 
     /**jsdoc
-     * Get the loudness of the most recent frame of audio played.
+     * Gets the loudness of the most recent frame of audio played.
      * @function AudioInjector.getLoudness
      * @returns {number} The loudness of the most recent frame of audio played, range <code>0.0</code> &ndash; <code>1.0</code>.
      */
     float getLoudness() const { return DependencyManager::get<AudioInjectorManager>()->getLoudness(_injector); }
 
     /**jsdoc
-     * Get whether or not the audio is currently playing.
+     * Gets whether or not the audio is currently playing.
      * @function AudioInjector.isPlaying
      * @returns {boolean} <code>true</code> if the audio is currently playing, otherwise <code>false</code>.
      * @example <caption>See if a sound is playing.</caption>