Mirrors/overte-thingvellir
3
0
Fork 0
mirror of https://thingvellir.net/git/overte synced 2025-03-27 23:52:03 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #15321 from ctrlaltdavid/M21956

Browse source 
Case 21956: Audio JSDoc
This commit is contained in:
jennaingersoll 2019-04-25 17:03:58 -07:00 committed by GitHub
commit 24196e2776
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 199 additions and 116 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

196
interface/src/scripting/Audio.h
View file

@ -40,25 +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} mutedDesktop - <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} mutedDesktop - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
* @property {boolean} mutedHMD - <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, if you speak while your microphone is muted, "muted" is displayed on the screen as a warning.
* @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} 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 {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
* <code>false</code>. Some devices do not support stereo, in which case the value is always <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 {Uuid[]} soloList <em>Read-only.</em> Get the list of currently soloed node UUIDs.
* @property {object} devices - <em>Read-only.</em>
* <p class="important">Deprecated: This property is deprecated and will be removed.
* @property {boolean} pushToTalk - <code>true</code> if push-to-talk is enabled for the current user context (desktop or
* 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 currently 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)
@ -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 &mdash; configured on the server &mdash; 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 - <code>true</code> to enable reverberation, <code>false</code> 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 <caption>Report current audio gain settings.</caption>
* // 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} <code>true</code> if an audio recording is currently being made, otherwise <code>false</code>.
*/
@ -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 - <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) {
@ -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 - <code>true</code> if the audio input is muted for desktop mode, otherwise <code>false</code>.
* @returns {Signal}
*/
* Triggered when desktop audio input is muted or unmuted.
* @function Audio.mutedDesektopChanged
* @param {boolean} isMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
* @returns {Signal}
* @example <caption>Report when desktop muting changes.</caption>
* 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 - <code>true</code> if the audio input is muted for HMD mode, otherwise <code>false</code>.
* @returns {Signal}
*/
* Triggered when HMD audio input is muted or unmuted.
* @function Audio.mutedHMDChanged
* @param {boolean} isMuted - <code>true</code> if HMD audio input is muted, otherwise <code>false</code>.
* @returns {Signal}
*/
void mutedHMDChanged(bool isMuted);
/**
* Triggered when Push-to-Talk has been enabled or disabled.
* @function Audio.pushToTalkChanged
* @param {boolean} enabled - <code>true</code> if Push-to-Talk is enabled, otherwise <code>false</code>.
* @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 - <code>true</code> if push-to-talk is enabled, otherwise <code>false</code>.
* @returns {Signal}
* @example <caption>Report when push-to-talk changes.</caption>
* 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 - <code>true</code> if Push-to-Talk is emabled for Desktop mode, otherwise <code>false</code>.
* @returns {Signal}
*/
/**jsdoc
* Triggered when push-to-talk is enabled or disabled for desktop mode.
* @function Audio.pushToTalkDesktopChanged
* @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for desktop mode, otherwise <code>false</code>.
* @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 - <code>true</code> if Push-to-Talk is emabled for HMD mode, otherwise <code>false</code>.
* @returns {Signal}
*/
/**jsdoc
* Triggered when push-to-talk is enabled or disabled for HMD mode.
* @function Audio.pushToTalkHMDChanged
* @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for HMD mode, otherwise <code>false</code>.
* @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}
@ -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 <code>0.0</code> &ndash;
* <code>1.0</code>. The resulting value of <code>Audio.inputVolume</code> 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 <code>0.0</code>
* <code>1.0</code>. The resulting value of <code>Audio.inputVolume</code> 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 <code>0.0</code>
* and <code>1.0</code>.
* @returns {Signal}
*/
@ -379,11 +405,11 @@ signals:
void contextChanged(const QString& context);
/**jsdoc
* Triggered when pushing to talk.
* @function Audio.pushingToTalkChanged
* @param {boolean} talking - <code>true</code> if broadcasting with PTT, <code>false</code> otherwise.
* @returns {Signal}
*/
* Triggered when the user starts or stops push-to-talk.
* @function Audio.pushingToTalkChanged
* @param {boolean} talking - <code>true</code> if started push-to-talk, <code>false</code> if stopped push-to-talk.
* @returns {Signal}
*/
void pushingToTalkChanged(bool talking);
public slots:

14
libraries/audio/src/AudioInjectorOptions.cpp
View file

@ -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 <code>0.0</code> and <code>1.0</code>.
* @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 <code>0.0625</code> &ndash; <code>16.0</code>. A value of <code>0.0625</code> lowers the
* pitch by 2 octaves; <code>1.0</code> is no change in pitch; <code>16.0</code> raises the pitch by 2 octaves.
* resample the sound at, range <code>0.0625</code> &ndash; <code>16.0</code>.<br />
* A value of <code>0.0625</code> lowers the pitch by 2 octaves.<br />
* A value of <code>1.0</code> means there is no change in pitch.<br />
* A value of <code>16.0</code> raises the pitch by 2 octaves.
* @property {boolean} loop=false - If <code>true</code>, the sound is played repeatedly until playback is stopped.
* @property {number} secondOffset=0 - Starts playback from a specified time (seconds) within the sound file, &ge;
* <code>0</code>.
* @property {boolean} localOnly=false - IF <code>true</code>, the sound is played back locally on the client rather than to
* @property {boolean} localOnly=false - If <code>true</code>, the sound is played back locally on the client rather than to
* others via the audio mixer.
* @property {boolean} ignorePenumbra=false - <strong>Deprecated:</strong> This property is deprecated and will be
* removed.
* @property {boolean} ignorePenumbra=false - <p class="important">Deprecated: This property is deprecated and will be
* removed.</p>
*/
void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) {
if (!object.isObject()) {

2
libraries/audio/src/Sound.h
View file

@ -124,7 +124,7 @@ typedef QSharedPointer<Sound> SharedSoundPointer;
* An audio resource, created by {@link SoundCache.getSound}, to be played back using {@link Audio.playSound}.
* <p>Supported formats:</p>
* <ul>
* <li>WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2 (stereo), or 4 (ambisonic) channels.</li>
* <li>WAV: 16-bit uncompressed at any sample rate, with 1 (mono), 2 (stereo), or 4 (ambisonic) channels.</li>
* <li>MP3: Mono or stereo, at any sample rate.</li>
* <li>RAW: 48khz 16-bit mono or stereo. File name must include <code>".stereo"</code> to be interpreted as stereo.</li>
* </ul>

87
libraries/script-engine/src/AudioScriptingInterface.h
View file

@ -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 <caption>Listen to a single nearby avatar for a short while.</caption>
* // 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<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 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<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 +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} <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 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 - <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 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} <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 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 - <code>true</code> to enable echoing microphone audio back to you from the client,
* <code>false</code> to disable.
* @example <caption>Echo local audio for a few seconds.</caption>
* 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 &mdash; "injecting" &mdash; 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 <code>injectorOptions</code> has <code>localOnly</code> set to
* <code>true</code> 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 <caption>Play a sound.</caption>
* 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} <code>localOnly</code> set <code>true</code> and
* the specified <code>position</code>.
* @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 <code>true</code> 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 <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>.
*/
@ -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 <code>Audio.noiseReduction</code> is
* <code>true</code>.
* @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 <code>Audio.noiseReduction</code> is
* <code>true</code>.
* @function Audio.noiseGateClosed

16
libraries/script-engine/src/ScriptAudioInjector.h
View file

@ -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 or "injects" 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 starts 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>