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

Merge pull request #1509 from jspsych/preload-docs

Browse Source 
Merging preload docs
This commit is contained in:
Josh de Leeuw 2021-02-12 11:38:22 -05:00 committed by GitHub
commit 2fece8c7b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
38 changed files with 816 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/core_library/jspsych-core.md
View File

@ -3,7 +3,7 @@
---
## jsPsych.addNodeToEndOfTimeline
```
jsPsych.addNodeToEndOfTimeline(node_parameters, callback)
jsPsych.addNodeToEndOfTimeline(node_parameters)
```
### Parameters
@ -11,7 +11,6 @@ jsPsych.addNodeToEndOfTimeline(node_parameters, callback)
| Parameter | Type | Description |
| --------------- | -------- | ---------------------------------------- |
| node_parameters | object | An object defining a timeline. It must have, at a minimum, a `timeline` parameter with a valid timeline array as the value for that parameter. |
| callback | function | An optional callback function. If adding the node to the timeline requires any preloading of media assets, this callback will be triggered after preloading is compelte. |
### Return value
@ -385,17 +384,11 @@ The settings object can contain several parameters. The only *required* paramete
| show_progress_bar | boolean | If true, then [a progress bar](../overview/progress-bar.md) is shown at the top of the page. |
| message_progress_bar | string | Message to display next to the progress bar. The default is 'Completion Progress'. |
| auto_update_progress_bar | boolean | If true, then the progress bar at the top of the page will automatically update as every top-level timeline or trial is completed. |
| show_preload_progress_bar | boolean | If true, then a progress bar is displayed while media files are automatically preloaded. |
| preload_audio | array | An array of audio files to preload before starting the experiment. |
| preload_images | array | An array of image files to preload before starting the experiment. |
| preload_video | array | An array of video files to preload before starting the experiment. |
| max_load_time | numeric | The maximum number of milliseconds to wait for content to preload. If the wait time is exceeded an error message is displayed and the experiment stops. The default value is 60 seconds. |
| max_preload_attempts | numeric | The maximum number of attempts to preload each file in case of an error. The default value is 10. There is a small delay of 200ms between each attempt. |
| use_webaudio | boolean | If false, then jsPsych will not attempt to use the WebAudio API for audio playback. Instead, HTML5 Audio objects will be used. The WebAudio API offers more precise control over the timing of audio events, and should be used when possible. The default value is true. |
| default_iti | numeric | The default inter-trial interval in ms. The default value if none is specified is 0ms. |
| experiment_width | numeric | The desired width of the jsPsych container in pixels. If left undefined, the width will be 100% of the display element. Usually this is the `<body>` element, and the width will be 100% of the screen size. |
| minimum_valid_rt | numeric | The minimum valid response time for key presses during the experiment. Any key press response time that is less than this value will be treated as invalid and ignored. Note that this parameter only applies to _keyboard responses_, and not to other response types such as buttons and sliders. The default value is 0. |
| override_safe_mode | boolean | Running a jsPsych experiment directly in a web browser (e.g., by double clicking on a local HTML file) will load the page using the `file://` protocol. Some features of jsPsych don't work with this protocol. By default, when jsPsych detects that it's running on a page loaded via the `file://` protocol, it runs in _safe mode_, which automatically disables features that don't work in this context. Specifically, the use of Web Audio is disabled (audio will be played using HTML5 audio instead, even if `use_webaudio` is `true`) and video preloading is disabled (both automatic preloading and manual preloading via `preload_video`). The `override_safe_mode` parameter defaults to `false`, but you can set it to `true` to force these features to operate under the `file://` protocol. In order for this to work, you will need to disable web security (CORS) features in your browser - this is safe to do if you know what you are doing. Note that this parameter has no effect when you are running the experiment on a web server, because the page will be loaded via the `http://` or `https://` protocol. |
| override_safe_mode | boolean | Running a jsPsych experiment directly in a web browser (e.g., by double clicking on a local HTML file) will load the page using the `file://` protocol. Some features of jsPsych don't work with this protocol. By default, when jsPsych detects that it's running on a page loaded via the `file://` protocol, it runs in _safe mode_, which automatically disables features that don't work in this context. Specifically, the use of Web Audio is disabled (audio will be played using HTML5 audio instead, even if `use_webaudio` is `true`) and video preloading is disabled. The `override_safe_mode` parameter defaults to `false`, but you can set it to `true` to force these features to operate under the `file://` protocol. In order for this to work, you will need to disable web security (CORS) features in your browser - this is safe to do if you know what you are doing. Note that this parameter has no effect when you are running the experiment on a web server, because the page will be loaded via the `http://` or `https://` protocol. |
| case_sensitive_responses | boolean | If true, then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. "A" (uppercase) will not be recognized as a valid response if the trial only accepts "a" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both "a" and "A" responses will be valid when the trial's key choice parameter is "a". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is false. |
Possible values for the exclusions parameter above.

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

@ -2,39 +2,6 @@
The pluginAPI module contains functions that are useful when developing new plugins.
---
## jsPsych.pluginAPI.autoPreload
```
jsPsych.pluginAPI.autoPreload(timeline, callback)
```
### Parameters
Parameter | Type | Description
----------|------|------------
timeline | TimelineNode object | A TimelineNode object that contains an arbitrary set of trials.
callback | function | A function to execute when loading is complete
### Return value
Returns nothing.
### Description
Attempts to preload all image files and audio files that will be used to run the trials on the timeline. Content will only preload from plugins that have used the `registerPreload` method to define the media types of their parameters.
The callback function executes once all of the files are preloaded.
This method is used internally by the core jsPsych code. It is not recommended that you call it manually.
### Examples
```javascript
// you probably shouldn't use this method
```
---
## jsPsych.pluginAPI.cancelAllKeyboardResponses
@ -118,6 +85,7 @@ Returns nothing.
Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout()
---
## jsPsych.pluginAPI.getAudioBuffer
```
@ -136,7 +104,7 @@ Returns buffered audio file for playback. If the browser supports it the buffer
### 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 `preloadAudioFiles` or the automatic preload (`autoPreload`).
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.
### Examples
@ -149,6 +117,51 @@ startTime = context.currentTime;
source.start(startTime);
```
## jsPsych.pluginAPI.getAutoPreloadList
```
jsPsych.pluginAPI.getAutoPreloadList(timeline)
```
### Parameters
Parameter | Type | Description
----------|------|------------
timeline | array | An array containing the trial object(s) from which a list of media files should be automatically generated. This array can contain the entire experiment timeline, or any individual parts of a larger timeline, such as specific timeline nodes and trial objects.
### Return value
An object with properties for each media type: `images`, `audio`, and `video`. Each property contains an array of the unique files of that media type that were automatically extracted from the timeline. If no files are found in the timeline for a particular media type, then the array will be empty for that type.
### Description
This method is used to automatically generate lists of unique image, audio, and video files from a timeline. It is used by the `preload` plugin to generate a list of to-be-preloaded files based on the trials passed to the `trials` parameter and/or the experiment timeline passed to `jsPsych.init` (when `auto_preload` is true). It can be used in custom plugins and experiment code to generate a list of audio/image/video files, based on a timeline.
This function will only return files from plugins that have used the `registerPreload` method to define the media types of their parameters, and only when the trial's parameter value is not a function. When a file path is returned to the trial parameter from a function (including by `jsPsych.timelineVariable` function), or when the file path is embedded in an HTML string, that file will not be detected by the `getAutoPreloadList` method. In these cases, the file should be preloaded manually. See [Media Preloading](../overview/media-preloading.md) for more information.
### Example
```javascript
var audio_trial = {
type: 'audio-keyboard-response'
stimulus: 'file.mp3'
}
var image_trial = {
type: 'image-keyboard-response'
stimulus: 'file.png'
}
var video_trial = {
type: 'video-keyboard-response'
stimulus: 'file.mp4'
}
var timeline = [audio_trial, image_trial, video_trial];
jsPsych.pluginAPI.getAutoPreloadList(timeline);
```
---
## jsPsych.pluginAPI.getKeyboardResponse
@ -219,10 +232,10 @@ var listener = jsPsych.pluginAPI.getKeyboardResponse({
```
---
## jsPsych.pluginAPI.preloadAudioFiles
## jsPsych.pluginAPI.preloadAudio
```
jsPsych.pluginAPI.preloadAudioFiles(files, callback_complete, callback_load)
jsPsych.pluginAPI.preloadAudio(files, callback_complete, callback_load, callback_error)
```
### Parameters
@ -231,7 +244,8 @@ Parameter | Type | Description
----------|------|------------
files | array | An array of audio file paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task).
callback_complete | function | A function to execute when all the files have been loaded.
callback_load | function | A function to execute after each file has been loaded. A single parameter is passed to this function which contains the number of files that have been loaded so far.
callback_load | function | A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded.
callback_error | function | A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.
### Return value
@ -239,11 +253,11 @@ Returns nothing.
### Description
Use this function to preload audio files that are not part of a plugin with automatic preloading. Audio files in official plugins will automatically preload. See [Media Preloading](../overview/media-preloading.md) for more information.
This function is used to preload audio files. It is used by the `preload` plugin, and could be called directly to preload audio files in custom plugins or experiment. See [Media Preloading](../overview/media-preloading.md) for more information.
It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the files are loaded. Thus, it is possible that an audio file would be required for playing before it is done preloading. The `callback_complete` function will only execute after all the audio files are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the `callback_complete` function).
The `callback_load` function can be used to indicate progress. See example below.
The `callback_load` and `callback_error` functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.
### Examples
@ -252,7 +266,11 @@ The `callback_load` function can be used to indicate progress. See example below
var sounds = ['file1.mp3', 'file2.mp3', 'file3.mp3'];
jsPsych.pluginAPI.preloadAudioFiles(sounds, function(){ startExperiment(); });
jsPsych.pluginAPI.preloadAudio(sounds,
function(){ startExperiment(); },
function(file){ console.log('file loaded: ', file); }
function(file){ console.log('error loading file: ', file); }
);
function startExperiment(){
jsPsych.init({
@ -266,11 +284,13 @@ function startExperiment(){
```javascript
var sounds = ['file1.mp3', 'file2.mp3', 'file3.mp3'];
var n_loaded = 0;
jsPsych.pluginAPI.preloadAudioFiles(sounds, function(){ startExperiment(); }, function(nLoaded) { updateLoadedCount(nLoaded); });
jsPsych.pluginAPI.preloadAudio(sounds, function(){ startExperiment(); }, function(file) { updateLoadedCount(file); });
function updateLoadedCount(nLoaded){
var percentcomplete = nLoaded / sounds.length * 100;
function updateLoadedCount(file){
n_loaded++;
var percentcomplete = n_loaded / sounds.length * 100;
// could put something fancier here, like a progress bar
// or updating text in the DOM.
@ -284,12 +304,11 @@ function startExperiment(){
}
```
---
## jsPsych.pluginAPI.preloadImages
```
jsPsych.pluginAPI.preloadImages(images, callback_complete, callback_load)
jsPsych.pluginAPI.preloadImages(images, callback_complete, callback_load, callback_error)
```
### Parameters
@ -298,7 +317,8 @@ Parameter | Type | Description
----------|------|------------
images | array | An array of image paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task).
callback_complete | function | A function to execute when all the images have been loaded.
callback_load | function | A function to execute after each image has been loaded. A single parameter is passed to this function which contains the number of images that have been loaded so far.
callback_load | function | A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded.
callback_error | function | A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.
### Return value
@ -306,11 +326,11 @@ Returns nothing.
### Description
Use this function to preload image files that are not part of a plugin with automatic preloading. Image files in official plugins will automatically preload. See [Media Preloading](../overview/media-preloading.md) for more information.
This function is used to preload image files. It is used by the `preload` plugin, and could be called directly to preload image files in custom plugins or experiment code. See [Media Preloading](../overview/media-preloading.md) for more information.
It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the images are loaded. Thus, it is possible that an image would be required for display before it is done preloading. The `callback_complete` function will only execute after all the images are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the `callback_complete` function).
The `callback_load` function can be used to indicate progress, if the number of images to be loaded is known ahead of time. See example below.
The `callback_load` and `callback_error` functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.
### Examples
@ -319,7 +339,11 @@ The `callback_load` function can be used to indicate progress, if the number of
var images = ['img/file1.png', 'img/file2.png', 'img/file3.png'];
jsPsych.pluginAPI.preloadImages(images, function(){ startExperiment(); });
jsPsych.pluginAPI.preloadImages(images,
function(){ startExperiment(); },
function(file){ console.log('file loaded: ', file); }
function(file){ console.log('error loading file: ', file); }
);
function startExperiment(){
jsPsych.init({
@ -333,11 +357,13 @@ function startExperiment(){
```javascript
var images = ['img/file1.png', 'img/file2.png', 'img/file3.png'];
var n_loaded = 0;
jsPsych.pluginAPI.preloadImages(images, function(){ startExperiment(); }, function(nLoaded) { updateLoadedCount(nLoaded); });
jsPsych.pluginAPI.preloadImages(images, function(){ startExperiment(); }, function(file) { updateLoadedCount(file); });
function updateLoadedCount(nLoaded){
var percentcomplete = nLoaded / images.length * 100;
function updateLoadedCount(file){
n_loaded++;
var percentcomplete = n_loaded / images.length * 100;
// could put something fancier here, like a progress bar
// or updating text in the DOM.
@ -351,11 +377,84 @@ function startExperiment(){
}
```
---
## jsPsych.pluginAPI.preloadVideo
```
jsPsych.pluginAPI.preloadVideo(video, callback_complete, callback_load, callback_error)
```
### Parameters
Parameter | Type | Description
----------|------|------------
video | array | An array of video paths to load. The array can be nested (e.g., if videos are in multiple arrays to help sort by condition or task).
callback_complete | function | A function to execute when all the videos have been loaded.
callback_load | function | A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded.
callback_error | function | A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.
### Return value
Returns nothing.
### Description
This function is used to preload video files. It is used by the `preload` plugin, and could be called directly to preload video files in custom plugins or experiment code. See [Media Preloading](../overview/media-preloading.md) for more information.
It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the videos are loaded. Thus, it is possible that a video would be requested before it is done preloading. The `callback_complete` function will only execute after all the videos are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the `callback_complete` function).
The `callback_load` and `callback_error` functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.
### Examples
#### Basic use
```javascript
var videos = ['vid/file1.mp4', 'vid/file2.mp4', 'vid/file3.mp4'];
jsPsych.pluginAPI.preloadVideo(videos,
function(){ startExperiment(); },
function(file){ console.log('file loaded: ', file); }
function(file){ console.log('error loading file: ', file); }
);
function startExperiment(){
jsPsych.init({
timeline: exp
});
}
```
#### Show progress of loading
```javascript
var videos = ['vid/file1.mp4', 'vid/file2.mp4', 'vid/file3.mp4'];
var n_loaded = 0;
jsPsych.pluginAPI.preloadVideo(videos, function(){ startExperiment(); }, function(file) { updateLoadedCount(file); });
function updateLoadedCount(file){
n_loaded++;
var percentcomplete = n_loaded / videos.length * 100;
// could put something fancier here, like a progress bar
// or updating text in the DOM.
console.log('Loaded '+percentcomplete+'% of videos');
}
function startExperiment(){
jsPsych.init({
timeline: exp
});
}
```
---
## jsPsych.pluginAPI.registerPreload
```
jsPsych.pluginAPI.registerPreload(plugin_name, parameter, media_type, conditional_function)
jsPsych.pluginAPI.registerPreload(plugin_name, parameter, media_type)
```
### Parameters
@ -365,7 +464,6 @@ Parameter | Type | Description
plugin_name | string | The name of the plugin. e.g., 'image-keyboard-response'.
parameter | string | The name of the parameter that is a media file. e.g., 'stimulus'
media_type | string | The type of media, either 'image', 'audio' or 'video'.
conditional_function | function | Only run the preload for a trial if this function returns true, or if this function does not exist.
### Return value
@ -375,13 +473,12 @@ Nothing.
Use this method in a plugin file to mark a parameter as containing an element that should be preloaded. The method should be called in the plugin file such that it gets called when the file is loaded.
The `conditional_function` function is passed a single argument containing the trial object.
### Example
For an example, see the [image-keyboard-response](https://github.com/jodeleeuw/jsPsych/blob/master/plugins/jspsych-image-keyboard-response.js) and [audio-keyboard-response](https://github.com/jodeleeuw/jsPsych/blob/master/plugins/jspsych-audio-keyboard-response.js) plugins.
For an example, see the [image-keyboard-response](https://github.com/jspsych/jsPsych/blob/master/plugins/jspsych-image-keyboard-response.js) and [audio-keyboard-response](https://github.com/jspsych/jsPsych/blob/master/plugins/jspsych-audio-keyboard-response.js) plugins.
---
## jsPsych.pluginAPI.setTimeout
```

7
docs/overview/experiment-options.md
View File

@ -2,13 +2,14 @@
There are several options that can be set when calling `jsPsych.init()` to launch the experiment.
Options are specified in the object passed to `jsPsych.init`. For example, to specify a set of images to preload and the default inter-trial interval the object would contain:
Options are specified in the object passed to `jsPsych.init`. For example, to specify a default inter-trial interval, a minimum valid response time duration, and a maximum width for all of the experiment's page content, the object would contain:
```js
jsPsych.init({
timeline: [...],
preload_images: ['img1.png', 'img2.png'],
default_iti: 500
default_iti: 250,
minimum_valid_rt: 100,
experiment_width: 800
});
```

325
docs/overview/media-preloading.md
View File

@ -1,58 +1,64 @@
# Media Preloading
If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. Preloading files means that the subject's browser will download all of the files and store them in local memory on the subject's computer. This is important because loading a file is much faster if it is already in memory on the subject's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a subject's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment.
If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the [jsPsych `preload` plugin](../plugins/jspsych-preload.md). Preloading files means that the subject's browser will download the files and store them in local memory on the subject's computer. This is important because loading a file is much faster if it is already in memory on the subject's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a subject's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment.
Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The [Cross-origin requests (CORS) and safe mode](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page contains more information about this.
## Automatic Preloading
jsPsych will automatically preload audio, video, and image files that are used as parameters for the standard set of plugins.
jsPsych can automatically preload audio, video, and image files that are used as parameters for the standard set of plugins, based on the timeline that is passed to `jsPsych.init`. You must initiate this preloading using a `preload` trial. You should add this `preload` trial into your timeline when you want the preloading to occur, and set the `auto_preload` parameter to `true`.
```javascript
// the image file img/file1.png is
// automatically preloaded before the experiment begins
var trial = {
// the "auto_preload: true" setting tells the plugin to automatically find stimuli to preload based
// the main experiment timeline (used in jsPsych.init)
var preload = {
type: 'preload',
auto_preload: true
}
// this image file can be automatically preloaded
var image_trial = {
type: 'image-keyboard-response',
stimulus: 'img/file1.png'
}
// the sound file is also preloaded automatically
// the sound file is can be automatically preloaded
var sound_trial = {
type: 'audio-keyboard-response',
stimulus: 'audio/hello.mp3'
}
// the video file is preloaded automatically (as long as the experiment is running on a server)
// the video file can be automatically preloaded (as long as the experiment is running on a server)
var video_trial = {
type: 'video',
stimulus: ['video/sample_video.mp4']
}
jsPsych.init({
timeline: [trial]
timeline: [preload, image_trial, sound_trial, video_trial]
});
```
## Manual preloading
If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the audio, video, or images, or you are using timeline variables), then you can manually specify the files to preload.
You can specify an array of image files (`preload_images`) and an array of audio files (`preload_audio`) for preloading in the `jsPsych.init()` method. These files will load before the experiment starts.
If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the media files, you are using timeline variables, or you are embedding the media files in an HTML string), then these files will not be detected when you use the `auto_preload` option, so you must manually specify them. The `preload` plugin allows you to add these files using the `images`, `audio` and `video` parameters.
```javascript
// this trial will not preload the images, because the image file is being used
// in an HTML string
var trial = {
// this image file cannot be automatically preloaded because it is embedded in an HTML string
var image_trial = {
type: 'html-keyboard-response',
stimulus: '<img src="img/file1.png"></img>',
}
var audio_trial = {
// this audio file cannot be automatically preloaded because it is returned from a function
var sound_trial = {
type: 'audio-keyboard-response',
stimulus: function() { return 'audio/foo.mp3' }
stimulus: function() { return 'audio/sound1.mp3' }
}
var video_timeline = {
// these video files cannot be automatically preloaded because they are passed into a trial
// using the jsPsych.timelineVariable function
var video_trials = {
timeline: [
{
type: 'video',
@ -65,27 +71,290 @@ var video_timeline = {
]
}
// an array of paths to images that need to be loaded
// to manually preload media files, create an array of file paths for each media type
var images = ['img/file1.png'];
var audio = ['audio/foo.mp3'];
var audio = ['audio/sound1.mp3'];
var video = ['video/1.mp4', 'video/2.mp4'];
// these array can be passed into the preload plugin using the images, audio and video parameters
var preload = {
type: 'preload',
images: images,
audio: audio,
video: video
}
jsPsych.init({
timeline: [trial],
preload_audio: audio,
preload_images: images,
preload_video: video
timeline: [preload, image_trial, sound_trial, video_trials],
});
```
## Combining automatic and manual preloading
It's possible to combine automatic and manual preloading. For instance, you may want to automatically preload all of the media files based on your experiment timeline, while also manually preloading any files that can't be automatically preloaded. Any duplicate file names across all preloading methods will be removed before preloading starts, so including the same file names in multiple `preload` parameters will not affect the preloading duration.
```javascript
// this file can be preloaded automatically
var image_trial = {
type: 'image-keyboard-response',
stimulus: 'img/file1.png'
}
// this file can be preloaded automatically
var sound_trial = {
type: 'audio-keyboard-response',
stimulus: 'audio/hello.mp3'
}
// these files must be preloaded manually
var video_trials = {
timeline: [
{
type: 'video',
stimulus: jsPsych.timelineVariable('video')
}
],
timeline_variables: [
{video: ['video/1.mp4']},
{video: ['video/2.mp4']}
]
}
var video = ['video/1.mp4', 'video/2.mp4'];
var preload = {
type: 'preload',
auto_preload: true, // automatically preload the image and audio files
video: video // manually preload the videos used with timeline variables
}
jsPsych.init({
timeline: [preload, image_trial, sound_trial, video_trials],
});
```
## Preloading in batches
Some experiments use many and/or large media files. This can cause problems when participants have slow and/or unreliable internet connections, because it increases the chances of loading errors during preloading. This can also cause problems with file caching, i.e. ensuring that the preloaded files remain in the browser's memory, because loading all stimuli at once may exceed the browser's cache limits. One option for mitigating these problems is to load the media files in smaller batches throughout the experiment. Files should be preloaded as close as possible to when they will be needed. For instance, if you have several blocks of trials, then right before each block, you can preload the stimuli that's needed for that block.
Here is an example with trials where the stimuli files can be preloaded automatically. In this case, the `trials` parameter is used to tell the `preload` plugin to preload the stimuli from a specific part of the timeline.
```javascript
// these image files in these trial blocks can be automatically preloaded
var block_1 = {
timeline: [
{
type: 'image-keyboard-response',
stimulus: 'img/file1.png'
},
{
type: 'image-keyboard-response',
stimulus: 'img/file2.png'
}
]
}
var block_2 = {
timeline: [
{
type: 'image-keyboard-response',
stimulus: 'img/file3.png'
},
{
type: 'image-keyboard-response',
stimulus: 'img/file4.png'
}
]
}
var preload_1 = {
type: 'preload',
trials: block_1 // automatically preload just the images from block_1 trials
}
var preload_2 = {
type: 'preload',
trials: block_2 // automatically preload just the images from block_2 trials
}
jsPsych.init({
// add each preload trial onto the main timeline before the appropriate trial block
timeline: [preload_1, block_1, preload_2, block_2],
});
```
Below is an example with trials where the stimuli files cannot be preloaded automatically, because the stimuli files are passed to the trials via `jsPsych.timelineVariable`. In this case, we create separate arrays for each batch of files, and then pass those arrays to the each preload trial.
```javascript
// these trial blocks cannot be automatically preloaded,
// because the media files are passed to the trial parameters with timeline variables
var block_1 = {
timeline: [...],
timeline_variables: [
{stim: 'file1.png'},
{stim: 'file1.png'}
]
}
var block_2 = {
timeline: [...],
timeline_variables: [
{stim: 'file3.png'},
{stim: 'file4.png'}
]
}
var images_block_1 = ['file1.png', 'file2.png'];
var images_block_2 = ['file3.png', 'file4.png'];
// preload trial for preloading the block 1 stimuli
var preload_1 = {
type: 'preload',
images: images_block_1
}
// preload trial for preloading the block 2 stimuli
var preload_2 = {
type: 'preload',
images: images_block_2
}
jsPsych.init({
// add each preload trial to the main timeline before the appropriate trial block
timeline: [preload_1, block_1, preload_2, block_2],
});
```
## Preloading progress bar
By default, jsPsych will display a small progress bar while files are being preloaded. This progress bar represents all files that are being automatically preloaded or preloaded from the `preload_audio`, `preload_video`, and `preload_images` arrays. You may wish to turn this off if you are only loading a small number of files, as it will disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the `show_preload_progress_bar` parameter in `jsPsych.init()`
By default, the `preload` plugin will display a progress bar while files are being preloaded. This progress bar represents all files that are being preloaded during the trial, regardless of whether the file is being preloaded automatically via the `auto_preload` or `trials` parameters, or manually via the `audio`, `images`, and `video` parameters. You may wish to turn the preload progress bar off if you are only loading a small number of files, as it will appear and disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the `show_progress_bar` parameter in the `preload` trial.
```javascript
jsPsych.init({
timeline: timeline,
show_preload_progress_bar: false // hide preload progress bar
});
var preload_trial = {
type: 'preload',
auto_preload: true
show_progress_bar: false // hide progress bar
}
```
## Loading time limits
It's usually a good idea to set a time limit for file loading, to ensure that participants aren't waiting for an unreasonable amount of time. Time limits can be specified in milliseconds using the `max_load_time` parameter. If you set a loading time limit and all files haven't finished loading before this time, then the `preload` trial will either stop an error (if `continue_after_error` is false, the default) or the trial will end and the experiment will continue (if `continue_after_error` is `true`). If `max_load_time` is `null` (the default), then there is no time limit.
```javascript
var preload_trial = {
type: 'preload',
auto_preload: true
max_load_time: 60000 // 1 minute
}
```
## Loading and error messages
It's possible to specify custom messages to be shown on the page while the media files are loading, and in case of one or more file loading errors. The `message` parameter allows you to customize the loading message using an HML-formatted string. If `show_progress_bar` is `true`, then this message will be shown above the progress bar.
```javascript
var preload_trial = {
type: 'preload',
auto_preload: true
message: 'Please wait while the experiment loads. This may take a few minutes.',
}
```
A preloading error will occur when either (a) one or more files produces a loading error, and/or (b) all files have not finished loading before the `max_load_time` duration. The `error_message` parameter allows you to customize the messsage that's shown on the page in these cases. This message will only be shown if `continue_after_error` is `false` (the default).
```javascript
var preload_trial = {
type: 'preload',
auto_preload: true,
error_message: 'The experiment failed to load. Please contact the researcher.'
}
```
In addition to the `error_message` parameter, it's also possible to show more detailed error messages on the page about any files that failed to load. You can control this with the `show_detailed_errors` parameter. Detailed error messages will appear below the general error message. This only applies if `continue_after_error` is `false` (the default).
Detailed error messages can be useful when testing and debugging your experiment. If `show_detailed_errors` is `true`, then if one or more loading errors occurs before the `max_load_time` is reached, then the error page will also contian a list of the file(s) that produced an error, along with error information (if there is any). Note that this may not be a complete list, because it will only report any errors that occurred before the `max_load_time` was reached. If there are no file loading errors but preloading hasn't finished before the `max_load_time`, then detailed error message will just tell you that loading timed out.
```javascript
var preload_trial = {
type: 'preload',
auto_preload: true
show_detailed_errors: true // show details of any file loading errors and/or loading time out
}
```
## Options for handling errors
If `continue_after_error` is `true`, then the experiment _will not stop_ if one or more files fails to load. Instead, the trial will end and the experiment will continue. However, the preload trial data will contain a property called `success`, which is whether or not all files were loaded successfully, `timeout`, which is whether or not the files loaded successfully before the `max_load_time`. The preload trial data will also contain lists of any `image`, `audio`, and `video` files that failed to load. This gives you the option to continue the experiment after preloading fails and use the preload trial data decide what to do next. For instance, you may decide to skip the trials that use the stimuli files that failed to load, or try loading the failed files again. Another option is to simply end the experiment when preloading fails, but send the data back to your server so that you have more information about the loading failure.
```javascript
var preload_trial = {
type: 'preload',
auto_preload: true
message: 'Please wait while the experiment loads...',
continue_after_error: true // don't stop the experiment if there are file loading errors or if loading times out
}
var save_data = {
type: 'call-function',
async: true,
func: function(done){
var data = jsPsych.data.get().json();
save_data(data, function() {done()})
}
}
var fail_message = {
type: 'html-keyboard-response',
stimulus: 'The experiment failed to load. Please contact the researcher.',
choices: jsPsych.NO_KEYS,
trial_duration: null // the experiment will stop here, since there are no valid key choices or trial duration
}
var if_loading_fails = {
timeline: [save_data, fail_message],
conditional_function: function() {
if (jsPsych.data.getLastTrialData()[0].values().success) {
// preloading was successful, so skip this conditional timeline
// and move on with the experiment
return false;
} else {
// preloading failed, so run this conditional timeline:
// save the data to the server and show the fail message
return true;
}
}
}
// ... rest of experiment
jsPsych.init({
timeline: [preload_trial, if_loading_fails, ... ]
})
```
The `preload` plugin's `on_success` and `on_error` callback functions provide another way of tracking preloading progress and handling file loading errors. These functions are called after any file either loads successfully or produces an error, respectively. These functions receive a single argument, which is the path of the file (string) that loaded or produced an error.
```javascript
var file_load_count = 0;
var file_error_count = 0;
var preload_trial = {
type: 'preload',
auto_preload: true,
on_error: function(file) {
file_error_count++;
console.log('Error: ',file);
},
on_success: function(file) {
file_load_count++;
console.log('Loaded: ',file);
}
};
```
Note that there's no guarantee that any/all files will trigger one of these two callback functions, because they are cancelled after the `preload` trial ends. For instance, if a file takes longer to load then the `max_load_time`, then the `preload` trial will end due to timing out, and the `on_success` and `on_error` callbacks for any in-progress files will be cancelled.

4
docs/overview/running-experiments.md
View File

@ -25,7 +25,7 @@ Web browsers have a security policy called [cross-origin resource sharing (CORS)
To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTML page is running via the `file://` protocol, and if so, automatically disables the features that don't work in that context. Specifically, when a jsPsych experiment runs offline:
* **Web Audio is disabled** (even if `use_webaudio` is set to `true` in `jsPsych.init`). The WebAudio API option is used by default because it allows more precise measurement of response times relative to the onset of the audio. But because WebAudio doesn't work offline, audio will be played using HTML5 audio instead. This is equivalent to setting `use_webaudio` to `false` in `jsPsych.init`.
* **Video preloading is disabled** (both automatic preloading via plugins, and manual preloading via `preload_video` in `jsPsych.init`). Videos will still play when you run your experiment offline, but they will load _during_ the experiment, which might cause noticeable delays before video playback starts.
* **Video preloading is disabled** (both automatic and manual preloading via the `preload` plugin). Videos will still play when you run your experiment offline, but they will load _during_ the experiment, which might cause noticeable delays before video playback starts.
This safe mode feature is controlled by the `override_safe_mode` parameter in [`jsPsych.init`](../core_library/jspsych-core.md#jspsychinit), which defaults to `false`. If you leave this setting as the default, then you won't need to worry about CORS errors while running your experiment offline, or remembering to change your `jsPsych.init` settings when you move the experiment online.
@ -37,7 +37,7 @@ The `override_safe_mode` parameter also has no effect when your experiment is ru
While running your experiment offline, any media files are likely to load very quickly because they are stored on your own computer's disk. Therefore you may not notice problems with file loading delays while running your experiment locally (either offline or on a _local_ server) because the files will load fast enough that they never cause disruption. However, when your experiment is hosted on a _remote_ server, the files will need to be transferred over the internet, which means they will take longer to load - in some cases much longer. Loading delays are most noticeable with media files: images, audio, and video. As explained on the [Media Preloading](media-preloading.md) page, loading delays during your experiment can cause problems for stimulus display and response times.
It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see [here](https://developers.google.com/web/tools/chrome-devtools/network) for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the `max_load_time` parameter in [`jsPsych.init`](../core_library/jspsych-core.md#jspsychinit) so that participants with slow/unreliable internet connections will be able to take part in your experiment.
It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see [here](https://developers.google.com/web/tools/chrome-devtools/network) for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the `max_load_time` parameter in [`the preload plugin`](../plugins/jspsych-preload.md) so that participants with slow/unreliable internet connections will be able to take part in your experiment.
### Permanent data storage

2
docs/plugins/jspsych-audio-button-response.md
View File

@ -4,7 +4,7 @@ This plugin plays audio files and records responses generated with a button clic
If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.
Audio files are automatically preloaded by jsPsych. However, if you are using timeline variables or another dynamic method to specify the audio stimulus you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the audio stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
The trial can end when the subject responds, when the audio file has finished playing, or if the subject has failed to respond within a fixed length of time. You can also prevent a button response from being made before the audio has finished playing.

2
docs/plugins/jspsych-audio-keyboard-response.md
View File

@ -4,7 +4,7 @@ This plugin plays audio files and records responses generated with the keyboard.
If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.
Audio files are automatically preloaded by jsPsych. However, if you are using timeline variables or another dynamic method to specify the audio stimulus you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
The trial can end when the subject responds, when the audio file has finished playing, or if the subject has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the audio has finished playing.

2
docs/plugins/jspsych-audio-slider-response.md
View File

@ -4,7 +4,7 @@ This plugin plays an audio file and allows the subject to respond by dragging a
If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.
Audio files are automatically preloaded by jsPsych. However, if you are using timeline variables or another dynamic method to specify the audio stimulus you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
Audio files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to [manually preload](/overview/media-preloading/#manual-preloading) the audio.
The trial can end when the subject responds, or if the subject has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the audio has finished playing.

2
docs/plugins/jspsych-image-button-response.md
View File

@ -2,6 +2,8 @@
This plugin displays an image and records responses generated with a button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the subject has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting.
Image files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the images.
## Parameters
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.

1
docs/plugins/jspsych-image-keyboard-response.md
View File

@ -2,6 +2,7 @@
This plugin displays and image and records responses generated with the keyboard. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the subject has failed to respond within a fixed length of time.
Image files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the images.
## Parameters

2
docs/plugins/jspsych-image-slider-response.md
View File

@ -2,6 +2,8 @@
This plugin displays and image and allows the subject to respond by dragging a slider.
Image files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the images.
## Parameters
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.

128
docs/plugins/jspsych-preload.md Normal file
View File

@ -0,0 +1,128 @@
# jspsych-preload
This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the [Media Preloading page](/overview/media-preloading.md) for more information.
The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the `max_load_time` duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The `continue_after_error` parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful.
## Parameters
In addition to the [parameters available in all plugins](/overview/plugins.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. While there are no specific parameters that are required, the plugin expects to be given a set of files to load through one or more of the following parameters: `auto_preload` or `trials` (for automatic loading), and/or `images`, `audio`, `video` (for manual loading). To automatically load files based on a timeline of trials, either set the `auto_preload` parameter is `true` (to load files based on the main timeline passed to `jsPsych.init`) or use the `trials` parameter to load files based on a specific subset of trials. To manually load a set of files, use the `images`, `audio`, and `video` parameters. You can combine automatic and manual loading methods in a single preload trial.
All other parameters can be left unspecified if the default value is acceptable.
| Parameter | Type | Default Value | Description |
| --------------------- | -------------- | -------------------------------- | ---------------------------------------- |
| auto_preload | boolean | false | If `true`, the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to `jsPsych.init`. If `false`, any file(s) to be preloaded should be specified by passing a timeline array to the `trials` parameter and/or an array of file paths to the `images`, `audio`, and/or `video` parameters. Setting this parameter to `false` is useful when you plan to preload your files in smaller batches throughout the experiment. |
| trials | timeline array | [] | An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See [Creating an Experiment: The Timeline](../overview/timeline.md) for information on constructing timelines. |
| images | array | [] | Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. |
| audio | array | [] | Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. |
| video | array | [] | Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. |
| message | HTML string | null | HTML-formatted message to show above the progress bar while the files are loading. If `null`, then no message is shown. |
| show_progress_bar | boolean | true | If `true`, a progress bar will be shown while the files are loading. If `false`, no progress bar is shown. |
| continue_after_error | boolean | false | If `false`, then the experiment will stop during this trial if either (a) one or more of the files fails to load, and/or (b) all files do not finish loading before the `max_load_time` duration is reached. The trial will display the `error_message`, as well as the detailed error messages if `show_detailed_errors` is `true`. If `true`, the experiment will continue even if loading fails or times out, and information about loading success/failure will be stored in the trial data (see "Data Generated" below). |
| error_message | HTML string | 'The experiment failed to load.' | HTML-formatted message to be shown on the page after loading fails or times out. Only applies when `continue_after_error` is `false`. |
| show_detailed_errors | boolean | false | If `true`, and if `continue_after_error` is `false`, then a list of detailed errors will be shown below the `error_message`. This list will contain the file paths for any files that produced a loading failure, as well as a message indicating that loading timed out, if that was the case. This setting is intended to help the researcher with testing/debugging. If `false`, and if `continue_after_error` is `false`, then only the `error_message` will be shown if loading fails or times out. |
| max_load_time | numeric | null | Duration to wait, in milliseconds, for all files to load before loading times out. If one or more files has not finished loading within this time limit, then the trial will stop with an error (if `continue_after_error` is `false`), or the trial will end with information about the loading time-out in the trial data (see "Data Generated" below). If `null`, the trial will wait indefinitely for all files to either load or produce an error. |
| on_error | function | null | Function to be called immediately after a file loading request has returned an error. The function receives a single argument, which is the file path that produced the error. This callback is cancelled as soon as the trial ends. See example below. |
| on_success | function | null | Function to be called immediately after a file has successfully loaded. The function receives a single argument, which is the file path that finished loading. This callback is cancelled as soon as the trial ends. See example below. |
## Data Generated
In addition to the [default data collected by all plugins](/overview/plugins.md#data-collected-by-plugins), this plugin collects the following data for each trial.
| Name | Type | Value |
| -------------- | ------- | ---------------------------------------- |
| success | boolean | If `true`, then all files loaded successfully within the `max_load_time`. If `false`, then one or more file requests returned a failure and/or the file loading did not complete within the `max_load_time` duration. |
| timeout | boolean | If `true`, then the files did not finish loading within the `max_load_time` duration. If `false`, then the file loading did not timeout. Note that when the preload trial does not timeout (`timeout: false`), it is still possible for loading to fail (`success: false`). This happens if one or more files fails to load and all file requests trigger either a success or failure event before the `max_load_time` duration. |
| failed_images | array | One or more image file paths that produced a loading failure before the trial ended. |
| failed_audio | array | One or more audio file paths that produced a loading failure before the trial ended. |
| failed_video | array | One or more video file paths that produced a loading failure before the trial ended. |
## Examples
#### Loading files automatically based on the main timeline
```javascript
var preload = {
type: 'preload',
auto_preload: true // automatically load all files based on the main timeline
};
// define other trials to add to the timeline...
jsPsych.init({
timeline: [preload, trial1, trial2, trial3]
});
```
#### Loading files manually
```javascript
var preload = {
type: 'preload',
images: ['file1.png']
};
```
#### Combining automatic and manual methods
```javascript
// automatically load stimuli from the main timeline,
// and manually add any other stimuli files that can't be loaded automatically
var preload = {
type: 'preload',
auto_preload: true,
images: ['image1.png','image2.png']
};
// define other trials to add to the timeline...
jsPsych.init({
timeline: [preload, trial1, trial2, trial3]
});
```
#### Loading files in batches
```javascript
var block_1 = {
timeline: [...]
}
var block_2 = {
timeline: [...]
}
var preload_1 = {
type: 'preload',
trials: block_1 // automatically load block_1 stimuli
};
var preload_2 = {
type: 'preload',
trials: block_2 // automatically load block_2 stimuli
};
jsPsych.init(
// add each preload trial to the timeline before the appropriate trial block
timeline: [preload_1, block_1, preload_2, block_2]
)
```
#### Using the on_success and on_error functions
```javascript
var preload = {
type: 'preload',
audio: ['sound.mp3'],
on_success: function(file) {
console.log('File loaded: ',file);
},
on_error: function(file) {
console.log('Error loading file: ',file);
}
};
```
For more examples, see the "jspsych-preload.html" file in the jsPsych examples folder and the [Media Preloading](/overview/media-preloading.md) documentation page.

2
docs/plugins/jspsych-video-button-response.md
View File

@ -2,6 +2,8 @@
This plugin plays a video and records responses generated by button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the subject responds, when the video file has finished playing, or if the subject has failed to respond within a fixed length of time. You can also prevent a button response from being made before the video has finished playing. The button itself can be customized using HTML formatting.
Video files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on [Running Experiments](/overview/running-experiments.md) for more information.
## Parameters
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.

2
docs/plugins/jspsych-video-keyboard-response.md
View File

@ -2,6 +2,8 @@
This plugin plays a video file and records a keyboard response. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the subject responds, when the video file has finished playing, or if the subject has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the video has finished playing.
Video files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on [Running Experiments](/overview/running-experiments.md) for more information.
## Parameters
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.

2
docs/plugins/jspsych-video-slider-response.md
View File

@ -2,6 +2,8 @@
This plugin plays a video and allows the subject to respond by dragging a slider. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the subject responds, when the video file has finished playing, or if the subject has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the video has finished playing.
Video files can be automatically preloaded by jsPsych using the [`preload` plugin](jspsych-preload.md). However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to [manually preload](/overview/media-preloading/#manual-preloading) the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on [Running Experiments](/overview/running-experiments.md) for more information.
## Parameters
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.

50
docs/plugins/list-of-plugins.md Normal file
View File

@ -0,0 +1,50 @@
# List of Plugins
These are the plugins that are included in the jsPsych release. If you don't see a plugin that will work for your needs, you can post on [GitHub Discussions](https://github.com/jspsych/jsPsych/discussions) to see if anyone else in the community has an unofficial plugin to share or to get help creating a new plugin. You can also view the [documentation on creating a new plugin](/overview/plugins/#creating-a-new-plugin) or [watch a video tutorial on creating a new plugin](https://www.youtube.com/watch?v=XQcsFwAmbiw&list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh&index=4).
Plugin | Description
------ | -----------
[jspsych&#8209;animation](/plugins/jspsych-animation) | Shows a sequence of images at a specified frame rate. Records key presses (including timing information) made by the subject while they are viewing the animation.
[jspsych&#8209;audio&#8209;button&#8209;response](/plugins/jspsych-audio-button-response) | Play an audio file and allow the subject to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons.
[jspsych&#8209;audio&#8209;keyboard&#8209;response](/plugins/jspsych-audio-keyboard-response) | Play an audio file and allow the subject to respond by pressing a key.
[jspsych&#8209;audio&#8209;slider&#8209;response](/plugins/jspsych-audio-slider-response) | Play an audio file and allow the subject to respond by moving a slider to indicate a value.
[jspsych&#8209;call&#8209;function](/plugins/jspsych-call-function) | Executes an arbitrary function call. Doesn't display anything to the subject, and the subject is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data.
[jspsych&#8209;canvas&#8209;button&#8209;response](/plugins/jspsych-canvas-button-response) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images).
[jspsych&#8209;canvas&#8209;keyboard&#8209;response](/plugins/jspsych-canvas-keyboard-response) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images).
[jspsych&#8209;canvas&#8209;slider&#8209;response](/plugins/jspsych-canvas-slider-response) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and ask the subject to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images).
[jspsych&#8209;categorize&#8209;animation](/plugins/jspsych-categorize-animation) | The subject responds to an animation and can be given feedback about their response.
[jspsych&#8209;categorize&#8209;html](/plugins/jspsych-categorize-html) | The subject responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response.
[jspsych&#8209;categorize&#8209;image](/plugins/jspsych-categorize-image) | The subject responds to an image using the keyboard and can be given feedback about the correctness of their response.
[jspsych&#8209;cloze](/plugins/jspsych-cloze) | Plugin for displaying a cloze test and checking participants answers against a correct solution.
[jspsych&#8209;external&#8209;html](/plugins/jspsych-external-html) | Displays an external HTML page (such as a consent form) and lets the subject respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a subject has granted consent before starting the experiment.
[jspsych&#8209;free&#8209;sort](/plugins/jspsych-free-sort) | Displays a set of images on the screen in random locations. Subjects can click and drag the images to move them around the screen. Records all the moves made by the subject, so the sequence of moves can be recovered from the data.
[jspsych&#8209;fullscreen](/plugins/jspsych-fullscreen) | Toggles the experiment in and out of fullscreen mode.
[jspsych&#8209;html&#8209;button&#8209;response](/plugins/jspsych-html-button-response) | Display an HTML-formatted stimulus and allow the subject to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons.
[jspsych&#8209;html&#8209;keyboard&#8209;response](/plugins/jspsych-html-keyboard-response) | Display an HTML-formatted stimulus and allow the subject to respond by pressing a key.
[jspsych&#8209;html&#8209;slider&#8209;response](/plugins/jspsych-html-slider-response) | Display an HTML-formatted stimulus and allow the subject to respond by moving a slider to indicate a value.
[jspsych&#8209;iat&#8209;html](/plugins/jspsych-iat-html) | The implicit association task, using HTML-formatted stimuli.
[jspsych&#8209;iat&#8209;image](/plugins/jspsych-iat-image) | The implicit association task, using images as stimuli.
[jspsych&#8209;image&#8209;button&#8209;response](/plugins/jspsych-image-button-response) | Display an image and allow the subject to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons.
[jspsych&#8209;image&#8209;keyboard&#8209;response](/plugins/jspsych-image-keyboard-response) | Display an image and allow the subject to respond by pressing a key.
[jspsych&#8209;image&#8209;slider&#8209;response](/plugins/jspsych-image-slider-response) | Display an image and allow the subject to respond by moving a slider to indicate a value.
[jspsych&#8209;instructions](/plugins/jspsych-instructions) | For displaying instructions to the subject. Allows the subject to navigate between pages of instructions using keys or buttons.
[jspsych&#8209;maxdiff](/plugins/jspsych-maxdiff) | Displays rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns.
[jspsych&#8209;preload](/plugins/jspsych-preload) | This plugin loads images, audio, and video files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and to avoid disrupting the flow of the experiment.
[jspsych&#8209;rdk](/plugins/jspsych-rdk) | This plugin displays a Random Dot Kinematogram (RDK) and allows the subject to report the primary direction of motion by pressing a key on the keyboard.
[jspsych&#8209;reconstruction](/plugins/jspsych-reconstruction) | The subject interacts with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time.
[jspsych&#8209;resize](/plugins/jspsych-resize) | Calibrate the display so that materials display with a known physical size.
[jspsych&#8209;same&#8209;different&#8209;html](/plugins/jspsych-same-different-html) | A same-different judgment task. An HTML-formatted stimulus is shown, followed by a brief gap, and then another stimulus is shown. The subject indicates whether the stimuli are the same or different.
[jspsych&#8209;same&#8209;different&#8209;image](/plugins/jspsych-same-different-image) | A same-different judgment task. An image is shown, followed by a brief gap, and then another stimulus is shown. The subject indicates whether the stimuli are the same or different.
[jspsych&#8209;serial&#8209;reaction&#8209;time](/plugins/jspsych-serial-reaction-time) | A set of boxes are displayed on the screen and one of them changes color. The subject presses a key that corresponds to the different color box as fast as possible.
[jspsych&#8209;serial&#8209;reaction&#8209;time&#8209;mouse](/plugins/jspsych-serial-reaction-time-mouse) | A set of boxes are displayed on the screen and one of them changes color. The subjects clicks the box that changed color as fast as possible.
[jspsych&#8209;survey&#8209;html&#8209;form](/plugins/jspsych-survey-html-form) | Renders a custom HTML form. Allows for mixing multiple kinds of form input.
[jspsych&#8209;survey&#8209;likert](/plugins/jspsych-survey-likert) | Displays likert-style questions.
[jspsych&#8209;survey&#8209;multi&#8209;choice](/plugins/jspsych-survey-multi-choice) | Displays multiple choice questions with one answer allowed per question.
[jspsych&#8209;survey&#8209;multi&#8209;select](/plugins/jspsych-survey-multi-select) | Displays multiple choice questions with multiple answes allowed per question.
[jspsych&#8209;survey&#8209;text](/plugins/jspsych-survey-text) | Shows a prompt with a text box. The subject writes a response and then submits by clicking a button.
[jspsych&#8209;video&#8209;button&#8209;response](/plugins/jspsych-video-button-response) | Displays a video file with many options for customizing playback. Subject responds to the video by pressing a button.
[jspsych&#8209;video&#8209;keyboard&#8209;response](/plugins/jspsych-video-keyboard-response) | Displays a video file with many options for customizing playback. Subject responds to the video by pressing a key.
[jspsych&#8209;video&#8209;slider&#8209;response](/plugins/jspsych-video-slider-response) | Displays a video file with many options for customizing playback. Subject responds to the video by moving a slider.
[jspsych&#8209;visual&#8209;search&#8209;circle](/plugins/jspsych-visual-search-circle) | A customizable visual-search task modelled after [Wang, Cavanagh, & Green (1994)](http://dx.doi.org/10.3758/BF03206946). The subject indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point.
[jspsych&#8209;vsl&#8209;animate&#8209;occlusion](/plugins/jspsych-vsl-animate-occlusion) | A visual statistical learning paradigm based on [Fiser & Aslin (2002)](http://dx.doi.org/10.1037//0278-7393.28.3.458). A sequence of stimuli are shown in an oscillatory motion. An occluding rectangle is in the center of the display, and the stimuli change when they are behind the rectangle.
[jspsych&#8209;vsl&#8209;grid&#8209;scene](/plugins/jspsych-vsl-grid-scene) | A visual statistical learning paradigm based on [Fiser & Aslin (2001)](http://dx.doi.org/10.1111/1467-9280.00392). A scene made up of individual stimuli arranged in a grid is shown. This plugin can also generate the HTML code to render the stimuli for use in other plugins.

10
examples/demo-flanker.html
View File

@ -5,6 +5,7 @@
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-html-keyboard-response.js"></script>
<script src="../plugins/jspsych-image-keyboard-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body>
@ -90,8 +91,16 @@
}
};
// manually preload images due to presenting them with timeline variables
var images = ["img/con1.png","img/con2.png","img/inc1.png","img/inc2.png"];
var preload = {
type: 'preload',
images: images
}
/*set up experiment structure*/
var timeline = [];
timeline.push(preload);
timeline.push(welcome);
timeline.push(instructions);
timeline.push(test);
@ -100,7 +109,6 @@
/*start experiment*/
jsPsych.init({
timeline: timeline,
preload_images: ["img/con1.png","img/con2.png","img/inc1.png","img/inc2.png"],
on_finish: function() {
jsPsych.data.displayData();
}

9
examples/jspsych-categorize-animation.html
View File

@ -4,6 +4,7 @@
<head>
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-categorize-animation.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
<style>
#jspsych-categorize-animation-stimulus {
@ -15,6 +16,11 @@
<body></body>
<script>
var preload = {
type: 'preload',
auto_preload: true
}
// If render_on_canvas is false, the images will be shown via an <img> rather than <canvas> element.
// In some browsers, the first time the images are shown, the <img> method (render_on_canvas: false) will produce a brief
// blank screen (white flash) between images.
@ -32,8 +38,7 @@
};
jsPsych.init({
timeline: [trials],
preload_images: ['img/happy_face_1.jpg', 'img/sad_face_3.jpg'],
timeline: [preload, trials],
on_finish: function() {
jsPsych.data.displayData();
}

12
examples/jspsych-iat.html
View File

@ -6,12 +6,21 @@
<script src="../plugins/jspsych-iat-image.js"></script>
<script src="../plugins/jspsych-iat-html.js"></script>
<script src="../plugins/jspsych-html-keyboard-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link href="../css/jspsych.css" rel="stylesheet">
</head>
<body>
</body>
<script>
// manually preload images due to presenting them with timeline variables
var images = ['img/age/of1.jpg','img/age/of2.jpg','img/age/of3.jpg','img/age/om1.jpg','img/age/om2.jpg','img/age/om3.jpg',
'img/age/yf1.jpg','img/age/yf4.jpg','img/age/yf5.jpg','img/age/ym2.jpg','img/age/ym3.jpg','img/age/ym5.jpg'];
var preload = {
type: 'preload',
images: images
}
var welcome_block = {
type: 'html-keyboard-response',
stimulus: '<p>Welcome to the Age Task. In this study you will ' +
@ -482,6 +491,7 @@ var trial_block7 = {
};
var timeline = [];
timeline.push(preload);
timeline.push(welcome_block);
timeline.push(category_block);
timeline.push(instructions_block);
@ -502,8 +512,6 @@ var trial_block7 = {
jsPsych.init({
timeline: timeline,
preload_images: ['img/age/of1.jpg','img/age/of2.jpg','img/age/of3.jpg','img/age/om1.jpg','img/age/om2.jpg','img/age/om3.jpg',
'img/age/yf1.jpg','img/age/yf4.jpg','img/age/yf5.jpg','img/age/ym2.jpg','img/age/ym3.jpg','img/age/ym5.jpg'],
on_finish: function() {
jsPsych.data.displayData();
}

9
examples/jspsych-image-button-response.html
View File

@ -3,6 +3,7 @@
<head>
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-image-button-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
@ -10,6 +11,13 @@
var timeline = [];
// all images are used in standard trials that can be automatically preloaded (as well as being used in trials
// that use timeline variables), so we can preload all image files with the auto_preload option
timeline.push({
type: 'preload',
auto_preload: true
});
// If render_on_canvas is false, the images will be shown via an <img> rather than <canvas> element.
// In some browsers, the first time the images are shown, the <img> method (render_on_canvas: false) will produce a brief
// blank screen (white flash) between images that are presented consecutively with no post_trial_gap between them.
@ -76,7 +84,6 @@
jsPsych.init({
timeline: timeline,
preload_images: ['img/happy_face_1.jpg','img/happy_face_2.jpg','img/happy_face_3.jpg','img/happy_face_4.jpg'],
on_finish: function(){jsPsych.data.displayData();}
});

9
examples/jspsych-image-keyboard-response.html
View File

@ -3,11 +3,19 @@
<head>
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-image-keyboard-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
<script>
// all images are used in standard trials that can be automatically preloaded (as well as being used in trials
// that use timeline variables), so we can preload all image files with the auto_preload option
timeline.push({
type: 'preload',
auto_preload: true
});
// If render_on_canvas is false, the images will be shown via an <img> rather than <canvas> element.
// In some browsers, the first time the images are shown, the <img> method (render_on_canvas: false) will produce a brief
// blank screen (white flash) between images that are presented consecutively with no post_trial_gap between them.
@ -68,7 +76,6 @@
jsPsych.init({
timeline: [trial_proc, trial_1, trial_2, trial_3, trial_4],
preload_images: ['img/happy_face_1.jpg','img/happy_face_2.jpg','img/happy_face_3.jpg','img/happy_face_4.jpg'],
on_finish: function() {
jsPsych.data.displayData();
}

13
examples/jspsych-image-slider-response.html
View File

@ -3,11 +3,21 @@
<head>
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-image-slider-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
<script>
// three images are used in a standard way in image-* plugins and can therefore be automatically preloaded.
// there's one additional image ('img/happy_face_4.jpg') that is only used in timeline variables
// and will not be automatically preloaded, so this file must be preloaded manually.
var preload = {
type: 'preload',
auto_preload: true,
images: ['img/happy_face_4.jpg']
}
// If render_on_canvas is false, the images will be shown via an <img> rather than <canvas> element.
// In some browsers, the first time the images are shown, the <img> method (render_on_canvas: false) will produce a brief
// blank screen (white flash) between images that are presented consecutively with no post_trial_gap between them.
@ -64,8 +74,7 @@
}
jsPsych.init({
timeline: [trial_proc, trial_1, trial_2, trial_3],
preload_images: ['img/happy_face_1.jpg','img/happy_face_2.jpg','img/happy_face_3.jpg','img/happy_face_4.jpg'],
timeline: [preload, trial_proc, trial_1, trial_2, trial_3],
on_finish: function() {
jsPsych.data.displayData();
},

12
examples/jspsych-video-button-response.html
View File

@ -4,11 +4,20 @@
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-video-button-response.js"></script>
<script src="../plugins/jspsych-html-button-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
<script>
// preloading videos only works when the file is running on a server
// if you run this experiment by opening the file directly in the browser,
// then video preloading will be disabled to prevent CORS errors
var preload = {
type: 'preload',
auto_preload: true
}
var pre_trial = {
type: 'html-button-response',
stimulus: '<div style="max-width:600px;"><p>Some browsers now require that a user interacts with a web page before video or audio content will autoplay. Clicking the button below satisfies that requirement.</p><p>Without this trial, the video will load but not play.</p></div>',
@ -48,8 +57,7 @@
}
jsPsych.init({
show_preload_progress_bar: true,
timeline: [pre_trial, trial_1, trial_2],
timeline: [preload, pre_trial, trial_1, trial_2],
on_finish: function() { jsPsych.data.displayData(); }
});

12
examples/jspsych-video-keyboard-response.html
View File

@ -4,11 +4,20 @@
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-video-keyboard-response.js"></script>
<script src="../plugins/jspsych-html-button-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
<script>
// preloading videos only works when the file is running on a server
// if you run this experiment by opening the file directly in the browser,
// then video preloading will be disabled to prevent CORS errors
var preload = {
type: 'preload',
auto_preload: true
}
var pre_trial = {
type: 'html-button-response',
stimulus: '<div style="max-width:600px;"><p>Some browsers now require that a user interacts with a web page before video or audio content will autoplay. Clicking the button below satisfies that requirement.</p><p>Without this trial, the video will load but not play.</p></div>',
@ -44,8 +53,7 @@
}
jsPsych.init({
show_preload_progress_bar: true,
timeline: [pre_trial, trial_1, trial_2],
timeline: [preload, pre_trial, trial_1, trial_2],
on_finish: function() { jsPsych.data.displayData(); }
});

12
examples/jspsych-video-slider-response.html
View File

@ -4,11 +4,20 @@
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-video-slider-response.js"></script>
<script src="../plugins/jspsych-html-button-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
<body></body>
<script>
// preloading videos only works when the file is running on a server
// if you run this experiment by opening the file directly in the browser,
// then video preloading will be disabled to prevent CORS errors
var preload = {
type: 'preload',
auto_preload: true
}
var pre_trial = {
type: 'html-button-response',
stimulus: '<div style="max-width:600px;"><p>Some browsers now require that a user interacts with a web page before video or audio content will autoplay. Clicking the button below satisfies that requirement.</p><p>Without this trial, the video will load but not play.</p></div>',
@ -46,8 +55,7 @@
}
jsPsych.init({
show_preload_progress_bar: true,
timeline: [pre_trial, trial_1, trial_2],
timeline: [preload, pre_trial, trial_1, trial_2],
on_finish: function() { jsPsych.data.displayData(); }
});

16
examples/manual-preloading.html
View File

@ -2,6 +2,7 @@
<html>
<head>
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<script src="../plugins/jspsych-html-keyboard-response.js"></script>
<script src="../plugins/jspsych-image-keyboard-response.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
@ -10,6 +11,7 @@
<body></body>
<script>
// create the list of images that should be preloaded
var images_to_preload = [
'img/happy_face_1.jpg',
'img/happy_face_2.jpg',
@ -21,13 +23,18 @@
'img/sad_face_4.jpg'
];
var preload_trial = {
type: 'preload',
images: images_to_preload // preload the list of images
}
var pre_trial = {
type: 'html-keyboard-response',
stimulus: '<p>If you check the Network tab in your browser&rsquo;s developer tools,<br>you should see that 8 images have been loaded into memory.</p>'+
'<p>The next trial uses the image-keyboard-response plugin.<br>This plugin automatically preloads the image when an image file name is used for the stimulus parameter.</p>'+
'<p>However, in this case the stimulus parameter is a <em>function</em> that randomly selects an image to display,<br>'+
'<p>However, in this case the stimulus parameter is a <em>function</em> that randomly selects an image to display.<br>'+
'We therefore need to manually preload the images.</p>'+
'<p>The image that is selected should not load again in the Network tab when the trial starts.</p>'+
'<p>The image that is randomly selected and displayed in the next trial should not load again in the Network tab when the trial starts.</p>'+
'<p>Press any key to continue.</p>'
}
@ -42,11 +49,10 @@
}
jsPsych.init({
timeline: [pre_trial, trial],
timeline: [preload, pre_trial, trial],
on_finish: function() {
jsPsych.data.displayData();
},
preload_images: images_to_preload
}
});
</script>

13
examples/timeline-variables.html
View File

@ -5,8 +5,8 @@
<script src="../jspsych.js"></script>
<script src="../plugins/jspsych-image-keyboard-response.js"></script>
<script src="../plugins/jspsych-audio-keyboard-response.js"></script>
<script src="../plugins/jspsych-html-keyboard-response.js"></script>
<script src="../plugins/jspsych-preload.js"></script>
<link rel="stylesheet" href="../css/jspsych.css">
</head>
@ -14,6 +14,14 @@
</body>
<script>
// manually preload the image files, since they are passed to the image-keyboard-response stimulus parameter
// through timeline variables, and therefore cannot be automatically preloaded
var images = ['img/happy_face_1.jpg', 'img/happy_face_2.jpg', 'img/happy_face_3.jpg'];
var preload = {
type: 'preload',
images: images
}
var timeline_variables = [
{ v1: 'img/happy_face_1.jpg', v2: 'Ann' },
{ v1: 'img/happy_face_2.jpg', v2: 'Jackson' },
@ -44,8 +52,7 @@
}
jsPsych.init({
timeline: [node],
preload_images: ['img/happy_face_1.jpg', 'img/happy_face_2.jpg', 'img/happy_face_3.jpg'],
timeline: [preload, node],
on_finish: function() {
jsPsych.data.displayData();
},

2
mkdocs.yml
View File

@ -56,6 +56,7 @@ nav:
- 'jsPsych.turk': 'core_library/jspsych-turk.md'
- 'jsPsych.pluginAPI': 'core_library/jspsych-pluginAPI.md'
- Plugins:
- 'List of Plugins': 'plugins/list-of-plugins.md'
- 'jspsych-animation': 'plugins/jspsych-animation.md'
- 'jspsych-audio-button-response': 'plugins/jspsych-audio-button-response.md'
- 'jspsych-audio-keyboard-response': 'plugins/jspsych-audio-keyboard-response.md'
@ -81,6 +82,7 @@ nav:
- 'jspsych-image-slider-response': 'plugins/jspsych-image-slider-response.md'
- 'jspsych-instructions': 'plugins/jspsych-instructions.md'
- 'jspsych-maxdiff': 'plugins/jspsych-maxdiff.md'
- 'jspsych-preload': 'plugins/jspsych-preload.md'
- 'jspsych-rdk': 'plugins/jspsych-rdk.md'
- 'jspsych-reconstruction': 'plugins/jspsych-reconstruction.md'
- 'jspsych-resize': 'plugins/jspsych-resize.md'

3
tests/plugins/plugin-animation.test.js
View File

@ -25,8 +25,7 @@ describe('animation plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="img/face_1.jpg" id="jspsych-animation-image"></img>');

33
tests/plugins/plugin-categorize-animation.test.js
View File

@ -23,8 +23,7 @@ describe('categorize-animation plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
jest.runTimersToTime(500);
@ -43,8 +42,7 @@ describe('categorize-animation plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
jest.runTimersToTime(1500);
@ -62,8 +60,7 @@ describe('categorize-animation plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
jest.runTimersToTime(1500);
@ -83,8 +80,7 @@ describe('categorize-animation plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
jest.runTimersToTime(1500);
@ -107,8 +103,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1500);
@ -130,8 +125,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1500);
@ -153,8 +147,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1500);
@ -177,8 +170,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1000);
@ -204,8 +196,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1000);
@ -234,8 +225,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1500);
@ -259,8 +249,7 @@ describe('categorize-animation plugin', function(){
};
jsPsych.init({
timeline: [trials],
auto_preload: false
timeline: [trials]
});
jest.runTimersToTime(1500);

18
tests/plugins/plugin-free-sort.test.js
View File

@ -20,8 +20,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('src=\"img/happy_face_1.jpg\" data-src=\"img/happy_face_1.jpg\"'));
@ -39,8 +38,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('class=\"jspsych-free-sort-arena\" style=\"position: relative; width:700px; height:500px;'));
@ -55,8 +53,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<img src=\"img/happy_face_1.jpg\".+width:200px; height:200px'));
@ -70,8 +67,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<p>This is a prompt</p>'));
@ -86,8 +82,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<p>This is a prompt</p>.+<button id=\"jspsych-free-sort-done-btn\"'));
@ -102,8 +97,7 @@ describe('free-sort plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<button id=\"jspsych-free-sort-done-btn\" class=\"jspsych-btn\".+>Finito</button>'));

33
tests/plugins/plugin-iat-image.test.js
View File

@ -29,8 +29,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(/blue.png/);
@ -51,8 +50,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
utils.pressKey('j');
@ -73,8 +71,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
utils.pressKey('f');
@ -98,8 +95,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
utils.pressKey('f');
@ -123,8 +119,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
utils.pressKey('j');
@ -148,8 +143,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<p>Press j for:<br> <b>UNFRIENDLY</b>'));
@ -176,8 +170,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().querySelector('#wrongImgContainer').style.visibility).toBe('hidden');
@ -200,8 +193,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<img src=\"../media/blue.png\" id=\"jspsych-iat-stim\">'));
@ -227,8 +219,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
utils.pressKey('f');
@ -254,8 +245,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<img src="../media/blue.png" id=\"jspsych-iat-stim\">'));
@ -288,8 +278,7 @@ describe('iat-image plugin', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<img src="../media/blue.png" id=\"jspsych-iat-stim\">'));

27
tests/plugins/plugin-image-button-response.test.js
View File

@ -23,8 +23,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png"');
@ -39,8 +38,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<button class=\"jspsych-btn\">button-choice1</button>'));
@ -57,8 +55,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch(new RegExp('<button class="jspsych-custom-button">buttonChoice</button>'));
@ -73,8 +70,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-button-response-stimulus"');
@ -94,8 +90,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<button class=\"jspsych-btn\">button-choice</button></div></div><p>This is a prompt</p>');
@ -111,8 +106,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().querySelector('#jspsych-image-button-response-stimulus').style.visibility).toMatch("");
@ -130,8 +124,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-button-response-stimulus"');
@ -149,8 +142,7 @@ describe('image-button-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-button-response-stimulus"');
@ -173,8 +165,7 @@ describe('image-button-response', function(){
};
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(spy).toHaveBeenCalled();

21
tests/plugins/plugin-image-keyboard-response.test.js
View File

@ -22,8 +22,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src=\"../media/blue.png\" id=\"jspsych-image-keyboard-response-stimulus\"');
@ -40,8 +39,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-keyboard-response-stimulus"');
@ -61,8 +59,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<div id="foo">this is a prompt</div>');
@ -79,8 +76,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().querySelector('#jspsych-image-keyboard-response-stimulus').style.visibility).toMatch("");
@ -100,8 +96,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-keyboard-response-stimulus"');
@ -119,8 +114,7 @@ describe('image-keyboard-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<img src="../media/blue.png" id="jspsych-image-keyboard-response-stimulus"');
@ -144,8 +138,7 @@ describe('image-keyboard-response', function(){
};
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(spy).toHaveBeenCalled();

25
tests/plugins/plugin-image-slider-response.test.js
View File

@ -29,8 +29,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
});
@ -44,8 +43,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<span style=\"text-align: center; font-size: 80%;\">left</span>');
@ -64,8 +62,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<button id=\"jspsych-image-slider-response-next\" class=\"jspsych-btn\">button</button>');
@ -86,8 +83,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().querySelector('#jspsych-image-slider-response-response').min).toBe('2');
@ -108,8 +104,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<p>This is a prompt</p>');
@ -128,8 +123,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().querySelector('#jspsych-image-slider-response-stimulus').style.visibility).toMatch("");
@ -146,12 +140,10 @@ describe('image-slider-response', function(){
button_label: 'button',
trial_duration: 500,
render_on_canvas: false
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<div id="jspsych-image-slider-response-stimulus"><img src="../media/blue.png"');
@ -170,8 +162,7 @@ describe('image-slider-response', function(){
}
jsPsych.init({
timeline: [trial],
auto_preload: false
timeline: [trial]
});
expect(jsPsych.getDisplayElement().innerHTML).toMatch('<div id="jspsych-image-slider-response-stimulus"><img src="../media/blue.png"');

7
tests/plugins/plugin-video-button-response.test.js
View File

@ -14,22 +14,19 @@ describe('video-button-response plugin', function(){
expect(typeof window.jsPsych.plugins['video-button-response']).not.toBe('undefined');
});
test('video preloading initiates automatically', function(){
test('video preloading registers correctly', function(){
const preload_spy = jest.spyOn(jsPsych.pluginAPI, 'registerPreload');
const console_spy = jest.spyOn(console, 'warn');
require(root + 'plugins/jspsych-video-button-response.js');
var trial = {
type: 'video-button-response',
stimulus: [root + 'tests/media/sample_video.mp4'],
stimulus: ['vid.mp4'],
choices: ['y']
}
jsPsych.init({
timeline: [trial]
});
expect(preload_spy).toHaveBeenCalled();
expect(console_spy).not.toHaveBeenCalledWith('jsPsych failed to auto preload one or more files:');
preload_spy.mockRestore();
console_spy.mockRestore();
});
});

7
tests/plugins/plugin-video-keyboard-response.test.js
View File

@ -14,22 +14,19 @@ describe('video-keyboard-response plugin', function(){
expect(typeof window.jsPsych.plugins['video-keyboard-response']).not.toBe('undefined');
});
test('video preloading initiates automatically', function(){
test('video preloading registers correctly', function(){
const preload_spy = jest.spyOn(jsPsych.pluginAPI, 'registerPreload');
const console_spy = jest.spyOn(console, 'warn');
require(root + 'plugins/jspsych-video-keyboard-response.js');
var trial = {
type: 'video-keyboard-response',
stimulus: [root + 'tests/media/sample_video.mp4'],
stimulus: ['video.mp4'],
choices: jsPsych.ALL_KEYS
}
jsPsych.init({
timeline: [trial]
});
expect(preload_spy).toHaveBeenCalled();
expect(console_spy).not.toHaveBeenCalledWith('jsPsych failed to auto preload one or more files:');
preload_spy.mockRestore();
console_spy.mockRestore();
});
});

7
tests/plugins/plugin-video-slider-response.test.js
View File

@ -14,21 +14,18 @@ describe('video-slider-response plugin', function(){
expect(typeof window.jsPsych.plugins['video-slider-response']).not.toBe('undefined');
});
test('video preloading initiates automatically', function(){
test('video preloading registers correctly', function(){
const preload_spy = jest.spyOn(jsPsych.pluginAPI, 'registerPreload');
const console_spy = jest.spyOn(console, 'warn');
require(root + 'plugins/jspsych-video-slider-response.js');
var trial = {
type: 'video-slider-response',
stimulus: [root + 'tests/media/sample_video.mp4']
stimulus: ['video.mp4']
}
jsPsych.init({
timeline: [trial]
});
expect(preload_spy).toHaveBeenCalled();
expect(console_spy).not.toHaveBeenCalledWith('jsPsych failed to auto preload one or more files:');
preload_spy.mockRestore();
console_spy.mockRestore();
});
});