Chordious 1.0 Tutorial

After you’ve clicked around Chordious for a bit, you may have found that things don’t work exactly the way you’re expecting. With that in mind, here’s a quick tutorial (found also in the readme) for using Chordious:

Chordious overview

With Chordious you can create chord diagrams for any fretted string instrument, like the ukulele, guitar, or banjo. You can make your diagrams use the same style, or make each one unique-it’s up to you!

The basic flow is to first create an input file called a ChordDocument, then feed that file into Chordious, which will read the file line-by-line and generate the chord diagram files. So let’s talk about that input file first.

The ChordDocument file

At its heart, the ChordDocument file is just a plain text file, with three types of lines:

  1. Chord lines
  2. Option lines
  3. Comment lines

Let’s dive into what each of these lines mean.

Chord lines

A Chord line defines a particular chord diagram. It consists of:

  1. The title or name for the top of the diagram (C, Gmin7, etc.)
  2. An optional filename (in case you want multiple diagrams with the same title)
  3. The number of strings to display in the diagram
  4. The number of frets to display in the diagram
  5. The baseline number, or what number fret the diagram starts at
  6. The barre number, or what fret, if any, that the player should barre
  7. The marks, or what fingerings make up the chord

A Chord line lists all of those items from left to right on a single line in the text file. (See Advanced below if you’re interested in how the line is encoded).

Option lines

A Option, or options line, defines the style of all of the chords that follow it. (We will return to this point in a minute.) The line contains:

  1. The full width (in pixels) of the following diagrams
  2. The full height (in pixels) of the following diagrams
  3. The stroke width, or line thickness (in pixels) of the following diagrams
  4. The margin (in pixels) between the edge of the image and the actual diagram
  5. The font-size (in pixels) of the diagram’s title
  6. The font-family of the diagram’s text
  7. The font-style of the diagram’s title
  8. The type of barres to use
  9. Whether or not to force the barres across all the strings
  10. Whether or not to put a mark above open (unfretted) strings

A Option line starts with a percent sign (%), and then, like a Chord line, lists all of its components from left to right on a single line in the text file. (Again, see Advanced below if you’re interested in how the line is encoded).

Comment lines

Finally we have Comment lines. Comment lines are ignored by Chordious, and are there simply to give you a place to add useful text your ChordDocument without Chordious trying to process it as a Chord or Options line. A Comment line starts with a hash or pound-sign (#), and has plenty of uses:

  1. Put a title and description at the top of your ChordDocument, so you can tell different ChordDocuments apart.
  2. Organize your file, by letting you describe the upcoming lines.
  3. Temporarily disable a Chord or Options line, so that it isn’t processed by Chordious.

Okay, now that you know a little about how the ChordDocument works, let’s see how we can make one in the Chordious designer!

Using the Chordious designer

When you first start Chordious, you’ll see that the interface is divided into four columns from left to right. The first column contains the contents of your ChordDocument, that is, the list of Chord, Option, and Comment lines. You can use the New, Open, Save, and Save As options in the File menu to work with ChordDocuments as you would expect in most programs. (If you want, open the sample.txt file included with Chordious to populate a list of lines in the left-most column.)

The second column has actions you can perform on the lines to the left. Here you can:

  1. Add a new Chord line with “New Chord”.
  2. Add a new Option line with “New Options”.
  3. Add a new Comment line with “New Comment”.
  4. Move the selected line up or down in the list.
  5. Edit the selected line (Comments and Options lines only)
  6. Toggle the selected line to/from a Comment (see below).
  7. Delete the selected line.
  8. Launch the Chord Finder

The third column contains a preview of the selected line, presuming that selected line is a Chord line.

The fourth column contains the designer for the selected line, presuming that selected line is a Chord line.

Let’s start with the simplest operation, adding a new Chord line. Simply click on the “New Chord” button in the second column, and watch how it both appears in the left-most column, and then enables the Chord Preview and Chord Designer columns.

You can edit the chord diagram’s properties under Chord Designer, and watch how the diagram updates live under Chord Preview. Play around and modify the chord to your liking.

Now, let’s look at the buttons beneath the Chord Designer. There are three buttons: Default, Revert, and Save.

Changes you make to a chord aren’t saved until you click on the Save button. That will update the selected Chord line in the first column with the changes you made in the designer. If you made a mistake while editing the chord, you can always press the Revert button to reset the Chord back to what it was before you started editing it.

The Default button is a little different, and is there to help you with adding a lot of similar chords at once. When you hit “New Chord”, Chordious adds a chord defaulting to a C chord on standard ukulele. If you want, you can use the Default button to set that default “New Chord” to whatever you currently have in the Chord Designer. Your new default will last until you exit Chordious.

So let’s say you’ve added a new chord, but you’re not too thrilled about the default style. Sounds like it’s time to add a new Option line! Go ahead and click on the “New Options” button in the second column.

You should now see a smaller window titled “Chord Options Editor”. Here you can change any of the style options of your diagrams. Go ahead and change a few of the options now, then click OK to add a new Option line to the left-most column in the main window.

Now you should be back in the main window, with your new Option line selected in the left-most column. Go ahead and select the chord you added earlier.

Wait, what happened? It still looks the same as it did before! That’s because, as I mentioned earlier, when you’re ready to export the actual Chord diagrams later, Chordious reads through the ChordDocument in order from top to bottom, one line at a time. A Option line sets the style for all the Chord lines that follow it.

So, what to do? If you want the Option line to affect the style of the Chord you created earlier, you’ll need to use the “Move Down” or “Move Up” buttons to reorder the lines. Move the Option line above the Chord line, then select the Chord line.

There we go! Now we see our new style applied! If you want to change that style later, you can select the Option line and hit the “Edit Line” button to bring up the Chord Options Editor window again.

So you might be asking, why not just let you edit the individual style of each chord when you’ve got it selected in the Chord Designer?

The answer is simple: because in general, the idea behind Chordious to create a set of relatively matching diagrams all following the same style rules. By putting a single Option line before the Chord lines, I’ve now got a set style that applies to all of them.

The real power though, comes with combining Options and Comments, as we’ll soon see.

If you want to add a Comment, hit “New Comment”, enter whatever text you want, and a Comment line with that text will appear in the left-most column. You can move it up and down like any other line, and use “Edit Line” to change the text of the Comment.

But the real, power-use of Comments, is to toggle Chord and Options lines on or off. How does that work? Basically, if you select a Chord or Option line, and hit “Toggle Comment”, that line will instantly become a Comment line. For Chord lines that means Chordious will skip that line when exporting the diagrams. To re-enable that line, just hit “Toggle Comment” again- Chordious is smart enough to figure out that line used to be a valid Chord, and so your Chord line will be as good as new!

For Option lines, toggling them into Comment lines means their styles stop applying to the Chord lines beneath them. This means you can, for example, apply different styles to the same set of Chords, without having to change any of the Chords.

So, say you want to create two sets of Chord diagrams, one set for a songbook, with a very professional style, and another for a poster in school, with a large, cartoony style.

You could duplicate and maintain two separate ChordDocuments, each with its own Option line at the top of the list. Or, you could put the two different Option lines at the top of one file, and “comment one out”, or disable just one with “Toggle Comment”. When you export the diagrams, only the active one will be used. So you could export the professional diagrams, then disable the professional style, enable the cartoony style, and then export the cartoony diagrams.

That also means that if you create a style you like, but still want to experiment around, just by moving Options lines around and toggling some of them on or off, you can store and switch between a variety of styles in your ChordDocument and keep reusing the same set of Chords lines you’ve entered.

And of course, if you do want some diagrams to be one style, and some to be another, all you have to do is order your Chord and Option lines so that the Option line you want appears above the Chord lines you want it to apply to.

When you export the diagrams, Chordious will start form the top of the document, and process each line one at a time. When it sees an Option line, it’ll set the style to whatever the Option line says. When it sees a Chord line, it’ll make a new image file with whatever style it saw last. Later, if it sees another Option line, the old style will be cleared out and the next set of image files will use the new style.

So, feel free to play around and experiment with Chord, Option, and Comment lines. The Chord Preview column will always show you exactly what the final image will look like, so if you’re still confused about how the Option lines work, just reorder them in the left-most column, select a Chord, and check out the Chord Preview column.

Using the Chord Finder

The Chord Finder can, given an instrument, tuning, and a chord type, will find all of the valid chords shapes for you. To start it, simply click on the Chord Finder button on the bottom of the second column of the main app.

Now you’ll first want to work from left to right along the top of the window and select your preferred instrument and tuning, then the note and chord quality of the chord you wish to find. Then on the left hand side of the dialog there are a few options to confine your search.

“Num Frets” lets you specify the number of frets to show in the diagrams, while “Max Fret” lets you specify the highest fret on the fretboard you want to use. “Max Reach” specifies the maximum number of frets you want to stretch your fingers over. Note that your “Max Reach” should be less than or equal to the “Num Frets” value, otherwise you’re saying you want chords that are larger than your diagram!

“Auto Add Barres” specifies if you want the Chord Finder to automatically calculate where to barre on the fretboard. “Allow Open Strings” specifies if you want to allow unfretted strings in your chords, and “Allow Muted Strings” specifies if you want to allow unplayed or muted strings.

When you’ve got everything selected the way you want it, just click on the “Find Chords” button, and if your search parameters were wide enough, you should be greeted with a list of chord diagrams on the right of the dialog.

Now that you have some diagrams, you’ll probably want to save them into your ChordDocument. Simply highlight the diagrams you want (using ctrl or shift to select multiple diagrams) then click on the “Save Selected” button. Now if you close the Chord Finder you should see the diagrams you selected added to the end of your ChordDocument.

Once the diagrams are in your ChordDocument as Chord lines, you can treat them like any other Chord line.

Exporting the Chord lines into image files

So now you have a ChordDocument, with all kinds of pretty Chord lines. How now do you generate image files that you can use in your own projects?

It’s simple, just select Export from the File menu and the image type. You’ll be asked to select an output folder (or you can create a new one), and then Chordious will get to work creating your image files.

Chordious creates individual files for each Chord line, naming them with whatever was in the Filename field. If a Chord line doesn’t have a Filename set, Chordious will use the Title field. Chordious will not prompt you about overwriting files, so if you have multiple Chord lines with the same Title (say, different fingerings for the same chord), you’ll want to give each a unique Filename so that Chordious doesn’t overwrite a diagram with another just because the Titles are the same.

Wait, what are SVG files?

If you’ve worked with image files on your computer before, you’re probably familiar with the more common image types like JPG, GIF, or PNG. There are a lot of programs around for editing those file types. So why does Chordious make SVG images? What are SVG images?

First of all, SVG images are technically just text files, and it’s ridiculously easy to make text files. Secondly, instead of actually having to draw the chord diagrams, with SVG images all I do is create a text file that describes how to draw the diagram, ie. draw a box, put lines across it, add some text and some circles.

Secondly, and perhaps more importantly, SVG images are “vector-graphics”, which is a fancy way for saying they aren’t actual pictures, just instructions for how to draw pictures. Because of that, they scale way better than JPG, GIF, or PNG files. A computer can “do the math” and simply redraw the diagram at any size and still end up with a sharp, beautiful picture.

To see this in action, open one of the SVG chord diagrams with your favorite web browser. Now zoom in a ton, and you’ll see how sharp the lines remain, at any size. This makes it easy for you to say, use the images on a letter-sized handout, then blow those exact same images up to put on a wall poster and not have to worry about the images becoming all blurry.

Try that with your JPG, GIF, and PNGs!

And of course, if you really need your images in another format, Chordious can output to JPG and PNG too.

Advanced Topics

How the Chord and ChordOption lines are constructed

The Chord and ChordOption lines are just semi-colon delimited lists of values. Simple, if not very forward-proof. when I want to track new values, I usually have to add them to the end of the line, and make sure that if Chordious sees an older line, that it updates it without changing what the chord looks like.

I try very hard to make sure that new versions of Chordious can still read older ChordDocuments and their lines and still create the same pictures they did in the earlier version.

Editing the ChordDocument by hand

The ChordDocument is just a plain text file, which you can open with your favorite text editor. You’re free to edit the file directly if you think that’s faster than using the graphical Chordious designer. In fact, the early versions of Chordious had no graphical designer, so if you changed something in your ChordDocument, you had to actually export the images to see if your change did what you wanted!

Unless you really feel the need to, I recommend just using the graphical designer. If there’s some part of using the designer that you don’t like, drop me a line and I’ll see if I can fix the issue in a future version.

If for some reason you just want to quickly tweak a single line, a shortcut is to select the line in Chordious, hit “Toggle Comment”, then “Edit Line” so you can edit the line’s text directly. As long as the line is still valid, you should be able to toggle it back.

Chordious.CLI Usage

From the command line, you can run Chordious.CLI.exe and pass in either a single Chord line or a ChordDocument, followed by an output directory, and the app will quickly export the images into that directory.

For example:

mono Chordious.CLI.exe sample.txt sample/

will export all of the chords in sample.txt to the folder named sample/.

mono Chordious.CLI.exe C;4;5;0;0;0;0;0;3 sample/

will create an image called C.svg in the sample folder.

Use Chordious.CLI.exe -? for more input options.


Father. Engineer. Retro games. Ukuleles. Nerd.

Tagged with: ,
Posted in Tutorials
One comment on “Chordious 1.0 Tutorial
  1. […] pretty powerful for making custom chord diagrams. Now, if you’ve poked around a bit, read the written Chordious tutorial, and are still confused (or even still on the fence for giving Chordious a try), I’ve gone […]


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: