@lookit/record 4.1.0 → 6.0.0

package/dist/index.d.ts

@@ -5,7 +5,8 @@ declare const info$3: {
     readonly version: string;
     readonly parameters: {
         readonly template: {
-            readonly type: ParameterType.STRING;
+            readonly type: ParameterType.SELECT;
+            readonly options: readonly ["consent-template-5", "consent-garden", "consent-recording-only"];
             readonly default: "consent-template-5";
         };
         readonly locale: {
@@ -131,6 +132,19 @@ declare const info$3: {
             readonly type: ParameterType.BOOL;
             readonly default: false;
         };
+        /**
+         * This parameter is only relevant for the consent-recording-only template.
+         * If a different template is used, this parameter will be ignored. Whether
+         * or not the consent trial is the only data being collected on CHS (i.e.
+         * the study redirects to an external URL immediately after the consent
+         * trial). If false (the default), the consent template contains information
+         * about how CHS handles data/responses. If true, any statements about
+         * session data/responses are omitted.
+         */
+        readonly only_consent_on_chs: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
     };
     readonly data: {
         readonly chs_type: {
@@ -147,7 +161,8 @@ declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
         readonly version: string;
         readonly parameters: {
             readonly template: {
-                readonly type: ParameterType.STRING;
+                readonly type: ParameterType.SELECT;
+                readonly options: readonly ["consent-template-5", "consent-garden", "consent-recording-only"];
                 readonly default: "consent-template-5";
             };
             readonly locale: {
@@ -273,6 +288,19 @@ declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
                 readonly type: ParameterType.BOOL;
                 readonly default: false;
             };
+            /**
+             * This parameter is only relevant for the consent-recording-only template.
+             * If a different template is used, this parameter will be ignored. Whether
+             * or not the consent trial is the only data being collected on CHS (i.e.
+             * the study redirects to an external URL immediately after the consent
+             * trial). If false (the default), the consent template contains information
+             * about how CHS handles data/responses. If true, any statements about
+             * session data/responses are omitted.
+             */
+            readonly only_consent_on_chs: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
         };
         readonly data: {
             readonly chs_type: {
@@ -404,7 +432,30 @@ declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
 declare const info$2: {
     readonly name: "start-record-plugin";
     readonly version: string;
-    readonly parameters: {};
+    readonly parameters: {
+        /**
+         * This string can contain HTML markup. Any content provided will be
+         * displayed while the video recording connection is established. If null
+         * (the default), then the default 'establishing video connection, please
+         * wait' (or appropriate translation based on 'locale') will be displayed.
+         * Use a blank string for no message/content.
+         */
+        readonly wait_for_connection_message: {
+            readonly type: ParameterType.HTML_STRING;
+            readonly default: string | null;
+        };
+        /**
+         * Locale code used for translating the default 'establishing video
+         * connection, 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_connection_message' parameter is specified then this value
+         * is ignored.
+         */
+        readonly locale: {
+            readonly type: ParameterType.STRING;
+            readonly default: "en-us";
+        };
+    };
     readonly data: {};
 };
 type Info$2 = typeof info$2;
@@ -414,7 +465,30 @@ declare class StartRecordPlugin implements JsPsychPlugin<Info$2> {
     static readonly info: {
         readonly name: "start-record-plugin";
         readonly version: string;
-        readonly parameters: {};
+        readonly parameters: {
+            /**
+             * This string can contain HTML markup. Any content provided will be
+             * displayed while the video recording connection is established. If null
+             * (the default), then the default 'establishing video connection, please
+             * wait' (or appropriate translation based on 'locale') will be displayed.
+             * Use a blank string for no message/content.
+             */
+            readonly wait_for_connection_message: {
+                readonly type: ParameterType.HTML_STRING;
+                readonly default: string | null;
+            };
+            /**
+             * Locale code used for translating the default 'establishing video
+             * connection, 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_connection_message' parameter is specified then this value
+             * is ignored.
+             */
+            readonly locale: {
+                readonly type: ParameterType.STRING;
+                readonly default: "en-us";
+            };
+        };
         readonly data: {};
     };
     private recorder;
@@ -424,8 +498,15 @@ declare class StartRecordPlugin implements JsPsychPlugin<Info$2> {
      * @param jsPsych - Object provided by jsPsych.
      */
     constructor(jsPsych: JsPsych);
-    /** Trial function called by jsPsych. */
-    trial(): void;
+    /**
+     * Trial function called by jsPsych.
+     *
+     * @param display_element - DOM element where jsPsych content is being
+     *   rendered (set in initJsPsych and automatically made available to a
+     *   plugin's trial method via jsPsych core).
+     * @param trial - Trial object with parameters/values.
+     */
+    trial(display_element: HTMLElement, trial: TrialType<Info$2>): Promise<void>;
 }
 
 declare const info$1: {
@@ -454,6 +535,14 @@ declare const info$1: {
             readonly type: ParameterType.STRING;
             readonly default: "en-us";
         };
+        /**
+         * Maximum duration (in seconds) to wait for the session recording to finish
+         * uploading before continuing with the experiment.
+         */
+        readonly max_upload_seconds: {
+            readonly type: ParameterType.INT;
+            readonly default: 10;
+        };
     };
     readonly data: {};
 };
@@ -487,6 +576,14 @@ declare class StopRecordPlugin implements JsPsychPlugin<Info$1> {
                 readonly type: ParameterType.STRING;
                 readonly default: "en-us";
             };
+            /**
+             * Maximum duration (in seconds) to wait for the session recording to finish
+             * uploading before continuing with the experiment.
+             */
+            readonly max_upload_seconds: {
+                readonly type: ParameterType.INT;
+                readonly default: 10;
+            };
         };
         readonly data: {};
     };
@@ -505,7 +602,7 @@ declare class StopRecordPlugin implements JsPsychPlugin<Info$1> {
      *   plugin's trial method via jsPsych core).
      * @param trial - Trial object with parameters/values.
      */
-    trial(display_element: HTMLElement, trial: TrialType<Info$1>): void;
+    trial(display_element: HTMLElement, trial: TrialType<Info$1>): Promise<void>;
 }
 
 interface Parameters {
@@ -526,12 +623,18 @@ interface Parameters {
      * 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.
+     * 'wait_for_upload_message' parameter is specified then this value is
+     * ignored.
      *
      * @default "en-us"
      */
     locale?: string;
+    /**
+     * Maximum duration (in seconds) to wait for the trial recording to finish
+     * uploading before continuing with the experiment. Default is 10 seconds (set
+     * during initialize).
+     */
+    max_upload_seconds?: null | number;
 }
 /** This extension allows researchers to record webcam audio/video during trials. */
 declare class TrialRecordExtension implements JsPsychExtension {
@@ -541,6 +644,7 @@ declare class TrialRecordExtension implements JsPsychExtension {
     private pluginName;
     private uploadMsg;
     private locale;
+    private maxUploadSeconds;
     /**
      * Video recording extension.
      *

package/dist/index.js

@@ -6,7 +6,7 @@ import Handlebars from 'handlebars';
 
 var _package = {
   name: "@lookit/record",
-  version: "4.1.0",
+  version: "6.0.0",
   description: "Recording extensions and plugins for CHS studies.",
   homepage: "https://github.com/lookit/lookit-jspsych#readme",
   bugs: {
@@ -47,8 +47,8 @@ var _package = {
     typescript: "^5.6.2"
   },
   peerDependencies: {
-    "@lookit/data": "^0.2.0",
-    "@lookit/templates": "^2.1.0",
+    "@lookit/data": "^0.3.0",
+    "@lookit/templates": "^3.1.0",
     jspsych: "^8.0.3"
   }
 };
@@ -123,6 +123,12 @@ class S3UndefinedError extends Error {
     this.name = "S3UndefinedError";
   }
 }
+class NoFileNameError extends Error {
+  constructor() {
+    super("No filename found for recording.");
+    this.name = "NoFileNameError";
+  }
+}
 class StreamActiveOnResetError extends Error {
   constructor() {
     super("Won't reset recorder. Stream is still active.");
@@ -147,6 +153,12 @@ class ElementNotFoundError extends Error {
     this.name = "ElementNotFoundError";
   }
 }
+class TimeoutError extends Error {
+  constructor(msg) {
+    super(`${msg}`);
+    this.name = "TimeoutError";
+  }
+}
 
 var playbackFeed = "<video\n  autoplay\n  playsinline\n  src=\"{{{src}}}\"\n  class=\"webcam-feed\"\n  id=\"{{webcam_element_id}}\"\n  width=\"{{width}}\"\n  height=\"{{height}}\"\n  controls\n></video>";
 
@@ -158,6 +170,31 @@ var img$8 = "data:image/svg+xml,%3c%3fxml version='1.0' encoding='utf-8' %3f%3e%
 
 var img$7 = "data:image/svg+xml,%3c%3fxml version='1.0' encoding='utf-8' %3f%3e%3csvg viewBox='-1 -1 18 18' xmlns='http://www.w3.org/2000/svg'%3e %3ccircle fill='red' stroke='black' stroke-width='0.5' cx='8' cy='8' r='8'%3e%3c/circle%3e%3c/svg%3e";
 
+const promiseWithTimeout = (promise, promiseId, timeoutMs, onTimeoutCleanup) => {
+  let timeoutHandle;
+  const timeout = new Promise((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      onTimeoutCleanup?.();
+      resolve("timeout");
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeout]).then(
+    (value) => {
+      if (value == "timeout") {
+        console.log(`Upload for ${promiseId} timed out.`);
+      } else {
+        console.log(`Upload for ${promiseId} completed.`);
+        clearTimeout(timeoutHandle);
+      }
+      return value;
+    },
+    (err) => {
+      clearTimeout(timeoutHandle);
+      throw err;
+    }
+  );
+};
+
 class Recorder {
   constructor(jsPsych) {
     this.jsPsych = jsPsych;
@@ -257,13 +294,73 @@ class Recorder {
     this.recorder.stop();
     this.stream.getTracks().map((t) => t.stop());
   }
-  stop(maintain_container_size = false) {
+  stop({
+    maintain_container_size = false,
+    stop_timeout_ms = null,
+    upload_timeout_ms = 1e4
+  } = {}) {
+    this.preStopCheck();
     this.clearWebcamFeed(maintain_container_size);
     this.stopTracks();
-    if (!this.stopPromise) {
-      throw new NoStopPromiseError();
-    }
-    return this.stopPromise;
+    const snapshot = {
+      s3: !this.localDownload ? this.s3 : null,
+      filename: this.filename,
+      localDownload: this.localDownload,
+      url: "null"
+    };
+    const stopped = stop_timeout_ms ? promiseWithTimeout(
+      this.stopPromise,
+      `${snapshot.filename}-stopped`,
+      stop_timeout_ms,
+      this.createTimeoutHandler("stop", snapshot.filename)
+    ) : this.stopPromise;
+    stopped.finally(() => {
+      try {
+        this.reset();
+      } catch (err) {
+        console.error("Error while resetting recorder after stop: ", err);
+      }
+    });
+    const uploadPromise = (async () => {
+      let url;
+      try {
+        url = await stopped;
+        if (url == "timeout") {
+          throw new TimeoutError("Recorder stop timed out.");
+        }
+      } catch (err) {
+        console.warn("Upload failed because recorder stop timed out");
+        throw err;
+      }
+      snapshot.url = url;
+      if (snapshot.localDownload) {
+        try {
+          this.download(snapshot.filename, snapshot.url);
+          await Promise.resolve();
+        } catch (err) {
+          console.error("Local download failed: ", err);
+          throw err;
+        }
+      } else {
+        try {
+          await snapshot.s3.completeUpload();
+        } catch (err) {
+          console.error("Upload failed: ", err);
+          throw err;
+        }
+      }
+    })();
+    const uploaded = upload_timeout_ms ? promiseWithTimeout(
+      uploadPromise,
+      `${snapshot.filename}-uploaded`,
+      upload_timeout_ms,
+      this.createTimeoutHandler("upload", snapshot.filename)
+    ) : uploadPromise;
+    window.chs.pendingUploads.push({
+      promise: uploadPromise,
+      file: snapshot.filename
+    });
+    return { stopped, uploaded };
   }
   initializeCheck() {
     if (!this.recorder) {
@@ -276,19 +373,27 @@ class Recorder {
       throw new StreamDataInitializeError();
     }
   }
+  preStopCheck() {
+    if (!this.recorder) {
+      throw new RecorderInitializeError();
+    }
+    if (!this.stream.active) {
+      throw new StreamInactiveInitializeError();
+    }
+    if (!this.stopPromise) {
+      throw new NoStopPromiseError();
+    }
+    if (!this.filename) {
+      throw new NoFileNameError();
+    }
+  }
   handleStop(resolve) {
-    return async () => {
+    return () => {
       if (this.blobs.length === 0) {
         throw new CreateURLError();
       }
       this.url = URL.createObjectURL(new Blob(this.blobs));
-      if (this.localDownload) {
-        this.download();
-      } else {
-        await this.s3.completeUpload();
-      }
-      this.reset();
-      resolve();
+      resolve(this.url);
     };
   }
   handleDataAvailable(event) {
@@ -297,11 +402,11 @@ class Recorder {
       this.s3.onDataAvailable(event.data);
     }
   }
-  download() {
-    if (this.filename && this.url) {
+  download(filename, url) {
+    if (filename && url) {
       const link = document.createElement("a");
-      link.href = this.url;
-      link.download = this.filename;
+      link.href = url;
+      link.download = filename;
       link.click();
     }
   }
@@ -330,13 +435,33 @@ class Recorder {
     const rand_digits = Math.floor(Math.random() * 1e3);
     return `${prefix}_${window.chs.study.id}_${trial_id}_${window.chs.response.id}_${new Date().getTime()}_${rand_digits}.webm`;
   }
+  createTimeoutHandler(eventName, id) {
+    return () => {
+      console.warn(`Recorder ${eventName} timed out: ${id}`);
+      if (!this.stream.active) {
+        try {
+          this.reset();
+        } catch (err) {
+          console.error("Error while resetting recorder after timeout: ", err);
+        }
+      }
+    };
+  }
 }
 
 const info$3 = {
   name: "consent-video",
   version: _package.version,
   parameters: {
-    template: { type: ParameterType.STRING, default: "consent-template-5" },
+    template: {
+      type: ParameterType.SELECT,
+      options: [
+        "consent-template-5",
+        "consent-garden",
+        "consent-recording-only"
+      ],
+      default: "consent-template-5"
+    },
     locale: { type: ParameterType.STRING, default: "en-us" },
     additional_video_privacy_statement: {
       type: ParameterType.STRING,
@@ -381,7 +506,8 @@ const info$3 = {
     prompt_all_adults: { type: ParameterType.BOOL, default: false },
     prompt_only_adults: { type: ParameterType.BOOL, default: false },
     consent_statement_text: { type: ParameterType.STRING, default: "" },
-    omit_injury_phrase: { type: ParameterType.BOOL, default: false }
+    omit_injury_phrase: { type: ParameterType.BOOL, default: false },
+    only_consent_on_chs: { type: ParameterType.BOOL, default: false }
   },
   data: {
     chs_type: {
@@ -514,7 +640,10 @@ const _VideoConsentPlugin = class {
     stop.addEventListener("click", async () => {
       stop.disabled = true;
       this.addMessage(display, this.uploadingMsg);
-      await this.recorder.stop(true);
+      const { stopped, uploaded } = this.recorder.stop({
+        maintain_container_size: true
+      });
+      await stopped;
       this.recordFeed(display);
       this.getImg(display, "record-icon").style.visibility = "hidden";
       this.addMessage(display, this.notRecordingMsg);
@@ -542,7 +671,16 @@ VideoConsentPlugin.info = info$3;
 const info$2 = {
   name: "start-record-plugin",
   version: _package.version,
-  parameters: {},
+  parameters: {
+    wait_for_connection_message: {
+      type: ParameterType.HTML_STRING,
+      default: null
+    },
+    locale: {
+      type: ParameterType.STRING,
+      default: "en-us"
+    }
+  },
   data: {}
 };
 const _StartRecordPlugin = class {
@@ -555,8 +693,14 @@ const _StartRecordPlugin = class {
       throw new ExistingRecordingError();
     }
   }
-  trial() {
-    this.recorder.start(false, `${_StartRecordPlugin.info.name}-multiframe`).then(() => {
+  async trial(display_element, trial) {
+    if (trial.wait_for_connection_message == null) {
+      display_element.innerHTML = chsTemplates.establishingConnection(trial);
+    } else {
+      display_element.innerHTML = trial.wait_for_connection_message;
+    }
+    await this.recorder.start(false, `${_StartRecordPlugin.info.name}-multiframe`).then(() => {
+      display_element.innerHTML = "";
       this.jsPsych.finishTrial();
     });
   }
@@ -575,6 +719,10 @@ const info$1 = {
     locale: {
       type: ParameterType.STRING,
       default: "en-us"
+    },
+    max_upload_seconds: {
+      type: ParameterType.INT,
+      default: 10
     }
   },
   data: {}
@@ -588,19 +736,25 @@ class StopRecordPlugin {
       throw new NoSessionRecordingError();
     }
   }
-  trial(display_element, trial) {
+  async trial(display_element, trial) {
     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(() => {
+    const { stopped, uploaded } = this.recorder.stop({
+      upload_timeout_ms: trial.max_upload_seconds !== null ? trial.max_upload_seconds * 1e3 : null
+    });
+    try {
+      await stopped;
+      await uploaded;
+    } catch (err) {
+      console.error("StopRecordPlugin: recorder stop/upload failed.", err);
+    } finally {
       window.chs.sessionRecorder = null;
       display_element.innerHTML = "";
       this.jsPsych.finishTrial();
-    }).catch((err) => {
-      console.error("StopRecordPlugin: recorder stop/upload failed.", err);
-    });
+    }
   }
 }
 StopRecordPlugin.info = info$1;
@@ -610,14 +764,14 @@ class TrialRecordExtension {
     this.jsPsych = jsPsych;
     this.uploadMsg = null;
     this.locale = "en-us";
+    this.maxUploadSeconds = void 0;
     autoBind(this);
   }
   async initialize(params) {
     await new Promise((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);
+      this.maxUploadSeconds = params?.max_upload_seconds === void 0 ? 10 : params.max_upload_seconds;
       resolve();
     });
   }
@@ -628,13 +782,14 @@ class TrialRecordExtension {
     if (startParams?.locale) {
       this.locale = startParams.locale;
     }
-    console.log(this.uploadMsg);
-    console.log(this.locale);
+    if (startParams?.max_upload_seconds !== void 0) {
+      this.maxUploadSeconds = startParams?.max_upload_seconds;
+    }
     this.recorder = new Recorder(this.jsPsych);
+    this.pluginName = this.getCurrentPluginName();
+    this.recorder.start(false, `${this.pluginName}`);
   }
   on_load() {
-    this.pluginName = this.getCurrentPluginName();
-    this.recorder?.start(false, `${this.pluginName}`);
   }
   async on_finish() {
     const displayEl = this.jsPsych.getDisplayElement();
@@ -646,13 +801,27 @@ class TrialRecordExtension {
     } else {
       displayEl.innerHTML = this.uploadMsg;
     }
-    try {
-      await this.recorder?.stop();
+    if (this.recorder) {
+      const { stopped, uploaded } = this.recorder.stop({
+        upload_timeout_ms: this.maxUploadSeconds !== null ? this.maxUploadSeconds * 1e3 : null
+      });
+      try {
+        await stopped;
+        await uploaded;
+        displayEl.innerHTML = "";
+        return {};
+      } catch (err) {
+        console.error(
+          "TrialRecordExtension: recorder stop/upload failed.",
+          err
+        );
+        displayEl.innerHTML = "";
+        return {};
+      }
+    } else {
       displayEl.innerHTML = "";
-    } catch (err) {
-      console.error("TrialRecordExtension: recorder stop/upload failed.", err);
+      return {};
     }
-    return {};
   }
   getCurrentPluginName() {
     const current_plugin_class = this.jsPsych.getCurrentTrial().type;