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

package/dist/index.d.ts

@@ -1,35 +1,49 @@
-import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
+import { JsPsychPlugin, ParameterType, JsPsych, TrialType } from 'jspsych';
+
 declare const info: {
     readonly name: "audio-keyboard-response";
+    readonly version: string;
     readonly parameters: {
         /** The audio file to be played. */
         readonly stimulus: {
             readonly type: ParameterType.AUDIO;
-            readonly pretty_name: "Stimulus";
             readonly default: any;
         };
-        /** 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.
+         */
         readonly choices: {
             readonly type: ParameterType.KEYS;
-            readonly pretty_name: "Choices";
             readonly 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).
+         */
         readonly prompt: {
             readonly type: ParameterType.HTML_STRING;
             readonly pretty_name: "Prompt";
             readonly default: any;
         };
-        /** 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.
+         */
         readonly trial_duration: {
             readonly type: ParameterType.INT;
-            readonly pretty_name: "Trial duration";
             readonly default: any;
         };
-        /** 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
+         */
         readonly response_ends_trial: {
             readonly type: ParameterType.BOOL;
-            readonly pretty_name: "Response ends trial";
             readonly default: true;
         };
         /** If true, then the trial will end as soon as the audio file finishes playing. */
@@ -38,56 +52,97 @@ declare const info: {
             readonly pretty_name: "Trial ends after audio";
             readonly 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).
+         */
         readonly response_allowed_while_playing: {
             readonly type: ParameterType.BOOL;
-            readonly pretty_name: "Response allowed while playing";
             readonly default: true;
         };
     };
+    readonly data: {
+        /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
+        readonly response: {
+            readonly 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`.
+         */
+        readonly rt: {
+            readonly type: ParameterType.INT;
+        };
+        /** Path to the audio file that played during the trial. */
+        readonly stimulus: {
+            readonly 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.
  *
- * jsPsych plugin for playing an audio file and getting a keyboard response
+ * 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.
+ *
+ * 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}
  */
 declare class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
     private jsPsych;
     static info: {
         readonly name: "audio-keyboard-response";
+        readonly version: string;
         readonly parameters: {
             /** The audio file to be played. */
             readonly stimulus: {
                 readonly type: ParameterType.AUDIO;
-                readonly pretty_name: "Stimulus";
                 readonly default: any;
             };
-            /** 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.
+             */
             readonly choices: {
                 readonly type: ParameterType.KEYS;
-                readonly pretty_name: "Choices";
                 readonly 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).
+             */
             readonly prompt: {
                 readonly type: ParameterType.HTML_STRING;
                 readonly pretty_name: "Prompt";
                 readonly default: any;
             };
-            /** 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.
+             */
             readonly trial_duration: {
                 readonly type: ParameterType.INT;
-                readonly pretty_name: "Trial duration";
                 readonly default: any;
             };
-            /** 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
+             */
             readonly response_ends_trial: {
                 readonly type: ParameterType.BOOL;
-                readonly pretty_name: "Response ends trial";
                 readonly default: true;
             };
             /** If true, then the trial will end as soon as the audio file finishes playing. */
@@ -96,20 +151,48 @@ declare class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
                 readonly pretty_name: "Trial ends after audio";
                 readonly 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).
+             */
             readonly response_allowed_while_playing: {
                 readonly type: ParameterType.BOOL;
-                readonly pretty_name: "Response allowed while playing";
                 readonly default: true;
             };
         };
+        readonly data: {
+            /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
+            readonly response: {
+                readonly 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`.
+             */
+            readonly rt: {
+                readonly type: ParameterType.INT;
+            };
+            /** Path to the audio file that played during the trial. */
+            readonly stimulus: {
+                readonly type: ParameterType.STRING;
+            };
+        };
     };
     private audio;
+    private params;
+    private display;
+    private response;
+    private startTime;
+    private finish;
     constructor(jsPsych: JsPsych);
     trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void): Promise<unknown>;
-    simulate(trial: TrialType<Info>, simulation_mode: any, simulation_options: any, load_callback: () => void): void;
+    private end_trial;
+    private after_response;
+    private setup_keyboard_listener;
+    simulate(trial: TrialType<Info>, simulation_mode: any, simulation_options: any, load_callback: () => void): Promise<any>;
     private simulate_data_only;
     private simulate_visual;
     private create_simulation_data;
 }
-export default AudioKeyboardResponsePlugin;
+
+export { AudioKeyboardResponsePlugin as default };

package/dist/index.js

@@ -1,233 +1,212 @@
+import autoBind from 'auto-bind';
 import { ParameterType } from 'jspsych';
 
+var _package = {
+  name: "@jspsych/plugin-audio-keyboard-response",
+  version: "2.0.0",
+  description: "jsPsych plugin for playing an audio file and getting a keyboard response",
+  type: "module",
+  main: "dist/index.cjs",
+  exports: {
+    import: "./dist/index.js",
+    require: "./dist/index.cjs"
+  },
+  typings: "dist/index.d.ts",
+  unpkg: "dist/index.browser.min.js",
+  files: [
+    "src",
+    "dist"
+  ],
+  source: "src/index.ts",
+  scripts: {
+    test: "jest",
+    "test:watch": "npm test -- --watch",
+    tsc: "tsc",
+    build: "rollup --config",
+    "build:watch": "npm run build -- --watch"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/jspsych/jsPsych.git",
+    directory: "packages/plugin-audio-keyboard-response"
+  },
+  author: "Josh de Leeuw",
+  license: "MIT",
+  bugs: {
+    url: "https://github.com/jspsych/jsPsych/issues"
+  },
+  homepage: "https://www.jspsych.org/latest/plugins/audio-keyboard-response",
+  peerDependencies: {
+    jspsych: ">=7.1.0"
+  },
+  devDependencies: {
+    "@jspsych/config": "^3.0.0",
+    "@jspsych/test-utils": "^1.2.0"
+  }
+};
+
 const info = {
-    name: "audio-keyboard-response",
-    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. */
-        choices: {
-            type: ParameterType.KEYS,
-            pretty_name: "Choices",
-            default: "ALL_KEYS",
-        },
-        /** Any content here will be displayed below the stimulus. */
-        prompt: {
-            type: ParameterType.HTML_STRING,
-            pretty_name: "Prompt",
-            default: null,
-        },
-        /** The maximum duration to wait for a response. */
-        trial_duration: {
-            type: ParameterType.INT,
-            pretty_name: "Trial duration",
-            default: null,
-        },
-        /** If true, the trial will end when user makes a response. */
-        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. */
-        trial_ends_after_audio: {
-            type: ParameterType.BOOL,
-            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. */
-        response_allowed_while_playing: {
-            type: ParameterType.BOOL,
-            pretty_name: "Response allowed while playing",
-            default: true,
-        },
+  name: "audio-keyboard-response",
+  version: _package.version,
+  parameters: {
+    stimulus: {
+      type: ParameterType.AUDIO,
+      default: void 0
     },
-};
-/**
- * **audio-keyboard-response**
- *
- * jsPsych plugin for playing an audio file and getting a keyboard response
- *
- * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}
- */
-class AudioKeyboardResponsePlugin {
-    constructor(jsPsych) {
-        this.jsPsych = jsPsych;
+    choices: {
+      type: ParameterType.KEYS,
+      default: "ALL_KEYS"
+    },
+    prompt: {
+      type: ParameterType.HTML_STRING,
+      pretty_name: "Prompt",
+      default: null
+    },
+    trial_duration: {
+      type: ParameterType.INT,
+      default: null
+    },
+    response_ends_trial: {
+      type: ParameterType.BOOL,
+      default: true
+    },
+    trial_ends_after_audio: {
+      type: ParameterType.BOOL,
+      pretty_name: "Trial ends after audio",
+      default: false
+    },
+    response_allowed_while_playing: {
+      type: ParameterType.BOOL,
+      default: true
     }
-    trial(display_element, trial, on_load) {
-        // hold the .resolve() function from the Promise that ends the trial
-        let trial_complete;
-        // 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);
-            }
-            // show prompt if there is one
-            if (trial.prompt !== null) {
-                display_element.innerHTML = trial.prompt;
-            }
-            // start audio
-            if (context !== null) {
-                startTime = context.currentTime;
-                this.audio.start(startTime);
-            }
-            else {
-                this.audio.play();
-            }
-            // start keyboard listener when trial starts or sound ends
-            if (trial.response_allowed_while_playing) {
-                setup_keyboard_listener();
-            }
-            else if (!trial.trial_ends_after_audio) {
-                this.audio.addEventListener("ended", setup_keyboard_listener);
-            }
-            // end trial if time limit is set
-            if (trial.trial_duration !== null) {
-                this.jsPsych.pluginAPI.setTimeout(() => {
-                    end_trial();
-                }, trial.trial_duration);
-            }
-            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);
-            // kill keyboard listeners
-            this.jsPsych.pluginAPI.cancelAllKeyboardResponses();
-            // gather the data to store for the trial
-            var trial_data = {
-                rt: response.rt,
-                stimulus: trial.stimulus,
-                response: response.key,
-            };
-            // clear the display
-            display_element.innerHTML = "";
-            // move on to the next trial
-            this.jsPsych.finishTrial(trial_data);
-            trial_complete();
-        };
-        // function to handle responses by the subject
-        function after_response(info) {
-            // only record the first response
-            if (response.key == null) {
-                response = info;
-            }
-            if (trial.response_ends_trial) {
-                end_trial();
-            }
-        }
-        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,
-                });
-            }
-        };
-        return new Promise((resolve) => {
-            trial_complete = resolve;
-        });
+  },
+  data: {
+    response: {
+      type: ParameterType.STRING
+    },
+    rt: {
+      type: ParameterType.INT
+    },
+    stimulus: {
+      type: ParameterType.STRING
     }
-    simulate(trial, simulation_mode, simulation_options, load_callback) {
-        if (simulation_mode == "data-only") {
-            load_callback();
-            this.simulate_data_only(trial, simulation_options);
-        }
-        if (simulation_mode == "visual") {
-            this.simulate_visual(trial, simulation_options, load_callback);
-        }
+  }
+};
+class AudioKeyboardResponsePlugin {
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+    this.response = { rt: null, key: null };
+    autoBind(this);
+  }
+  trial(display_element, trial, on_load) {
+    return new Promise(async (resolve) => {
+      this.finish = resolve;
+      this.params = trial;
+      this.display = display_element;
+      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);
+      if (trial.trial_ends_after_audio) {
+        this.audio.addEventListener("ended", this.end_trial);
+      }
+      if (trial.prompt !== null) {
+        display_element.innerHTML = trial.prompt;
+      }
+      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;
+      if (trial.response_allowed_while_playing) {
+        this.setup_keyboard_listener();
+      } else if (!trial.trial_ends_after_audio) {
+        this.audio.addEventListener("ended", this.setup_keyboard_listener);
+      }
+      if (trial.trial_duration !== null) {
+        this.jsPsych.pluginAPI.setTimeout(() => {
+          this.end_trial();
+        }, trial.trial_duration);
+      }
+      on_load();
+      this.audio.play();
+    });
+  }
+  end_trial() {
+    this.jsPsych.pluginAPI.clearAllTimeouts();
+    this.audio.stop();
+    this.audio.removeEventListener("ended", this.end_trial);
+    this.audio.removeEventListener("ended", this.setup_keyboard_listener);
+    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();
+    var trial_data = {
+      rt: this.response.rt,
+      response: this.response.key,
+      stimulus: this.params.stimulus
+    };
+    this.display.innerHTML = "";
+    this.finish(trial_data);
+  }
+  after_response(info2) {
+    this.response = info2;
+    if (this.params.response_ends_trial) {
+      this.end_trial();
     }
-    simulate_data_only(trial, simulation_options) {
-        const data = this.create_simulation_data(trial, simulation_options);
-        this.jsPsych.finishTrial(data);
+  }
+  setup_keyboard_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_visual(trial, simulation_options, load_callback) {
-        const data = this.create_simulation_data(trial, simulation_options);
-        const display_element = this.jsPsych.getDisplayElement();
-        const respond = () => {
-            if (data.rt !== null) {
-                this.jsPsych.pluginAPI.pressKey(data.response, data.rt);
-            }
-        };
-        this.trial(display_element, trial, () => {
-            load_callback();
-            if (!trial.response_allowed_while_playing) {
-                this.audio.addEventListener("ended", respond);
-            }
-            else {
-                respond();
-            }
-        });
+  }
+  async simulate(trial, simulation_mode, simulation_options, load_callback) {
+    if (simulation_mode == "data-only") {
+      load_callback();
+      return this.simulate_data_only(trial, simulation_options);
     }
-    create_simulation_data(trial, simulation_options) {
-        const default_data = {
-            stimulus: trial.stimulus,
-            rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-            response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
-        };
-        const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
-        this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
-        return data;
+    if (simulation_mode == "visual") {
+      return this.simulate_visual(trial, simulation_options, load_callback);
     }
+  }
+  simulate_data_only(trial, simulation_options) {
+    const data = this.create_simulation_data(trial, simulation_options);
+    return data;
+  }
+  async simulate_visual(trial, simulation_options, load_callback) {
+    const data = this.create_simulation_data(trial, simulation_options);
+    const display_element = this.jsPsych.getDisplayElement();
+    const respond = () => {
+      if (data.rt !== null) {
+        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);
+      }
+    };
+    const result = await this.trial(display_element, trial, () => {
+      load_callback();
+      if (!trial.response_allowed_while_playing) {
+        this.audio.addEventListener("ended", respond);
+      } else {
+        respond();
+      }
+    });
+    return result;
+  }
+  create_simulation_data(trial, simulation_options) {
+    const default_data = {
+      stimulus: trial.stimulus,
+      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+    };
+    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
+    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
+    return data;
+  }
 }
 AudioKeyboardResponsePlugin.info = info;