-
Notifications
You must be signed in to change notification settings - Fork 3
Beginners
This guide is intended for stringed instrument players with little to no experience with programming, git, python and the command line. No prerequisites are necessary and this setup takes at most 10 minutes. At the end of this guide, you should hopefully have one-click access to ThatChord on your desktop computer: an ad-free, powerful, fast and fully customisable chord diagram generator.
Please note that this installation guide only works for MacOS users. ThatChord works with Linux and Windows too, but the automation that this guide sets up will not work for other platforms.
This guide will make extensive use of your Mac's Terminal. The Terminal is a pre-installed application on your Mac which gives you access to commands that interact directly with your Mac's Unix shell. You can navigate through folders just like you can with the Finder (though you don't see nice icons for your files, just plain text). It's also through the Terminal that many important applications are run, some of which we will be using here.
Commands you have to enter into your Terminal will be presented in this guide as follows:
cd Documents
mkdir MyFolder
Each line of code is a separate command. To run it, copy and paste it into the Terminal and hit enter. If there are several commands, as above, copy the first one and hit enter before running the second command. If you're curious, the two commands above will navigate to your Documents folder, and create a new subfolder called "MyFolder".
Anyway, let's get started!
Homebrew is a package manager for your Mac that runs in your Terminal. A number of popular applications, including Python, can be installed with Homebrew using very simple commands. If you already have Homebrew (you can check by running brew in your Terminal - if you get "command not found", then you haven't got it), skip this section. Otherwise, to install Homebrew, run the following in your Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
This might take a while to download. If you ever have to use the command line again, Homebrew will likely come in handy anyway, so it's a good thing you've installed it.
It's possible your Mac has a Python interpreter pre-installed, but it might be Python2. To be sure, we'll make sure you have Python3 by installing it using Homebrew. Run:
brew install python3
We're going to use git to create your own personal copy of all the ThatChord files present in this online repository. This will create a new folder called "ThatChord" with all the Python files inside. You can copy this repository anywhere on your Mac, but for the purposes for automation I have assumed that you've made it a subfolder of your Documents folder - so it's best to do that. Run the following:
cd ~/Documents
git clone https://github.com/tomcontileslie/ThatChord.git ThatChord
And you're done! All the Python files you need for ThatChord are already available on your computer.
In the future, if any updates to ThatChord appear online, you will be able to painlessly incorporate them into your personal version by running:
cd ~/Documents/ThatChord
git pull origin master
You are, of course, also welcome to make your own modifications to the source code in your local copy. If you have improvements to suggest, come back to this GitHub repository and check out the Issues page, or fork my repository and submit a pull request.
Pillow is a version of the Python Imaging Library (PIL) that allows Python to draw, modify and save images. ThatChord is able to draw chord diagrams for you and requires the Pillow add-on to do this. You can run ThatChord without Pillow, if you change the settings so that the program outputs plaintext diagrams rather than images.
PyYAML is a Python package which reads the settings out of your settings file. This is necessary for ThatChord to run.
Install these essential packages, and a few other ones necessary for ThatChord, by running:
python3 -m pip install -r requirements.txt
At this point, ThatChord should work! Try typing:
cd ~/Documents/ThatChord
python3 thatchord.py Bbadd9
You should see a ukulele chord appear.
Doing this each time you want to see a chord is tiresome, so the next section sets up a more streamlined way of running ThatChord.
The GitHub repository you cloned in step 3 contains an Apple Workflow file which we are going to install as an Apple Script on your Mac. This will allow it to be run in one click and will do all the work in the Terminal for you. Do the following:
- Using the Finder, open the ThatChord folder (in Documents). You should see some python files and a couple folders.
- Look for the workflow called "ThatChord". Its icon should be a cog.
- Right-click the workflow and in Open With..., pick "Automator" - NOT "Automator Installer" which will attempt to install it in the wrong format.
- In the application that opens, you will see the workflow. Go into File > Convert To.
- In the pop-up that appears, select Application.
- You're now editing the Application version of the ThatChord workflow. Go into File > Save.
- Change the format (at the bottom) to Application, and change the name to ThatChord.app. Save your new application in your ThatChord folder.
- Open your ThatChord folder in the Finder where you should see your new application. We now need to move it to a different folder.
- In the terminal, type:
open /Library/Scripts- this should open a Finder window. - Drag and drop the new ThatChord application into the other Finder window entitled "Scripts". You may need to enter your password to authenticate the installation of ThatChord as a script - don't worry, all the app does is essentially run the code we saw in the previous section.
At this point, ThatChord is an easily accessible script. You can make it part of the menu bar (at the top of your screen) by following the instructions in the next section.
Do the following things to add your scripts to the menu bar, where they can easily be accessed:
- From the Launchpad, open the Script Editor.
- Next to the apple icon in the top left corner, click Script Editor and choose "Preferences..."
- In the General tab, tick the boxes saying "Show Script menu in menu bar" and "Show Computer scripts".
You're done!
If all has gone well, ThatChord will run effortlessly. To find a chord diagram, click on the Scripts icon in your menu bar (the icon that looks like a piece of parchment in the shape of an S) and select ThatChord. A prompt will ask you to enter the chord you want, and the corresponding chord diagram will appear seconds later.
If you want to change the default instrument or its tuning, see the Settings wiki page. There are also special commands you can enter in the ThatChord prompt if you want to custom define a chord or do other things like that; see the Usage page for more info.