@lookit/record 0.0.3

package/src/errors.ts

@@ -0,0 +1,243 @@
+/** Error thrown when recorder is null. */
+export class RecorderInitializeError extends Error {
+  /**
+   * When there isn't a recorder, provide the user with an explanation of what
+   * they could do to resolve the issue.
+   */
+  public constructor() {
+    const message = "Neither camera nor microphone has been initialized.";
+    super(message);
+    this.name = "RecorderInitializeError";
+  }
+}
+
+/** Error thrown when stream is inactive and recorder is started. */
+export class StreamInactiveInitializeError extends Error {
+  /**
+   * Error check on initialize. Attempting to validate recorder is ready to
+   * start recording.
+   */
+  public constructor() {
+    super(
+      "Stream is inactive when attempting to start recording.  Recorder reset might be needed.",
+    );
+    this.name = "StreamInactiveInitializeError";
+  }
+}
+
+/** Error thrown when stream data is available and recorder is started. */
+export class StreamDataInitializeError extends Error {
+  /**
+   * Error check on recorder initialize. Attempt to validate recorder data array
+   * is empty and ready to start recording.
+   */
+  public constructor() {
+    super(
+      "Stream data from another recording still available when attempting to start recording.  Recorder reset might be needed. ",
+    );
+    this.name = "StreamDataInitializeError";
+  }
+}
+
+/**
+ * Error thrown when trying to stop an active session recording that cannot be
+ * found.
+ */
+export class NoSessionRecordingError extends Error {
+  /**
+   * When trying to stop a recording that isn't found, provide the user with an
+   * explanation of what they could do to resolve the issue.
+   */
+  public constructor() {
+    const message =
+      "Cannot stop a session recording because no active session recording was found. Maybe it needs to be started, or there was a problem starting the recording.";
+    super(message);
+    this.name = "NoSessionRecordingError";
+  }
+}
+
+/**
+ * Error thrown when trying to trying to start a recording while another is
+ * already active.
+ */
+export class ExistingRecordingError extends Error {
+  /**
+   * When trying to start a recording but there is already an active recording
+   * in progress, provide the user with an explanation of what they could do to
+   * resolve the issue.
+   */
+  public constructor() {
+    const message =
+      "Cannot start a new recording because an active recording was found. Maybe a session recording needs to be stopped, trial recording is being used during session recording, or there was a problem stopping a prior recording.";
+    super(message);
+    this.name = "ExistingRecordingError";
+  }
+}
+
+/**
+ * Error thrown when trying to to stop the recorder and the stop promise doesn't
+ * exist.
+ */
+export class NoStopPromiseError extends Error {
+  /**
+   * When attempting to stop a recording but there's no stop promise to ensure
+   * the stop has completed.
+   */
+  public constructor() {
+    const message =
+      "There is no Stop Promise, which means the recorder wasn't started properly.";
+    super(message);
+    this.name = "NoStopPromiseError";
+  }
+}
+
+/**
+ * Error thrown when attempting an action that relies on an input stream, such
+ * as the mic volume check, but no such stream is found.
+ */
+export class NoStreamError extends Error {
+  /**
+   * When attempting an action that requires an input stream, such as the mic
+   * check, but no stream is found.
+   */
+  public constructor() {
+    const message =
+      "No input stream found. Maybe the recorder was not initialized with initializeRecorder.";
+    super(message);
+    this.name = "NoStreamError";
+  }
+}
+
+/**
+ * Error thrown if there's a problem setting up the microphone input level
+ * check.
+ */
+export class MicCheckError extends Error {
+  /**
+   * Occurs if there's a problem setting up the mic check, including setting up
+   * the audio context and stream source, loading the audio worklet processor
+   * script, setting up the port message event handler, and resolving the
+   * promise chain via message events passed to onMicActivityLevel.
+   *
+   * @param err - Error passed into this error that is thrown in the catch
+   *   block, if any. Errors passed to catch blocks must have type unknown.
+   */
+  public constructor(err: unknown) {
+    let message = `There was a problem setting up and running the microphone check.`;
+    if (
+      err instanceof Object &&
+      "message" in err &&
+      typeof err.message === "string"
+    ) {
+      message += ` ${err.message}`;
+    }
+    if (typeof err === "string") {
+      message += ` ${err}`;
+    }
+    super(message);
+    this.name = "MicCheckError";
+  }
+}
+
+/**
+ * Error thrown when attempting to access S3 object and it's, unknowingly,
+ * undefined.
+ */
+export class S3UndefinedError extends Error {
+  /**
+   * Provide feed back when recorder attempts to use S3 object and it's
+   * undefined.
+   */
+  public constructor() {
+    super("S3 object is undefined.");
+    this.name = "S3UndefinedError";
+  }
+}
+
+/**
+ * Error thrown when attempting to reset recorder, but its stream is still
+ * active.
+ */
+export class StreamActiveOnResetError extends Error {
+  /**
+   * This error will be thrown when developer attempts to reset recorder while
+   * active.
+   */
+  public constructor() {
+    super("Won't reset recorder. Stream is still active.");
+    this.name = "StreamActiveOnResetError";
+  }
+}
+
+/** Error thrown when attempting to select webcam element and it's not found. */
+export class NoWebCamElementError extends Error {
+  /**
+   * Error thrown when attempting to retrieve webcam element and it's not in the
+   * DOM.
+   */
+  public constructor() {
+    super("No webcam element found.");
+    this.name = "NoWebCamElementError";
+  }
+}
+
+/**
+ * Error thrown when attempting to create playback/download url and data array
+ * is empty.
+ */
+export class CreateURLError extends Error {
+  /**
+   * Throw this error when data array is empty and url still needs to be
+   * created. Sometimes this means the "reset()" method was called too early.
+   */
+  public constructor() {
+    super("Video/audio URL couldn't be created.  No data available.");
+    this.name = "CreateURLError";
+  }
+}
+
+/** 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 {
+  /**
+   * Button couldn't be found by ID field.
+   *
+   * @param id - HTML ID parameter.
+   */
+  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.`);
+  }
+}
+
+/** Error throw what specified language isn't found */
+export class TranslationNotFoundError extends Error {
+  /**
+   * This will be thrown when attempting to init i18n
+   *
+   * @param baseName - Language a2code with region
+   */
+  public constructor(baseName: string) {
+    super(`"${baseName}" translation not found.`);
+  }
+}

package/src/img-import.d.ts

@@ -0,0 +1 @@
+declare module "*.png";

package/src/index.spec.ts

@@ -0,0 +1,104 @@
+import { LookitWindow } from "@lookit/data/dist/types";
+import { initJsPsych } from "jspsych";
+import { ExistingRecordingError, NoSessionRecordingError } from "./errors";
+import Rec from "./index";
+import Recorder from "./recorder";
+
+declare const window: LookitWindow;
+
+jest.mock("./recorder");
+jest.mock("@lookit/data");
+jest.mock("jspsych", () => ({
+  ...jest.requireActual("jspsych"),
+  initJsPsych: jest
+    .fn()
+    .mockReturnValue({ finishTrial: jest.fn().mockImplementation() }),
+}));
+
+/**
+ * Manual mock to set up window.chs value for testing.
+ *
+ * @param chs - Contents of chs storage.
+ */
+const setCHSValue = (chs = {}) => {
+  Object.defineProperty(global, "window", {
+    value: {
+      chs,
+    },
+  });
+};
+
+beforeEach(() => {
+  setCHSValue();
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+test("Trial recording", () => {
+  const mockRecStart = jest.spyOn(Recorder.prototype, "start");
+  const mockRecStop = jest.spyOn(Recorder.prototype, "stop");
+  const jsPsych = initJsPsych();
+  const trialRec = new Rec.TrialRecordExtension(jsPsych);
+
+  trialRec.on_start();
+  trialRec.on_load();
+  trialRec.on_finish();
+
+  expect(Recorder).toHaveBeenCalledTimes(1);
+  expect(mockRecStart).toHaveBeenCalledTimes(1);
+  expect(mockRecStop).toHaveBeenCalledTimes(1);
+});
+
+test("Trial recording's initialize does nothing", async () => {
+  const jsPsych = initJsPsych();
+  const trialRec = new Rec.TrialRecordExtension(jsPsych);
+
+  expect(await trialRec.initialize()).toBeUndefined();
+  expect(Recorder).toHaveBeenCalledTimes(0);
+});
+
+test("Start Recording", async () => {
+  const mockRecStart = jest.spyOn(Recorder.prototype, "start");
+  const jsPsych = initJsPsych();
+  const startRec = new Rec.StartRecordPlugin(jsPsych);
+
+  // manual mock
+  mockRecStart.mockImplementation(jest.fn().mockReturnValue(Promise.resolve()));
+
+  await startRec.trial();
+
+  expect(jsPsych.finishTrial).toHaveBeenCalledTimes(1);
+  expect(() => {
+    new Rec.StartRecordPlugin(jsPsych);
+  }).toThrow(ExistingRecordingError);
+});
+
+test("Stop Recording", async () => {
+  const mockRecStop = jest.spyOn(Recorder.prototype, "stop");
+  const jsPsych = initJsPsych();
+
+  setCHSValue({
+    sessionRecorder: new Recorder(jsPsych),
+  });
+
+  const stopRec = new Rec.StopRecordPlugin(jsPsych);
+  const display_element = jest
+    .fn()
+    .mockImplementation() as unknown as HTMLElement;
+
+  mockRecStop.mockImplementation(jest.fn().mockReturnValue(Promise.resolve()));
+
+  await stopRec.trial(display_element);
+
+  expect(jsPsych.finishTrial).toHaveBeenCalledTimes(1);
+  expect(window.chs.sessionRecorder).toBeNull();
+  expect(display_element.innerHTML).toStrictEqual("");
+
+  setCHSValue();
+
+  expect(async () => await new Rec.StopRecordPlugin(jsPsych)).rejects.toThrow(
+    NoSessionRecordingError,
+  );
+});

package/src/index.ts

@@ -0,0 +1,13 @@
+import { VideoConsentPlugin } from "./consentVideo";
+import StartRecordPlugin from "./start";
+import StopRecordPlugin from "./stop";
+import TrialRecordExtension from "./trial";
+import VideoConfigPlugin from "./video_config";
+
+export default {
+  TrialRecordExtension,
+  StartRecordPlugin,
+  StopRecordPlugin,
+  VideoConfigPlugin,
+  VideoConsentPlugin,
+};

package/src/mic_check.d.ts

@@ -0,0 +1 @@
+declare module "*";

package/src/mic_check.js

@@ -0,0 +1,74 @@
+const SMOOTHING_FACTOR = 0.99;
+const SCALING_FACTOR = 5;
+/**
+ * Audio Worklet Processor class for processing audio input streams. This is
+ * used by the Recorder to run a volume check on the microphone input stream.
+ * Source:
+ * https://www.webrtc-developers.com/how-to-know-if-my-microphone-works/#detect-noise-or-silence
+ */
+export default class MicCheckProcessor extends AudioWorkletProcessor {
+  _volume;
+  _micChecked;
+  /** Constructor for the mic check processor. */
+  constructor() {
+    super();
+    this._volume = 0;
+    this._micChecked = false;
+    /**
+     * Callback to handle a message event on the processor's port. This
+     * determines how the processor responds when the recorder posts a message
+     * to the processor with e.g. this.processorNode.port.postMessage({
+     * micChecked: true }).
+     *
+     * @param event - Message event generated from the 'postMessage' call, which
+     *   includes, among other things, the data property.
+     * @param event.data - Data sent by the message emitter.
+     */
+    this.port.onmessage = (event) => {
+      if (
+        event.data &&
+        event.data.micChecked &&
+        event.data.micChecked == true
+      ) {
+        this._micChecked = true;
+      }
+    };
+  }
+  /**
+   * Process method that implements the audio processing algorithm for the Audio
+   * Processor Worklet. "Although the method is not a part of the
+   * AudioWorkletProcessor interface, any implementation of
+   * AudioWorkletProcessor must provide a process() method." Source:
+   * https://developer.mozilla.org/en-US/docs/Web/API/AudioWorkletProcessor/process
+   * The process method can take the following arguments: inputs, outputs,
+   * parameters. Here we are only using inputs.
+   *
+   * @param inputs - An array of inputs from the audio stream (microphone)
+   *   connnected to the node. Each item in the inputs array is an array of
+   *   channels. Each channel is a Float32Array containing 128 samples. For
+   *   example, inputs[n][m][i] will access n-th input, m-th channel of that
+   *   input, and i-th sample of that channel.
+   * @returns Boolean indicating whether or not the Audio Worklet Node should
+   *   remain active, even if the User Agent thinks it is safe to shut down. In
+   *   this case, when the recorder decides that the mic check criteria has been
+   *   met, it will return false (processor should be shut down), otherwise it
+   *   will return true (processor should remain active).
+   */
+  process(inputs) {
+    if (this._micChecked) {
+      return false;
+    } else {
+      const input = inputs[0];
+      const samples = input[0];
+      if (samples) {
+        const sumSquare = samples.reduce((p, c) => p + c * c, 0);
+        const rms =
+          Math.sqrt(sumSquare / (samples.length || 1)) * SCALING_FACTOR;
+        this._volume = Math.max(rms, this._volume * SMOOTHING_FACTOR);
+        this.port.postMessage({ volume: this._volume });
+      }
+      return true;
+    }
+  }
+}
+registerProcessor("mic-check-processor", MicCheckProcessor);

package/src/mic_check.ts

@@ -0,0 +1,77 @@
+const SMOOTHING_FACTOR = 0.99;
+const SCALING_FACTOR = 5;
+
+/**
+ * Audio Worklet Processor class for processing audio input streams. This is
+ * used by the Recorder to run a volume check on the microphone input stream.
+ * Source:
+ * https://www.webrtc-developers.com/how-to-know-if-my-microphone-works/#detect-noise-or-silence
+ */
+export default class MicCheckProcessor extends AudioWorkletProcessor {
+  private _volume: number;
+  private _micChecked: boolean;
+  /** Constructor for the mic check processor. */
+  public constructor() {
+    super();
+    this._volume = 0;
+    this._micChecked = false;
+    /**
+     * Callback to handle a message event on the processor's port. This
+     * determines how the processor responds when the recorder posts a message
+     * to the processor with e.g. this.processorNode.port.postMessage({
+     * micChecked: true }).
+     *
+     * @param event - Message event generated from the 'postMessage' call, which
+     *   includes, among other things, the data property.
+     * @param event.data - Data sent by the message emitter.
+     */
+    this.port.onmessage = (event: MessageEvent) => {
+      if (
+        event.data &&
+        event.data.micChecked &&
+        event.data.micChecked == true
+      ) {
+        this._micChecked = true;
+      }
+    };
+  }
+
+  /**
+   * Process method that implements the audio processing algorithm for the Audio
+   * Processor Worklet. "Although the method is not a part of the
+   * AudioWorkletProcessor interface, any implementation of
+   * AudioWorkletProcessor must provide a process() method." Source:
+   * https://developer.mozilla.org/en-US/docs/Web/API/AudioWorkletProcessor/process
+   * The process method can take the following arguments: inputs, outputs,
+   * parameters. Here we are only using inputs.
+   *
+   * @param inputs - An array of inputs from the audio stream (microphone)
+   *   connnected to the node. Each item in the inputs array is an array of
+   *   channels. Each channel is a Float32Array containing 128 samples. For
+   *   example, inputs[n][m][i] will access n-th input, m-th channel of that
+   *   input, and i-th sample of that channel.
+   * @returns Boolean indicating whether or not the Audio Worklet Node should
+   *   remain active, even if the User Agent thinks it is safe to shut down. In
+   *   this case, when the recorder decides that the mic check criteria has been
+   *   met, it will return false (processor should be shut down), otherwise it
+   *   will return true (processor should remain active).
+   */
+  public process(inputs: Float32Array[][]) {
+    if (this._micChecked) {
+      return false;
+    } else {
+      const input = inputs[0];
+      const samples = input[0];
+      if (samples) {
+        const sumSquare = samples.reduce((p, c) => p + c * c, 0);
+        const rms =
+          Math.sqrt(sumSquare / (samples.length || 1)) * SCALING_FACTOR;
+        this._volume = Math.max(rms, this._volume * SMOOTHING_FACTOR);
+        this.port.postMessage({ volume: this._volume });
+      }
+      return true;
+    }
+  }
+}
+
+registerProcessor("mic-check-processor", MicCheckProcessor);