Acoustic Grammar Reducer — User Guide

What is this?

Acoustic Grammar Reducer is a structural audio reduction system that analyzes temporal, pitch, dynamic, and timbral relations in a recording and constructs a relative acoustic hierarchy from them. It detects acoustically supported event boundaries, merges weaker boundaries into larger groups, scores the resulting groups for structural salience, and uses the highest-ranked structural spans to create a shorter montage from the original recording. The result is an acoustically derived structural skeleton whose content depends on the current source and parameter settings.

The montage is intended to expose a reduced structural backbone of the source rather than reproduce the whole recording.

Why “grammar”?

Here, “grammar” means a hierarchy inferred from relations among acoustic events. The system borrows two ideas from GTTM-style musical organization:

• Grouping: where one perceptual/musical unit appears to end and another begins.
• Time-span reduction: which units act as stronger structural heads and which are more subordinate.

The implementation turns those ideas into measurable acoustic decisions. Boundaries are supported by timing, pitch, dynamics, and timbre; structural heads are supported by duration, pitch stability, intensity, and low pitch variance.

How the application works

The application treats the recording as a sequence of acoustically defined events and larger structural units. It begins by measuring changes in pitch, intensity, timing, and spectral/formant characteristics across the Sound. These measurements are then used to locate event onsets and to estimate where acoustically supported group boundaries occur.

Once these initial events have been identified, the reducer evaluates how strongly each boundary separates one region from the next. Boundaries supported by larger timing gaps, pitch changes, dynamic drops, or timbral shifts are more likely to remain. Weaker boundaries are merged, allowing short local events to form larger acoustic groups.

The resulting groups are then evaluated for structural salience. Duration, pitch stability, intensity peaks, and pitch variance contribute to a head score for each group. A dynamic-programming stage uses these scores together with minimum-spacing constraints to select a structural backbone rather than simply choosing the loudest or longest events.

The final reduction is created from the L0 and L1 spans. Praat cuts those regions directly from the original Sound, keeps them in their original temporal order, optionally aligns edit points to nearby zero crossings, and joins them with short overlaps. The result is a compressed version of the performance that retains the highest-ranked structural regions under the current acoustic model while omitting lower-ranked material.

Complete pipeline

Stage 1 — Acoustic analysis in Praat

Representative-channel policy

For a multichannel source, the script does not average channels to mono. Averaging can cancel anti-phase material and create a misleadingly weak analysis signal. Instead, it measures whole-file RMS for every real channel and selects the strongest-RMS channel for analysis.

This channel is used for:

• Pitch analysis;
• Formant analysis;
• Intensity analysis;
• the temporary WAV used by Python spectral-flux analysis;
• zero-crossing snapping during the final edit.

The final montage itself is still extracted from the original multichannel Sound.

Frame table

At each analysis frame, Praat writes:

The default frame step is 10 ms. The user can set it between 2 and 50 ms.

Temporary WAV

A throwaway copy of the analysis channel is peak-scaled to 0.99 before 16-bit WAV export. This protects the temporary WAV from clipping. It does not alter the Praat Intensity measurements, which were already calculated from the unscaled analysis channel.

Stage 2A — Acoustic onset detection

Onsets are detected in Python from two complementary cues:

Spectral flux

The spectral part uses:

• a Hann analysis window of approximately 43–46 ms across supported sample rates;
• 16 linear frequency bands;
• a default upper analysis frequency of 5 kHz;
• log-band power;
• half-wave rectification independently in each band;
• an L2 combination of positive band changes.

Both spectral flux and the positive intensity derivative are robustly normalized against their own distribution before mixing. This prevents one exceptional transient from compressing every other event toward zero.

Adaptive threshold

The default detector does not use one flat global threshold. After optional moving-average smoothing, a candidate peak must clear a local median floor by the chosen onset margin:

This is why the same engine can be tuned differently for a plucked attack, a bowed note change, speech, or a continuous texture.

Peak picking

An accepted onset must:

• clear the adaptive threshold;
• be a local maximum;
• respect the minimum inter-onset interval (minimum IOI).

The first frame always anchors the beginning of the first segment.

Stage 2B — GPR-style grouping

Every accepted onset initially creates a raw segment. The engine then evaluates the boundary between each pair of consecutive segments using four relative cues:

Each cue is min–max normalized within the current file, then the selected Grouping style supplies the weights.

Weak-boundary merging is a quantile

Merge weakest fraction is not an absolute strength threshold. A value of 0.50 means:

The engine resolves that requested fraction to the corresponding boundary-strength cut. This makes the control meaningful even when one recording has boundary strengths centered around 0.15 and another around 0.35.

If all boundary strengths are identical, the engine keeps them rather than inventing a distinction that is not present in the evidence.

Stage 2C — pTSR-style structural head scoring

After weak boundaries have been merged, each surviving group receives a structural head score.

The combined score is then renormalized to 0…1 within the current set of groups.

Why dynamic programming?

The engine does not simply take the highest scores. It selects a well-spaced structural backbone. A weighted one-dimensional dynamic program maximizes total selected score while enforcing a minimum time gap between chosen group starts.

A second dynamic-programming pass selects Primary Anchors inside that head backbone, so every L0 Anchor originates from a group that already qualified for the structural head pool.

The L0–L3 hierarchy

The final montage keeps L0 + L1. L2 and L3 remain visible in the analysis hierarchy but do not enter the EDL used for audio splicing.

Stage 3 — Building the Skeleton Montage

The Python engine writes an edit decision list containing the original-time spans classified as L0 or L1. Praat then cuts those exact regions from the original Sound.

Zero-crossing snapping

When enabled, each cut boundary is moved to the nearest zero crossing only if that crossing lies within a small window. The default window is 5 ms. On multichannel material, the crossing is measured on the same strongest-RMS channel used for the acoustic analysis.

Crossfade

Retained chunks are concatenated in their original temporal order. The default overlap is 10 ms. Requested overlaps at or below 0.5 ms are treated as no overlap and use ordinary concatenation.

If the requested crossfade is too long for the shortest retained chunk, Praat automatically clamps it to 45% of that chunk rather than allowing the overlap to swallow the segment.

What is preserved?

• original sample rate;
• original number of channels;
• original samples inside every retained span;
• original ordering of retained material;
• original level relationships, apart from the overlap region itself.

There is no pitch shifting, time stretching, spectral reconstruction, or final peak normalization in the montage stage.

Retention target

Target retention controls the desired fraction of the original duration represented by the structural head pool before crossfading.

The retention budget is applied before Stage 3 edits. The finished montage can differ slightly from that pre-splice duration: zero-crossing snapping can move each cut by up to 5 ms, and adjacent chunks shorten the combined timeline by the overlap used for crossfading.

Input material presets

The material preset answers one practical question: what does an event boundary look like acoustically in this recording? It changes onset detection and supplies a default weak-boundary merge fraction. Grouping style, Structural style, Reduction density, and pitch range remain independent.

Grouping and structural styles

Grouping style — GPR cue weights

Structural style — pTSR head-score weights

Reduction density

Reduction density controls the target proportions of structural levels and the minimum spacing between selected heads.

These are targets and selection constraints, not promises that every recording will produce exactly those proportions. The actual result depends on the number, duration, spacing, and scores of the groups found in that file.

Parameter reference

Outputs and intermediate artifacts

Primary output

This is the actual deliverable: retained original-audio spans in source order, joined with the requested overlap.

Optional TextGrid

The TextGrid refers to the original Sound timeline, not the montage timeline.

Intermediate files

• acoustic_features.csv — per-frame acoustic measurements plus onset columns written back by Python;
• gttm_output.TextGrid — hierarchy on the original timeline;
• splicing_edl.csv — L0/L1 source spans used to build the montage;
• pgttm_trace.csv — decimated onset trace for the figure;
• pgttm_segments.csv — raw boundaries, grouping decisions, level and score for the figure;
• temp_pgttm_analysis.wav — temporary analysis-channel WAV.

By default the CSV, TextGrid, EDL, and figure tables are scratch and are deleted after a successful run once the Sound, optional imported TextGrid, and figure have been created. Keep intermediate files moves those artifacts to the working directory and leaves them there. The temporary analysis WAV is separate: it remains in the temporary directory and is preserved after the Python stage only when Debug is enabled. Failed runs leave diagnostic artifacts in place where possible.

Analysis visualization

The figure deliberately separates the control domain from the audio that was actually produced.

I — Onset Detection Function

Shows the mixed spectral-flux / dB-rise onset function, the adaptive local-median-plus-margin threshold curve, and the accepted onset positions.

II — GPR Boundary Strength

One stem per raw boundary. The resolved quantile cut is drawn explicitly, and the display distinguishes boundaries that survive from boundaries absorbed by merging.

III — pTSR Head-Score Field

Plots merged-group duration on a logarithmic X axis against head score on Y. Point color/size indicates the final L0–L3 class.

IV — Reduction Map

The upper band shows every merged group in its structural class. The lower band shows only L0/L1 material — exactly the material passed to the EDL and therefore eligible for the montage.

V — The Montage Itself

A measured spectrogram of the finished output Sound. Vertical marks show montage splice locations rather than source-time boundaries.

QC strip

The summary reports detector settings, onset count, resolved merge cut, group count, L0–L3 counts, retained duration, crossfade, final peak, and RMS.

Why the pipeline remains practical on long files

The implementation is deliberately split between Praat and Python according to the operations each handles efficiently.

• Praat handles: Pitch, Formant, Intensity, object orchestration, Sound extraction, zero-crossing queries, and montage construction.
• NumPy handles: spectral analysis and onset DSP that would otherwise require hundreds of thousands of individual Praat spectrum queries.

Several design choices specifically avoid length-dependent bottlenecks:

• the feature CSV is streamed in buffered blocks rather than storing every frame in thousands of indexed Praat variables;
• spectral flux uses chunked FFT processing;
• the local-median threshold is calculated in chunks;
• the dynamic-programming predecessor search uses searchsorted rather than a backward scan;
• visualization data is decimated to approximately 1200 onset-trace points instead of making Praat query the complete frame table;
• max-pooling preserves onset peaks when that figure trace is reduced.

Interpretive limits

• Not a full parse: no complete GTTM rule hierarchy or competing parses are evaluated.
• Acoustic proxies: pitch, formant, intensity, and spectral-change measurements stand in for structural evidence; their reliability depends on the material.
• Representative channel: multichannel analysis is based on one strongest-RMS channel even though the output montage preserves all channels.
• Pitch dependence: unvoiced/percussive groups do not receive artificial “perfect pitch stability”; their pitch-stability contribution is zero.
• Formants as timbre proxy: F1/F2 change is treated as one acoustic cue, not as a complete model of timbre.
• Relative L2/L3 labels: “Ornament” and “Artifact / Noise” are structural-ranking names, not semantic ground truth.
• Retention target can overshoot: at least one head is always kept.
• Splice aesthetics are separate from analysis: zero-crossing snapping and crossfade modify edit boundaries slightly after the grammar has already made its structural decision.

Recommended way to use it

1. Choose the material preset that best describes how boundaries manifest in the recording.
2. Set a realistic Pitch floor/ceiling for the source.
3. Begin with Balanced Grouping, Balanced Structural style, Balanced Reduction density, and Target retention around .45.
4. Inspect Panels I–IV before judging the audio. They show why material was kept or removed.
5. If too few genuine onsets are detected, adjust the material type or Custom onset settings.
6. If the montage is too close to the source, reduce Target retention and/or merge a smaller fraction of boundaries so the reducer has more groups to choose from.
7. If the result is too fragmented, increase weak-boundary merging or use Sparse density.
8. Use the imported TextGrid when you need to inspect the hierarchy on the source timeline.