@lookit/record 4.1.0 → 5.0.0

package/README.md

@@ -368,6 +368,13 @@ string, be sure to preload the media files with the `preload` plugin and
 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**
@@ -452,6 +459,27 @@ const trialRec = {
 };
 ```
 
+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
@@ -480,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
 
@@ -519,6 +557,13 @@ string, be sure to preload the media files with the `preload` plugin and
 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**
@@ -570,28 +615,55 @@ jsPsych.run([
 
 **Setting parameters**
 
-By default, 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 this message to another language. For
-example, the trial below will display the Brazilian Portuguese translation of
-this message. If the locale string does not match any of the translation codes
-that we support, then the message will be displayed in English.
+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 while the session recording file
-is uploading. The value must be a string. It can include HTML-formatted content,
+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.1.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,19 +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();
-	      }
-	      this.reset();
-	      resolve();
+	      resolve(this.url);
 	    };
 	  }
 	  handleDataAvailable(event) {
@@ -8609,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();
 	    }
 	  }
@@ -8642,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 = {
@@ -8828,7 +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);
+	      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);
@@ -8854,7 +8974,16 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	const info$2 = {
 	  name: "start-record-plugin",
 	  version: _package.version,
-	  parameters: {},
+	  parameters: {
+	    wait_for_connection_message: {
+	      type: jspsych.ParameterType.HTML_STRING,
+	      default: null
+	    },
+	    locale: {
+	      type: jspsych.ParameterType.STRING,
+	      default: "en-us"
+	    }
+	  },
 	  data: {}
 	};
 	class StartRecordPlugin {
@@ -8869,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();
 	    });
 	  }
@@ -8887,6 +9022,10 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    locale: {
 	      type: jspsych.ParameterType.STRING,
 	      default: "en-us"
+	    },
+	    max_upload_seconds: {
+	      type: jspsych.ParameterType.INT,
+	      default: 10
 	    }
 	  },
 	  data: {}
@@ -8902,19 +9041,25 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  }
 	  static info = info$1;
 	  recorder;
-	  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);
-	    });
+	    }
 	  }
 	}
 
@@ -8932,12 +9077,12 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  pluginName;
 	  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";
-	      console.log(this.uploadMsg);
-	      console.log(this.locale);
+	      this.maxUploadSeconds = params?.max_upload_seconds === void 0 ? 10 : params.max_upload_seconds;
 	      resolve();
 	    });
 	  }
@@ -8948,13 +9093,14 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    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();
@@ -8966,13 +9112,27 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    } 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;
@@ -9383,4 +9543,4 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	return index;
 
 })(chsData, chsTemplates, jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@lookit/record@4.1.0/dist/index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@lookit/record@5.0.0/dist/index.browser.js.map