Fill in and tidy Audio API JSDoc

This commit is contained in:
David Rowe 2019-03-29 18:53:30 +13:00
parent 8ff47659d3
commit 5c8d89fb12
3 changed files with 128 additions and 93 deletions

View file

@ -40,24 +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} muted - <code>true</code> if the audio input is muted for the current user context (desktop or HMD),
* otherwise <code>false</code>.
* @property {boolean} desktopMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
* @property {boolean} hmdMuted - <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, a "muted" warning is displayed when you try to speak while your microphone is muted.
* @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} 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 {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 {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 {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 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)
@ -131,7 +147,7 @@ public:
Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD);
/**jsdoc
* Enable or disable reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options
* Enables or disables reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options
* come from either the domain's audio zone if used &mdash; configured on the server &mdash; or as scripted by
* {@link Audio.setReverbOptions|setReverbOptions}.
* @function Audio.setReverb
@ -164,69 +180,65 @@ public:
Q_INVOKABLE void setReverb(bool enable);
/**jsdoc
* Configure reverberation options. Use {@link Audio.setReverb|setReverb} to enable or disable reverberation.
* Configures reverberation options. Use {@link Audio.setReverb|setReverb} to enable or disable reverberation.
* @function Audio.setReverbOptions
* @param {AudioEffectOptions} options - The reverberation options.
*/
Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options);
/**jsdoc
* Sets the avatar gain at the server.
* Units are Decibels (dB)
* Sets the volume (gain) that avatar's voices are played at. This gain is used at the server.
* @function Audio.setAvatarGain
* @param {number} gain (in dB)
*/
* @param {number} Avatar gain (dB) at the server.
*/
Q_INVOKABLE void setAvatarGain(float gain);
/**jsdoc
* Gets the avatar gain at the server.
* Gets the volume (gain) that avatar's voices are played at. This gain is used at the server.
* @function Audio.getAvatarGain
* @returns {number} gain (in dB)
*/
* @returns {number} Avatar gain (dB) at the server.
*/
Q_INVOKABLE float getAvatarGain();
/**jsdoc
* Sets the injector gain at the server.
* Units are Decibels (dB)
* Sets the volume (gain) that the environment is played at, for sounds from the server.
* @function Audio.setInjectorGain
* @param {number} gain (in dB)
*/
* @param {number} Injector gain (dB) at the server.
*/
Q_INVOKABLE void setInjectorGain(float gain);
/**jsdoc
* Gets the injector gain at the server.
* Gets the volume (gain) that the environment is played at, for sounds from the server.
* @function Audio.getInjectorGain
* @returns {number} gain (in dB)
*/
* @returns {number} Injector gain (dB) at the server.
*/
Q_INVOKABLE float getInjectorGain();
/**jsdoc
* Sets the local injector gain in the client.
* Units are Decibels (dB)
* Sets the volume (gain) that the environment is played at, for sounds from the client.
* @function Audio.setLocalInjectorGain
* @param {number} gain (in dB)
*/
* @param {number} Local injector gain (dB) in the client.
*/
Q_INVOKABLE void setLocalInjectorGain(float gain);
/**jsdoc
* Gets the local injector gain in the client.
* Gets the volume (gain) that the environment is played at, for sounds from the client.
* @function Audio.getLocalInjectorGain
* @returns {number} gain (in dB)
*/
* @returns {number} Local injector gain (dB) in the client.
*/
Q_INVOKABLE float getLocalInjectorGain();
/**jsdoc
* Sets the injector gain for system sounds.
* Units are Decibels (dB)
* Sets the volume (gain) that system sounds are played at.
* @function Audio.setSystemInjectorGain
* @param {number} gain (in dB)
*/
* @param {number} System injector gain (dB) in the client.
*/
Q_INVOKABLE void setSystemInjectorGain(float gain);
/**jsdoc
* Gets the injector gain for system sounds.
* Gets the volume (gain) that system sounds are played at.
* @function Audio.getSystemInjectorGain
* @returns {number} gain (in dB)
* @returns {number} System injector gain (dB) in the client.
*/
Q_INVOKABLE float getSystemInjectorGain();
@ -252,13 +264,13 @@ public:
Q_INVOKABLE bool startRecording(const QString& filename);
/**jsdoc
* Finish making an audio recording started with {@link Audio.startRecording|startRecording}.
* Finishes making an audio recording started with {@link Audio.startRecording|startRecording}.
* @function Audio.stopRecording
*/
Q_INVOKABLE void stopRecording();
/**jsdoc
* Check whether an audio recording is currently being made.
* Checks whether an audio recording is currently being made.
* @function Audio.getRecording
* @returns {boolean} <code>true</code> if an audio recording is currently being made, otherwise <code>false</code>.
*/
@ -274,9 +286,10 @@ signals:
void nop();
/**jsdoc
* Triggered when the audio input is muted or unmuted.
* Triggered when the audio input is muted or unmuted for the current context (desktop or HMD).
* @function Audio.mutedChanged
* @param {boolean} isMuted - <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) {
@ -286,47 +299,47 @@ signals:
void mutedChanged(bool isMuted);
/**jsdoc
* Triggered when desktop audio input is muted or unmuted.
* @function Audio.desktopMutedChanged
* @param {boolean} isMuted - <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.desktopMutedChanged
* @param {boolean} isMuted - <code>true</code> if desktop audio input is muted, otherwise <code>false</code>.
* @returns {Signal}
*/
void desktopMutedChanged(bool isMuted);
/**jsdoc
* Triggered when HMD audio input is muted or unmuted.
* @function Audio.hmdMutedChanged
* @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.hmdMutedChanged
* @param {boolean} isMuted - <code>true</code> if HMD audio input is muted, otherwise <code>false</code>.
* @returns {Signal}
*/
void hmdMutedChanged(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}
*/
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}
@ -378,11 +391,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 push-to-talk changes.
* @function Audio.pushingToTalkChanged
* @param {boolean} talking - <code>true</code> if started pushing to talk, <code>false</code> if stopped pushing to talk.
* @returns {Signal}
*/
void pushingToTalkChanged(bool talking);
public slots:

View file

@ -41,25 +41,27 @@ public:
}
/**jsdoc
* Add nodes to the audio solo list
* Adds avatar to the audio solo list. If the audio solo list is non-empty, only audio from the avatars in the list is
* played.
* @function Audio.addToSoloList
* @param {Uuid[]} uuidList - List of node UUIDs to add to the solo list.
* @param {Uuid[]} ids - Avatar IDs to add to the solo list.
*/
Q_INVOKABLE void addToSoloList(QVector<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 non-empty, only audio from the avatars in the list
* is played.
* @function Audio.removeFromSoloList
* @param {Uuid[]} uuidList - List of node UUIDs to remove from the solo list.
* @param {Uuid[]} ids - Avatar IDs to remove from the solo list.
*/
Q_INVOKABLE void removeFromSoloList(QVector<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 +69,51 @@ public:
}
/**jsdoc
* Gets whether echoing microphone audio back to your from the server is enabled. When enabled, microphone audio is echoed
* only if you're unmuted or are pushing-to-talk.
* @function Audio.getServerEcho
* @returns {boolean} <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 echoiing microphone audio back to your from the server is enabled. When enabled, microphone audio is echoed
* only if you're unmuted or are pushing-to-talk.
* @function Audio.setServerEcho
* @parm {boolean} serverEcho
* @parm {boolean} serverEcho - <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 pushing-to-talk.
* @function Audio.toggleServerEcho
*/
Q_INVOKABLE void toggleServerEcho();
/**jsdoc
* Gets whether echoing microphone audio back to your by the client is enabled. When enabled, microphone audio is even if
* you're muted or not pushing-to-talk.
* @function Audio.getLocalEcho
* @returns {boolean} <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 echoing microphone audio back to your by the client is enabled. When enabled, microphone audio is even if
* you're muted or not pushing-to-talk.
* @function Audio.setLocalEcho
* @parm {boolean} localEcho
* @parm {boolean} localEcho - <code>true</code> to enable echoing microphone audio back to you from the client,
* <code>false</code> to disable.
*/
Q_INVOKABLE void setLocalEcho(bool localEcho);
/**jsdoc
* Toggles the echoing of microphone audio back to you from the client. When enabled, microphone audio is echoed even if
* you're muted or not pushing-to-talk.
* @function Audio.toggleLocalEcho
*/
Q_INVOKABLE void toggleLocalEcho();
@ -129,7 +149,7 @@ protected:
Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions());
/**jsdoc
* Start playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling
* Starts playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling
* {@link Audio.playSound} with {@link AudioInjector.AudioInjectorOptions} <code>localOnly</code> set <code>true</code> and
* the specified <code>position</code>.
* @function Audio.playSystemSound
@ -140,15 +160,15 @@ protected:
Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound);
/**jsdoc
* Set whether or not the audio input should be used in stereo. If the audio input does not support stereo then setting a
* value of <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>.
*/

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 &mdash; "injects" &mdash; 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 start 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>