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.
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.
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.
Quick start
HierarchicalRecomposition.praat through Praat AudioTools (or use Praat’s Run script… command if running the script directly).source_hnr_HiddenSonata. The Info window shows the structure, the effective parameters and the operation counts.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.
| Preset | Compositional behaviour | Useful controls to explore | Default length |
|---|---|---|---|
| Latent Counterpoint | Two 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 Spiral | Earlier 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 Litany | The 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 Braiding | Three 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 Refrain | The 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 Architecture | Selected 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 Choir | The 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 Sonata | An 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 |
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.
| Control | Custom default | Range | Effect |
|---|---|---|---|
| Target duration | 1.0 | 0.1–5.0 | Output length as a multiple of the source. For example, 1.5 makes a result 50% longer. |
| Phrase coherence | 0.5 | 0–1 | Controls grouping by acoustic similarity. Lower values generally make larger, more heterogeneous phrases; higher values favour smaller, more homogeneous phrases. |
| Fragmentation | 0.3 | 0–1 | Controls use and size of slices or grains. Its precise role depends on the preset. |
| Memory strength | 0.5 | 0–1 | Controls returns to earlier material, recall depth, imitation or the degree of thematic restatement, depending on the preset. |
| Repetition | 0.5 | 0–1 | Changes repetitions, cycles or the persistence of material, depending on the preset. |
| Overlap amount | 0.3 | 0–1 | Shapes the spacing and overlap of entries, or rests between fragments in some presets. |
| Formal surprise | 0.2 | 0–1 | Controls 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 amount | 0.0 | 0–1 | Global 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 seed | 42 | integer | Reproduces the seeded plan and scheduling choices when the source, settings, installed model path and runtime remain the same. |
| Stretch mode | Resample | two options | Choose whether extra duration also changes pitch or uses pitch-preserving processing. |
| Edit preset values | On | On / Off | Opens an editable preset-specific parameter dialog. |
| Draw visualization | On | On / Off | Draws the diagnostic process map in Praat Picture. |
| Play result | On | On / Off | Plays 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:
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.
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 dimension | Interpretation | Plan dimension | Interpretation |
|---|---|---|---|
repetition | Restate material | fragmentation | Extract shorter pieces |
overlap | Allow concurrent events | stretch | Local time expansion |
foreground | Prominence / gain | memory | Return to earlier material |
contrast | Seek a contrasting relation | inversion | Temporal reversal |
density_up | Add local layers | density_down | Thin local activity |
braid | Interleave another strand | call_response | Generate an answering phrase |
collapse | Break or reduce density | restatement | Bring back a previous phrase |
surprise | Disrupt established order | formal_weight | Influence 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.
| Area | What it shows | How to use it |
|---|---|---|
| Source and segmentation | Input waveform, event onsets, and event / phrase / section spans. | See which portions of the original were treated as structural units. |
| Plan matrix | Phrase rows × sixteen planning dimensions, shaded by value. | Check whether the generated plan changes from one phrase to another. |
| Operation lanes | Placed, repeated, fragmented, recalled, braided, echoed and reversed material on the output timeline. | Read the constructed form and its overlapping or repeated actions. |
| Form parts | Named formal spans, where the planner defines them. | See sonata sections, litany cells, braid phases or a final collapse; empty declared spans are reported. |
| Stereo field | Pan positions of rendered operations, where spatialization is present. | See how strands or echoes are distributed between left and right. |
| Source map | Where each operation actually reads its material from in the original, including slice offsets and reversed orientation. | Understand jumps, recalls and source transformations. |
| Result and summary | Output 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.
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
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.
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.
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.
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.
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.
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.