sound

elements

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.

▸ Object ends on its own?

At default plays a beep until a condition you set in property end. Or if you use property fileName or dataExpr, by default ends on its own when the file/data ends. You can set property repeat = <cd>true<cd> if you want a sound file or data to repeat.

"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).

No—runs until any condition you set in property end.

Input properties

Adjustable properties

You can vary or allow the subject to adjust the following properties of an object of this type when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.

Adjustable properties

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars

(None)

fileName
dataExpr

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

You can set one of fileName or dataExpr. 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

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 of file/data, t2 = <cd>inf<cd> = end of file/data.

speed

Default: play forward

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

repeat
phase

Default: repeat = ends on its own when sound file/data ends
Default: phase = start at start

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

If repeat = <cd>true<cd>, you can set phase to specify a start time in the sound (sec). 0 = start. Note if you also set times above, phase is relative to times(1) and sets a start time within the specified time range.

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.

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.