From 5c8d89fb125de1bba2cb19562e230a2a4c694a0b Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 29 Mar 2019 18:53:30 +1300 Subject: [PATCH] Fill in and tidy Audio API JSDoc --- interface/src/scripting/Audio.h | 163 ++++++++++-------- .../src/AudioScriptingInterface.h | 42 +++-- .../script-engine/src/ScriptAudioInjector.h | 16 +- 3 files changed, 128 insertions(+), 93 deletions(-) diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h index d6823ea452..cd3f7b1725 100644 --- a/interface/src/scripting/Audio.h +++ b/interface/src/scripting/Audio.h @@ -40,24 +40,40 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { * @hifi-server-entity * @hifi-assignment-client * - * @property {boolean} muted - true if the audio input is muted, otherwise false. + * @property {boolean} muted - true if the audio input is muted for the current user context (desktop or HMD), + * otherwise false. + * @property {boolean} desktopMuted - true if desktop audio input is muted, otherwise false. + * @property {boolean} hmdMuted - true if the HMD input is muted, otherwise false. + * @property {boolean} warnWhenMuted - true if the "muted" warning is enabled, otherwise false. + * When enabled, a "muted" warning is displayed when you try to speak while your microphone is muted. * @property {boolean} noiseReduction - true if noise reduction is enabled, otherwise false. 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 0.0 (no sound) – - * 1.0 (the onset of clipping). Read-only. - * @property {boolean} clipping - true if the audio input is clipping, otherwise false. * @property {number} inputVolume - Adjusts the volume of the input audio; range 0.0 – 1.0. * 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 0.0 and 1.0. - * @property {boolean} isStereoInput - true if the input audio is being used in stereo, otherwise - * false. Some devices do not support stereo, in which case the value is always false. + * @property {number} inputLevel - The loudness of the audio input, range 0.0 (no sound) – + * 1.0 (the onset of clipping). Read-only. + * @property {boolean} clipping - true if the audio input is clipping, otherwise false. * @property {string} context - The current context of the audio: either "Desktop" or "HMD". * Read-only. * @property {object} devices Read-only. Deprecated: This property is deprecated and will be * removed. - * @property {boolean} isSoloing Read-only. true if any nodes are soloed. - * @property {Uuid[]} soloList Read-only. Get the list of currently soloed node UUIDs. + * @property {boolean} pushToTalk - true if push-to-talk is enabled for the current user context (desktop or + * HMD), otherwise false. + * @property {boolean} pushToTalkDesktop - true if desktop push-to-talk is enabled, otherwise + * false. + * @property {boolean} pushToTalkHMD - true if HMD push-to-talk is enabled, otherwise false. + * @property {boolean} pushingToTalk - true if the user is currently pushing to talk, otherwise + * false. + * + * @comment The following properties are from AudioScriptingInterface.h. + * @property {boolean} isStereoInput - true if the input audio is being used in stereo, otherwise + * false. Some devices do not support stereo, in which case the value is always false. + * @property {boolean} isSoloing - true if audio soloing, i.e., playing audio from only specific avatars. + * Read-only. + * @property {Uuid[]} soloList - The list of currently soloed avatar IDs. Empty list if not currently audio soloing. + * Read-only. */ 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 — configured on the server — 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. - * Units are Decibels (dB) + * Sets the volume (gain) that avatar's voices are played at. This gain is used at the server. * @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. - * Units are Decibels (dB) + * Sets the volume (gain) that the environment is played at, for sounds from the server. * @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. - * Units are Decibels (dB) + * Sets the volume (gain) that the environment is played at, for sounds from the client. * @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. - * Units are Decibels (dB) + * Sets the volume (gain) that system sounds are played at. * @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} true if an audio recording is currently being made, otherwise false. */ @@ -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 - true if the audio input is muted, otherwise false. + * @param {boolean} isMuted - true if the audio input is muted for the current context (desktop or HMD), + * otherwise false. * @returns {Signal} * @example Report when audio input is muted or unmuted * Audio.mutedChanged.connect(function (isMuted) { @@ -286,47 +299,47 @@ signals: void mutedChanged(bool isMuted); /**jsdoc - * Triggered when desktop audio input is muted or unmuted. - * @function Audio.desktopMutedChanged - * @param {boolean} isMuted - true if the audio input is muted for desktop mode, otherwise false. - * @returns {Signal} - */ + * Triggered when desktop audio input is muted or unmuted. + * @function Audio.desktopMutedChanged + * @param {boolean} isMuted - true if desktop audio input is muted, otherwise false. + * @returns {Signal} + */ void desktopMutedChanged(bool isMuted); /**jsdoc - * Triggered when HMD audio input is muted or unmuted. - * @function Audio.hmdMutedChanged - * @param {boolean} isMuted - true if the audio input is muted for HMD mode, otherwise false. - * @returns {Signal} - */ + * Triggered when HMD audio input is muted or unmuted. + * @function Audio.hmdMutedChanged + * @param {boolean} isMuted - true if HMD audio input is muted, otherwise false. + * @returns {Signal} + */ void hmdMutedChanged(bool isMuted); - /** - * Triggered when Push-to-Talk has been enabled or disabled. - * @function Audio.pushToTalkChanged - * @param {boolean} enabled - true if Push-to-Talk is enabled, otherwise false. - * @returns {Signal} - */ + /**jsdoc + * Triggered when push-to-talk is enabled or disabled for the current context (desktop or HMD). + * @function Audio.pushToTalkChanged + * @param {boolean} enabled - true if push-to-talk is enabled, otherwise false. + * @returns {Signal} + */ void pushToTalkChanged(bool enabled); - /** - * Triggered when Push-to-Talk has been enabled or disabled for desktop mode. - * @function Audio.pushToTalkDesktopChanged - * @param {boolean} enabled - true if Push-to-Talk is emabled for Desktop mode, otherwise false. - * @returns {Signal} - */ + /**jsdoc + * Triggered when push-to-talk is enabled or disabled for desktop mode. + * @function Audio.pushToTalkDesktopChanged + * @param {boolean} enabled - true if push-to-talk is enabled for desktop mode, otherwise false. + * @returns {Signal} + */ void pushToTalkDesktopChanged(bool enabled); - /** - * Triggered when Push-to-Talk has been enabled or disabled for HMD mode. - * @function Audio.pushToTalkHMDChanged - * @param {boolean} enabled - true if Push-to-Talk is emabled for HMD mode, otherwise false. - * @returns {Signal} - */ + /**jsdoc + * Triggered when push-to-talk is enabled or disabled for HMD mode. + * @function Audio.pushToTalkHMDChanged + * @param {boolean} enabled - true if push-to-talk is enabled for HMD mode, otherwise false. + * @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 - true if audio input noise reduction is enabled, otherwise false. * @returns {Signal} @@ -378,11 +391,11 @@ signals: void contextChanged(const QString& context); /**jsdoc - * Triggered when pushing to talk. - * @function Audio.pushingToTalkChanged - * @param {boolean} talking - true if broadcasting with PTT, false otherwise. - * @returns {Signal} - */ + * Triggered when push-to-talk changes. + * @function Audio.pushingToTalkChanged + * @param {boolean} talking - true if started pushing to talk, false if stopped pushing to talk. + * @returns {Signal} + */ void pushingToTalkChanged(bool talking); public slots: diff --git a/libraries/script-engine/src/AudioScriptingInterface.h b/libraries/script-engine/src/AudioScriptingInterface.h index a6801dcdcb..4b19b719e2 100644 --- a/libraries/script-engine/src/AudioScriptingInterface.h +++ b/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 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 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} true if echoing microphone audio back to you from the server is enabled, + * false 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 - true to enable echoing microphone back to you from the server, + * false 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} true if echoing microphone audio back to you from the client is enabled, + * false 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 - true to enable echoing microphone audio back to you from the client, + * false 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} localOnly set true and * the specified position. * @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 - * value of true has no effect. + * Sets whether the audio input should be used in stereo. If the audio input doesn't support stereo then setting a value + * of true has no effect. * @function Audio.setStereoInput * @param {boolean} stereo - true if the audio input should be used in stereo, otherwise false. */ 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} true if the audio input is used in stereo, otherwise false. */ diff --git a/libraries/script-engine/src/ScriptAudioInjector.h b/libraries/script-engine/src/ScriptAudioInjector.h index d77291b92c..a67c15bace 100644 --- a/libraries/script-engine/src/ScriptAudioInjector.h +++ b/libraries/script-engine/src/ScriptAudioInjector.h @@ -17,7 +17,9 @@ #include /**jsdoc - * Plays — "injects" — the content of an audio file. Used in the {@link Audio} API. + * Plays — "injects" — the content of an audio file. + * + *

Create using {@link Audio} API methods.

* * @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()->restart(_injector); } /**jsdoc - * Stop audio playback. + * Stops audio playback. * @function AudioInjector.stop * @example Stop playing a sound before it finishes. * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); @@ -71,28 +73,28 @@ public slots: void stop() { DependencyManager::get()->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()->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()->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 0.0 – 1.0. */ float getLoudness() const { return DependencyManager::get()->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} true if the audio is currently playing, otherwise false. * @example See if a sound is playing.