@jspsych/plugin-audio-keyboard-response 2.1.1 → 2.2.0

package/dist/index.browser.js

@@ -49,7 +49,7 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 
 	var autoBind$1 = /*@__PURE__*/getDefaultExportFromCjs(autoBind);
 
-	var version = "2.1.1";
+	var version = "2.2.0";
 
 	const info = {
 	  name: "audio-keyboard-response",
@@ -110,6 +110,17 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	    response_allowed_while_playing: {
 	      type: jspsych.ParameterType.BOOL,
 	      default: true
+	    },
+	    /** If true, the response is not registered until the participant releases the key. The response
+	     * time (`rt`) still reflects when the key was pressed, and the additional data field
+	     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+	     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+	     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+	     * key is still held, no response is recorded for the trial.
+	     */
+	    wait_for_key_release: {
+	      type: jspsych.ParameterType.BOOL,
+	      default: false
 	    }
 	  },
 	  data: {
@@ -127,6 +138,10 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	    /** Path to the audio file that played during the trial. */
 	    stimulus: {
 	      type: jspsych.ParameterType.STRING
+	    },
+	    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+	    rt_key_duration: {
+	      type: jspsych.ParameterType.INT
 	    }
 	  },
 	  // prettier-ignore
@@ -138,7 +153,11 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	class AudioKeyboardResponsePlugin {
 	  constructor(jsPsych) {
 	    this.jsPsych = jsPsych;
-	    this.response = { rt: null, key: null };
+	    this.response = {
+	      rt: null,
+	      key: null,
+	      rt_key_duration: null
+	    };
 	    autoBind$1(this);
 	  }
 	  static {
@@ -180,13 +199,18 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	    var trial_data = {
 	      rt: this.response.rt,
 	      response: this.response.key,
-	      stimulus: this.params.stimulus
+	      stimulus: this.params.stimulus,
+	      rt_key_duration: this.response.rt_key_duration
 	    };
 	    this.display.innerHTML = "";
 	    this.finish(trial_data);
 	  }
 	  after_response(info2) {
-	    this.response = info2;
+	    this.response = {
+	      rt: info2.rt,
+	      key: info2.key,
+	      rt_key_duration: info2.rt_key_duration ?? null
+	    };
 	    if (this.params.response_ends_trial) {
 	      this.end_trial();
 	    }
@@ -200,7 +224,8 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	        persist: false,
 	        allow_held_key: false,
 	        audio_context: this.jsPsych.pluginAPI.audioContext(),
-	        audio_context_start_time: this.startTime
+	        audio_context_start_time: this.startTime,
+	        wait_for_key_release: this.params.wait_for_key_release
 	      });
 	    } else {
 	      this.jsPsych.pluginAPI.getKeyboardResponse({
@@ -208,7 +233,8 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	        valid_responses: this.params.choices,
 	        rt_method: "performance",
 	        persist: false,
-	        allow_held_key: false
+	        allow_held_key: false,
+	        wait_for_key_release: this.params.wait_for_key_release
 	      });
 	    }
 	  }
@@ -247,8 +273,10 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	    const default_data = {
 	      stimulus: trial.stimulus,
 	      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-	      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+	      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+	      rt_key_duration: null
 	    };
+	    default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
 	    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
 	    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
 	    return data;
@@ -258,4 +286,4 @@ var jsPsychAudioKeyboardResponse = (function (jspsych) {
 	return AudioKeyboardResponsePlugin;
 
 })(jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-audio-keyboard-response@2.1.1/dist/index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-audio-keyboard-response@2.2.0/dist/index.browser.js.map

package/dist/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","sources":["../../../node_modules/auto-bind/index.js","../package.json","../src/index.ts"],"sourcesContent":["'use strict';\n\n// Gets all non-builtin properties up the prototype chain\nconst getAllProperties = object => {\n\tconst properties = new Set();\n\n\tdo {\n\t\tfor (const key of Reflect.ownKeys(object)) {\n\t\t\tproperties.add([object, key]);\n\t\t}\n\t} while ((object = Reflect.getPrototypeOf(object)) && object !== Object.prototype);\n\n\treturn properties;\n};\n\nmodule.exports = (self, {include, exclude} = {}) => {\n\tconst filter = key => {\n\t\tconst match = pattern => typeof pattern === 'string' ? key === pattern : pattern.test(key);\n\n\t\tif (include) {\n\t\t\treturn include.some(match);\n\t\t}\n\n\t\tif (exclude) {\n\t\t\treturn !exclude.some(match);\n\t\t}\n\n\t\treturn true;\n\t};\n\n\tfor (const [object, key] of getAllProperties(self.constructor.prototype)) {\n\t\tif (key === 'constructor' || !filter(key)) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(object, key);\n\t\tif (descriptor && typeof descriptor.value === 'function') {\n\t\t\tself[key] = self[key].bind(self);\n\t\t}\n\t}\n\n\treturn self;\n};\n","{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.1.1\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string } = { rt: null, key: null };\n  private startTime: number;\n  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number }) {\n    this.response = info;\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;;;;CAEA;CACA,MAAM,gBAAgB,GAAG,MAAM,IAAI;CACnC,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAE,CAAA;;CAE7B,CAAC,GAAG;CACJ,EAAE,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;CAC7C,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;CAChC,GAAA;CACA,EAAE,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,MAAM,KAAK,MAAM,CAAC,SAAS,EAAA;;CAElF,CAAC,OAAO,UAAU,CAAA;CAClB,CAAC,CAAA;;KAED,QAAc,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK;CACpD,CAAC,MAAM,MAAM,GAAG,GAAG,IAAI;CACvB,EAAE,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,GAAG,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;;CAE5F,EAAE,IAAI,OAAO,EAAE;CACf,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;CAC7B,GAAA;;CAEA,EAAE,IAAI,OAAO,EAAE;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;CAC9B,GAAA;;CAEA,EAAE,OAAO,IAAI,CAAA;CACb,EAAE,CAAA;;CAEF,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE;CAC3E,EAAE,IAAI,GAAG,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;CAC7C,GAAG,SAAA;CACH,GAAA;;CAEA,EAAE,MAAM,UAAU,GAAG,OAAO,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAClE,EAAE,IAAI,UAAU,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE;CAC5D,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;CACnC,GAAA;CACA,EAAA;;CAEA,CAAC,OAAO,IAAI,CAAA;CACZ,CAAC,CAAA;;;;CCxCC,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GCmFA,SAAA,EAAA;CAAA;;IAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","x_google_ignoreList":[0]}
+{"version":3,"file":"index.browser.js","sources":["../../../node_modules/auto-bind/index.js","../package.json","../src/index.ts"],"sourcesContent":["'use strict';\n\n// Gets all non-builtin properties up the prototype chain\nconst getAllProperties = object => {\n\tconst properties = new Set();\n\n\tdo {\n\t\tfor (const key of Reflect.ownKeys(object)) {\n\t\t\tproperties.add([object, key]);\n\t\t}\n\t} while ((object = Reflect.getPrototypeOf(object)) && object !== Object.prototype);\n\n\treturn properties;\n};\n\nmodule.exports = (self, {include, exclude} = {}) => {\n\tconst filter = key => {\n\t\tconst match = pattern => typeof pattern === 'string' ? key === pattern : pattern.test(key);\n\n\t\tif (include) {\n\t\t\treturn include.some(match);\n\t\t}\n\n\t\tif (exclude) {\n\t\t\treturn !exclude.some(match);\n\t\t}\n\n\t\treturn true;\n\t};\n\n\tfor (const [object, key] of getAllProperties(self.constructor.prototype)) {\n\t\tif (key === 'constructor' || !filter(key)) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(object, key);\n\t\tif (descriptor && typeof descriptor.value === 'function') {\n\t\t\tself[key] = self[key].bind(self);\n\t\t}\n\t}\n\n\treturn self;\n};\n","{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string; rt_key_duration: number } = {\n    rt: null,\n    key: null,\n    rt_key_duration: null,\n  };\n  private startTime: number;\n  private finish: ({}: {\n    rt: number;\n    response: string;\n    stimulus: string;\n    rt_key_duration: number;\n  }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n      rt_key_duration: this.response.rt_key_duration,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number; rt_key_duration?: number }) {\n    this.response = {\n      rt: info.rt,\n      key: info.key,\n      rt_key_duration: info.rt_key_duration ?? null,\n    };\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;;;;CAEA;CACA,MAAM,gBAAgB,GAAG,MAAM,IAAI;CACnC,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAE;;CAE7B,CAAC,GAAG;CACJ,EAAE,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;CAC7C,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,EAAA;CACA,CAAA,CAAE,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,MAAM,KAAK,MAAM,CAAC,SAAS;;CAElF,CAAC,OAAO,UAAU;CAClB,CAAC;;KAED,QAAc,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK;CACpD,CAAC,MAAM,MAAM,GAAG,GAAG,IAAI;CACvB,EAAE,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,GAAG,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;;CAE5F,EAAE,IAAI,OAAO,EAAE;CACf,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;CAC7B,EAAA;;CAEA,EAAE,IAAI,OAAO,EAAE;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;CAC9B,EAAA;;CAEA,EAAE,OAAO,IAAI;CACb,CAAA,CAAE;;CAEF,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE;CAC3E,EAAE,IAAI,GAAG,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;CAC7C,GAAG;CACH,EAAA;;CAEA,EAAE,MAAM,UAAU,GAAG,OAAO,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC;CAClE,EAAE,IAAI,UAAU,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE;CAC5D,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;CACnC,EAAA;CACA,CAAA;;CAEA,CAAC,OAAO,IAAI;CACZ,CAAC;;;;CCxCC,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GCkGA,SAAA,EAAA;CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","x_google_ignoreList":[0]}

package/dist/index.browser.min.js

@@ -1,2 +1,2 @@
-var jsPsychAudioKeyboardResponse=function(o){"use strict";function c(s){return s&&s.__esModule&&Object.prototype.hasOwnProperty.call(s,"default")?s.default:s}const y=s=>{const e=new Set;do for(const t of Reflect.ownKeys(s))e.add([s,t]);while((s=Reflect.getPrototypeOf(s))&&s!==Object.prototype);return e};var _=(s,{include:e,exclude:t}={})=>{const a=i=>{const r=n=>typeof n=="string"?i===n:n.test(i);return e?e.some(r):t?!t.some(r):!0};for(const[i,r]of y(s.constructor.prototype)){if(r==="constructor"||!a(r))continue;const n=Reflect.getOwnPropertyDescriptor(i,r);n&&typeof n.value=="function"&&(s[r]=s[r].bind(s))}return s},m=c(_),P="2.1.1",u=(s,e,t)=>new Promise((a,i)=>{var r=l=>{try{p(t.next(l))}catch(d){i(d)}},n=l=>{try{p(t.throw(l))}catch(d){i(d)}},p=l=>l.done?a(l.value):Promise.resolve(l.value).then(r,n);p((t=t.apply(s,e)).next())});const f={name:"audio-keyboard-response",version:P,parameters:{stimulus:{type:o.ParameterType.AUDIO,default:void 0},choices:{type:o.ParameterType.KEYS,default:"ALL_KEYS"},prompt:{type:o.ParameterType.HTML_STRING,pretty_name:"Prompt",default:null},trial_duration:{type:o.ParameterType.INT,default:null},response_ends_trial:{type:o.ParameterType.BOOL,default:!0},trial_ends_after_audio:{type:o.ParameterType.BOOL,pretty_name:"Trial ends after audio",default:!1},response_allowed_while_playing:{type:o.ParameterType.BOOL,default:!0}},data:{response:{type:o.ParameterType.STRING},rt:{type:o.ParameterType.INT},stimulus:{type:o.ParameterType.STRING}},citations:{apa:"de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments. Journal of Open Source Software, 8(85), 5351. https://doi.org/10.21105/joss.05351 ",bibtex:'@article{Leeuw2023jsPsych, 	author = {de Leeuw, Joshua R. and Gilbert, Rebecca A. and Luchterhandt, Bj{\\" o}rn}, 	journal = {Journal of Open Source Software}, 	doi = {10.21105/joss.05351}, 	issn = {2475-9066}, 	number = {85}, 	year = {2023}, 	month = {may 11}, 	pages = {5351}, 	publisher = {Open Journals}, 	title = {jsPsych: Enabling an {Open}-{Source} {Collaborative} {Ecosystem} of {Behavioral} {Experiments}}, 	url = {https://joss.theoj.org/papers/10.21105/joss.05351}, 	volume = {8}, }  '}};class h{constructor(e){this.jsPsych=e,this.response={rt:null,key:null},m(this)}trial(e,t,a){return new Promise(i=>u(this,null,function*(){var r;this.finish=i,this.params=t,this.display=e,this.audio=yield this.jsPsych.pluginAPI.getAudioPlayer(t.stimulus),t.trial_ends_after_audio&&this.audio.addEventListener("ended",this.end_trial),t.prompt!==null&&(e.innerHTML=t.prompt),this.startTime=(r=this.jsPsych.pluginAPI.audioContext())==null?void 0:r.currentTime,t.response_allowed_while_playing?this.setup_keyboard_listener():t.trial_ends_after_audio||this.audio.addEventListener("ended",this.setup_keyboard_listener),t.trial_duration!==null&&this.jsPsych.pluginAPI.setTimeout(()=>{this.end_trial()},t.trial_duration),a(),this.audio.play()}))}end_trial(){this.jsPsych.pluginAPI.clearAllTimeouts(),this.audio.removeEventListener("ended",this.end_trial),this.audio.removeEventListener("ended",this.setup_keyboard_listener),this.audio.stop(),this.jsPsych.pluginAPI.cancelAllKeyboardResponses();var e={rt:this.response.rt,response:this.response.key,stimulus:this.params.stimulus};this.display.innerHTML="",this.finish(e)}after_response(e){this.response=e,this.params.response_ends_trial&&this.end_trial()}setup_keyboard_listener(){this.jsPsych.pluginAPI.useWebaudio?this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:this.after_response,valid_responses:this.params.choices,rt_method:"audio",persist:!1,allow_held_key:!1,audio_context:this.jsPsych.pluginAPI.audioContext(),audio_context_start_time:this.startTime}):this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:this.after_response,valid_responses:this.params.choices,rt_method:"performance",persist:!1,allow_held_key:!1})}simulate(e,t,a,i){return u(this,null,function*(){if(t=="data-only")return i(),this.simulate_data_only(e,a);if(t=="visual")return this.simulate_visual(e,a,i)})}simulate_data_only(e,t){return this.create_simulation_data(e,t)}simulate_visual(e,t,a){return u(this,null,function*(){const i=this.create_simulation_data(e,t),r=this.jsPsych.getDisplayElement(),n=()=>{i.rt!==null&&this.jsPsych.pluginAPI.pressKey(i.response,i.rt)};return yield this.trial(r,e,()=>{a(),e.response_allowed_while_playing?n():this.audio.addEventListener("ended",n)})})}create_simulation_data(e,t){const a={stimulus:e.stimulus,rt:this.jsPsych.randomization.sampleExGaussian(500,50,.006666666666666667,!0),response:this.jsPsych.pluginAPI.getValidKey(e.choices)},i=this.jsPsych.pluginAPI.mergeSimulationData(a,t);return this.jsPsych.pluginAPI.ensureSimulationDataConsistency(e,i),i}}return h.info=f,h}(jsPsychModule);
-//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-audio-keyboard-response@2.1.1/dist/index.browser.min.js.map
+var jsPsychAudioKeyboardResponse=(function(n){"use strict";function h(s){return s&&s.__esModule&&Object.prototype.hasOwnProperty.call(s,"default")?s.default:s}const y=s=>{const e=new Set;do for(const t of Reflect.ownKeys(s))e.add([s,t]);while((s=Reflect.getPrototypeOf(s))&&s!==Object.prototype);return e};var c=(s,{include:e,exclude:t}={})=>{const i=r=>{const a=o=>typeof o=="string"?r===o:o.test(r);return e?e.some(a):t?!t.some(a):!0};for(const[r,a]of y(s.constructor.prototype)){if(a==="constructor"||!i(a))continue;const o=Reflect.getOwnPropertyDescriptor(r,a);o&&typeof o.value=="function"&&(s[a]=s[a].bind(s))}return s},m=h(c),f="2.2.0",u=(s,e,t)=>new Promise((i,r)=>{var a=l=>{try{d(t.next(l))}catch(p){r(p)}},o=l=>{try{d(t.throw(l))}catch(p){r(p)}},d=l=>l.done?i(l.value):Promise.resolve(l.value).then(a,o);d((t=t.apply(s,e)).next())});const P={name:"audio-keyboard-response",version:f,parameters:{stimulus:{type:n.ParameterType.AUDIO,default:void 0},choices:{type:n.ParameterType.KEYS,default:"ALL_KEYS"},prompt:{type:n.ParameterType.HTML_STRING,pretty_name:"Prompt",default:null},trial_duration:{type:n.ParameterType.INT,default:null},response_ends_trial:{type:n.ParameterType.BOOL,default:!0},trial_ends_after_audio:{type:n.ParameterType.BOOL,pretty_name:"Trial ends after audio",default:!1},response_allowed_while_playing:{type:n.ParameterType.BOOL,default:!0},wait_for_key_release:{type:n.ParameterType.BOOL,default:!1}},data:{response:{type:n.ParameterType.STRING},rt:{type:n.ParameterType.INT},stimulus:{type:n.ParameterType.STRING},rt_key_duration:{type:n.ParameterType.INT}},citations:{apa:"de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments. Journal of Open Source Software, 8(85), 5351. https://doi.org/10.21105/joss.05351 ",bibtex:'@article{Leeuw2023jsPsych, 	author = {de Leeuw, Joshua R. and Gilbert, Rebecca A. and Luchterhandt, Bj{\\" o}rn}, 	journal = {Journal of Open Source Software}, 	doi = {10.21105/joss.05351}, 	issn = {2475-9066}, 	number = {85}, 	year = {2023}, 	month = {may 11}, 	pages = {5351}, 	publisher = {Open Journals}, 	title = {jsPsych: Enabling an {Open}-{Source} {Collaborative} {Ecosystem} of {Behavioral} {Experiments}}, 	url = {https://joss.theoj.org/papers/10.21105/joss.05351}, 	volume = {8}, }  '}};class _{constructor(e){this.jsPsych=e,this.response={rt:null,key:null,rt_key_duration:null},m(this)}trial(e,t,i){return new Promise(r=>u(this,null,function*(){var a;this.finish=r,this.params=t,this.display=e,this.audio=yield this.jsPsych.pluginAPI.getAudioPlayer(t.stimulus),t.trial_ends_after_audio&&this.audio.addEventListener("ended",this.end_trial),t.prompt!==null&&(e.innerHTML=t.prompt),this.startTime=(a=this.jsPsych.pluginAPI.audioContext())==null?void 0:a.currentTime,t.response_allowed_while_playing?this.setup_keyboard_listener():t.trial_ends_after_audio||this.audio.addEventListener("ended",this.setup_keyboard_listener),t.trial_duration!==null&&this.jsPsych.pluginAPI.setTimeout(()=>{this.end_trial()},t.trial_duration),i(),this.audio.play()}))}end_trial(){this.jsPsych.pluginAPI.clearAllTimeouts(),this.audio.removeEventListener("ended",this.end_trial),this.audio.removeEventListener("ended",this.setup_keyboard_listener),this.audio.stop(),this.jsPsych.pluginAPI.cancelAllKeyboardResponses();var e={rt:this.response.rt,response:this.response.key,stimulus:this.params.stimulus,rt_key_duration:this.response.rt_key_duration};this.display.innerHTML="",this.finish(e)}after_response(e){var t;this.response={rt:e.rt,key:e.key,rt_key_duration:(t=e.rt_key_duration)!=null?t:null},this.params.response_ends_trial&&this.end_trial()}setup_keyboard_listener(){this.jsPsych.pluginAPI.useWebaudio?this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:this.after_response,valid_responses:this.params.choices,rt_method:"audio",persist:!1,allow_held_key:!1,audio_context:this.jsPsych.pluginAPI.audioContext(),audio_context_start_time:this.startTime,wait_for_key_release:this.params.wait_for_key_release}):this.jsPsych.pluginAPI.getKeyboardResponse({callback_function:this.after_response,valid_responses:this.params.choices,rt_method:"performance",persist:!1,allow_held_key:!1,wait_for_key_release:this.params.wait_for_key_release})}simulate(e,t,i,r){return u(this,null,function*(){if(t=="data-only")return r(),this.simulate_data_only(e,i);if(t=="visual")return this.simulate_visual(e,i,r)})}simulate_data_only(e,t){return this.create_simulation_data(e,t)}simulate_visual(e,t,i){return u(this,null,function*(){const r=this.create_simulation_data(e,t),a=this.jsPsych.getDisplayElement(),o=()=>{r.rt!==null&&this.jsPsych.pluginAPI.pressKey(r.response,r.rt)};return yield this.trial(a,e,()=>{i(),e.response_allowed_while_playing?o():this.audio.addEventListener("ended",o)})})}create_simulation_data(e,t){const i={stimulus:e.stimulus,rt:this.jsPsych.randomization.sampleExGaussian(500,50,.006666666666666667,!0),response:this.jsPsych.pluginAPI.getValidKey(e.choices),rt_key_duration:null};i.rt_key_duration=i.rt===null||!e.wait_for_key_release?null:this.jsPsych.randomization.sampleExGaussian(150,30,.01,!0);const r=this.jsPsych.pluginAPI.mergeSimulationData(i,t);return this.jsPsych.pluginAPI.ensureSimulationDataConsistency(e,r),r}}return _.info=P,_})(jsPsychModule);
+//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-audio-keyboard-response@2.2.0/dist/index.browser.min.js.map

package/dist/index.browser.min.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.min.js","sources":["../../../node_modules/auto-bind/index.js","../package.json","../src/index.ts"],"sourcesContent":["'use strict';\n\n// Gets all non-builtin properties up the prototype chain\nconst getAllProperties = object => {\n\tconst properties = new Set();\n\n\tdo {\n\t\tfor (const key of Reflect.ownKeys(object)) {\n\t\t\tproperties.add([object, key]);\n\t\t}\n\t} while ((object = Reflect.getPrototypeOf(object)) && object !== Object.prototype);\n\n\treturn properties;\n};\n\nmodule.exports = (self, {include, exclude} = {}) => {\n\tconst filter = key => {\n\t\tconst match = pattern => typeof pattern === 'string' ? key === pattern : pattern.test(key);\n\n\t\tif (include) {\n\t\t\treturn include.some(match);\n\t\t}\n\n\t\tif (exclude) {\n\t\t\treturn !exclude.some(match);\n\t\t}\n\n\t\treturn true;\n\t};\n\n\tfor (const [object, key] of getAllProperties(self.constructor.prototype)) {\n\t\tif (key === 'constructor' || !filter(key)) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(object, key);\n\t\tif (descriptor && typeof descriptor.value === 'function') {\n\t\t\tself[key] = self[key].bind(self);\n\t\t}\n\t}\n\n\treturn self;\n};\n","{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.1.1\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string } = { rt: null, key: null };\n  private startTime: number;\n  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number }) {\n    this.response = info;\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":["getAllProperties","object","properties","key","autoBind","self","include","exclude","filter","match","pattern","descriptor","version","_a"],"mappings":"8JAGA,MAAMA,EAAmBC,GAAU,CAClC,MAAMC,EAAa,IAAI,IAEvB,EACC,WAAWC,KAAO,QAAQ,QAAQF,CAAM,EACvCC,EAAW,IAAI,CAACD,EAAQE,CAAG,CAAC,SAEpBF,EAAS,QAAQ,eAAeA,CAAM,IAAMA,IAAW,OAAO,WAExE,OAAOC,CACR,MAEAE,EAAiB,CAACC,EAAM,CAAC,QAAAC,EAAS,QAAAC,CAAO,EAAI,CAAA,IAAO,CACnD,MAAMC,EAASL,GAAO,CACrB,MAAMM,EAAQC,GAAW,OAAOA,GAAY,SAAWP,IAAQO,EAAUA,EAAQ,KAAKP,CAAG,EAEzF,OAAIG,EACIA,EAAQ,KAAKG,CAAK,EAGtBF,EACI,CAACA,EAAQ,KAAKE,CAAK,EAGpB,EACT,EAEC,SAAW,CAACR,EAAQE,CAAG,IAAKH,EAAiBK,EAAK,YAAY,SAAS,EAAG,CACzE,GAAIF,IAAQ,eAAiB,CAACK,EAAOL,CAAG,EACvC,SAGD,MAAMQ,EAAa,QAAQ,yBAAyBV,EAAQE,CAAG,EAC3DQ,GAAc,OAAOA,EAAW,OAAU,aAC7CN,EAAKF,CAAG,EAAIE,EAAKF,CAAG,EAAE,KAAKE,CAAI,EAElC,CAEC,OAAOA,CACR,SCxCEO,EAAW,s1BCmFA,UAAA,iuBAAe,4HArF5B,KAAA,WAAA,CAAA,IAAAC","x_google_ignoreList":[0]}
+{"version":3,"file":"index.browser.min.js","sources":["../../../node_modules/auto-bind/index.js","../package.json","../src/index.ts"],"sourcesContent":["'use strict';\n\n// Gets all non-builtin properties up the prototype chain\nconst getAllProperties = object => {\n\tconst properties = new Set();\n\n\tdo {\n\t\tfor (const key of Reflect.ownKeys(object)) {\n\t\t\tproperties.add([object, key]);\n\t\t}\n\t} while ((object = Reflect.getPrototypeOf(object)) && object !== Object.prototype);\n\n\treturn properties;\n};\n\nmodule.exports = (self, {include, exclude} = {}) => {\n\tconst filter = key => {\n\t\tconst match = pattern => typeof pattern === 'string' ? key === pattern : pattern.test(key);\n\n\t\tif (include) {\n\t\t\treturn include.some(match);\n\t\t}\n\n\t\tif (exclude) {\n\t\t\treturn !exclude.some(match);\n\t\t}\n\n\t\treturn true;\n\t};\n\n\tfor (const [object, key] of getAllProperties(self.constructor.prototype)) {\n\t\tif (key === 'constructor' || !filter(key)) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(object, key);\n\t\tif (descriptor && typeof descriptor.value === 'function') {\n\t\t\tself[key] = self[key].bind(self);\n\t\t}\n\t}\n\n\treturn self;\n};\n","{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string; rt_key_duration: number } = {\n    rt: null,\n    key: null,\n    rt_key_duration: null,\n  };\n  private startTime: number;\n  private finish: ({}: {\n    rt: number;\n    response: string;\n    stimulus: string;\n    rt_key_duration: number;\n  }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n      rt_key_duration: this.response.rt_key_duration,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number; rt_key_duration?: number }) {\n    this.response = {\n      rt: info.rt,\n      key: info.key,\n      rt_key_duration: info.rt_key_duration ?? null,\n    };\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":["getAllProperties","object","properties","key","autoBind","self","include","exclude","filter","match","pattern","descriptor","version","d","t","e","s","n","r","l","_a"],"mappings":"+JAGA,MAAMA,EAAmBC,GAAU,CAClC,MAAMC,EAAa,IAAI,IAEvB,EACC,WAAWC,KAAO,QAAQ,QAAQF,CAAM,EACvCC,EAAW,IAAI,CAACD,EAAQE,CAAG,CAAC,SAEpBF,EAAS,QAAQ,eAAeA,CAAM,IAAMA,IAAW,OAAO,WAExE,OAAOC,CACR,MAEAE,EAAiB,CAACC,EAAM,CAAC,QAAAC,EAAS,QAAAC,CAAO,EAAI,CAAA,IAAO,CACnD,MAAMC,EAASL,GAAO,CACrB,MAAMM,EAAQC,GAAW,OAAOA,GAAY,SAAWP,IAAQO,EAAUA,EAAQ,KAAKP,CAAG,EAEzF,OAAIG,EACIA,EAAQ,KAAKG,CAAK,EAGtBF,EACI,CAACA,EAAQ,KAAKE,CAAK,EAGpB,EACT,EAEC,SAAW,CAACR,EAAQE,CAAG,IAAKH,EAAiBK,EAAK,YAAY,SAAS,EAAG,CACzE,GAAIF,IAAQ,eAAiB,CAACK,EAAOL,CAAG,EACvC,SAGD,MAAMQ,EAAa,QAAQ,yBAAyBV,EAAQE,CAAG,EAC3DQ,GAAc,OAAOA,EAAW,OAAU,aAC7CN,EAAKF,CAAG,EAAIE,EAAKF,CAAG,EAAE,KAAKE,CAAI,EAElC,CAEC,OAAOA,CACR,SCxCEO,EAAW,QCFb,EAAA,CAAAC,EAAAC,EAAAC,IAAA,IAAA,QAAA,CAAA,EAAAC,IAAA,CAAA,IAAAC,EAAAC,GAAA,CAAA,GAAA,CAAAC,EAAAJ,EAAA,KAAAG,CAAA,CAAA,CAAA,OAAA,EAAA,CAAAF,EAAA,CAAA,CAAA,CAAA,EAAA,EAAAE,GAAA,CAAA,GAAA,CAAAC,EAAAJ,EAAA,MAAAG,CAAA,CAAA,CAAA,OAAA,EAAA,CAAAF,EAAA,CAAA,CAAA,CAAA,EAAAG,EAAAD,GAAAA,EAAA,KAAA,EAAAA,EAAA,KAAA,EAAA,QAAA,QAAAA,EAAA,KAAA,EAAA,KAAAD,EAAA,CAAA,EAAAE,GAAAJ,EAAAA,EAAA,MAAAF,EAAAC,CAAA,GAAA,KAAA,CAAA,CAAA,CAAA,8uBAoGa,UAAA,iuBAAe,kKApG5B,IAAAM,ygCAAA,IAAAA","x_google_ignoreList":[0]}

package/dist/index.cjs

@@ -3,7 +3,7 @@
 var autoBind = require('auto-bind');
 var jspsych = require('jspsych');
 
-var version = "2.1.1";
+var version = "2.2.0";
 
 const info = {
   name: "audio-keyboard-response",
@@ -64,6 +64,17 @@ const info = {
     response_allowed_while_playing: {
       type: jspsych.ParameterType.BOOL,
       default: true
+    },
+    /** If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: jspsych.ParameterType.BOOL,
+      default: false
     }
   },
   data: {
@@ -81,6 +92,10 @@ const info = {
     /** Path to the audio file that played during the trial. */
     stimulus: {
       type: jspsych.ParameterType.STRING
+    },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: jspsych.ParameterType.INT
     }
   },
   // prettier-ignore
@@ -92,7 +107,11 @@ const info = {
 class AudioKeyboardResponsePlugin {
   constructor(jsPsych) {
     this.jsPsych = jsPsych;
-    this.response = { rt: null, key: null };
+    this.response = {
+      rt: null,
+      key: null,
+      rt_key_duration: null
+    };
     autoBind(this);
   }
   static {
@@ -134,13 +153,18 @@ class AudioKeyboardResponsePlugin {
     var trial_data = {
       rt: this.response.rt,
       response: this.response.key,
-      stimulus: this.params.stimulus
+      stimulus: this.params.stimulus,
+      rt_key_duration: this.response.rt_key_duration
     };
     this.display.innerHTML = "";
     this.finish(trial_data);
   }
   after_response(info2) {
-    this.response = info2;
+    this.response = {
+      rt: info2.rt,
+      key: info2.key,
+      rt_key_duration: info2.rt_key_duration ?? null
+    };
     if (this.params.response_ends_trial) {
       this.end_trial();
     }
@@ -154,7 +178,8 @@ class AudioKeyboardResponsePlugin {
         persist: false,
         allow_held_key: false,
         audio_context: this.jsPsych.pluginAPI.audioContext(),
-        audio_context_start_time: this.startTime
+        audio_context_start_time: this.startTime,
+        wait_for_key_release: this.params.wait_for_key_release
       });
     } else {
       this.jsPsych.pluginAPI.getKeyboardResponse({
@@ -162,7 +187,8 @@ class AudioKeyboardResponsePlugin {
         valid_responses: this.params.choices,
         rt_method: "performance",
         persist: false,
-        allow_held_key: false
+        allow_held_key: false,
+        wait_for_key_release: this.params.wait_for_key_release
       });
     }
   }
@@ -201,8 +227,10 @@ class AudioKeyboardResponsePlugin {
     const default_data = {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null
     };
+    default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
     this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
     return data;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.1.1\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string } = { rt: null, key: null };\n  private startTime: number;\n  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number }) {\n    this.response = info;\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;;AAEE,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECmFA,SAAA,EAAA;AAAA;;GAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string; rt_key_duration: number } = {\n    rt: null,\n    key: null,\n    rt_key_duration: null,\n  };\n  private startTime: number;\n  private finish: ({}: {\n    rt: number;\n    response: string;\n    stimulus: string;\n    rt_key_duration: number;\n  }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n      rt_key_duration: this.response.rt_key_duration,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number; rt_key_duration?: number }) {\n    this.response = {\n      rt: info.rt,\n      key: info.key,\n      rt_key_duration: info.rt_key_duration ?? null,\n    };\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECkGA,SAAA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -60,6 +60,17 @@ declare const info: {
             readonly type: ParameterType.BOOL;
             readonly default: true;
         };
+        /** If true, the response is not registered until the participant releases the key. The response
+         * time (`rt`) still reflects when the key was pressed, and the additional data field
+         * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+         * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+         * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+         * key is still held, no response is recorded for the trial.
+         */
+        readonly wait_for_key_release: {
+            readonly type: ParameterType.BOOL;
+            readonly default: false;
+        };
     };
     readonly data: {
         /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
@@ -77,6 +88,10 @@ declare const info: {
         readonly stimulus: {
             readonly type: ParameterType.STRING;
         };
+        /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+        readonly rt_key_duration: {
+            readonly type: ParameterType.INT;
+        };
     };
     readonly citations: "__CITATIONS__";
 };
@@ -160,6 +175,17 @@ declare class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
                 readonly type: ParameterType.BOOL;
                 readonly default: true;
             };
+            /** If true, the response is not registered until the participant releases the key. The response
+             * time (`rt`) still reflects when the key was pressed, and the additional data field
+             * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+             * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+             * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+             * key is still held, no response is recorded for the trial.
+             */
+            readonly wait_for_key_release: {
+                readonly type: ParameterType.BOOL;
+                readonly default: false;
+            };
         };
         readonly data: {
             /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
@@ -177,6 +203,10 @@ declare class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
             readonly stimulus: {
                 readonly type: ParameterType.STRING;
             };
+            /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+            readonly rt_key_duration: {
+                readonly type: ParameterType.INT;
+            };
         };
         readonly citations: "__CITATIONS__";
     };

package/dist/index.js

@@ -1,7 +1,7 @@
 import autoBind from 'auto-bind';
 import { ParameterType } from 'jspsych';
 
-var version = "2.1.1";
+var version = "2.2.0";
 
 const info = {
   name: "audio-keyboard-response",
@@ -62,6 +62,17 @@ const info = {
     response_allowed_while_playing: {
       type: ParameterType.BOOL,
       default: true
+    },
+    /** If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: ParameterType.BOOL,
+      default: false
     }
   },
   data: {
@@ -79,6 +90,10 @@ const info = {
     /** Path to the audio file that played during the trial. */
     stimulus: {
       type: ParameterType.STRING
+    },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: ParameterType.INT
     }
   },
   // prettier-ignore
@@ -90,7 +105,11 @@ const info = {
 class AudioKeyboardResponsePlugin {
   constructor(jsPsych) {
     this.jsPsych = jsPsych;
-    this.response = { rt: null, key: null };
+    this.response = {
+      rt: null,
+      key: null,
+      rt_key_duration: null
+    };
     autoBind(this);
   }
   static {
@@ -132,13 +151,18 @@ class AudioKeyboardResponsePlugin {
     var trial_data = {
       rt: this.response.rt,
       response: this.response.key,
-      stimulus: this.params.stimulus
+      stimulus: this.params.stimulus,
+      rt_key_duration: this.response.rt_key_duration
     };
     this.display.innerHTML = "";
     this.finish(trial_data);
   }
   after_response(info2) {
-    this.response = info2;
+    this.response = {
+      rt: info2.rt,
+      key: info2.key,
+      rt_key_duration: info2.rt_key_duration ?? null
+    };
     if (this.params.response_ends_trial) {
       this.end_trial();
     }
@@ -152,7 +176,8 @@ class AudioKeyboardResponsePlugin {
         persist: false,
         allow_held_key: false,
         audio_context: this.jsPsych.pluginAPI.audioContext(),
-        audio_context_start_time: this.startTime
+        audio_context_start_time: this.startTime,
+        wait_for_key_release: this.params.wait_for_key_release
       });
     } else {
       this.jsPsych.pluginAPI.getKeyboardResponse({
@@ -160,7 +185,8 @@ class AudioKeyboardResponsePlugin {
         valid_responses: this.params.choices,
         rt_method: "performance",
         persist: false,
-        allow_held_key: false
+        allow_held_key: false,
+        wait_for_key_release: this.params.wait_for_key_release
       });
     }
   }
@@ -199,8 +225,10 @@ class AudioKeyboardResponsePlugin {
     const default_data = {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-      response: this.jsPsych.pluginAPI.getValidKey(trial.choices)
+      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null
     };
+    default_data.rt_key_duration = default_data.rt === null || !trial.wait_for_key_release ? null : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
     this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
     return data;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.1.1\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.2.0\",\n    \"@jspsych/test-utils\": \"^1.2.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string } = { rt: null, key: null };\n  private startTime: number;\n  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number }) {\n    this.response = info;\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n    };\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;AAEE,IAAW,OAAA,GAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECmFA,SAAA,EAAA;AAAA;;GAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@jspsych/plugin-audio-keyboard-response\",\n  \"version\": \"2.2.0\",\n  \"description\": \"jsPsych plugin for playing an audio file and getting a keyboard response\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.cjs\",\n  \"exports\": {\n    \"import\": \"./dist/index.js\",\n    \"require\": \"./dist/index.cjs\"\n  },\n  \"typings\": \"dist/index.d.ts\",\n  \"unpkg\": \"dist/index.browser.min.js\",\n  \"files\": [\n    \"src\",\n    \"dist\"\n  ],\n  \"source\": \"src/index.ts\",\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"npm test -- --watch\",\n    \"tsc\": \"tsc\",\n    \"build\": \"rollup --config\",\n    \"build:watch\": \"npm run build -- --watch\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/jspsych/jsPsych.git\",\n    \"directory\": \"packages/plugin-audio-keyboard-response\"\n  },\n  \"author\": \"Josh de Leeuw\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/jspsych/jsPsych/issues\"\n  },\n  \"homepage\": \"https://www.jspsych.org/latest/plugins/audio-keyboard-response\",\n  \"peerDependencies\": {\n    \"jspsych\": \">=7.1.0\"\n  },\n  \"devDependencies\": {\n    \"@jspsych/config\": \"^3.3.4\",\n    \"@jspsych/test-utils\": \"^1.3.0\"\n  }\n}\n","import autoBind from \"auto-bind\";\nimport { JsPsych, JsPsychPlugin, ParameterType, TrialType } from \"jspsych\";\n\nimport { AudioPlayerInterface } from \"../../jspsych/src/modules/plugin-api/AudioPlayer\";\nimport { version } from \"../package.json\";\n\nconst info = <const>{\n  name: \"audio-keyboard-response\",\n  version: version,\n  parameters: {\n    /** The audio file to be played. */\n    stimulus: {\n      type: ParameterType.AUDIO,\n      default: undefined,\n    },\n    /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.\n     * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -\n     * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)\n     * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)\n     * for more examples. Any key presses that are not listed in the array will be ignored. The default value of `\"ALL_KEYS\"`\n     * means that all keys will be accepted as valid responses. Specifying `\"NO_KEYS\"` will mean that no responses are allowed.\n     */\n    choices: {\n      type: ParameterType.KEYS,\n      default: \"ALL_KEYS\",\n    },\n    /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that\n     * it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).\n     */\n    prompt: {\n      type: ParameterType.HTML_STRING,\n      pretty_name: \"Prompt\",\n      default: null,\n    },\n    /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the\n     * participant fails to make a response before this timer is reached, the participant's response will be\n     * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the\n     * trial will wait for a response indefinitely.\n     */\n    trial_duration: {\n      type: ParameterType.INT,\n      default: null,\n    },\n    /** If true, then the trial will end whenever the participant makes a response (assuming they make their\n     * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will\n     * continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to\n     * force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete\n     */\n    response_ends_trial: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, then the trial will end as soon as the audio file finishes playing. */\n    trial_ends_after_audio: {\n      type: ParameterType.BOOL,\n      pretty_name: \"Trial ends after audio\",\n      default: false,\n    },\n    /** If true, then responses are allowed while the audio is playing. If false, then the audio must finish\n     * playing before a keyboard response is accepted. Once the audio has played all the way through, a valid\n     * keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).\n     */\n    response_allowed_while_playing: {\n      type: ParameterType.BOOL,\n      default: true,\n    },\n    /** If true, the response is not registered until the participant releases the key. The response\n     * time (`rt`) still reflects when the key was pressed, and the additional data field\n     * `rt_key_duration` records how long the key was held down. Note that when this is true, the\n     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at\n     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the\n     * key is still held, no response is recorded for the trial.\n     */\n    wait_for_key_release: {\n      type: ParameterType.BOOL,\n      default: false,\n    },\n  },\n  data: {\n    /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */\n    response: {\n      type: ParameterType.STRING,\n    },\n    /** The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus\n     * first began playing until the participant made a key response. If no key was pressed before the trial ended, then the\n     * value will be `null`.\n     */\n    rt: {\n      type: ParameterType.INT,\n    },\n    /** Path to the audio file that played during the trial. */\n    stimulus: {\n      type: ParameterType.STRING,\n    },\n    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */\n    rt_key_duration: {\n      type: ParameterType.INT,\n    },\n  },\n  // prettier-ignore\n  citations: '__CITATIONS__',\n};\n\ntype Info = typeof info;\n\n/**\n * This plugin plays audio files and records responses generated with the keyboard.\n *\n * If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the\n * playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of\n * response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.\n *\n * Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](preload.md). However, if you are using\n * 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.\n *\n * The trial can end when the participant responds, when the audio file has finished playing, or if the participant has\n * failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before\n * the audio has finished playing.\n *\n * @author Josh de Leeuw\n * @see {@link https://www.jspsych.org/latest/plugins/audio-keyboard-response/ audio-keyboard-response plugin documentation on jspsych.org}\n */\nclass AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {\n  static info = info;\n  private audio: AudioPlayerInterface;\n  private params: TrialType<Info>;\n  private display: HTMLElement;\n  private response: { rt: number; key: string; rt_key_duration: number } = {\n    rt: null,\n    key: null,\n    rt_key_duration: null,\n  };\n  private startTime: number;\n  private finish: ({}: {\n    rt: number;\n    response: string;\n    stimulus: string;\n    rt_key_duration: number;\n  }) => void;\n\n  constructor(private jsPsych: JsPsych) {\n    autoBind(this);\n  }\n\n  trial(display_element: HTMLElement, trial: TrialType<Info>, on_load: () => void) {\n    return new Promise(async (resolve) => {\n      this.finish = resolve;\n      this.params = trial;\n      this.display = display_element;\n      // load audio file\n      this.audio = await this.jsPsych.pluginAPI.getAudioPlayer(trial.stimulus);\n\n      // set up end event if trial needs it\n      if (trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.end_trial);\n      }\n\n      // show prompt if there is one\n      if (trial.prompt !== null) {\n        display_element.innerHTML = trial.prompt;\n      }\n\n      // start playing audio here to record time\n      // use this for offsetting RT measurement in\n      // setup_keyboard_listener\n      this.startTime = this.jsPsych.pluginAPI.audioContext()?.currentTime;\n\n      // start keyboard listener when trial starts or sound ends\n      if (trial.response_allowed_while_playing) {\n        this.setup_keyboard_listener();\n      } else if (!trial.trial_ends_after_audio) {\n        this.audio.addEventListener(\"ended\", this.setup_keyboard_listener);\n      }\n\n      // end trial if time limit is set\n      if (trial.trial_duration !== null) {\n        this.jsPsych.pluginAPI.setTimeout(() => {\n          this.end_trial();\n        }, trial.trial_duration);\n      }\n\n      // call trial on_load method because we are done with all loading setup\n      on_load();\n\n      this.audio.play();\n    });\n  }\n\n  private end_trial() {\n    // kill any remaining setTimeout handlers\n    this.jsPsych.pluginAPI.clearAllTimeouts();\n\n    // remove end event listeners if they exist\n    this.audio.removeEventListener(\"ended\", this.end_trial);\n    this.audio.removeEventListener(\"ended\", this.setup_keyboard_listener);\n\n    // stop the audio file if it is playing\n    this.audio.stop();\n\n    // kill keyboard listeners\n    this.jsPsych.pluginAPI.cancelAllKeyboardResponses();\n\n    // gather the data to store for the trial\n    var trial_data = {\n      rt: this.response.rt,\n      response: this.response.key,\n      stimulus: this.params.stimulus,\n      rt_key_duration: this.response.rt_key_duration,\n    };\n\n    // clear the display\n    this.display.innerHTML = \"\";\n\n    // move on to the next trial\n    this.finish(trial_data);\n  }\n\n  private after_response(info: { key: string; rt: number; rt_key_duration?: number }) {\n    this.response = {\n      rt: info.rt,\n      key: info.key,\n      rt_key_duration: info.rt_key_duration ?? null,\n    };\n    if (this.params.response_ends_trial) {\n      this.end_trial();\n    }\n  }\n\n  private setup_keyboard_listener() {\n    // start the response listener\n    if (this.jsPsych.pluginAPI.useWebaudio) {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"audio\",\n        persist: false,\n        allow_held_key: false,\n        audio_context: this.jsPsych.pluginAPI.audioContext(),\n        audio_context_start_time: this.startTime,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    } else {\n      this.jsPsych.pluginAPI.getKeyboardResponse({\n        callback_function: this.after_response,\n        valid_responses: this.params.choices,\n        rt_method: \"performance\",\n        persist: false,\n        allow_held_key: false,\n        wait_for_key_release: this.params.wait_for_key_release,\n      });\n    }\n  }\n\n  async simulate(\n    trial: TrialType<Info>,\n    simulation_mode,\n    simulation_options: any,\n    load_callback: () => void\n  ) {\n    if (simulation_mode == \"data-only\") {\n      load_callback();\n      return this.simulate_data_only(trial, simulation_options);\n    }\n    if (simulation_mode == \"visual\") {\n      return this.simulate_visual(trial, simulation_options, load_callback);\n    }\n  }\n\n  private simulate_data_only(trial: TrialType<Info>, simulation_options) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    return data;\n  }\n\n  private async simulate_visual(\n    trial: TrialType<Info>,\n    simulation_options,\n    load_callback: () => void\n  ) {\n    const data = this.create_simulation_data(trial, simulation_options);\n\n    const display_element = this.jsPsych.getDisplayElement();\n\n    const respond = () => {\n      if (data.rt !== null) {\n        this.jsPsych.pluginAPI.pressKey(data.response, data.rt);\n      }\n    };\n\n    const result = await this.trial(display_element, trial, () => {\n      load_callback();\n      if (!trial.response_allowed_while_playing) {\n        this.audio.addEventListener(\"ended\", respond);\n      } else {\n        respond();\n      }\n    });\n\n    return result;\n  }\n\n  private create_simulation_data(trial: TrialType<Info>, simulation_options) {\n    const default_data = {\n      stimulus: trial.stimulus,\n      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),\n      response: this.jsPsych.pluginAPI.getValidKey(trial.choices),\n      rt_key_duration: null,\n    };\n    default_data.rt_key_duration =\n      default_data.rt === null || !trial.wait_for_key_release\n        ? null\n        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);\n\n    const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);\n\n    this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);\n\n    return data;\n  }\n}\n\nexport default AudioKeyboardResponsePlugin;\n"],"names":[],"mappings":";;;AAEE,IAAA,OAAA,GAAW,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ECkGA,SAAA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspsych/plugin-audio-keyboard-response",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "jsPsych plugin for playing an audio file and getting a keyboard response",
   "type": "module",
   "main": "dist/index.cjs",
@@ -37,7 +37,7 @@
     "jspsych": ">=7.1.0"
   },
   "devDependencies": {
-    "@jspsych/config": "^3.2.0",
-    "@jspsych/test-utils": "^1.2.0"
+    "@jspsych/config": "^3.3.4",
+    "@jspsych/test-utils": "^1.3.0"
   }
 }

package/src/index.spec.ts

@@ -1,6 +1,13 @@
 jest.mock("../../jspsych/src/modules/plugin-api/AudioPlayer");
 
-import { flushPromises, pressKey, simulateTimeline, startTimeline } from "@jspsych/test-utils";
+import {
+  flushPromises,
+  keyDown,
+  keyUp,
+  pressKey,
+  simulateTimeline,
+  startTimeline,
+} from "@jspsych/test-utils";
 import { initJsPsych } from "jspsych";
 
 //@ts-expect-error mock
@@ -126,6 +133,167 @@ describe("audio-keyboard-response", () => {
   });
 });
 
+describe("audio-keyboard-response wait_for_key_release", () => {
+  it("does not end the trial until the key is released and records the hold duration", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { getData, expectRunning, expectFinished } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+          wait_for_key_release: true,
+        },
+      ],
+      jsPsych
+    );
+
+    jest.advanceTimersByTime(100);
+    await keyDown("a");
+
+    await expectRunning();
+
+    jest.advanceTimersByTime(250);
+    await keyUp("a");
+
+    await expectFinished();
+
+    expect(getData().values()[0].rt).toBe(100);
+    expect(getData().values()[0].rt_key_duration).toBe(250);
+  });
+
+  it("records the hold duration when the trial ends by duration", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { getData, expectFinished } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+          wait_for_key_release: true,
+          response_ends_trial: false,
+          trial_duration: 1000,
+        },
+      ],
+      jsPsych
+    );
+
+    await keyDown("a");
+    jest.advanceTimersByTime(250);
+    await keyUp("a");
+
+    jest.advanceTimersByTime(750);
+    await expectFinished();
+
+    expect(getData().values()[0].rt_key_duration).toBe(250);
+  });
+
+  it("records a null response when the trial ends while the key is still held", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { getData, expectFinished } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+          wait_for_key_release: true,
+          response_ends_trial: false,
+          trial_duration: 1000,
+        },
+      ],
+      jsPsych
+    );
+
+    await keyDown("a");
+    jest.advanceTimersByTime(1000);
+    await expectFinished();
+
+    expect(getData().values()[0].response).toBe(null);
+    expect(getData().values()[0].rt).toBe(null);
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+
+    await keyUp("a");
+  });
+
+  it("rt_key_duration is null on default trials (wait_for_key_release false)", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { getData, expectFinished } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+        },
+      ],
+      jsPsych
+    );
+
+    await keyDown("a");
+    await expectFinished();
+
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+
+    await keyUp("a");
+  });
+
+  it("a key held past trial_duration does not contaminate the next trial", async () => {
+    const jsPsych = initJsPsych({ use_webaudio: false });
+
+    const { getData, expectRunning, expectFinished } = await startTimeline(
+      [
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+          wait_for_key_release: true,
+          trial_duration: 1000,
+        },
+        {
+          type: audioKeyboardResponse,
+          stimulus: "foo.mp3",
+          choices: ["a"],
+          wait_for_key_release: true,
+        },
+      ],
+      jsPsych
+    );
+
+    // trial 1: press and hold the key, then let the trial time out
+    await keyDown("a");
+    jest.advanceTimersByTime(1000);
+    await flushPromises();
+
+    // trial 1 ended by duration with no response because the key was never released
+    expect(getData().values()[0].response).toBe(null);
+    expect(getData().values()[0].rt).toBe(null);
+    expect(getData().values()[0].rt_key_duration).toBe(null);
+
+    // trial 2 is now running with the key still held; a key-repeat must not register
+    await keyDown("a");
+    await expectRunning();
+
+    // releasing the held-over key must not register a response in trial 2
+    await keyUp("a");
+    await expectRunning();
+
+    // a fresh press/release cycle in trial 2 works normally
+    jest.advanceTimersByTime(200);
+    await keyDown("a");
+    jest.advanceTimersByTime(125);
+    await keyUp("a");
+
+    await expectFinished();
+
+    expect(getData().values()[1].response).toBe("a");
+    expect(getData().values()[1].rt).toBe(200);
+    expect(getData().values()[1].rt_key_duration).toBe(125);
+  });
+});
+
 describe("audio-keyboard-response simulation", () => {
   test("data mode works", async () => {
     const timeline = [

package/src/index.ts

@@ -64,6 +64,17 @@ const info = <const>{
       type: ParameterType.BOOL,
       default: true,
     },
+    /** If true, the response is not registered until the participant releases the key. The response
+     * time (`rt`) still reflects when the key was pressed, and the additional data field
+     * `rt_key_duration` records how long the key was held down. Note that when this is true, the
+     * trial cannot end until the key is released: with `response_ends_trial: true` the trial ends at
+     * the key release, and if the trial ends for another reason (e.g., `trial_duration`) while the
+     * key is still held, no response is recorded for the trial.
+     */
+    wait_for_key_release: {
+      type: ParameterType.BOOL,
+      default: false,
+    },
   },
   data: {
     /** Indicates which key the participant pressed. If no key was pressed before the trial ended, then the value will be `null`. */
@@ -81,6 +92,10 @@ const info = <const>{
     stimulus: {
       type: ParameterType.STRING,
     },
+    /** The duration in milliseconds that the response key was held down, measured from key press to key release. Only recorded when `wait_for_key_release` is true; null otherwise or when no response was made. */
+    rt_key_duration: {
+      type: ParameterType.INT,
+    },
   },
   // prettier-ignore
   citations: '__CITATIONS__',
@@ -110,9 +125,18 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
   private audio: AudioPlayerInterface;
   private params: TrialType<Info>;
   private display: HTMLElement;
-  private response: { rt: number; key: string } = { rt: null, key: null };
+  private response: { rt: number; key: string; rt_key_duration: number } = {
+    rt: null,
+    key: null,
+    rt_key_duration: null,
+  };
   private startTime: number;
-  private finish: ({}: { rt: number; response: string; stimulus: string }) => void;
+  private finish: ({}: {
+    rt: number;
+    response: string;
+    stimulus: string;
+    rt_key_duration: number;
+  }) => void;
 
   constructor(private jsPsych: JsPsych) {
     autoBind(this);
@@ -181,6 +205,7 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
       rt: this.response.rt,
       response: this.response.key,
       stimulus: this.params.stimulus,
+      rt_key_duration: this.response.rt_key_duration,
     };
 
     // clear the display
@@ -190,8 +215,12 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
     this.finish(trial_data);
   }
 
-  private after_response(info: { key: string; rt: number }) {
-    this.response = info;
+  private after_response(info: { key: string; rt: number; rt_key_duration?: number }) {
+    this.response = {
+      rt: info.rt,
+      key: info.key,
+      rt_key_duration: info.rt_key_duration ?? null,
+    };
     if (this.params.response_ends_trial) {
       this.end_trial();
     }
@@ -208,6 +237,7 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         allow_held_key: false,
         audio_context: this.jsPsych.pluginAPI.audioContext(),
         audio_context_start_time: this.startTime,
+        wait_for_key_release: this.params.wait_for_key_release,
       });
     } else {
       this.jsPsych.pluginAPI.getKeyboardResponse({
@@ -216,6 +246,7 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
         rt_method: "performance",
         persist: false,
         allow_held_key: false,
+        wait_for_key_release: this.params.wait_for_key_release,
       });
     }
   }
@@ -273,7 +304,12 @@ class AudioKeyboardResponsePlugin implements JsPsychPlugin<Info> {
       stimulus: trial.stimulus,
       rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
       response: this.jsPsych.pluginAPI.getValidKey(trial.choices),
+      rt_key_duration: null,
     };
+    default_data.rt_key_duration =
+      default_data.rt === null || !trial.wait_for_key_release
+        ? null
+        : this.jsPsych.randomization.sampleExGaussian(150, 30, 1 / 100, true);
 
     const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);