@lookit/record 0.0.3

package/dist/mic_check.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Audio Worklet Processor class for processing audio input streams. This is
+ * used by the Recorder to run a volume check on the microphone input stream.
+ * Source:
+ * https://www.webrtc-developers.com/how-to-know-if-my-microphone-works/#detect-noise-or-silence
+ */
+export default class MicCheckProcessor extends AudioWorkletProcessor {
+    private _volume;
+    private _micChecked;
+    /** Constructor for the mic check processor. */
+    constructor();
+    /**
+     * Process method that implements the audio processing algorithm for the Audio
+     * Processor Worklet. "Although the method is not a part of the
+     * AudioWorkletProcessor interface, any implementation of
+     * AudioWorkletProcessor must provide a process() method." Source:
+     * https://developer.mozilla.org/en-US/docs/Web/API/AudioWorkletProcessor/process
+     * The process method can take the following arguments: inputs, outputs,
+     * parameters. Here we are only using inputs.
+     *
+     * @param inputs - An array of inputs from the audio stream (microphone)
+     *   connnected to the node. Each item in the inputs array is an array of
+     *   channels. Each channel is a Float32Array containing 128 samples. For
+     *   example, inputs[n][m][i] will access n-th input, m-th channel of that
+     *   input, and i-th sample of that channel.
+     * @returns Boolean indicating whether or not the Audio Worklet Node should
+     *   remain active, even if the User Agent thinks it is safe to shut down. In
+     *   this case, when the recorder decides that the mic check criteria has been
+     *   met, it will return false (processor should be shut down), otherwise it
+     *   will return true (processor should remain active).
+     */
+    process(inputs: Float32Array[][]): boolean;
+}

package/dist/recorder.d.ts

@@ -0,0 +1,146 @@
+import { JsPsych } from "jspsych";
+import { CSSWidthHeight } from "./types";
+/** Recorder handles the state of recording and data storage. */
+export default class Recorder {
+    private jsPsych;
+    private url?;
+    private _s3?;
+    private blobs;
+    private localDownload;
+    private filename?;
+    private stopPromise?;
+    private webcam_element_id;
+    private streamClone;
+    /**
+     * Recorder for online experiments.
+     *
+     * @param jsPsych - Object supplied by jsPsych.
+     */
+    constructor(jsPsych: JsPsych);
+    /**
+     * Get recorder from jsPsych plugin API.
+     *
+     * If camera recorder hasn't been initialized, then return the microphone
+     * recorder.
+     *
+     * @returns MediaRecorder from the plugin API.
+     */
+    private get recorder();
+    /**
+     * Get stream from either recorder.
+     *
+     * @returns MediaStream from the plugin API.
+     */
+    private get stream();
+    /**
+     * Get s3 class variable. Throw error if doesn't exist.
+     *
+     * @returns - S3 object.
+     */
+    private get s3();
+    /** Set s3 class variable. */
+    private set s3(value);
+    /**
+     * Initialize recorder using the jsPsych plugin API. There should always be a
+     * stream initialized when the Recorder class is instantiated. This method is
+     * just used to re-initialize the stream with a clone when the recorder needs
+     * to be reset during a trial.
+     *
+     * @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.
+     */
+    initializeRecorder(stream: MediaStream, opts?: MediaRecorderOptions): void;
+    /** Reset the recorder to be used again. */
+    reset(): void;
+    /**
+     * Insert a rendered template into an element.
+     *
+     * @param element - Element to have video inserted into.
+     * @param template - Template string
+     * @param insertStream - Should the stream be attributed to the webcam
+     *   element.
+     * @returns Webcam element
+     */
+    private insertVideoFeed;
+    /**
+     * Insert a video element containing the webcam feed onto the page.
+     *
+     * @param element - The HTML div element that should serve as the container
+     *   for the webcam display.
+     * @param width - The width of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'100%'`
+     * @param height - The height of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'auto'`
+     */
+    insertWebcamFeed(element: HTMLDivElement, width?: CSSWidthHeight, height?: CSSWidthHeight): void;
+    /**
+     * Insert video playback feed into supplied element.
+     *
+     * @param element - The HTML div element that should serve as the container
+     *   for the webcam display.
+     * @param on_ended - Callback function called when playing video ends.
+     * @param width - The width of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'100%'`
+     * @param height - The height of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'auto'`
+     */
+    insertPlaybackFeed(element: HTMLDivElement, on_ended: (this: HTMLVideoElement, e: Event) => void, width?: CSSWidthHeight, height?: CSSWidthHeight): void;
+    /**
+     * Insert a feed to be used for recording into an element.
+     *
+     * @param element - Element to have record feed inserted into.
+     * @param width - The width of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'100%'`
+     * @param height - The height of the video element containing the webcam feed,
+     *   in CSS units (optional). Default is `'auto'`
+     */
+    insertRecordFeed(element: HTMLDivElement, width?: CSSWidthHeight, height?: CSSWidthHeight): void;
+    /**
+     * Start recording. Also, adds event listeners for handling data and checks
+     * for recorder initialization.
+     *
+     * @param prefix - Prefix for the video recording file name (string). This is
+     *   the string that comes before "_<TIMESTAMP>.webm".
+     */
+    start(prefix: "consent" | "session_video" | "trial_video"): Promise<void>;
+    /**
+     * Stop all streams/tracks. This stops any in-progress recordings and releases
+     * the media devices. This is can be called when recording is not in progress,
+     * e.g. To end the camera/mic access when the experiment is displaying the
+     * camera feed but not recording (e.g. Video-config).
+     */
+    stopTracks(): void;
+    /**
+     * Stop recording and camera/microphone. This will stop accessing all media
+     * tracks, clear the webcam feed element (if there is one), and return the
+     * stop promise. This should only be called after recording has started.
+     *
+     * @returns Promise that resolves after the media recorder has stopped and
+     *   final 'dataavailable' event has occurred, when the "stop" event-related
+     *   callback function is called.
+     */
+    stop(): Promise<void>;
+    /** Throw Error if there isn't a recorder provided by jsPsych. */
+    private initializeCheck;
+    /**
+     * Handle the recorder's stop event. This is a function that takes the stop
+     * promise's 'resolve' as an argument and returns a function that resolves
+     * that stop promise. The function that is returned is used as the recorder's
+     * "stop" event-related callback function.
+     *
+     * @param resolve - Promise resolve function.
+     * @returns Function that is called on the recorder's "stop" event.
+     */
+    private handleStop;
+    /**
+     * Function ran at each time slice and when the recorder stopped.
+     *
+     * @param event - Event containing blob data.
+     */
+    private handleDataAvailable;
+    /** Download data url used in local development. */
+    private download;
+    /** Private helper to clear the webcam feed, if there is one. */
+    private clearWebcamFeed;
+}

package/dist/start.d.ts

@@ -0,0 +1,24 @@
+import { JsPsych, JsPsychPlugin } from "jspsych";
+declare const info: {
+    readonly name: "start-record-plugin";
+    readonly parameters: {};
+};
+type Info = typeof info;
+/** Start recording. Used by researchers who want to record across trials. */
+export default class StartRecordPlugin implements JsPsychPlugin<Info> {
+    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;
+}
+export {};

package/dist/stop.d.ts

@@ -0,0 +1,30 @@
+import { JsPsych, JsPsychPlugin } from "jspsych";
+declare const info: {
+    readonly name: "stop-record-plugin";
+    readonly parameters: {};
+};
+type Info = typeof info;
+/** Stop recording. Used by researchers who want to record across trials. */
+export default class StopRecordPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static readonly info: {
+        readonly name: "stop-record-plugin";
+        readonly parameters: {};
+    };
+    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).
+     */
+    trial(display_element: HTMLElement): void;
+}
+export {};

package/dist/trial.d.ts

@@ -0,0 +1,28 @@
+import { JsPsych, JsPsychExtension, JsPsychExtensionInfo } from "jspsych";
+/** This extension will allow reasearchers to record trials. */
+export default class TrialRecordExtension implements JsPsychExtension {
+    private jsPsych;
+    static readonly info: JsPsychExtensionInfo;
+    private recorder?;
+    /**
+     * 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(): {};
+}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A valid CSS height/width value, which can be a number, a string containing a
+ * number with units, or 'auto'.
+ */
+export type CSSWidthHeight = number | `${number}${"px" | "cm" | "mm" | "em" | "%"}` | "auto";

package/dist/utils.d.ts

@@ -0,0 +1,21 @@
+import { PluginInfo, TrialType } from "jspsych";
+/**
+ * Pulled from EFP. Function to convert researcher's text to HTML.
+ *
+ * @param text - Text
+ * @returns Formatted string
+ */
+export declare const expFormat: (text?: string | string[]) => string;
+/**
+ * Get a translation file based on selected language.
+ *
+ * @param lcl - Locale object with locale
+ * @returns Translations from i18next
+ */
+export declare const getTranslation: (lcl: Intl.Locale) => Record<string, string>;
+/**
+ * Initialize both i18next and Handlebars.
+ *
+ * @param trial - Yup
+ */
+export declare const initI18nAndTemplates: (trial: TrialType<PluginInfo>) => void;

package/dist/video_config.d.ts

@@ -0,0 +1,296 @@
+import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+declare const info: {
+    readonly name: "video-config-plugin";
+    readonly version: string;
+    readonly parameters: {
+        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;
+export 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}
+ */
+export default class VideoConfigPlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        readonly name: "video-config-plugin";
+        readonly version: string;
+        readonly parameters: {
+            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 webcam_container_id;
+    private reload_button_id_text;
+    private reload_button_id_cam;
+    private camera_selection_id;
+    private mic_selection_id;
+    private next_button_id;
+    private error_msg_div_id;
+    private step1_id;
+    private step2_id;
+    private step3_id;
+    private step_complete_class;
+    private step_complete_text;
+    private waiting_for_access_msg;
+    private checking_mic_msg;
+    private access_problem_msg;
+    private setup_problem_msg;
+    /**
+     * 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 troubleshooting_intro - Troubleshooting intro parameter from the
+     *   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.
+     */
+    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 errorMsg - Message to display in the error message div. Pass an
+     *   empty string to clear any existing errors/messages.
+     */
+    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;
+}
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lookit/record",
+  "version": "0.0.3",
+  "description": "Recording extensions and plugins for CHS studies.",
+  "homepage": "https://github.com/lookit/lookit-jspsych#readme",
+  "bugs": {
+    "url": "https://github.com/lookit/lookit-jspsych/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lookit/lookit-jspsych.git"
+  },
+  "license": "ISC",
+  "author": "Christopher J Green <okaycj@mit.edu> (https://github.com/okaycj)",
+  "main": "dist/index.js",
+  "unpkg": "dist/index.browser.min.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup --config",
+    "buildMicCheck": "npx tsc src/mic_check.ts --target esnext --lib ESNext --types node,audioworklet --skipLibCheck true",
+    "dev": "rollup --config rollup.config.dev.mjs --watch",
+    "test": "jest --coverage"
+  },
+  "dependencies": {
+    "auto-bind": "^5.0.1"
+  },
+  "devDependencies": {
+    "@jspsych/config": "^2.0.0",
+    "@jspsych/test-utils": "^1.2.0",
+    "@rollup/plugin-image": "^3.0.3",
+    "@rollup/plugin-replace": "^6.0.1",
+    "@types/audioworklet": "^0.0.60",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node-polyglot": "^2.5.0",
+    "handlebars": "^4.7.8",
+    "i18next": "^23.15.1",
+    "i18next-icu": "^2.3.0",
+    "js-yaml": "^4.1.0",
+    "rollup-plugin-dotenv": "^0.5.1",
+    "rollup-plugin-polyfill-node": "^0.13.0",
+    "rollup-plugin-string-import": "^1.2.4",
+    "typescript": "^5.6.2"
+  },
+  "peerDependencies": {
+    "@lookit/data": "^0.0.3",
+    "jspsych": "^8.0.2"
+  }
+}