Praat AudioTools Audio Quantizer

What this does

Audio Quantizer is an offline, onset-based timing processor for monophonic audio such as sung phrases, flute, or single-line instrumental playing. Select a Sound in Praat, define a tempo and rhythmic subdivision, and generate a new Sound whose detected note onsets move toward a timing grid. The original recording remains unchanged.

The timing grid can be mathematically straight or can inherit the microtiming of a short audio reference. Unlike MIDI quantization, the processor must first infer the beginnings of acoustic events. Unlike simple chopping and reassembly, it calculates a monotonic time map across the complete recording.

Main capabilities:

• Three grid types: Straight grid, Learned groove from a reference Sound, and Groove from a groove Table.
• Five rhythmic divisions: quarter notes, eighth notes, sixteenth notes, eighth-note triplets, and sixteenth-note triplets.
• Four onset-input methods: intensity slope, spectral flux, hybrid analysis, or manual onset TextGrid.
• Two independent strengths: Groove strength changes the grid; Quantization strength determines how far the target audio moves toward it.
• Voice-aware processing: selectable Voice-safe or Standard stretch profiles; WSOLA is the default resynthesis engine, with PSOLA available.
• Independent auditory clock: optional stereo preview with quantized audio in the left channel and click track in the right.
• Inspectable results: optional onset TextGrid, native Praat Picture visualization, numerical mapping check, and re-detection of attacks in the processed Sound.
• Native Praat workflow: no Python, external program, temporary WAV, or disk file is required during execution.

Quick start

1. Load a mono Sound into Praat and select it in the Objects window.
2. Run Audio_Quantizer.praat.
3. Keep Grid type = Straight grid for a first test. Set Tempo BPM and Grid division (for example 120 BPM and eighth notes).
4. Choose Quantization strength and, if needed, a maximum onset shift. Start with a moderate strength for vocal material.
5. Leave Automatic - Hybrid, WSOLA, and Voice-safe selected. Turn on Click track = Grid subdivision to hear the grid.
6. Press OK. Praat creates a processed mono Sound and, if clicks are enabled, a stereo preview. With Play result enabled, the preview is played automatically.
7. Inspect the Info report or optional Picture window. Listen to the mono result separately when judging timbre and artifacts.

Core concept and signal flow

The user supplies BPM. The script does not estimate the target performance's tempo automatically. Its reference-learning mode can fit the supplied reference tempo slightly (within a limited tolerance), but still requires a plausible tempo and meaningful bar alignment.

Three grid modes

These modes share the same downstream onset-to-target mapping, collision handling, duration constraints, and resynthesis engines. The important distinction is which grid positions the solver receives.

Object selection and dialogs

Tempo, rhythmic division and grid origin

Tempo BPM is quarter-note BPM, accepted between 20 and 300. The subdivision determines the distance between possible timing targets.

The script rejects a grid interval shorter than 30 ms. For Grid origin, choose First detected onset (default), Beginning of Sound, or Manual offset in milliseconds relative to the Sound's beginning.

Onset detection and note-level validation

An onset is an acoustically inferred attack or new event. It is not a MIDI note-on message and is not guaranteed to coincide with a musically intended note boundary. The four modes are:

Automatic processing includes an energy gate, an adaptive threshold, local peak picking, short backwards refinement toward the start of an attack, and a minimum-separation rule (80 ms by default). Onset sensitivity defaults to 1.5; higher values lower the threshold and generally produce more candidates.

With Note validation on (default, under Advanced settings), candidate attacks are checked for evidence including onset of voicing, a meaningful pitch transition, re-articulation, an unvoiced lead into a new note, or sufficiently strong acoustic evidence. Pitch is supplementary: the method can retain clear attacks even without stable pitch.

Quantization strength and displacement limits

Two distinct operations occur: first the timing grid is constructed, and only then is each target onset moved toward its nearest permissible grid position.

Two detected events may compete for one grid point. The script considers neighboring slots and applies an order-preserving constraint solver. It does not delete or merge notes to achieve perfect alignment. If an exact destination is unsafe, it reports a partial adjustment or an unquantized collision.

Learning a groove from a short reference Sound

Select Learned groove from a reference Sound and then choose the reference in the second dialog. The source should contain clear, repeated rhythmic events. A short drum pattern, articulated instrumental figure or repeated vocal rhythm is usually easier to analyze than an unarticulated legato line.

The reference detector must find at least four accepted onsets. The script assigns each reference onset to a nominal slot, then performs a two-pass least-squares fit of tempo and phase. A fitted reference tempo is adopted only if the grid interval differs by no more than 8% from the supplied tempo. Otherwise the user-supplied reference tempo remains in effect.

For each slot in the repeating pattern, the script calculates a median normalized timing offset across observed repetitions and an estimated spread. Multiple attacks assigned to the same slot are resolved by retaining the closer event. Beat-slot offsets are adjusted to preserve the reference clock on average. Unobserved slots remain straight; no timing deviation is invented for them.

How groove transfer works

Instead of storing deviations only in milliseconds, Audio Quantizer stores each slot's offset as a fraction of that grid interval. This allows a groove recorded at one BPM to be applied at another BPM.

Here, the learned offset is 14% of an eighth-note slot, so it scales with the destination tempo. Actual learned values are capped to plus or minus 0.45 of a grid interval to maintain an ordered grid.

It is the timing organization of the reference that is transferred. The melody, note sequence, articulation, timbral identity, and dynamics of the target are not copied from the reference or replaced.

Groove Table: keeping and reusing a learned pattern

Enable Keep groove Table in the Learned groove dialog to leave a reusable Praat Table in the Objects list. A subsequent run can use Grid type = Groove from a groove Table, with the target Sound and this Table selected.

Each row represents one slot in the pattern; the Table includes columns such as:

Elastic time mapping and collision-safe quantization

The processor creates a strictly ordered mapping between source time and destination time. Source anchors include the Sound beginning, accepted note onsets, and Sound ending. The two ends are fixed so the mapping aims to preserve the complete duration.

A chain-constraint solver combines the requested destinations with maximum displacement, minimum spacing, and allowed local stretching. The solution avoids reversed or collapsed events. If the solver cannot place an onset exactly on the requested grid position, the event is constrained rather than discarded.

Time change is distributed according to acoustic stretchability: silence is given greater weight than stable voiced material, unvoiced material less weight, and protected attacks approximately zero weight. The script builds a continuously sampled, weighted DurationTier and verifies the integrated duration at each onset anchor before synthesizing sound.

WSOLA and PSOLA: two resynthesis engines

The onset detector and stretchability analysis can still analyze Pitch when WSOLA is selected. "WSOLA: no pitch analysis" refers to its time-synthesis engine, not a promise that no pitch information is ever used anywhere in the script.

When Quantization strength is 0%, or the requested mapping contains no actual movement, the script creates an unprocessed copy rather than unnecessarily resynthesizing the source.

Voice-safe and Standard profiles

Voice-safe does not restrict every region of the file to 0.80-1.25. Silence can absorb much larger timing changes. This intentional asymmetry protects voiced material where possible, but can also result in incomplete quantization of densely sung passages.

The profile selects ratio and attack-protection values; it does not automatically reduce the Quantization strength. The main form's default strength is still 100%. For expressive singing, choose a moderate strength if naturalness matters more than full grid alignment.

Click-track listening preview

The optional click provides an independent timing reference. It is not generated from where the processed attacks happened to land. When enabled, the script keeps the processed mono Sound and also creates a stereo preview:

Each click is a short, approximately 5 ms windowed tone. Beat clicks use 2,000 Hz; subdivision clicks use 1,500 Hz at 60% of beat-click amplitude. The default Click level is 0.25 and is adjustable in Advanced settings.

In either Groove mode, a second-dialog setting Click follows selects Groove grid (default) or Straight grid. This is an important musical distinction: a groove-quantized performance is not necessarily supposed to coincide with a perfectly straight metronome.

Output Sounds, optional TextGrid and final selection

Output names vary with the actual input name, BPM, grid division, and whether the groove is active. If Play result is enabled, Praat plays the stereo click preview when present; otherwise it plays the mono result. The created outputs are selected at the end of the run.

The optional TextGrid has two point tiers: Quantized_Onsets and Original_Onsets. The second tier retains pre-quantization timestamps for comparison; these are not physical attacks in the output Sound. If Keep onset TextGrid is off, no diagnostic TextGrid remains.

Analysis report: how to read the numbers

With Show analysis report enabled (default), Praat's Info window summarizes the full run.

A low grid-fit concentration warns that the source performance does not clearly correspond to the selected tempo/division/phase. A quantizer can still produce an output in such a case, but its timing corrections may be musically arbitrary.

Five-panel Praat Picture visualization

With Draw visualization enabled (default), the script draws a native, approximately eight-inch Praat Picture layout. This is a diagnostic display, not an external image file.

For a learned groove, the grid lines refer to the selected groove-adjusted grid when Groove strength is nonzero. This makes the timing transformation visible as a musical mapping rather than as a generic audio effect.

Advanced settings

Enable Advanced settings on the main form to open a second dialog before processing.

Compositional workflows

Diagnostics and troubleshooting

Installation and requirements

Audio Quantizer is a single native Praat script. It requires a Praat version supporting the commands used by the script (including arrays, matrices, Table commands and the selected resynthesis functions). There is no Python package or second executable to install.

plugin_AudioTools/
  Dynamics & Envelope/
    Audio_Quantizer.praat
  ... (other existing AudioTools modules)

In Praat, load or select the required mono Sound object(s) and use Praat → Open Praat script... (or your existing AudioTools launcher/menu) to run the script. Select the correct objects before opening the form. For groove Table reuse, a compatible Table must already be present in Praat's Objects list.

In-memory processing and object safety

The script keeps the original user objects intact. It creates analysis objects and temporary grains inside Praat, then removes them during the normal processing path. No intermediary WAV, Python process, shell command or online service is required. The resulting mono Sound, optional stereo click preview, optional onset TextGrid and optional new groove Table are the intended persistent objects in the Objects window.

Play result plays the click preview when available; otherwise it plays the mono Sound. Finishing a successful run selects its output objects. The optional Groove Table is retained for reuse inside the current Praat session, not silently written to disk.

Limitations and performance considerations

• Monophonic focus: the target and reference Sounds must be mono. The processor is not a general polyphonic beat or drum quantizer.
• Reference interpretation is user-guided: BPM, bar organization, downbeat and pattern length matter. A pickup note or incorrect phase can produce the wrong groove.
• Groove represents timing offsets: it does not capture dynamics, articulation, timbre, note probabilities or pitch relationships.
• One repeating groove pattern: variation across different sections of a composition is reduced to slot-wise statistics; a gradually changing feel is not modeled independently by bar.
• Missing slots stay straight: events absent from the reference cannot provide evidence for a per-slot deviation.
• Strict timing limits are intentional: some note attacks remain off-grid to prevent event collisions, extreme stretching or damage to voiced material.
• Source onset estimates are imperfect: legato, phonetic transitions, vibrato, breath noise and repeated notes can confound automatic detection.
• WSOLA is not artifact-free: even waveform-based alignment may create smearing or discontinuities when local temporal changes are large.
• Numerical grid agreement is not identical to sound quality: the time-map integral, re-detected onset errors and critical listening answer different questions.
• Performance can scale poorly: the current WSOLA implementation makes many short Praat Sounds in memory, so test long recordings cautiously.
• No automatic disk persistence: a Groove Table must be deliberately saved through Praat's normal object-save workflow if needed across sessions.

Practical recommendation: first evaluate a short straight-grid example, then learn a groove from a short, clearly articulated reference. Keep the click enabled during timing checks, but evaluate the separate mono output for sound quality.