diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h index f7116ced3a..ed54dca5c6 100644 --- a/interface/src/scripting/Audio.h +++ b/interface/src/scripting/Audio.h @@ -40,25 +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} mutedDesktop - 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} 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, 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 + * 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. * @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 {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 {object} devices - Read-only. + *

Deprecated: This property is deprecated and will be removed. + * @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 currently 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) @@ -117,23 +132,23 @@ public: /**jsdoc * @function Audio.setInputDevice - * @param {object} device - * @param {boolean} isHMD + * @param {object} device - Device. + * @param {boolean} isHMD - Is HMD. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setInputDevice(const QAudioDeviceInfo& device, bool isHMD); /**jsdoc * @function Audio.setOutputDevice - * @param {object} device - * @param {boolean} isHMD + * @param {object} device - Device. + * @param {boolean} isHMD - Is HMD. * @deprecated This function is deprecated and will be removed. */ 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 - * 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. @@ -165,69 +180,71 @@ 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 gain (relative volume) that avatars' voices are played at. This gain is used at the server. * @function Audio.setAvatarGain - * @param {number} gain (in dB) - */ + * @param {number} gain - Avatar gain (dB) at the server. + */ Q_INVOKABLE void setAvatarGain(float gain); /**jsdoc - * Gets the avatar gain at the server. + * Gets the gain (relative volume) that avatars' 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. + * @example Report current audio gain settings. + * // 0 value = normal volume; -ve value = quieter; +ve value = louder. + * print("Avatar gain: " + Audio.getAvatarGain()); + * print("Environment server gain: " + Audio.getInjectorGain()); + * print("Environment local gain: " + Audio.getLocalInjectorGain()); + * print("System gain: " + Audio.getSystemInjectorGain()); + */ Q_INVOKABLE float getAvatarGain(); /**jsdoc - * Sets the injector gain at the server. - * Units are Decibels (dB) + * Sets the gain (relative volume) that environment sounds from the server are played at. * @function Audio.setInjectorGain - * @param {number} gain (in dB) - */ + * @param {number} gain - Injector gain (dB) at the server. + */ Q_INVOKABLE void setInjectorGain(float gain); /**jsdoc - * Gets the injector gain at the server. + * Gets the gain (relative volume) that environment sounds from the server are played at. * @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 gain (relative volume) that environment sounds from the client are played at. * @function Audio.setLocalInjectorGain - * @param {number} gain (in dB) - */ + * @param {number} gain - Injector gain (dB) in the client. + */ Q_INVOKABLE void setLocalInjectorGain(float gain); /**jsdoc - * Gets the local injector gain in the client. + * Gets the gain (relative volume) that environment sounds from the client are played at. * @function Audio.getLocalInjectorGain - * @returns {number} gain (in dB) - */ + * @returns {number} Injector gain (dB) in the client. + */ Q_INVOKABLE float getLocalInjectorGain(); /**jsdoc - * Sets the injector gain for system sounds. - * Units are Decibels (dB) + * Sets the gain (relative volume) that system sounds are played at. * @function Audio.setSystemInjectorGain - * @param {number} gain (in dB) - */ + * @param {number} gain - Injector gain (dB) in the client. + */ Q_INVOKABLE void setSystemInjectorGain(float gain); /**jsdoc - * Gets the injector gain for system sounds. + * Gets the gain (relative volume) that system sounds are played at. * @function Audio.getSystemInjectorGain - * @returns {number} gain (in dB) + * @returns {number} Injector gain (dB) in the client. */ Q_INVOKABLE float getSystemInjectorGain(); @@ -253,13 +270,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. */ @@ -275,9 +292,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) { @@ -287,47 +305,55 @@ signals: void mutedChanged(bool isMuted); /**jsdoc - * Triggered when desktop audio input is muted or unmuted. - * @function Audio.mutedDesktopChanged - * @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.mutedDesektopChanged + * @param {boolean} isMuted - true if desktop audio input is muted, otherwise false. + * @returns {Signal} + * @example Report when desktop muting changes. + * Audio.mutedDesktopChanged.connect(function (isMuted) { + * print("Desktop muted: " + isMuted); + * }); + */ void mutedDesktopChanged(bool isMuted); /**jsdoc - * Triggered when HMD audio input is muted or unmuted. - * @function Audio.mutedHMDChanged - * @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.mutedHMDChanged + * @param {boolean} isMuted - true if HMD audio input is muted, otherwise false. + * @returns {Signal} + */ void mutedHMDChanged(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} + * @example Report when push-to-talk changes. + * Audio.pushToTalkChanged.connect(function (enabled) { + * print("Push to talk: " + (enabled ? "on" : "off")); + * }); + */ 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} @@ -346,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} */ @@ -379,11 +405,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 the user starts or stops push-to-talk. + * @function Audio.pushingToTalkChanged + * @param {boolean} talking - true if started push-to-talk, false if stopped push-to-talk. + * @returns {Signal} + */ void pushingToTalkChanged(bool talking); public slots: diff --git a/libraries/audio/src/AudioInjectorOptions.cpp b/libraries/audio/src/AudioInjectorOptions.cpp index 0946841fc6..cb7da4de33 100644 --- a/libraries/audio/src/AudioInjectorOptions.cpp +++ b/libraries/audio/src/AudioInjectorOptions.cpp @@ -48,21 +48,23 @@ 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. + * @property {boolean} ignorePenumbra=false -

Deprecated: This property is deprecated and will be + * removed.

*/ void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) { if (!object.isObject()) { diff --git a/libraries/audio/src/Sound.h b/libraries/audio/src/Sound.h index e5ba322599..62fdb9dcdc 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 c97ea10329..dea44d6a1d 100644 --- a/libraries/script-engine/src/AudioScriptingInterface.h +++ b/libraries/script-engine/src/AudioScriptingInterface.h @@ -41,25 +41,54 @@ public: } /**jsdoc - * Add nodes to the audio solo list + * 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[]} uuidList - List of node UUIDs to add to the solo list. + * @param {Uuid[]} ids - Avatar IDs to add to the solo list. + + * @example Listen to a single nearby avatar for a short while. + * // Find nearby avatars. + * var RANGE = 100; // m + * var nearbyAvatars = AvatarList.getAvatarsInRange(MyAvatar.position, RANGE); + * + * // Remove own avatar from list. + * var myAvatarIndex = nearbyAvatars.indexOf(MyAvatar.sessionUUID); + * if (myAvatarIndex !== -1) { + * nearbyAvatars.splice(myAvatarIndex, 1); + * } + * + * if (nearbyAvatars.length > 0) { + * // Listen to only one of the nearby avatars. + * var avatarName = AvatarList.getAvatar(nearbyAvatars[0]).displayName; + * print("Listening only to " + avatarName); + * Audio.addToSoloList([nearbyAvatars[0]]); + * + * // Stop listening to only the one avatar after a short while. + * Script.setTimeout(function () { + * print("Finished listening only to " + avatarName); + * Audio.resetSoloList(); + * }, 10000); // 10s + * + * } else { + * print("No nearby avatars"); + * } */ 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 not 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 +96,56 @@ public: } /**jsdoc + * 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. */ Q_INVOKABLE bool getServerEcho(); /**jsdoc + * 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 + * @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 using push-to-talk. * @function Audio.toggleServerEcho */ Q_INVOKABLE void toggleServerEcho(); /**jsdoc + * 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. */ Q_INVOKABLE bool getLocalEcho(); /**jsdoc + * 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 + * @parm {boolean} localEcho - true to enable echoing microphone audio back to you from the client, + * false to disable. + * @example Echo local audio for a few seconds. + * Audio.setLocalEcho(true); + * Script.setTimeout(function () { + * Audio.setLocalEcho(false); + * }, 3000); // 3s */ Q_INVOKABLE void setLocalEcho(bool localEcho); /**jsdoc + * 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(); @@ -105,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 @@ -113,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("http://hifi-content.s3.amazonaws.com/ken/samples/forest_ambiX.wav"); @@ -139,26 +192,26 @@ 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 - * @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. */ 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. */ @@ -168,7 +221,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} */ @@ -197,7 +250,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 @@ -206,7 +259,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 d77291b92c..3023623d72 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 or "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 starts 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.