diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h index b66c228bf2..825393408e 100644 --- a/interface/src/scripting/Audio.h +++ b/interface/src/scripting/Audio.h @@ -45,12 +45,12 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { * @property {boolean} mutedDesktop - true if desktop audio input is muted, otherwise false. * @property {boolean} mutedHMD - 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. + * When enabled, if you speak while your microphone is muted, "muted" is displayed on the screen as a warning. * @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} 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 + * @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 {number} inputLevel - The loudness of the audio input, range 0.0 (no sound) – * 1.0 (the onset of clipping). Read-only. @@ -64,7 +64,7 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { * @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 + * @property {boolean} pushingToTalk - true if the user is currently pushing-to-talk, otherwise * false. * * @comment The following properties are from AudioScriptingInterface.h. @@ -147,8 +147,8 @@ public: Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD); /**jsdoc - * 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 + * 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 configured on the server or settings scripted by * {@link Audio.setReverbOptions|setReverbOptions}. * @function Audio.setReverb * @param {boolean} enable - true to enable reverberation, false to disable. @@ -207,44 +207,44 @@ public: Q_INVOKABLE float getAvatarGain(); /**jsdoc - * Sets the gain (relative volume) that the environment is played at, for sounds from the server. + * Sets the gain (relative volume) that environment sounds from the server are played at. * @function Audio.setInjectorGain * @param {number} Injector gain (dB) at the server. */ Q_INVOKABLE void setInjectorGain(float gain); /**jsdoc - * Gets the gain (relative volume) that the environment is played at, for sounds from the server. + * Gets the gain (relative volume) that environment sounds from the server are played at. * @function Audio.getInjectorGain * @returns {number} Injector gain (dB) at the server. */ Q_INVOKABLE float getInjectorGain(); /**jsdoc - * Sets the gain (relative volume) that the environment is played at, for sounds from the client. + * Sets the gain (relative volume) that environment sounds from the client are played at. * @function Audio.setLocalInjectorGain - * @param {number} Local injector gain (dB) in the client. + * @param {number} Injector gain (dB) in the client. */ Q_INVOKABLE void setLocalInjectorGain(float gain); /**jsdoc - * Gets the gain (relative volume) that the environment is played at, for sounds from the client. + * Gets the gain (relative volume) that environment sounds from the client are played at. * @function Audio.getLocalInjectorGain - * @returns {number} Local injector gain (dB) in the client. + * @returns {number} Injector gain (dB) in the client. */ Q_INVOKABLE float getLocalInjectorGain(); /**jsdoc * Sets the gain (relative volume) that system sounds are played at. * @function Audio.setSystemInjectorGain - * @param {number} System injector gain (dB) in the client. + * @param {number} Injector gain (dB) in the client. */ Q_INVOKABLE void setSystemInjectorGain(float gain); /**jsdoc * Gets the gain (relative volume) that system sounds are played at. * @function Audio.getSystemInjectorGain - * @returns {number} System injector gain (dB) in the client. + * @returns {number} Injector gain (dB) in the client. */ Q_INVOKABLE float getSystemInjectorGain(); @@ -372,8 +372,8 @@ signals: * Triggered when the input audio volume changes. * @function Audio.inputVolumeChanged * @param {number} volume - The requested volume to be applied to the audio input, range 0.0 – - * 1.0. The resulting value of Audio.inputVolume depends on the capabilities of the device: - * for example, the volume can't be changed on some devices, and others might only support values of 0.0 + * 1.0. The resulting value of Audio.inputVolume depends on the capabilities of the device. + * For example, the volume can't be changed on some devices, while others might only support values of 0.0 * and 1.0. * @returns {Signal} */ @@ -405,9 +405,9 @@ signals: void contextChanged(const QString& context); /**jsdoc - * Triggered when pushing-to-talk changes. + * Triggered when the user starts or stops push-to-talk. * @function Audio.pushingToTalkChanged - * @param {boolean} talking - true if started pushing to talk, false if stopped pushing to talk. + * @param {boolean} talking - true if started push-to-talk, false if stopped push-to-talk. * @returns {Signal} */ void pushingToTalkChanged(bool talking); diff --git a/libraries/audio/src/AudioInjectorOptions.cpp b/libraries/audio/src/AudioInjectorOptions.cpp index 0946841fc6..ee6b960e9f 100644 --- a/libraries/audio/src/AudioInjectorOptions.cpp +++ b/libraries/audio/src/AudioInjectorOptions.cpp @@ -48,18 +48,20 @@ QScriptValue injectorOptionsToScriptValue(QScriptEngine* engine, const AudioInje } /**jsdoc - * Configures how an audio injector plays its audio. + * Configures where and how an audio injector plays its audio. * @typedef {object} AudioInjector.AudioInjectorOptions * @property {Vec3} position=Vec3.ZERO - The position in the domain to play the sound. * @property {Quat} orientation=Quat.IDENTITY - The orientation in the domain to play the sound in. * @property {number} volume=1.0 - Playback volume, between 0.0 and 1.0. * @property {number} pitch=1.0 - Alter the pitch of the sound, within +/- 2 octaves. The value is the relative sample rate to - * resample the sound at, range 0.0625 – 16.0. A value of 0.0625 lowers the - * pitch by 2 octaves; 1.0 is no change in pitch; 16.0 raises the pitch by 2 octaves. + * resample the sound at, range 0.0625 – 16.0.
+ * A value of 0.0625 lowers the pitch by 2 octaves.
+ * A value of 1.0 means there is no change in pitch.
+ * A value of 16.0 raises the pitch by 2 octaves. * @property {boolean} loop=false - If true, the sound is played repeatedly until playback is stopped. * @property {number} secondOffset=0 - Starts playback from a specified time (seconds) within the sound file, ≥ * 0. - * @property {boolean} localOnly=false - IF true, the sound is played back locally on the client rather than to + * @property {boolean} localOnly=false - If true, the sound is played back locally on the client rather than to * others via the audio mixer. * @property {boolean} ignorePenumbra=false - Deprecated: This property is deprecated and will be * removed. diff --git a/libraries/audio/src/Sound.h b/libraries/audio/src/Sound.h index f5f47add32..a5a48b836c 100644 --- a/libraries/audio/src/Sound.h +++ b/libraries/audio/src/Sound.h @@ -124,7 +124,7 @@ typedef QSharedPointer SharedSoundPointer; * An audio resource, created by {@link SoundCache.getSound}, to be played back using {@link Audio.playSound}. *

Supported formats:

* diff --git a/libraries/script-engine/src/AudioScriptingInterface.h b/libraries/script-engine/src/AudioScriptingInterface.h index a98666681a..34958181a9 100644 --- a/libraries/script-engine/src/AudioScriptingInterface.h +++ b/libraries/script-engine/src/AudioScriptingInterface.h @@ -41,7 +41,7 @@ public: } /**jsdoc - * Adds avatars to the audio solo list. If the audio solo list is non-empty, only audio from the avatars in the list is + * Adds avatars to the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list is * played. * @function Audio.addToSoloList * @param {Uuid[]} ids - Avatar IDs to add to the solo list. @@ -78,7 +78,7 @@ public: } /**jsdoc - * Removes avatars from the audio solo list. If the audio solo list is non-empty, only audio from the avatars in the list + * Removes avatars from the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list * is played. * @function Audio.removeFromSoloList * @param {Uuid[]} ids - Avatar IDs to remove from the solo list. @@ -96,8 +96,8 @@ public: } /**jsdoc - * Gets whether echoing microphone audio back to you from the server is enabled. When enabled, microphone audio is echoed - * only if you're unmuted or are pushing-to-talk. + * Gets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed only + * if you're unmuted or are using push-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. @@ -105,8 +105,8 @@ public: Q_INVOKABLE bool getServerEcho(); /**jsdoc - * Sets whether echoing microphone audio back to you from the server is enabled. When enabled, microphone audio is echoed - * only if you're unmuted or are pushing-to-talk. + * Sets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed + * only if you're unmuted or are using push-to-talk. * @function Audio.setServerEcho * @parm {boolean} serverEcho - true to enable echoing microphone back to you from the server, * false to disable. @@ -115,14 +115,14 @@ public: /**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. + * you're unmuted or are using push-to-talk. * @function Audio.toggleServerEcho */ Q_INVOKABLE void toggleServerEcho(); /**jsdoc - * Gets whether echoing microphone audio back to you by the client is enabled. When enabled, microphone audio is echoed - * even if you're muted or not pushing-to-talk. + * Gets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed + * even if you're muted or not using push-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. @@ -130,8 +130,8 @@ public: Q_INVOKABLE bool getLocalEcho(); /**jsdoc - * Sets whether echoing microphone audio back to you by the client is enabled. When enabled, microphone audio is echoed - * even if you're muted or not pushing-to-talk. + * Sets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed + * even if you're muted or not using push-to-talk. * @function Audio.setLocalEcho * @parm {boolean} localEcho - true to enable echoing microphone audio back to you from the client, * false to disable. @@ -144,8 +144,8 @@ public: 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. + * Toggles the echoing of microphone audio back to you by the client. When enabled, microphone audio is echoed even if + * you're muted or not using push-to-talk. * @function Audio.toggleLocalEcho */ Q_INVOKABLE void toggleLocalEcho(); @@ -157,7 +157,7 @@ protected: // these methods are protected to stop C++ callers from calling, but invokable from script /**jsdoc - * Starts playing — "injecting" — the content of an audio file. The sound is played globally (sent to the audio + * Starts playing or "injecting" the content of an audio file. The sound is played globally (sent to the audio * mixer) so that everyone hears it, unless the injectorOptions has localOnly set to * true in which case only the client hears the sound played. No sound is played if sent to the audio mixer * but the client is not connected to an audio mixer. The {@link AudioInjector} object returned by the function can be used @@ -165,7 +165,8 @@ protected: * @function Audio.playSound * @param {SoundObject} sound - The content of an audio file, loaded using {@link SoundCache.getSound}. See * {@link SoundObject} for supported formats. - * @param {AudioInjector.AudioInjectorOptions} [injectorOptions={}] - Audio injector configuration. + * @param {AudioInjector.AudioInjectorOptions} [injectorOptions={}] - Configures where and how the audio injector plays the + * audio file. * @returns {AudioInjector} The audio injector that plays the audio file. * @example Play a sound. * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); @@ -181,11 +182,11 @@ protected: Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions()); /**jsdoc - * Starts 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 - * @param {SoundObject} sound - The content of an audio file, loaded using {@link SoundCache.getSound}. See + * @param {SoundObject} sound - The content of an audio file, which is loaded using {@link SoundCache.getSound}. See * {@link SoundObject} for supported formats. * @returns {AudioInjector} The audio injector that plays the audio file. */ @@ -210,7 +211,7 @@ signals: /**jsdoc * Triggered when the client is muted by the mixer because their loudness value for the noise background has reached the - * threshold set for the domain in the server settings. + * threshold set for the domain (in the server settings). * @function Audio.mutedByMixer * @returns {Signal} */ @@ -239,7 +240,7 @@ signals: void disconnected(); /**jsdoc - * Triggered when the noise gate is opened: the input audio signal is no longer blocked (fully attenuated) because it has + * Triggered when the noise gate is opened. The input audio signal is no longer blocked (fully attenuated) because it has * risen above an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is * true. * @function Audio.noiseGateOpened @@ -248,7 +249,7 @@ signals: void noiseGateOpened(); /**jsdoc - * Triggered when the noise gate is closed: the input audio signal is blocked (fully attenuated) because it has fallen + * Triggered when the noise gate is closed. The input audio signal is blocked (fully attenuated) because it has fallen * below an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is * true. * @function Audio.noiseGateClosed diff --git a/libraries/script-engine/src/ScriptAudioInjector.h b/libraries/script-engine/src/ScriptAudioInjector.h index a67c15bace..3023623d72 100644 --- a/libraries/script-engine/src/ScriptAudioInjector.h +++ b/libraries/script-engine/src/ScriptAudioInjector.h @@ -17,7 +17,7 @@ #include /**jsdoc - * Plays — "injects" — the content of an audio file. + * Plays or "injects" the content of an audio file. * *

Create using {@link Audio} API methods.

* @@ -47,7 +47,7 @@ public: public slots: /**jsdoc - * Stops current playback, if any, and start playing from the beginning. + * Stops current playback, if any, and starts playing from the beginning. * @function AudioInjector.restart */ void restart() { DependencyManager::get()->restart(_injector); }