@lookit/record 4.0.0 → 5.0.0

package/README.md

@@ -356,9 +356,28 @@ To use the CHS trial recording extension, you need to:
 
 ### Parameters
 
-This extension does not accept any parameters.
+**`wait_for_upload_message` [`null` or HTML string | `null` ]**
 
-### Example
+This parameter determines what content should be displayed while the trial
+recording is uploading. If `null` (the default), then the message 'uploading
+video, please wait...' (or appropriate translation based on `locale`) will be
+displayed. 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](https://www.jspsych.org/latest/overview/media-preloading/#manual-preloading).
+Use a blank string (`""`) for no message/content. If a value is provided then
+the `locale` parameter will be ignored.
+
+**`max_upload_seconds` [ Integer | 10 ]**
+
+Maximum duration (in seconds) to wait for the trial recording to finish
+uploading before continuing with the experiment. If the maximum upload duration
+is reached and the upload has not finished, then the experiment will move on and
+the trial recording upload will continue in the background.
+
+### Examples
+
+**Basic usage**
 
 To record a single trial, you will have to first load the extension in
 `initJsPsych`.
@@ -375,7 +394,7 @@ record any trial you design.
 
 ```javascript
 const trialRec = {
-  // ... Other trial paramters ...
+  // ... Other trial parameters ...
   extensions: [{ type: chsRecord.TrialRecordExtension }],
 };
 ```
@@ -386,6 +405,81 @@ Finally, insert the trials into the timeline.
 jsPsych.run([videoConfig, trialRec]);
 ```
 
+**Setting parameters**
+
+You can set the trial extension parameters when you load the extension with
+`initJsPsych`.
+
+In the example below, the default "uploading video, please wait..." message will
+be displayed in French while a trial recording is uploading at the end of the
+trial.
+
+```javascript
+const jsPsych = initJsPsych({
+  extensions: [
+    {
+      type: chsRecord.TrialRecordExtension,
+      params: { locale: "fr" },
+    },
+  ],
+});
+```
+
+And in this example, the custom message "Please wait!" will be displayed while
+the trial recording is uploading. You can include any HTML-formatted content in
+this string, which means you can display images, videos, animations etc.
+
+```javascript
+const jsPsych = initJsPsych({
+  extensions: [
+    {
+      type: chsRecord.TrialRecordExtension,
+      params: { wait_for_upload_message: "<div>Please wait!</div>" },
+    },
+  ],
+});
+```
+
+You can also set the parameters within individual trials. This will override any
+parameters set during the extension initialization (in `initJsPsych`), which can
+be useful if you want to change the parameter values during the experiment. In
+this example, the `wait_for_upload_message` is set to an empty string, which
+will prevent the default "uploading video, please wait..." message from
+appearing after the trial finishes.
+
+```javascript
+const trialRec = {
+  // ... Other trial parameters ...
+  extensions: [
+    {
+      type: chsRecord.TrialRecordExtension,
+      params: { wait_for_upload_message: "" },
+    },
+  ],
+};
+```
+
+By default, the trial recording extension will wait up to 10 seconds for the
+recording to finish uploading before moving on to the next trial. If the upload
+does not finish in that time, it will continue to upload in the background. You
+can adjust this duration with the `max_upload_seconds` parameter. You may want
+to increase or decrease this duration depending on the duration of your recorded
+trials, or you expect that some participants may have slow/unreliable internet
+connections. This example decreases the maximum upload duration from 10 to 5
+seconds:
+
+```javascript
+const trialRec = {
+  // ... Other trial parameters ...
+  extensions: [
+    {
+      type: chsRecord.TrialRecordExtension,
+      params: { max_upload_seconds: 5 },
+    },
+  ],
+};
+```
+
 ## Session Recording
 
 You might prefer to record across multiple trials in a study session. This can
@@ -414,8 +508,18 @@ const startRec = { type: chsRecord.StartRecordPlugin };
 
 #### Parameters
 
-This plugin does not accept any parameters, other those available in all
-plugins.
+**`wait_for_connection_message` [`null` or HTML string | `null` ]**
+
+This parameter determines what content should be displayed while the session
+recording is initializing. If `null` (the default), then the message
+'establishing video connection, please wait' (or appropriate translation based
+on `locale`) will be displayed. 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](https://www.jspsych.org/latest/overview/media-preloading/#manual-preloading).
+Use a blank string (`""`) for no message/content. If a value is provided then
+the `locale` parameter will be ignored.
 
 ### Stop Recording Plugin
 
@@ -425,12 +529,44 @@ The plugin to stop session recording is called `chsRecord.StopRecordPlugin`.
 const stopRec = { type: chsRecord.StopRecordPlugin };
 ```
 
+When the trial starts, by default, this plugin will display "uploading video,
+please wait...", or the appropriate translation based on the `locale` parameter.
+This message can be customized using the `wait_for_upload_message` parameter,
+which is the HTML-formatted string to be displayed while the session recording
+is uploading.
+
+```javascript
+const stopRec = {
+  type: chsRecord.StopRecordPlugin,
+  wait_for_upload_message:
+    "<p style='color:red;'>Please wait while we upload your video.</p>",
+};
+```
+
 #### Parameters
 
-This plugin does not accept any parameters, other those available in all
-plugins.
+**`wait_for_upload_message` [`null` or HTML string | `null` ]**
 
-### Example
+This parameter determines what content should be displayed while the session
+recording is uploading. If `null` (the default), then the message 'uploading
+video, please wait...' (or appropriate translation based on `locale`) will be
+displayed. 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](https://www.jspsych.org/latest/overview/media-preloading/#manual-preloading).
+Use a blank string (`""`) for no message/content. If a value is provided then
+the `locale` parameter will be ignored.
+
+**`max_upload_seconds` [ Integer | 10 ]**
+
+Maximum duration (in seconds) to wait for the session recording to finish
+uploading before continuing with the experiment. If the maximum upload duration
+is reached and the upload has not finished, then the experiment will move on and
+the session recording upload will continue in the background.
+
+### Examples
+
+**Basic usage**
 
 First, make sure that you've added a video config trial to your experiment
 timeline. Then, create your start and stop recording trials:
@@ -476,3 +612,58 @@ jsPsych.run([
   stopRec,
 ]);
 ```
+
+**Setting parameters**
+
+By default, the start session recording plugin will display "establishing video
+connection, please wait" while establishing the connection to our video storage,
+and the stop session recording plugin will display "uploading video, please
+wait..." while the session recording is uploading. You can set the `locale`
+parameter value to translate these messages to another language. For example,
+the trial below will display the Brazilian Portuguese translation of these
+messages. If the locale string does not match any of the translation codes that
+we support, then the message will be displayed in English.
+
+```javascript
+const startpRec = {
+  type: type: chsRecord.StartRecordPlugin,
+  locale: "pt-br",
+};
+const stopRec = {
+  type: chsRecord.StopRecordPlugin,
+  locale: "pt-br",
+};
+```
+
+You can also set custom content to be displayed at the start of the session
+recording, while it is initializing, and/or at the end, when the file is
+uploading. The value must be a string. It can include HTML-formatted content,
+which means that you can embed audio, video, images etc. (be sure to preload any
+media files!).
+
+```javascript
+const startpRec = {
+  type: type: chsRecord.StartRecordPlugin,
+  wait_for_connection_message: "<p style='color:green;>Please wait...</p>"
+};
+const stopRec = {
+  type: chsRecord.StopRecordPlugin,
+  wait_for_upload_message: "<p style='color:red;'>Hang on a sec!</p>",
+};
+```
+
+By default, the stop session recording plugin will wait up to 10 seconds for the
+session recording to finish uploading before moving on with the experiment. If
+the upload does not finish in that time, it will continue to upload in the
+background. You can adjust this duration with the `max_upload_seconds`
+parameter. You may want to increase this duration if, for example, your
+experiment creates a very long session recording, or you expect that some
+participants may have slow/unreliable internet connections. This example
+increases the maximum upload duration from 10 to 20 seconds:
+
+```javascript
+const stopRec = {
+  type: chsRecord.StopRecordPlugin,
+  max_upload_seconds: 20,
+};
+```

package/dist/index.browser.js

@@ -32,7 +32,7 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 
 	var _package = {
 	  name: "@lookit/record",
-	  version: "4.0.0",
+	  version: "5.0.0",
 	  description: "Recording extensions and plugins for CHS studies.",
 	  homepage: "https://github.com/lookit/lookit-jspsych#readme",
 	  bugs: {
@@ -73,8 +73,8 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    typescript: "^5.6.2"
 	  },
 	  peerDependencies: {
-	    "@lookit/data": "^0.2.0",
-	    "@lookit/templates": "^2.1.0",
+	    "@lookit/data": "^0.3.0",
+	    "@lookit/templates": "^3.0.0",
 	    jspsych: "^8.0.3"
 	  }
 	};
@@ -149,6 +149,12 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    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.");
@@ -173,6 +179,12 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    this.name = "ElementNotFoundError";
 	  }
 	}
+	class TimeoutError extends Error {
+	  constructor(msg) {
+	    super(`${msg}`);
+	    this.name = "TimeoutError";
+	  }
+	}
 
 	// Gets all non-builtin properties up the prototype chain.
 	const getAllProperties = object => {
@@ -8465,6 +8477,31 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 
 	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;
@@ -8569,13 +8606,73 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    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) {
@@ -8588,18 +8685,27 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      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();
-	      }
-	      resolve();
+	      resolve(this.url);
 	    };
 	  }
 	  handleDataAvailable(event) {
@@ -8608,11 +8714,11 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      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();
 	    }
 	  }
@@ -8641,6 +8747,18 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    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 = {
@@ -8693,6 +8811,11 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    prompt_only_adults: { type: jspsych.ParameterType.BOOL, default: false },
 	    consent_statement_text: { type: jspsych.ParameterType.STRING, default: "" },
 	    omit_injury_phrase: { type: jspsych.ParameterType.BOOL, default: false }
+	  },
+	  data: {
+	    chs_type: {
+	      type: jspsych.ParameterType.STRING
+	    }
 	  }
 	};
 	class VideoConsentPlugin {
@@ -8822,8 +8945,10 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    stop.addEventListener("click", async () => {
 	      stop.disabled = true;
 	      this.addMessage(display, this.uploadingMsg);
-	      await this.recorder.stop(true);
-	      this.recorder.reset();
+	      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);
@@ -8846,7 +8971,21 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  }
 	}
 
-	const info$2 = { name: "start-record-plugin", parameters: {} };
+	const info$2 = {
+	  name: "start-record-plugin",
+	  version: _package.version,
+	  parameters: {
+	    wait_for_connection_message: {
+	      type: jspsych.ParameterType.HTML_STRING,
+	      default: null
+	    },
+	    locale: {
+	      type: jspsych.ParameterType.STRING,
+	      default: "en-us"
+	    }
+	  },
+	  data: {}
+	};
 	class StartRecordPlugin {
 	  constructor(jsPsych) {
 	    this.jsPsych = jsPsych;
@@ -8859,8 +8998,14 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  }
 	  static info = info$2;
 	  recorder;
-	  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();
 	    });
 	  }
@@ -8868,9 +9013,22 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 
 	const info$1 = {
 	  name: "stop-record-plugin",
+	  version: _package.version,
 	  parameters: {
-	    locale: { type: jspsych.ParameterType.STRING, default: "en-us" }
-	  }
+	    wait_for_upload_message: {
+	      type: jspsych.ParameterType.HTML_STRING,
+	      default: null
+	    },
+	    locale: {
+	      type: jspsych.ParameterType.STRING,
+	      default: "en-us"
+	    },
+	    max_upload_seconds: {
+	      type: jspsych.ParameterType.INT,
+	      default: 10
+	    }
+	  },
+	  data: {}
 	};
 	class StopRecordPlugin {
 	  constructor(jsPsych) {
@@ -8883,13 +9041,25 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  }
 	  static info = info$1;
 	  recorder;
-	  trial(display_element, trial) {
-	    display_element.innerHTML = chsTemplates.uploadingVideo(trial);
-	    this.recorder.stop().then(() => {
+	  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;
+	    }
+	    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();
-	    });
+	    }
 	  }
 	}
 
@@ -8899,22 +9069,70 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    autoBind(this);
 	  }
 	  static info = {
-	    name: "chs-trial-record-extension"
+	    name: "chs-trial-record-extension",
+	    version: _package.version,
+	    data: {}
 	  };
 	  recorder;
 	  pluginName;
-	  async initialize() {
+	  uploadMsg = null;
+	  locale = "en-us";
+	  maxUploadSeconds = void 0;
+	  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";
+	      this.maxUploadSeconds = params?.max_upload_seconds === void 0 ? 10 : params.max_upload_seconds;
+	      resolve();
+	    });
 	  }
-	  on_start() {
+	  on_start(startParams) {
+	    if (startParams?.wait_for_upload_message) {
+	      this.uploadMsg = startParams.wait_for_upload_message;
+	    }
+	    if (startParams?.locale) {
+	      this.locale = startParams.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}`);
 	  }
-	  on_finish() {
-	    this.recorder?.stop();
-	    return {};
+	  async on_finish() {
+	    const displayEl = this.jsPsych.getDisplayElement();
+	    if (this.uploadMsg == null) {
+	      displayEl.innerHTML = chsTemplates.uploadingVideo({
+	        type: this.jsPsych.getCurrentTrial().type,
+	        locale: this.locale
+	      });
+	    } else {
+	      displayEl.innerHTML = this.uploadMsg;
+	    }
+	    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 = "";
+	      return {};
+	    }
 	  }
 	  getCurrentPluginName() {
 	    const current_plugin_class = this.jsPsych.getCurrentTrial().type;
@@ -9325,4 +9543,4 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	return index;
 
 })(chsData, chsTemplates, jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@lookit/record@4.0.0/dist/index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@lookit/record@5.0.0/dist/index.browser.js.map