@jspsych/plugin-audio-keyboard-response 1.1.2 → 2.0.0

package/src/index.spec.ts

@@ -1,10 +1,131 @@
-import { pressKey, simulateTimeline, startTimeline } from "@jspsych/test-utils";
+jest.mock("../../jspsych/src/modules/plugin-api/AudioPlayer");
+
+import { flushPromises, pressKey, simulateTimeline, startTimeline } from "@jspsych/test-utils";
 import { initJsPsych } from "jspsych";
 
+//@ts-expect-error mock
+import { mockStop } from "../../jspsych/src/modules/plugin-api/AudioPlayer";
 import audioKeyboardResponse from ".";
 
 jest.useFakeTimers();
 
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe("audio-keyboard-response", () => {
+  // this relies on AudioContext, which we haven't mocked yet
+  it.skip("works with all defaults", async () => {
+    const { expectFinished, expectRunning } = await startTimeline([
+      {
+        type: audioKeyboardResponse,
+        stimulus: "foo.mp3",
+      },
+    ]);
+
+    expectRunning();
+
+    pressKey("a");
+
+    expectFinished();
+
+    await flushPromises();
+  });
+
+  it("works with use_webaudio:false", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { expectFinished, expectRunning } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+        },
+      ],
+      jsPsych
+    );
+
+    await expectRunning();
+    pressKey("a");
+    await expectFinished();
+  });
+
+  it("ends when trial_ends_after_audio is true and audio finishes", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { expectFinished, expectRunning } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          trial_ends_after_audio: true,
+        },
+      ],
+      jsPsych
+    );
+
+    await expectRunning();
+
+    jest.runAllTimers();
+
+    await expectFinished();
+  });
+
+  it("prevents responses when response_allowed_while_playing is false", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { expectFinished, expectRunning } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          response_allowed_while_playing: false,
+        },
+      ],
+      jsPsych
+    );
+
+    await expectRunning();
+
+    pressKey("a");
+
+    await expectRunning();
+
+    jest.runAllTimers();
+
+    await expectRunning();
+
+    pressKey("a");
+
+    await expectFinished();
+  });
+
+  it("ends when trial_duration is shorter than the audio duration, stopping the audio", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { expectFinished, expectRunning } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          trial_duration: 500,
+        },
+      ],
+      jsPsych
+    );
+
+    await expectRunning();
+
+    expect(mockStop).not.toHaveBeenCalled();
+
+    jest.advanceTimersByTime(500);
+
+    expect(mockStop).toHaveBeenCalled();
+
+    await expectFinished();
+  });
+});
+
 describe("audio-keyboard-response simulation", () => {
   test("data mode works", async () => {
     const timeline = [
@@ -22,8 +143,7 @@ describe("audio-keyboard-response simulation", () => {
     expect(typeof getData().values()[0].response).toBe("string");
   });
 
-  // can't run this until we mock Audio elements.
-  test.skip("visual mode works", async () => {
+  test("visual mode works", async () => {
     const jsPsych = initJsPsych({ use_webaudio: false });
 
     const timeline = [

package/src/index.ts

@@ -1,36 +1,53 @@
+import autoBind from "auto-bind";
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { AudioPlayerInterface } from "../../jspsych/src/modules/plugin-api/AudioPlayer";
+import { version } from "../package.json";
+
 const info = <const>{
   name: "audio-keyboard-response",
+  version: version,
   parameters: {
     /** The audio file to be played. */
     stimulus: {
       type: ParameterType.AUDIO,
-      pretty_name: "Stimulus",
       default: undefined,
     },
-    /** Array containing the key(s) the subject is allowed to press to respond to the stimulus. */
+    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.
+     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -
+     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)
+     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)
+     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `"ALL_KEYS"`
+     * means that all keys will be accepted as valid responses. Specifying `"NO_KEYS"` will mean that no responses are allowed.
+     */
     choices: {
       type: ParameterType.KEYS,
-      pretty_name: "Choices",
       default: "ALL_KEYS",
     },
-    /** Any content here will be displayed below the stimulus. */
+    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that
+     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).
+     */
     prompt: {
       type: ParameterType.HTML_STRING,
       pretty_name: "Prompt",
       default: null,
     },
-    /** The maximum duration to wait for a response. */
+    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the
+     * participant fails to make a response before this timer is reached, the participant's response will be
+     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the
+     * trial will wait for a response indefinitely.
+     */
     trial_duration: {
       type: ParameterType.INT,
-      pretty_name: "Trial duration",
       default: null,
     },
-    /** If true, the trial will end when user makes a response. */
+    /** If true, then the trial will end whenever the participant makes a response (assuming they make their
+     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will
+     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to
+     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete
+     */
     response_ends_trial: {
       type: ParameterType.BOOL,
-      pretty_name: "Response ends trial",
       default: true,
     },
     /** If true, then the trial will end as soon as the audio file finishes playing. */
@@ -39,72 +56,77 @@ const info = <const>{
       pretty_name: "Trial ends after audio",
       default: false,
     },
-    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before a response is accepted. */
+    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish
+     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid
+     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).
+     */
     response_allowed_while_playing: {
       type: ParameterType.BOOL,
-      pretty_name: "Response allowed while playing",
       default: true,
     },
   },
+  data: {
+    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
+    response: {
+      type: ParameterType.STRING,
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus
+     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the
+     * value will be `null`.
+     */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** Path to the audio file that played during the trial. */
+    stimulus: {
+      type: ParameterType.STRING,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **audio-keyboard-response**
+ * This plugin plays audio files and records responses generated with the keyboard.
+ *
+ * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the
+ * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of
+ * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.
+ *
+ * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using
+ * timeline variables or another dynamic method to specify the audio stimulus, then you will need to [manually preload](../overview/media-preloading.md#manual-preloading) the audio.
  *
- * jsPsych plugin for playing an audio file and getting a keyboard response
+ * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has
+ * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before
+ * the audio has finished playing.
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}
  */
 class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
   static info = info;
-  private audio;
-
-  constructor(private jsPsych: JsPsych) {}
+  private audio: AudioPlayerInterface;
+  private params: TrialType<Info>;
+  private display: HTMLElement;
+  private response: { rt: number; key: string } = { rt: null, key: null };
+  private startTime: number;
+  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;
+
+  constructor(private jsPsych: JsPsych) {
+    autoBind(this);
+  }
 
   trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {
-    // hold the .resolve() function from the Promise that ends the trial
-    let trial_complete;
+    return new Promise(async (resolve) => {
+      this.finish = resolve;
+      this.params = trial;
+      this.display = display_element;
+      // load audio file
+      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);
 
-    // setup stimulus
-    var context = this.jsPsych.pluginAPI.audioContext();
-
-    // store response
-    var response = {
-      rt: null,
-      key: null,
-    };
-
-    // record webaudio context start time
-    var startTime;
-
-    // load audio file
-    this.jsPsych.pluginAPI
-      .getAudioBuffer(trial.stimulus)
-      .then((buffer) => {
-        if (context !== null) {
-          this.audio = context.createBufferSource();
-          this.audio.buffer = buffer;
-          this.audio.connect(context.destination);
-        } else {
-          this.audio = buffer;
-          this.audio.currentTime = 0;
-        }
-        setupTrial();
-      })
-      .catch((err) => {
-        console.error(
-          `Failed to load audio file "${trial.stimulus}". Try checking the file path. We recommend using the preload plugin to load audio files.`
-        );
-        console.error(err);
-      });
-
-    const setupTrial = () => {
       // set up end event if trial needs it
       if (trial.trial_ends_after_audio) {
-        this.audio.addEventListener("ended", end_trial);
+        this.audio.addEventListener("ended", this.end_trial);
       }
 
       // show prompt if there is one
@@ -112,107 +134,91 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         display_element.innerHTML = trial.prompt;
       }
 
-      // start audio
-      if (context !== null) {
-        startTime = context.currentTime;
-        this.audio.start(startTime);
-      } else {
-        this.audio.play();
-      }
+      // start playing audio here to record time
+      // use this for offsetting RT measurement in
+      // setup_keyboard_listener
+      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;
 
       // start keyboard listener when trial starts or sound ends
       if (trial.response_allowed_while_playing) {
-        setup_keyboard_listener();
+        this.setup_keyboard_listener();
       } else if (!trial.trial_ends_after_audio) {
-        this.audio.addEventListener("ended", setup_keyboard_listener);
+        this.audio.addEventListener("ended", this.setup_keyboard_listener);
       }
 
       // end trial if time limit is set
       if (trial.trial_duration !== null) {
         this.jsPsych.pluginAPI.setTimeout(() => {
-          end_trial();
+          this.end_trial();
         }, trial.trial_duration);
       }
 
+      // call trial on_load method because we are done with all loading setup
       on_load();
-    };
-
-    // function to end trial when it is time
-    const end_trial = () => {
-      // kill any remaining setTimeout handlers
-      this.jsPsych.pluginAPI.clearAllTimeouts();
 
-      // stop the audio file if it is playing
-      // remove end event listeners if they exist
-      if (context !== null) {
-        this.audio.stop();
-      } else {
-        this.audio.pause();
-      }
-
-      this.audio.removeEventListener("ended", end_trial);
-      this.audio.removeEventListener("ended", setup_keyboard_listener);
+      this.audio.play();
+    });
+  }
 
-      // kill keyboard listeners
-      this.jsPsych.pluginAPI.cancelAllKeyboardResponses();
+  private end_trial() {
+    // kill any remaining setTimeout handlers
+    this.jsPsych.pluginAPI.clearAllTimeouts();
 
-      // gather the data to store for the trial
-      var trial_data = {
-        rt: response.rt,
-        stimulus: trial.stimulus,
-        response: response.key,
-      };
+    // stop the audio file if it is playing
+    this.audio.stop();
 
-      // clear the display
-      display_element.innerHTML = "";
+    // remove end event listeners if they exist
+    this.audio.removeEventListener("ended", this.end_trial);
+    this.audio.removeEventListener("ended", this.setup_keyboard_listener);
 
-      // move on to the next trial
-      this.jsPsych.finishTrial(trial_data);
+    // kill keyboard listeners
+    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();
 
-      trial_complete();
+    // gather the data to store for the trial
+    var trial_data = {
+      rt: this.response.rt,
+      response: this.response.key,
+      stimulus: this.params.stimulus,
     };
 
-    // function to handle responses by the subject
-    function after_response(info) {
-      // only record the first response
-      if (response.key == null) {
-        response = info;
-      }
+    // clear the display
+    this.display.innerHTML = "";
 
-      if (trial.response_ends_trial) {
-        end_trial();
-      }
-    }
+    // move on to the next trial
+    this.finish(trial_data);
+  }
 
-    const setup_keyboard_listener = () => {
-      // start the response listener
-      if (context !== null) {
-        this.jsPsych.pluginAPI.getKeyboardResponse({
-          callback_function: after_response,
-          valid_responses: trial.choices,
-          rt_method: "audio",
-          persist: false,
-          allow_held_key: false,
-          audio_context: context,
-          audio_context_start_time: startTime,
-        });
-      } else {
-        this.jsPsych.pluginAPI.getKeyboardResponse({
-          callback_function: after_response,
-          valid_responses: trial.choices,
-          rt_method: "performance",
-          persist: false,
-          allow_held_key: false,
-        });
-      }
-    };
+  private after_response(info: { key: string; rt: number }) {
+    this.response = info;
+    if (this.params.response_ends_trial) {
+      this.end_trial();
+    }
+  }
 
-    return new Promise((resolve) => {
-      trial_complete = resolve;
-    });
+  private setup_keyboard_listener() {
+    // start the response listener
+    if (this.jsPsych.pluginAPI.useWebaudio) {
+      this.jsPsych.pluginAPI.getKeyboardResponse({
+        callback_function: this.after_response,
+        valid_responses: this.params.choices,
+        rt_method: "audio",
+        persist: false,
+        allow_held_key: false,
+        audio_context: this.jsPsych.pluginAPI.audioContext(),
+        audio_context_start_time: this.startTime,
+      });
+    } else {
+      this.jsPsych.pluginAPI.getKeyboardResponse({
+        callback_function: this.after_response,
+        valid_responses: this.params.choices,
+        rt_method: "performance",
+        persist: false,
+        allow_held_key: false,
+      });
+    }
   }
 
-  simulate(
+  async simulate(
     trial: TrialType<Info>,
     simulation_mode,
     simulation_options: any,
@@ -220,20 +226,24 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
   ) {
     if (simulation_mode == "data-only") {
       load_callback();
-      this.simulate_data_only(trial, simulation_options);
+      return this.simulate_data_only(trial, simulation_options);
     }
     if (simulation_mode == "visual") {
-      this.simulate_visual(trial, simulation_options, load_callback);
+      return this.simulate_visual(trial, simulation_options, load_callback);
     }
   }
 
   private simulate_data_only(trial: TrialType<Info>, simulation_options) {
     const data = this.create_simulation_data(trial, simulation_options);
 
-    this.jsPsych.finishTrial(data);
+    return data;
   }
 
-  private simulate_visual(trial: TrialType<Info>, simulation_options, load_callback: () => void) {
+  private async simulate_visual(
+    trial: TrialType<Info>,
+    simulation_options,
+    load_callback: () => void
+  ) {
     const data = this.create_simulation_data(trial, simulation_options);
 
     const display_element = this.jsPsych.getDisplayElement();
@@ -244,7 +254,7 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
       }
     };
 
-    this.trial(display_element, trial, () => {
+    const result = await this.trial(display_element, trial, () => {
       load_callback();
       if (!trial.response_allowed_while_playing) {
         this.audio.addEventListener("ended", respond);
@@ -252,6 +262,8 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         respond();
       }
     });
+
+    return result;
   }
 
   private create_simulation_data(trial: TrialType<Info>, simulation_options) {