Specify an audio trial with keyboard response

The trial_audio_keyboard_response function is used to play an audio stimulus and collect a response using a key press.

trial_audio_keyboard_response(
  stimulus,
  choices = respond_any_key(),
  prompt = NULL,
  trial_ends_after_audio = FALSE,
  trial_duration = NULL,
  response_ends_trial = TRUE,
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

Arguments

stimulus	Path to the audio file to be played
choices	A character vector of keycodes (either numeric values or the characters themselves). Alternatively, respond_any_key() and respond_no_key() can be used
prompt	A string (may contain HTML) that will be displayed below the stimulus, intended as a reminder about the actions to take (e.g., which key to press).
trial_ends_after_audio	Does the trial end after the audio finishes playing? (default = FALSE)
trial_duration	How long to wait for a response before ending trial in milliseconds. If NULL, the trial will wait indefinitely. If no response is made before the deadline is reached, the response will be recorded as NULL.
response_ends_trial	If TRUE, then the trial will end when a response is made (or the trial_duration expires). If FALSE, the trial continues until the deadline expires.
post_trial_gap	The gap in milliseconds between the current trial and the next trial. If NULL, there will be no gap.
on_finish	A javascript callback function to execute when the trial finishes
on_load	A javascript callback function to execute when the trial begins, before any loading has occurred
data	An object containing additional data to store for the trial

Value

Functions with a trial_ prefix always return a "trial" object. A trial object is simply a list containing the input arguments, with NULL elements removed. Logical values in the input (TRUE and FALSE) are transformed to character vectors "true" and "false" and are specified to be objects of class "json", ensuring that they will be written to file as the javascript logicals, true and false.

Details

The trial_audio_keyboard_response function belongs to the "stimulus-response" family of trials, all of which display a stimulus of a particular type (image, audio, video or HTML) and collect responses using a particular mechanism (button, keyboard or slider). It plays audio files and records responses generated with a key press.

Stimulus display

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.

Response mechanism

For this kind of trial, participants can make a response by pressing a key, and the choices argument is used to control which keys will register a valid response. The default value choices = respond_any_key() is to allow the participant to press any key to register their response. Alternatively it is possible to set choices = respond_no_key(), which prevents all keys from registering a response: this can be useful if the trial is designed to run for a fixed duration, regardless of what the participant presses.

In many situations it is preferable to require the participant to respond using specific keys (e.g., for a binary choice tasks, it may be desirable to require participants to press F for one response or J for the other). This can be achieved in two ways. One possibility is to use a character vector as input (e.g., choices = c("f","j")). The other is to use the numeric code that specifies the desired key in javascript, which in this case would be choices = c(70, 74). To make it a little easier to work with numeric codes, the jaysire package includes the keycode() function to make it easier to convert from one format to the other.

Other behaviour

The trial can end when the subject responds (response_ends_trial = TRUE), when the audio file has finished playing (trial_ends_after_audio = TRUE), or if the subject has failed to respond within a fixed length of time (specified using the trial_duration argument).

Like all functions in the trial_ family it contains four additional arguments:

The post_trial_gap argument is a numeric value specifying the length of the pause between the current trial ending and the next one beginning. This parameter overrides any default values defined using the build_experiment function, and a blank screen is displayed during this gap period.
The on_load and on_finish arguments can be used to specify javascript functions that will execute before the trial begins or after it ends. The javascript code can be written manually and inserted *as* javascript by using the insert_javascript function. However, the fn_ family of functions supplies a variety of functions that may be useful in many cases.
The data argument can be used to insert custom data values into the jsPsych data storage for this trial

Data

When this function is called from R it returns the trial object that will later be inserted into the experiment when build_experiment is called. However, when the trial runs as part of the experiment it returns values that are recorded in the jsPsych data store and eventually form part of the data set for the experiment.

The data recorded by this trial is as follows:

The rt value is the response time in milliseconds taken for the user to make a response. The time is measured from when the stimulus first appears on the screen until the response.
The key_press variable is the numeric javascript key code corresponding to the response.

In addition, it records default variables that are recorded by all trials:

trial_type is a string that records the name of the plugin used to run the trial.
trial_index is a number that records the index of the current trial across the whole experiment.
time_elapsed counts the number of milliseconds since the start of the experiment when the trial ended.
internal_node_id is a string identifier for the current "node" in the timeline.