Auto-Harmonic Layering — User Guide
Detects recurring pitched regions, chooses two harmony intervals for each selected region, resynthesizes those voices with Praat pitch-tier manipulation, and mixes them with the original as a stereo result.
What this does
Auto-Harmonic Layering analyzes the selected Sound for recurring pitch trajectories. It builds a pitch self-similarity matrix, searches diagonal runs that indicate a later region with a similar frame-by-frame pitch contour, ranks the candidates, and keeps the strongest non-overlapping regions up to Num_loops_to_find.
Each selected region is then assigned two harmony intervals. The assignment can be Pitch-Aware, where the intervals depend on the preset and the region's average pitch, or Fixed Chord Type, where the same interval structure is used for every selected region. The two harmony voices are pitch-shifted with Praat Manipulation/PitchTier resynthesis and placed into a stereo wet layer.
The recurrence detector uses a later matching pitch trajectory as evidence that a region recurs. The regions passed to the harmonizer are the selected candidate regions themselves; the later matching positions are used by detection and are not automatically expanded into a separate list of all repeats.
Quick start
- Select exactly one Sound object in Praat. The script accepts mono or stereo input.
- Run
Auto-Harmonic_Layering.praat. - Choose a Preset. The preset controls hidden pitch-analysis, recurrence-tolerance, stereo-spread, fade, diatonic, and voice-leading settings.
- Set
Num_loops_to_findandMin_loop_duration. - Choose
Harmony_style: Pitch-Aware or Fixed Chord Type. - If using Fixed Chord Type, choose
Fixed_chord_if_used. - Set the linear
Dry_levelandWet_levelgains. - Choose whether to draw the visualization and play the result.
Processing workflow
1. Pitch analysis and recurrence search
- Stereo input is converted to mono for analysis and harmony synthesis only. The original stereo channels are retained for the dry mix.
- Pitch is analyzed at a fixed 0.05 s time step using the preset's pitch floor and ceiling.
- Unvoiced frames are stored as zero and cannot form matching SSM cells.
- For two voiced frames with pitch values f₁ and f₂, the pitch distance is measured in semitones:
similarity = 1 − d / tolerance, when d < tolerance
similarity = 0 otherwise
- A candidate is a diagonal run of positive similarity lasting at least
Min_loop_duration. - The candidate score is the sum of its similarity values, so both match strength and run length contribute to ranking.
- The strongest candidates are considered from highest score downward; overlapping selected regions are rejected.
- There is no separate maximum-loop-duration control in the current interface.
2. Harmony selection
The selected regions are sorted chronologically before harmony generation. Pitch-Aware mode then selects interval pairs according to the preset. Rich and Diatonic estimate a global major/minor key from pitch-class counts; Experimental chooses a random chord type independently for each selected region.
3. Pitch shifting, stereo placement, and mixing
Each selected region is extracted from the mono analysis signal. Two harmony voices are created with Praat Manipulation objects: the PitchTier is multiplied by 2^(interval/12), replaced in the Manipulation, and resynthesized with overlap-add. The resulting harmony segment keeps the source-region duration.
The two voices receive fixed pre-pan gains of 0.75 and 0.60, are placed with constant-power stereo panning, receive preset-dependent linear fade-in/out ramps, and are added at the region's original sample position. Wet_level is applied once after all wet events have been summed.
Presets
Presets are complete internal configurations. The visible controls remain available, but the pitch floor/ceiling, SSM tolerance, stereo spread, fade time, diatonic switch, and voice-leading switch come from the selected preset.
| Preset | Pitch range | SSM tolerance | Stereo spread | Fade | Diatonic key use | Voice leading |
|---|---|---|---|---|---|---|
| Subtle | 75–600 Hz | 0.45 st | 0.35 | 35 ms | No | Yes |
| Rich | 75–600 Hz | 0.75 st | 0.70 | 50 ms | Yes | Yes |
| Bold | 60–700 Hz | 1.00 st | 0.90 | 20 ms | No | No |
| Diatonic | 75–600 Hz | 0.60 st | 0.60 | 60 ms | Yes | Yes |
| Experimental | 50–800 Hz | 1.25 st | 0.80 | 15 ms | No | No |
| Custom | 75–600 Hz | 0.75 st | 0.70 | 30 ms | No | Yes |
Harmony selection
Fixed Chord Type
When Harmony_style = Fixed Chord Type, the fixed chord selection takes precedence over the preset's Pitch-Aware chord logic. The preset still controls recurrence analysis, fade, stereo spread, and voice leading.
| Fixed chord | Voice 2 | Voice 3 |
|---|---|---|
| Octaves | +12 st | +24 st |
| Fifths | +7 st | +12 st |
| Major | +4 st | +7 st |
| Minor | +3 st | +7 st |
| Sus4 | +5 st | +7 st |
Pitch-Aware: Subtle and Custom
| Region mean pitch | Assigned intervals | Label |
|---|---|---|
| < 150 Hz | +7, +12 st | 5th |
| 150 to < 250 Hz | +3, +7 st | Min |
| 250 to < 350 Hz | +4, +7 st | Maj |
| ≥ 350 Hz | +12, +19 st | Oct5 |
Pitch-Aware: Bold
| Region mean pitch | Assigned intervals | Label |
|---|---|---|
| < 180 Hz | +7, +19 st | Open5 |
| 180 to < 320 Hz | +5, +12 st | Open4 |
| ≥ 320 Hz | +12, +19 st | Oct5 |
Pitch-Aware: Rich and Diatonic
The script forms a pitch-class histogram from all voiced pitch frames and compares it with rotated major and minor key profiles. The highest-scoring tonic/mode becomes the estimated global key. For each selected region, Voice 2 is assigned the in-key pitch class nearest a major third above the region pitch, while Voice 3 is assigned the distinct in-key pitch class nearest a perfect fifth.
Pitch-Aware: Experimental
Each selected region independently chooses one of six interval structures with equal integer selection from the script's random generator:
| Type | Intervals |
|---|---|
| Oct | +12, +24 st |
| 5th | +7, +12 st |
| Maj | +4, +7 st |
| Min | +3, +7 st |
| Sus4 | +5, +7 st |
| Dim | +3, +6 st |
There is no random-seed control in the form, so Experimental chord assignments can change between runs.
Voice leading
For presets with voice leading enabled, the chord pitch classes are retained while each harmony interval can be shifted by −12, 0, or +12 semitones. The script chooses the octave placement that minimizes the total motion of the two harmony voices from the previous selected region, while keeping Voice 2 below Voice 3 and avoiding duplicate/unison harmony voices.
Parameters
| Parameter | Default | Meaning |
|---|---|---|
Preset | Subtle | Chooses the internal pitch-analysis, recurrence, stereo, fade, diatonic, and voice-leading configuration. |
Num_loops_to_find | 5 | Maximum number of strongest non-overlapping recurring candidate regions retained for harmonization. |
Min_loop_duration | 0.4 s | Minimum diagonal-run duration and minimum recurrence lag used by the SSM search. |
Harmony_style | Pitch-Aware | Selects preset-dependent pitch-aware harmony or one fixed chord structure for every selected region. |
Fixed_chord_if_used | Major | Used only when Harmony_style = Fixed Chord Type. |
Dry_level | 0.75 | Linear gain applied independently to the original dry left/right channels. |
Wet_level | 0.45 | Linear gain applied to the summed wet harmony buffers after all selected regions have been added. |
Draw_visualization | Yes | Draws original/result waveforms, region map, and processing summary in the Praat Picture window. |
Play_result | Yes | Plays the final stereo Sound after processing. |
Dry_level and Wet_level are direct linear multipliers. The script performs no per-note or final peak normalization, so high gain settings can produce peaks above the source's range.Mixing & channel behavior
Harmony voices
The wet layer contains two generated harmony voices. The original pitch is supplied by the dry signal rather than by a third wet “root” voice.
Before panning, Voice 2 uses a fixed gain of 0.75 and Voice 3 a fixed gain of 0.60. The preset's stereo-spread value controls constant-power panning:
Voice 3 angle = (1 + spread) · π/4
L = cos(angle), R = sin(angle)
At spread 0 both voices are centered with equal-power left/right coefficients. At spread 1 Voice 2 is hard left and Voice 3 hard right.
Fades
Each wet harmony segment receives a linear fade-in and fade-out. The effective fade is:
This creates a trapezoidal envelope when the segment is longer than twice the fade duration; very short regions can become triangular.
Mono input
The mono source is copied to both dry output channels. The stereo wet harmony layer is then added to those two copies, producing a stereo result.
Stereo input
The original left and right channels remain the dry signal. A mono downmix is used only for pitch analysis and harmony resynthesis; the generated stereo wet layer is added to the preserved dry left/right channels.
Visualization
When Draw_visualization is enabled, the script draws four areas:
- Original waveform — the selected source Sound.
- Harmonized waveform — the final stereo result.
- Loop map with chord labels — each selected region is shown as a blue time rectangle labeled with region index, chord label, and average pitch in Hz.
- Summary strip — preset, requested/found regions, number harmonized, harmony mode, voice-leading state, Dry/Wet values, stereo spread, fade, pitch-analysis range, SSM tolerance, output name, duration, RMS values, and sample rate.
Output
| Property | Behavior |
|---|---|
| Object name | <source>_harmonized_<Preset> |
| Channels | Always stereo. |
| Duration | Matches the original Sound. |
| Sample rate | Matches the original Sound. |
| Dry stereo image | Preserved for stereo input; duplicated to L/R for mono input. |
| Wet content | Two pitch-shifted mono-derived harmony voices distributed in stereo. |
| Normalization | None. Dry/Wet remain direct linear gains. |
| Temporary objects | Analysis, SSM, manipulation, and intermediate wet/dry objects are removed; the final Sound remains selected. |
Further reading
- 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, 17, 97–110. Relevant to Praat's autocorrelation-based pitch analysis.
- Müller, M. (2015). Fundamentals of Music Processing: Audio, Analysis, Algorithms, Applications. Springer. See the material on music structure analysis and self-similarity representations.
- Praat Manual: Manipulation and overlap-add. These document the PitchTier-based resynthesis path used for the two generated harmony voices.