Add further Audio API examples

interface/src/scripting/Audio.h

@@ -197,6 +197,12 @@ public:
      * Gets the volume (gain) that avatar's voices are played at. This gain is used at the server.
      * @function Audio.getAvatarGain
      * @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();
 
@@ -303,6 +309,10 @@ signals:
      * @function Audio.desktopMutedChanged
      * @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.desktopMutedChanged.connect(function (desktopMuted) {
+     *     print("Desktop muted: " + desktopMuted);
+     * });
      */
     void desktopMutedChanged(bool isMuted);
 
@@ -319,6 +329,10 @@ signals:
      * @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);
 

libraries/script-engine/src/AudioScriptingInterface.h

@@ -45,6 +45,33 @@ public:
      * played.
      * @function Audio.addToSoloList
      * @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);
@@ -108,6 +135,11 @@ public:
      * @function Audio.setLocalEcho
      * @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);