@lookit/record 3.0.1 → 4.1.0

package/README.md

@@ -356,9 +356,21 @@ 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` ]**
+
+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.
 
-### Example
+### Examples
+
+**Basic usage**
 
 To record a single trial, you will have to first load the extension in
 `initJsPsych`.
@@ -375,7 +387,7 @@ record any trial you design.
 
 ```javascript
 const trialRec = {
-  // ... Other trial paramters ...
+  // ... Other trial parameters ...
   extensions: [{ type: chsRecord.TrialRecordExtension }],
 };
 ```
@@ -386,6 +398,60 @@ 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: "" },
+    },
+  ],
+};
+```
+
 ## Session Recording
 
 You might prefer to record across multiple trials in a study session. This can
@@ -425,12 +491,37 @@ 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.
+
+### 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 +567,31 @@ jsPsych.run([
   stopRec,
 ]);
 ```
+
+**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.
+
+```javascript
+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,
+which means that you can embed audio, video, images etc. (be sure to preload any
+media files!).
+
+```javascript
+const stopRec = {
+  type: chsRecord.StopRecordPlugin,
+  wait_for_upload_message: "<p style='color:red;'>Hang on a sec!</p>",
+};
+```

package/dist/index.browser.js

@@ -32,7 +32,7 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 
 	var _package = {
 	  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: {
@@ -74,7 +74,7 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  },
 	  peerDependencies: {
 	    "@lookit/data": "^0.2.0",
-	    "@lookit/templates": "^2.0.0",
+	    "@lookit/templates": "^2.1.0",
 	    jspsych: "^8.0.3"
 	  }
 	};
@@ -167,21 +167,10 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    this.name = "CreateURLError";
 	  }
 	}
-	class VideoContainerNotFoundError extends Error {
-	  constructor() {
-	    super("Video Container could not be found.");
-	    this.name = "VideoContainerError";
-	  }
-	}
-	class ButtonNotFoundError extends Error {
-	  constructor(id) {
-	    super(`"${id}" button not found.`);
-	    this.name = "ButtonNotFoundError";
-	  }
-	}
-	class ImageNotFoundError extends Error {
-	  constructor(id) {
-	    super(`"${id}" image not found.`);
+	class ElementNotFoundError extends Error {
+	  constructor(id, tag) {
+	    super(`"${id}" ${tag} not found.`);
+	    this.name = "ElementNotFoundError";
 	  }
 	}
 
@@ -8580,9 +8569,9 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    this.recorder.stop();
 	    this.stream.getTracks().map((t) => t.stop());
 	  }
-	  stop() {
+	  stop(maintain_container_size = false) {
+	    this.clearWebcamFeed(maintain_container_size);
 	    this.stopTracks();
-	    this.clearWebcamFeed();
 	    if (!this.stopPromise) {
 	      throw new NoStopPromiseError();
 	    }
@@ -8610,6 +8599,7 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      } else {
 	        await this.s3.completeUpload();
 	      }
+	      this.reset();
 	      resolve();
 	    };
 	  }
@@ -8627,11 +8617,20 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      link.click();
 	    }
 	  }
-	  clearWebcamFeed() {
+	  clearWebcamFeed(maintain_container_size) {
 	    const webcam_feed_element = document.querySelector(
 	      `#${this.webcam_element_id}`
 	    );
 	    if (webcam_feed_element) {
+	      if (maintain_container_size) {
+	        const parent_div = webcam_feed_element.parentElement;
+	        if (parent_div) {
+	          const width = webcam_feed_element.offsetWidth;
+	          const height = webcam_feed_element.offsetHeight;
+	          parent_div.style.height = `${height}px`;
+	          parent_div.style.width = `${width}px`;
+	        }
+	      }
 	      webcam_feed_element.remove();
 	    }
 	  }
@@ -8695,6 +8694,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 {
@@ -8706,6 +8710,11 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  static info = info$3;
 	  recorder;
 	  video_container_id = "lookit-jspsych-video-container";
+	  msg_container_id = "lookit-jspsych-video-msg-container";
+	  uploadingMsg = null;
+	  startingMsg = null;
+	  recordingMsg = null;
+	  notRecordingMsg = null;
 	  trial(display, trial) {
 	    const consentVideo = chsTemplates.consentVideo(trial);
 	    display.insertAdjacentHTML("afterbegin", consentVideo);
@@ -8714,13 +8723,25 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    this.stopButton(display);
 	    this.playButton(display);
 	    this.nextButton(display);
+	    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"
+	    );
 	  }
 	  getVideoContainer(display) {
 	    const videoContainer = display.querySelector(
 	      `div#${this.video_container_id}`
 	    );
 	    if (!videoContainer) {
-	      throw new VideoContainerNotFoundError();
+	      throw new ElementNotFoundError(this.video_container_id, "div");
 	    }
 	    return videoContainer;
 	  }
@@ -8731,14 +8752,31 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  }
 	  playbackFeed(display) {
 	    const videoContainer = this.getVideoContainer(display);
-	    this.recorder.insertPlaybackFeed(videoContainer, this.onEnded(display));
+	    this.recorder.insertPlaybackFeed(
+	      videoContainer,
+	      this.onPlaybackEnded(display)
+	    );
+	  }
+	  getMessageContainer(display) {
+	    const msgContainer = display.querySelector(
+	      `div#${this.msg_container_id}`
+	    );
+	    if (!msgContainer) {
+	      throw new ElementNotFoundError(this.msg_container_id, "div");
+	    }
+	    return msgContainer;
+	  }
+	  addMessage(display, message) {
+	    const msgContainer = this.getMessageContainer(display);
+	    msgContainer.innerHTML = message;
 	  }
-	  onEnded(display) {
+	  onPlaybackEnded(display) {
 	    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;
@@ -8747,14 +8785,14 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  getButton(display, id) {
 	    const btn = display.querySelector(`button#${id}`);
 	    if (!btn) {
-	      throw new ButtonNotFoundError(id);
+	      throw new ElementNotFoundError(id, "button");
 	    }
 	    return btn;
 	  }
 	  getImg(display, id) {
 	    const img = display.querySelector(`img#${id}`);
 	    if (!img) {
-	      throw new ImageNotFoundError(id);
+	      throw new ElementNotFoundError(id, "img");
 	    }
 	    return img;
 	  }
@@ -8764,12 +8802,14 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    const play = this.getButton(display, "play");
 	    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;
 	    });
 	  }
 	  playButton(display) {
@@ -8787,11 +8827,13 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	    const play = this.getButton(display, "play");
 	    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;
 	    });
 	  }
 	  nextButton(display) {
@@ -8809,7 +8851,12 @@ 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: {},
+	  data: {}
+	};
 	class StartRecordPlugin {
 	  constructor(jsPsych) {
 	    this.jsPsych = jsPsych;
@@ -8831,9 +8878,18 @@ 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"
+	    }
+	  },
+	  data: {}
 	};
 	class StopRecordPlugin {
 	  constructor(jsPsych) {
@@ -8847,11 +8903,17 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	  static info = info$1;
 	  recorder;
 	  trial(display_element, trial) {
-	    display_element.innerHTML = chsTemplates.uploadingVideo(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(() => {
 	      window.chs.sessionRecorder = null;
 	      display_element.innerHTML = "";
 	      this.jsPsych.finishTrial();
+	    }).catch((err) => {
+	      console.error("StopRecordPlugin: recorder stop/upload failed.", err);
 	    });
 	  }
 	}
@@ -8862,21 +8924,54 @@ 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";
+	  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);
+	      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;
+	    }
+	    console.log(this.uploadMsg);
+	    console.log(this.locale);
 	    this.recorder = new Recorder(this.jsPsych);
 	  }
 	  on_load() {
 	    this.pluginName = this.getCurrentPluginName();
 	    this.recorder?.start(false, `${this.pluginName}`);
 	  }
-	  on_finish() {
-	    this.recorder?.stop();
+	  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;
+	    }
+	    try {
+	      await this.recorder?.stop();
+	      displayEl.innerHTML = "";
+	    } catch (err) {
+	      console.error("TrialRecordExtension: recorder stop/upload failed.", err);
+	    }
 	    return {};
 	  }
 	  getCurrentPluginName() {
@@ -9288,4 +9383,4 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	return index;
 
 })(chsData, chsTemplates, jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@lookit/record@3.0.1/dist/index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@lookit/record@4.1.0/dist/index.browser.js.map