Merge branch 'master' into feature-key-code-update

docs/core_library/jspsych-pluginAPI.md

@@ -172,23 +172,45 @@ filepath | string | The path to the audio file that was preloaded.
 
 ### Return value
 
-Returns buffered audio file for playback. If the browser supports it the buffer will be playable with the WebAudio API. Otherwise, the returned buffer will be an HTML5 Audio object.
+Returns a Promise that resolves when the audio file loads. Success handler's parameter will be the audio buffer. If the experiment is running using the WebAudio API it will be an AudioBuffer object. Otherwise, it will be an HTML5 Audio object. The failure handler's parameter is the error generated by `preloadAudio`.
 
 ### Description
 
-Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. The file must be preloaded with the `preload` plugin.
+Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. 
+
+It is strongly recommended that you preload audio files before calling this method. This method will load the files if they are not preloaded, but this may result in delays during the experiment as audio is downloaded.
 
 ### Examples
 
+#### HTML 5 Audio
 ```javascript
-// the code below is used to play audio in the audio-keyboard-response plugin
+jsPsych.pluginAPI.getAudioBuffer('my-sound.mp3')
-var source = context.createBufferSource();
+  .then(function(audio){
-source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+    audio.play();
-source.connect(context.destination);
+  })
-startTime = context.currentTime;
+  .catch(function(err){
-source.start(startTime);
+    console.error('Audio file failed to load')
+  })
 ```
 
+#### WebAudio API
+```javascript
+var context = jsPsych.pluginAPI.audioContext();
+
+jsPsych.pluginAPI.getAudioBuffer('my-sound.mp3')
+  .then(function(buffer){
+    audio = context.createBufferSource();
+    audio.buffer = buffer;
+    audio.connect(context.destination);
+    audio.start(context.currentTime);
+  })
+  .catch(function(err){
+    console.error('Audio file failed to load')
+  })
+```
+
+See the `audio-keyboard-response` plugin for an example in a fuller context.
+
 ---
 ## jsPsych.pluginAPI.getAutoPreloadList
 

docs/plugins/jspsych-webgazer-calibrate.md

@@ -4,7 +4,7 @@ This plugin can be used to calibrate the [WebGazer extension](/extensions/jspsyc
 
 ## Parameters
 
-In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
+In addition to the [parameters available in all plugins](/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
 
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
@@ -17,7 +17,7 @@ time_per_point | numeric | 1000 | If `calibration_mode` is set to `view`, then t
 
 ## Data Generated
 
-In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
+In addition to the [default data collected by all plugins](/overview/plugins#data-collected-by-plugins), this plugin collects the following data for each trial.
 
 Name | Type | Value
 -----|------|------

docs/plugins/jspsych-webgazer-init-camera.md

@@ -4,7 +4,7 @@ This plugin initializes the camera and helps the participant center their face i
 
 ## Parameters
 
-In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
+In addition to the [parameters available in all plugins](/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
 
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
@@ -13,7 +13,7 @@ button_text | string | Continue | The text for the button that participants clic
 
 ## Data Generated
 
-In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
+In addition to the [default data collected by all plugins](/overview/plugins#data-collected-by-plugins), this plugin collects the following data for each trial.
 
 Name | Type | Value
 -----|------|------

docs/plugins/jspsych-webgazer-validate.md

@@ -4,7 +4,7 @@ This plugin can be used to measure the accuracy and precision of gaze prediction
 
 ## Parameters
 
-In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
+In addition to the [parameters available in all plugins](/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
 
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
@@ -20,7 +20,7 @@ show_validation_data | bool | false | If `true` then a visualization of the vali
 
 ## Data Generated
 
-In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
+In addition to the [default data collected by all plugins](/overview/plugins#data-collected-by-plugins), this plugin collects the following data for each trial.
 
 Name | Type | Value
 -----|------|------

docs/tutorials/video-tutorials.md

@@ -1,5 +1,11 @@
 # Video tutorials
 
+## YouTube Channel
+
 A variety of video tutorials are available on [Josh de Leeuw's YouTube channel](https://www.youtube.com/playlist?list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh). Some tutorials walk through creating a basic version of an entire experiment, like the tutorial on creating a [dichotic listening experiment](https://www.youtube.com/playlist?list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh) aimed at new users. Others focus on specific features of jsPsych, like how to use [functions as parameters](https://www.youtube.com/watch?v=8-j2aAZ_iOk&list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh&index=5) to create experiments that change in response to participant input or how to [create a new plugin](https://www.youtube.com/watch?v=XQcsFwAmbiw&list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh&index=4).
 
-Recordings from a Summer 2020 workshop on conducting online research with jsPsych are available on the [workshop's YouTube channel](https://www.youtube.com/channel/UCBZ5F1UysHWlplUNDRwbsWA). [Session 1](https://www.youtube.com/watch?v=BuhfsIFRFe8) provides an overview of jsPsych suitable for brand new users. [Session 3](https://www.youtube.com/watch?v=LP7o0iAALik) covers some more advanced features of jsPsych.
+## Workshops
+
+**Moving Research Online (2020)**. Recordings from a [Summer 2020 workshop](https://www.movingresearchonline.info) on conducting online research are available on the [workshop's YouTube channel](https://www.youtube.com/channel/UCBZ5F1UysHWlplUNDRwbsWA). [Session 1](https://www.youtube.com/watch?v=BuhfsIFRFe8) provides an overview of jsPsych suitable for brand new users. [Session 3](https://www.youtube.com/watch?v=LP7o0iAALik) covers some more advanced features of jsPsych. This workshop was funded by the National Science Foundation.
+
+**babySTEP (2021)**. The Centre for Comparative Psycholinguistics (CCP, University of Alberta Department of Linguistics) hosted a two-part jsPsych workshop in 2021 as part of their annual [STEP program](https://ccp.artsrn.ualberta.ca/portfolio/step/). [Day 1](https://drive.google.com/file/d/1_bd_Tz1IoyGaZzuPoR_Qb6Rtd5wg4t4D/view?usp=drive_web) covered the basics of creating a jsPsych experiment, with an emphasis on audio stimuli. [Day 2](https://drive.google.com/file/d/1dIw1xIVY1lCHwFKGRaUnWMguwHfdkbGK/view?usp=drive_web) was organized around pre-submitted questions. The video demonstrates how to create a more complex experiment involving reading a sentence and hearing different audio options for completing the sentences, and answers several questions about timing accuracy, recording participant generated audio, embedding jsPsych into course (or other) websites, and some (non-empirical) advice about attention checks.

jspsych.js

@@ -2532,12 +2532,22 @@ jsPsych.pluginAPI = (function() {
 
   module.getAudioBuffer = function(audioID) {
 
-    if (audio_buffers[audioID] === 'tmp') {
+    return new Promise(function(resolve, reject){
-      console.error('Audio file failed to load in the time allotted.')
+      // check whether audio file already preloaded
-      return;
+      if(typeof audio_buffers[audioID] == 'undefined' || audio_buffers[audioID] == 'tmp'){
+         // if audio is not already loaded, try to load it
+        function complete(){
+          resolve(audio_buffers[audioID])
         }
-
+        function error(e){
-    return audio_buffers[audioID];
+          reject(e.error);
+        }
+        module.preloadAudio([audioID], complete, function(){}, error)
+      } else {
+        // audio is already loaded
+        resolve(audio_buffers[audioID]);
+      }
+    });
 
   }
 

plugins/jspsych-audio-button-response.js

@@ -87,31 +87,44 @@ jsPsych.plugins["audio-button-response"] = (function() {
 
     // setup stimulus
     var context = jsPsych.pluginAPI.audioContext();
+    var audio;
+
+    // store response
+    var response = {
+      rt: null,
+      button: null
+    };
+
+    // record webaudio context start time
+    var startTime;
+
+    // load audio file
+    jsPsych.pluginAPI.getAudioBuffer(trial.stimulus)
+      .then(function (buffer) {
         if (context !== null) {
-      var source = context.createBufferSource();
+          audio = context.createBufferSource();
-      source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio.buffer = buffer;
-      source.connect(context.destination);
+          audio.connect(context.destination);
         } else {
-      var audio = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio = buffer;
           audio.currentTime = 0;
         }
+        setupTrial();
+      })
+      .catch(function (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)
+      });
 
+    function setupTrial() {
       // set up end event if trial needs it
       if (trial.trial_ends_after_audio) {
-      if(context !== null){
-        source.addEventListener('ended', end_trial);
-      } else {
         audio.addEventListener('ended', end_trial);
       }
-    }
 
       // enable buttons after audio ends if necessary
       if ((!trial.response_allowed_while_playing) & (!trial.trial_ends_after_audio)) {
-      if (context !== null) {
-        source.addEventListener('ended', enable_buttons);
-      } else {
         audio.addEventListener('ended', enable_buttons);
-      }
       }
 
       //display buttons
@@ -120,7 +133,7 @@ jsPsych.plugins["audio-button-response"] = (function() {
         if (trial.button_html.length == trial.choices.length) {
           buttons = trial.button_html;
         } else {
-        console.error('Error in image-button-response plugin. The length of the button_html array does not equal the length of the choices array');
+          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++) {
@@ -148,11 +161,26 @@ jsPsych.plugins["audio-button-response"] = (function() {
         disable_buttons();
       }
 
-    // store response
+      // start time
-    var response = {
+      startTime = performance.now();
-      rt: null,
+
-      button: null
+      // start audio
-    };
+      if (context !== null) {
+        startTime = context.currentTime;
+        audio.start(startTime);
+      } else {
+        audio.play();
+      }
+
+      // end trial if time limit is set
+      if (trial.trial_duration !== null) {
+        jsPsych.pluginAPI.setTimeout(function () {
+          end_trial();
+        }, trial.trial_duration);
+      }
+    }
+
+
 
     // function to handle responses by the subject
     function after_response(choice) {
@@ -184,14 +212,13 @@ jsPsych.plugins["audio-button-response"] = (function() {
       // stop the audio file if it is playing
       // remove end event listeners if they exist
       if (context !== null) {
-				source.stop();
+        audio.stop();
-        source.removeEventListener('ended', end_trial);
-        source.removeEventListener('ended', enable_buttons);
       } else {
         audio.pause();
+      }
+
       audio.removeEventListener('ended', end_trial);
       audio.removeEventListener('ended', enable_buttons);
-			}
 
       // gather the data to store for the trial
       var trial_data = {
@@ -234,23 +261,7 @@ jsPsych.plugins["audio-button-response"] = (function() {
       }
     }
 
-		// start time
-    var startTime = performance.now();
 
-		// start audio
-    if(context !== null){
-      startTime = context.currentTime;
-      source.start(startTime);
-    } else {
-      audio.play();
-    }
-
-    // end trial if time limit is set
-    if (trial.trial_duration !== null) {
-      jsPsych.pluginAPI.setTimeout(function() {
-        end_trial();
-      }, trial.trial_duration);
-    }
 
   };
 

plugins/jspsych-audio-keyboard-response.js

@@ -69,34 +69,69 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
 
     // setup stimulus
     var context = jsPsych.pluginAPI.audioContext();
+    var audio;
+
+    // store response
+    var response = {
+      rt: null,
+      key: null
+    };
+
+    // record webaudio context start time
+    var startTime;
+
+    // load audio file
+    jsPsych.pluginAPI.getAudioBuffer(trial.stimulus)
+      .then(function (buffer) {
         if (context !== null) {
-      var source = context.createBufferSource();
+          audio = context.createBufferSource();
-      source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio.buffer = buffer;
-      source.connect(context.destination);
+          audio.connect(context.destination);
         } else {
-      var audio = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio = buffer;
           audio.currentTime = 0;
         }
+        setupTrial();
+      })
+      .catch(function (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)
+      });
 
+    function setupTrial() {
       // set up end event if trial needs it
       if (trial.trial_ends_after_audio) {
-      if(context !== null){
-        source.addEventListener('ended', end_trial);
-      } else {
         audio.addEventListener('ended', end_trial);
       }
-    }
 
       // show prompt if there is one
       if (trial.prompt !== null) {
         display_element.innerHTML = trial.prompt;
       }
 
-    // store response
+      // start audio
-    var response = {
+      if (context !== null) {
-      rt: null,
+        startTime = context.currentTime;
-      key: null
+        audio.start(startTime);
-    };
+      } else {
+        audio.play();
+      }
+
+      // start keyboard listener when trial starts or sound ends
+      if (trial.response_allowed_while_playing) {
+        setup_keyboard_listener();
+      } else if (!trial.trial_ends_after_audio) {
+        audio.addEventListener('ended', setup_keyboard_listener);
+      }
+
+      // end trial if time limit is set
+      if (trial.trial_duration !== null) {
+        jsPsych.pluginAPI.setTimeout(function () {
+          end_trial();
+        }, trial.trial_duration);
+      }
+    }
+
 
     // function to end trial when it is time
     function end_trial() {
@@ -107,14 +142,14 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
       // stop the audio file if it is playing
       // remove end event listeners if they exist
       if (context !== null) {
-        source.stop();
+        audio.stop();
-        source.removeEventListener('ended', end_trial);
-        source.removeEventListener('ended', setup_keyboard_listener);
       } else {
         audio.pause();
+      }
+
       audio.removeEventListener('ended', end_trial);
       audio.removeEventListener('ended', setup_keyboard_listener);
-      }
+
 
       // kill keyboard listeners
       jsPsych.pluginAPI.cancelAllKeyboardResponses();
@@ -137,7 +172,7 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
     }
 
     // function to handle responses by the subject
-    var after_response = function(info) {
+    function after_response(info) {
 
       // only record the first response
       if (response.key == null) {
@@ -152,7 +187,7 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
     function setup_keyboard_listener() {
       // start the response listener
       if (context !== null) {
-        var keyboardListener = jsPsych.pluginAPI.getKeyboardResponse({
+        jsPsych.pluginAPI.getKeyboardResponse({
           callback_function: after_response,
           valid_responses: trial.choices,
           rt_method: 'audio',
@@ -162,7 +197,7 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
           audio_context_start_time: startTime
         });
       } else {
-        var keyboardListener = jsPsych.pluginAPI.getKeyboardResponse({
+        jsPsych.pluginAPI.getKeyboardResponse({
           callback_function: after_response,
           valid_responses: trial.choices,
           rt_method: 'performance',
@@ -171,33 +206,6 @@ jsPsych.plugins["audio-keyboard-response"] = (function() {
         });
       }
     }
-
-    // start audio
-    if(context !== null){
-      var startTime = context.currentTime;
-      source.start(startTime);
-    } else {
-      audio.play();
-    }
-
-    // start keyboard listener when trial starts or sound ends
-    if (trial.response_allowed_while_playing) {
-      setup_keyboard_listener();
-    } else if (!trial.trial_ends_after_audio) {
-      if(context !== null){
-        source.addEventListener('ended', setup_keyboard_listener);
-      } else {
-        audio.addEventListener('ended', setup_keyboard_listener);
-      }
-    }
-
-    // end trial if time limit is set
-    if (trial.trial_duration !== null) {
-      jsPsych.pluginAPI.setTimeout(function() {
-        end_trial();
-      }, trial.trial_duration);
-    }
-
   };
 
   return plugin;

plugins/jspsych-audio-slider-response.js

@@ -98,31 +98,48 @@ jsPsych.plugins['audio-slider-response'] = (function() {
 
     // setup stimulus
     var context = jsPsych.pluginAPI.audioContext();
+    var audio;
+
+    // record webaudio context start time
+    var startTime;
+
+    // for storing data related to response
+    var response;
+
+
+    // load audio file
+    jsPsych.pluginAPI.getAudioBuffer(trial.stimulus)
+      .then(function (buffer) {
         if (context !== null) {
-      var source = context.createBufferSource();
+          audio = context.createBufferSource();
-      source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio.buffer = buffer;
-      source.connect(context.destination);
+          audio.connect(context.destination);
         } else {
-      var audio = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
+          audio = buffer;
           audio.currentTime = 0;
         }
+        setupTrial();
+      })
+      .catch(function (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)
+      });
+
+    function setupTrial() {
+
 
       // set up end event if trial needs it
       if (trial.trial_ends_after_audio) {
-      if(context !== null){
+
-        source.addEventListener('ended', end_trial);
-      } else {
         audio.addEventListener('ended', end_trial);
-      }
+
       }
 
       // enable slider after audio ends if necessary
       if ((!trial.response_allowed_while_playing) & (!trial.trial_ends_after_audio)) {
-      if (context !== null) {
+
-        source.addEventListener('ended', enable_slider);
-      } else {
         audio.addEventListener('ended', enable_slider);
-      }
+
       }
 
       var html = '<div id="jspsych-audio-slider-response-wrapper" style="margin: 100px 0px;">';
@@ -165,7 +182,7 @@ jsPsych.plugins['audio-slider-response'] = (function() {
 
       display_element.innerHTML = html;
 
-    var response = {
+      response = {
         rt: null,
         response: null
       };
@@ -200,6 +217,31 @@ jsPsych.plugins['audio-slider-response'] = (function() {
 
       });
 
+      startTime = performance.now();
+      // start audio
+      if (context !== null) {
+        startTime = context.currentTime;
+        audio.start(startTime);
+      } else {
+        audio.play();
+      }
+
+      // end trial if trial_duration is set
+      if (trial.trial_duration !== null) {
+        jsPsych.pluginAPI.setTimeout(function () {
+          end_trial();
+        }, trial.trial_duration);
+      }
+    }
+
+    // function to enable slider after audio ends
+    function enable_slider() {
+      document.querySelector('#jspsych-audio-slider-response-response').disabled = false;
+      if (!trial.require_movement) {
+        document.querySelector('#jspsych-audio-slider-response-next').disabled = false;
+      }
+    }
+
     function end_trial() {
 
       // kill any remaining setTimeout handlers
@@ -208,14 +250,14 @@ jsPsych.plugins['audio-slider-response'] = (function() {
       // stop the audio file if it is playing
       // remove end event listeners if they exist
       if (context !== null) {
-        source.stop();
+        audio.stop();
-        source.removeEventListener('ended', end_trial);
-        source.removeEventListener('ended', enable_slider);
       } else {
         audio.pause();
+      }
+
       audio.removeEventListener('ended', end_trial);
       audio.removeEventListener('ended', enable_slider);
-      }
+
 
       // save data
       var trialdata = {
@@ -230,32 +272,6 @@ jsPsych.plugins['audio-slider-response'] = (function() {
       // next trial
       jsPsych.finishTrial(trialdata);
     }
-
-    // function to enable slider after audio ends
-    function enable_slider() {
-      document.querySelector('#jspsych-audio-slider-response-response').disabled = false;
-      if (!trial.require_movement) {
-        document.querySelector('#jspsych-audio-slider-response-next').disabled = false;
-      }
-    }
-
-		var startTime = performance.now();
-		// start audio
-    if(context !== null){
-      startTime = context.currentTime;
-      source.start(startTime);
-    } else {
-      audio.play();
-    }
-
-    // end trial if trial_duration is set
-    if (trial.trial_duration !== null) {
-      jsPsych.pluginAPI.setTimeout(function() {
-        end_trial();
-      }, trial.trial_duration);
-    }
-
-
   };
 
   return plugin;