# Chordious 1.0.1 by Jon Thysell # ## Features ## * Outputs to clean, scalable SVG images * Configurable styling, including: * Diagram height and width * Font size and family * Number of frets and strings * Specify top fret and barres * See a live preview of your chord with the UI chord designer * Find chords for all your instruments and tunings with the chord finder * Bulk create diagrams from the command line with Chordious.CLI.exe * Runs anywhere Mono does (Windows, Mac OS X, Linux) ## Installation ## Note: Chordious requires Mono to run, and at least Mono 2.10.9 installed to run properly. ### Windows ### 1. Download the latest Mono for Windows installer exe from http://www.mono-project.com/download/#download-win . 2. Run and complete the Mono for Windows installer exe. 3. Download the latest Chordious Windows installer exe from http://chordious.com/download/ . 4. Run the Chordious Windows installer exe. 5. Launch Chordious from the short-cut in your Start Menu (or Start Screen in Windows 8/8.1). Chordious has been tested on Windows XP, 7, 8, and 8.1. ### Mac OS X ### 1. Download the latest Mono for Mac OS X MRE pkg from http://www.mono-project.com/download/#download-mac . 2. Run and complete the Mono for Mac OS X pkg. 3. Download the latest Chordious Mac dmg from http://chordious.com/download/ . 4. Mount the Chordious Mac dmg and open the volume. 5. Launch the Chordious app. 6. (Optional) Copy the Chordious app to your Applications folder. Chordious has been tested on Mac OS X 10.9 "Mavericks". ### Linux ### You'll need the latest Mono runtime, rsvg-sharp, and their dependencies. Your best bet is to use your distro's package manager to get them. On Debian-based distros you can try the following: sudo apt-get install librsvg2-2.18-cil mono-runtime On other distros you can try following the instructions at http://www.mono-project.com/download/#download-lin . If you're on a Debian-based distro, download and install the latest Chordious deb package from http://chordious.com/download/ . Then from a shell prompt you can run: chordious On other distros, download the latest Chordious Linux Binaries tar.gz from http://chordious.com/download/ . Unzip the folder somewhere on your system. Then from the folder where you unzipped Chordious simply run chordious.sh On some systems, you may be able to simple double-click on Chordious.exe, or right-click and select Open with > Mono Runtime. ## 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. Happy chording! /jon ## Advanced Topics ## ### How the Chord and ChordOption lines are constructed ### The Chord and ChordOption lines are just semi-colon delimted 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 shorcut 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.