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.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 0.4.1 (2026) License: MIT License Repo: GitHub
Contents:

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.

Signal flow: mono analysis/source copy → zones and phrase anchors → field blend + behavior → phrase resampling → fades and placement → stereo voice spread → dry/companion mix → attenuation-only peak safety.

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

  1. Select exactly one Sound object.
  2. Run Microtonal_Harmonic_Field_Engine.praat.
  3. Choose one of the seven engine presets or Custom.
  4. For Custom, select Field_A, Field_B, the number of voices, and the primary pitch behavior.
  5. Set the dry/companion levels, phrase placement, optional time correction, stereo spread, and output peak ceiling.
  6. Choose whether to draw the visualization and play the result.
  7. Click OK. The result is created as <source>_MHFE_result.
Channel behavior: stereo or multichannel input is converted to mono before analysis and phrase generation. The dry source used in the final mix is also this mono working copy. The engine then creates a new stereo image, so the original spatial image is not preserved.

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.

PresetField A / BBehaviorVoice handlingBehavior detail
Just BloomJust / Harmonic SeriesLeanUp to 4Lean strength 0.78
Septimal ShadowSeptimal / 12-TETLeanExactly 2Lean strength 0.65
Wolf CorridorPythagorean / PythagoreanDriftUp to 3Drift time constant 1.2 s
Harmonic GravityHarmonic Series / Harmonic SeriesLeanUp to 4Lean strength 0.82
Temperament Collapse31-TET / 12-TETLeanExactly 2Default lean strength 0.70
Dual Root ConflictJust / PythagoreanOscillateUp to 22.5 Hz, 15 cents
Comma DriftJust / JustDriftUp to 3Drift time constant 1.5 s
CustomUses form selectionsUses form selection1–5Uses 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:

Zone classification

For each frame, a stability weight is derived from HNR:

HNRnorm = clamp(HNR / 30, 0, 1)
PitchStrength = clamp((HNR - 5) / 25, 0, 1)
VoicingWeight = 0.5 × PitchStrength + 0.5 × HNRnorm

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

SystemVoice 1Voice 2Voice 3Voice 4Voice 5
12-TET700.00400.00300.00500.00200.00
Just Intonation701.96386.31315.64498.04203.91
Pythagorean701.96407.82294.13498.04203.91
19-TET694.74378.95315.79505.26189.47
31-TET696.77387.10309.68503.23193.55
Harmonic Series701.96386.31968.83203.911088.27
Septimal 7-limit968.83266.87582.51435.08231.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

BehaviorCurrent implementation
SnapUses the raw field target for the phrase.
LeanInterpolates in cents from the phrase anchor toward the field target.
DriftPersistent one-pole approach toward the target; state carries from phrase to phrase for each voice.
OscillateAdds a persistent sinusoidal cents offset around the target; phase carries across phrases.
SmearPersistent phrase-to-phrase smoother. The blend toward the smoothed target increases with the proportion of Unstable frames in the phrase.
RefuseAdds 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

  1. For each voice and phrase, read the interval from both fields and blend them with the current field-mix value.
  2. Apply the phrase-specific wolf offset when appropriate.
  3. Apply the selected pitch behavior and store the resulting phrase target.
  4. Convert target/anchor frequency to a playback-speed factor, limited to 0.25–3.0.
  5. Extract enough source material that playback-rate pitch shifting produces approximately the phrase duration. If the source runs short, pad the request with silence.
  6. Override the segment sampling frequency and resample back to the source sampling rate using precision 50.
  7. Optionally correct duration, apply short raised-cosine fades, and place the segment into the voice timeline.
  8. Accumulate all phrase layers for that voice.

Placement modes

Time correction

Each phrase receives an edge fade of up to 15 ms, limited to one quarter of the generated segment duration.

Parameters

Form fields

ParameterDefaultMeaning
Preset_modeJust BloomSeven presets plus Custom.
Field_AJust IntonationUsed directly when Preset_mode = Custom.
Field_BPythagoreanUsed directly when Preset_mode = Custom.
N_voices2Requested companion voices; internally limited to 1–5 and may be capped or forced by a preset.
Companion_level0.55Linear gain applied to companion layers before stereo panning.
Original_level0.80Linear dry level before centre placement.
Primary_behaviorLeanUsed directly when Preset_mode = Custom.
Placement_modeAlign startAlign start, align centre, or stretch to fit.
Time_correctionNoneNone, Snap to phrase, or Elastic (PSOLA).
Stereo_spread0.80 = all companion voices centred; 1 = full left-to-right distribution.
Output_peak0.92Peak ceiling used only when the final result exceeds this value.
VisualizeYesDraw the three-panel Picture summary.
Play_resultYesPlay 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

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.