jspsych 6.2.0 → 7.1.0

package/src/modules/plugin-api/KeyboardListenerAPI.ts

@@ -0,0 +1,165 @@
+import autoBind from "auto-bind";
+
+export type KeyboardListener = (e: KeyboardEvent) => void;
+
+export type ValidResponses = string[] | "ALL_KEYS" | "NO_KEYS";
+
+export interface GetKeyboardResponseOptions {
+  callback_function: any;
+  valid_responses?: ValidResponses;
+  rt_method?: "performance" | "audio";
+  persist?: boolean;
+  audio_context?: AudioContext;
+  audio_context_start_time?: number;
+  allow_held_key?: boolean;
+  minimum_valid_rt?: number;
+}
+
+export class KeyboardListenerAPI {
+  constructor(
+    private getRootElement: () => Element | undefined,
+    private areResponsesCaseSensitive: boolean = false,
+    private minimumValidRt = 0
+  ) {
+    autoBind(this);
+    this.registerRootListeners();
+  }
+
+  private listeners = new Set<KeyboardListener>();
+  private heldKeys = new Set<string>();
+
+  private areRootListenersRegistered = false;
+
+  /**
+   * If not previously done and `this.getRootElement()` returns an element, adds the root key
+   * listeners to that element.
+   */
+  private registerRootListeners() {
+    if (!this.areRootListenersRegistered) {
+      const rootElement = this.getRootElement();
+      if (rootElement) {
+        rootElement.addEventListener("keydown", this.rootKeydownListener);
+        rootElement.addEventListener("keyup", this.rootKeyupListener);
+        this.areRootListenersRegistered = true;
+      }
+    }
+  }
+
+  private rootKeydownListener(e: KeyboardEvent) {
+    // Iterate over a static copy of the listeners set because listeners might add other listeners
+    // that we do not want to be included in the loop
+    for (const listener of Array.from(this.listeners)) {
+      listener(e);
+    }
+    this.heldKeys.add(this.toLowerCaseIfInsensitive(e.key));
+  }
+
+  private toLowerCaseIfInsensitive(string: string) {
+    return this.areResponsesCaseSensitive ? string : string.toLowerCase();
+  }
+
+  private rootKeyupListener(e: KeyboardEvent) {
+    this.heldKeys.delete(this.toLowerCaseIfInsensitive(e.key));
+  }
+
+  private isResponseValid(validResponses: ValidResponses, allowHeldKey: boolean, key: string) {
+    // check if key was already held down
+    if (!allowHeldKey && this.heldKeys.has(key)) {
+      return false;
+    }
+
+    if (validResponses === "ALL_KEYS") {
+      return true;
+    }
+    if (validResponses === "NO_KEYS") {
+      return false;
+    }
+
+    return validResponses.includes(key);
+  }
+
+  getKeyboardResponse({
+    callback_function,
+    valid_responses = "ALL_KEYS",
+    rt_method = "performance",
+    persist,
+    audio_context,
+    audio_context_start_time,
+    allow_held_key = false,
+    minimum_valid_rt = this.minimumValidRt,
+  }: GetKeyboardResponseOptions) {
+    if (rt_method !== "performance" && rt_method !== "audio") {
+      console.log(
+        'Invalid RT method specified in getKeyboardResponse. Defaulting to "performance" method.'
+      );
+      rt_method = "performance";
+    }
+
+    const usePerformanceRt = rt_method === "performance";
+    const startTime = usePerformanceRt ? performance.now() : audio_context_start_time * 1000;
+
+    this.registerRootListeners();
+
+    if (!this.areResponsesCaseSensitive && typeof valid_responses !== "string") {
+      valid_responses = valid_responses.map((r) => r.toLowerCase());
+    }
+
+    const listener: KeyboardListener = (e) => {
+      const rt = Math.round(
+        (rt_method == "performance" ? performance.now() : audio_context.currentTime * 1000) -
+          startTime
+      );
+      if (rt < minimum_valid_rt) {
+        return;
+      }
+
+      const key = this.toLowerCaseIfInsensitive(e.key);
+
+      if (this.isResponseValid(valid_responses, allow_held_key, key)) {
+        // if this is a valid response, then we don't want the key event to trigger other actions
+        // like scrolling via the spacebar.
+        e.preventDefault();
+
+        if (!persist) {
+          // remove keyboard listener if it exists
+          this.cancelKeyboardResponse(listener);
+        }
+
+        callback_function({ key, rt });
+      }
+    };
+
+    this.listeners.add(listener);
+    return listener;
+  }
+
+  cancelKeyboardResponse(listener: KeyboardListener) {
+    // remove the listener from the set of listeners if it is contained
+    this.listeners.delete(listener);
+  }
+
+  cancelAllKeyboardResponses() {
+    this.listeners.clear();
+  }
+
+  compareKeys(key1: string | null, key2: string | null) {
+    if (
+      (typeof key1 !== "string" && key1 !== null) ||
+      (typeof key2 !== "string" && key2 !== null)
+    ) {
+      console.error(
+        "Error in jsPsych.pluginAPI.compareKeys: arguments must be key strings or null."
+      );
+      return undefined;
+    }
+
+    if (typeof key1 === "string" && typeof key2 === "string") {
+      // if both values are strings, then check whether or not letter case should be converted before comparing (case_sensitive_responses in initJsPsych)
+      return this.areResponsesCaseSensitive
+        ? key1 === key2
+        : key1.toLowerCase() === key2.toLowerCase();
+    }
+
+    return key1 === null && key2 === null;
+  }
+}

package/src/modules/plugin-api/MediaAPI.ts

@@ -0,0 +1,337 @@
+import { ParameterType } from "../../modules/plugins";
+import { unique } from "../utils";
+
+const preloadParameterTypes = <const>[
+  ParameterType.AUDIO,
+  ParameterType.IMAGE,
+  ParameterType.VIDEO,
+];
+type PreloadType = typeof preloadParameterTypes[number];
+
+export class MediaAPI {
+  constructor(private useWebaudio: boolean, private webaudioContext?: AudioContext) {}
+
+  // video //
+  private video_buffers = {};
+  getVideoBuffer(videoID) {
+    return this.video_buffers[videoID];
+  }
+
+  // audio //
+  private context = null;
+  private audio_buffers = [];
+
+  initAudio() {
+    this.context = this.useWebaudio ? this.webaudioContext : null;
+  }
+
+  audioContext() {
+    if (this.context !== null) {
+      if (this.context.state !== "running") {
+        this.context.resume();
+      }
+    }
+    return this.context;
+  }
+
+  getAudioBuffer(audioID) {
+    return new Promise((resolve, reject) => {
+      // check whether audio file already preloaded
+      if (
+        typeof this.audio_buffers[audioID] == "undefined" ||
+        this.audio_buffers[audioID] == "tmp"
+      ) {
+        // if audio is not already loaded, try to load it
+        this.preloadAudio(
+          [audioID],
+          () => {
+            resolve(this.audio_buffers[audioID]);
+          },
+          () => {},
+          (e) => {
+            reject(e.error);
+          }
+        );
+      } else {
+        // audio is already loaded
+        resolve(this.audio_buffers[audioID]);
+      }
+    });
+  }
+
+  // preloading stimuli //
+  private preload_requests = [];
+
+  private img_cache = {};
+
+  preloadAudio(
+    files,
+    callback_complete = () => {},
+    callback_load = (filepath) => {},
+    callback_error = (error_msg) => {}
+  ) {
+    files = unique(files.flat());
+
+    let n_loaded = 0;
+
+    if (files.length == 0) {
+      callback_complete();
+      return;
+    }
+
+    const load_audio_file_webaudio = (source, count = 1) => {
+      const request = new XMLHttpRequest();
+      request.open("GET", source, true);
+      request.responseType = "arraybuffer";
+      request.onload = () => {
+        this.context.decodeAudioData(
+          request.response,
+          (buffer) => {
+            this.audio_buffers[source] = buffer;
+            n_loaded++;
+            callback_load(source);
+            if (n_loaded == files.length) {
+              callback_complete();
+            }
+          },
+          (e) => {
+            callback_error({ source: source, error: e });
+          }
+        );
+      };
+      request.onerror = function (e) {
+        let err: ProgressEvent | string = e;
+        if (this.status == 404) {
+          err = "404";
+        }
+        callback_error({ source: source, error: err });
+      };
+      request.onloadend = function (e) {
+        if (this.status == 404) {
+          callback_error({ source: source, error: "404" });
+        }
+      };
+      request.send();
+      this.preload_requests.push(request);
+    };
+
+    const load_audio_file_html5audio = (source, count = 1) => {
+      const audio = new Audio();
+      const handleCanPlayThrough = () => {
+        this.audio_buffers[source] = audio;
+        n_loaded++;
+        callback_load(source);
+        if (n_loaded == files.length) {
+          callback_complete();
+        }
+        audio.removeEventListener("canplaythrough", handleCanPlayThrough);
+      };
+      audio.addEventListener("canplaythrough", handleCanPlayThrough);
+      audio.addEventListener("error", function handleError(e) {
+        callback_error({ source: audio.src, error: e });
+        audio.removeEventListener("error", handleError);
+      });
+      audio.addEventListener("abort", function handleAbort(e) {
+        callback_error({ source: audio.src, error: e });
+        audio.removeEventListener("abort", handleAbort);
+      });
+      audio.src = source;
+      this.preload_requests.push(audio);
+    };
+
+    for (const file of files) {
+      if (typeof this.audio_buffers[file] !== "undefined") {
+        n_loaded++;
+        callback_load(file);
+        if (n_loaded == files.length) {
+          callback_complete();
+        }
+      } else {
+        this.audio_buffers[file] = "tmp";
+        if (this.audioContext() !== null) {
+          load_audio_file_webaudio(file);
+        } else {
+          load_audio_file_html5audio(file);
+        }
+      }
+    }
+  }
+
+  preloadImages(
+    images,
+    callback_complete = () => {},
+    callback_load = (filepath) => {},
+    callback_error = (error_msg) => {}
+  ) {
+    // flatten the images array
+    images = unique(images.flat());
+
+    var n_loaded = 0;
+
+    if (images.length === 0) {
+      callback_complete();
+      return;
+    }
+
+    for (var i = 0; i < images.length; i++) {
+      var img = new Image();
+
+      img.onload = function () {
+        n_loaded++;
+        callback_load(img.src);
+        if (n_loaded === images.length) {
+          callback_complete();
+        }
+      };
+
+      img.onerror = function (e) {
+        callback_error({ source: img.src, error: e });
+      };
+
+      img.src = images[i];
+
+      this.img_cache[images[i]] = img;
+      this.preload_requests.push(img);
+    }
+  }
+
+  preloadVideo(
+    videos,
+    callback_complete = () => {},
+    callback_load = (filepath) => {},
+    callback_error = (error_msg) => {}
+  ) {
+    // flatten the video array
+    videos = unique(videos.flat());
+
+    let n_loaded = 0;
+
+    if (videos.length === 0) {
+      callback_complete();
+      return;
+    }
+
+    for (const video of videos) {
+      const video_buffers = this.video_buffers;
+
+      //based on option 4 here: http://dinbror.dk/blog/how-to-preload-entire-html5-video-before-play-solved/
+      const request = new XMLHttpRequest();
+      request.open("GET", video, true);
+      request.responseType = "blob";
+      request.onload = function () {
+        if (this.status === 200 || this.status === 0) {
+          const videoBlob = this.response;
+          video_buffers[video] = URL.createObjectURL(videoBlob); // IE10+
+          n_loaded++;
+          callback_load(video);
+          if (n_loaded === videos.length) {
+            callback_complete();
+          }
+        }
+      };
+      request.onerror = function (e) {
+        let err: ProgressEvent | string = e;
+        if (this.status == 404) {
+          err = "404";
+        }
+        callback_error({ source: video, error: err });
+      };
+      request.onloadend = function (e) {
+        if (this.status == 404) {
+          callback_error({ source: video, error: "404" });
+        }
+      };
+      request.send();
+      this.preload_requests.push(request);
+    }
+  }
+
+  private preloadMap = new Map<string, Record<string, PreloadType>>();
+
+  getAutoPreloadList(timeline_description: any[]) {
+    /** Map each preload parameter type to a set of paths to be preloaded */
+    const preloadPaths = Object.fromEntries(
+      preloadParameterTypes.map((type) => [type, new Set<string>()])
+    );
+
+    const traverseTimeline = (node, inheritedTrialType?) => {
+      const isTimeline = typeof node.timeline !== "undefined";
+
+      if (isTimeline) {
+        for (const childNode of node.timeline) {
+          traverseTimeline(childNode, node.type ?? inheritedTrialType);
+        }
+      } else if ((node.type ?? inheritedTrialType)?.info) {
+        // node is a trial with type.info set
+
+        // Get the plugin name and parameters object from the info object
+        const { name: pluginName, parameters } = (node.type ?? inheritedTrialType).info;
+
+        // Extract parameters to be preloaded and their types from parameter info if this has not
+        // yet been done for `pluginName`
+        if (!this.preloadMap.has(pluginName)) {
+          this.preloadMap.set(
+            pluginName,
+            Object.fromEntries(
+              Object.entries<any>(parameters)
+                // Filter out parameter entries with media types and a non-false `preload` option
+                .filter(
+                  ([_name, { type, preload }]) =>
+                    preloadParameterTypes.includes(type) && (preload ?? true)
+                )
+                // Map each entry's value to its parameter type
+                .map(([name, { type }]) => [name, type])
+            )
+          );
+        }
+
+        // Add preload paths from this trial
+        for (const [parameterName, parameterType] of Object.entries(
+          this.preloadMap.get(pluginName)
+        )) {
+          const parameterValue = node[parameterName];
+          const elements = preloadPaths[parameterType];
+
+          if (typeof parameterValue === "string") {
+            elements.add(parameterValue);
+          } else if (Array.isArray(parameterValue)) {
+            for (const element of parameterValue.flat()) {
+              if (typeof element === "string") {
+                elements.add(element);
+              }
+            }
+          }
+        }
+      }
+    };
+
+    traverseTimeline({ timeline: timeline_description });
+
+    return {
+      images: [...preloadPaths[ParameterType.IMAGE]],
+      audio: [...preloadPaths[ParameterType.AUDIO]],
+      video: [...preloadPaths[ParameterType.VIDEO]],
+    };
+  }
+
+  cancelPreloads() {
+    for (const request of this.preload_requests) {
+      request.onload = () => {};
+      request.onerror = () => {};
+      request.oncanplaythrough = () => {};
+      request.onabort = () => {};
+    }
+    this.preload_requests = [];
+  }
+
+  private microphone_recorder: MediaRecorder = null;
+
+  initializeMicrophoneRecorder(stream: MediaStream) {
+    const recorder = new MediaRecorder(stream);
+    this.microphone_recorder = recorder;
+  }
+
+  getMicrophoneRecorder(): MediaRecorder {
+    return this.microphone_recorder;
+  }
+}

package/src/modules/plugin-api/SimulationAPI.ts

@@ -0,0 +1,181 @@
+export class SimulationAPI {
+  dispatchEvent(event: Event) {
+    document.body.dispatchEvent(event);
+  }
+
+  /**
+   * Dispatches a `keydown` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
+  keyDown(key: string) {
+    this.dispatchEvent(new KeyboardEvent("keydown", { key }));
+  }
+
+  /**
+   * Dispatches a `keyup` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
+  keyUp(key: string) {
+    this.dispatchEvent(new KeyboardEvent("keyup", { key }));
+  }
+
+  /**
+   * Dispatches a `keydown` and `keyup` event in sequence to simulate pressing a key.
+   * @param key Character code (`.key` property) for the key to press.
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  pressKey(key: string, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        this.keyDown(key);
+        this.keyUp(key);
+      }, delay);
+    } else {
+      this.keyDown(key);
+      this.keyUp(key);
+    }
+  }
+
+  /**
+   * Dispatches `mousedown`, `mouseup`, and `click` events on the target element
+   * @param target The element to click
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  clickTarget(target: Element, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+        target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
+        target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      }, delay);
+    } else {
+      target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+      target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
+      target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    }
+  }
+
+  /**
+   * Sets the value of a target text input
+   * @param target A text input element to fill in
+   * @param text Text to input
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  fillTextInput(target: HTMLInputElement, text: string, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        target.value = text;
+      }, delay);
+    } else {
+      target.value = text;
+    }
+  }
+
+  /**
+   * Picks a valid key from `choices`, taking into account jsPsych-specific
+   * identifiers like "NO_KEYS" and "ALL_KEYS".
+   * @param choices Which keys are valid.
+   * @returns A key selected at random from the valid keys.
+   */
+  getValidKey(choices: "NO_KEYS" | "ALL_KEYS" | Array<string> | Array<Array<string>>) {
+    const possible_keys = [
+      "a",
+      "b",
+      "c",
+      "d",
+      "e",
+      "f",
+      "g",
+      "h",
+      "i",
+      "j",
+      "k",
+      "l",
+      "m",
+      "n",
+      "o",
+      "p",
+      "q",
+      "r",
+      "s",
+      "t",
+      "u",
+      "v",
+      "w",
+      "x",
+      "y",
+      "z",
+      "0",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+      " ",
+    ];
+
+    let key;
+    if (choices == "NO_KEYS") {
+      key = null;
+    } else if (choices == "ALL_KEYS") {
+      key = possible_keys[Math.floor(Math.random() * possible_keys.length)];
+    } else {
+      const flat_choices = choices.flat();
+      key = flat_choices[Math.floor(Math.random() * flat_choices.length)];
+    }
+
+    return key;
+  }
+
+  mergeSimulationData(default_data, simulation_options) {
+    // override any data with data from simulation object
+    return {
+      ...default_data,
+      ...simulation_options?.data,
+    };
+  }
+
+  ensureSimulationDataConsistency(trial, data) {
+    // All RTs must be rounded
+    if (data.rt) {
+      data.rt = Math.round(data.rt);
+    }
+
+    // If a trial_duration and rt exist, make sure that the RT is not longer than the trial.
+    if (trial.trial_duration && data.rt && data.rt > trial.trial_duration) {
+      data.rt = null;
+      if (data.response) {
+        data.response = null;
+      }
+      if (data.correct) {
+        data.correct = false;
+      }
+    }
+
+    // If trial.choices is NO_KEYS make sure that response and RT are null
+    if (trial.choices && trial.choices == "NO_KEYS") {
+      if (data.rt) {
+        data.rt = null;
+      }
+      if (data.response) {
+        data.response = null;
+      }
+    }
+
+    // If response is not allowed before stimulus display complete, ensure RT
+    // is longer than display time.
+    if (trial.allow_response_before_complete) {
+      if (trial.sequence_reps && trial.frame_time) {
+        const min_time = trial.sequence_reps * trial.frame_time * trial.stimuli.length;
+        if (data.rt < min_time) {
+          data.rt = null;
+          data.response = null;
+        }
+      }
+    }
+  }
+}

package/src/modules/plugin-api/TimeoutAPI.ts

@@ -0,0 +1,16 @@
+export class TimeoutAPI {
+  private timeout_handlers = [];
+
+  setTimeout(callback, delay) {
+    const handle = window.setTimeout(callback, delay);
+    this.timeout_handlers.push(handle);
+    return handle;
+  }
+
+  clearAllTimeouts() {
+    for (const handler of this.timeout_handlers) {
+      clearTimeout(handler);
+    }
+    this.timeout_handlers = [];
+  }
+}