-
Notifications
You must be signed in to change notification settings - Fork 3
1. FretboardMapper Algorithm Configuration and Tunables
Scott VanRavenswaay edited this page Aug 7, 2025
·
2 revisions
Source of truth
- CLI flags defined in
arguments.py(mapper_group)- Default values and dataclass fields in
config.py- Scoring & fingering logic in
mapper.py
| Flag | Default | Description |
|---|---|---|
--tuning <NAME> |
STANDARD |
Selects guitar tuning (open-string pitches). Choices: STANDARD, E_FLAT, DROP_D, OPEN_G, BASS_STANDARD, BASS_DROP_D, BASS_E_FLAT, SEVEN_STRING_STANDARD, BARITONE_B, BARITONE_A, BARITONE_C, C_SHARP, OPEN_C6, DROP_C. |
--max-fret <INT> |
24 |
Highest fret number considered on the virtual neck. |
These parameters tune the internal cost function in _score_fingering:
| Flag | Default | Effect |
|---|---|---|
--fret-span-penalty <FLOAT> |
100.0 |
Cost per fret between highest & lowest note in a chord (wide stretches get big negative). |
--movement-penalty <FLOAT> |
3.0 |
Cost per semitone difference between successive chord fingerings. |
--string-switch-penalty <FLOAT> |
5.0 |
Cost per string change (symmetric difference) between chords. |
--high-fret-penalty <FLOAT> |
5.0 |
Penalty multiplier for average-fret > sweet-spot high. |
--low-string-high-fret-multiplier <FLOAT> |
10.0 |
Additional multiplier when high-fret penalty applies on low (thicker) strings. |
--unplayable-fret-span <INT> |
4 |
Span above which a fingering is flagged unplayable (score = –1000). |
--sweet-spot-bonus <FLOAT> |
0.5 |
Positive bonus if average fret lies between --sweet-spot-low and --sweet-spot-high. |
--sweet-spot-low <INT> |
0 |
Lowest fret of the "sweet spot" range. |
--sweet-spot-high <INT> |
12 |
Highest fret of the "sweet spot" range. |
--ignore-open |
false |
Exclude open-string (fret 0) from span calculations; only fretted notes count. |
All defaults correspond to MapperConfig fields in config.py.
Controls how hammer-ons, pull-offs, legato, and taps get detected:
| Flag | Default | Effect |
|---|---|---|
--legato-time-threshold <F> |
0.5 |
Max time (in beats) between two notes on same string to consider a hammer-on/pull-off. |
--tapping-run-threshold <INT> |
2 |
Minimum run length (consecutive non-pick events) in single-string mode to mark a TAP. |
How simultaneous notes get grouped and cleaned before fingering:
| Flag | Default | Effect |
|---|---|---|
--dedupe |
false |
Remove duplicate pitches in a chord before mapping. Maps to deduplicate_pitches. |
--quantization-resolution <FLOAT> |
0.125 |
Beat-grid resolution (e.g. 0.125=8th-note) for grouping events into time bins. |
Encourage open-string fingerings when available:
| Flag | Default | Effect |
|---|---|---|
--prefer-open |
false |
Apply an extra penalty to any fretted note when the same pitch is playable open. |
--fretted-open-penalty <FLOAT> |
20.0 |
Penalty amount per fretted-versus-open note. |
# default mapper (STANDARD, 24 frets)
gtrsnipe --tuning DROP_D \
--fret-span-penalty 200 \
--movement-penalty 1.5 \
--sweet-spot-high 9 \
--prefer-open \
input.mid output.tab- Start with defaults.
- If chords end up with wild stretches, increase
--fret-span-penaltyor reduce--unplayable-fret-span. - If your hand moves too much between chords, raise
--movement-penalty. - To favor open strings, add
--prefer-open(and tune the accompanying--fretted-open-penalty).
You can now iterate: tweak one parameter, re-run, examine resulting tab (and any debug logs), then repeat until you reach a comfortable fingering style.
--debug can be used to show the scoring calculations to gain understanding of how your tweaks affect the results.
--ignore-open can make a surprising amount of difference without having to tweak scoring weights.
Compare the first few measures of MrCrowley from earlier:
Normal transcription:
e|-------------------|-----------------------|--1----------------|--3--------------------|--5----------------|
B|--6----------------|--5--------------------|--1----------------|--5--------------1---p0|--5----------------|
G|--7----------------|--5--------------------|--2-----0---h2----4|--5--------------------|--5-----4---h5----7|
D|--7---------------5|--7--------------7---p5|--3----------------|--5-----5--------------|--7----------------|
A|--5-----7---h8-----|--7-----7--------------|--3----------------|--3---------3----------|--7----------------|
E|-------------------|--5---------5----------|--1----------------|-----------------------|--5----------------|
with --ignore-open:
e|--1----------------|--0--------------------|--1----------------|--3--------------------|--5----------------|
B|--3----------------|--1--------------------|--1----------------|--5--------------1---p0|--5----------------|
G|--2----------------|--2--------------2---p0|--2-----0---h2----4|--5--------------------|--5-----4---h5----7|
D|--0-----2---h3----5|--2-----2--------------|--3----------------|--5-----5--------------|--7----------------|
A|-------------------|--0---------0----------|--3----------------|--3---------3----------|--7----------------|
E|-------------------|-----------------------|--1----------------|-----------------------|--5----------------|
