Does Audapter do what experimenters think it does? An audit of the blab-lab version

Since b2.4 (April 2026), masking noise drops out for 16 ms about once every 10 s, in about one of every five or six trials of a blab masking phase

Affects blab's current experiments on b2.4 and later.
Relevant blab studies affected. Affected, on data collected with b2.4 or later (since April 2026) only: runners that load the noise once per session, so its position runs on across trials. Public: simonSingleWord v2, v1, coAdapt, simonMultisyllable v2, attentionComp, attentionAdapt, uhdapter, vsaCentralize (its committed experiment script calls a runner that is not in the repository), vsaGeneralize, vsaSentence, the free-speech template (each link is the line that loads the noise once). Unpublished: timeAdapt, timeWrap, varMod, sponAdapt, vsaRetention, diphthongAdapt, brut, vin, and the simon and cerebellar studies. Safe as run: runners that reload the noise before every trial, which rewinds it (the MRI and iEEG interleaved runners, noGoAdapt, varModAdapt, compRetest). How audible: in fb 3 (most runners; babble at gain 0.02 under the participant's own voice) a 16 ms dropout is subtle; fb 2 studies (brut, vin, and the masking phases of simonSingleWord v2, uhdapter and vsaSentence) and fb 4 studies (vsaGeneralize, biteblockAdapt, diphthongAdapt, sponAdapt, sponAdapt2, vsaRetention) are more exposed, because the noise is all or most of what is heard.

What happens

In feedback modes 2–5 Audapter plays the loaded noise (datapb) in a loop. It loops at the end of its 480,000-sample (10 s) buffer, not at the end of the noise that was loaded, and the unused end of the buffer is silence. The bundled babble is 479,230 samples, 770 short of the buffer, so once per 10 s of running time the participant hears 16 ms of silence instead of noise. The noise position carries on from trial to trial (reset does not rewind it), so the dropout lands at a different point in each affected trial. A noise file much shorter than 10 s gives a correspondingly longer silence.

When it matters

Matters whenever masking noise is meant to be continuous, most of all in fb 2 masking phases (transfer or noise-baseline phases), where the noise is all the participant hears and a dropout briefly unmasks their own voice. In fb 3 phases the babble is quiet (fb3Gain 0.02) and a 16 ms dropout is less noticeable. Safe if the loaded noise is exactly 480,000 samples, or on versions before b2.4.

Example

The masking phase of blab's simonSingleWord v2 experiment (fb 2, fb2Gain 0.16, 1.8 s trials, AudapterIO('init') every trial, the bundled babble loaded once with get_noiseSource). Over 24 trials the current build plays 4 silences of 16 ms, in trials 6, 12, 17, 23, at 0.98 s, 0.18 s, 1.18 s, 0.38 s into the trial. With the pre-b2.4 buffer the same session plays none.

Audapter.cpppbLen               = maxPBSize;    /* audit fix I-01 */pbLen = (len > 0) ? len : maxPBSize;    /* audit fix I-01: loop at the loaded length */if (pbCounter >= maxPBSize)pbCounter -= maxPBSize;if (pbCounter >= pbLen) /* audit fix I-01: was maxPBSize */pbCounter -= pbLen;Audapter.hint pbLen;  /* audit fix I-01: length of the loaded datapb (loop point) */

How big, how often

Data: data.json from the export script.

2202pbCounter += p.downFact;2203if (pbCounter >= maxPBSize)2204    pbCounter -= maxPBSize;

1216if (ns == string("datapb")) { /* Zero out the remaining part */1217    for (int i = len; i < maxPBSize; i++)1218        *((dtype*)ptr + i) = 0.0;1219}

176static const int maxPBSize = 480000;            /* Maximum length (samples) for waveform playback */

325maxPBSize = Audapter('getMaxPBLen');326if length(mbw) > maxPBSize327    mbw = mbw(1 : maxPBSize);328end329 330Audapter(3, 'datapb', mbw, 0);

In blab's timeWrap and cerebTimeAdapt, participants hear their own voice 2.8–3.5 dBA quieter and 13 ms later from the first phase after pre onward, because the later phases switch the phase vocoder into its time-warp mode

Affects designs whose phases differ in how the phase vocoder runs: off in a baseline and in warp mode later (timeWrap, cerebTimeAdapt), on without a PCF, or with the warp section dropped on some trials.
Relevant blab studies affected. Affected: timeWrap and cerebTimeAdapt (24 kHz, frameLen 32, nDelay 3; pre phase with bPitchShift 0 and no PCF, later phases with bPitchShift 1 and a warp-row PCF; both experiment scripts call the Audapter runner for both phases). Measured at those settings the voice is played 0.0 dBA in the pre phase and -2.8 dBA afterwards on this sentence (-3.5 to -2.8 dBA across 4 voices), and 13.3 ms later. The timeAdapt family (frameLen 48) plays at -0.3 dBA with its warp rows. No blab study we know of uses the vocoder without a PCF (part C).

What happens

With bPitchShift = 1 the phase vocoder processes the voice even at 0 semitones. Without a time-warp section in the PCF, it plays the voice louder than it came in: +3.5 dBA at the default 16 kHz / frameLen 32, and +6.0 dBA at the 24 kHz / frameLen 48 settings blab uses for time warping. With a warp section loaded, even a zero-length one, the vocoder runs in its warp mode for the whole trial, at a different level: -0.3 dBA at 24 kHz / frameLen 48, -2.6 dBA at 16 kHz / frameLen 32. When a pitch shift starts, the level changes again, by an amount that depends on F0 and vowel.

When it matters

Matters when trials or phases differ in whether a warp section is loaded (a loudness cue that tells the participant which trials are perturbed), when the vocoder is on in some phases and off in others (for example a calibration at bPitchShift = 0), and for pitch-shift onsets. Safe if every trial carries a warp section (a zero-length row on control trials), as in blab's timeWrap experiment.

Example

A. timeWrap and cerebTimeAdapt. Their settings on a real sentence: in the pre phase (bPitchShift 0, no PCF) the voice is played at 0.0 dBA; in the later phases (bPitchShift 1, a PCF with a warp row, here zero-length as on a control trial) at -2.8 dBA, with a real warp at -2.8 dBA. On 4 voices the step is -3.5 to -2.8 dBA. The output also comes later: clicks sent through the same path arrive 2.7 ms after the input in the pre phase and 16.0 ms after it in the later phases, a 13.3 ms step at the phase boundary. B. Time-warp designs at timeAdapt settings (24 kHz, frameLen 48): if control trials keep a zero-length warp row, both kinds play at the spoken level (control -0.3 dBA, warp -0.2 dBA); if control trials drop the warp section, they play at +6.0 dBA, 6.2 dBA louder than the warp trials around them. C. A plausible design, not one blab runs: the vocoder on without a PCF after a baseline with it off (24 kHz, frameLen 32, nDelay 3) plays 0.0 dBA then +3.5 dBA. Clearing a warp PCF with Audapter('pcf', '', 0) leaves the vocoder in its warp mode for the rest of the MATLAB session: at the part-C settings a no-PCF trial run after warp trials plays at -2.8 dBA instead of +3.5 dBA, so the level of a later phase depends on what ran earlier in the session.

# one statermsSlopeWin = 0.030000window for the level-slope estimate n = 11 rules follow0 OST_END NaN NaN {}state 0: final state n = 0no maxIOI timeouts

11 time-warp section0.40, 0.5, 0.0, 0.0, 2.0time warp from 0.40 s: slow to ×0.5 for 0.0 s, hold 0.0 s, then ×2.0 (zero length: no audible warp) 11 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change

phase_vocoder.cpp/* audit fix PT-5: Hann analysis x Hann synthesis overlap-added at hop = L/osamp sums to 3*osamp/8, so with the2/(osamp/2) factor below the output is 1.5 x the input (+3.52 dB) for any osamp >= 4. Divide it out in pitch-shiftmode. The time-warp modes scale by 0.5 above (gain 0.75) and are left unchanged. */const dtype olaGain = (mode == PITCH_SHIFT_ONLY) ? 1.5 : 1.0;ftBuf2[2 * i] = 2 * ftBuf2[2 * i] * hWin[i] / (osamp / 2.0);ftBuf2[2 * i] = 2 * ftBuf2[2 * i] * hWin[i] / (osamp / 2.0) / olaGain;

How big, how often

Level and loudness: for PT-5 A timeWrap/cerebTimeAdapt pre vs later phase, the heard level changes by -2.8 dBA and the loudness level by -2.7 to -2.4 phon (ISO 532-1, 60–85 dB SPL): at least 1 phon at every presentation level, above the ~1 dB just-noticeable difference. Level and loudness agree here: the change is close to a pure gain.

Data: data.json from the export script.

218for (int i = 0; i < pvocFrameLen; ++i) {219    X_magn[i] = 2.0 * sqrt(ftBuf1[i * 2] * ftBuf1[i * 2] + 220                           ftBuf1[i * 2 + 1] * ftBuf1[i * 2 + 1]);

465/* Scaling */466for (int i = 0; i < pvocFrameLen; ++i)467    ftBuf2[2 * i] = 2 * ftBuf2[2 * i] * hWin[i] / (osamp / 2.0);

138params.addBoolParam("bpvocmpnorm", "Phase vocoder amplitude normalization switch");

877else if (ns == string("bpvocampnorm")) {878    ptr = (void *)&p.bPvocAmpNorm;

2152&& (nzCnt == p.pvocFrameLen)) {2153    out_over_in = ms_out / ms_in;2154    amp_ratio = sqrt(out_over_in);

With gain adaptation off, as in every blab formant experiment, a formant shift changes the heard level: on real voices, lowering F1 by 125 mel raised it by a median +2.9 dBA and raising it changed it by a median -1.4 dBA, so perturbed trials carry a level cue

Affects formant-shift experiments run with bGainAdapt 0, which is what getAudapterDefaultParams sends.
Relevant blab studies affected. Affected: every blab formant experiment, because getAudapterDefaultParams sets p.gainAdapt = 0 and AudapterIO('init') always sends it; no blab runner changes it. The level goes with the condition: attentionComp's shifted trials are louder than its noShift (catch) trials (shiftIH, F1 down, by 0.0 to 2.6 dBA; shiftAE, F1 up and F2 down, by 0.4 to 2.2 dBA, across voices); coAdapt's down-shifted word is louder than its up-shifted word; in simonSingleWord the level changes where the shift direction flips inside "bedhead". The 2-D centralization fields at strength 0.5 (the VSA studies) change the level by -1.8 to +0.7 dBA.

What happens

Audapter's formant shifter moves the two lowest resonances with a pair of filters. Moving a resonance changes how much of the voice's energy passes through, so the output level changes with the shift (in our runs, up when F1 is lowered, with exceptions such as a sustained /i/ with a very low F1; raising F1 changes it less and in either direction). Audapter has a gain-adaptation step that computes the filters' gain change and divides it out (bGainAdapt), but the MATLAB defaults switch it off. With it off, the level of every shifted trial differs from an unshifted trial of the same speech, by an amount that depends on the direction and size of the shift and on the vowel.

When it matters

Matters for designs that compare shifted and unshifted trials (compensation designs with catch trials) or opposite shifts (up vs down), because the level difference goes with the condition, and for any analysis of produced loudness after a shift. For reference, a level change of about 1 dB is noticeable in broadband sounds such as speech (Miller 1947). Natural speech has the opposite tendency (open vowels with high F1 are intrinsically louder), so the cue is also unnatural. Lowering F1 mostly boosts the strong low harmonics, to which the ear is less sensitive, so the heard change is smaller than the unweighted level suggests: on the two ARCTIC voices whose clips are below, the loudness model gives +1.3 to +2.8 phon for F1 −125 mel and -1.8 to -1.2 phon for F1 +125 mel (ISO 532-1, 60–85 dB SPL). With bGainAdapt 1 the cue does not go away but reverses: gain adaptation equalises the unweighted level, so the heard level then drops when F1 is lowered (median -1.4 dBA, -3.2 to -1.4 phon on the two ARCTIC voices) and rises when it is raised (median +2.4 dBA). Switching it on is not a simple fix.

Example

Eight real voices (four ARCTIC sentences, two PVQD speakers' sustained /a/ and /i/), each shifted and unshifted with the same settings (blab defaults, field mode, fb 1 so the voice can be measured). On the ARCTIC bdl sentence: F1 −125 mel +2.9 dBA, F1 +125 mel -0.7 dBA, F1 −20 % +1.2 dBA, F1 +20 % -0.4 dBA, 2-D centralization +0.7 dBA, re the unshifted output over the shifted span. Running the public coAdapt and attentionComp experiments with their own scripts, spoken by 8 AI-generated voices (heard level = signalOut × dScale re input), shows level differences by condition within one phase: coAdapt's down-shifted word is 0.5–5.4 dBA (median 2.9) louder than its up-shifted word, and attentionComp's shiftIH and shiftAE trials are up to 2.6 and 2.2 dBA louder than its catch trials.

How big, how often

Level and loudness: for FMT level bdl_a0005 F1 -125 mel bGainAdapt 0, the heard level changes by +2.8 dBA and the loudness level by +1.3 to +1.7 phon (ISO 532-1, 60–85 dB SPL): at least 1 phon at every presentation level, above the ~1 dB just-noticeable difference. The loudness level changes less than the A-weighted level because the change also reshapes the spectrum.

Data: data.json from the export script.

1940//SC Notice that gain adaptation is done after formant shifts1941if (p.bGainAdapt) {1942    nZC = gainAdapt(outBuf, gtot, p.frameLen, p.frameShift); // apply gain adaption between zerocrossings1943}1944nZCp = gainPerturb(outBuf, gtot, p.frameLen, p.frameShift);

2430dtype Audapter::getGain(dtype * r, dtype * ophi,dtype * sphi, int nfmts)2431{// this routine calculates the gain factor used by the routine gainAdapt to compensate the formant shift2432//SC-Mod(2008/01/05) arguments xiff0 and xiff1: for intensity correction during formant shifts2433    int i0;2434    dtype prod=1;2435    2436    for (i0 = 0; i0 < nfmts; i0++)2437        prod  *= (1-2*r[i0]*cos(sphi[i0])+pow(r[i0],2.0))/(1-2*r[i0]*cos(ophi[i0]) + pow(r[i0],2.0));2438    2439    return prod;2440}

96p.gainAdapt     =0;

29Audapter(3,'bgainadapt',p.gainAdapt, toPrompt);

An undocumented blab change that vsaSentence depends on: a field perturbation switches on again every time the formants re-enter the field (and minVowelLen has no effect)

Touches blab's current experiments: vsaSentence depends on this behaviour, and the other VSA experiments use the same restricted field. It is an undocumented behaviour change, not a defect for blab; it matters for anyone running these designs on Audapter 2.1.5 or another fork.
Relevant blab studies affected. Affected by design: vsaSentence depends on the re-arming, and vsaCentralize and vsaGeneralize use the same restricted field. The uniform whole-plane fields (attentionComp, coAdapt, uhdapter) are unaffected.

What happens

This is a question about documentation, not a defect: blab changed the rule deliberately (the "formant dropout fix", 2020), and vsaSentence's sentence design needs it, because its field excludes consonants, so with the original one-shot rule only the first vowel of each sentence would be perturbed. In perturbation-field mode, Audapter perturbs every stretch of speech whose formants fall inside the field, each time they enter it, for the whole trial. The parameter minVowelLen, which looks like it controls how long a stretch must be, has no effect and cannot even be changed.

When it matters

Affects field-mode experiments without an OST/PCF. On multi-syllable stimuli, diphthongs and glides, later syllables and returns to the target vowel are perturbed too, not only the first vowel. A brief tracker excursion out of the field does not end the perturbation. With a PCF loaded, the PCF decides per OST state and this does not apply. Across 80 real recordings this roughly doubles the perturbed frames compared with perturbing one stretch per trial.

Example

A field that raises F1 by 20 % while F1 is at least 600 Hz. On a 1 s /a/ → /i/ → /a/ glide, F1 leaves the field and comes back: Audapter shifts both /a/ stretches (0.12–0.35 s, 0.88–1.20 s), so the final /a/ is heard at 909 Hz instead of the spoken 778 Hz. A one-shot rule would shift only the first (0.12–0.35 s). On a steady /a/ with a brief F1 dip, the shift resumes after the dip.

Audapter.cpp//if (p.transCounter>=p.minVowelLen){   CWN removed for dropouts//  p.transDone=true;//}if (p.transCounter>=p.minVowelLen){ /* audit alternative F6: upstream 2.1.5 behaviour (one field entry per trial) */p.transDone=true;}p.transDone = false;    // CWN added for dropouts

How big, how often

Data: data.json from the export script.

2399if (p.bShift){2400    if (!p.transDone){2401        f2mp=f2m;2402        if (f2mp>=p.F2Min && f2mp<=p.F2Max && f1m>=p.F1Min && f1m<=p.F1Max 2403            && ((p.LBk<=0 && f1m*p.LBk+p.LBb<=f2m) || (p.LBk>0 && f1m*p.LBk+p.LBb>=f2m))){2404            btransition=true;2405            p.transCounter++;2406        }2407        else{2408            btransition=false;              2409            //if (p.transCounter>=p.minVowelLen){   CWN removed for dropouts2410            //  p.transDone=true;2411            //}2412            p.transCounter=0;2413        }           2414    }2415    else{2416        btransition=false;2417        p.transCounter=0;2418        p.transDone = false;    // CWN added for dropouts2419    }2420}

1806if (p.bShift) {1807    if (pertCfg.n == 0) {1808        /*during_trans = false;*/1809    }1810    else {1811        during_trans = (pertCfg.fmtPertAmp[stat] != 0);1812    }

152params.addIntParam("minvowellen", "Minimum vowel length (frames)");

469dtype minVowelLen;

vsaCentralize's public repository ships an unused runner whose field wiring is wrong; the runner the experiment actually calls is wired correctly

A repository-hygiene note, not an Audapter defect and not a question about the lab's data. It matters to anyone who reuses the public runner as a template for a new vowel-space experiment.
Relevant blab studies safe as run; unused public copy mis-wired. vsaCentralize is safe as run: its experiment script calls run_vsaAdapt_audapter (in blab's unpublished code, not in the public repository), which sends the mel grids after init, as vsaSentence does. The public run_vsaAdapt2_audapter.m is called by no script, and it is mis-wired.

What the design intends

Each vowel should be heard partway toward the centre of the speaker's own vowel space. The lab's calc_pertField('in', fmtMeans, 1) builds a 257 × 257 field in mel: at every F1–F2 point the shift points toward the centroid of the speaker's corner vowels and its size is the distance to it. The experiment script scales that field by shiftScaleFact, which is 0.5 in the hold phase for the adapt group, so a vowel is heard 50 % of the way to the centre.

What the unused public runner does

Audapter looks up each frame's formants on the grid in pertf1/pertf2. calc_pertField returns mel grids in p.pertF1/p.pertF2. The runner the experiment calls re-sends those. The unused public runner instead re-sends p.pertf1/p.pertf2 (lower case) right after AudapterIO('init'): the Hz grids (200–1500 and 500–3500) the experiment script stored earlier. MATLAB field names are case-sensitive; Audapter's parameter names are not, so the Hz grid silently replaces the mel grid. The formants (in mel) are then looked up at the wrong cell of the field, and each vowel receives the shift meant for a different point of the vowel space.

Example

What someone reusing the public run_vsaAdapt2_audapter.m would get. On a real sustained /i/ (PVQD speaker LA9015), at strength 0.5: the design intends F2 to fall toward the centre; with the public runner's wiring, F2 rises. Measured on the audio: spoken F1 305 Hz, F2 2292 Hz; correctly wired F1 355 Hz, F2 1926 Hz; public runner F1 345 Hz, F2 2562 Hz. On six synthetic vowels at the lab's default means, 4 of 6 (/i/, /æ/, /ɪ/, /ɛ/) move away from the centre, and every heard vowel misses the intended one by 76–250 mel. Wired correctly (the called runner, and vsaSentence), the same field moves every vowel 0.49–0.50 of the way to the centre, as designed.

How big, how often

Data: data.json from the export script.

186p.bShift2D = 1;     % flag for 2D experiments187p.pertAmp2D = pertAmp';     % convert to Audapter naming scheme w/ 2D188p.pertPhi2D = pertPhi';     % convert to Audapter naming scheme w/ 2D189p.pertF1 = pertF1;190p.pertF2 = pertF2;

113p.pertf1 = floor(p.F1Min:(p.F1Max-p.F1Min)/(fieldDim-1):p.F1Max);114p.pertf2 = floor(p.F2Min:(p.F2Max-p.F2Min)/(fieldDim-1):p.F2Max);

61AudapterIO('init', p);62Audapter(3,'pertf1',p.pertf1);63Audapter(3,'pertf2',p.pertf2);64Audapter(3,'pertAmp2D',p.pertAmp2D);65Audapter(3,'pertPhi2D',p.pertPhi2D);

120if strcmp(expt.group,'adapt')121    maxScaleFact = .5;122elseif strcmp(expt.group,'null')123    maxScaleFact = 0;124end125% shiftScaleFact is a scalar between 0 and maxScaleFact that is used to scale shiftMag matrix126expt.shiftScaleFact = [zeros(1,nBaseline) linspace(0,maxScaleFact,nRamp) maxScaleFact*ones(1,nHold) zeros(1,nWashout+nRetention)];

An open question for vsaGeneralize: as committed, the runner its experiment script calls perturbs the baseline trials by 201–490 mel and gives the training trials the full, unscaled field; the lab's logs can settle it

A question about the lab's public experiment code, not an Audapter defect. The public experiment script calls this public runner; the version that collected the data could still differ from the committed one. This is a reading of public code, not a claim about published results; the lab's public data (OSF 78z93) can settle it.
Relevant blab studies affected. vsaGeneralize: its public experiment script calls this public runner, so this is the open question. The lab's later vsaGeneralize2 study is not affected: it sends the mel grids and scales pertAmp2D.

What the design intends

"A non-uniform auditory perturbation of vowel formants that centralizes all vowels" (README). Baseline-training trials have strength 0 (no perturbation); training trials have strength 0.5, so each vowel is heard halfway to the centre of the speaker's vowel space; generalization trials are unperturbed and masked (fb 4).

What the committed code does

calc_pertField switches on the two-dimensional field (bShift2D = 1) at full strength, and AudapterIO('init') sends it. Per trial, the committed runner scales only the one-dimensional pertAmp, which is all zeros, so the two-dimensional field is never scaled: it stays at full strength on every fb 3 trial, including strength 0. The runner also re-sends the Hz grids (as in vsaCentralize), so the full-strength field is looked up in the wrong place.

Example

On a real sustained /ɑ/ (PVQD speaker LA9015) on a baseline-training trial (strength 0): the design intends no change; as committed, F2 is raised by 761 Hz. Measured on the audio: spoken F1 673 Hz, F2 1163 Hz; intended F1 673 Hz, F2 1163 Hz; as committed F1 523 Hz, F2 1923 Hz. On six synthetic vowels every one is shifted, by 201–490 mel, and the training-phase shifts are identical to the baseline ones. Confirmed by running the committed vsaGeneralize experiment script and runner end to end for a full session (466 trials, unmodified code; see "Running the lab's own code"): baseline-training trials at strength 0 are shifted like training trials in every one of eight AI-generated voices: 0.29–0.37 s per trial, median 177–236 mel in F1 and 334–424 mel in F2, heard F2 ×1.51–1.70. The lab's logs can settle whether this runner collected the data.

How big, how often

Data: data.json from the export script.

186p.bShift2D = 1;     % flag for 2D experiments187p.pertAmp2D = pertAmp';     % convert to Audapter naming scheme w/ 2D188p.pertPhi2D = pertPhi';     % convert to Audapter naming scheme w/ 2D

131p.pertf1 = floor(p.F1Min:(p.F1Max-p.F1Min)/(fieldDim-1):p.F1Max);132p.pertf2 = floor(p.F2Min:(p.F2Max-p.F2Min)/(fieldDim-1):p.F2Max);133% p.pertAmp = zeros(fieldDim,fieldDim); % define dummy pert field134p.pertAmp = zeros(1, fieldDim);135% p.pertPhi = zeros(fieldDim,fieldDim); % define dummy pert field136p.pertPhi = zeros(1, fieldDim);137expt.audapterParams = p;138 139maxScaleFact = .5;140% shiftScaleFact is a scalar between 0 and maxScaleFact that is used to scale shiftMag matrix141expt.shiftScaleFact = [zeros(1,nBaseline_generalize) zeros(1, nBaseline_train) maxScaleFact*ones(1,nTrain) zeros(1,nGeneralization)];

74Audapter(3,'pertf1',p.pertf1);75Audapter(3,'pertf2',p.pertf2);76Audapter(3,'pertAmp',p.pertAmp);77Audapter(3,'pertPhi',p.pertPhi);

116% set new perturbation117p.pertAmp = expt.shiftScaleFact(trial_index) * expt.audapterParams.pertAmp;118Audapter('setParam','pertAmp',p.pertAmp)

A dead line in the public vsaGeneralize script: p.fb4Gain = 0.98 never reaches Audapter, so the noise plays at the default level, as in every blab fb 4 study

Informational. For everyone: AudapterIO('init') silently ignores fields of p it does not know, so a misspelt or non-existent parameter has no effect and no warning; check the saved data.params for the value you meant.
Relevant blab studies safe as run. Safe as run, and already noted in the lab's own code: blab's unpublished runners (vsaGeneralize2, biteblockAdapt, trainingVarGen, sponAdapt2) carry comments that fb4Gain is not an Audapter parameter, that the real one is fb4GainDB (default 10 dB), and that none of their experiments change it. So every blab fb 4 study, vsaGeneralize included, played the noise at the same default level; only the 0.98 in the public script suggests otherwise.

What the line suggests

In the generalization phases (fb 4, speech-modulated masking noise) the script sets the noise gain to 0.98 (p.fb4Gain = 0.98), just under unity.

What the committed code does

AudapterIO('init') forwards only p.fb4GainDB, in decibels; a field called fb4Gain is ignored without a warning. Audapter therefore uses its default of 10 dB, not the −0.18 dB that 0.98 corresponds to.

Example

A real sentence (CMU ARCTIC bdl "Will we ever forget it.") in fb 4 with the bundled babble. Measured on the audio: at the gain the line suggests (0.98) the output would be -42.4 dBFS (A-weighted); at the default level that actually plays, -32.2 dBFS (10.2 dBA louder).

How big, how often

Level and loudness: for 0.98 (intended) vs default, the heard level changes by +10.2 dBA and the loudness level by +8.9 to +9.6 phon (ISO 532-1, 60–85 dB SPL): at least 1 phon at every presentation level, above the ~1 dB just-noticeable difference. The loudness level changes less than the A-weighted level because the change also reshapes the spectrum.

Data: data.json from the export script.

62w = get_noiseSource(p);63Audapter('setParam', 'datapb', w, 1);64if strcmp(conds2run{1},'baselineGeneralize') || strcmp(conds2run{1},'generalization')65    p.fb = 4;66    p.fb4Gain = 0.98;

163if (isfield(p, 'fb4GainDB'))164    Audapter(3, 'fb4gaindb', p.fb4GainDB, toPrompt);165end

With some OST rule combinations, the "speech has ended" rule fires later on every trial, so a perturbation meant to stop at the end of a word runs on into the next word

Not triggered by any blab design we inspected: in all 69 blab OST files, public and unpublished, every INTENSITY_FALL has a rule that refreshes the stored time earlier in the same trial. Affects any design in which the only rules before an INTENSITY_FALL are ELAPSED_TIME, blab's RMS-floor onset rule (INTENSITY_RATIO_ABOVE_THRESH_WITH_RMS_FLOOR) or a ratio rule.
Relevant blab studies safe as run. Safe as run: no blab OST, public or unpublished, has an INTENSITY_FALL preceded only by ELAPSED_TIME, the RMS-floor rule or a ratio rule (timeWrap uses the RMS-floor rule for onset, followed by a rise-and-hold rule).

What happens

An OST remembers the frame at which a level-based rule last ended (lastStatEnd). INTENSITY_FALL, the usual "speech has ended" rule, may only fire once more than its minimum time has passed since that frame. Audapter('reset') does not clear the stored frame, and neither does reloading the OST or AudapterIO('init'). Rules that record their own end (the rise-and-hold, slope and stretch rules, and INTENSITY_FALL itself) overwrite it in every trial, so a FALL after them works. ELAPSED_TIME and the RMS-floor rule never write it, and the ratio rules write it only in a state that a normally numbered rule never reaches. A FALL right after one of those rules therefore waits for a frame from an earlier trial: the detected offset can never come earlier than the previous trial's offset plus the minimum time. It creeps later on every trial, and jumps after any long trial. The perturbation that should stop at the offset stays on.

When it matters

Matters when a perturbation (or the next state) is timed from a detected offset, no rule before the FALL in the trial refreshes the stored time, and the same Audapter session runs more than one trial. It does not matter whether the earlier trials were perturbed: only how long their speech lasted. The first trial after MATLAB starts is always correct, so a single-trial pilot will not show it. Safe if any INTENSITY_RISE_HOLD, INTENSITY_RISE_HOLD_POS_SLOPE, slope, stretch, FALL or INTENSITY_AND_RATIO rule runs before the FALL in the same trial (as in blab's measureFormants, bedhead, seven/sever and pedigree OSTs), or if no rule is timed from an offset.

Example

A "shift the first word" design with catch trials: two-word trials, F1 raised 125 mel from the detected onset of word 1 to its detected offset, one catch trial in four, same OST all session and the PCF reloaded before every trial, with blab's standard settings. Onset is detected with blab's RMS-floor rule. The words are a real voice (a sustained /ɑ/ then /i/ of PVQD speaker SJ7001, cut to each trial's length). Trials 1 and 2 are correct. Trial 3 is a catch trial with a long first word (1.20 s); after it, trial 4's offset is found only at 1.45 s instead of 0.53 s, so word 2 (/i/) is heard with F1 raised (+80 % instead of +1 %; F1 253 → 454 Hz). After the second long catch trial the offset is never detected again (trials 7 and 8). The same session on synthetic vowels gives the same timings within 22 ms.

rmsSlopeWin = 0.030000window for the level-slope estimate n = 33 rules follow0 INTENSITY_RATIO_ABOVE_THRESH_WITH_RMS_FLOOR 0.2 0.02 {}state 0 → 2: high-frequency energy ratio above 0.2 (ignored below level 0.0003) for 0.02 s; does not record its end time2 INTENSITY_FALL 0.01 0.02 {}state 2 → 3: level below 0.01 for 10 ms, once more than 0.02 s have passed since the last recorded state end3 OST_END NaN NaN {}state 3: final state n = 0no maxIOI timeouts

rmsSlopeWin = 0.030000window for the level-slope estimate n = 33 rules follow0 INTENSITY_RISE_HOLD_POS_SLOPE 0.01 0.05 {}state 0 → 2: level rises above 0.01 and keeps rising for 0.05 s2 INTENSITY_FALL 0.01 0.02 {}state 2 → 3: level below 0.01 for 10 ms, once more than 0.02 s have passed since the last recorded state end3 OST_END NaN NaN {}state 3: final state n = 0no maxIOI timeouts

00 time-warp sections 44 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change1, 0.0, 0, 0, 0state 1: no change2, 0.0, 0, 125, 0state 2: formant shift 125 mel, F1 up3, 0.0, 0, 0, 0state 3: no change

00 time-warp sections 44 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change1, 0.0, 0, 0, 0state 1: no change2, 0.0, 0, 0, 0state 2: no change3, 0.0, 0, 0, 0state 3: no change

Audapter.cppostTab.reset(); /* audit fix OST-F1: OST_TAB::reset() was never called */ost.cpplastStatEnd = 0;    /* audit fix OST-F1: was never initialised */stretchSpanAccum = 0.0;/* audit fix OST-F1: state onset frames must not carry over from the previous trial */if (statOnsetIndices)memset(statOnsetIndices, 0, n * 4 * sizeof(int));   /* 4 = maxStatesPerLine in readFromFile */

How big, how often

Data: data.json from the export script.

97void OST_TAB::reset() {98    stretchCnt = 0;99    lastStatEnd = 0;100    stretchSpanAccum = 0.0;101}

648dataFileCnt = 0;649 650//SC(2012/10/19): OST online sentence tracking651stat = 0;652 

546if ((bIsGOET == 0) && ((data_counter - lastStatEnd) > minDurN)) {547    stat_out = stat + 1;548    statOnsetIndices[stat_out] = frame_counter;549    lastStatEnd = data_counter;550}

641else if (t_mode == INTENSITY_RATIO_ABOVE_THRESH_WITH_RMS_FLOOR) { // (+2) RMS ratio above threshold, with minimum RMS throughout. prm1: rms_ratio threshold; prm2: minDurN642    if (stat == t_stat0) {643        // If RMS intensity isn't above 0.0003, ignore the ratio as it's too noisy at low intensities644        if ((1. / rms_ratio > prm1[k]) && (rms_s >= 0.0003)) {645            stat_out = stat + 1;646            statOnsetIndices[stat_out] = frame_counter;647            stretchCnt = 0;648        }649    }650    else if (stat - t_stat0 == 1) {651        minDurN = (int)floor(prm2[k] / frameDur);652 653        if ((1. / rms_ratio > prm1[k]) && (rms_s >= 0.0003)) {654            stretchCnt++;655            if (stretchCnt > minDurN) {656                stat_out = stat + 1;657                statOnsetIndices[stat_out] = frame_counter;658            }659        }660        else {661            stat_out = stat - 1;662        }663    }664 665}

A PCF loaded earlier in the session stays loaded through AudapterIO('init') and overrides a later field-mode experiment: shift trials are not shifted, or no-shift trials are

blab's runners are protected: every blab field-mode runner we inspected clears the OST and PCF before AudapterIO('init'). Affects any runner that leaves out those two lines, for example a copy of a runner or a new experiment run in the same MATLAB session after an OST/PCF block.
Relevant blab studies safe as run. Safe as run: every blab field-mode runner clears the OST and PCF before AudapterIO('init').

What happens

An OST or PCF stays loaded until Audapter('ost', '', 0) and Audapter('pcf', '', 0) clear it. Audapter('reset') and AudapterIO('init', p) do not. While a PCF is loaded, it decides every formant shift, and the perturbation field set with pertAmp/pertPhi is ignored. Every blab formant session starts with the measureFormants calibration block, which loads an OST and an all-zero PCF, so a field-mode experiment that follows it without clearing them delivers no shift at all.

When it matters

Matters when a field-mode block follows any block that loaded an OST/PCF in the same MATLAB session. With the calibration's all-zero PCF, the whole experiment is silently unperturbed; after a block with a nonzero PCF (for example a bedhead hold block), "noShift" trials are perturbed at that block's strength. Safe if the runner calls Audapter('ost', '', 0); Audapter('pcf', '', 0); before AudapterIO('init', p), as blab's attentionComp, coAdapt, uhdapter, VSA and template runners do. These two lines are load-bearing.

Example

The measureFormants calibration (two trials), then an attentionComp-style field experiment: 125 mel F1 shift set per trial with pertAmp/pertPhi, noShift trials interleaved, fb 3 with the bundled babble, a real sentence on every trial (CMU ARCTIC clb "I had faith in them."). With the clear lines, trial 3 is heard with F1 raised (+23 %). Without them, trial 3 is heard unchanged (-1 %) and the log shows no shifted frame (0.000 s instead of 1.174 s). A synthetic vowel gives the same result (+20 % vs +1 %).

# Online status tracking (OST) configuration filermsSlopeWin = 0.050000window for the level-slope estimate # Main section: Heuristic rules for trackingn = 33 rules follow0 INTENSITY_RISE_HOLD_POS_SLOPE 0.01 0.05 {} # Detect the onset the vowelstate 0 → 2: level rises above 0.01 and keeps rising for 0.05 s2 INTENSITY_FALL   0.03 0.01 {} # Detect the offset of the vowelstate 2 → 3: level below 0.03 for 10 ms, once more than 0.01 s have passed since the last recorded state end4 OST_END NaN NaN {} state 4: final state n = 0no maxIOI timeouts

# Section 1 (Time warping): (ostStat_initial), tBegin, rate1, dur1, durHold, rate2 00 time-warp sections # Section 2: stat pitchShift(st) gainShift(dB) fmtPertAmp fmtPertPhi(rad)55 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change1, 0.0, 0, 0, 0state 1: no change2, 0.0, 0, 0, 0state 2: no change3, 0.0, 0, 0, 0state 3: no change4, 0.0, 0, 0, 0state 4: no change

How big, how often

Data: data.json from the export script.

1806if (p.bShift) {1807    if (pertCfg.n == 0) {1808        /*during_trans = false;*/1809    }1810    else {1811        during_trans = (pertCfg.fmtPertAmp[stat] != 0);1812    }

1838/* That using ost and pcf files overrides the perturbation field 1839    specified with pertF2, pertAmp, pertPhi. */1840if (pertCfg.n > 0) {1841    mamp = pertCfg.fmtPertAmp[stat];        1842    mphi = pertCfg.fmtPertPhi[stat];1843}

427case 'pcf'428    if nargin == 2429        Audapter(9, params);430    elseif nargin == 4431        Audapter(9, params, varargin{1});432    else433        error('%s: Invalid syntax under mode: %s', mfilename, action);434    end

Pitch catch trials made by clearing the PCF can be heard at the full pitch shift, when the trial before ended while shifted

Not triggered by any blab design we inspected: blab's pitch experiments (pitchAdaptPD, pitchComp) re-run AudapterIO('init', p) before every trial, which restores the pitch setting. Affects pitch designs that make catch trials with Audapter('pcf', '', 0) and do not re-run init.
Relevant blab studies safe as run. Safe as run: blab's pitch experiments (pitchAdaptPD, pitchComp) re-run AudapterIO('init', p) before every trial.

What happens

While a PCF is loaded, Audapter writes the PCF's pitch shift for the current OST state into the user parameter pitchShiftRatio on every frame. Clearing the PCF with Audapter('pcf', '', 0) leaves the last value there, and with no PCF the phase vocoder uses pitchShiftRatio for the whole trial. If the previous trial ended in a shifted state (the participant was still voicing when the trial stopped), every following "unperturbed" trial is shifted by the full amount, and data.params.pitchShiftRatio logs the shifted value.

When it matters

Matters for pitch-perturbation designs with interleaved catch or control trials made by clearing the PCF, when a perturbed trial can end before the OST returns to an unshifted state: sustained-vowel designs, or trials cut off mid-word. If the perturbed trial ends after the shift is switched off, the catch trial is clean. Safe if catch trials load an all-zero PCF, or AudapterIO('init', p) runs before every trial (it re-sends pitchShiftRatio), or the script sets pitchShiftRatio after clearing the PCF.

Example

A sustained-vowel pitch design: +2 semitones from the detected voice onset until the level falls, phase vocoder, catch trials interleaved, on a real sustained /a/ (PVQD speaker SJ7001). The speaker is still voicing when each perturbed trial stops. With catch trials made by loading an all-zero PCF, catch trial 2 is heard at 0 cents. Made with Audapter('pcf', '', 0), it is heard at +198 cents, the whole perturbation, and data.params.pitchShiftRatio logs 1.1225. A synthetic vowel gives the same (0 cents vs +200 cents).

rmsSlopeWin = 0.030000window for the level-slope estimate n = 33 rules follow0 INTENSITY_RISE_HOLD 0.02 0.02 {}state 0 → 2: level rises above 0.02 (next state) and stays above it for 0.02 s2 INTENSITY_FALL 0.01 0.02 {}state 2 → 3: level below 0.01 for 10 ms, once more than 0.02 s have passed since the last recorded state end3 OST_END NaN NaN {}state 3: final state n = 0no maxIOI timeouts

00 time-warp sections 44 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change1, 0.0, 0, 0, 0state 1: no change2, 2.0, 0, 0, 0state 2: pitch +2 st3, 0.0, 0, 0, 0state 3: no change

00 time-warp sections 44 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0.0, 0, 0, 0state 0: no change1, 0.0, 0, 0, 0state 1: no change2, 0.0, 0, 0, 0state 2: no change3, 0.0, 0, 0, 0state 3: no change

How big, how often

Data: data.json from the export script.

1970if (pertCfg.n > 0) {1971    if (stat < pertCfg.n) {1972        p.pitchShiftRatio[0] = pow(2.0, pertCfg.pitchShift[stat] / 12.0);1973        intShiftRatio = pow(10, pertCfg.intShift[stat] / 20.0);1974    }

After an OST maxIOI timeout, the next ELAPSED_TIME lasts one frame, and without reloading the OST the timeout fires 0.2 s later in every trial

Not triggered: no blab OST we inspected has a maxIOI (timeout) section. Affects OSTs with a timeout that are loaded once for many trials.
Relevant blab studies n.a.. Not applicable: no blab OST we inspected has a maxIOI section.

What happens

When a maxIOI rule moves the OST to a later state, Audapter records the time of that jump against the wrong state. An ELAPSED_TIME rule in the new state then fires on the next frame instead of after its duration. The wrong record also shifts the reference that later timeouts are measured from, so if the OST is not reloaded between trials, each trial's timeout fires later than the one before.

When it matters

Affects OST files with a maxIOI section, on trials where the timeout actually fires, typically quiet or unusual productions where onset detection fails. The one-frame ELAPSED_TIME happens on every such trial. The growing delay happens only when the OST is loaded once and several trials run with reset() between them; reloading the OST before each trial removes the delay but not the one-frame ELAPSED_TIME.

Example

A soft talker: a real sustained /a/ (PVQD speaker SJ7001) that never reaches the onset threshold, so the 0.2 s timeout must start the sequence, and F1 is raised 30 % from 0.1 s after the timeout. Intended: the shift starts at 0.30 s in every trial. With the OST loaded once and reset() between trials, it starts at 0.20, 0.41 and 0.61 s in trials 1–3: the ELAPSED_TIME state lasts one frame instead of 0.1 s, and every trial's timeout comes 0.2 s later than the last.

rmsSlopeWin = 0.030000window for the level-slope estimate n = 33 rules follow0 INTENSITY_RISE_HOLD 0.02 0.02 {}state 0 → 2: level rises above 0.02 (next state) and stays above it for 0.02 s2 ELAPSED_TIME 0.1 NaN {}state 2 → 3: moves on 0.1 s after this state began; does not record its end time3 OST_END NaN NaN {}state 3: final state n = 11 maxIOI (timeout) entries0 0.2 2

00 time-warp sections 44 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0, 0, 0, 0state 0: no change1, 0, 0, 0, 0state 1: no change2, 0, 0, 0, 0state 2: no change3, 0, 0, 0.3, 0state 3: formants ×1.3 (F1)

ost.cppstatOnsetIndices[stat] = frame_counter;statOnsetIndices[j] = frame_counter;    /* audit fix OST-F2: was [stat] */

How big, how often

Data: data.json from the export script.

723if (maxIOICfg.n > 0) {724    for (i = 0; i < maxIOICfg.n; i++) {725        if ((stat >= maxIOICfg.stat0[i]) && (stat < maxIOICfg.stat1[i])) {726            if ((frame_counter - statOnsetIndices[maxIOICfg.stat0[i]]) * frameDur > maxIOICfg.maxInterval[i]) {727                for (j = stat + 1; j <= maxIOICfg.stat1[i]; j++) {728                    statOnsetIndices[stat] = frame_counter;729                }730 731                stat_out = maxIOICfg.stat1[i];732                733            }

371if (t_mode == ELAPSED_TIME) { // (+1) Elapsed time from previous state. prm1: duration (s)372    if ((data_counter - statOnsetIndices[stat]) * frameDur > prm1[k]) {373        stat_out = stat + 1;374        statOnsetIndices[stat_out] = frame_counter;375    }

256if ((statOnsetIndices = (int *) calloc(n * maxStatesPerLine, sizeof(int))) == NULL) {

An ELAPSED_TIME rule numbered as if it advanced two states runs twice, so a 100–200 ms post-onset delay becomes 200–400 ms and the shift misses a short vowel; Audapter does not check the numbering

Affects OST files where a one-state rule (ELAPSED_TIME, INTENSITY_FALL) is followed by a rule numbered two states later, an easy slip because most level rules do span two states.
Relevant blab studies n.a.. Not applicable as far as we know: blab's OST files number their rules correctly, apart from free-speech's measureFormants.ost, whose doubled INTENSITY_FALL is harmless there (EXP-2).

What happens

Each OST rule owns the states from its own number up to the next rule's number. Level rules such as INTENSITY_RISE_HOLD use two states, but ELAPSED_TIME and INTENSITY_FALL move on after one. If the next rule is numbered two higher anyway, the one-state rule is applied again in the unused state in between: its time runs twice, and any PCF rows written for "the rule's two states" apply for twice as long. Audapter accepts the file without a warning.

When it matters

Matters for timed designs: a random delay after the detected onset, a fixed perturbation duration, or a hold before the next event. Safe if every ELAPSED_TIME or INTENSITY_FALL rule is followed by a rule numbered one higher, and the PCF's shifted rows match the states the rules actually use. Checking ost_stat of a pilot trial shows the doubled states.

Example

A plausible design, not one blab runs: F1 raised 125 mel for 0.2 s, starting a random 100–200 ms after the detected voice onset, on a short real vowel (0.35 s). Numbered correctly, the shift starts 0.10 s, 0.15 s and 0.20 s after onset and covers 190, 140 and 90 ms of the vowel. With every rule numbered two apart it starts 0.20 s, 0.30 s and never after onset and covers 88, 0 and 0 ms: at the longest delay the vowel is over before the shift begins. The shift state itself lasts 0.40 s instead of 0.20 s (from ost_stat).

rmsSlopeWin = 0.030000window for the level-slope estimate n = 44 rules follow0 INTENSITY_RISE_HOLD 0.02 0.02 {}state 0 → 2: level rises above 0.02 (next state) and stays above it for 0.02 s2 ELAPSED_TIME 0.15 NaN {}state 2 → 3: moves on 0.15 s after this state began; does not record its end time4 ELAPSED_TIME 0.2 NaN {}state 4 → 5: moves on 0.2 s after this state began; does not record its end time6 OST_END NaN NaN {}state 6: final state n = 0no maxIOI timeouts

rmsSlopeWin = 0.030000window for the level-slope estimate n = 44 rules follow0 INTENSITY_RISE_HOLD 0.02 0.02 {}state 0 → 2: level rises above 0.02 (next state) and stays above it for 0.02 s2 ELAPSED_TIME 0.15 NaN {}state 2 → 3: moves on 0.15 s after this state began; does not record its end time3 ELAPSED_TIME 0.2 NaN {}state 3 → 4: moves on 0.2 s after this state began; does not record its end time4 OST_END NaN NaN {}state 4: final state n = 0no maxIOI timeouts

00 time-warp sections 77 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0, 0, 0, 0state 0: no change1, 0, 0, 0, 0state 1: no change2, 0, 0, 0, 0state 2: no change3, 0, 0, 0, 0state 3: no change4, 0, 0, 125, 0state 4: formant shift 125 mel, F1 up5, 0, 0, 125, 0state 5: formant shift 125 mel, F1 up6, 0, 0, 0, 0state 6: no change

00 time-warp sections 55 state rows: state, pitch (semitones), level (dB), formant shift amount, angle0, 0, 0, 0, 0state 0: no change1, 0, 0, 0, 0state 1: no change2, 0, 0, 0, 0state 2: no change3, 0, 0, 125, 0state 3: formant shift 125 mel, F1 up4, 0, 0, 0, 0state 4: no change