Onset-Based Oscillator Bank — User Guide

Transform detected acoustic attacks into pitched, resonant oscillator bursts. Shape the spectrum, stagger individual partial entrances, and choose how event pitches are estimated, while keeping the original sound available through an independent Dry/Wet mix.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 2.7 (2026) Application: Praat scripting language License: MIT License Repository: Praat AudioTools

What this does

Onset-Based Oscillator Bank turns attacks in a recorded sound into additive-synthesis events. Each detected onset is refined in time, assigned a pitch where possible, and used to trigger a bank of harmonic oscillators. Partial count, detuning, decay, spectral brightness, waveshaping, and onset strength shape the resulting resonance.

The instrument follows two features of its input: the timing of attacks determines when resonances begin, while estimated event pitch determines their harmonic foundations. An optional Attack Stagger delays the entrance of individual partials within each event. The original recording can be retained, attenuated, or completely replaced by the synthesized signal.

Two independent choices: the preset determines the character of the response; Dry/Wet (%) always remains under the user's control. Pitch-estimation and Attack Stagger settings are also not overwritten by the six musical presets.

Signal flow

Selected Sound (original sample rate)
    ↓
Mono analysis copy → Intensity-rise onset candidates
    ↓
Local RMS-rise timing refinement
    ↓
Pitch estimation: Legacy / diagnostic / context-aware
    ↓
Usable event pitches trigger additive oscillator bursts
    ↓
Per-partial attack, decay, detuning, brightness, waveshaping
    + optional independent partial-onset delays (Attack Stagger)
    ↓
Wet oscillator bank (same signal in each output channel)
    ↓
Wet fadeout → Dry/Wet (%) mix with original channels
    ↓
Peak safety attenuation if necessary → restored start time

The script analyzes and synthesizes at the original sample rate. There is no Speed Mode and no automatic analysis downsampling.

Quick start

  1. Select exactly one Sound object in Praat and run Onset-Based_Oscillator_Bank.praat.
  2. Choose Custom or one of the six musical presets.
  3. Choose a Pitch estimation mode. For sustained pitched instruments, try a context-aware mode; for an exact legacy comparison choose Legacy v2.3.
  4. If needed, set Pitch floor and Pitch ceiling to a plausible fundamental-frequency range.
  5. Set Attack stagger (ms) to 0 for synchronized partials or a positive value to spread their entrances. Choose the stagger pattern and optionally set a random seed.
  6. Set Dry/Wet (%) to your preferred mix. This choice is respected in every preset: 0 = source only; 100 = synthesized bank only.
  7. Set tail and fadeout durations as needed, then run. The output remains selected and can optionally be played and visualized.
If the result lacks notes: first check whether onsets were detected and whether the selected pitch-estimation mode found usable event pitches. Lowering the onset threshold may find more attacks; a narrower, musically plausible pitch range can sometimes improve pitch tracking, but cannot resolve all ambiguities.

Onset detection

Intensity-rise candidates

Analysis uses a mono, zero-based copy of the input. The script constructs a Praat Intensity contour using a 50 Hz analysis floor, and computes:

rise score = (current intensity − intensity two frames earlier) / 2

A candidate is accepted when its rise score exceeds Onset_threshold_(dB), its intensity exceeds Min_intensity_(dB), and the refined event is sufficiently far from the previous accepted onset according to Min_interval_(s).

Timing refinement

For each candidate, the script searches forward up to 80 ms in 2 ms steps. At each position, it compares the RMS of the preceding and following 5 ms windows, selecting the strongest positive rise. This compensates for the tendency of symmetric Intensity analysis windows to locate sharp attacks early.

Onset velocity

velocity = clamp((rise score − threshold) / 10, 0.3, 1.0)

When Velocity sensitive is enabled, the measured onset strength scales the synthesized event's amplitude. Otherwise, usable events are rendered at a common velocity scale.

The onset detector is the same across pitch-estimation modes. Pitch analysis determines whether and at what frequency a detected event is synthesized; it does not move the onset.

Pitch estimation and octave ambiguity

The script offers four pitch-estimation modes. Their differences matter for flute tones, speech, noisy attacks, and other material in which an isolated short-window estimate may be misleading.

ModeHow it worksWhat happens to uncertain events
Legacy v2.3 DefaultAnalyzes a short segment around each onset using Praat raw autocorrelation. It first requests the pitch at the onset, then falls back to the segment mean and median.Events without a valid estimate do not trigger a burst.
Legacy v2.3 + octave diagnosticsUses the same pitch and synthesis decisions, but additionally checks spectral evidence for possible octave errors or a non-single-harmonic-series event.Reports suspicions only. It never corrects or rejects a pitch on the basis of these diagnostics.
Context-aware: skip unpitchedUses a continuous Praat pitch track, selecting a locally consistent group of post-onset frames for each event.Events without enough stable voiced frames are not synthesized.
Context-aware: nearest pitchUses the same context-aware estimate for pitched events.An unpitched event borrows the pitch of the nearest reliably pitched event in the recording, if one exists.

Pitch range

Pitch floor defaults to 50 Hz (minimum permitted value 25 Hz). Pitch ceiling defaults to 0, meaning the automatic ceiling min(4000 Hz, sample rate / 4), with the script's low-rate guard. A positive manual ceiling is constrained to sample rate / 4. The effective ceiling must be at least twice the floor.

How context-aware estimation works

Rather than taking the mean of one short onset segment, this method analyzes the whole recording with a continuous raw-autocorrelation pitch track and stronger continuity penalties for octave jumps. For each detected onset it examines frames beginning about 15 ms after the attack and continuing up to the following onset or approximately 200 ms, with a minimum intended analysis span of about 60 ms where the recording permits.

It finds the largest cluster of voiced frames within ±3 semitones of a candidate and uses their median in logarithmic pitch space. At least three agreeing voiced frames are required. This can prevent an isolated low- or high-octave frame from dominating the event frequency, but it is not a polyphonic pitch estimator.

In skip mode, events without a stable pitch remain visible in the diagnostics but produce no wet oscillator burst. In nearest pitch mode, they can still trigger a burst at the frequency of a nearby pitched event, which preserves more rhythmic activity but can assign an artificial pitch to noise or consonants.

Octave diagnostics are advisory. The report-only mode can mark a possible ×2, ÷2 or other integer-ratio error, or a spectrum that does not resemble one harmonic series. Chords, bells, noisy attacks and missing fundamentals can make these spectral heuristics unreliable. The diagnostics do not automatically transpose any note.

Oscillator bank

Harmonic structure

Each usable event pitch F0 generates up to 32 partials, bounded by the selected count and the source sample rate's Nyquist frequency:

partial frequency ≈ F0 × partial number × (1 + random detuning)

Partial spread (%) is a detuning percentage: 1.0 permits approximately ±1% variation for each harmonic; values are internally capped at 5%. Partials that are too high for the Nyquist safety margin are omitted.

Envelope and amplitude

Each partial has a linearly rising attack followed by exponential decay. The preset selects the base attack duration; each partial receives an additional random attack-duration variation of up to 10 ms. Decay is randomized by ±0.5 s and clamped to a minimum of 50 ms.

attack envelope:  local time / attack duration

decay envelope:   exp(−(local time − attack duration) / decay time)

Partial amplitude falls approximately as 0.1 / sqrt(partial number), multiplied by Brightness^(partial number − 1), event velocity when enabled, and independent random amplitude variation of ±30%.

Waveshaping

A preset-dependent cubic-waveshaping amount blends extra spectral energy into each partial. The engine expands the cubic sine term into the fundamental and its third harmonic, and omits third-harmonic components that would exceed the Nyquist safety threshold.

Attack Stagger: independent partial entrances

Attack Stagger controls when the partials within one synthesized resonance begin, separately from how long each partial's attack takes. With 0 ms all partials begin together, following the original bank behavior. A positive value spreads their entrances over a user-defined interval of up to 100 ms.

Attack stagger modeBehavior
Random uniformIndependent entrance delays distributed uniformly between 0 and the selected maximum.
Random Gaussian-likeDelays clustered toward the center of the interval by averaging three uniform random values.
Ascending spectral (low first)Lower-frequency partials enter first; higher partials follow across the selected interval.
Descending spectral (high first)Higher-frequency partials enter first; lower partials follow.

The ordering is based on the actual detuned partial frequencies, not just partial numbers. Each delayed partial contributes silence until its entrance, then begins its own attack and decay with the oscillator phase starting at that entrance. The burst is lengthened by the largest delay.

Attack Stagger does not spread the detected onsets themselves. Each acoustic attack still triggers one event at its detected time; staggering happens inside the oscillator bank created by that event.

Listening suggestion: compare 0 ms, 10–20 ms and 40–80 ms with the same preset and random seed. Small values can subtly change attack fusion; larger values can make the partials arrive as a perceptible spectral sequence. Stagger does not guarantee a smoother or quieter attack; peak and crest factor can increase.

Random seed

Random seed = 0 leaves synthesis unseeded, as in the original implementation. A positive seed makes the run repeatable. The implementation uses a separate random stream for stagger delays so enabling stagger does not need to change the underlying detuning, attack durations, decays, or amplitudes. The random generator is restored to an unpredictable state afterward.

Presets

The six musical presets shape onset sensitivity and the oscillator bank. They do not override Dry/Wet (%), the Pitch estimation mode, Pitch floor/ceiling, or Attack Stagger settings. The Attack Stagger default is 0 ms for all presets unless the user changes it.

PresetOnset settings
threshold / minimum intensity / interval
Oscillator settings
partials / spread / brightness
Envelope & waveshaping
decay / base attack / waveshape
Typical character
CustomUses form valuesUses form valuesDecay from form / 5 ms base attack / 0.20 waveshapeUser-defined resonance
Gentle Resonance2.0 dB / 35 dB / 0.15 s8 / ±0.3% / 0.52.0 s / 10 ms / 0.10Restrained, softer resonances
Percussive Bells1.5 dB / 40 dB / 0.08 s15 / ±0.8% / 0.91.0 s / 2 ms / 0.30Short bright attacks and bell-like decay
Ethereal Pad2.5 dB / 30 dB / 0.20 s20 / ±0.2% / 0.63.5 s / 50 ms / 0.15Slower, sustained spectral layers
Metallic Shimmer1.2 dB / 35 dB / 0.10 s18 / ±1.0% / 1.01.2 s / 3 ms / 0.40Bright, detuned metallic textures
Natural Pluck1.5 dB / 35 dB / 0.12 s6 / ±0.4% / 0.70.8 s / 1 ms / 0.15Compact plucked responses
Dense Cluster1.0 dB / 32 dB / 0.05 s25 / ±1.2% / 0.81.8 s / 8 ms / 0.25High-density overlapping resonances

The attack duration still includes independent random variation of 0–10 ms and the decay includes ±0.5 s variation. Preset settings describe the synthesis model, not a guarantee of a particular perceptual result. All preset mixes use the user's chosen Dry/Wet percentage.

Parameters

ParameterForm defaultFunction
PresetCustomCustom or one of six onset/synthesis settings.
Onset threshold (dB)1.5Intensity-rise threshold; lower values generally accept more candidates.
Min intensity (dB)35Minimum Intensity at an onset candidate.
Min interval (s)0.10Minimum time between accepted refined onsets.
Pitch floor (Hz)50Lowest candidate F0, minimum allowed 25 Hz.
Pitch ceiling (Hz, 0 = auto)0Automatic up to 4000 Hz or sample rate / 4; manually adjustable within limits.
Pitch estimationLegacy v2.3Legacy, diagnostic-only, or two context-aware modes.
Velocity sensitiveOnScales synthesized amplitude using onset-rise strength.
Num partials12Requested partial count, clamped to 1–32 and further bounded by Nyquist.
Partial spread (%)0.5Random percentage detuning; capped at 5%.
Decay (s)1.5Base exponential-decay time.
Brightness0.7Spectral roll-off and waveshaping weighting, clamped to 0–1.
Attack stagger (ms)0Maximum delayed entrance per partial, 0–100 ms. Independent of preset.
Attack stagger modeRandom uniformUniform, Gaussian-like, ascending or descending entrances.
Random seed (0 = unseeded)00 = unseeded; positive integer = reproducible synthesis.
Tail duration (s)2.0Additional output time after the source.
Fadeout duration (s)0.5Fade at the end of the wet signal, clamped to output length.
Dry/Wet (%)100Independent of presets: 0% = exact source samples plus silence; 100% = synth only; 1–99% = linear mix.
Draw visualizationOnCreates a diagnostic Praat Picture page.
Play resultOnPlays the selected result after synthesis.
Processing rate: the script always uses the input Sound's original sample rate. There is no speed/quality selector; this avoids changing pitch decisions and upper-partial bandwidth through downsampling.

Input & output behavior

PropertyBehavior
Input selectionExactly one Sound object, at least 0.1 s long.
AnalysisMono copy for detecting onsets and estimating pitch. Full original sample rate is retained.
Output channelsSame channel count as the source. The wet oscillator bank is the same in each channel; the dry branch retains each channel independently.
0% wetOriginal input samples exactly through the source duration, followed by silent extension. No peak scaling on this path once processing reaches the output stage.
1–99% wetLinear blend: dry × (1 − wetFraction) + synthesized × wetFraction. No 1%/99% shortcut.
100% wetSynthesized oscillator-bank sound only (identical wet component in each output channel).
Output durationsource duration + Tail duration + Attack stagger (seconds); the last term is zero when staggering is off.
Wet fadeoutLinear fade at the end of the extended wet signal. The dry source itself is not faded.
Peak protectionFor wet percentages above zero, attenuation only if the final peak exceeds 0.99. Quiet signals are not boosted.
Time originOriginal Sound start time is restored to the output after diagnostics.
Output sample rateExactly the source sample rate; no automatic downsampling or upsampling.
Output nameoriginal_resonated_PresetName.
Important: choosing 0% Wet controls the mix; it does not bypass onset analysis at the start of the script. If no onsets are found, the script exits before output is created. Similarly, a source with no usable pitched events can produce silent wet output in modes that skip unpitched events.

Visualization and reports

The script draws the Praat AudioTools 8 × 8 Picture layout when visualization is enabled.

PanelWhat it shows
A — Original + onsetsMono waveform with red markers for onsets with a usable pitch and grey markers for those without one.
B — OutputResulting waveform, including the extended tail.
C — Event pitchesSelected event pitches in green. Context-aware modes also show the continuous pitch track in grey and a cross for materially different legacy estimates; diagnostic mode adds labels for octave or mixture suspicions.
D — Onset velocitiesVelocity stems with orange for events with a usable pitch and grey otherwise.
E — SummaryPreset, onsets, partials, spread, decay, pitch range, stagger, seed, Dry/Wet, sample rate, render time, RMS, and safety-scaling status.

The Info window reports overall processing statistics. Context-aware modes additionally list each onset's legacy pitch, selected pitch, voiced-frame count, measured pitch spread and whether a nearest-neighbor pitch was borrowed. The diagnostic-only mode prints suspected octave alternatives without changing the sound.

Notes & limitations

Further reading