@lookit/record 4.0.0 → 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: "4.0.0",
+	  version: "4.1.0",
 	  description: "Recording extensions and plugins for CHS studies.",
 	  homepage: "https://github.com/lookit/lookit-jspsych#readme",
 	  bugs: {
@@ -8599,6 +8599,7 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      } else {
 	        await this.s3.completeUpload();
 	      }
+	      this.reset();
 	      resolve();
 	    };
 	  }
@@ -8693,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 {
@@ -8823,7 +8829,6 @@ var chsRecord = (function (Data, chsTemplates, jspsych) {
 	      stop.disabled = true;
 	      this.addMessage(display, this.uploadingMsg);
 	      await this.recorder.stop(true);
-	      this.recorder.reset();
 	      this.recordFeed(display);
 	      this.getImg(display, "record-icon").style.visibility = "hidden";
 	      this.addMessage(display, this.notRecordingMsg);
@@ -8846,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;
@@ -8868,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) {
@@ -8884,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);
 	    });
 	  }
 	}
@@ -8899,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() {
@@ -9325,4 +9383,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@4.1.0/dist/index.browser.js.map