Contact

If you have any questions about or problems with Tunebook, email me at jerry @ jhlabs.com.

Tunebook and iOS 13

iOS 13 introduced a bug where it was no longer possible to transfer ABC files to Tunebook. This is related to the fact that the ".abc" extension for ABC files is also used by the Alembic 3D file format. A workround is to rename the ABC file to have the extension ".txt" instead of ".abc".

I have a fix for this problem, but unfortunately, Apple have rejected the update because Tunebook and Tunebook for iPad have the same functionality which contravenes a new App Store rule. This leaves me with the choice: Stop supporting one of the two apps, make the two apps just support iPhone or iPad respectively, or stop updating altogether., The first two will require some of my customers to purchase the other app and migrate all their data to it. I consider this unacceptable and so as things stand, Tunebook will not be updated for the forseeable future. I am appealing against the decision, but things don't look good. I'd like to apologize to all my users. This is out of my control and I'm not happy about the situation.

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 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.

A note on versions. Tunebook was originally written when the iPhone first appeared. When the iPad was released, I wrote a new version which had a different user interface which took advantage of the larger screen, called Tunebook for iPad. It's now possible to create universal apps which have different version for different devices and Tunebook is now universal. I had to decide what to do about the two different apps and decided to make them both identical. That is, there are now two apps, Tunebook and Tunebook SD, but they are both the same. The reason for doing this was that I couldn't discontinue one of the two without abandoning users of it and forcing them to pay again, as well as having to migrate all their tunes to the new app. It's inconvenient, but it's the best I could do. You now only need to buy Tunebook once to have it on iPad and iPhone/iPod.

This documentation mostly concentrates on the iPad user interface, with notes on the differences for the iPhone version at the end.

Getting Started

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.

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 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 annoying 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.

Playing Tunes

Tunebook can play tunes in a variety of not-very-realistic voices. To play the tune which is being displayed, your first need to make sure the play controls are visible. The play controls are in a bar underneath the tune display and can be shown or hidden by tapping on the button at the bottom right of the sidebar. Tap on the play button to play the tune. The time slider allows you to skip in the tune, and the rewind button skips back to the start of the tune. To change the voice, volume or playback speed, click on the playback settings 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, but 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.

Playback Controls

Editing Tunes

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.

Showing All Tunes

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 new tunebook, go to the tunebooks list and 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. You can add more tunes later on by selecting the tunebook and pressing the "+" button again.

Creating, Deleting and Reordering Tunebooks

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.

Viewing Tunebooks

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.

Adding, Removing and Reordering Tunes in Tunebooks

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.

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 many ways to import tunes into Tunebook: You can browse for ABC files on the Internet using tunebook's builtin Web browser, connect to Tunebook from a Web browser and use a form to upload files into it, use iTunes file sharing, send tunes from another application such as DropBox, or you can enter new tunes in a text editor.

To browse for tunes on the Web, tap the Settings button and select "Import Tunes from Web" (on the iPhone, this is in the "Manage" tab). 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 top right to import it.

If you are a user of thesession.org, find a tune and click the "Download ABC" button below it to import it.

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.

If you have a DropBox account and the DropBox app, the easiest way to import tunes is to put the ABC files into your DropBox folder, run the DropBox app, select the ABC files and choose "Tunebook" from the "Send To" menu.

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 many ways to export tunes out of Tunebook: You can email them, send them to another application such as DropBox, use AirDrop to send to other devices, use iTunes on your computer, or you can connect to Tunebook from a Web browser and download the tunes.

To send the tune to another application, print, or email the tune to your friends, show the sidebar and tap on the action button. This display a menu, the contents of which vary with device and iOS version. Choose "Share ABC", "Share PDF" or "Share MIDI" to send the file to another application, print or email it. Choose "Email Tune" to email the tune to your friends. 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.

DropBox

If you have a DropBox account, this provides an easy way to transfer tunes in and out of Tunebook. To use this, you need to have the DropBox app installed. To export a tune to your dropbox folder, choose "Share ABC" from the action menu and choose DropBox from the "send to" menu. To import a tune from your DropBox folder, do the same thing in the DroBox app and choose Tunebook as the app to send to.

The Web Server

To download tunes from Tunebook using a Web browser, choose "Start Web Server" from Settings. 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.

Settings

To change Tunebook's settings, press the Settings button at the bottom left of the sidebar. The settings are:

Tunebook on the iPhone

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

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.

Troubleshooting

Gray bar at the bottom of the screen hiding the controls?

This is a problem introduced in version 3.2.12 and fixed in 3.2.13. If you have this problem, you can make the shortcuts bar go away by tapping in the search field to show the keyboard, then tapping the button to hide the keyboard (at the bottom right of the keyboard). There's also a global setting in General>Keyboard>Shortcuts which will turn off this bar for all apps.

No Sound?

One problem which seems to come up frequently is no sound when playing back tunes. The first thing to note is that Tunebook uses the iOS non-music player, which means that it honours the Mute setting on your device. Make sure Mute is turned off. Otherwise, this is usually due to a problem in iOS where the device gets confused and thinks that it has headphones or a dock plugged in, or is muted. This affects all apps which generate audio, but not apps which use the music player to play from the music library, which has separate settings. To fix this problem, try the following in turn:

One of these will usually restore sound. If not, get in touch.

Can't connect to Web Server?

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.

Crashing or freezing?

If Tunebook freezes or crashes, it is very useful to have a crash logs from you to help me diagnose the problem. These logs contain information about what Tunebook was doing at the time of the crash and contain no personal information. To find the log files, sync your device, then locate the log file for Tunebook using one of the paths given below. The log file’s name should start with the word "Tunebook".

Problems with a specific tune?

If Tunebook has problems of any sort displaying or playing a tune, it would very helpful if you could email a copy of the ABC for the tune to jerry@huxtable.com. I'll attempt to fix the problem for a future update.'

For French Speakers

Gérald Ryckeboer has kindly translated this page into French, downloadable as a PDF file.

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 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.

Privacy

Tunebook does not collect or store any personal information. It has no accounts and does not ask for any personal information. It contacts no servers apart from any which you may visit using its built-in Web browser. Tunebook has no access to any information from the Web browser though.