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 MIDI key played is
string value + fret, as in stock. - Key
ksounds at440 * 2^((k - 69) / 17)Hz. Key 69 is A4, key 56 is C4, 17 keys are one octave. - A file saved by the fork opens in stock TuxGuitar and shows plain integer frets. Do not touch the readers or writers for this.
- Files from stock TuxGuitar or Guitar Pro are not converted on open. Their numbers are read as steps and sound wrong. This is deliberate.
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:
f < 0: the plain integer.f == 0:0.- Otherwise take the last dot with
dot.fret <= f(the nut if none),k = f - dot.fret. Return the dot name ifk == 0, elsename.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.
- Format:
fret:namepairs separated by commas, semicolons or whitespace. Names are free text. - A blank string means the default dots.
- Entries with no colon, an empty side, a non-numeric fret or a fret
<= 0are skipped with a warning on stderr. - The list is sorted by fret. When two entries share a fret the first one wins, with a warning.
- On save, store the normalized list, or the empty string if the field was blank.
- Saving goes through the existing settings reload, so open tabs repaint at once.
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 |
- Naturals sit on pitch classes 0, 3, 6, 7, 10, 13, 16.
- Octave is
floorDiv(key - 56, 17) + 4. - A staff position and octave map back to
56 + 17 * (octave - 4) + natural step. - Valid keys are 0 to 127. Key 0 is G#0.
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:
- Clicking the staff to enter a note adds or subtracts 2 steps for a sharp or flat, where stock used 1.
- Tools > Transpose offers -17 to +17 and is labelled in steps.
- ASCII export names the strings with the same namer.
- Guessing a key signature from a scale keeps private 12-EDO tables. Scales are still 12-EDO data.
Playback
Note numbers are left alone and the synth is retuned. At the end of every channel update the player:
- Sends a MIDI Tuning Standard bulk tuning dump for all 128 keys.
- 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
- Name:
17-EDOpadded with spaces. - Per key: target pitch in 12-EDO semitones is
p = 69 + (k - 69) * 12 / 17.xx = floor(p), andyy zzisround((p - xx) * 16384)as 14 bits, high 7 first. If the fraction rounds to 16384, carry intoxx. - Checksum: XOR of every byte after
F0up to the last key byte, masked to 7 bits.
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:
- File > New.
- Loading a template. The template files stay stock.
- Adding a track.
- Changing a track's string count, only if the count actually changed.
- Switching a track from a percussion channel to a melodic one.
Do not change the song manager's default tuning constant. The Guitar Pro writers use it too.
Track > Tuning:
- Every built-in preset is offered converted. Its label, the strings table and the "which preset matches the current tuning" check all use the converted values.
tunings.xmlstays stock. - Presets in the user's custom group are stored and applied raw.
- Two new buttons, "-1 step" and "+1 step", move the selected string, clamped to 0..127.
- If the highest string plus the track's max fret exceeds 127, show a warning that names how many frets fit (
127 - highest). It is a label inside the dialog. A modal opened from the preset drop-down's selection event froze the SWT dialog. - The single-string chooser lists all 128 keys by name with octave and has a spinner for the raw step value, labelled "Step value (17-EDO step, 69 = A4)".
- Stock has a bug here that breaks preset matching in nested groups: the recursive group search passes the dialog's field where it should pass its parameter.
Fretboard view
- Draws 34 frets, two octaves.
- Fret
nsits atS * (1 - 2^(-n / 17)), withSchosen so the last fret lands on the right edge. This replaces stock's linear-ish spacing. Mirror it for the left-handed direction. - Double dot on multiples of 17. Single dot on the formatter's other dot frets.
- Click hit-testing already works from the fret position array and needs no change.
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.
- Mouse events gain a control-down flag (
SWT.MOD1in the SWT toolkit, false elsewhere). - While dragging, the caret follows the mouse and the selection is kept.
- 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.
- Refused between percussion and non-percussion tracks.
- 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.
- Del with the caret in an empty measure removes the measure. With a selection, every empty measure the selection touches is removed and the remaining beats get the stock delete.
- The song always keeps one measure.
- Elsewhere the stock behaviour stays: deleting a rest pulls the following beats left.
- When measures were removed, refresh the whole song, clear the selection and clamp the caret to the last measure.
- Undo for this action becomes whole-song. A beat-range undo cannot restore a removed measure.
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.
- In the staff, the number 3 is drawn next to the tremolo slashes.
- In
.tgfiles it is an optional child of the tremolo picking element, written only when not normal:<divisionType enters="3" times="2"/>. Files without it read as before. - A sixteenth-triplet tremolo lasts one sixth of a quarter.
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
- No
java.util.logging. The macOS bundle ships a JRE made withjlink --add-modules java.desktop, which has nojava.loggingmodule. A library class that imported it hung the app at the splash screen. Warnings go toSystem.err. - Extra width must be zero for labels that fit. Otherwise every measure reflows compared to stock.
- Send the tuning after the channels are set up. The dump and the RPN go at the end of the channel update, once every channel has been configured.
Checks
- Unit: the label table above for frets 0 to 40; the dump bytes listed under Playback; the three tuning rows.
- Round trip: save in the fork, open in stock, see plain integers.
- ASCII export of a low E string at raw fret 5 followed by fret 4 prints
3.1then3. - By ear or by pitch detection on rendered audio: open A strings at 110 and 220 Hz, low E at 82.7 Hz.
Known limits
- Natural harmonics, the tonic colour in chord diagrams and chord names from imported files still assume 12 notes.
- Two different accidentals on one staff position in one measure (C# then Cb) are not told apart.
- LilyPond and MusicXML export have no 17-EDO support, which is why they are unpackaged.
- The dot list is global, not per track or per file. A per-track setting would need a new file attribute.
- Only the SWT desktop build was tested.