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.
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.
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
- Select exactly one Sound object in Praat and run
Onset-Based_Oscillator_Bank.praat. - Choose Custom or one of the six musical presets.
- Choose a Pitch estimation mode. For sustained pitched instruments, try a context-aware mode; for an exact legacy comparison choose Legacy v2.3.
- If needed, set Pitch floor and Pitch ceiling to a plausible fundamental-frequency range.
- 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.
- Set Dry/Wet (%) to your preferred mix. This choice is respected in every preset: 0 = source only; 100 = synthesized bank only.
- Set tail and fadeout durations as needed, then run. The output remains selected and can optionally be played and visualized.
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.
| Mode | How it works | What happens to uncertain events |
|---|---|---|
| Legacy v2.3 Default | Analyzes 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 diagnostics | Uses 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 unpitched | Uses 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 pitch | Uses 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.
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 mode | Behavior |
|---|---|
| Random uniform | Independent entrance delays distributed uniformly between 0 and the selected maximum. |
| Random Gaussian-like | Delays 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.
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.
| Preset | Onset settings threshold / minimum intensity / interval | Oscillator settings partials / spread / brightness | Envelope & waveshaping decay / base attack / waveshape | Typical character |
|---|---|---|---|---|
| Custom | Uses form values | Uses form values | Decay from form / 5 ms base attack / 0.20 waveshape | User-defined resonance |
| Gentle Resonance | 2.0 dB / 35 dB / 0.15 s | 8 / ±0.3% / 0.5 | 2.0 s / 10 ms / 0.10 | Restrained, softer resonances |
| Percussive Bells | 1.5 dB / 40 dB / 0.08 s | 15 / ±0.8% / 0.9 | 1.0 s / 2 ms / 0.30 | Short bright attacks and bell-like decay |
| Ethereal Pad | 2.5 dB / 30 dB / 0.20 s | 20 / ±0.2% / 0.6 | 3.5 s / 50 ms / 0.15 | Slower, sustained spectral layers |
| Metallic Shimmer | 1.2 dB / 35 dB / 0.10 s | 18 / ±1.0% / 1.0 | 1.2 s / 3 ms / 0.40 | Bright, detuned metallic textures |
| Natural Pluck | 1.5 dB / 35 dB / 0.12 s | 6 / ±0.4% / 0.7 | 0.8 s / 1 ms / 0.15 | Compact plucked responses |
| Dense Cluster | 1.0 dB / 32 dB / 0.05 s | 25 / ±1.2% / 0.8 | 1.8 s / 8 ms / 0.25 | High-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
| Parameter | Form default | Function |
|---|---|---|
| Preset | Custom | Custom or one of six onset/synthesis settings. |
| Onset threshold (dB) | 1.5 | Intensity-rise threshold; lower values generally accept more candidates. |
| Min intensity (dB) | 35 | Minimum Intensity at an onset candidate. |
| Min interval (s) | 0.10 | Minimum time between accepted refined onsets. |
| Pitch floor (Hz) | 50 | Lowest candidate F0, minimum allowed 25 Hz. |
| Pitch ceiling (Hz, 0 = auto) | 0 | Automatic up to 4000 Hz or sample rate / 4; manually adjustable within limits. |
| Pitch estimation | Legacy v2.3 | Legacy, diagnostic-only, or two context-aware modes. |
| Velocity sensitive | On | Scales synthesized amplitude using onset-rise strength. |
| Num partials | 12 | Requested partial count, clamped to 1–32 and further bounded by Nyquist. |
| Partial spread (%) | 0.5 | Random percentage detuning; capped at 5%. |
| Decay (s) | 1.5 | Base exponential-decay time. |
| Brightness | 0.7 | Spectral roll-off and waveshaping weighting, clamped to 0–1. |
| Attack stagger (ms) | 0 | Maximum delayed entrance per partial, 0–100 ms. Independent of preset. |
| Attack stagger mode | Random uniform | Uniform, Gaussian-like, ascending or descending entrances. |
| Random seed (0 = unseeded) | 0 | 0 = unseeded; positive integer = reproducible synthesis. |
| Tail duration (s) | 2.0 | Additional output time after the source. |
| Fadeout duration (s) | 0.5 | Fade at the end of the wet signal, clamped to output length. |
| Dry/Wet (%) | 100 | Independent of presets: 0% = exact source samples plus silence; 100% = synth only; 1–99% = linear mix. |
| Draw visualization | On | Creates a diagnostic Praat Picture page. |
| Play result | On | Plays the selected result after synthesis. |
Input & output behavior
| Property | Behavior |
|---|---|
| Input selection | Exactly one Sound object, at least 0.1 s long. |
| Analysis | Mono copy for detecting onsets and estimating pitch. Full original sample rate is retained. |
| Output channels | Same channel count as the source. The wet oscillator bank is the same in each channel; the dry branch retains each channel independently. |
| 0% wet | Original 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% wet | Linear blend: dry × (1 − wetFraction) + synthesized × wetFraction. No 1%/99% shortcut. |
| 100% wet | Synthesized oscillator-bank sound only (identical wet component in each output channel). |
| Output duration | source duration + Tail duration + Attack stagger (seconds); the last term is zero when staggering is off. |
| Wet fadeout | Linear fade at the end of the extended wet signal. The dry source itself is not faded. |
| Peak protection | For wet percentages above zero, attenuation only if the final peak exceeds 0.99. Quiet signals are not boosted. |
| Time origin | Original Sound start time is restored to the output after diagnostics. |
| Output sample rate | Exactly the source sample rate; no automatic downsampling or upsampling. |
| Output name | original_resonated_PresetName. |
Visualization and reports
The script draws the Praat AudioTools 8 × 8 Picture layout when visualization is enabled.
| Panel | What it shows |
|---|---|
| A — Original + onsets | Mono waveform with red markers for onsets with a usable pitch and grey markers for those without one. |
| B — Output | Resulting waveform, including the extended tail. |
| C — Event pitches | Selected 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 velocities | Velocity stems with orange for events with a usable pitch and grey otherwise. |
| E — Summary | Preset, 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
- This is a monophonic event-pitch model. Chords, complex bells, noise and consonants may have no single meaningful F0. Context-aware estimation improves some local errors but cannot infer all simultaneously sounding pitches.
- Onsets and pitch are separate decisions. A detected attack can be displayed without generating wet sound when it lacks a usable pitch.
- Context-aware nearest-pitch mode trades accuracy for continuity. Borrowed pitches keep more event triggers, but can create pitched resonances at originally unpitched attacks.
- Attack Stagger shapes partial entrances only. It does not change acoustic onset detection or create independent onset events from one trigger.
- Stagger can increase transient peaks. It changes overlap and early spectral balance; it is not inherently a smoothing or loudness-control process.
- The wet bank has no spatial movement. Its signal is copied identically into all output channels; the dry source retains any original inter-channel differences.
- Peak protection is not loudness matching. Different presets and seeds may produce different perceptual levels even when their peaks are below 0.99.
Further reading
- Bello, J. P., Daudet, L., Abdallah, S., Duxbury, C., Davies, M. E., & Sandler, M. B. (2005). A Tutorial on Onset Detection in Music Signals. IEEE Transactions on Speech and Audio Processing, 13(5), 1035–1047. DOI.
- Boersma, P. (1993). Accurate short-term analysis of the fundamental frequency and the harmonics-to-noise ratio of a sampled sound. Proceedings of the Institute of Phonetic Sciences Amsterdam, 17, 97–110.
- Praat Manual: Sound: To Intensity..., Sound: To Pitch (ac)... and pitch analysis by raw autocorrelation.
- Truax, Barry. Soundscape Composition and Microsound. Relevant to the perceptual distinction between synchronized partial attacks and asynchronous, textured spectral entrances.