Microtonal Harmonic Field Engine — User Guide
Analysis-driven microtonal harmonisation that derives phrase anchors from the source, blends two interval fields, applies phrase-level pitch behaviours, and builds stereo companion voices by resampling source phrases.
What this does
Microtonal Harmonic Field Engine analyses one selected Sound, detects stable, unstable, and noisy/unvoiced regions, groups active regions into phrases, derives one harmonic anchor per phrase, and creates up to five companion voices from two selectable interval fields.
Each companion voice is generated from the source phrase itself. The engine computes one phrase-level target, converts it to a playback-rate factor, extracts source material, changes its effective sampling rate, resamples it back to the source sample rate, fades the phrase, and places it in a full-length voice buffer. The process therefore transposes the complete phrase spectrum, including breath and noise inside the phrase, rather than synthesising a new oscillator or re-tracking the shifted result.
The harmony is phrase-based and source-derived. The engine does not impose a score or quantise the original melody to one tuning system. The selected fields provide companion intervals relative to each phrase anchor.
Quick start
- Select exactly one Sound object.
- Run
Microtonal_Harmonic_Field_Engine.praat. - Choose one of the seven engine presets or Custom.
- For Custom, select Field_A, Field_B, the number of voices, and the primary pitch behavior.
- Set the dry/companion levels, phrase placement, optional time correction, stereo spread, and output peak ceiling.
- Choose whether to draw the visualization and play the result.
- Click OK. The result is created as
<source>_MHFE_result.
Presets
The menu contains seven presets plus Custom. Presets override the active tuning fields, behavior, and some behavior parameters. They may also force or cap the voice count. Companion_level, Original_level, Placement_mode, Time_correction, Stereo_spread, Output_peak, Visualize, and Play_result remain as set in the form.
| Preset | Field A / B | Behavior | Voice handling | Behavior detail |
|---|---|---|---|---|
| Just Bloom | Just / Harmonic Series | Lean | Up to 4 | Lean strength 0.78 |
| Septimal Shadow | Septimal / 12-TET | Lean | Exactly 2 | Lean strength 0.65 |
| Wolf Corridor | Pythagorean / Pythagorean | Drift | Up to 3 | Drift time constant 1.2 s |
| Harmonic Gravity | Harmonic Series / Harmonic Series | Lean | Up to 4 | Lean strength 0.82 |
| Temperament Collapse | 31-TET / 12-TET | Lean | Exactly 2 | Default lean strength 0.70 |
| Dual Root Conflict | Just / Pythagorean | Oscillate | Up to 2 | 2.5 Hz, 15 cents |
| Comma Drift | Just / Just | Drift | Up to 3 | Drift time constant 1.5 s |
| Custom | Uses form selections | Uses form selection | 1–5 | Uses fixed engine defaults for Lean/Drift/Oscillate/Smear internals |
Field-mix motion
The effective interval for each voice is a phrase-by-phrase blend of Field A and Field B. The blend strategy depends on the preset. Just Bloom gradually moves toward Field B and also responds to instability; Septimal Shadow responds mainly to instability; Temperament Collapse moves from A to B across the piece; Dual Root Conflict oscillates between fields; Comma Drift stays on Field A. Other cases use accumulated comma and phrase instability to influence the blend.
Analysis, zones, phrases, and anchors
Analysis is performed on the mono working copy with a fixed 10 ms step:
- Pitch: 60–800 Hz.
- Harmonicity: Praat
To Harmonicity (cc). - Intensity: Praat Intensity in dB SPL.
Zone classification
For each frame, a stability weight is derived from HNR:
PitchStrength = clamp((HNR - 5) / 25, 0, 1)
VoicingWeight = 0.5 × PitchStrength + 0.5 × HNRnorm
- S — Stable: defined F0, intensity ≥ 40 dB SPL, and
VoicingWeight ≥ 0.60. - U — Unstable: defined F0 and intensity ≥ 40 dB SPL, but below the stability threshold.
- N — Noisy/Unvoiced: undefined F0 or intensity below 40 dB SPL.
A single isolated frame whose zone differs from both neighbours is reassigned to the preceding zone before phrase detection.
Phrase detection
A phrase begins when the engine enters an S or U region. A run of N frames lasting at least 0.18 s closes the current phrase. Up to 200 phrases are retained. Short N regions inside a phrase can therefore remain part of the extracted source material.
Phrase anchor
The anchor is calculated in cents. The engine first uses Stable frames only, weighted by the HNR-derived voicing weight. Only if a phrase contains no usable Stable frames does it use Unstable frames at half weight. If neither pass succeeds, the first voiced frame is used as a last resort.
Anchors also have phrase-to-phrase memory. With the default memory weight of 0.35, ordinary changes are blended with the preceding anchor; changes larger than 60 cents receive much less memory.
Comma and wolf events
For each phrase transition, the anchor step is octave-reduced and compared with the nearest perfect fifth (701.96 cents) or fourth (498.04 cents, including signed equivalents). Only steps within 120 cents of one of those references contribute to the accumulated comma.
A phrase is marked as a wolf phrase whenever |comma| ≥ 38 cents. A wolf event is counted only when the trajectory crosses into that threshold region. Voice 2 is the designated wolf voice when two or more voices exist; otherwise voice 1 is used.
Interval fields and pitch behaviors
Built-in interval tables
| System | Voice 1 | Voice 2 | Voice 3 | Voice 4 | Voice 5 |
|---|---|---|---|---|---|
| 12-TET | 700.00 | 400.00 | 300.00 | 500.00 | 200.00 |
| Just Intonation | 701.96 | 386.31 | 315.64 | 498.04 | 203.91 |
| Pythagorean | 701.96 | 407.82 | 294.13 | 498.04 | 203.91 |
| 19-TET | 694.74 | 378.95 | 315.79 | 505.26 | 189.47 |
| 31-TET | 696.77 | 387.10 | 309.68 | 503.23 | 193.55 |
| Harmonic Series | 701.96 | 386.31 | 968.83 | 203.91 | 1088.27 |
| Septimal 7-limit | 968.83 | 266.87 | 582.51 | 435.08 | 231.17 |
User-Defined uses the fixed script string 0, 150, 350, 702, 968 by default, assigned to voices 1–5. If fewer values are parsed, missing higher voices fall back to 701.96 cents.
Behaviors
| Behavior | Current implementation |
|---|---|
| Snap | Uses the raw field target for the phrase. |
| Lean | Interpolates in cents from the phrase anchor toward the field target. |
| Drift | Persistent one-pole approach toward the target; state carries from phrase to phrase for each voice. |
| Oscillate | Adds a persistent sinusoidal cents offset around the target; phase carries across phrases. |
| Smear | Persistent phrase-to-phrase smoother. The blend toward the smoothed target increases with the proportion of Unstable frames in the phrase. |
| Refuse | Adds 21.5 cents to the field target. |
The behavior operates on the phrase anchor and phrase-level field target. The resulting target determines one playback-rate factor for that voice and phrase. The source phrase's internal pitch and spectral motion are carried along by the resampling.
On a wolf phrase, the designated wolf voice receives an additional pitch offset of (comma / 38) × 5 cents before its behavior is applied. Its phrase layer is also multiplied by the fixed wolf emphasis factor 1.4.
Companion-voice generation
- For each voice and phrase, read the interval from both fields and blend them with the current field-mix value.
- Apply the phrase-specific wolf offset when appropriate.
- Apply the selected pitch behavior and store the resulting phrase target.
- Convert target/anchor frequency to a playback-speed factor, limited to 0.25–3.0.
- Extract enough source material that playback-rate pitch shifting produces approximately the phrase duration. If the source runs short, pad the request with silence.
- Override the segment sampling frequency and resample back to the source sampling rate using precision 50.
- Optionally correct duration, apply short raised-cosine fades, and place the segment into the voice timeline.
- Accumulate all phrase layers for that voice.
Placement modes
- Align start: place the generated phrase at the source phrase start.
- Align centre: align the generated segment centre to the source phrase centre.
- Stretch to fit: perform an additional sampling-rate/resample duration correction so the segment fits the phrase duration before placement.
Time correction
- None: no additional PSOLA duration correction.
- Snap to phrase: use a DurationTier only when the residual duration difference is at least 20 ms.
- Elastic (PSOLA): use a DurationTier whenever a duration correction is required.
Each phrase receives an edge fade of up to 15 ms, limited to one quarter of the generated segment duration.
Parameters
Form fields
| Parameter | Default | Meaning |
|---|---|---|
| Preset_mode | Just Bloom | Seven presets plus Custom. |
| Field_A | Just Intonation | Used directly when Preset_mode = Custom. |
| Field_B | Pythagorean | Used directly when Preset_mode = Custom. |
| N_voices | 2 | Requested companion voices; internally limited to 1–5 and may be capped or forced by a preset. |
| Companion_level | 0.55 | Linear gain applied to companion layers before stereo panning. |
| Original_level | 0.80 | Linear dry level before centre placement. |
| Primary_behavior | Lean | Used directly when Preset_mode = Custom. |
| Placement_mode | Align start | Align start, align centre, or stretch to fit. |
| Time_correction | None | None, Snap to phrase, or Elastic (PSOLA). |
| Stereo_spread | 0.8 | 0 = all companion voices centred; 1 = full left-to-right distribution. |
| Output_peak | 0.92 | Peak ceiling used only when the final result exceeds this value. |
| Visualize | Yes | Draw the three-panel Picture summary. |
| Play_result | Yes | Play the final result. |
Fixed engine defaults
The current script keeps the following settings outside the form: 10 ms analysis step; 60–800 Hz pitch range; 40 dB SPL silence floor; 0.60 stability threshold; anchor memory 0.35; 60-cent anchor inertia boundary; Lean 0.70; Drift 0.80 s; Oscillate 3.5 Hz / 10 cents; Smear window 0.12 s; unstable-smear amount 0.65; wolf threshold 38 cents; wolf gain 1.4; 15 ms fades; speed-factor limits 0.25–3.0.
Output behavior
- Name:
<source>_MHFE_result. - Channels: always stereo.
- Spatial image: rebuilt from mono. The dry source is centred at constant-power gains
Original_level × 0.707per channel. Companion voices are spread evenly from-Stereo_spreadto+Stereo_spreadwith a constant-power pan law. - Duration: same overall duration as the selected source.
- Time domain: processing is internally zero-based, so a source with non-zero xmin is returned on a 0…duration timeline rather than preserving its absolute xmin.
- Sample rate: source sampling frequency.
- Peak handling: if the final absolute peak exceeds Output_peak,
Scale peakattenuates it to that value. Quieter output is not boosted. This is an attenuate-only peak safety, not target normalization.
Visualization
When Visualize is enabled, the Picture window shows three data panels plus a summary strip.
Zone map
Frames are painted Stable (green), Unstable (orange), or Noisy/Unvoiced (grey). Dotted vertical lines mark detected phrase starts.
Pitch panel
The grey curve is the analyzed source F0. Dotted blue horizontal lines are phrase anchors. Each coloured voice curve now uses the stored voice_target_hz values that were actually produced by the synthesis calculation, including field blending, wolf offset, and the selected behavior. The plotted companion target is phrase-level; it is not a re-analysis of the resampled audio.
Comma panel
The red trajectory shows accumulated phrase comma. Dotted horizontal references mark 0 and ±38 cents. The vertical range is based on the true peak absolute comma over the run, so earlier excursions remain visible even if the final comma later returns toward zero.
Summary strip
The footer identifies the visualization as Zone map • microtonal target voices • comma trajectory. Run parameters, phrase counts, zone percentages, peak comma, wolf-event count, phrase truncation status, and peak-safety status are reported in the Info window.