This allows to record audio from the Datapixx, optionally synchronized to
visual stimulus onset, optionally with simple but precise timestamping of
onset of audio signals.
This is an experimental proof-of-concept prototype! Its name, behaviour
and interface may change without warning in future beta-releases!
Subfunctions and their meaning
DatapixxAudioKey(‘Open’ [, sampleRate][, lrMode][, inputJack][, inputGain]);
- Open audio system for recording. This will stop any running audio
acquisition operations. Audio sampling will be performed at the given
optional ‘sampleRate’ between 8000 Hz and 96Khz with the given number of
audio input channels ‘lrMode’ (0 = Mono: Average of left and right
channel, 1 = Only left channel, 2 = Only right channel, 3 = Stereo).
Optionally select ‘inputJack’ as audio input (1=Microphone, 2=Line-In)
and ‘inputGain’ as input amplifier gain. If no ‘inputJack’ is specified
and no input is preselected, ‘inputJack’ will default to microphone
- Close audio subsystem after stopping any running acquisition operations.
[startTimeBox, startTimeGetSecs] = DatapixxAudioKey(‘CaptureNow’ [, maxDurationSecs=30][, startOffsetSecs=0][,bufferBaseAddress=20e6] [, numBufferFrames=maxScheduleFrames]);
- Start audio capture immediately (ie., with minimum possible delay on
your system), return a ‘startTimeBox’ timestamp in Datapixx clock time of
when capture actually started or will start, taking the ‘startOffsetSecs’
into account. You can also use the 2nd optional return argument
‘startTimeGetSecs’ to get the same timestamp mapped to Psychtoolbox
GetSecs() time. For a more precise mapping to GetSecs time, you can
convert the ‘startTimeBox’ timestamp into Psychtoolbox GetSecs() time
with the proper mapping functions of PsychDataPixx (see “help
The optional ‘startOffsetSecs’ allows to delay the start of the capture
operation by ‘startOffsetSecs’ seconds. The optional ‘maxDurationSecs’
allows to define an upper limit onto the duration of the audio capture
operation. The operation will stop automatically after the given number
of seconds. By default, capture will run for 30 seconds. For
robustness and efficiency, you should specify a reasonable upper limit if
possible. ‘bufferBaseAddress’ is the memory start address of the audio
buffer for capture, ‘numBufferFrames’ is the size of the buffer. See
“Datapixx SetAudioSchedule?” for more info. Leave at default settings if
DatapixxAudioKey(‘CaptureAtFlip’[, flipCount=next][, maxDurationSecs=30][, startOffsetSecs=0][,bufferBaseAddress=20e6] [, numBufferFrames=maxScheduleFrames]);
- Schedule start of audio capture synchronized to the visual stimulus
onset of a future Screen(‘Flip’) or Screen(‘AsyncFlipBegin’) command.
All parameters are identical to the ones for DatapixxAudioKey(‘CaptureNow’,…),
except for the first optional parameter ‘flipCount’. ‘flipCount’ defines
at which Screen(‘Flip’) audio capture should be started. If omitted or
set to zero or , capture will be triggered by the next flip command.
Otherwise it will be triggered by the flip command with the given
‘flipCount’. You can query the current flipCount via PsychDatapixx(‘FlipCount’).
Example: Setting flipCount = PsychDatapixx(‘FlipCount’) + 10; would start
audio capture at the 10’th invocation of a flip command from now.
This function doesn’t return a capture start timestamp as capture will
only happen in the future, so the timestamp is only available in the
[audiodata, onsetTimeSecs] = DatapixxAudioKey(‘GetResponse’[, amountSecs=current][, blocking=1][, stopCapture=0]);
- Try to fetch available captured audiodata from a running capture
operation. Only call this function after a capture operation has been
started via DatapixxAudioKey(‘CaptureNow’) or scheduled for start at a
certain flipCount via DatapixxAudioKey(‘CaptureAtFlip’) and the flip is
imminent, i.e., after the flip command for that flip has been called
already. The function will error-out if you call it too early!
The optional ‘amountSecs’ asks the driver to return exactly
‘amountSecs’ worth of audio data. By default it will return whatever
is available at time of call. If ‘amountSecs’ is specified, but the
requested amount is not yet available, the optional ‘blocking’ flag will
define behaviour: If set to 1 (default), the driver will wait until the
specified amount becomes available. If set to 0, the driver will return
with empty  return arguments so you can retry later. The optional
‘stopCapture’ flag if set to 1 will stop audio capture, its default
setting of zero will keep capture running until manually stopped or until
it stops by itself.
‘audiodata’ is the vector or matrix of captured audiodata. 1 Row for mono
recording, or a 2-row matrix (one row for each audio channel) in stereo
recording modes. Each value is an audio signal sample in range [-1 ; 1].
‘onsetTimeSecs’ is the time since start of audio capture when a certain
level of loudness (as set by DatapixxAudioKey(‘TriggerLevel’)) was first
exceeded, e.g., due to onset of a vocal response of a subject.
‘readOffset’ is the sample index of the next sample that will be read on
the next call to this function, if any.
oldLevel = DatapixxAudioKey(‘TriggerLevel’ [, newLevel]);
- Return old and optionally set new trigger threshold level for the
timestamping of onset of audio signals in DatapixxAudioKey(‘GetResponse’).
‘oldLevel’ is the current/old level. ‘newLevel’ is the optional new
level. Level can be between 0 and 1, with a default level of 0.1 for 10%
of max signal intensity as trigger level.
- Auto-Select trigger threshold level for audio onset timestamping. After
start of audio capture, there must be a period of silence, where the only
signal recorded is due to noise in the microphone/amplifiers etc, not due
to actual signal. You must provide the minimum duration of this time
period of silence as ‘silenceSecs’ parameter, e.g., 1.5 for 1.5 seconds
of guaranteed silence at start of recording. During recording, the
function will use this chunk of silence to compute an optimal trigger
level, which is 10% louder than the loudest sample in the silence block
and then use that triggerlevel as if DatapixxAudioKey(‘TriggerLevel’) had
been called with that auto-selected level.
- Stop audio capture as soon as possible.