@lookit/record 1.0.0 → 3.0.0

package/dist/errors.d.ts

@@ -1,149 +0,0 @@
-/** Error thrown when recorder is null. */
-export declare class RecorderInitializeError extends Error {
-    /**
-     * When there isn't a recorder, provide the user with an explanation of what
-     * they could do to resolve the issue.
-     */
-    constructor();
-}
-/** Error thrown when stream is inactive and recorder is started. */
-export declare class StreamInactiveInitializeError extends Error {
-    /**
-     * Error check on initialize. Attempting to validate recorder is ready to
-     * start recording.
-     */
-    constructor();
-}
-/** Error thrown when stream data is available and recorder is started. */
-export declare class StreamDataInitializeError extends Error {
-    /**
-     * Error check on recorder initialize. Attempt to validate recorder data array
-     * is empty and ready to start recording.
-     */
-    constructor();
-}
-/**
- * Error thrown when trying to stop an active session recording that cannot be
- * found.
- */
-export declare class NoSessionRecordingError extends Error {
-    /**
-     * When trying to stop a recording that isn't found, provide the user with an
-     * explanation of what they could do to resolve the issue.
-     */
-    constructor();
-}
-/**
- * Error thrown when trying to trying to start a recording while another is
- * already active.
- */
-export declare class ExistingRecordingError extends Error {
-    /**
-     * When trying to start a recording but there is already an active recording
-     * in progress, provide the user with an explanation of what they could do to
-     * resolve the issue.
-     */
-    constructor();
-}
-/**
- * Error thrown when trying to to stop the recorder and the stop promise doesn't
- * exist.
- */
-export declare class NoStopPromiseError extends Error {
-    /**
-     * When attempting to stop a recording but there's no stop promise to ensure
-     * the stop has completed.
-     */
-    constructor();
-}
-/**
- * Error thrown when attempting an action that relies on an input stream, such
- * as the mic volume check, but no such stream is found.
- */
-export declare class NoStreamError extends Error {
-    /**
-     * When attempting an action that requires an input stream, such as the mic
-     * check, but no stream is found.
-     */
-    constructor();
-}
-/**
- * Error thrown if there's a problem setting up the microphone input level
- * check.
- */
-export declare class MicCheckError extends Error {
-    /**
-     * Occurs if there's a problem setting up the mic check, including setting up
-     * the audio context and stream source, loading the audio worklet processor
-     * script, setting up the port message event handler, and resolving the
-     * promise chain via message events passed to onMicActivityLevel.
-     *
-     * @param err - Error passed into this error that is thrown in the catch
-     *   block, if any. Errors passed to catch blocks must have type unknown.
-     */
-    constructor(err: unknown);
-}
-/**
- * Error thrown when attempting to access S3 object and it's, unknowingly,
- * undefined.
- */
-export declare class S3UndefinedError extends Error {
-    /**
-     * Provide feed back when recorder attempts to use S3 object and it's
-     * undefined.
-     */
-    constructor();
-}
-/**
- * Error thrown when attempting to reset recorder, but its stream is still
- * active.
- */
-export declare class StreamActiveOnResetError extends Error {
-    /**
-     * This error will be thrown when developer attempts to reset recorder while
-     * active.
-     */
-    constructor();
-}
-/** Error thrown when attempting to select webcam element and it's not found. */
-export declare class NoWebCamElementError extends Error {
-    /**
-     * Error thrown when attempting to retrieve webcam element and it's not in the
-     * DOM.
-     */
-    constructor();
-}
-/**
- * Error thrown when attempting to create playback/download url and data array
- * is empty.
- */
-export declare class CreateURLError extends Error {
-    /**
-     * Throw this error when data array is empty and url still needs to be
-     * created. Sometimes this means the "reset()" method was called too early.
-     */
-    constructor();
-}
-/** Error thrown when video container couldn't be found. */
-export declare class VideoContainerNotFoundError extends Error {
-    /** No video container found. */
-    constructor();
-}
-/** Error thrown when button not found. */
-export declare class ButtonNotFoundError extends Error {
-    /**
-     * Button couldn't be found by ID field.
-     *
-     * @param id - HTML ID parameter.
-     */
-    constructor(id: string);
-}
-/** Throw Error when image couldn't be found. */
-export declare class ImageNotFoundError extends Error {
-    /**
-     * Error when image couldn't be found by ID field.
-     *
-     * @param id - HTML ID parameter
-     */
-    constructor(id: string);
-}

package/dist/mic_check.d.ts

@@ -1,33 +0,0 @@
-/**
- * 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

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

@@ -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";