@lookit/record 4.0.0 → 5.0.0

package/dist/index.d.ts

@@ -132,6 +132,11 @@ declare const info$3: {
             readonly default: false;
         };
     };
+    readonly data: {
+        readonly chs_type: {
+            readonly type: ParameterType.STRING;
+        };
+    };
 };
 type Info$3 = typeof info$3;
 /** The video consent plugin. */
@@ -269,6 +274,11 @@ declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
                 readonly default: false;
             };
         };
+        readonly data: {
+            readonly chs_type: {
+                readonly type: ParameterType.STRING;
+            };
+        };
     };
     private readonly recorder;
     private readonly video_container_id;
@@ -393,7 +403,32 @@ declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
 
 declare const info$2: {
     readonly name: "start-record-plugin";
-    readonly parameters: {};
+    readonly version: string;
+    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;
 /** Start recording. Used by researchers who want to record across trials. */
@@ -401,7 +436,32 @@ declare class StartRecordPlugin implements JsPsychPlugin<Info$2> {
     private jsPsych;
     static readonly info: {
         readonly name: "start-record-plugin";
-        readonly parameters: {};
+        readonly version: string;
+        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;
     /**
@@ -410,18 +470,53 @@ 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: {
     readonly name: "stop-record-plugin";
+    readonly version: string;
     readonly parameters: {
+        /**
+         * This string can contain HTML markup. Any content provided will be
+         * displayed while the recording is uploading. If null (the default), then
+         * the default 'uploading video, please wait' (or appropriate translation
+         * based on 'locale') will be displayed. Use a blank string for no
+         * message/content.
+         */
+        readonly wait_for_upload_message: {
+            readonly type: ParameterType.HTML_STRING;
+            readonly default: string | null;
+        };
+        /**
+         * 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 is
+         * ignored.
+         */
         readonly locale: {
             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: {};
 };
 type Info$1 = typeof info$1;
 /** Stop recording. Used by researchers who want to record across trials. */
@@ -429,12 +524,40 @@ declare class StopRecordPlugin implements JsPsychPlugin<Info$1> {
     private jsPsych;
     static readonly info: {
         readonly name: "stop-record-plugin";
+        readonly version: string;
         readonly parameters: {
+            /**
+             * This string can contain HTML markup. Any content provided will be
+             * displayed while the recording is uploading. If null (the default), then
+             * the default 'uploading video, please wait' (or appropriate translation
+             * based on 'locale') will be displayed. Use a blank string for no
+             * message/content.
+             */
+            readonly wait_for_upload_message: {
+                readonly type: ParameterType.HTML_STRING;
+                readonly default: string | null;
+            };
+            /**
+             * 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 is
+             * ignored.
+             */
             readonly locale: {
                 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: {};
     };
     private recorder;
     /**
@@ -451,15 +574,49 @@ 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>;
 }
 
-/** This extension will allow reasearchers to record trials. */
+interface Parameters {
+    /**
+     * Content that should be displayed while the recording is uploading. If null
+     * (the default), then the default 'uploading video, please wait...' (or
+     * appropriate translation based on 'locale') will be displayed. Use a blank
+     * string for no message/content. 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. Use a blank string (`""`)
+     * for no message/content.
+     *
+     * @default null
+     */
+    wait_for_upload_message?: null | string;
+    /**
+     * 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 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 {
     private jsPsych;
     static readonly info: JsPsychExtensionInfo;
     private recorder?;
     private pluginName;
+    private uploadMsg;
+    private locale;
+    private maxUploadSeconds;
     /**
      * Video recording extension.
      *
@@ -467,20 +624,34 @@ declare class TrialRecordExtension implements JsPsychExtension {
      */
     constructor(jsPsych: JsPsych);
     /**
-     * Ran on the initialize step for extensions, called when an instance of
+     * Runs on the initialize step for extensions, called when an instance of
      * jsPsych is first initialized through initJsPsych().
+     *
+     * @param params - Parameters object
+     * @param params.wait_for_upload_message - Message to display while waiting
+     *   for upload. String or null (default)
+     * @param params.locale - Message to display while waiting for upload. String
+     *   or null (default).
+     */
+    initialize(params?: Parameters): Promise<void>;
+    /**
+     * Runs at the start of a trial.
+     *
+     * @param startParams - Parameters object
+     * @param startParams.wait_for_upload_message - Message to display while
+     *   waiting for upload. String or null (default). If given, this will
+     *   overwrite the value used during initialization.
      */
-    initialize(): Promise<void>;
-    /** Ran at the start of a trial. */
-    on_start(): void;
-    /** Ran when the trial has loaded. */
+    on_start(startParams?: Parameters): void;
+    /** Runs when the trial has loaded. */
     on_load(): void;
     /**
-     * Ran when trial has finished.
+     * Runs when trial has finished.
      *
-     * @returns Trial data.
+     * @returns Any data from the trial extension that should be added to the rest
+     *   of the trial data.
      */
-    on_finish(): {};
+    on_finish(): Promise<{}>;
     /**
      * Gets the plugin name for the trial that is being extended. This is same as
      * the "trial_type" value that is stored in the data for this trial.