@lookit/record 3.0.1 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lookit/record",
-  "version": "3.0.1",
+  "version": "4.1.0",
   "description": "Recording extensions and plugins for CHS studies.",
   "homepage": "https://github.com/lookit/lookit-jspsych#readme",
   "bugs": {
@@ -42,7 +42,7 @@
   },
   "peerDependencies": {
     "@lookit/data": "^0.2.0",
-    "@lookit/templates": "^2.0.0",
+    "@lookit/templates": "^2.1.0",
     "jspsych": "^8.0.3"
   }
 }

package/src/consentVideo.spec.ts

@@ -6,11 +6,7 @@ import { initJsPsych, PluginInfo, TrialType } from "jspsych";
 import playbackFeed from "../hbs/playback-feed.hbs";
 import recordFeed from "../hbs/record-feed.hbs";
 import { VideoConsentPlugin } from "./consentVideo";
-import {
-  ButtonNotFoundError,
-  ImageNotFoundError,
-  VideoContainerNotFoundError,
-} from "./errors";
+import { ElementNotFoundError } from "./errors";
 import Recorder from "./recorder";
 
 declare const window: LookitWindow;
@@ -67,7 +63,21 @@ test("GetVideoContainer error when no container", () => {
   const plugin = new VideoConsentPlugin(jsPsych);
   expect(() =>
     plugin["getVideoContainer"](document.createElement("div")),
-  ).toThrow(VideoContainerNotFoundError);
+  ).toThrow(ElementNotFoundError);
+  expect(() =>
+    plugin["getVideoContainer"](document.createElement("div")),
+  ).toThrow(`"${plugin["video_container_id"]}" div not found.`);
+});
+
+test("getMessageContainer error when no container", () => {
+  const jsPsych = initJsPsych();
+  const plugin = new VideoConsentPlugin(jsPsych);
+  expect(() =>
+    plugin["getMessageContainer"](document.createElement("div")),
+  ).toThrow(ElementNotFoundError);
+  expect(() =>
+    plugin["getMessageContainer"](document.createElement("div")),
+  ).toThrow(`"${plugin["msg_container_id"]}" div not found.`);
 });
 
 test("GetVideoContainer", () => {
@@ -81,6 +91,17 @@ test("GetVideoContainer", () => {
   expect(html).toBe(`<div id="lookit-jspsych-video-container"></div>`);
 });
 
+test("getMessageContainer", () => {
+  const jsPsych = initJsPsych();
+  const plugin = new VideoConsentPlugin(jsPsych);
+  const display = document.createElement("div");
+
+  display.innerHTML = `<div id="${plugin["msg_container_id"]}"></div>`;
+
+  const html = plugin["getMessageContainer"](display).outerHTML;
+  expect(html).toBe(`<div id="lookit-jspsych-video-msg-container"></div>`);
+});
+
 test("recordFeed", () => {
   const jsPsych = initJsPsych();
   const plugin = new VideoConsentPlugin(jsPsych);
@@ -103,7 +124,7 @@ test("playbackFeed", () => {
   const vidContainer = "some video container";
 
   plugin["getVideoContainer"] = jest.fn().mockReturnValue(vidContainer);
-  plugin["onEnded"] = jest.fn().mockReturnValue("some func");
+  plugin["onPlaybackEnded"] = jest.fn().mockReturnValue("some func");
   plugin["playbackFeed"](display);
 
   expect(Recorder.prototype.insertPlaybackFeed).toHaveBeenCalledWith(
@@ -112,7 +133,7 @@ test("playbackFeed", () => {
   );
 });
 
-test("onEnded", () => {
+test("onPlaybackEnded", () => {
   const jsPsych = initJsPsych();
   const plugin = new VideoConsentPlugin(jsPsych);
   const display = document.createElement("div");
@@ -145,7 +166,7 @@ test("onEnded", () => {
     return "";
   });
 
-  plugin["onEnded"](display)();
+  plugin["onPlaybackEnded"](display)();
 
   expect(plugin["recordFeed"]).toHaveBeenCalledWith(display);
   expect(plugin["recordFeed"]).toHaveBeenCalledTimes(1);
@@ -174,7 +195,10 @@ test("getButton error when button not found", () => {
   const display = document.createElement("div");
 
   expect(() => plugin["getButton"](display, "next")).toThrow(
-    ButtonNotFoundError,
+    ElementNotFoundError,
+  );
+  expect(() => plugin["getButton"](display, "next")).toThrow(
+    `"next" button not found.`,
   );
 });
 
@@ -183,7 +207,10 @@ test("getImg error when image not found", () => {
   const plugin = new VideoConsentPlugin(jsPsych);
   const display = document.createElement("div");
   expect(() => plugin["getImg"](display, "record-icon")).toThrow(
-    ImageNotFoundError,
+    ElementNotFoundError,
+  );
+  expect(() => plugin["getImg"](display, "record-icon")).toThrow(
+    `"record-icon" img not found.`,
   );
 });
 
@@ -283,7 +310,6 @@ test("stopButton", async () => {
     .forEach((button) => expect(button.disabled).toBeFalsy());
   expect(stopButton!.disabled).toBeTruthy();
   expect(Recorder.prototype.stop).toHaveBeenCalledTimes(1);
-  expect(Recorder.prototype.reset).toHaveBeenCalledTimes(1);
   expect(plugin["recordFeed"]).toHaveBeenCalledTimes(1);
   expect(plugin["recordFeed"]).toHaveBeenCalledWith(display);
 });

package/src/consentVideo.ts

@@ -3,11 +3,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 {
-  ButtonNotFoundError,
-  ImageNotFoundError,
-  VideoContainerNotFoundError,
-} from "./errors";
+import { ElementNotFoundError } from "./errors";
 import Recorder from "./recorder";
 
 declare const window: LookitWindow;
@@ -63,6 +59,11 @@ const info = <const>{
     consent_statement_text: { type: ParameterType.STRING, default: "" },
     omit_injury_phrase: { type: ParameterType.BOOL, default: false },
   },
+  data: {
+    chs_type: {
+      type: ParameterType.STRING,
+    },
+  },
 };
 type Info = typeof info;
 
@@ -71,6 +72,11 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
   public static readonly info = info;
   private readonly recorder: Recorder;
   private readonly video_container_id = "lookit-jspsych-video-container";
+  private readonly msg_container_id = "lookit-jspsych-video-msg-container";
+  private uploadingMsg: string | null = null;
+  private startingMsg: string | null = null;
+  private recordingMsg: string | null = null;
+  private notRecordingMsg: string | null = null;
 
   /**
    * Instantiate video consent plugin.
@@ -89,7 +95,7 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
    * @param trial - Trial data including user supplied parameters.
    */
   public trial(display: HTMLElement, trial: TrialType<Info>) {
-    // Get trial HTML string
+    // Get trial HTML string from templates package. This will also set the i18n locale.
     const consentVideo = chsTemplates.consentVideo(trial);
 
     // Add rendered document to display HTML
@@ -97,11 +103,26 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
 
     // Video recording HTML
     this.recordFeed(display);
+    // Set event listeners for buttons.
     this.recordButton(display);
     this.stopButton(display);
     this.playButton(display);
     this.nextButton(display);
+    // Translate and store any messages that may need to be shown. Locale has already been set via the chsTemplates consentVideo method.
+    this.uploadingMsg = chsTemplates.translateString(
+      "exp-lookit-video-consent.Stopping-and-uploading",
+    );
+    this.startingMsg = chsTemplates.translateString(
+      "exp-lookit-video-consent.Starting-recorder",
+    );
+    this.recordingMsg = chsTemplates.translateString(
+      "exp-lookit-video-consent.Recording",
+    );
+    this.notRecordingMsg = chsTemplates.translateString(
+      "exp-lookit-video-consent.Not-recording",
+    );
   }
+
   /**
    * Retrieve video container element.
    *
@@ -114,7 +135,7 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
     );
 
     if (!videoContainer) {
-      throw new VideoContainerNotFoundError();
+      throw new ElementNotFoundError(this.video_container_id, "div");
     }
 
     return videoContainer;
@@ -138,23 +159,59 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
    */
   private playbackFeed(display: HTMLElement) {
     const videoContainer = this.getVideoContainer(display);
-    this.recorder.insertPlaybackFeed(videoContainer, this.onEnded(display));
+    this.recorder.insertPlaybackFeed(
+      videoContainer,
+      this.onPlaybackEnded(display),
+    );
   }
 
   /**
-   * Put back the webcam feed once the video recording has ended. This is used
-   * with the "ended" Event.
+   * Get message container that appears alongside the video element.
+   *
+   * @param display - HTML element for experiment.
+   * @returns Message container div element.
+   */
+  private getMessageContainer(display: HTMLElement) {
+    const msgContainer = display.querySelector<HTMLDivElement>(
+      `div#${this.msg_container_id}`,
+    );
+
+    if (!msgContainer) {
+      throw new ElementNotFoundError(this.msg_container_id, "div");
+    }
+
+    return msgContainer;
+  }
+
+  /**
+   * Add HTML-formatted message alongside the video feed, e.g. for waiting
+   * periods during webcam feed transitions (starting, stopping/uploading). This
+   * will also replace an existing message with the new one. To clear any
+   * existing messages, pass an empty string.
+   *
+   * @param display - HTML element for experiment.
+   * @param message - HTML content for message div.
+   */
+  private addMessage(display: HTMLElement, message: string) {
+    const msgContainer = this.getMessageContainer(display);
+    msgContainer.innerHTML = message;
+  }
+
+  /**
+   * Put back the webcam feed once the video recording playback has ended. This
+   * is used with the "ended" Event.
    *
    * @param display - JsPsych display HTML element.
    * @returns Event function
    */
-  private onEnded(display: HTMLElement) {
+  private onPlaybackEnded(display: HTMLElement) {
     return () => {
       const next = this.getButton(display, "next");
       const play = this.getButton(display, "play");
       const record = this.getButton(display, "record");
 
       this.recordFeed(display);
+      this.addMessage(display, this.notRecordingMsg!);
       next.disabled = false;
       play.disabled = false;
       record.disabled = false;
@@ -174,7 +231,7 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
   ) {
     const btn = display.querySelector<HTMLButtonElement>(`button#${id}`);
     if (!btn) {
-      throw new ButtonNotFoundError(id);
+      throw new ElementNotFoundError(id, "button");
     }
     return btn;
   }
@@ -190,7 +247,7 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
     const img = display.querySelector<HTMLImageElement>(`img#${id}`);
 
     if (!img) {
-      throw new ImageNotFoundError(id);
+      throw new ElementNotFoundError(id, "img");
     }
 
     return img;
@@ -208,12 +265,14 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
     const next = this.getButton(display, "next");
 
     record.addEventListener("click", async () => {
+      this.addMessage(display, this.startingMsg!);
       record.disabled = true;
-      stop.disabled = false;
       play.disabled = true;
       next.disabled = true;
-      this.getImg(display, "record-icon").style.visibility = "visible";
       await this.recorder.start(true, VideoConsentPlugin.info.name);
+      this.getImg(display, "record-icon").style.visibility = "visible";
+      this.addMessage(display, this.recordingMsg!);
+      stop.disabled = false;
     });
   }
 
@@ -245,11 +304,13 @@ export class VideoConsentPlugin implements JsPsychPlugin<Info> {
 
     stop.addEventListener("click", async () => {
       stop.disabled = true;
-      record.disabled = false;
-      play.disabled = false;
-      await this.recorder.stop();
-      this.recorder.reset();
+      this.addMessage(display, this.uploadingMsg!);
+      await this.recorder.stop(true);
       this.recordFeed(display);
+      this.getImg(display, "record-icon").style.visibility = "hidden";
+      this.addMessage(display, this.notRecordingMsg!);
+      play.disabled = false;
+      record.disabled = false;
     });
   }
   /**

package/src/errors.ts

@@ -196,36 +196,16 @@ export class CreateURLError extends Error {
   }
 }
 
-/** Error thrown when video container couldn't be found. */
-export class VideoContainerNotFoundError extends Error {
-  /** No video container found. */
-  public constructor() {
-    super("Video Container could not be found.");
-    this.name = "VideoContainerError";
-  }
-}
-
-/** Error thrown when button not found. */
-export class ButtonNotFoundError extends Error {
+/** Error thrown when an HTML element is not found. */
+export class ElementNotFoundError extends Error {
   /**
-   * Button couldn't be found by ID field.
+   * Element couldn't be found by ID field.
    *
    * @param id - HTML ID parameter.
+   * @param tag - HTML tag of the element.
    */
-  public constructor(id: string) {
-    super(`"${id}" button not found.`);
-    this.name = "ButtonNotFoundError";
-  }
-}
-
-/** Throw Error when image couldn't be found. */
-export class ImageNotFoundError extends Error {
-  /**
-   * Error when image couldn't be found by ID field.
-   *
-   * @param id - HTML ID parameter
-   */
-  public constructor(id: string) {
-    super(`"${id}" image not found.`);
+  public constructor(id: string, tag: string) {
+    super(`"${id}" ${tag} not found.`);
+    this.name = "ElementNotFoundError";
   }
 }