Skip to content

Settings

Jump to bottom
Tom Conti-Leslie edited this page Jan 8, 2021 · 5 revisions

NOTE JAN 2021: this page is outdated and settings are now modified in settings.yml, not settings.py. Some of the guidance below still holds, but I will update this page eventually to represent the current state of things. Please contact me (e.g. by raising an issue) if you encounter any issues, I am happy to help.

Using ThatChord's Settings file

The instrument that ThatChord finds chord diagrams for is customisable almost exclusively through its settings file: settings.py, in the main folder. This file also contains settings regarding how input and output is handled. This wiki page will cover:

  • How to change your settings
  • How to customise your instrument
  • How to change input and output format
  • How to change the graphical parameters of the output

How to change your settings

All editing of settings takes place in the settings.py file. To open the settings file, navigate to your ThatChord folder and open settings.py in edit mode. Alternatively, you can run ThatChord and when prompted for a chord, type "SETTINGS". This will open the file with your computer's default application.

Most of the settings that can be changed in settings.py are strings containing only capital letters. For example, the default instrument when you download ThatChord is ukulele, indicated by the following line of the file:

instrument_preset = "UKULELE"

if you wish to change the value of the instrument preset, change the content of the quotation marks to another valid value. For example, guitar can be obtained by changing the above line to:

instrument_preset = "GUITAR"

and saving your changes.

For some settings elements, entering an unrecognised value will create an error. This is the case, for example, if you write:

input_type = "SOMEGARBAGE"

and save your changes.

For other settings elements, entering an unrecognised value simply means that rather than using a preset, the custom values underneath are used instead. For example, you can choose guitar as your ranking preset by doing:

ranking_preset = "GUITAR"

And all this does behind the scenes is set the value of the variable ranks to be [3, 0, 3, 1, 0, 5, 2, 5, 8]: a list of ranking weights which happens to work well for guitar chords. This avoids you having to type out a long and difficult-to-remember list of numbers every time you want to change instruments. However, if you want to choose a custom list of ranks rather than using a preset, simply set the preset value to something which is not recognised - for example, "CUSTOM" - and then choose your ranks just underneath. For example, you could do:

# CHOOSE YOUR RANKING COEFFICIENT PRESET HERE, OR SET TO EMPTY TO USE SETTINGS
# UNDERNEATH.
# --------------------------------------------------------------------------- #
ranking_preset = "SOMEGARBAGE"
# --------------------------------------------------------------------------- #

# If the preset is unrecognised, the following coefficients are used.
ranks = [8, 0, 1, 2, 5, 2, 9, 2, 4]

and the result will be that your custom list of ranks will be used.

Similarly, entering an unrecognised preset name for instrument_preset will instead use the custom-defined values of tuning, nfrets, nmute, important, order, left and stringstarts defined below it.

How to customise your instrument

A number of instrument presets are available in settings.py which automatically set your instrument's tuning, number of frets, handedness, and a few other technical properties. A full list of recognised presets (this may not be fully up to date) is below. As you may guess, I am mostly knowledgeable in ukulele. Pull requests to ThatChord's repo which will add guitar presets are much appreciated.

UKULELE                           (soprano ukulele)
UKULELE-D                         (soprano, D tuning)
UKULELE-CONCERT
UKULELE-CONCERT-LINEAR            (concert uke, low G string)
UKULELE-TENOR
UKULELE-TENOR-LINEAR              (tenor uke, low G string)
UKULELE-TENOR-CHICAGO             (tenor uke, DGBE tuning)
UKULELE-TENOR-CHICAGO-LINEAR      (tenor uke, DGBE tuning, low D)
UKULELE-BARITONE                  (baritone uke, GCEA tuning, high G)
UKULELE-BARITONE-LINEAR           (baritone uke, GCEA tuning, low G)
UKULELE-BARITONE-CHICAGO          (baritone uke, DGBE tuning, high D)
UKULELE-BARITONE-CHICAGO-LINEAR   (baritone uke, DGBE tuning, high D)

GUITAR

BANJO                             (GDGBD, leftmost string starts at 5th fret)

SAZ                               (DGA tuning)

Writing any of the above presets with -L at the end will make it left-handed.

If you choose a preset not in the list, the settings underneath are used. Namely, you can pick whatever tuning you want by changing the tuning variable. Enter notes as numbers, where 0 represents C, 1 is C#, and so on to 11 for B. So for example, an instrument tuned DGABC would be entered as:

tuning = [2, 7, 9, 11, 0]

The other settings just below the preset control the following:

  • nfrets is the number of frets on the neck. Chords diagrams going higher than your chosen number are disregarded. The lower this number if, the faster ThatChord runs (because it has less options to check).
  • nmute is how many strings on the left of the neck can be muted. On guitar this is typically 2, on banjo it is 1, and on ukulele it is 0 since strings are generally not muted.
  • important sets the minimum number of notes in a chord that must be played for the diagram to be valid. E.g. if important is 3 but you want Cmaj7, a chord with only C, G and B is valid. I recommend just setting this to the number of strings.
  • order is a list of the same length as the tuning which says what order the strings are in from lowest to highest. It helps in deciding how well a chord covers the bass notes.
  • set left to True for left-handed playing.
  • set stringstarts to a list of zeros, unless one of your instrument's strings starts partway up the neck, e.g. on a banjo, the leftmost string starts on the fifth fret. So in that case, stringstarts = [5, 0, 0, 0, 0].

How to change input and output format

Input and output format is governed by the following variables:

input_type
output_format
output_method
save_method
save_loc

How to choose the value of each is explained below. All possible values are listed along with the consequences.

Input type

This allows you to choose how your chord query is taken into the algorithm, i.e. where do you write "Cmaj7" if you want to see the diagram for Cmaj7?

  • Set to DIRECT if you wish to modify thatchord.py and run the file directly each time you want to see a chord. There is a variable called request in thatchord.py which is set by default to be "Gadd9". If you change this and save the algorithm with DIRECT as your input type, that string will be considered as the request.
  • Set to CONSOLE if you have a Python console available. Then, executing thatchord.py - for example, by running python3 thatchord.py in your command line - will open a Python console which will prompt you for input.
  • Set to TERMINAL if you want your request to be passed as an additional argument from the command line. For example, you will be expected to run python3 thatchord.py Cmaj7 in your command line.

Output format

  • Set to TEXT for plaintext output.
  • Set to PNG for png image output. This requires the Pillow module.

Output method

  • Set to PRINT (only if your output format is TEXT) for the chord diagram to be printed to the Python console.
  • Set to SPLASH if you want the output text, or image, to be opened in a new window.
  • Set to NONE if you don't want to see the output. Presumably, you are either testing the algorithm's speed or saving the output somewhere via the next setting.

Save method

  • Set to SINGLE for a temp file to be created with the output text or image. This will be saved in the subfolder of your ThatChord folder specified in the save_loc variable. This temp file will override any existing temp file with the same name. The name will be ThatChordTemp.png or ThatChordTemp.txt.
  • Set to LIBRARY for the output to be saved in the same location as the previous option, but with a slightly more unique name so it's unlikely to overwrite other diagrams (unless you chose the same chord name).
  • Set to NONE if you don't want the output to be saved. Note that you can't splash text output if you don't save it.

Save location

save_loc specifies what subfolder of ThatChord/ to save output in. By default, this is diagrams/, which is an already existing subfolder. If you choose anything else, make sure that folder exists. Also remember to end the folder name with a forward slash.

Clone this wiki locally