@lookit/record 2.0.0 → 3.0.1

package/dist/index.d.ts

@@ -1,8 +1,777 @@
-import { VideoConsentPlugin } from "./consentVideo";
-import StartRecordPlugin from "./start";
-import StopRecordPlugin from "./stop";
-import TrialRecordExtension from "./trial";
-import VideoConfigPlugin from "./videoConfig";
+import { JsPsychPlugin, ParameterType, JsPsych, TrialType, JsPsychExtension, JsPsychExtensionInfo } from 'jspsych';
+
+declare const info$3: {
+    readonly name: "consent-video";
+    readonly version: string;
+    readonly parameters: {
+        readonly template: {
+            readonly type: ParameterType.STRING;
+            readonly default: "consent-template-5";
+        };
+        readonly locale: {
+            readonly type: ParameterType.STRING;
+            readonly default: "en-us";
+        };
+        readonly additional_video_privacy_statement: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly datause: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly gdpr: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+        readonly gdpr_personal_data: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly gdpr_sensitive_data: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly PIName: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly include_databrary: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+        readonly institution: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly PIContact: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly payment: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly private_level_only: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+        readonly procedures: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly purpose: {
+            readonly type: ParameterType.STRING;
+            readonly default: undefined;
+        };
+        readonly research_rights_statement: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly risk_statement: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly voluntary_participation: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly purpose_header: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly procedures_header: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly participation_header: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly benefits_header: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly risk_header: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly summary_statement: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly additional_segments: {
+            readonly type: ParameterType.COMPLEX;
+            readonly array: true;
+            readonly default: readonly [];
+            readonly nested: {
+                readonly title: {
+                    readonly type: ParameterType.STRING;
+                    readonly default: "";
+                };
+                readonly text: {
+                    readonly type: ParameterType.STRING;
+                    readonly default: "";
+                };
+            };
+        };
+        readonly prompt_all_adults: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+        readonly prompt_only_adults: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+        readonly consent_statement_text: {
+            readonly type: ParameterType.STRING;
+            readonly default: "";
+        };
+        readonly omit_injury_phrase: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
+    };
+};
+type Info$3 = typeof info$3;
+/** The video consent plugin. */
+declare class VideoConsentPlugin implements JsPsychPlugin<Info$3> {
+    private readonly jsPsych;
+    static readonly info: {
+        readonly name: "consent-video";
+        readonly version: string;
+        readonly parameters: {
+            readonly template: {
+                readonly type: ParameterType.STRING;
+                readonly default: "consent-template-5";
+            };
+            readonly locale: {
+                readonly type: ParameterType.STRING;
+                readonly default: "en-us";
+            };
+            readonly additional_video_privacy_statement: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly datause: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly gdpr: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+            readonly gdpr_personal_data: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly gdpr_sensitive_data: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly PIName: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly include_databrary: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+            readonly institution: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly PIContact: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly payment: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly private_level_only: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+            readonly procedures: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly purpose: {
+                readonly type: ParameterType.STRING;
+                readonly default: undefined;
+            };
+            readonly research_rights_statement: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly risk_statement: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly voluntary_participation: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly purpose_header: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly procedures_header: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly participation_header: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly benefits_header: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly risk_header: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly summary_statement: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly additional_segments: {
+                readonly type: ParameterType.COMPLEX;
+                readonly array: true;
+                readonly default: readonly [];
+                readonly nested: {
+                    readonly title: {
+                        readonly type: ParameterType.STRING;
+                        readonly default: "";
+                    };
+                    readonly text: {
+                        readonly type: ParameterType.STRING;
+                        readonly default: "";
+                    };
+                };
+            };
+            readonly prompt_all_adults: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+            readonly prompt_only_adults: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+            readonly consent_statement_text: {
+                readonly type: ParameterType.STRING;
+                readonly default: "";
+            };
+            readonly omit_injury_phrase: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
+        };
+    };
+    private readonly recorder;
+    private readonly video_container_id;
+    /**
+     * Instantiate video consent plugin.
+     *
+     * @param jsPsych - JsPsych object
+     */
+    constructor(jsPsych: JsPsych);
+    /**
+     * Create/Show trial view.
+     *
+     * @param display - HTML element for experiment.
+     * @param trial - Trial data including user supplied parameters.
+     */
+    trial(display: HTMLElement, trial: TrialType<Info$3>): void;
+    /**
+     * Retrieve video container element.
+     *
+     * @param display - HTML element for experiment.
+     * @returns Video container
+     */
+    private getVideoContainer;
+    /**
+     * Add webcam feed to HTML.
+     *
+     * @param display - HTML element for experiment.
+     */
+    private recordFeed;
+    /**
+     * Playback Feed
+     *
+     * @param display - JsPsych display HTML element.
+     */
+    private playbackFeed;
+    /**
+     * Put back the webcam feed once the video recording has ended. This is used
+     * with the "ended" Event.
+     *
+     * @param display - JsPsych display HTML element.
+     * @returns Event function
+     */
+    private onEnded;
+    /**
+     * Retrieve button element from DOM.
+     *
+     * @param display - HTML element for experiment.
+     * @param id - Element id
+     * @returns Button element
+     */
+    private getButton;
+    /**
+     * Select and return the image element.
+     *
+     * @param display - HTML element for experiment.
+     * @param id - ID string of Image element
+     * @returns Image Element
+     */
+    private getImg;
+    /**
+     * Add record button to HTML.
+     *
+     * @param display - HTML element for experiment.
+     */
+    private recordButton;
+    /**
+     * Set up play button to playback last recorded video.
+     *
+     * @param display - HTML element for experiment.
+     */
+    private playButton;
+    /**
+     * Add stop button to HTML.
+     *
+     * @param display - HTML element for experiment.
+     */
+    private stopButton;
+    /**
+     * Add next button to HTML.
+     *
+     * @param display - HTML element for experiment.
+     */
+    private nextButton;
+    /**
+     * Mark the response in the lookit-api database as having completed the
+     * consent frame, then finish the trial.
+     */
+    private endTrial;
+    /**
+     * Add CHS type to experiment data. This will enable Lookit API to run the
+     * "consent" Frame Action Dispatcher method after the experiment has
+     * completed.
+     *
+     * @returns Object containing CHS type.
+     */
+    static chsData(): {
+        chs_type: string;
+    };
+}
+
+declare const info$2: {
+    readonly name: "start-record-plugin";
+    readonly parameters: {};
+};
+type Info$2 = typeof info$2;
+/** Start recording. Used by researchers who want to record across trials. */
+declare class StartRecordPlugin implements JsPsychPlugin<Info$2> {
+    private jsPsych;
+    static readonly info: {
+        readonly name: "start-record-plugin";
+        readonly parameters: {};
+    };
+    private recorder;
+    /**
+     * Plugin used to start recording.
+     *
+     * @param jsPsych - Object provided by jsPsych.
+     */
+    constructor(jsPsych: JsPsych);
+    /** Trial function called by jsPsych. */
+    trial(): void;
+}
+
+declare const info$1: {
+    readonly name: "stop-record-plugin";
+    readonly parameters: {
+        readonly locale: {
+            readonly type: ParameterType.STRING;
+            readonly default: "en-us";
+        };
+    };
+};
+type Info$1 = typeof info$1;
+/** Stop recording. Used by researchers who want to record across trials. */
+declare class StopRecordPlugin implements JsPsychPlugin<Info$1> {
+    private jsPsych;
+    static readonly info: {
+        readonly name: "stop-record-plugin";
+        readonly parameters: {
+            readonly locale: {
+                readonly type: ParameterType.STRING;
+                readonly default: "en-us";
+            };
+        };
+    };
+    private recorder;
+    /**
+     * Plugin used to stop recording.
+     *
+     * @param jsPsych - Object provided by jsPsych.
+     */
+    constructor(jsPsych: JsPsych);
+    /**
+     * 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$1>): void;
+}
+
+/** This extension will allow reasearchers to record trials. */
+declare class TrialRecordExtension implements JsPsychExtension {
+    private jsPsych;
+    static readonly info: JsPsychExtensionInfo;
+    private recorder?;
+    private pluginName;
+    /**
+     * Video recording extension.
+     *
+     * @param jsPsych - JsPsych object passed into extensions.
+     */
+    constructor(jsPsych: JsPsych);
+    /**
+     * Ran on the initialize step for extensions, called when an instance of
+     * jsPsych is first initialized through initJsPsych().
+     */
+    initialize(): Promise<void>;
+    /** Ran at the start of a trial. */
+    on_start(): void;
+    /** Ran when the trial has loaded. */
+    on_load(): void;
+    /**
+     * Ran when trial has finished.
+     *
+     * @returns Trial data.
+     */
+    on_finish(): {};
+    /**
+     * 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.
+     *
+     * @returns Plugin name string from the plugin class's info.
+     */
+    private getCurrentPluginName;
+}
+
+declare const info: {
+    readonly name: "video-config-plugin";
+    readonly version: string;
+    readonly parameters: {
+        readonly locale: {
+            readonly type: ParameterType.STRING;
+            readonly default: "en-us";
+        };
+        readonly troubleshooting_intro: {
+            /**
+             * Optional string to appear at the start of the "Setup tips and
+             * troubleshooting" section.
+             */
+            readonly type: ParameterType.HTML_STRING;
+            readonly default: "";
+            readonly pretty_name: "Troubleshooting Intro";
+        };
+    };
+    readonly data: {
+        readonly rt: {
+            readonly type: ParameterType.INT;
+        };
+        readonly camId: {
+            readonly type: ParameterType.STRING;
+        };
+        readonly micId: {
+            readonly type: ParameterType.STRING;
+        };
+    };
+};
+type Info = typeof info;
+type VideoConsentTrialType = TrialType<Info>;
+/**
+ * **Video Config**.
+ *
+ * CHS jsPsych plugin for presenting a video recording configuration plugin, to
+ * help participants set up their webcam and microphone before beginning a study
+ * that includes video/audio recording. This plugin must be used before any
+ * other trials in the experiment can access the camera/mic.
+ *
+ * @author Becky Gilbert
+ * @see {@link https://github.com/lookit/lookit-jspsych/blob/main/packages/video-config/README.md video-config plugin documentation on Github}
+ */
+declare class VideoConfigPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        readonly name: "video-config-plugin";
+        readonly version: string;
+        readonly parameters: {
+            readonly locale: {
+                readonly type: ParameterType.STRING;
+                readonly default: "en-us";
+            };
+            readonly troubleshooting_intro: {
+                /**
+                 * Optional string to appear at the start of the "Setup tips and
+                 * troubleshooting" section.
+                 */
+                readonly type: ParameterType.HTML_STRING;
+                readonly default: "";
+                readonly pretty_name: "Troubleshooting Intro";
+            };
+        };
+        readonly data: {
+            readonly rt: {
+                readonly type: ParameterType.INT;
+            };
+            readonly camId: {
+                readonly type: ParameterType.STRING;
+            };
+            readonly micId: {
+                readonly type: ParameterType.STRING;
+            };
+        };
+    };
+    private display_el;
+    private start_time;
+    private recorder;
+    private hasReloaded;
+    private response;
+    private camId;
+    private micId;
+    private minVolume;
+    private micChecked;
+    private processorNode;
+    private mimeType;
+    /**
+     * Constructor for video config plugin.
+     *
+     * @param jsPsych - JsPsych object automatically passed into the constructor.
+     */
+    constructor(jsPsych: JsPsych);
+    /**
+     * Trial method called by jsPsych.
+     *
+     * @param display_element - Element where the jsPsych trial will be displayed.
+     * @param trial - Trial object with parameters/values.
+     */
+    trial(display_element: HTMLElement, trial: VideoConsentTrialType): void;
+    /**
+     * Add HTML content to the page.
+     *
+     * @param trial - Trial object.
+     */
+    private addHtmlContent;
+    /** Add event listeners to elements after they've been added to the page. */
+    private addEventListeners;
+    /**
+     * Access media devices, populate device lists, setup the jsPsych
+     * camera/stream and Recorder instance, and run the permissions/mic checks.
+     * This is run when the trial first loads and anytime the user clicks the
+     * reload recorder button.
+     *
+     * 1. Request permissions.
+     * 2. Enumerate devices and populate the device selection elements with options.
+     * 3. Initialize the jsPsych recorder with the current/selected devices, and
+     *    create a new Recorder.
+     * 4. Run the stream checks. (If completed successfully, this will clear any
+     *    error messages and enable the next button).
+     */
+    private setupRecorder;
+    /**
+     * Request permission to use the webcam and/or microphone. This can be used
+     * with and without specific device selection (and other constraints).
+     *
+     * @param constraints - Media stream constraints object with 'video' and
+     *   'audio' properties, whose values can be boolean or a
+     *   MediaTrackConstraints object or undefined.
+     * @param constraints.video - If false, do not include video. If true, use the
+     *   default webcam device. If a media track constraints object is passed,
+     *   then it can contain the properties of all media tracks and video tracks:
+     *   https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints.
+     * @param constraints.audio - If false, do not include audio. If true, use the
+     *   default mic device. If a media track constraints object is passed, then
+     *   it can contain the properties of all media tracks and audio tracks:
+     *   https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints.
+     * @returns Camera/microphone stream.
+     */
+    private requestPermission;
+    /**
+     * Receives device lists and populates the device selection HTML elements.
+     * This is run when the trial loads, and in response to changes to the
+     * available devices.
+     *
+     * @param devices - Object with properties 'cameras' and 'mics', which are
+     *   arrays containing lists of available devices.
+     * @param devices.cameras - Array of MediaDeviceInfo objects for webcam/video
+     *   input devices.
+     * @param devices.mics - Array of MediaDeviceInfo objects for mic/audio input
+     *   devices.
+     */
+    private updateDeviceSelection;
+    /**
+     * Takes the selected device IDs from the camera/mic selection elements, gets
+     * the streams for these devices, sets these as the input devices via
+     * jsPsych.pluginAPI.initializeCameraRecorder, and creates a new Recorder.
+     */
+    private setDevices;
+    /**
+     * Run the stream checks after permissions have been granted and devices have
+     * been selected. This is run when the trial first loads, after permissions
+     * are granted, and in response to changes to the device selection. It checks
+     * for (1) the existence of the required streams, (2) minimum microphone input
+     * level (when audio is included), and (3) media permissions (via recorder
+     * destroy/reload). This runs the stream checks, updates the info/error
+     * messages, enables the next button, and handles errors. This is factored out
+     * of the set up process (setupRecorder) because it is also triggered by a
+     * change in the cam/mic device selection.
+     */
+    private runStreamChecks;
+    /**
+     * If there is a change to the available devices, then we need to: (1) get the
+     * updated device lists, and (2) update the select elements with these list
+     * elements.
+     */
+    private onDeviceChange;
+    /**
+     * Gets the lists of available cameras and mics (via Media Devices
+     * 'enumerateDevices'). These lists can be used to populate camera/mic
+     * selection elements.
+     *
+     * @param include_audio - Whether or not to include audio capture (mic)
+     *   devices. Optional, default is true.
+     * @param include_camera - Whether or not to include the webcam (video)
+     *   devices. Optional, default is true.
+     * @returns Object with properties 'cameras' and 'mics', containing lists of
+     *   available devices.
+     */
+    private getDeviceLists;
+    /**
+     * Initialize recorder using the jsPsych plugin API. This must be called
+     * before running the stream checks.
+     *
+     * @param stream - Media stream returned from getUserMedia that should be used
+     *   to set up the jsPsych recorder.
+     * @param opts - Media recorder options to use when setting up the recorder.
+     *   This will include the mimeType property that is set via getMimeTypeCodec,
+     *   as well as any other options that can passed via the calling context.
+     */
+    initializeAndCreateRecorder: (stream: MediaStream, opts?: MediaRecorderOptions) => void;
+    /**
+     * Perform a sound check on the audio input (microphone).
+     *
+     * @param minVol - Minimum mic activity needed to reach the mic check
+     *   threshold (optional). Default is `this.minVolume`
+     * @returns Promise that resolves when the mic check is complete because the
+     *   audio stream has reached the required minimum level.
+     */
+    private checkMic;
+    /**
+     * Handle the mic level messages that are sent via an AudioWorkletProcessor.
+     * This checks the current level against the minimum threshold, and if the
+     * threshold is met, sets the micChecked property to true and resolves the
+     * checkMic promise.
+     *
+     * @param currentActivityLevel - Microphone activity level calculated by the
+     *   processor node.
+     * @param minVolume - Minimum microphone activity level needed to pass the
+     *   microphone check.
+     * @param resolve - Resolve callback function for Promise returned by the
+     *   checkMic method.
+     */
+    private onMicActivityLevel;
+    /**
+     * Creates the processor node for the mic check input level processing, and
+     * connects the microphone to the processor node.
+     *
+     * @param audioContext - Audio context that was created in checkMic. This is
+     *   used to create the processor node.
+     * @param microphone - Microphone audio stream source, created in checkMic.
+     *   The processor node will be connected to this source.
+     * @returns Promise that resolves after the processor node has been created,
+     *   and the microphone audio stream source is connected to the processor node
+     *   and audio context destination.
+     */
+    private createConnectProcessor;
+    /**
+     * Set up the port's on message event handler for the mic check processor
+     * node. This adds the event related callback, which calls onMicActivityLevel
+     * with the event data.
+     *
+     * @param minVol - Minimum volume level (RMS amplitude) passed from checkMic.
+     * @returns Promise that resolves from inside the onMicActivityLevel callback,
+     *   when the mic stream input level has reached the threshold.
+     */
+    private setupPortOnMessage;
+    /**
+     * Update the instructions for a given step, based on whether or not the check
+     * has passed for that step.
+     *
+     * @param step - Which instructions step to update. 1 = stream access, 2 =
+     *   reload complete, 3 = mic level check.
+     * @param checkPassed - Whether or not the mic check has passed.
+     */
+    private updateInstructions;
+    /**
+     * Update the errors/messages div with information for the user about the
+     * camera/mic checks.
+     *
+     * @param errorMsgId - Span element ID containing the message to display in
+     *   the error message div. Call the function without an errorMsgId to clear
+     *   the errors.
+     */
+    private updateErrors;
+    /**
+     * Collect trial data and end the trial. JsPsych.finishTrial takes the
+     * plugin's trial data as an argument, ends the trial, and moves on to the
+     * next trial in the experiment timeline.
+     */
+    private endTrial;
+    /**
+     * Destroy the recorder. This is used to stop the streams at the end of the
+     * trial, and as part of the reload check to test the user's browser
+     * permissions by mimicking the start of a new trial (i.e. stop streams and
+     * then create a new Recorder instance).
+     */
+    private destroyRecorder;
+    /** Handle the next button click event. */
+    private nextButtonClick;
+    /** Handle the reload recorder button click event. */
+    private reloadButtonClick;
+    /**
+     * Toggle the next button disable property.
+     *
+     * @param enable - Whether to enable (true) or disable (false) the next
+     *   button.
+     */
+    private enableNext;
+    /**
+     * Check support for recording containers/codecs, in order of preference, and
+     * get the first supported type. The first supported type found in the
+     * mime_types array is returned and will be passed to the "mimeType" property
+     * in the recorder options object that is passed to the recorder
+     * initialization function (jsPsych.pluginAPI.initializeCameraRecorder). If
+     * none of these types is supported, the function returns null.
+     *
+     * Note: we will likely need to continuously update the mime_types list as new
+     * formats become supported, we support other browsers/versions, etc.
+     *
+     * @returns Mime type string, or null (if none from the array are supported).
+     */
+    private getCompatibleMimeType;
+}
+
 declare const _default: {
     TrialRecordExtension: typeof TrialRecordExtension;
     StartRecordPlugin: typeof StartRecordPlugin;
@@ -10,4 +779,6 @@ declare const _default: {
     VideoConfigPlugin: typeof VideoConfigPlugin;
     VideoConsentPlugin: typeof VideoConsentPlugin;
 };
-export default _default;
+
+export { _default as default };
+//# sourceMappingURL=index.d.ts.map