Praat AudioTools / User Guide

Hierarchical Neural Recomposition

Transform a sound recording into a new musical structure. The engine listens analytically to the source, groups its events into phrases and larger sections, and recomposes the material using eight distinct formal strategies.

Author: Shai Cohen Department: Music, Bar-Ilan University, Israel Engine: 1.10 (2026) License: MIT Praat AudioTools on GitHub

What it does

Hierarchical Neural Recomposition is an offline analysis-and-resynthesis tool. It takes a selected Praat Sound, detects audio events, groups them into phrases and sections, then selects and rearranges material from the recording. Rather than applying one continuous effect to the whole file, it constructs a new timeline out of event statements, slices, returns, echoes, overlapping strands and other compositional operations.

1. EventsOnsets and audio segments with measured acoustic characteristics.
2. Phrases and sectionsGroups of adjacent events; larger boundaries suggested by acoustic novelty.
3. RecompositionA source-conditioned plan, interpreted by the chosen formal planner and rendered as audio.

The result is a new Sound object in Praat, with an optional process visualization showing how the material was analysed and recomposed. The original Sound remains available.

What “neural” means here. The PyTorch network is randomly initialized and seeded; it does not load trained weights, train on your recording, or learn a musical grammar. Acoustic descriptors provide most of the source-dependent plan, while the untrained network supplies structured generative variation. The tool is therefore best understood as a descriptor-guided generative recomposition system with an untrained neural component.

Quick start

1
Select exactly one Sound object in Praat. A mono or multichannel recording can be used; the engine builds a phase-aware mono working source before recomposing it.
2
Run HierarchicalRecomposition.praat through Praat AudioTools (or use Praat’s Run script… command if running the script directly).
3
Choose Custom or one of the eight presets. With Edit preset values checked, choosing a preset opens a second dialog containing its actual parameter values. You can adjust those values before selecting Render.
4
Choose a Stretch mode and Stretch amount, and set the random seed if needed. Enable Draw visualization to inspect the process; Play result plays the finished Sound after import.
5
Render. Praat exports a temporary WAV, the Python engine analyses and resynthesizes it, and Praat imports the result under a name such as source_hnr_HiddenSonata. The Info window shows the structure, the effective parameters and the operation counts.
Practical starting point: Try Fragmented Litany for an unmistakable transformation of sound into short repeated cells, Formal Braiding for spatially differentiated strands, or Memory Spiral for returns and temporal displacement.

The eight presets

Each preset is a different scheduling strategy, not merely a stored collection of effect settings. Presets also supply default values; with preset editing enabled you may change those values without abandoning the preset’s structural logic.

PresetCompositional behaviourUseful controls to exploreDefault length
Latent CounterpointTwo continuing voice streams are formed from acoustically similar phrase clusters. They have different pan positions and staggered entries; material can be imitated or fragmented between voices.Phrase coherence, Memory, Fragmentation, Repetition, Overlap×1.2
Memory SpiralEarlier phrases return at changing look-back distances. Recall is folded into later events rather than simply looping the source.Memory, Repetition, Overlap×1.5
Fragmented LitanyThe sound is cut into cells of short event slices, repeated with gradual changes of order and length. Earlier cells may return in their mutated state.Fragmentation, Repetition, Memory, Surprise, Overlap×1.3
Formal BraidingThree heuristic sound families (attack-like, sustained and noisy) occupy different stereo strands. The texture alternates between simultaneous braiding and more exposed solo phases.Contrast, Memory, Fragmentation, Overlap×1.1
Collapsing RefrainThe opening phrase becomes a recurring refrain. Its returns are progressively shortened, attenuated and filtered; a dedicated final passage contains only dissolving refrain residues.Memory, Repetition, Fragmentation×1.4
Echo ArchitectureSelected events produce decaying echoes along the phrase’s own inter-onset pattern. Echo generations alternate across the stereo field.Overlap, Contrast, Memory×1.6
Recursive Speech ChoirThe source is treated as an utterance-like succession of events and recomposed as several offset, differently panned voices; no speech recognition or singing synthesis is performed.Overlap, Memory, Repetition×1.0
Hidden SonataAn acoustically contrasting A/B pair is arranged into exposition, fragmentary development and transformed recapitulation. These are sonata-inspired time windows, not a tonal sonata analysis.Contrast, Memory, Fragmentation, Surprise×1.8
These are compositional interpretations, not recognition systems. “Counterpoint” refers to independent timelines and imitation, not tonal voice leading; “choir” is a multi-voice redistribution of recorded material, not vocal synthesis; “sonata” refers to an imposed A/B, development and return outline based on acoustic contrast.

Custom uses the shared phrase-by-phrase scheduler rather than one of these dedicated preset forms. It is useful for exploring how the general controls affect event ordering, recall, fragmentation, layering and surprise.

Parameters and preset editing

The main dialog displays Custom defaults. When you select a named preset, its own default parameters are used instead. If Edit preset values is checked, Praat opens a pre-filled dialog with eight editable settings, including Section contrast, which is not visible among the Custom controls. If editing is unchecked, the stored preset values are applied unchanged.

ControlCustom defaultRangeEffect
Target duration1.00.1–5.0Output length as a multiple of the source. For example, 1.5 makes a result 50% longer.
Phrase coherence0.50–1Controls grouping by acoustic similarity. Lower values generally make larger, more heterogeneous phrases; higher values favour smaller, more homogeneous phrases.
Fragmentation0.30–1Controls use and size of slices or grains. Its precise role depends on the preset.
Memory strength0.50–1Controls returns to earlier material, recall depth, imitation or the degree of thematic restatement, depending on the preset.
Repetition0.50–1Changes repetitions, cycles or the persistence of material, depending on the preset.
Overlap amount0.30–1Shapes the spacing and overlap of entries, or rests between fragments in some presets.
Formal surprise0.20–1Controls preset-specific variation, such as changes of order, slice reversal or irregular spacing. The same numeric setting has different musical consequences in different presets.
Stretch amount0.00–1Global time expansion: 0 means no extra stretch; 1 multiplies normal operation duration by up to 2. The plan can also introduce its own local stretching.
Random seed42integerReproduces the seeded plan and scheduling choices when the source, settings, installed model path and runtime remain the same.
Stretch modeResampletwo optionsChoose whether extra duration also changes pitch or uses pitch-preserving processing.
Edit preset valuesOnOn / OffOpens an editable preset-specific parameter dialog.
Draw visualizationOnOn / OffDraws the diagnostic process map in Praat Picture.
Play resultOnOn / OffPlays the output after rendering.

Section contrast is available in the preset edit dialog (0–1). It has context-dependent roles, including theme contrast and development overlays in Hidden Sonata, spacing between voices in Latent Counterpoint, the stereo width of Formal Braiding and echo width in Echo Architecture. In Custom the internal value is fixed at 0.5.

Important: There are no active Density or Source_trace controls in the Praat form. Both names remain only as unused positional placeholders in the Python command-line interface for compatibility. Do not use them to adjust the sound.

Time stretch and pitch

Stretch amount controls the amount of overall event expansion. At 0, there is no additional global stretching, although individual operations may still be stretched by the compositional plan. At 1, the global factor is ×2. The selected mode determines how stretching sounds:

Resample (pitch follows)

Extending an event also lowers its pitch, like slowing a tape. It changes both duration and pitch and can be used as a compositional colour.

Preserve pitch (phase vocoder)

Uses phase-locked spectral resynthesis with level matching and onset handling to extend duration while aiming to retain pitch and attack definition.

The Info window reports how many rendered operations were actually stretched. When this count is zero, changing Stretch mode alone will not change the sound; increase Stretch amount to engage time stretching.

Pitch preservation is an algorithmic aim, not a guarantee of artifact-free processing. Very short events, noise and sharp attacks may respond differently from sustained tones. Longer stretched events also change the density and timing of the recomposed texture.

How the engine works

1. Event detection. Short-time spectral flux finds candidate onsets. Long gaps are chunked so the source timeline is not discarded. Source channels are folded down with protection against severe phase cancellation.

2. Event description. Each event receives seven features: duration, RMS, normalized spectral centroid, spectral flatness, harmonicity estimate, onset sharpness and log-RMS.

3. Phrase grouping. Adjacent events are grouped by feature similarity. Phrase coherence controls the grouping threshold.

4. Section boundaries. Differences in timbre across phrase boundaries, wider-context changes and local energy dips contribute to an acoustic novelty score. The strongest peaks define section boundaries. These are algorithmic section estimates, not manually annotated formal divisions.

5. Plan generation. A deterministic descriptor-based plan is blended with a seeded, untrained three-level neural network. The resulting sixteen-dimensional plan is then influenced by the user controls.

6. Formal scheduling and rendering. The chosen preset interprets the plan in its own way and constructs operations. The renderer retrieves the actual source segments, optionally reverses, filters or stretches them, places and overlaps them, then applies one output-level soft limiter.

What the neural hierarchy contributes

With PyTorch installed, the network contains an EventEncoder (7 acoustic values to a 32-dimensional event embedding), a PhraseEncoder (transformer over successive events, producing 64-dimensional phrase embeddings) and a bidirectional-GRU SectionPlanner operating on the aggregated section embeddings. The output is expanded into a sixteen-dimensional plan for each phrase.

The planner uses 20% neural output and 80% acoustic descriptors. On five user-controlled slots (repetition, fragmentation, overlap, memory and contrast), a further mix combines 35% of that plan with 65% of the user setting. These are numerical mixing coefficients, not percentages of the audible result. If PyTorch is unavailable, a seeded NumPy projection-based fallback supplies the generative component instead.

Sixteen compositional dimensions

The plan describes tendencies rather than commands that are guaranteed to trigger on every phrase. A preset can prioritize particular dimensions or use its own direct control mapping.

Plan dimensionInterpretationPlan dimensionInterpretation
repetitionRestate materialfragmentationExtract shorter pieces
overlapAllow concurrent eventsstretchLocal time expansion
foregroundProminence / gainmemoryReturn to earlier material
contrastSeek a contrasting relationinversionTemporal reversal
density_upAdd local layersdensity_downThin local activity
braidInterleave another strandcall_responseGenerate an answering phrase
collapseBreak or reduce densityrestatementBring back a previous phrase
surpriseDisrupt established orderformal_weightInfluence phrase ordering

Reading the process map

When Draw visualization is enabled, Praat Picture displays a diagnostic map of the actual analysis and rendered operation schedule. It is more informative than a simple before-and-after waveform comparison.

AreaWhat it showsHow to use it
Source and segmentationInput waveform, event onsets, and event / phrase / section spans.See which portions of the original were treated as structural units.
Plan matrixPhrase rows × sixteen planning dimensions, shaded by value.Check whether the generated plan changes from one phrase to another.
Operation lanesPlaced, repeated, fragmented, recalled, braided, echoed and reversed material on the output timeline.Read the constructed form and its overlapping or repeated actions.
Form partsNamed formal spans, where the planner defines them.See sonata sections, litany cells, braid phases or a final collapse; empty declared spans are reported.
Stereo fieldPan positions of rendered operations, where spatialization is present.See how strands or echoes are distributed between left and right.
Source mapWhere each operation actually reads its material from in the original, including slice offsets and reversed orientation.Understand jumps, recalls and source transformations.
Result and summaryOutput waveform, durations, operation totals, model path and diagnostics.Review what was rendered rather than what was merely planned.

The time-based displays use a shared seconds axis, so a longer or shorter output is visibly different from the source rather than being rescaled to the same width. On dense material some data are sampled for drawing; counts in the Info window describe the full run.

Understanding the counts: Planned means accepted into the scheduler, Rendered means at least one sample entered the output window, and Audible means the operation’s own peak was within 60 dB of the pre-limiter mix peak. “Audible” is a simple level threshold, not a perceptual test or a guarantee that an operation is distinguishable by ear.

For Hidden Sonata, the Info window also reports each theme window (expoA, expoB, dev, recapA, recapB) and the fraction of its time span covered by its own operations. These measures help inspect formal execution but do not establish thematic coherence or musical success.

Requirements and troubleshooting

Installation and files

Praat calls an external Python engine. Keep HierarchicalRecomposition.praat with your AudioTools installation and make sure hierarchical_recomposition.py is available at the expected plugin location plugin_AudioTools/py/, or in Praat’s default directory when running the script independently.

Python requires numpy, scipy and soundfile. torch is optional. Install required dependencies with:

python -m pip install numpy scipy soundfile

To enable the PyTorch model, install PyTorch separately using the instructions appropriate to your platform and Python environment. Without it, the script can use its NumPy fallback.

Common questions

My preset will not run.

Some forms require detectable variation: Counterpoint needs distinct phrase material, Formal Braiding needs at least three events, and Sonata/Refrain need material that can support their formal divisions. When the input is insufficient, the script reports the reason instead of silently substituting a different form. Try a longer, more varied source or a less formally constrained preset.

The result is very sparse or fragmented.

Reduce Fragmentation or Formal surprise, increase Repetition or Overlap, or choose a preset such as Memory Spiral. Actual results depend strongly on the source’s onsets and acoustic contrasts.

Changing a setting did little.

Controls work through the chosen preset’s scheduling rules and may affect different musical properties. Keep the random seed fixed when comparing settings, and inspect the output and operation lanes. For time stretching, increase Stretch amount if necessary.

Why does the output have stereo channels?

Some presets use spatial separation as part of the form. Counterpoint voices, braided families, echoes and the choir can be placed across stereo. Other recompositions may remain mono. The input is analysed and recomposed from a mono working source.

Why is the model called neural if it is not trained?

The optional neural component is a seeded, randomly initialized generator. The source-dependent part primarily comes from measured acoustic descriptors. No training is performed and no learned model of musical form is claimed.

How can I reproduce a result?

Use the same source, preset, editable values, Stretch mode and amount, seed, and Python environment. The same seed is intended to give repeatable scheduling; rendering differences can still arise across distinct software environments.

Command-line engine

The Python script can be run independently of Praat. It expects an input WAV, an output WAV, a stats file, followed by positional controls:

python hierarchical_recomposition.py input.wav output.wav stats.txt \
  target_duration density coherence contrast memory repetition \
  fragmentation overlap source_trace surprise seed preset_name \
  explicit stretch_mode stretch_amount

The density and source_trace arguments are inactive compatibility placeholders. Use explicit to honor the passed values; preset or omission retains the legacy preset-override behaviour. stretch_mode is resample or preserve; stretch_amount is a number from 0 to 1. These are engine arguments, not extra fields in the Praat form.