@lookit/record 2.0.0 → 3.0.0

package/dist/recorder.d.ts

@@ -1,158 +0,0 @@
-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 consent - Boolean indicating whether or not the recording is consent
-     *   footage.
-     * @param trial_type - Trial type, as saved in the jsPsych data. This comes
-     *   from the plugin info "name" value (not the class name).
-     */
-    start(consent: boolean, trial_type: string): 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;
-    /**
-     * Creates a valid video file name based on parameters
-     *
-     * @param consent - Boolean indicating whether or not the recording is consent
-     *   footage.
-     * @param trial_type - Trial type, as saved in the jsPsych data. This comes
-     *   from the plugin info "name" value (not the class name).
-     * @returns File name string with .webm extension.
-     */
-    private createFileName;
-}

package/dist/start.d.ts

@@ -1,24 +0,0 @@
-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

@@ -1,41 +0,0 @@
-import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
-declare const info: {
-    readonly name: "stop-record-plugin";
-    readonly parameters: {
-        readonly locale: {
-            readonly type: ParameterType.STRING;
-            readonly default: "en-us";
-        };
-    };
-};
-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: {
-            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>): void;
-}
-export {};

package/dist/trial.d.ts

@@ -1,36 +0,0 @@
-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?;
-    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;
-}

package/dist/types.d.ts

@@ -1,10 +0,0 @@
-import { JsPsychPlugin, PluginInfo } from "jspsych";
-import { Class } from "type-fest";
-export interface jsPsychPluginWithInfo extends Class<JsPsychPlugin<PluginInfo>> {
-    info: PluginInfo;
-}
-/**
- * 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/videoConfig.d.ts

@@ -1,312 +0,0 @@
-import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
-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;
-export type VideoConsentTrialType = TrialType<Info>;
-export declare const html_params: {
-    webcam_container_id: string;
-    reload_button_id_text: string;
-    reload_button_id_cam: string;
-    camera_selection_id: string;
-    mic_selection_id: string;
-    next_button_id: string;
-    error_msg_div_id: string;
-    step1_id: string;
-    step2_id: string;
-    step3_id: string;
-    step_complete_class: string;
-    waiting_for_access_msg_id: string;
-    checking_mic_msg_id: string;
-    access_problem_msg_id: string;
-    setup_problem_msg_id: string;
-    chromeInitialPrompt: any;
-    chromeAlwaysAllow: any;
-    chromePermissions: any;
-    firefoxInitialPrompt: any;
-    firefoxChooseDevice: any;
-    firefoxDevicesBlocked: any;
-    checkmarkIcon: any;
-};
-/**
- * **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 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;
-    /**
-     * 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.
-     */
-    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;
-}
-export {};