PsychPortAudio is a new sounddriver for PTB-3. It is meant to become a
replacement for all other Matlab based sound drivers and PTB's old
SND()
function.
PsychPortAudio has subfunctions;
type
for a list overview of supported subfunctions
and
for help on a specific subfunction.
- Features
- See also
- Usage
- Caution
- Allows instant start of sound playback with a very low onset latency compared to other sound drivers (on well working hardware).
- Allows start of playback at a scheduled future system time: E.g., schedule sound onset for a specific time in the future (e.g., visual stimulus onset time), then do other things in your Matlab code. Scheduled start of playback can be accurate to the sub-millisecond level on some system setups.
- Wait for sound onset, or continue with execution of Matlab code immediately.
- Asynchronous operation: Sound playback works in the background while your Matlab code continues to do other things.
- Infinitely repeating playback, or playback of a sound for 'n' times.
- Returns timestamps and status for all crucial events.
- Support multi-channel devices, e.g., 8-channel sound cards.
- Supports multi-channel sound capture and full-duplex capture and playback of sound on some systems.
- Enumerate, open and use multiple sound cards in parallel.
- Reliable (compared to Matlabs sound facilities).
- Efficient, causes only very low cpu load.
InitializePsychSound for more info on low-latency configurations.
BasicSoundOutputDemo for a very basic demo of sound output (without special emphasis on low-latency).
BasicSoundInputDemo for a basic demo of sound capture.
BasicSoundFeedbackDemo shows how to implement a simple audio feedback loop with controllable delay.
PsychPortAudioTimingTest is a script that we used for testing PA's sound onset
latency and accuracy. It also serves as an example on how to get perfectly
synched audio-visual stimulus onsets.
The red keywords are links for per-function documentation!
% PsychPortAudio - A sound driver built around the PortAudio sound library:
% General information:
version =
PsychPortAudio('
Version'
);
oldlevel =
PsychPortAudio('
Verbosity'
[,level
]);
count =
PsychPortAudio('
GetOpenDeviceCount'
);
devices =
PsychPortAudio('
GetDevices'
[,devicetype
] [, deviceIndex
]);
% General settings:
[oldyieldInterval, oldMutexEnable, lockToCore1, audioserver_autosuspend
] =
PsychPortAudio('
EngineTunables'
[, yieldInterval
] [, MutexEnable
] [, lockToCore1
] [, audioserver_autosuspend
]);
oldRunMode =
PsychPortAudio('
RunMode', pahandle
[,runMode
]);
% Device setup and shutdown:
pahandle =
PsychPortAudio('
Open'
[, deviceid
][, mode
][, reqlatencyclass
][, freq
][, channels
][, buffersize
][, suggestedLatency
][, selectchannels
][, specialFlags=
0]);
pahandle =
PsychPortAudio('
OpenSlave', pamaster
[, mode
][, channels
][, selectchannels
]);
PsychPortAudio('
Close'
[, pahandle
]);
oldOpMode =
PsychPortAudio('
SetOpMode', pahandle
[, opModeOverride
]);
oldbias =
PsychPortAudio('
LatencyBias', pahandle
[,biasSecs
]);
[oldMasterVolume, oldChannelVolumes
] =
PsychPortAudio('
Volume', pahandle
[, masterVolume
][, channelVolumes
]);
enable =
PsychPortAudio('
DirectInputMonitoring', pahandle, enable
[, inputChannel = -
1][, outputChannel =
0][, gainLevel =
0.0][, stereoPan =
0.5]);
[underflow, nextSampleStartIndex, nextSampleETASecs
] =
PsychPortAudio('
FillBuffer', pahandle, bufferdata
[, streamingrefill=
0][, startIndex=Append
]);
bufferhandle =
PsychPortAudio('
CreateBuffer'
[, pahandle
], bufferdata
);
PsychPortAudio('
DeleteBuffer'
[, bufferhandle
] [, waitmode
]);
PsychPortAudio('
RefillBuffer', pahandle
[, bufferhandle=
0], bufferdata
[, startIndex=
0]);
PsychPortAudio('
SetLoop', pahandle
[, startSample=
0][, endSample=
max][, UnitIsSeconds=
0]);
startTime =
PsychPortAudio('
Start', pahandle
[, repetitions=
1] [, when=
0] [, waitForStart=
0] [, stopTime=
inf] [, resume=
0]);
startTime =
PsychPortAudio('
RescheduleStart', pahandle, when
[, waitForStart=
0] [, repetitions
] [, stopTime
]);
status =
PsychPortAudio('
GetStatus' pahandle
);
[audiodata absrecposition overflow cstarttime
] =
PsychPortAudio('
GetAudioData', pahandle
[, amountToAllocateSecs
][, minimumAmountToReturnSecs
][, maximumAmountToReturnSecs
][, singleType=
0]);
[startTime endPositionSecs xruns estStopTime
] =
PsychPortAudio('
Stop', pahandle
[,waitForEndOfPlayback=
0] [, blockUntilStopped=
1] [, repetitions
] [, stopTime
]);
PsychPortAudio('
UseSchedule', pahandle, enableSchedule
[, maxSize =
128]);
[success, freeslots
] =
PsychPortAudio('
AddToSchedule', pahandle
[, bufferHandle=
0][, repetitions=
1][, startSample=
0][, endSample=
max][, UnitIsSeconds=
0][, specialFlags=
0]);
You *must* call
InitializePsychSound before first invocation of
PsychPortAudio(), at least on MS-Windows, but possibly also on OS/X! If
you omit that call, initialization of the driver may fail with some
"Invalid MEX file" error from Matlab!
PsychPortAudio is built around a modified version of the free, open-source
PortAudio sound library for portable realtime sound:
http://www.portaudio.com
Psychtoolbox/PsychBasic/PsychPortAudio.m