Frog Wizard

Forking TuxGuitar into a 17-EDO tab editor

TuxGuitar 17EDO is a fork of TuxGuitar 2.1.0 for guitars with 17 equal divisions of the octave. Stock TuxGuitar assumes 12 notes per octave in the tab, the staff, the fretboard and the synth. The fork changes all four to 17-EDO and has no 12-EDO mode. This page describes the changes in enough detail that a coding agent can reapply them to a stock checkout without the fork's source.

e |-----0------|
B |-----0.1----|
G |-----0------|
D |-----0.3----|
A |-----3------|
E |------------|

That is C major (C E G C E). The raw frets stored in the file are 0, 1, 0, 3, 4.

Model

Nothing in the song model or any file format changes. A note is still an integer fret and a string is still an integer value. The fork reinterprets both as 17-EDO steps:

The EDO is a constant, 17. An earlier version had an EDO setting, enable flags and a configurable reference key. All were removed. Do not add them.

Fret labels

Every place that prints a fret number prints a dot-relative label instead. A fret that carries a fretboard dot is labelled with the number that dot has on a 12-EDO neck. Frets past a dot are <dot>.<k>, with k the steps past it. The nut acts as a dot named 0.

Default dots: for each 12-EDO dot c in 3, 5, 7, 9, 12, 15, 17, 19, 21, 24, the dot sits on fret round(c * 17 / 12) and is named c:

4:3, 7:5, 10:7, 13:9, 17:12, 21:15, 24:17, 27:19, 30:21, 34:24

Formatting a fret f:

  1. f < 0: the plain integer.
  2. f == 0: 0.
  3. Otherwise take the last dot with dot.fret <= f (the nut if none), k = f - dot.fret. Return the dot name if k == 0, else name.k.
Fret 0 1 2 3 4 5 6 7 8 9 10 13 16 17 19 34 40
Label 0 0.1 0.2 0.3 3 3.1 3.2 5 5.1 5.2 7 9 9.3 12 12.2 24 24.6

The dot list is the only setting. It is the config key edo.labels.dots, default empty, edited in Tools > Settings on a new page titled "Fret labels" with a text field, a "Reset to default" button and a live preview of the labels for frets 0 to 19.

With dots 5:A, 2:B, fret 3 is B.1 and fret 35 is A.30.

Where the label is used:

Place Note
Tab staff, text renderer The label replaces the integer. Tied notes stay L, dead notes X, ghost notes get parentheses around the label.
Tab staff, vector digit renderer Digits use the existing glyphs. A dot is a filled square of side 0.18 * size on the baseline, with the same 0.1 * size gap as between digits.
Chord diagram first-fret number Widen the reserved space to max(configured spacing, text width + spacing / 4) and discard the cached diagram image when the label or the width changes.
Chord editor dialog Same label. Its fret limit rises from 24 to 99.
Print, PDF, PNG/JPG, SVG, ASCII tab Same label.
Caret Next to the caret box, when a note is selected, draw <raw> = <label> on a background-coloured rectangle, for example 19 = 12.2. The raw number is what the user types.

The layout style object carries the formatter and defaults to the default dots. The desktop builds it from config in one function, and that function also publishes the formatter on the application context. The SVG writer, the ASCII writer and the headless PDF styles have no config access and read it from the context, falling back to the default. Without this, exports ignore a custom dot list.

Width. Stock spacing ignores the width of the fret text, so sixteenth notes labelled 24.4 overlap. No painter exists while measure widths are computed, so the width is estimated: each character is 0.9 * note font height * font scale, a . is half that. The note asks for extra room of max(0, estimate + 6 * scale - duration width) through the hook bends already use for extra width, combined with the bend width by max. Ghost notes add 6 * scale. Tied and dead notes ask for nothing, and nothing is asked when the tab staff is hidden. At 0.8 the labels touched.

The per-track max fret spinner in Track > Properties goes to 99, up from 39. Typing frets is unchanged: two digits within a second combine, clamped to the track's max fret.

Note names and the staff

Pitches are named in Superpyth notation, the chain of fifths. A whole tone is 3 steps, E-F and B-C are 1 step, and a sharp or flat is 2 steps. C# is one step above Db.

Pitch class is floorMod(key - 56, 17):

pc 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Name C Db C# D Eb D# E F Gb F# G Ab G# A Bb A# B

Four pitch classes have a second name. Key signatures use TuxGuitar's encoding: 0 is none, 1 to 7 are sharps, 8 to 14 are 1 to 7 flats.

pc Default Second name Second name is in the key signature for
1 Db B# 7
5 D# Fb 14
8 Gb E# 6, 7
15 A# Cb 13, 14

A note uses its second name when exactly one of these holds: the key signature contains it, or the note's "alternative enharmonic" flag is set. The flag does nothing on the other 13 pitch classes. B# belongs to the octave below the computed one and Cb to the octave above.

An accidental is drawn when the note's alteration differs from what the key signature gives its staff position. All of this replaces the internals of the one utility class that names notes, with its public method signatures kept, so the score renderer, fretboard, matrix editor, print header and tuning dialogs follow without edits. Its sharp-name and flat-name functions return the same name, since sharps and flats are different pitches.

Other staff changes:

Playback

Note numbers are left alone and the synth is retuned. At the end of every channel update the player:

  1. Sends a MIDI Tuning Standard bulk tuning dump for all 128 keys.
  2. On every non-percussion channel, sends RPN 0,3 (tuning program select) with data entry MSB 0, then reselects RPN 0,0 so later data entry still means pitch bend range.

The dump is 408 bytes:

F0 7E 7F 08 01 00  <16-byte name>  128 x (xx yy zz)  <checksum>  F7

Key 69 encodes as 45 00 00. Key 70 is semitone 69 with fraction 11565. Key 52 is exactly semitone 57, so 220 Hz. Key 35 is 110 Hz.

Stock has no sysex path. Add a sendSysex(byte[]) method with a no-op default to the synthesizer and receiver interfaces and implement it in three ports:

Port How
Java Sound (Gervill) Wrap the bytes in a SysexMessage and send to a receiver.
TuxGuitar Synth, Gervill processor Same, forwarded to every channel's processor.
FluidSynth New JNI call to fluid_synth_sysex, passing the payload without the leading F0 and trailing F7.

The Java Sound plugin has two port classes. The one for Synthesizer devices drives the synth through the MidiChannel API, which cannot carry sysex. It has to fetch Synthesizer.getReceiver() and send there. Cache the receiver and drop it on error. The Gervill port is this class, so patching only the external-device port leaves the default synth in 12-EDO.

ALSA, JACK, WinMM, AudioUnit and other external ports keep the no-op. Android shares the library, so it shows 17-EDO labels and names but plays untuned.

Tunings

Converting a 12-EDO MIDI note to a step value rounds relative to A4, so every A string is exact:

step = 69 + round((note - 69) * 17 / 12)    clamped to 0..127
Tuning 12-EDO Steps Between strings
E standard, low to high 40 45 50 55 59 64 28 35 42 49 55 62 7-7-7-6-7
D standard 38 43 48 53 57 62 25 32 39 46 52 59 7-7-7-6-7
4-string bass 28 33 38 43 11 18 25 32 7-7-7

A fresh track still starts from the stock 12-EDO defaults and is then converted: each string to its step value, max fret to at least 34. Run that conversion after exactly these events, on non-percussion tracks only:

Do not change the song manager's default tuning constant. The Guitar Pro writers use it too.

Track > Tuning:

Fretboard view

Editing changes

These are unrelated to tuning.

Sticky duration. When the caret lands on a beat, stock copies that beat's duration into the selected duration. The fork copies only if the voice has notes. Otherwise typing sixteenths and stepping into a new measure resets the selection to a whole note, because the new measure holds a whole rest.

Move selection. Ctrl + drag with the left button on an active selection moves the selected beats.

  1. Mouse events gain a control-down flag (SWT.MOD1 in the SWT toolkit, false elsewhere).
  2. While dragging, the caret follows the mouse and the selection is kept.
  3. On release, if the mouse actually dragged and the drop beat is not the first selected beat: store the selected beats, clear them (notes of every voice, chord, text), write the stored beats at the drop beat's precise start with the same routine paste uses, reselect them, and put the caret on the first one.
  4. Refused between percussion and non-percussion tracks.
  5. The clipboard is untouched. It is one undo step, with whole-song undo.

Reuse the paste code path, since it already extends the song when the destination runs past the end.

Del on rests and empty measures. A measure is empty when, in every track, all its beats are rests with no text and no chord.

Repeat close without repeat open. In stock playback, a repeat close that follows a finished repeat with no explicit repeat open in between is ignored. Fix: when a repeat finishes, set the implicit repeat start to the next measure (its index and start time) and keep the repeat-open state.

Tremolo picking triplets. The tremolo picking dialog gets a triplet checkbox that sets the effect duration's division to 3:2.

Removed

These stock tools only know 12 notes and are hidden. Their actions stay registered and their sources stay in the tree.

Tool Removed from
Chord editor Chord menu entry, edit toolbar button, main toolbar item map. Saved custom chords can still be inserted from the Chord menu.
Scale tool Tools menu, the fretboard's scale button, name label and scale overlay.
Piano view View menu, main toolbar item map.
Tuner, LilyPond and MusicXML plugins The module and artifact lists of every desktop build script.

The application name is TuxGuitar 17EDO, in the app name constant and the macOS bundle name.

Things that break quietly

Checks

Known limits

#java #microtonal #midi #spec #tuxguitar