Recording JSDoc

libraries/script-engine/src/RecordingScriptingInterface.h

@@ -24,6 +24,9 @@ class QScriptEngine;
 class QScriptValue;
 
 /**jsdoc
+ * The <code>Recording</code> API makes and plays back recordings of voice and avatar movements. Playback may be done on a 
+ * user's avatar or an assignment client agent (see the {@link Agent} API).
+ *
  * @namespace Recording
  *
  * @hifi-interface
@@ -40,56 +43,79 @@ public:
 public slots:
 
     /**jsdoc
-     * @function Recording.loadRecording
+     * Called when a {@link Recording.loadRecording} call is complete.
-     * @param {string} url
+     * @callback Recording~loadRecordingCallback
-     * @param {Recording~loadRecordingCallback} [callback=null]
+     * @param {boolean} success - <code>true</code> if the recording has successfully been loaded, <code>false</code> if it 
+     *     hasn't.
+     * @param {string} url - The URL of the recording that was requested to be loaded.
      */
     /**jsdoc
-     * Called when {@link Recording.loadRecording} is complete.
+     * Loads a recording so that it is ready for playing.
-     * @callback Recording~loadRecordingCallback
+     * @function Recording.loadRecording
-     * @param {boolean} success
+     * @param {string} url - The ATP, HTTP, or file system URL of the recording to load.
-     * @param {string} url
+     * @param {Recording~loadRecordingCallback} [callback=null] - The function to call upon completion.
+     * @example <caption>Load and play back a recording from the asset server.</caption>
+     * var assetPath = Window.browseAssets();
+     * print("Asset path: " + assetPath);
+     * 
+     * if (assetPath.slice(-4) === ".hfr") {
+     *     Recording.loadRecording("atp:" + assetPath, function (success, url) {
+     *         if (!success) {
+     *             print("Error loading recording.");
+     *             return;
+     *         }
+     *         Recording.startPlaying();
+     *     });
+     * }
      */
     void loadRecording(const QString& url, QScriptValue callback = QScriptValue());
 
 
     /**jsdoc
+     * Starts playing the recording currently loaded or paused.
      * @function Recording.startPlaying
      */
     void startPlaying();
 
     /**jsdoc
+     * Pauses playback of the recording currently playing. Use {@link Recording.startPlaying|startPlaying} to resume playback 
+     * or {@link Recording.stopPlaying|stopPlaying} to stop playback.
      * @function Recording.pausePlayer
      */
     void pausePlayer();
 
     /**jsdoc
+     * Stops playing the recording currently playing or paused.
      * @function Recording.stopPlaying
      */
     void stopPlaying();
 
     /**jsdoc
+     * Gets whether a recording is currently playing.
      * @function Recording.isPlaying
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if a recording is being played, <code>false</code> if one isn't.
      */
     bool isPlaying() const;
 
     /**jsdoc
+     * Gets whether recording playback is currently paused.
      * @function Recording.isPaused
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if recording playback is currently paused, <code>false</code> if it isn't.
      */
     bool isPaused() const;
 
 
     /**jsdoc
+     * Gets the current playback time in the loaded recording, in seconds.
      * @function Recording.playerElapsed
-     * @returns {number}
+     * @returns {number} The current playback time in the loaded recording, in seconds.
      */
     float playerElapsed() const;
 
     /**jsdoc
+     * Gets the length of the loaded recording, in seconds.
      * @function Recording.playerLength
-     * @returns {number}
+     * @returns {number} The length of the recording currently loaded, in seconds
      */
     float playerLength() const;
 
@@ -102,132 +128,222 @@ public slots:
     void setPlayerVolume(float volume);
 
     /**jsdoc
+     * <p class="important">Not implemented: This method is not implemented yet.</p>
      * @function Recording.setPlayerAudioOffset
-     * @param {number} audioOffset
+     * @param {number} audioOffset - Audio offset.
      */
     void setPlayerAudioOffset(float audioOffset);
 
     /**jsdoc
+     * Sets the current playback time in the loaded recording.
      * @function Recording.setPlayerTime
-     * @param {number} time
+     * @param {number} time - The current playback time, in seconds.
      */
     void setPlayerTime(float time);
 
     /**jsdoc
+     * Sets whether playback should repeat in a loop.
      * @function Recording.setPlayerLoop
-     * @param {boolean} loop
+     * @param {boolean} loop - <code>true</code> if playback should repeat, <code>false</code> if it shouldn't.
      */
     void setPlayerLoop(bool loop);
 
 
     /**jsdoc
+     * Sets whether recording playback will use the display name that the recording was made with.
      * @function Recording.setPlayerUseDisplayName
-     * @param {boolean} useDisplayName
+     * @param {boolean} useDisplayName - <code>true</code> to have recording playback use the display name that the recording 
+     *     was made with, <code>false</code> to have recording playback keep the current display name.
      */
     void setPlayerUseDisplayName(bool useDisplayName);
 
     /**jsdoc
+     * <p><em>Not used.</em></p>
      * @function Recording.setPlayerUseAttachments
-     * @param {boolean} useAttachments
+     * @param {boolean} useAttachments - Use attachments.
+     * @deprecated This method is deprecated and will be removed.
      */
     void setPlayerUseAttachments(bool useAttachments);
 
     /**jsdoc
+     * <p><em>Not used.</em></p>
      * @function Recording.setPlayerUseHeadModel
-     * @param {boolean} useHeadModel
+     * @param {boolean} useHeadModel - Use head model.
-     * @todo <strong>Note:</strong> This function currently has no effect.
+     * @deprecated This method is deprecated and will be removed.
      */
     void setPlayerUseHeadModel(bool useHeadModel);
 
     /**jsdoc
+     * Sets whether recording playback will use the avatar model that the recording was made with.
      * @function Recording.setPlayerUseSkeletonModel
-     * @param {boolean} useSkeletonModel
+     * @param {boolean} useSkeletonModel - <code>true</code> to have recording playback use the avatar model that the recording 
-     * @todo <strong>Note:</strong> This function currently doesn't work.
+     *     was made with, <code>false</code> to have playback use the current avatar model.
      */
     void setPlayerUseSkeletonModel(bool useSkeletonModel);
 
     /**jsdoc
+     * Sets whether recordings are played at the current avatar location or the recorded location.
      * @function Recording.setPlayFromCurrentLocation
-     * @param {boolean} playFromCurrentLocation
+     * @param {boolean} playFromCurrentLocation - <code>true</code> to play recordings at the current avatar location, 
+     *     <code>false</code> to play recordings at the recorded location.
      */
     void setPlayFromCurrentLocation(bool playFromCurrentLocation);
 
 
     /**jsdoc
+     * Gets whether recording playback will use the display name that the recording was made with.
      * @function Recording.getPlayerUseDisplayName
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if recording playback will use the display name that the recording was made with, 
+     *     <code>false</code> if playback will keep the current display name.
      */
     bool getPlayerUseDisplayName() { return _useDisplayName; }
 
     /**jsdoc
+     * <p><em>Not used.</em></p>
      * @function Recording.getPlayerUseAttachments
-     * @returns {boolean}
+     * @returns {boolean} Use attachments.
+     * @deprecated This method is deprecated and will be removed.
      */
     bool getPlayerUseAttachments() { return _useAttachments; }
 
     /**jsdoc
+     * <p><em>Not used.</em></p>
      * @function Recording.getPlayerUseHeadModel
-     * @returns {boolean}
+     * @returns {boolean} Use head model.
+     * @deprecated This method is deprecated and will be removed.
      */
     bool getPlayerUseHeadModel() { return _useHeadModel; }
 
     /**jsdoc
+     * Gets whether recording playback will use the avatar model that the recording was made with.
      * @function Recording.getPlayerUseSkeletonModel
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if recording playback will use the avatar model that the recording was made with, 
+     *     <code>false</code> if playback will use the current avatar model.
      */
     bool getPlayerUseSkeletonModel() { return _useSkeletonModel; }
 
     /**jsdoc
+     * Gets whether recordings are played at the current avatar location or the recorded location.
      * @function Recording.getPlayFromCurrentLocation
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if recordings are played at the current avatar location, <code>false</code> if 
+     *     played at the recorded location.
      */
     bool getPlayFromCurrentLocation() { return _playFromCurrentLocation; }
 
 
     /**jsdoc
+     * Starts making a recording.
      * @function Recording.startRecording
      */
     void startRecording();
 
     /**jsdoc
+     * Stops making a recording. The recording may be saved using {@link Recording.saveRecording|saveRecording} or 
+     * {@link Recording.saveRecordingToAsset|saveRecordingToAsset}, or immediately played back with 
+     * {@link Recording.loadLastRecording|loadLastRecording}.
      * @function Recording.stopRecording
      */
     void stopRecording();
 
     /**jsdoc
+     * Gets whether a recording is currently being made.
      * @function Recording.isRecording
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if a recording is currently being made, <code>false</code> if one isn't.
      */
     bool isRecording() const;
 
 
     /**jsdoc
+     * Gets the duration of the recording currently being made or recently made, in seconds.
      * @function Recording.recorderElapsed
-     * @returns {number}
+     * @returns {number} The duration of the recording currently being made or recently made, in seconds.
      */
     float recorderElapsed() const;
 
 
     /**jsdoc
+     * Gets the default directory that recordings are saved in.
      * @function Recording.getDefaultRecordingSaveDirectory
-     * @returns {string}
+     * @returns {string} The default recording save directory.
+     * @exampl <caption>Report the default save directory.</caption>
+     * print("Default save directory: " + Recording.getDefaultRecordingSaveDirectory());
      */
     QString getDefaultRecordingSaveDirectory();
 
     /**jsdoc
+     * Saves the most recently made recording to a file.
      * @function Recording.saveRecording
-     * @param {string} filename
+     * @param {string} filename - The path and name of the file to save the recording to.
+     * @example <caption>Save a 5 second recording to a file.</caption>
+     * Recording.startRecording();
+     * 
+     * Script.setTimeout(function () {
+     *     Recording.stopRecording();
+     *     var filename = (new Date()).toISOString();  // yyyy-mm-ddThh:mm:ss.sssZ
+     *     filename = filename.slice(0, -5).replace(/:/g, "").replace("T", "-") 
+     *         + ".hfr";  // yyyymmmdd-hhmmss.hfr
+     *     filename = Recording.getDefaultRecordingSaveDirectory() + filename;
+     *     Recording.saveRecording(filename);
+     *     print("Saved recording: " + filename);
+     * }, 5000);
      */
     void saveRecording(const QString& filename);
 
     /**jsdoc
+     * Called when a {@link Recording.saveRecordingToAsset} call is complete.
+     * @callback Recording~saveRecordingToAssetCallback
+     * @param {string} url - The URL of the recording stored in the asset server if successful, <code>""</code> if 
+     *     unsuccessful. The URL has <code>atp:</code> as the scheme and the SHA256 hash as the filename (with no extension).
+     */
+    /**jsdoc
+     * Saves the most recently made recording to the domain's asset server.
      * @function Recording.saveRecordingToAsset
-     * @param {function} getClipAtpUrl
+     * @param {Recording~saveRecordingToAssetCallback} callback - The function to call upon completion.
+     * @returns {boolean} <code>true</code> if the recording is successfully being saved, <code>false</code> if not.
+     * @example <caption>Save a 5 second recording to the asset server.</caption>
+     * function onSavedRecordingToAsset(url) {
+     *     if (url === "") {
+     *         print("Couldn't save recording.");
+     *         return;
+     *     }
+     * 
+     *     print("Saved recording: " + url);  // atp:SHA256
+     * 
+     *     var filename = (new Date()).toISOString();  // yyyy-mm-ddThh:mm:ss.sssZ
+     *     filename = filename.slice(0, -5).replace(/:/g, "").replace("T", "-")
+     *         + ".hfr";  // yyyymmmdd-hhmmss.hfr
+     *     var hash = url.slice(4);  // Remove leading "atp:" from url.
+     *     mappingPath = "/recordings/" + filename;
+     *     Assets.setMapping(mappingPath, hash, function (error) {
+     *         if (error) {
+     *             print("Mapping error: " + error);
+     *         }
+     *     });
+     *     print("Mapped recording: " + mappingPath);  // /recordings/filename
+     * }
+     * 
+     * Recording.startRecording();
+     * 
+     * Script.setTimeout(function () {
+     *     Recording.stopRecording();
+     *     var success = Recording.saveRecordingToAsset(onSavedRecordingToAsset);
+     *     if (!success) {
+     *         print("Couldn't save recording.");
+     *     }
+     * }, 5000);
      */
     bool saveRecordingToAsset(QScriptValue getClipAtpUrl);
 
     /**jsdoc
+     * Loads the most recently made recording and plays it back on your avatar.
      * @function Recording.loadLastRecording
+     * @example <caption>Make a 5 second recording and immediately play it back on your avatar.</caption>
+     * Recording.startRecording();
+     * 
+     * Script.setTimeout(function () {
+     *     Recording.stopRecording();
+     *     Recording.loadLastRecording();
+     * }, 5000);
      */
     void loadLastRecording();