If you have any questions about or problems with Tunebook, email me at jerry @ jhlabs.com.
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 The ABC Notation Website 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 iPad version.
Tunebook displaying a tune
The main screen of Tunebook shows the music you're viewing on the right and a sidebar showing all your tunes and tunebooks on the left. You can show or hide the sidebar by swiping your finger left or right, or simply tapping once on the music display. You can change the behaviour of the sidebar by changing the "Left/Right View" setting. In Left/Right mode, the music display shrinks when the sidebar is shown so that the music isn't covered by the sidebar. When you start up Tunebook for the first time, you won't have any tunebooks, but Tunebook comes with a few sample tunes, which you can view by tapping on "All Tunes" in the sidebar.
Showing All Tunes
To view a tune, simply tap on it in the tunes list.
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. 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 word which looks like a key name, such as "Ador" or "Bm" is a key signature, 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.
You can change the sort order of the tunes by tapping on the buttons below the search bar. You can sort by Index (the order in which the tunes were originally added to the list), Title, Key or Meter.
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 sidebar to see as much of the music as possible. Scroll by dragging, or pinch to zoom in or out.
Disclaimer: I am not responsible for any damage to iPads caused by their falling off of music stands!
Your iPad may go to sleep if you don't touch it for a couple of minutes, which is anoying when you're trying to read music. To prevent this, you can turn on a setting to prevent the it from going to sleep while Tunebook is running. Use this with care, as if you forget about it, your iPad battery may run flat.
Tapping on the music will perform different actions depending on where you tap. Tap in the middle to show or hide th sidebar. Tap at the left or right or the music to move to the previous or next tune in the tune list. Tap at the top or bottom of the music to scroll up or down by one screenful when the music is too long to fit on the screen in one go.
Tunebook can play tunes in a variety of not-very-realistic voices. To play the tune which is being displayed, show the sidebar and tap on the play button at the bottom right. To change the voice, volume or playback speed, click on the instrument 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.
The player controls give a set of eight preset instruments. The iPad version of Tunebook has a full General MIDI sound bank and you can select from more instruments in Settings. If the tune you're playing has guitar chords, Tunebook will attempt to create bass and treble accompaniments using the chords. You can change the instruments used for these in Settings or turn off accompaniments.
To email the tune to your friends, show the sidebar and tap on the action button, then select "Email Tune" from the menu. This will show a mail composition window which will allow you to email the tune in ABC format with a PDF version as an attachment.
To edit the ABC of the tune, show the sidebar and tap on the action button, then select "Edit Tune" from the menu. This displays a split-screen with a text editor showing the ABC for the tune as well as the sheet music. The music display will update as you type. To learn about ABC music notation, go to the abc notation home page.
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:
To create a new tunebook, tap on the "+" button at the bottom-centre of the sidebar. You'll be asked to give the tunebook a name. Type in the name and press Return. A window will appear which shows all your tunes. You can tap on tunes to select them and then tap "Done" to add the selected tunes to the tunebook.
To reorder, delete or rename tunebooks, tap on the Edit button at the top right of the sidebar.
You can delete a tunebook by tapping on the red delete button to its left. Deleting a tunebook does not delete the tunes contained in the tunebook from your tunes list.
To rename a tunebook, tap on the blue details button to its right.
To move a tunebook to a different position in the list, hold down on the stripy button to its right and drag the tunebook to the new position. You can only reorder tunebooks if you are sorting by Index.
To view the tunes in a tunebook, tap in the tunebook in the sidebar. The sidebar will show the tunes in the tunebook. You can view a tune by tapping on it in the sidebar. You can also view all the tunes (up to ten tunes) in the tunebook by tapping on the first row in the sidebar.
To add more tunes to a tunebook, tap on the "+" button at the bottom of the sidebar. A window will apear which allows you to select tunes to add to the tunebook.
To remove tunes from, or reorder tunes in a tunebook, tap on the Edit button at the top right of the sidebar.
You can remove a tune by tapping on the red delete button to its left. Removing a tune from a tunebook does not delete the tunes from your tunes database, only from this tunebook.
To move a tune to a different position in the tunebook, hold down on the stripy button to its right and drag the tune to the new position. You can only reorder tunes if you are sorting by Index.
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.
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.
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.
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 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.
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.
To change Tunebook's settings, press the Settings button at the bottom left of the sidebar. The settings are:
The iPhone version of Tunebook can do most of what the iPad version does, but is necessarily limited by the smaller display. For example, it's just not possible to fit an ABC editing view, the sheet music and the keyboard on the screen all at once.
The Tune List in Tunebook
The iPhone version is centred on the display shown above with tabs for tunes, tunebooks, search, settings and tools. Most of the operations you can perform on tunes and tunebooks are the same as described for the iPad above, the main differences arising from not being able to display a list of tunes at the same time as sheet music.
Tunebook Displaying a Tune
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.
Gérald Ryckeboer has kindly translated this page into French, downloadable as a PDF file.
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 the fluidsynth synthesizer and instruments are from the GeneralUser Soundfont. Please contact me if you want the latest source code or you can directly download slightly outdated source code.