HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 11:10:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Becky Gilbert 2021-02-19 10:24:21 -08:00 committed by GitHub
commit 0800497060
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 414 additions and 341 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
docs/core_library/jspsych-pluginAPI.md
View File

@ -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
var source = context.createBufferSource();
source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
source.connect(context.destination);
startTime = context.currentTime;
source.start(startTime);
jsPsych.pluginAPI.getAudioBuffer('my-sound.mp3')
.then(function(audio){
audio.play();
})
.catch(function(err){
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

4
docs/plugins/jspsych-webgazer-calibrate.md
View File

@ -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
-----|------|------

4
docs/plugins/jspsych-webgazer-init-camera.md
View File

@ -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
-----|------|------

4
docs/plugins/jspsych-webgazer-validate.md
View File

@ -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
-----|------|------

8
docs/tutorials/video-tutorials.md
View File

@ -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.

20
jspsych.js
View File

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

87
plugins/jspsych-audio-button-response.js
View File

@ -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();
source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
source.connect(context.destination);
audio = context.createBufferSource();
audio.buffer = buffer;
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
var response = {
rt: null,
button: null
};
// start time
startTime = performance.now();
// 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();
source.removeEventListener('ended', end_trial);
source.removeEventListener('ended', enable_buttons);
audio.stop();
} 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);
}
};

102
plugins/jspsych-audio-keyboard-response.js
View File

@ -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();
source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
source.connect(context.destination);
audio = context.createBufferSource();
audio.buffer = buffer;
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
var response = {
rt: null,
key: null
};
// start audio
if (context !== null) {
startTime = context.currentTime;
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();
source.removeEventListener('ended', end_trial);
source.removeEventListener('ended', setup_keyboard_listener);
audio.stop();
} 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;

102
plugins/jspsych-audio-slider-response.js
View File

@ -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();
source.buffer = jsPsych.pluginAPI.getAudioBuffer(trial.stimulus);
source.connect(context.destination);
audio = context.createBufferSource();
audio.buffer = buffer;
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();
source.removeEventListener('ended', end_trial);
source.removeEventListener('ended', enable_slider);
audio.stop();
} 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;