Onset-Based Oscillator Bank — User Guide

Onset-responsive additive resynthesis that turns detected attacks into pitched, decaying oscillator bursts while retaining optional dry-signal continuity.

Author: Shai Cohen Version: 2.3 (2026) Application: Praat scripting language License: MIT License

Contents:

What this does Signal flow Quick start Onset & pitch analysis Oscillator bank Presets Parameters Speed modes Input & output behavior Visualization Notes & limitations Further reading

What this does

Onset-Based Oscillator Bank analyzes the temporal attacks of a sound and uses selected onsets to trigger short additive-synthesis events. Each accepted onset is locally refined, assigned a pitch estimate, and converted into a bank of harmonic partials whose frequency spread, decay, brightness, velocity response, and waveshaping determine the resulting resonance.

The source therefore provides two kinds of control: its attack pattern determines when oscillator bursts begin, and the local pitch estimate determines the fundamental frequency of each bank. The generated bank can replace the source or be mixed with it, creating a continuum from dry articulation with added resonance to fully synthesized onset-driven output.

Core idea: detected attacks become synthesis events. A valid pitch at an onset defines the oscillator bank; onset strength can scale its amplitude; the original waveform remains available through the Dry/Wet control.

Signal flow

Selected Sound
   ↓
Optional analysis/synthesis downsampling
   ↓
Mono analysis copy → Intensity-rise onset candidates
   ↓
Local 5 ms RMS-rise timing refinement
   ↓
Raw-autocorrelation pitch estimate around each onset
   ↓
Valid-pitch onsets trigger additive oscillator bursts
   ↓
Attack + exponential decay + detuning + brightness/waveshaping
   ↓
Wet bank copied identically to every output channel
   ↓
Wet fadeout → optional upsampling → Dry/Wet mix
   ↓
Safety attenuation only when peak > 0.99
   ↓
Original start time restored

Quick start

Select exactly one Sound object.
Run Onset-Based_Oscillator_Bank.praat.
Choose a preset or Custom.
Adjust Onset threshold and Min intensity if attacks are missed or over-detected.
Use Num partials, Partial spread, Decay, and Brightness to shape the oscillator bank.
Choose a Speed mode. Balanced is the default.
Set the output Tail duration, Fadeout duration, and Dry/Wet mix.
Optionally draw the visualization and play the result.

If no onsets are found, the script stops and asks for a lower onset threshold. If onsets are found but none receive a valid pitch estimate, the wet bank is silent; the Dry/Wet setting then determines how much original signal remains.

Onset & pitch analysis

1. Intensity-rise candidates

Analysis is performed on a mono, zero-based copy of the working Sound. Praat creates an Intensity contour with a 50 Hz analysis floor and automatic time step. For each candidate frame the script compares the current Intensity with the value two frames earlier:

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

A candidate is accepted only when this rise score exceeds Onset_threshold_(dB), the current Intensity exceeds Min_intensity_(dB), and the refined onset is farther than Min_interval_(s) from the previous accepted onset.

2. Local timing refinement

The Intensity contour uses a symmetric analysis window and can place a sharp attack slightly early. For each candidate, the script therefore searches forward for up to 80 ms in 2 ms steps. At every step it compares the RMS of the preceding 5 ms with the following 5 ms and chooses the time with the strongest positive RMS rise.

3. Onset velocity

The original Intensity-rise score is converted to a normalized velocity:

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

When Velocity_sensitive is enabled, this value scales the complete oscillator burst. When it is disabled, every valid-pitch onset uses an amplitude scale of 1.0.

4. Pitch extraction

For each onset, the script analyzes approximately 20 ms before to 120 ms after the refined onset. It uses Praat's legacy To Pitch (ac) command, which is the raw-autocorrelation pitch method. The pitch floor is fixed at 50 Hz. The ceiling is:

min(4000 Hz, working sample rate / 4)

The script first queries pitch at the onset itself. If that value is undefined, it falls back to the mean pitch of the segment and then to its median. Only estimates between 50 Hz and the computed ceiling can trigger a burst.

Oscillator bank

Partial frequencies

For a detected pitch F0, partial n begins around n × F0. Each partial receives an independent random detuning:

frequency = F0 × n × (1 + U[-0.01, +0.01] × Partial_spread)

Because the GUI value is expressed as a percent, Partial spread = 1.0 produces up to approximately ±1% detuning around each harmonic; 0.5 produces ±0.5%.

The requested number of partials is additionally limited by the working Nyquist frequency. The bank uses only partials whose fundamentals remain below the script's high-frequency safety margin.

Attack and decay

Each partial receives its own attack and decay variation. The envelope is a linear attack followed by exponential decay:

attack:  x / attackTime

decay:   exp(-(x − attackTime) / decayTime)

The preset chooses the base attack. A random value from 0 to 10 ms is added to each partial. Decay receives a random variation of ±0.5 s and is clamped to at least 50 ms. Burst rendering is bounded to roughly four decay time constants, with an absolute maximum of 5 s and the global output-tail boundary.

Brightness and amplitude

Before random amplitude variation, each partial is weighted approximately as:

0.1 / sqrt(partial number) × Brightness^(partial number − 1) × velocity

Brightness therefore controls the spectral roll-off of the bank: lower values suppress upper partials more strongly. Independent amplitude randomization of ±30% adds small event-to-event and partial-to-partial differences.

Cubic waveshaping

A preset-dependent amount of cubic waveshaping is blended into each partial. The script expands sin³ analytically into a fundamental component and a third harmonic. This allows it to omit only the generated third harmonic when that component would exceed the Nyquist safety margin, rather than allowing it to alias back into the audible band.

Randomness: detuning, attack, decay, and amplitude are randomized for every valid-pitch onset. The script does not expose a random seed, so repeated runs with the same settings can produce slightly different wet signals.

Presets

Presets override the parameters shown below. Speed mode, Tail duration, Fadeout duration, Velocity sensitivity, visualization, and playback remain user-controlled unless explicitly listed.

Preset	Onset settings	Bank	Envelope / mix
Custom	Uses form values	Uses form values	Attack 5 ms; internal waveshape amount 0.20
Gentle Resonance	Threshold 2.0 dB; min intensity 35 dB; min interval 0.15 s	8 partials; spread 0.3%; brightness 0.5	Decay 2.0 s; attack 10 ms; Dry/Wet 0.7; waveshape 0.10
Percussive Bells	1.5 dB; 40 dB; 0.08 s	15 partials; 0.8%; brightness 0.9	Decay 1.0 s; attack 2 ms; Dry/Wet 1.0; waveshape 0.30
Ethereal Pad	2.5 dB; 30 dB; 0.20 s	20 partials; 0.2%; brightness 0.6	Decay 3.5 s; attack 50 ms; Dry/Wet 0.8; waveshape 0.15
Metallic Shimmer	1.2 dB; 35 dB; 0.10 s	18 partials; 1.0%; brightness 1.0	Decay 1.2 s; attack 3 ms; Dry/Wet 1.0; waveshape 0.40
Natural Pluck	1.5 dB; 35 dB; 0.12 s	6 partials; 0.4%; brightness 0.7	Decay 0.8 s; attack 1 ms; Dry/Wet 0.9; waveshape 0.15
Dense Cluster	1.0 dB; 32 dB; 0.05 s	25 partials; 1.2%; brightness 0.8	Decay 1.8 s; attack 8 ms; Dry/Wet 1.0; waveshape 0.25

Parameters

Parameter	Default	Meaning
Preset	Custom	Selects Custom or one of six parameter sets.
Onset_threshold_(dB)	1.5	Minimum two-frame Intensity-rise score required for an onset candidate.
Min_intensity_(dB)	35	Candidate Intensity must exceed this value.
Min_interval_(s)	0.10	Minimum spacing between accepted, refined onsets.
Velocity_sensitive	On	Uses the normalized onset-rise score to scale burst amplitude.
Num_partials	12	Requested harmonic partial count; internally clamped to 1–32 and further limited by Nyquist.
Partial_spread_(percent)	0.5	Maximum random detuning scale around harmonic frequencies; internally capped at 5%.
Decay_(s)	1.5	Base exponential-decay time before per-partial ±0.5 s randomization.
Brightness	0.7	0–1 spectral-tilt control; also scales the preset's cubic-waveshaping contribution.
Speed_mode	Balanced	Working sample-rate strategy for analysis and wet synthesis.
Tail_duration_(s)	2.0	Extends the output after the original source so late bursts can decay.
Fadeout_duration_(s)	0.5	Linear fade applied to the wet signal at the very end of the extended output.
Dry_wet_mix	1.0	0 = dry source plus silent tail; 1 = wet oscillator bank only.
Draw_visualization	On	Draws the suite-standard diagnostic page.
Play_result	On	Plays the selected output after processing.

Speed modes

Mode	Working rate	Behavior
Full Quality	Original sample rate	Analysis and oscillator synthesis run at the source rate.
Balanced	22,050 Hz	If the source rate is higher, a temporary working copy is downsampled to 22.05 kHz. The wet result is resampled back to the original rate before mixing.
Fast	16,000 Hz	Same strategy at 16 kHz. This reduces the available pitch/partial bandwidth and changes the analysis/synthesis resolution.

If the input sample rate is already at or below the selected target, the script does not upsample it. The final output sample rate remains the original sample rate in all modes.

Input & output behavior

Property	Behavior
Selection	Exactly one Sound; minimum duration 0.1 s.
Analysis channels	All input channels are converted to one mono analysis copy for onset and pitch detection.
Output channels	The original channel count is preserved. The synthesized wet bank is identical in every output channel; the dry path preserves each original channel independently.
100% wet	Every channel contains the same oscillator-bank signal.
Intermediate Dry/Wet	Each original channel is mixed with the same wet bank, so original inter-channel differences remain only through the dry component.
0% wet	The source samples are copied exactly across the original duration. The output still includes the requested silent tail.
Duration	`source duration + Tail_duration`.
Start time	The original `xmin` is restored after visualization. The extended tail follows the original time domain.
Sample rate	Same as the original Sound.
Output level	When Dry/Wet > 0.01, the script attenuates the complete output only if its peak exceeds 0.99. Quiet outputs are never boosted. At the exact dry path, no safety scaling is applied.
Output name	`original_resonated_PresetName`.
Reproducibility	Wet synthesis is stochastic and no user seed is provided.

Visualization

The v2.3 visualization uses the suite-standard 8 × 8 Picture layout and is diagnostic rather than a separate processing stage.

Panel	Content
A — Original + onsets	Mono analysis waveform over the original duration. Red vertical markers are onsets with valid pitch; grey markers are detected onsets without valid pitch.
B — Output	Processed waveform over the complete source-plus-tail duration.
C — Detected pitches	Valid pitch estimates plotted at their refined onset times.
D — Onset velocities	Stem plot of normalized onset-rise values; orange indicates a valid pitch and grey indicates no valid pitch.
E — Summary	Preset, valid/detected onset counts, partial count, spread, decay, threshold, interval, brightness, Dry/Wet, tail, speed, processing time, RMS, safety-scaling state, and output name.

Notes & limitations

Only valid-pitch onsets synthesize sound. An attack can appear in the onset visualization without creating a burst when the local pitch analysis is unvoiced or outside the allowed range.
The synthesis is event-based. Pitch is sampled around each onset and then held as the basis of that burst; it does not follow a continuous pitch trajectory after the trigger.
Wet spatial information is uniform. The same wet bank is written to every channel. Multichannel spatial differences come from the dry component.
Speed modes change the working bandwidth. Balanced and Fast can therefore change onset/pitch decisions and the number of available upper partials, not just processing time.
Safety scaling is attenuation-only. It protects peaks above 0.99 but does not loudness-match different presets or different random realizations.