Introduction

Tunebook is a viewer for music expressed in the ABC format. ABC is a simple text-based notation for music and many thousands of tunes are freely available in this format on the Web. ABC is also supported by many music applications. See http://abc.sourceforge.net/ for more details on the ABC format.

Tunebook started as a fun project for my personal amusement. I originally wanted to make it free for others to use, but it costs real money to register as an iPhone developer and so the charge is intended to cover some of the costs of development. Sorry.

Tunebook exists in two versions: one for the iPhone and one for the iPad. Although they have similar features, the user interface is different to take advantage of the iPad's larger screen. This documentation mostly concentrates on the iPhone version, but all features are also available on the iPad.

The Tune List

The home view of Tunebook is a list of all the tunes in the Tunebook database. Each tune shows its (main) title, time signature and key. You can filter this list by typing into the search bar at the top of the list (if the search bar is scrolled out of view, simply tap on the status bar at the top of the screen to scroll it into view). Tunebook will treat each word you type as a separate search term and search for any tune which contains all the words in its title. You can also search for tunes in a particular key by typing the name of the key, such as "A" or "Edor". Tunebook assumes that any single character word you type is a key name, so that typing "A" gives you tunes in A, not all tunes with the letter A in the title. You can also search for tunes with particular key signatures. For example, to find all tunes in 7/8, type "7/8" into the search bar.

The tunes list on the iPhone

The iPad version has a different interface where the tune is the focus and all tune and tunebook indices are shown in popover windows. To show the tune list, tap on the button at the left of the bottom toolbar.

The tunes list on the iPad

Viewing Tunes

To view a tune, click on its entry in the tune list. This will display the sheet music of the tune. Use landscape mode and tap the screen once to hide the navigation bar to see as much of the music as possible. Scroll by dragging, or pinch to zoom in or out.

A tune displayed on the iPhone

The larger screen of the iPad allows a page of music to be shown confortably and traditional tunes usually fit very nicely in landscape mode. Disclaimer: I am not responsible for any damage to iPads caused by falling off music stands!

To play the tune in a nasty tinny way, click on the play button in the bottom toolbar. To change the voice, volume or playback speed, click on the intrument button at the bottom left. This displays an overlay with a choice of not-so-hyper-realistic instruments, a volume slider and a speed slider.

Playback Controls

To email the tune to your friends, click on the email button in the bottom toolbar. On iOS 3.0 and upwards, this will show a mail window which will allow you to email the tune in ABC format as a PDF file. On older versions, it will launch the Mail application and only ABC format is available.

To edit the ABC of the tune, click on the "Edit" button at the top right. This displays a text editor which allows you to edit the ABC source of the tune. On the iPhone the text view will fill the screen - there's simply not enough room to display the music, the ABC anfd the keyboard all at once. You can switch back and forth between the sheet music and ABC views until you're happy with your changes. When finished, press the "Done" button to save your changes. On the iPad, the ABC text and music are both displayed at once and the music display will update as you type.

Tunebooks

To organize your tunes, you can create tunebooks. There are two kinds of tunebook, simple and smart. These are similar to playlists and smart playlists in iTunes. To create a tunebook, choose the "Tunebooks" tab, and press the "Edit" button:

Tunebooks displayed on the iPhone

Press on the green "+" button to create a new tunebook. You'll be asked to give it a name. When you've done this, press the "Done" button and then select the tunebook, which will contain no tunes. You can then press the "Edit" button to add tunes.

Deleting a tunebook does not delete the tunes contained in the tunebook.

You can't edit the list of tunes in a smart tunebook as it is the result of a search and will change as you add, delete or modify tunes.

Searching and Smart Tunebooks

As well as the quick search in the tunes page, you can search in the "Search" tab, which gives you more options. You can search the actual text of the ABC of the tune here. This allows you to find a tune when you know a few notes in it. You can also search by key, title and meter. The ABC search is an exact case-insensitive match, while the other search terms will search for any of the words you type. For example, you can type "6/8 9/8 12/8" in the "Meter" field in order to find jigs.

Tip: The ABC search searches the ABC header lines as well, so you can also search on keywords you add to your tunes.

When you are viewing the search results, you can press the "Save" button at the top right to save the search as a smart tunebook. This allows you to, say search for waltzes, and then create a tunebook which will always contain all the waltzes in your collection.

Importing Tunes

There are four ways to import tunes into Tunebook: You can browse for ABC files on the Internet, you can connect to Tunebook from a Web browser and use a form to upload files into it, you can use iTunes file sharing, or you can enter new tunes in a text editor.

To browse for tunes, press the "Manage" tab at the bottom of the main screen, then choose "Import Tunes". This will display a Web browser which allows you to wander the Web in search of ABC files. You can enter a URL into the address bar at the top, or you can press the "Bonjour" button at the top right which will allow you to find local Web sites published on Bonjour. This is useful if your ABC files are on your local computer and you have a Web server to access them. If you click on a link to an ABC file (a file with the extension ".abc"), Tunebook will ask you if you want to import the tunes in it. If the page you're viewing actually is an ABC file, then click on the "Import" button at the bottom right to import it.

If you are a user of thesession.org, Tunebook will attempt to import tunes from tune display pages - just navigate to a tune and press "Import". There's no need to open the "ABC" tab in the web page.

If you have tune files on your computer, but no Web server to serve them from, you'll need to upload the files from your computer into Tunebook. To upload tunes to Tunebook, choose "Share Tunes". This will start a Web server to which you can connect using a Web browser on your computer. The address to type into your Web browser is displayed on the screen and the server is also published on Bonjour so you can browse to it if you have a Bonjour-enabled browser. When you connect, you should see a form which allows you to upload ABC files into Tunebook. Simply follow the instructions to upload files. See "Troubleshooting Connections" below if you cannot connect.

ABC files can also be imported into Tunebook's database via iTunes. When your device is connected, click on it in iTunes, then click on the "Apps" tab at the top of the iTunes window. You should see something like this:

The File Sharing panel in iTunes

Here the ABC file "miriam.abc" has been added for import. You can add ABC files to the "Tunebook Documents" list and Tunebook will import them the next time you start it. After importing, Tunebook will remove the files so they don't get imported again. The file "tunedb.sql" which appears in the list is Tunebook's database of your tunes. Do not delete this file unless you want to delete all your tunes. If you do, Tunebook will recreate it, but you'll have lost your tunes. It's possible to transfer a tune database from one device to another by saving the file from one device and adding it to this list for the second device, but be very careful!

Finally, you can create new tunes by choosing "Add New Tune" from the main menu. This allows you to type or paste ABC. If you can get your ABC on the clipboard, say, from an email, you can paste it here, and Tunebook will add all the tunes it finds.

Exporting Tunes

There are two ways to export tunes out of Tunebook: You can email them, or you can connect to Tunebook from a Web browser and download the tunes.

To email a tune, press the email button at the bottom right of the screen when viewing a tune. On OS 3.0 or later, this will display a form allowing you to email the tune to your friends. The email includes the ABC text with a PDF attachment of the sheet music. On earlier versions, the Mail application will be run, and the email will only contain the ABC.

To download tunes from Tunebook, choose "Share Tunes". This starts a Web server to which you can connect from your Web browser:

Tunebook's Web page

When connected, follow the "Tunes" link and you'll be confronted with a list of all the tunes Tunebook contains. For each tune, you can download the ABC, PDF or MIDI versions. You can also download tunebooks as ABC files.

Troubleshooting Connections

When using Tunebook's built-in Web server to import or export tunes, it's sometimes hard to connect. The Web browser may be unable to connect to your device and time out or the device may not be visible in your list of Bonjour services. The most common reason this may happen is if your computer and the iPhone are on different subnets and hence are not visible to each other. Firstly, you won't be able to connect to your iPhone if it is connected to the Internet via the phone network - just as you can't connect to anybody else's phone. You need to have the iPhone connected to your local network via WiFi. If your computer is also connected via WiFi, then all should be well, but if your computer is connected via Ethernet connection may fail because some routers will place WiFi and Ethernet on different subnets. I can't give any advice on this because so much depends on the individual network setup. You may be able to configure your router so that the iPhone is visible to the computer, or you may have to temporarily connect the computer via Wifi. One possibility is to create a local Wifi network on the computer and connect directly.

Limitations

Be aware that the Internet abounds with dodgy ABC files which may cause problems. Some of these date from the days when the ABC specification was less well-defined. Most ABC files created for traditional music are fine, but many automatically-generated ones can confuse software. Particular problems you may run across are files which contain blank lines where they shouldn't, and files which are in the wrong character encoding. Tunebook tries to be lenient with these, but problems still arise. In particular some versions of the ABC specification say that a blank line is permitted after the tune header but before the tune body, but much ABC software, Tunebook included, does not permit this. The symptom of this is that the tune will display with just a title and no body, or the tune may only have the first few lines. You can fix these tunes by displaying them in Tunebook and editing them to remove the spurious blank lines.

Tunebook currently only displays single-page ABC files. Again, those monster automatically-generated ABC files may cause problems.

Tunebook does not handle tunes with multiple titles and will only index a tune under the first title found. This will be corrected in a future update.

License and Acknowledgements

Tunebook is assembled from a variety of Open Source software licensed under the GPL as well as a lot of hard work. The sheet music display is based on the well-known abc2ps application. Playback uses abc2midi and the fluidsynth synthesizer. Voices are adapted from the Fluid soundfonts. Download the source code.