Documentation

Tuning Lattice

Created by Elliot Cole

A visual and playable environment for working with just intonation: tuning design, interval calculation, performance, practice, and page layout in one instrument.

What It Is

Tuning Lattice is a visual and playable environment for working with just intonation. It lets you build tuning systems as ratio networks, hear them immediately, save playable scenes, and turn them into finished diagrams or exported tuning data.

The lattice diagram itself has a long history. Variants appear in Euler's tonnetz and in later just intonation work by composers and theorists including Harry Partch, Ben Johnston, James Tenney, La Monte Young, Terry Riley, Michael Harrison, and Erv Wilson. Tuning Lattice extends that paper-and-pencil tradition into an interactive tool: you can design lattices in 2D or 3D, assign prime factors to axes, work beyond three dimensions with custom nodes, and move fluidly between analysis, performance, and layout.

At its core, the app treats every node as a frequency ratio relative to a fundamental. From there, the same structure can be used as a tuning designer, a calculator, an instrument, a composition aid, a practice tool, and a diagram tool.

A Simple First Session

If you are new to the lattice, this is the fastest way to understand the app's main ideas.

  1. Set the fundamental.
  2. Choose simple axis factors such as 3, 5, and 7.
  3. Shift-click to add a few nearby nodes around the center. Use Z-click if you want to enter the Z axis.
  4. Click nodes to hear the intervals.
  5. Press Option-1 to save the state as a snapshot.
  6. Change the lattice and the playing nodes.
  7. Press Option-2 to save a second snapshot.
  8. Press 1 and 2 to switch between them.
  9. Open the Tuner from the top menu.
  10. Switch to Layout mode and make a clean diagram.

That sequence covers the central idea: one lattice can function as a theory model, a playable instrument, a rehearsal aid, and a finished document.

Ways To Use It

As a Tuning Designer

Use the lattice as a visual design surface for building and evaluating ratio spaces around a chosen fundamental.

  1. Set the fundamental at the top of the app.
  2. Choose prime-based factors for the X, Y, and Z axes.
  3. Start from the center node and Shift-click nearby ratios to grow the lattice. Use Option/Alt-click to remove ratios.
  4. Click nodes to toggle sound on and off.
  5. Use the displayed ratio, Hz, and cents readouts to evaluate the structure.
  6. Hold Z and click a node to add notes on its Z axis.
  7. Save the work with File > Save Lattice, or copy the URL if you want a shareable encoded state.

To go beyond 3 dimensions

Use Custom Nodes: hold C and click a node to add a custom node based on any ratio. Custom nodes appear as diamonds to show they are off the X-Y-Z grid.

If you already have a list of ratios relative to 1:1

Use Calculate > Find Ratios to build a lattice from that ratio set.

If you already have a list of intervals

Use Calculate > Build from Intervals to generate the lattice from interval input instead of placing nodes manually.

As a Just Intonation Calculator

Tuning Lattice can also function as a calculator for ratios, frequencies, cents, and interval relationships.

Useful tools

  • Hz, ratio, and cents readouts on nodes.
  • Interval finding and ratio search in the Calculate menu.
  • Interval Overlay for relationship labels.
  • Distance lines for comparison, labeling, and annotation.

To inspect frequencies and cents

  1. Set the fundamental and A4 reference if needed.
  2. Turn on the readouts you want in Options, such as Hz, cents, or cents deviation.
  3. Build the nodes you want to compare.
  4. Read each node directly in the lattice.

To inspect interval names between nodes

  1. Turn on Interval Overlay in the View panel.
  2. Hover over nodes to see interval labels.

To calculate the interval between two nodes

  1. Turn on Distances in the View panel and click Edit.
  2. Click and drag between nodes to create distance lines.
  3. Double-click labels to customize their text.
  4. Use Option/Alt-click on a distance line to remove it.

To find a new node as an interval from an existing node

  1. Hold I and click a node, or select Calculate > Find Interval.
  2. Choose an interval from the list, or enter a new ratio.

To visualize overtone interactions

  1. Click Overtones to enter the Overtone Tool.
  2. Edit the ratios in the Input Notes box. Use line breaks to separate ratios into chords.
  3. Show or hide overtones, combination tones, and columns showing alignments and roughness.
  4. Click nodes to hear them.
  5. Switch to Print mode to create print-ready diagrams.

As an Instrument

Tuning Lattice is also a playable instrument, with a built-in synth, keyboard mappings, MIDI input, pattern playback, one-button looping, LFOs, snapshots, and retuned MIDI out.

Main ways to play it

  • Click nodes directly in the lattice.
  • Use QWERTY keyboard mappings.
  • Play from a MIDI controller.
  • Build repeating playback patterns.
  • Loop your own performance.
  • Send retuned MIDI out to an external synth or MPE device.
  • Use snapshots to sequence harmonic states.

Simple playback

  1. Click nodes to turn them on or off.
  2. V-click a node to adjust its individual volume.
  3. Adjust waveform and envelope in the Synth menu.
  4. Press Shift-Space to turn all notes off.

To play from the computer keyboard

  1. Choose a keyboard mode.
  2. Use Piano Keyboard if you want a piano-like two-octave layout.
  3. Use Custom Piano Map if you want to assign combinations of nodes to specific keys.
  4. Use Isomorphic if you want the keyboard to approximate the shape of the current view.
  5. Use Isomorphic (Fuzzy) if you want nearby-key tolerance instead of exact key targeting.

To play from MIDI input

  1. Enable MIDI input.
  2. Select your MIDI device and channel.
  3. Play from your controller.

To use pattern playback

  1. Open the Play menu to choose a pattern, rhythm, tempo, and sustain or gate settings.
  2. Choose the sequence, rhythm, and octave behavior.
  3. Press Build and then Play to begin.
  4. Use the space bar to start and stop the pattern.
  5. Change the lattice or the view while it runs if you want the pattern to update live.

To use the built-in LFO

  1. Hold L and click-hold on a node to start an LFO.
  2. The time between mouse press and release becomes the LFO duration.
  3. Adjust rate and depth in the Synth menu.

To use the looper

The looper is controlled from the backslash key (\).

  1. Press once to arm recording.
  2. Recording begins when you play a note.
  3. Press again to enter Play mode and loop the recording.
  4. Press a third time to enter Overdub mode.
  5. Continue pressing to alternate between Play and Overdub.
  6. Press [ to clear the loop.

To use MIDI out

  1. Enable MIDI Out.
  2. Select the output device.
  3. Route the output to an instrument that supports per-note pitch bend retuning.
  4. Match the pitch-bend range in Tuning Lattice and on the target instrument.
  5. Play from the lattice and listen on the external synth instead of, or alongside, the internal engine.

As a Composition Aid

The snapshot system makes Tuning Lattice useful as a compositional sketchbook and a live scene manager.

What snapshots are good for

  • Saving chord regions or drone states.
  • Recalling different pattern setups.
  • Capturing playable states for performance.

To build a snapshot-based scene set

  1. Create a lattice state you want to keep. It can include playing nodes, LFOs, patterns, and loops.
  2. Hold Option/Alt and press a number key to save that state in a slot.
  3. Press the number key to recall it.
  4. Repeat for alternate harmonies, tunings, or playback states.

To use snapshots during playback

  1. Prepare several snapshots in advance.
  2. Use Snapshot Options to choose what should be recalled: play state, view, synth settings, sequence state, keyboard mode, and LFO behavior.
  3. Decide whether recalls should happen immediately or at cycle end for pattern playback.
  4. Enable Morph if you want connected sustained notes to bend between snapshot states.
  5. Recall snapshots by clicking the slots or using the number-key shortcuts.

A practical compositional use

  1. Build one lattice for an entire section or piece.
  2. Save contrasting harmonic regions as snapshots.
  3. Give each snapshot its own held notes, playback pattern, or LFO state.
  4. Explore movement between them to design harmonic progressions.

As a Practice Aid

Tuning Lattice can act as a reference instrument for rehearsal, ear training, and intonation work, and the Tuner can function as a live pitch-detection visualizer while you sing or play.

Useful practice scenarios

  • Holding a drone while you sing or play against it.
  • Checking the exact frequency of a target pitch.
  • Comparing nearby just intervals.
  • Using the tuner while practicing intonation.

To create a drone for practice

  1. Turn on audio.
  2. Toggle on one or more stable reference notes.
  3. Shape the synth so the sound is steady and unobtrusive.
  4. Practice against the drone while adjusting the fundamental or active harmony as needed.

To use the Tuner alongside the lattice

  1. Open the Tuner.
  2. Activate the microphone and adjust input level.
  3. Adjust the ratios and labels as desired.
  4. Click and drag on the graph to adjust range bounds, and scroll to zoom the range.
  5. Sing or play your instrument and watch the meter.
  6. Hold a reference in Tuning Lattice if needed. Use headphones so the lattice audio does not interfere with pitch detection.

As a Page Layout Tool

Layout mode turns the lattice into a finished diagram for scores, teaching materials, and export.

What layout mode lets you control

  • Page size and orientation.
  • Position, scale, and spacing.
  • Node size and shape.
  • Text styles for titles, ratios, note labels, axis labels, and custom text.
  • Which information layers are visible in the final diagram.

To make a presentation-ready diagram

  1. Build the lattice in the main editing view.
  2. Switch into Layout mode.
  3. Set the page size and orientation.
  4. Adjust zoom, spacing, and alignment so the lattice sits well on the page.
  5. Freeze the view to begin editing.
  6. Add a title and creator line if needed.
  7. Refine text sizes, fonts, and label visibility.
  8. Preview only the layers you want to publish.
  9. Export as PDF or SVG.

A good workflow here

  1. Finish the tuning logic first.
  2. Hide any labels that are useful during editing but distracting in the final diagram.
  3. Tune typography and spacing last.
  4. Export several versions if you want variants for screen, print, or teaching.

As a Design Surface for Scale Workshop

Tuning Lattice is also a front end for building tunings that you will later export into other tools, especially Scale Workshop.

Why this is useful

  • You can design the tuning visually before exporting it.
  • You can hear the tuning while you build it.
  • You can move from exploratory work to formal tuning files quickly.

To export to Scale Workshop

  1. Build the tuning you want in Tuning Lattice.
  2. Open the File menu.
  3. Export to Scale Workshop.
  4. Review the tuning there and convert it into the format you need.
  5. Export or install the result for your target environment, such as .scl, MTS, Max/MSP, or Pure Data workflows.