Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-08-08 23:57:13 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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-server-entity
* @hifi-assignment-client * @hifi-assignment-client
* *
* @property {boolean} muted - <code>true</code> if the audio input is muted, otherwise <code>false</code>. * @property {boolean} muted - <code>true</code> if the audio input is muted for the current user context (desktop or HMD),
* @property {boolean} mutedDesktop - <code>true</code> if the audio input is muted, otherwise <code>false</code>. * 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 * @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 * enabled, the input audio signal is blocked (fully attenuated) when it falls below an adaptive threshold set just
* above the noise floor. * 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; * @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> * <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 {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>. * @property {string} context - The current context of the audio: either <code>"Desktop"</code> or <code>"HMD"</code>.
* <em>Read-only.</em> * <em>Read-only.</em>
* @property {object} devices <em>Read-only.</em> <strong>Deprecated:</strong> This property is deprecated and will be * @property {object} devices - <em>Read-only.</em>
* removed. * <p class="important">Deprecated: This property is deprecated and will be removed.
* @property {boolean} isSoloing <em>Read-only.</em> <code>true</code> if any nodes are soloed. * @property {boolean} pushToTalk - <code>true</code> if push-to-talk is enabled for the current user context (desktop or
* @property {Uuid[]} soloList <em>Read-only.</em> Get the list of currently soloed node UUIDs. * HMD), otherwise <code>false</code>.
* @property {boolean} pushToTalkDesktop - <code>true</code> if desktop push-to-talk is enabled, otherwise
* <code>false</code>.
* @property {boolean} pushToTalkHMD - <code>true</code> if HMD push-to-talk is enabled, otherwise <code>false</code>.
* @property {boolean} pushingToTalk - <code>true</code> if the user is currently pushing-to-talk, otherwise
* <code>false</code>.
*
* @comment The following properties are from AudioScriptingInterface.h.
* @property {boolean} isStereoInput - <code>true</code> if the input audio is being used in stereo, otherwise
* <code>false</code>. Some devices do not support stereo, in which case the value is always <code>false</code>.
* @property {boolean} isSoloing - <code>true</code> if 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) Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
@ -117,23 +132,23 @@ public:
/**jsdoc /**jsdoc
* @function Audio.setInputDevice * @function Audio.setInputDevice
* @param {object} device * @param {object} device - Device.
* @param {boolean} isHMD * @param {boolean} isHMD - Is HMD.
* @deprecated This function is deprecated and will be removed. * @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE void setInputDevice(const QAudioDeviceInfo& device, bool isHMD); Q_INVOKABLE void setInputDevice(const QAudioDeviceInfo& device, bool isHMD);
/**jsdoc /**jsdoc
* @function Audio.setOutputDevice * @function Audio.setOutputDevice
* @param {object} device * @param {object} device - Device.
* @param {boolean} isHMD * @param {boolean} isHMD - Is HMD.
* @deprecated This function is deprecated and will be removed. * @deprecated This function is deprecated and will be removed.
*/ */
Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD); Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD);
/**jsdoc /**jsdoc
* Enable or disable reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options * Enables or disables reverberation. Reverberation is done by the client on the post-mix audio. The reverberation options
* come from either the domain's audio zone if used &mdash; configured on the server &mdash; or as scripted by * come from either the domain's audio zone configured on the server or settings scripted by
* {@link Audio.setReverbOptions|setReverbOptions}. * {@link Audio.setReverbOptions|setReverbOptions}.
* @function Audio.setReverb * @function Audio.setReverb
* @param {boolean} enable - <code>true</code> to enable reverberation, <code>false</code> to disable. * @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); Q_INVOKABLE void setReverb(bool enable);
/**jsdoc /**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 * @function Audio.setReverbOptions
* @param {AudioEffectOptions} options - The reverberation options. * @param {AudioEffectOptions} options - The reverberation options.
*/ */
Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options); Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options);
/**jsdoc /**jsdoc
* Sets the avatar gain at the server. * Sets the gain (relative volume) that avatars' voices are played at. This gain is used at the server.
* Units are Decibels (dB)
* @function Audio.setAvatarGain * @function Audio.setAvatarGain
* @param {number} gain (in dB) * @param {number} gain - Avatar gain (dB) at the server.
*/ */
Q_INVOKABLE void setAvatarGain(float gain); Q_INVOKABLE void setAvatarGain(float gain);
/**jsdoc /**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 * @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(); Q_INVOKABLE float getAvatarGain();
/**jsdoc /**jsdoc
* Sets the injector gain at the server. * Sets the gain (relative volume) that environment sounds from the server are played at.
* Units are Decibels (dB)
* @function Audio.setInjectorGain * @function Audio.setInjectorGain
* @param {number} gain (in dB) * @param {number} gain - Injector gain (dB) at the server.
*/ */
Q_INVOKABLE void setInjectorGain(float gain); Q_INVOKABLE void setInjectorGain(float gain);
/**jsdoc /**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 * @function Audio.getInjectorGain
* @returns {number} gain (in dB) * @returns {number} Injector gain (dB) at the server.
*/ */
Q_INVOKABLE float getInjectorGain(); Q_INVOKABLE float getInjectorGain();
/**jsdoc /**jsdoc
* Sets the local injector gain in the client. * Sets the gain (relative volume) that environment sounds from the client are played at.
* Units are Decibels (dB)
* @function Audio.setLocalInjectorGain * @function Audio.setLocalInjectorGain
* @param {number} gain (in dB) * @param {number} gain - Injector gain (dB) in the client.
*/ */
Q_INVOKABLE void setLocalInjectorGain(float gain); Q_INVOKABLE void setLocalInjectorGain(float gain);
/**jsdoc /**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 * @function Audio.getLocalInjectorGain
* @returns {number} gain (in dB) * @returns {number} Injector gain (dB) in the client.
*/ */
Q_INVOKABLE float getLocalInjectorGain(); Q_INVOKABLE float getLocalInjectorGain();
/**jsdoc /**jsdoc
* Sets the injector gain for system sounds. * Sets the gain (relative volume) that system sounds are played at.
* Units are Decibels (dB)
* @function Audio.setSystemInjectorGain * @function Audio.setSystemInjectorGain
* @param {number} gain (in dB) * @param {number} gain - Injector gain (dB) in the client.
*/ */
Q_INVOKABLE void setSystemInjectorGain(float gain); Q_INVOKABLE void setSystemInjectorGain(float gain);
/**jsdoc /**jsdoc
* Gets the injector gain for system sounds. * Gets the gain (relative volume) that system sounds are played at.
* @function Audio.getSystemInjectorGain * @function Audio.getSystemInjectorGain
* @returns {number} gain (in dB) * @returns {number} Injector gain (dB) in the client.
*/ */
Q_INVOKABLE float getSystemInjectorGain(); Q_INVOKABLE float getSystemInjectorGain();
@ -253,13 +270,13 @@ public:
Q_INVOKABLE bool startRecording(const QString& filename); Q_INVOKABLE bool startRecording(const QString& filename);
/**jsdoc /**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 * @function Audio.stopRecording
*/ */
Q_INVOKABLE void stopRecording(); Q_INVOKABLE void stopRecording();
/**jsdoc /**jsdoc
* Check whether an audio recording is currently being made. * Checks whether an audio recording is currently being made.
* @function Audio.getRecording * @function Audio.getRecording
* @returns {boolean} <code>true</code> if an audio recording is currently being made, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if an audio recording is currently being made, otherwise <code>false</code>.
*/ */
@ -275,9 +292,10 @@ signals:
void nop(); void nop();
/**jsdoc /**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 * @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} * @returns {Signal}
* @example <caption>Report when audio input is muted or unmuted</caption> * @example <caption>Report when audio input is muted or unmuted</caption>
* Audio.mutedChanged.connect(function (isMuted) { * Audio.mutedChanged.connect(function (isMuted) {
@ -287,47 +305,55 @@ signals:
void mutedChanged(bool isMuted); void mutedChanged(bool isMuted);
/**jsdoc /**jsdoc
* Triggered when desktop audio input is muted or unmuted. * Triggered when desktop audio input is muted or unmuted.
* @function Audio.mutedDesktopChanged * @function Audio.mutedDesektopChanged
* @param {boolean} isMuted - <code>true</code> if the audio input is muted for desktop mode, otherwise <code>false</code>. * @param {boolean} isMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
*/ * @example <caption>Report when desktop muting changes.</caption>
* Audio.mutedDesktopChanged.connect(function (isMuted) {
* print("Desktop muted: " + isMuted);
* });
*/
void mutedDesktopChanged(bool isMuted); void mutedDesktopChanged(bool isMuted);
/**jsdoc /**jsdoc
* Triggered when HMD audio input is muted or unmuted. * Triggered when HMD audio input is muted or unmuted.
* @function Audio.mutedHMDChanged * @function Audio.mutedHMDChanged
* @param {boolean} isMuted - <code>true</code> if the audio input is muted for HMD mode, otherwise <code>false</code>. * @param {boolean} isMuted - <code>true</code> if HMD audio input is muted, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
*/ */
void mutedHMDChanged(bool isMuted); void mutedHMDChanged(bool isMuted);
/** /**jsdoc
* Triggered when Push-to-Talk has been enabled or disabled. * Triggered when push-to-talk is enabled or disabled for the current context (desktop or HMD).
* @function Audio.pushToTalkChanged * @function Audio.pushToTalkChanged
* @param {boolean} enabled - <code>true</code> if Push-to-Talk is enabled, otherwise <code>false</code>. * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
*/ * @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); void pushToTalkChanged(bool enabled);
/** /**jsdoc
* Triggered when Push-to-Talk has been enabled or disabled for desktop mode. * Triggered when push-to-talk is enabled or disabled for desktop mode.
* @function Audio.pushToTalkDesktopChanged * @function Audio.pushToTalkDesktopChanged
* @param {boolean} enabled - <code>true</code> if Push-to-Talk is emabled for Desktop mode, otherwise <code>false</code>. * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for desktop mode, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
*/ */
void pushToTalkDesktopChanged(bool enabled); void pushToTalkDesktopChanged(bool enabled);
/** /**jsdoc
* Triggered when Push-to-Talk has been enabled or disabled for HMD mode. * Triggered when push-to-talk is enabled or disabled for HMD mode.
* @function Audio.pushToTalkHMDChanged * @function Audio.pushToTalkHMDChanged
* @param {boolean} enabled - <code>true</code> if Push-to-Talk is emabled for HMD mode, otherwise <code>false</code>. * @param {boolean} enabled - <code>true</code> if push-to-talk is enabled for HMD mode, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
*/ */
void pushToTalkHMDChanged(bool enabled); void pushToTalkHMDChanged(bool enabled);
/**jsdoc /**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 * @function Audio.noiseReductionChanged
* @param {boolean} isEnabled - <code>true</code> if audio input noise reduction is enabled, otherwise <code>false</code>. * @param {boolean} isEnabled - <code>true</code> if audio input noise reduction is enabled, otherwise <code>false</code>.
* @returns {Signal} * @returns {Signal}
@ -346,8 +372,8 @@ signals:
* Triggered when the input audio volume changes. * Triggered when the input audio volume changes.
* @function Audio.inputVolumeChanged * @function Audio.inputVolumeChanged
* @param {number} volume - The requested volume to be applied to the audio input, range <code>0.0</code> &ndash; * @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: * <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> * 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>. * and <code>1.0</code>.
* @returns {Signal} * @returns {Signal}
*/ */
@ -379,11 +405,11 @@ signals:
void contextChanged(const QString& context); void contextChanged(const QString& context);
/**jsdoc /**jsdoc
* Triggered when pushing to talk. * Triggered when the user starts or stops push-to-talk.
* @function Audio.pushingToTalkChanged * @function Audio.pushingToTalkChanged
* @param {boolean} talking - <code>true</code> if broadcasting with PTT, <code>false</code> otherwise. * @param {boolean} talking - <code>true</code> if started push-to-talk, <code>false</code> if stopped push-to-talk.
* @returns {Signal} * @returns {Signal}
*/ */
void pushingToTalkChanged(bool talking); void pushingToTalkChanged(bool talking);
public slots: public slots:

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

@ -48,21 +48,23 @@ QScriptValue injectorOptionsToScriptValue(QScriptEngine* engine, const AudioInje
} }
/**jsdoc /**jsdoc
* Configures how an audio injector plays its audio. * Configures where and how an audio injector plays its audio.
* @typedef {object} AudioInjector.AudioInjectorOptions * @typedef {object} AudioInjector.AudioInjectorOptions
* @property {Vec3} position=Vec3.ZERO - The position in the domain to play the sound. * @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 {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} 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 * @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 * resample the sound at, range <code>0.0625</code> &ndash; <code>16.0</code>.<br />
* pitch by 2 octaves; <code>1.0</code> is no change in pitch; <code>16.0</code> raises the pitch by 2 octaves. * 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 {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; * @property {number} secondOffset=0 - Starts playback from a specified time (seconds) within the sound file, &ge;
* <code>0</code>. * <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. * others via the audio mixer.
* @property {boolean} ignorePenumbra=false - <strong>Deprecated:</strong> This property is deprecated and will be * @property {boolean} ignorePenumbra=false - <p class="important">Deprecated: This property is deprecated and will be
* removed. * removed.</p>
*/ */
void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) { void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) {
if (!object.isObject()) { 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}. * An audio resource, created by {@link SoundCache.getSound}, to be played back using {@link Audio.playSound}.
* <p>Supported formats:</p> * <p>Supported formats:</p>
* <ul> * <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>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> * <li>RAW: 48khz 16-bit mono or stereo. File name must include <code>".stereo"</code> to be interpreted as stereo.</li>
* </ul> * </ul>

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

@ -41,25 +41,54 @@ public:
} }
/**jsdoc /**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 * @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) { Q_INVOKABLE void addToSoloList(QVector<QUuid> uuidList) {
_localAudioInterface->getAudioSolo().addUUIDs(uuidList); _localAudioInterface->getAudioSolo().addUUIDs(uuidList);
} }
/**jsdoc /**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 * @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) { Q_INVOKABLE void removeFromSoloList(QVector<QUuid> uuidList) {
_localAudioInterface->getAudioSolo().removeUUIDs(uuidList); _localAudioInterface->getAudioSolo().removeUUIDs(uuidList);
} }
/**jsdoc /**jsdoc
* Reset the list of soloed nodes. * Clears the audio solo list.
* @function Audio.resetSoloList * @function Audio.resetSoloList
*/ */
Q_INVOKABLE void resetSoloList() { Q_INVOKABLE void resetSoloList() {
@ -67,33 +96,56 @@ public:
} }
/**jsdoc /**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 * @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(); Q_INVOKABLE bool getServerEcho();
/**jsdoc /**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 * @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); Q_INVOKABLE void setServerEcho(bool serverEcho);
/**jsdoc /**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 * @function Audio.toggleServerEcho
*/ */
Q_INVOKABLE void toggleServerEcho(); Q_INVOKABLE void toggleServerEcho();
/**jsdoc /**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 * @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(); Q_INVOKABLE bool getLocalEcho();
/**jsdoc /**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 * @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); Q_INVOKABLE void setLocalEcho(bool localEcho);
/**jsdoc /**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 * @function Audio.toggleLocalEcho
*/ */
Q_INVOKABLE void toggleLocalEcho(); Q_INVOKABLE void toggleLocalEcho();
@ -105,7 +157,7 @@ protected:
// these methods are protected to stop C++ callers from calling, but invokable from script // these methods are protected to stop C++ callers from calling, but invokable from script
/**jsdoc /**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 * 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 * <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 * 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 * @function Audio.playSound
* @param {SoundObject} sound - The content of an audio file, loaded using {@link SoundCache.getSound}. See * @param {SoundObject} sound - The content of an audio file, loaded using {@link SoundCache.getSound}. See
* {@link SoundObject} for supported formats. * {@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. * @returns {AudioInjector} The audio injector that plays the audio file.
* @example <caption>Play a sound.</caption> * @example <caption>Play a sound.</caption>
* var sound = SoundCache.getSound("http://hifi-content.s3.amazonaws.com/ken/samples/forest_ambiX.wav"); * 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()); Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions());
/**jsdoc /**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 * {@link Audio.playSound} with {@link AudioInjector.AudioInjectorOptions} <code>localOnly</code> set <code>true</code> and
* the specified <code>position</code>. * the specified <code>position</code>.
* @function Audio.playSystemSound * @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. * {@link SoundObject} for supported formats.
* @returns {AudioInjector} The audio injector that plays the audio file. * @returns {AudioInjector} The audio injector that plays the audio file.
*/ */
Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound); Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound);
/**jsdoc /**jsdoc
* Set whether or not the audio input should be used in stereo. If the audio input does not support stereo then setting a * Sets whether the audio input should be used in stereo. If the audio input doesn't support stereo then setting a value
* value of <code>true</code> has no effect. * of <code>true</code> has no effect.
* @function Audio.setStereoInput * @function Audio.setStereoInput
* @param {boolean} stereo - <code>true</code> if the audio input should be used in stereo, otherwise <code>false</code>. * @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); Q_INVOKABLE void setStereoInput(bool stereo);
/**jsdoc /**jsdoc
* Get whether or not the audio input is used in stereo. * Gets whether the audio input is used in stereo.
* @function Audio.isStereoInput * @function Audio.isStereoInput
* @returns {boolean} <code>true</code> if the audio input is used in stereo, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the audio input is used in stereo, otherwise <code>false</code>.
*/ */
@ -168,7 +221,7 @@ signals:
/**jsdoc /**jsdoc
* Triggered when the client is muted by the mixer because their loudness value for the noise background has reached the * 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 * @function Audio.mutedByMixer
* @returns {Signal} * @returns {Signal}
*/ */
@ -197,7 +250,7 @@ signals:
void disconnected(); void disconnected();
/**jsdoc /**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 * risen above an adaptive threshold set just above the noise floor. Only occurs if <code>Audio.noiseReduction</code> is
* <code>true</code>. * <code>true</code>.
* @function Audio.noiseGateOpened * @function Audio.noiseGateOpened
@ -206,7 +259,7 @@ signals:
void noiseGateOpened(); void noiseGateOpened();
/**jsdoc /**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 * below an adaptive threshold set just above the noise floor. Only occurs if <code>Audio.noiseReduction</code> is
* <code>true</code>. * <code>true</code>.
* @function Audio.noiseGateClosed * @function Audio.noiseGateClosed

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

@ -17,7 +17,9 @@
#include <AudioInjectorManager.h> #include <AudioInjectorManager.h>
/**jsdoc /**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 * @class AudioInjector
* *
@ -45,13 +47,13 @@ public:
public slots: public slots:
/**jsdoc /**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 * @function AudioInjector.restart
*/ */
void restart() { DependencyManager::get<AudioInjectorManager>()->restart(_injector); } void restart() { DependencyManager::get<AudioInjectorManager>()->restart(_injector); }
/**jsdoc /**jsdoc
* Stop audio playback. * Stops audio playback.
* @function AudioInjector.stop * @function AudioInjector.stop
* @example <caption>Stop playing a sound before it finishes.</caption> * @example <caption>Stop playing a sound before it finishes.</caption>
* var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
@ -71,28 +73,28 @@ public slots:
void stop() { DependencyManager::get<AudioInjectorManager>()->stop(_injector); } void stop() { DependencyManager::get<AudioInjectorManager>()->stop(_injector); }
/**jsdoc /**jsdoc
* Get the current configuration of the audio injector. * Gets the current configuration of the audio injector.
* @function AudioInjector.getOptions * @function AudioInjector.getOptions
* @returns {AudioInjector.AudioInjectorOptions} Configuration of how the injector plays the audio. * @returns {AudioInjector.AudioInjectorOptions} Configuration of how the injector plays the audio.
*/ */
AudioInjectorOptions getOptions() const { return DependencyManager::get<AudioInjectorManager>()->getOptions(_injector); } AudioInjectorOptions getOptions() const { return DependencyManager::get<AudioInjectorManager>()->getOptions(_injector); }
/**jsdoc /**jsdoc
* Configure how the injector plays the audio. * Configures how the injector plays the audio.
* @function AudioInjector.setOptions * @function AudioInjector.setOptions
* @param {AudioInjector.AudioInjectorOptions} options - Configuration of how the injector plays the audio. * @param {AudioInjector.AudioInjectorOptions} options - Configuration of how the injector plays the audio.
*/ */
void setOptions(const AudioInjectorOptions& options) { DependencyManager::get<AudioInjectorManager>()->setOptions(_injector, options); } void setOptions(const AudioInjectorOptions& options) { DependencyManager::get<AudioInjectorManager>()->setOptions(_injector, options); }
/**jsdoc /**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 * @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>. * @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); } float getLoudness() const { return DependencyManager::get<AudioInjectorManager>()->getLoudness(_injector); }
/**jsdoc /**jsdoc
* Get whether or not the audio is currently playing. * Gets whether or not the audio is currently playing.
* @function AudioInjector.isPlaying * @function AudioInjector.isPlaying
* @returns {boolean} <code>true</code> if the audio is currently playing, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the audio is currently playing, otherwise <code>false</code>.
* @example <caption>See if a sound is playing.</caption> * @example <caption>See if a sound is playing.</caption>