Speaker device object

A speaker object is optional. You only need to make one if you want to change a property from default. Note for some properties you can also change the defaults themselves using pb_prefs, which is often more convenient.

An object of type speaker represents the high-precision PortAudio driver Psychtoolbox uses to play sound. There can only be one speaker object for an experiment. In an experiment script you can make one outside trials using function speakerObject and add it using addToExperiment. Most commonly if you need one you're using a sound element.

See help text for Psychtoolbox functions InitializePsychSound and generally the Psychtoolbox website for technical notes on PortAudio with different operating systems and hardware.

Input properties

n_device

Default: system default sound output device

A system can have multiple internal sound output “devices”. n_device is an integer setting device to use (0, 1, 2, …). <cd>[]<cd> = system default sound output device. See also record property n_device_r below.

You can use Psychtoolbox PsychPortAudio('GetDevices') to get a struct of available devices—n_device corresponds to numbers in field DeviceIndex. Devices with field NrOutputChannels > 0 are output devices. Type help InitializePsychSound for more information from Psychtoolbox.

If you need to set n_device, usually easiest is to use pb_prefs since it organizes device numbers and names in an easy menu.

numChannels

Default: 2 (stereo)

Number of channels to use. 1 = mono, 2 = stereo, etc. Generally this must be ≥ number of channels in sound files/data to play.

sampleRate

Default: device default

Sample rate for the sound device to use (Hz). Psychtoolbox PortAudio is designed so that parameters like this need to match to the sound files/data you play to reduce resource usage for best timing performance. Different internal sound devices can use different sample rates as well as have different default sample rates. You can change the sound device in n_device above, or change its sample rate in sampleRate here. 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. <cd>[]<cd> = default sample rate for the current device. See also record property sampleRate_r below.

priority
bufferSize
latency
latencyBias

Default: priority = medium
Default: bufferSize = Psychtoolbox automatic
Default: latency = Psychtoolbox automatic
Default: latencyBias = 0 sec

These properties set tradeoffs between sound timing precision (low latency) and compatibility. Usually easiest is to change these properties with pb_prefs. Note if sound output is crackly on your system, try setting latency.

priority corresponds to Psychtoolbox PsychPortAudio('Open') input reqlatencyclass setting resource usage priority. ≥ 2 also flips the latency input to InitializePsychSound. Higher values decrease latency but also compatibility. See Psychtoolbox help text for more information, but briefly:

<cd>0    <cd> – low
<cd>1    <cd> – medium
<cd>2    <cd> – high
<cd>3, 4 <cd> – highest but might not work and might actually increase latency

bufferSize goes to Psychtoolbox PsychPortAudio('Open') input buffersize. <cd>[]<cd> = Psychtoolbox automatic.

latency goes to Psychtoolbox PsychPortAudio('Open') input suggestedLatency. This is a number that is requested sound start latency (sec). Higher values increase latency but also improve compatibility. If needed, try increasing in increments of 0.005 sec. Note you can often compensate for increased latency by setting properties startBuffer/endBuffer. <cd>[]<cd> = Psychtoolbox automatic.

latencyBias: If sound output start/end is earlier or later than expected on average, you can try setting this to compensate (sec). See Psychtoolbox PsychPortAudio('LatencyBias') for more information.

Input properties all objects have

report
info

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 by listing them input property report.

n_device_r

Internal sound device number. You can set device using input property n_device above. This records the result in case you leave n_device at default <cd>[]<cd>.

sampleRate_r

Sample rate the internal sound device used. You can set a sample rate using input property sampleRate above. This records the result in case you leave sampleRate at default <cd>[]<cd>.