Harmonic Tension Sorted Grains — User Guide

What this does

Harmonic Tension Sorted Grains is a granular reordering tool. It draws grain locations randomly from the selected Sound, analyzes each grain as a mono spectral snapshot, derives a set of pitch classes, computes one interval-class score, and then sorts the original-channel-count grains by that score.

The processing chain is:

1. Choose how many random grain samples to draw.
2. Extract a Hanning-windowed mono analysis grain and the matching multichannel render grain.
3. Divide the requested analysis range into logarithmic frequency bands.
4. Take at most one sufficiently strong spectral maximum from each band.
5. Map those maxima to 12-TET pitch classes and remove duplicates.
6. Average fixed interval-class weights over all unique pitch-class pairs.
7. Sort the grains by score and concatenate them, optionally inserting digital-silence gaps.

What “harmonic tension” means here

The score is a compositional pitch-class interval metric. It is not a psychoacoustic roughness model, not a sensory-dissonance calculation, and not a prediction of perceived consonance for arbitrary audio.

The script assigns fixed weights to interval classes:

Quick start

1. Select exactly one Sound object.
2. Run Harmonic_Tension_Sorted_Grains.praat.
3. Choose Custom or one of the eight named presets.
4. Choose Chaos to Clarity for descending score or Clarity to Chaos for ascending score.
5. For Custom, set grain size, sampling density, spectral-band count and analysis range.
6. Set Gap_between_grains_ms to 0 for butt concatenation or a positive value for digital silence between grains.
7. Run the script. The result is named <source>_HTsorted_<preset>.

Grain sampling

How Sampling_overlap works

Sampling_overlap_(0-0.8) controls only the number of random grain draws. It does not create overlap in the final timeline.

The parameter therefore acts like a density control: larger values request more random samples from the source. All named presets use this rule.

Grain duration

With Fixed mode, every grain uses the base duration, limited to the source duration and a minimum of two samples. With Random mode:

The result is then clamped to the legal range from two samples up to the source duration.

Source position

Every grain start is drawn independently and uniformly from the legal source-start range. Sampling_overlap is not a source-hop relation; two consecutive draws can come from anywhere in the source.

Spectral peaks → unique pitch classes

For analysis only, the source is converted to mono. Each random grain is extracted with a Hanning window, converted to a Spectrum, then to Ltas (1-to-1) so the spectral frequency resolution is retained.

Logarithmic analysis bands

The effective upper frequency is:

The range Min_frequency_Hz ... analysisMax is divided into Number_of_peaks non-overlapping logarithmic bands:

Each band contributes at most one local spectral maximum. A candidate is accepted only when its level is no more than Peak_relative_threshold_dB below the strongest maximum anywhere in the full analysis range:

Pitch-class mapping

The frequency is therefore quantized to the nearest 12-TET semitone class. If several bands map to the same pitch class, that class is stored once. The score is computed on a true pitch-class set, not a multiset of repeated detections.

Interval-class tension score

For every unordered pair of unique pitch classes, the pitch-class distance is folded into interval class 0–6:

The grain score is the arithmetic mean of the corresponding IC weights:

Because all weights lie between 0 and 1, the resulting score also lies between 0 and 1.

Sorting & assembly

Sort direction

• Chaos to Clarity: descending score — highest score first.
• Clarity to Chaos: ascending score — lowest score first.

The insertion sort is stable, so grains with equal scores retain their original random-draw order.

Final timeline

The sorted Hanning-windowed grains are copied in the desired order and concatenated once. If Gap_between_grains_ms is positive, a matching-channel digital-silence object is inserted between successive grains.

Eight presets

All named presets set Random grain-size mode. They overwrite grain size/variation, Sampling_overlap, Max_grains, Number_of_peaks, Max_frequency_Hz, sort direction and gap. They do not overwrite Min_frequency_Hz, Peak_relative_threshold_dB, Draw_visualization or Play_result.

Parameters & limits

Visualization

The Picture window shows the transformation and score distribution:

• Original waveform: neutral gray.
• Sorted output waveform: blue, using the same amplitude scale as the input waveform.
• Sorted tension trajectory: absolute 0–1 score axis. Green = score < 0.35, amber = 0.35–0.75, red = ≥ 0.75. The line follows the sorted grain order and a dotted line marks the mean score.
• Distribution: 10-bin histogram using the same three score-class colors.
• Sorted output spectrum: a spectrogram capped at min(5000 Hz, Nyquist).
• Summary: grain count, score range and mean, effective analysis frequency range, and counts in the three score classes.

Output behavior

Normalization and edge fades

After concatenation, every non-silent result is peak-normalized to 0.90 using Sinc70 peak measurement. The script then applies a short raised-cosine fade at both ends:

Because the fades are applied after normalization and there is no second normalization pass, the final peak can end below 0.90 if the previous maximum lies inside an edge fade.

Duration, channels and naming

• Output duration is determined by the sampled grain durations plus explicit gaps, not by the original file duration.
• The original channel count is preserved.
• The original Sound remains unchanged.
• The result is named <source>_HTsorted_<preset name>.
• There is no Random_seed control, so random source positions and Random grain-duration mode can produce a different realization on each run.

Further Reading

• Forte, A. (1973). The Structure of Atonal Music. Yale University Press. Foundational reference for pitch-class sets and interval-class relations. JSTOR.
• Straus, J. N. (2016). Introduction to Post-Tonal Theory, 4th ed. W. W. Norton. A modern introduction to pitch-class set and interval-class analysis. Book record.
• Roads, C. (2002). Microsound. MIT Press. Granular and microsound composition techniques. MIT Press.
• Truax, B. (1994). “Discovering Inner Complexity: Time-Shifting and Transposition with a Real-Time Granulation Technique.” Computer Music Journal, 18(2), 38–48. Author publication list.