@jspsych/plugin-audio-button-response 1.1.1 → 1.1.3

package/README.md

@@ -0,0 +1,47 @@
+![jspsych logo](http://www.jspsych.org/7.0/img/jspsych-logo.jpg)
+
+jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser.
+
+## Plugin Description
+
+The audio-button-response plugin plays audio files and records responses generated with a button click. The audio will be played using the WebAudio API, allowing for reasonably precise timing of the playback by measuring it against the WebAudio specific clock. If WebAudio API is not supported by the browser, the files will be played using HTML5 audio.
+
+## Examples
+
+Several example experiments and plugin demonstrations are available in the `/examples` folder.
+After you've downloaded the [latest release](https://github.com/jspsych/jsPsych/releases), double-click on an example HTML file to run it in your web browser, and open it with a programming-friendly text editor to see how it works.
+
+## Documentation
+
+Documentation for this plugin is available [here](https://www.jspsych.org/latest/plugins/audio-button-response).
+
+## Getting help
+
+For questions about using the library, please use the GitHub [discussions forum](https://github.com/jspsych/jsPsych/discussions).
+You can also browse through the history of Q&A on the forum to find related questions.
+
+## Contributing
+
+We :heart: contributions!
+See the [contributing to jsPsych](https://www.jspsych.org/latest/developers/contributing/) documentation page for more information about how you can help.
+
+## Citation
+
+If you use this library in academic work, the preferred citation is:
+
+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://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
+
+This paper is an updated description of jsPsych and includes all current core team members. It replaces the earlier paper that described jsPsych:
+
+de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
+
+Citations help us demonstrate that this library is used and valued, which allows us to continue working on it.
+
+## Contributors
+
+jsPsych is open source project with [numerous contributors](https://github.com/jspsych/jsPsych/graphs/contributors).
+The project is currently managed by the core team of Josh de Leeuw ([@jodeleeuw](https://github.com/jodeleeuw)), Becky Gilbert ([@becky-gilbert](https://github.com/becky-gilbert)), and Björn Luchterhandt ([@bjoluc](https://github.com/bjoluc)).
+
+jsPsych was created by [Josh de Leeuw](http://www.twitter.com/joshdeleeuw).
+
+We're also grateful for the generous support from a [Mozilla Open Source Support award](https://www.mozilla.org/en-US/moss/), which funded development of the library from 2020-2021.

package/dist/index.browser.js

@@ -1,305 +1,305 @@
 var jsPsychAudioButtonResponse = (function (jspsych) {
   'use strict';
 
-  const info = {
-      name: "audio-button-response",
-      parameters: {
-          /** The audio to be played. */
-          stimulus: {
-              type: jspsych.ParameterType.AUDIO,
-              pretty_name: "Stimulus",
-              default: undefined,
-          },
-          /** Array containing the label(s) for the button(s). */
-          choices: {
-              type: jspsych.ParameterType.STRING,
-              pretty_name: "Choices",
-              default: undefined,
-              array: true,
-          },
-          /** The HTML for creating button. Can create own style. Use the "%choice%" string to indicate where the label from the choices parameter should be inserted. */
-          button_html: {
-              type: jspsych.ParameterType.HTML_STRING,
-              pretty_name: "Button HTML",
-              default: '<button class="jspsych-btn">%choice%</button>',
-              array: true,
-          },
-          /** Any content here will be displayed below the stimulus. */
-          prompt: {
-              type: jspsych.ParameterType.HTML_STRING,
-              pretty_name: "Prompt",
-              default: null,
-          },
-          /** The maximum duration to wait for a response. */
-          trial_duration: {
-              type: jspsych.ParameterType.INT,
-              pretty_name: "Trial duration",
-              default: null,
-          },
-          /** Vertical margin of button. */
-          margin_vertical: {
-              type: jspsych.ParameterType.STRING,
-              pretty_name: "Margin vertical",
-              default: "0px",
-          },
-          /** Horizontal margin of button. */
-          margin_horizontal: {
-              type: jspsych.ParameterType.STRING,
-              pretty_name: "Margin horizontal",
-              default: "8px",
-          },
-          /** If true, the trial will end when user makes a response. */
-          response_ends_trial: {
-              type: jspsych.ParameterType.BOOL,
-              pretty_name: "Response ends trial",
-              default: true,
-          },
-          /** If true, then the trial will end as soon as the audio file finishes playing. */
-          trial_ends_after_audio: {
-              type: jspsych.ParameterType.BOOL,
-              pretty_name: "Trial ends after audio",
-              default: false,
-          },
-          /**
-           * If true, then responses are allowed while the audio is playing.
-           * If false, then the audio must finish playing before a response is accepted.
-           */
-          response_allowed_while_playing: {
-              type: jspsych.ParameterType.BOOL,
-              pretty_name: "Response allowed while playing",
-              default: true,
-          },
-      },
-  };
-  /**
-   * **audio-button-response**
-   *
-   * jsPsych plugin for playing an audio file and getting a button response
-   *
-   * @author Kristin Diep
-   * @see {@link https://www.jspsych.org/plugins/jspsych-audio-button-response/ audio-button-response plugin documentation on jspsych.org}
-   */
-  class AudioButtonResponsePlugin {
-      constructor(jsPsych) {
-          this.jsPsych = jsPsych;
-      }
-      trial(display_element, trial, on_load) {
-          // hold the .resolve() function from the Promise that ends the trial
-          let trial_complete;
-          // setup stimulus
-          var context = this.jsPsych.pluginAPI.audioContext();
-          // store response
-          var response = {
-              rt: null,
-              button: null,
-          };
-          // record webaudio context start time
-          var startTime;
-          // load audio file
-          this.jsPsych.pluginAPI
-              .getAudioBuffer(trial.stimulus)
-              .then((buffer) => {
-              if (context !== null) {
-                  this.audio = context.createBufferSource();
-                  this.audio.buffer = buffer;
-                  this.audio.connect(context.destination);
-              }
-              else {
-                  this.audio = buffer;
-                  this.audio.currentTime = 0;
-              }
-              setupTrial();
-          })
-              .catch((err) => {
-              console.error(`Failed to load audio file "${trial.stimulus}". Try checking the file path. We recommend using the preload plugin to load audio files.`);
-              console.error(err);
-          });
-          const setupTrial = () => {
-              // set up end event if trial needs it
-              if (trial.trial_ends_after_audio) {
-                  this.audio.addEventListener("ended", end_trial);
-              }
-              // enable buttons after audio ends if necessary
-              if (!trial.response_allowed_while_playing && !trial.trial_ends_after_audio) {
-                  this.audio.addEventListener("ended", enable_buttons);
-              }
-              //display buttons
-              var buttons = [];
-              if (Array.isArray(trial.button_html)) {
-                  if (trial.button_html.length == trial.choices.length) {
-                      buttons = trial.button_html;
-                  }
-                  else {
-                      console.error("Error in audio-button-response plugin. The length of the button_html array does not equal the length of the choices array");
-                  }
-              }
-              else {
-                  for (var i = 0; i < trial.choices.length; i++) {
-                      buttons.push(trial.button_html);
-                  }
-              }
-              var html = '<div id="jspsych-audio-button-response-btngroup">';
-              for (var i = 0; i < trial.choices.length; i++) {
-                  var str = buttons[i].replace(/%choice%/g, trial.choices[i]);
-                  html +=
-                      '<div class="jspsych-audio-button-response-button" style="cursor: pointer; display: inline-block; margin:' +
-                          trial.margin_vertical +
-                          " " +
-                          trial.margin_horizontal +
-                          '" id="jspsych-audio-button-response-button-' +
-                          i +
-                          '" data-choice="' +
-                          i +
-                          '">' +
-                          str +
-                          "</div>";
-              }
-              html += "</div>";
-              //show prompt if there is one
-              if (trial.prompt !== null) {
-                  html += trial.prompt;
-              }
-              display_element.innerHTML = html;
-              if (trial.response_allowed_while_playing) {
-                  enable_buttons();
-              }
-              else {
-                  disable_buttons();
-              }
-              // start time
-              startTime = performance.now();
-              // start audio
-              if (context !== null) {
-                  startTime = context.currentTime;
-                  this.audio.start(startTime);
-              }
-              else {
-                  this.audio.play();
-              }
-              // end trial if time limit is set
-              if (trial.trial_duration !== null) {
-                  this.jsPsych.pluginAPI.setTimeout(() => {
-                      end_trial();
-                  }, trial.trial_duration);
-              }
-              on_load();
-          };
-          // function to handle responses by the subject
-          function after_response(choice) {
-              // measure rt
-              var endTime = performance.now();
-              var rt = Math.round(endTime - startTime);
-              if (context !== null) {
-                  endTime = context.currentTime;
-                  rt = Math.round((endTime - startTime) * 1000);
-              }
-              response.button = parseInt(choice);
-              response.rt = rt;
-              // disable all the buttons after a response
-              disable_buttons();
-              if (trial.response_ends_trial) {
-                  end_trial();
-              }
-          }
-          // function to end trial when it is time
-          const end_trial = () => {
-              // kill any remaining setTimeout handlers
-              this.jsPsych.pluginAPI.clearAllTimeouts();
-              // stop the audio file if it is playing
-              // remove end event listeners if they exist
-              if (context !== null) {
-                  this.audio.stop();
-              }
-              else {
-                  this.audio.pause();
-              }
-              this.audio.removeEventListener("ended", end_trial);
-              this.audio.removeEventListener("ended", enable_buttons);
-              // gather the data to store for the trial
-              var trial_data = {
-                  rt: response.rt,
-                  stimulus: trial.stimulus,
-                  response: response.button,
-              };
-              // clear the display
-              display_element.innerHTML = "";
-              // move on to the next trial
-              this.jsPsych.finishTrial(trial_data);
-              trial_complete();
-          };
-          function button_response(e) {
-              var choice = e.currentTarget.getAttribute("data-choice"); // don't use dataset for jsdom compatibility
-              after_response(choice);
-          }
-          function disable_buttons() {
-              var btns = document.querySelectorAll(".jspsych-audio-button-response-button");
-              for (var i = 0; i < btns.length; i++) {
-                  var btn_el = btns[i].querySelector("button");
-                  if (btn_el) {
-                      btn_el.disabled = true;
-                  }
-                  btns[i].removeEventListener("click", button_response);
-              }
-          }
-          function enable_buttons() {
-              var btns = document.querySelectorAll(".jspsych-audio-button-response-button");
-              for (var i = 0; i < btns.length; i++) {
-                  var btn_el = btns[i].querySelector("button");
-                  if (btn_el) {
-                      btn_el.disabled = false;
-                  }
-                  btns[i].addEventListener("click", button_response);
-              }
-          }
-          return new Promise((resolve) => {
-              trial_complete = resolve;
-          });
-      }
-      simulate(trial, simulation_mode, simulation_options, load_callback) {
-          if (simulation_mode == "data-only") {
-              load_callback();
-              this.simulate_data_only(trial, simulation_options);
-          }
-          if (simulation_mode == "visual") {
-              this.simulate_visual(trial, simulation_options, load_callback);
-          }
-      }
-      create_simulation_data(trial, simulation_options) {
-          const default_data = {
-              stimulus: trial.stimulus,
-              rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
-              response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
-          };
-          const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
-          this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
-          return data;
-      }
-      simulate_data_only(trial, simulation_options) {
-          const data = this.create_simulation_data(trial, simulation_options);
-          this.jsPsych.finishTrial(data);
-      }
-      simulate_visual(trial, simulation_options, load_callback) {
-          const data = this.create_simulation_data(trial, simulation_options);
-          const display_element = this.jsPsych.getDisplayElement();
-          const respond = () => {
-              if (data.rt !== null) {
-                  this.jsPsych.pluginAPI.clickTarget(display_element.querySelector(`div[data-choice="${data.response}"] button`), data.rt);
-              }
-          };
-          this.trial(display_element, trial, () => {
-              load_callback();
-              if (!trial.response_allowed_while_playing) {
-                  this.audio.addEventListener("ended", respond);
-              }
-              else {
-                  respond();
-              }
-          });
-      }
-  }
+  const info = {
+      name: "audio-button-response",
+      parameters: {
+          /** The audio to be played. */
+          stimulus: {
+              type: jspsych.ParameterType.AUDIO,
+              pretty_name: "Stimulus",
+              default: undefined,
+          },
+          /** Array containing the label(s) for the button(s). */
+          choices: {
+              type: jspsych.ParameterType.STRING,
+              pretty_name: "Choices",
+              default: undefined,
+              array: true,
+          },
+          /** The HTML for creating button. Can create own style. Use the "%choice%" string to indicate where the label from the choices parameter should be inserted. */
+          button_html: {
+              type: jspsych.ParameterType.HTML_STRING,
+              pretty_name: "Button HTML",
+              default: '<button class="jspsych-btn">%choice%</button>',
+              array: true,
+          },
+          /** Any content here will be displayed below the stimulus. */
+          prompt: {
+              type: jspsych.ParameterType.HTML_STRING,
+              pretty_name: "Prompt",
+              default: null,
+          },
+          /** The maximum duration to wait for a response. */
+          trial_duration: {
+              type: jspsych.ParameterType.INT,
+              pretty_name: "Trial duration",
+              default: null,
+          },
+          /** Vertical margin of button. */
+          margin_vertical: {
+              type: jspsych.ParameterType.STRING,
+              pretty_name: "Margin vertical",
+              default: "0px",
+          },
+          /** Horizontal margin of button. */
+          margin_horizontal: {
+              type: jspsych.ParameterType.STRING,
+              pretty_name: "Margin horizontal",
+              default: "8px",
+          },
+          /** If true, the trial will end when user makes a response. */
+          response_ends_trial: {
+              type: jspsych.ParameterType.BOOL,
+              pretty_name: "Response ends trial",
+              default: true,
+          },
+          /** If true, then the trial will end as soon as the audio file finishes playing. */
+          trial_ends_after_audio: {
+              type: jspsych.ParameterType.BOOL,
+              pretty_name: "Trial ends after audio",
+              default: false,
+          },
+          /**
+           * If true, then responses are allowed while the audio is playing.
+           * If false, then the audio must finish playing before a response is accepted.
+           */
+          response_allowed_while_playing: {
+              type: jspsych.ParameterType.BOOL,
+              pretty_name: "Response allowed while playing",
+              default: true,
+          },
+      },
+  };
+  /**
+   * **audio-button-response**
+   *
+   * jsPsych plugin for playing an audio file and getting a button response
+   *
+   * @author Kristin Diep
+   * @see {@link https://www.jspsych.org/plugins/jspsych-audio-button-response/ audio-button-response plugin documentation on jspsych.org}
+   */
+  class AudioButtonResponsePlugin {
+      constructor(jsPsych) {
+          this.jsPsych = jsPsych;
+      }
+      trial(display_element, trial, on_load) {
+          // hold the .resolve() function from the Promise that ends the trial
+          let trial_complete;
+          // setup stimulus
+          var context = this.jsPsych.pluginAPI.audioContext();
+          // store response
+          var response = {
+              rt: null,
+              button: null,
+          };
+          // record webaudio context start time
+          var startTime;
+          // load audio file
+          this.jsPsych.pluginAPI
+              .getAudioBuffer(trial.stimulus)
+              .then((buffer) => {
+              if (context !== null) {
+                  this.audio = context.createBufferSource();
+                  this.audio.buffer = buffer;
+                  this.audio.connect(context.destination);
+              }
+              else {
+                  this.audio = buffer;
+                  this.audio.currentTime = 0;
+              }
+              setupTrial();
+          })
+              .catch((err) => {
+              console.error(`Failed to load audio file "${trial.stimulus}". Try checking the file path. We recommend using the preload plugin to load audio files.`);
+              console.error(err);
+          });
+          const setupTrial = () => {
+              // set up end event if trial needs it
+              if (trial.trial_ends_after_audio) {
+                  this.audio.addEventListener("ended", end_trial);
+              }
+              // enable buttons after audio ends if necessary
+              if (!trial.response_allowed_while_playing && !trial.trial_ends_after_audio) {
+                  this.audio.addEventListener("ended", enable_buttons);
+              }
+              //display buttons
+              var buttons = [];
+              if (Array.isArray(trial.button_html)) {
+                  if (trial.button_html.length == trial.choices.length) {
+                      buttons = trial.button_html;
+                  }
+                  else {
+                      console.error("Error in audio-button-response plugin. The length of the button_html array does not equal the length of the choices array");
+                  }
+              }
+              else {
+                  for (var i = 0; i < trial.choices.length; i++) {
+                      buttons.push(trial.button_html);
+                  }
+              }
+              var html = '<div id="jspsych-audio-button-response-btngroup">';
+              for (var i = 0; i < trial.choices.length; i++) {
+                  var str = buttons[i].replace(/%choice%/g, trial.choices[i]);
+                  html +=
+                      '<div class="jspsych-audio-button-response-button" style="cursor: pointer; display: inline-block; margin:' +
+                          trial.margin_vertical +
+                          " " +
+                          trial.margin_horizontal +
+                          '" id="jspsych-audio-button-response-button-' +
+                          i +
+                          '" data-choice="' +
+                          i +
+                          '">' +
+                          str +
+                          "</div>";
+              }
+              html += "</div>";
+              //show prompt if there is one
+              if (trial.prompt !== null) {
+                  html += trial.prompt;
+              }
+              display_element.innerHTML = html;
+              if (trial.response_allowed_while_playing) {
+                  enable_buttons();
+              }
+              else {
+                  disable_buttons();
+              }
+              // start time
+              startTime = performance.now();
+              // start audio
+              if (context !== null) {
+                  startTime = context.currentTime;
+                  this.audio.start(startTime);
+              }
+              else {
+                  this.audio.play();
+              }
+              // end trial if time limit is set
+              if (trial.trial_duration !== null) {
+                  this.jsPsych.pluginAPI.setTimeout(() => {
+                      end_trial();
+                  }, trial.trial_duration);
+              }
+              on_load();
+          };
+          // function to handle responses by the subject
+          function after_response(choice) {
+              // measure rt
+              var endTime = performance.now();
+              var rt = Math.round(endTime - startTime);
+              if (context !== null) {
+                  endTime = context.currentTime;
+                  rt = Math.round((endTime - startTime) * 1000);
+              }
+              response.button = parseInt(choice);
+              response.rt = rt;
+              // disable all the buttons after a response
+              disable_buttons();
+              if (trial.response_ends_trial) {
+                  end_trial();
+              }
+          }
+          // function to end trial when it is time
+          const end_trial = () => {
+              // kill any remaining setTimeout handlers
+              this.jsPsych.pluginAPI.clearAllTimeouts();
+              // stop the audio file if it is playing
+              // remove end event listeners if they exist
+              if (context !== null) {
+                  this.audio.stop();
+              }
+              else {
+                  this.audio.pause();
+              }
+              this.audio.removeEventListener("ended", end_trial);
+              this.audio.removeEventListener("ended", enable_buttons);
+              // gather the data to store for the trial
+              var trial_data = {
+                  rt: response.rt,
+                  stimulus: trial.stimulus,
+                  response: response.button,
+              };
+              // clear the display
+              display_element.innerHTML = "";
+              // move on to the next trial
+              this.jsPsych.finishTrial(trial_data);
+              trial_complete();
+          };
+          function button_response(e) {
+              var choice = e.currentTarget.getAttribute("data-choice"); // don't use dataset for jsdom compatibility
+              after_response(choice);
+          }
+          function disable_buttons() {
+              var btns = document.querySelectorAll(".jspsych-audio-button-response-button");
+              for (var i = 0; i < btns.length; i++) {
+                  var btn_el = btns[i].querySelector("button");
+                  if (btn_el) {
+                      btn_el.disabled = true;
+                  }
+                  btns[i].removeEventListener("click", button_response);
+              }
+          }
+          function enable_buttons() {
+              var btns = document.querySelectorAll(".jspsych-audio-button-response-button");
+              for (var i = 0; i < btns.length; i++) {
+                  var btn_el = btns[i].querySelector("button");
+                  if (btn_el) {
+                      btn_el.disabled = false;
+                  }
+                  btns[i].addEventListener("click", button_response);
+              }
+          }
+          return new Promise((resolve) => {
+              trial_complete = resolve;
+          });
+      }
+      simulate(trial, simulation_mode, simulation_options, load_callback) {
+          if (simulation_mode == "data-only") {
+              load_callback();
+              this.simulate_data_only(trial, simulation_options);
+          }
+          if (simulation_mode == "visual") {
+              this.simulate_visual(trial, simulation_options, load_callback);
+          }
+      }
+      create_simulation_data(trial, simulation_options) {
+          const default_data = {
+              stimulus: trial.stimulus,
+              rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+              response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
+          };
+          const data = this.jsPsych.pluginAPI.mergeSimulationData(default_data, simulation_options);
+          this.jsPsych.pluginAPI.ensureSimulationDataConsistency(trial, data);
+          return data;
+      }
+      simulate_data_only(trial, simulation_options) {
+          const data = this.create_simulation_data(trial, simulation_options);
+          this.jsPsych.finishTrial(data);
+      }
+      simulate_visual(trial, simulation_options, load_callback) {
+          const data = this.create_simulation_data(trial, simulation_options);
+          const display_element = this.jsPsych.getDisplayElement();
+          const respond = () => {
+              if (data.rt !== null) {
+                  this.jsPsych.pluginAPI.clickTarget(display_element.querySelector(`div[data-choice="${data.response}"] button`), data.rt);
+              }
+          };
+          this.trial(display_element, trial, () => {
+              load_callback();
+              if (!trial.response_allowed_while_playing) {
+                  this.audio.addEventListener("ended", respond);
+              }
+              else {
+                  respond();
+              }
+          });
+      }
+  }
   AudioButtonResponsePlugin.info = info;
 
   return AudioButtonResponsePlugin;
 
 })(jsPsychModule);
-//# sourceMappingURL=index.browser.js.map
+//# sourceMappingURL=https://unpkg.com/@jspsych/plugin-audio-button-response@1.1.3/dist/index.browser.js.map