@lookit/record 3.0.1 → 4.1.0

package/src/recorder.ts

@@ -109,7 +109,13 @@ export default class Recorder {
     this.jsPsych.pluginAPI.initializeCameraRecorder(stream, recorder_options);
   }
 
-  /** Reset the recorder to be used again. */
+  /**
+   * Reset the recorder. This is used internally after stopping/uploading a
+   * recording, in order to create a new active stream that can be used by a new
+   * Recorder instance. This can also be used by the consuming plugin/extension
+   * when a recorder needs to be reset without the stop/upload events (e.g. in
+   * the video config plugin).
+   */
   public reset() {
     if (this.stream.active) {
       throw new StreamActiveOnResetError();
@@ -276,13 +282,19 @@ export default class Recorder {
    * tracks, clear the webcam feed element (if there is one), and return the
    * stop promise. This should only be called after recording has started.
    *
+   * @param maintain_container_size - Optional boolean indicating whether or not
+   *   to maintain the current size of the webcam feed container when removing
+   *   the video element. Default is false. If true, the container will be
+   *   resized to match the dimensions of the video element before it is
+   *   removed. This is useful for avoiding layout jumps when the webcam
+   *   container will be re-used during the trial.
    * @returns Promise that resolves after the media recorder has stopped and
    *   final 'dataavailable' event has occurred, when the "stop" event-related
    *   callback function is called.
    */
-  public stop() {
+  public stop(maintain_container_size: boolean = false) {
+    this.clearWebcamFeed(maintain_container_size);
     this.stopTracks();
-    this.clearWebcamFeed();
 
     if (!this.stopPromise) {
       throw new NoStopPromiseError();
@@ -326,6 +338,8 @@ export default class Recorder {
       } else {
         await this.s3.completeUpload();
       }
+      // Reset the recorder. This is necessary to create another active media stream from the stream clone, because the current stream is fully stopped/inactive and cannot be used again.
+      this.reset();
 
       resolve();
     };
@@ -353,12 +367,30 @@ export default class Recorder {
     }
   }
 
-  /** Private helper to clear the webcam feed, if there is one. */
-  private clearWebcamFeed() {
+  /**
+   * Private helper to clear the webcam feed, if there is one. If remove is
+   * false, the video element source attribute is cleared and the parent div
+   * will be set to the same dimensions. This is useful for avoiding layout
+   * jumps when the webcam container and video element will be re-used during
+   * the trial.
+   *
+   * @param maintain_container_size - Boolean indicating whether or not to set
+   *   the webcam feed container size before removing the video element
+   */
+  private clearWebcamFeed(maintain_container_size: boolean) {
     const webcam_feed_element = document.querySelector(
       `#${this.webcam_element_id}`,
     ) as HTMLVideoElement;
     if (webcam_feed_element) {
+      if (maintain_container_size) {
+        const parent_div = webcam_feed_element.parentElement as HTMLDivElement;
+        if (parent_div) {
+          const width = webcam_feed_element.offsetWidth;
+          const height = webcam_feed_element.offsetHeight;
+          parent_div.style.height = `${height}px`;
+          parent_div.style.width = `${width}px`;
+        }
+      }
       webcam_feed_element.remove();
     }
   }

package/src/start.ts

@@ -1,11 +1,17 @@
 import { LookitWindow } from "@lookit/data/dist/types";
 import { JsPsych, JsPsychPlugin } from "jspsych";
+import { version } from "../package.json";
 import { ExistingRecordingError } from "./errors";
 import Recorder from "./recorder";
 
 declare let window: LookitWindow;
 
-const info = <const>{ name: "start-record-plugin", parameters: {} };
+const info = <const>{
+  name: "start-record-plugin",
+  version,
+  parameters: {},
+  data: {},
+};
 type Info = typeof info;
 
 /** Start recording. Used by researchers who want to record across trials. */

package/src/stop.ts

@@ -1,6 +1,7 @@
 import { LookitWindow } from "@lookit/data/dist/types";
 import chsTemplates from "@lookit/templates";
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { version } from "../package.json";
 import { NoSessionRecordingError } from "./errors";
 import Recorder from "./recorder";
 
@@ -8,9 +9,32 @@ declare let window: LookitWindow;
 
 const info = <const>{
   name: "stop-record-plugin",
+  version,
   parameters: {
-    locale: { type: ParameterType.STRING, default: "en-us" },
+    /**
+     * This string can contain HTML markup. Any content provided will be
+     * displayed while the recording is uploading. If null (the default), then
+     * the default 'uploading video, please wait' (or appropriate translation
+     * based on 'locale') will be displayed. Use a blank string for no
+     * message/content.
+     */
+    wait_for_upload_message: {
+      type: ParameterType.HTML_STRING,
+      default: null as null | string,
+    },
+    /**
+     * Locale code used for translating the default 'uploading video, please
+     * wait' message. This code must be present in the translation files. If the
+     * code is not found then English will be used. If the
+     * 'wait_for_upload_message' parameter is specified then this value is
+     * ignored.
+     */
+    locale: {
+      type: ParameterType.STRING,
+      default: "en-us",
+    },
   },
+  data: {},
 };
 type Info = typeof info;
 
@@ -41,11 +65,21 @@ export default class StopRecordPlugin implements JsPsychPlugin<Info> {
    * @param trial - Trial object with parameters/values.
    */
   public trial(display_element: HTMLElement, trial: TrialType<Info>): void {
-    display_element.innerHTML = chsTemplates.uploadingVideo(trial);
-    this.recorder.stop().then(() => {
-      window.chs.sessionRecorder = null;
-      display_element.innerHTML = "";
-      this.jsPsych.finishTrial();
-    });
+    if (trial.wait_for_upload_message == null) {
+      display_element.innerHTML = chsTemplates.uploadingVideo(trial);
+    } else {
+      display_element.innerHTML = trial.wait_for_upload_message;
+    }
+    this.recorder
+      .stop()
+      .then(() => {
+        window.chs.sessionRecorder = null;
+        display_element.innerHTML = "";
+        this.jsPsych.finishTrial();
+      })
+      .catch((err) => {
+        console.error("StopRecordPlugin: recorder stop/upload failed.", err);
+        // TO DO: display translated error msg and/or researcher contact info
+      });
   }
 }

package/src/trial.ts

@@ -1,16 +1,55 @@
+import chsTemplates from "@lookit/templates";
 import autoBind from "auto-bind";
-import { JsPsych, JsPsychExtension, JsPsychExtensionInfo } from "jspsych";
+import {
+  JsPsych,
+  JsPsychExtension,
+  JsPsychExtensionInfo,
+  PluginInfo,
+  TrialType,
+} from "jspsych";
+import { version } from "../package.json";
 import Recorder from "./recorder";
 import { jsPsychPluginWithInfo } from "./types";
 
-/** This extension will allow reasearchers to record trials. */
+// JsPsychExtensionInfo does not allow parameters, so we define them as interfaces and use these to type the arguments passed to extension initialize and on_start functions.
+interface Parameters {
+  /**
+   * Content that should be displayed while the recording is uploading. If null
+   * (the default), then the default 'uploading video, please wait...' (or
+   * appropriate translation based on 'locale') will be displayed. Use a blank
+   * string for no message/content. Otherwise this parameter can be set to a
+   * custom string and can contain HTML markup. If you want to embed
+   * images/video/audio in this HTML string, be sure to preload the media files
+   * with the `preload` plugin and manual preloading. Use a blank string (`""`)
+   * for no message/content.
+   *
+   * @default null
+   */
+  wait_for_upload_message?: null | string;
+  /**
+   * Locale code used for translating the default 'uploading video, please
+   * wait...' message. This code must be present in the translation files. If
+   * the code is not found then English will be used. If the
+   * 'wait_for_upload_message' parameter is specified then this value
+   * isignored.
+   *
+   * @default "en-us"
+   */
+  locale?: string;
+}
+
+/** This extension allows researchers to record webcam audio/video during trials. */
 export default class TrialRecordExtension implements JsPsychExtension {
   public static readonly info: JsPsychExtensionInfo = {
     name: "chs-trial-record-extension",
+    version,
+    data: {},
   };
 
   private recorder?: Recorder;
   private pluginName: string | undefined;
+  private uploadMsg: null | string = null;
+  private locale: string = "en-us";
 
   /**
    * Video recording extension.
@@ -22,29 +61,76 @@ export default class TrialRecordExtension implements JsPsychExtension {
   }
 
   /**
-   * Ran on the initialize step for extensions, called when an instance of
+   * Runs on the initialize step for extensions, called when an instance of
    * jsPsych is first initialized through initJsPsych().
+   *
+   * @param params - Parameters object
+   * @param params.wait_for_upload_message - Message to display while waiting
+   *   for upload. String or null (default)
+   * @param params.locale - Message to display while waiting for upload. String
+   *   or null (default).
    */
-  public async initialize() {}
+  public async initialize(params?: Parameters) {
+    await new Promise<void>((resolve) => {
+      this.uploadMsg = params?.wait_for_upload_message
+        ? params.wait_for_upload_message
+        : null;
+      this.locale = params?.locale ? params.locale : "en-us";
+      console.log(this.uploadMsg);
+      console.log(this.locale);
+      resolve();
+    });
+  }
 
-  /** Ran at the start of a trial. */
-  public on_start() {
+  /**
+   * Runs at the start of a trial.
+   *
+   * @param startParams - Parameters object
+   * @param startParams.wait_for_upload_message - Message to display while
+   *   waiting for upload. String or null (default). If given, this will
+   *   overwrite the value used during initialization.
+   */
+  public on_start(startParams?: Parameters) {
+    if (startParams?.wait_for_upload_message) {
+      this.uploadMsg = startParams.wait_for_upload_message;
+    }
+    if (startParams?.locale) {
+      this.locale = startParams.locale;
+    }
+    console.log(this.uploadMsg);
+    console.log(this.locale);
     this.recorder = new Recorder(this.jsPsych);
   }
 
-  /** Ran when the trial has loaded. */
+  /** Runs when the trial has loaded. */
   public on_load() {
     this.pluginName = this.getCurrentPluginName();
     this.recorder?.start(false, `${this.pluginName}`);
   }
 
   /**
-   * Ran when trial has finished.
+   * Runs when trial has finished.
    *
-   * @returns Trial data.
+   * @returns Any data from the trial extension that should be added to the rest
+   *   of the trial data.
    */
-  public on_finish() {
-    this.recorder?.stop();
+  public async on_finish() {
+    const displayEl = this.jsPsych.getDisplayElement();
+    if (this.uploadMsg == null) {
+      displayEl.innerHTML = chsTemplates.uploadingVideo({
+        type: this.jsPsych.getCurrentTrial().type,
+        locale: this.locale,
+      } as TrialType<PluginInfo>);
+    } else {
+      displayEl.innerHTML = this.uploadMsg;
+    }
+    try {
+      await this.recorder?.stop();
+      displayEl.innerHTML = "";
+    } catch (err) {
+      console.error("TrialRecordExtension: recorder stop/upload failed.", err);
+      // TO DO: display translated error msg and/or researcher contact info
+    }
     return {};
   }