By default plays a beep at 440 hz (A). Or you can use property fileName or dataExpr to play a sound file or sound data. 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 add 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.

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

See also element type beep.

"Ends on its own" means ends automatically at that point. If an element can end on its own, you don't need to set end conditions for it in property end (unless you want it to maybe end earlier).

fileName
dataExpr

Defaults: play a beep until a condition you set in property end

You can set one of fileName OR dataExpr. Or if you leave both at default, the element plays a beep until a condition you set in property end—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 matrix has dimensions samples (rows) × channels (columns), matching the convention of MATLAB audioread—e.g. for mono sound an n×1 vector, for stereo sound an n×2 matrix, etc. 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.

e.g.
<cds>"soundData"<cds>
<cds>"sounds{5}"<cds>
<cds>"albums.meows(2).sound"<cds>

beepFrequency

Default: 440 Hz (A)

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

times

Default: play whole sound file/data

You can set this to a vector [t1 t2] (sec) to play only a specific time range in the sound file/data. t1 = <cd>0<cd> = start, t2 = <cd>inf<cd> = end. If you combine with maxNumLoops/breakInterval/phase below, those properties work within the part specified here.

maxNumLoops
breakInterval
phase

Default: maxNumLoops = play once
Default: breakInterval = no interval between loops
Default: phase = start at start of sound file/data

maxNumLoops is a number > 0 that is number of loops through the sound file/data or time range to play, after which the object ends. Note this number can be fractional, not just integer. <cd>inf<cd> = repeat until a condition you set in property end.

breakInterval is silent interval to add to end of the sound file/data or time range (sec). 0 = none. Generally use this if you want to have a break between loops. Note this simply adds to the length of the file/data, so for example if you set maxNumLoops = 1.5, that applies to the length including break.

phase is start time in the sound file/data or time range (sec). 0 = start. phase is best used to set a starting point for a looping stimulus. If you just want to play the file/data from a certain point to its end (or from a certain point to its start playing in reverse), use times above instead with maxNumLoops = 1.

speed

Default: play forward

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

volume

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.

reportTimeout

Default: 0.5 sec

A sound element waits after a trial it runs in for Psychtoolbox 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.

(None)