By default plays a beep at 440 hz (A) until a cue you set in property end occurs. Or you can use properties fileName or dataExpr to play a sound file or sound data. Then by default the element ends on its own when the file/data ends (so you don't need to set property end unless you want it to end earlier). You can set property repeat if you want to change this. Times reported by record properties startTime/endTime correspond to sound start/end.

This uses the high-precision PortAudio driver in Psychtoolbox. A system can have multiple internal sound “devices”. If you want to change which sound device to use or other parameters, you can use pb_prefs -> speaker tab. Or to change for only the current experiment, you can make an object of type speaker and set its properties. See help text for the Psychtoolbox function InitializePsychSound and generally the Psychtoolbox website and PsychPortAudio documentation for technical notes on PortAudio with different operating systems and hardware.

Mono sound plays on all channels open on the device. To set open channels, see in pb_prefs or speaker object property numChannels (default = 2).

IMPORTANT: Psychtoolbox PortAudio is designed so that parameters like device sample rate need to match the sound file/data to reduce resource usage for best timing precision. If not, the element will throw an error for a file or play distorted (sped up or slowed down) for data. Different internal sound devices can use different sample rates as well as have different default sample rates. You can change the sound device or its sample rate using in pb_prefs or with speaker object properties n_device, sampleRate. If you set a sample rate the current device cannot use, Psychtoolbox will give an error. Common rates are 44,100 and 48,000 Hz.

NOTE: If sound output is crackly on your system, try changing speaker properties priority and/or latency (try increments of 0.005 sec for latency), typically in pb_prefs.

See also element type beep.

For any trial you define in an experiment script, you can make one or more 


 objects using function 


Object and input them to addTrial.

For any trial you define in an experiment script, you can make one or more 


 objects using function 


Object and input them to addTrial.

Input properties

Adjustable properties

You can allow the subject to adjust the following input properties of an object of this type during the experiment using an adjuster element. If you need to make other properties adjustable, you can copy the element type using newPbType and edit it.





Default: play beep

You can set one of fileName or dataExpr. If you leave both at default, the element plays a beep on all channels (see property beepFrequency below).

fileName is a string that is name of sound file to play. Include path if the file is not in the MATLAB current folder or search path (or not the first file with that name on the search path). File can be any format MATLAB audioread understands (most formats).


dataExpr: Use this to get the sound from a sound data matrix in the base MATLAB workspace. The sound data matrix must have dimensions channels × samples—e.g. for mono sound a 1×n vector, for stereo sound a 2×n matrix, etc. NOTE MATLAB audioread outputs the opposite convention, so you need to transpose the variable if you use that function to produce it (use transpose or just ').

dataExpr is a string that is the expression pointing to the data. This can be just a variable name or it can include indexes, field names, etc.



Default: 440 Hz (A)

If you don't set fileName or dataExpr, this is the frequency of the beep the element plays (Hz).


Default: start at start

Time in sound to start at (sec). 0 = start.


Default: play forward

Currently only +1 = play forward, −1 = play backward.


Default: element ends on its own when sound file/data ends

<cd>true<cd>/<cd>false<cd>: play indefinitely by repeating until a cue you set in property end occurs. If <cd>false<cd>, the element ends on its own at end of sound file/data. Only for a sound file or data (the default beep always plays indefinitely).


Default: current system volume

A number between 0–1: 0 = no sound, 1 = current system volume. This scales the volume in your system sound settings. Mainly useful if you want different sound elements to play at different volumes.


Default: 0.5 sec

A sound element waits after a trial it runs in for Psychtolbox PortAudio to report sound start/end time. If you see a warning that the report was not received and recorded start/end time is approximate, you can increase maximum time to wait for the report here (sec). However, PsychBench cannot prepare or start the next trial while waiting, so set this minimally.

Alternatively, 0 = don't wait and disable the warning that report was not received. This can be useful if you are getting the warning in an experiment where timing doesn't matter.

Input properties all visual elements have


Input properties all adjuster elements have


Input properties all objects have


Record properties

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.