/usr/share/psychtoolbox-3/PsychTests/PsychPortAudioDataPixxTimingTest.m is in psychtoolbox-3-common 3.0.11.20131230.dfsg1-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | function PsychPortAudioDataPixxTimingTest(waitTime, exactstart, deviceid, latbias, triggerLevel)
% PsychPortAudioDataPixxTimingTest([waitTime = 1][, exactstart=1][, deviceid=-1][, latbias=0][, triggerLevel=0.01])
%
% Test script for sound onset timing reliability and sound onset latency of
% the PsychPortAudio sound driver.
%
% This script configures the driver for low latency and high timing
% precision, then executes ten trials where it tries to emit a beep sound,
% starting in exact sync to a black-white transition on the display.
%
% You'll need measurement equipment to use this: A DataPixx device from
% VPixx technologies, connected to your computer via the USB connection
% cable. Also a connection between the line-out jack of your soundcard and
% the line-in jack of the DataPixx to transmit the sound data. The DataPixx
% will receive the audio output of PsychPortAudio/Your Soundcard, timestamp
% it and send the computed timing data to your computer via USB.
%
% Some parameters may need tweaking, especially the 'triggerLevel'
% parameter.
%
% Optional parameters:
%
% 'waitTime' = Time to wait (in seconds) before playing sound. Defaults
% to 1 second if omitted.
%
% 'exactstart' = 0 -- Start immediately, measure absolute latency.
% = 1 -- Test accuracy of scheduled sound onset. (Default)
%
% 'deviceid' = -1 -- Auto-select optimal device (Default).
% >=0 -- Select specified output device. See
% PsychPortAudio('GetDevices') for a list of devices.
%
% 'latbias' = Hardware inherent latency bias. To be determined by
% measurement - allows to PA to correct for it if provided.
% Unit is seconds. Defaults to zero.
%
% 'triggerLevel' = Sound signal amplitude for DataPixx to detect sound
% onset. Defaults to 0.01 = 1% of max amplitude if
% exactstart == 0, otherwise it is auto-detected by
% calibration. This will likely need tweaking on your
% setup.
%
nTrials = 10;
% Initialize driver, request low-latency preinit:
InitializePsychSound(1);
if ~IsLinux
PsychPortAudio('Verbosity', 10);
end
% Force GetSecs and WaitSecs into memory to avoid latency later on:
GetSecs; WaitSecs(0.1);
if nargin < 1
waitTime = [];
end
if isempty(waitTime)
waitTime = 1;
end
% If 'exactstart' wasn't provided, assume user wants to test exact sync of
% audio and video onset, instead of testing total onset latency:
if nargin < 2
exactstart = [];
end
if isempty(exactstart)
exactstart = 1;
end
if exactstart
fprintf('Will test accuracy of scheduled sound onset, i.e. how well the driver manages to\n');
fprintf('emit sound at exactly the specified "when" deadline. Sound should start in exact\n');
fprintf('sync with display black-white transition (or at least very close - < 1 msec off).\n');
fprintf('The remaining bias can be corrected by providing the bias as "latbias" parameter\n');
fprintf('to this script. Variance of sound onset between trials should be very low, much\n');
fprintf('smaller than 1 millisecond on a well working system.\n\n');
else
fprintf('Well test total latency for immediate start of sound playback, i.e., the "when"\n');
fprintf('parameter is set to zero. The difference between display black-white transition\n');
fprintf('and start of emitted sound will be the total system latency.\n\n');
end
% Default to auto-selected default output device if none specified:
if nargin < 3
deviceid = [];
end
if isempty(deviceid)
deviceid = -1;
end
if deviceid == -1
fprintf('Will use auto-selected default output device. This is the system default output\n');
fprintf('device in "normal" (=reliable but high latency) mode. In low-latency mode its the\n');
fprintf('device with the lowest inherent latency on your system (as determined by some internal\n');
fprintf('heuristic). If you are not satisfied with the results you may query the available devices\n');
fprintf('yourself via a call to devs = PsychPortAudio(''GetDevices''); and provide the device index\n');
fprintf('of a suitable device\n\n');
else
fprintf('Selected the following output device (deviceid=%i) according to your spec:\n', deviceid);
devs = PsychPortAudio('GetDevices');
for idx = 1:length(devs)
if devs(idx).DeviceIndex == deviceid
break;
end
end
disp(devs(idx));
end
% Request latency mode 2, which used to be the best one in our measurement:
% classes 3 and 4 didn't yield any improvements, sometimes they even caused
% problems.
reqlatencyclass = 2; % class 2 empirically the best, 3 & 4 == 2
% Requested output frequency, may need adaptation on some audio-hw:
freq = 44100; % Must set this. 96khz, 48khz, 44.1khz.
buffersize = 0; % Pointless to set this. Auto-selected to be optimal.
suggestedLatencySecs = [];
if IsWin
% Hack to accomodate bad Windows systems or sound cards. By default,
% the more aggressive default setting of something like 5 msecs can
% cause sound artifacts on cheaper / less pro sound cards:
suggestedLatencySecs = 0.015 %#ok<NOPRT>
fprintf('Choosing a high suggestedLatencySecs setting of 15 msecs to account for shoddy Windows operating system.\n');
fprintf('For low-latency applications, you may want to tweak this to lower values if your system works better than average timing-wise.\n');
end
% Needs to determined via measurement once for each piece of audio
% hardware:
if nargin < 4
latbias = [];
end
if isempty(latbias)
% Unknown system: Assume zero bias. User can override with measured
% values:
fprintf('No "latbias" provided. Assuming zero bias. You''ll need to determine this via measurement for best results...\n');
latbias = 0;
end
if nargin < 5
triggerLevel = [];
end
% Open audio device for low-latency output:
pahandle = PsychPortAudio('Open', deviceid, [], reqlatencyclass, freq, 2, buffersize, suggestedLatencySecs);
% Tell driver about hardwares inherent latency, determined via calibration
% once:
prelat = PsychPortAudio('LatencyBias', pahandle, latbias) %#ok<NOPRT,NASGU>
postlat = PsychPortAudio('LatencyBias', pahandle) %#ok<NOPRT,NASGU>
% Generate some beep sound 1000 Hz, 0.1 secs, 50% amplitude:
mynoise(1,:) = 0.5 * MakeBeep(1000, 0.1, freq);
mynoise(2,:) = mynoise(1,:);
% Fill buffer with data:
PsychPortAudio('FillBuffer', pahandle, mynoise);
% Perform one warmup trial, to get the sound hardware fully up and running,
% performing whatever lazy initialization only happens at real first use.
% This "useless" warmup will allow for lower latency for start of playback
% during actual use of the audio driver in the real trials:
PsychPortAudio('Start', pahandle, 1, 0, 1);
PsychPortAudio('Stop', pahandle, 1);
% Ok, now the audio hardware is fully initialized and our driver is on
% hot-standby, ready to start playback of any sound with minimal latency.
% Switch to realtime scheduling at maximum allowable Priority:
Priority(MaxPriority(0));
% Initialize audio capture subsystem of Datapixx:
% 96 KhZ sampling rate, Mono capture: Average across channels (0), Audio
% input is line-in (2), Gain is 1.0 (1):
DatapixxAudioKey('Open', 96000, 0, 2, 1);
% Check settings by printing them:
dpixstatus = Datapixx('GetMicrophoneStatus') %#ok<NOPRT,NASGU>
% Auto-Selection of triggerLevel for Datapixx timestamping requested?
if exactstart && isempty(triggerLevel)
% Use auto-trigger mode. Tell the function how long the silence
% interval at start of each trial is expected to be. This will be
% used for calibration: We set it to 75% of the duration of the pause
% between start of Datapixx recording and scheduled sound onset time:
DatapixxAudioKey('AutoTriggerLevel', waitTime * 0.75);
fprintf('Setting lead time of silence in Datapixx auto-trigger mode to %f msecs.\n', waitTime * 0.75 * 1000);
else
% Triggerlevel for DataPixx sound onset detection:
if isempty(triggerLevel)
% Default to 1%:
triggerLevel = 0.01;
end
fprintf('Using a trigger level for DataPixx of %f. This may need tweaking by you...\n', triggerLevel);
DatapixxAudioKey('TriggerLevel', triggerLevel);
end
% Wait for keypress.
fprintf('\n\nPress any key to start measurement.\n\n');
KbStrokeWait;
% nTrials measurement trials:
for i=1:nTrials
% Start audio capture on DataPixx now. Return true 'tStartBox'
% timestamp of start in box clock time:
tStartBox = DatapixxAudioKey('CaptureNow');
if exactstart
% Schedule start of audio at exactly 'waitTime' seconds ahead:
PsychPortAudio('Start', pahandle, 1, GetSecs + waitTime, 0);
else
% No test of scheduling, but of absolute latency: Start audio
% playback immediately:
PsychPortAudio('Start', pahandle, 1, 0, 0);
end
if 0
% Spin-Wait until hw reports the first sample is played...
offset = 0; %#ok<*UNRCH>
while offset == 0
status = PsychPortAudio('GetStatus', pahandle);
offset = status.PositionSecs;
plat = status.PredictedLatency;
fprintf('Predicted Latency: %6.6f msecs.\n', plat*1000);
if offset>0
break;
end
WaitSecs('YieldSecs', 0.001);
end
end
% Retrieve true delay from DataPixx measurement and stop recording on the device:
[audiodata, measuredAudioDelta] = DatapixxAudioKey('GetResponse', waitTime + 1, [], 1); %#ok<*ASGLU>
% Compute expected delay based on audio onset time as predicted/measured by
% PsychPortAudio:
status = PsychPortAudio('GetStatus', pahandle);
tPortAudio(i) = status.StartTime; %#ok<AGROW>
tDataPixx(i) = tStartBox + measuredAudioDelta; %#ok<AGROW>
fprintf('Buffersize %i, xruns = %i, playpos = %6.6f secs.\n', status.BufferSize, status.XRuns, status.PositionSecs);
if 0
figure;
plot(audiodata);
end
% Stop playback:
PsychPortAudio('Stop', pahandle, 1);
end
% Remap Datapixx clock timestamps to Psychtoolbox GetSecs() timestamps:
tDataPixx = PsychDataPixx('BoxsecsToGetsecs', tDataPixx);
% Done: Back to normal scheduling:
Priority(0);
% Close Datapixx audio subsystem:
DatapixxAudioKey('Close');
% Close PsychPortAudio:
PsychPortAudio('Close');
fprintf('\n\n');
for i =1:nTrials
audioDelta(i) = 1000 * (tDataPixx(i) - tPortAudio(i)); %#ok<AGROW>
fprintf('%i. PsychPortAudio measured onset error is %6.6f msecs.\n', i, audioDelta(i));
end
% Discard 1st trial:
audioDelta = audioDelta(2:end);
fprintf('\nAvg error %6.6f msecs, Stddev %6.6f msecs, Range %6.6f msecs.\n\n', mean(audioDelta), std(audioDelta), range(audioDelta));
% Done. Bye.
return;
|