See About ABC for pointers to explanations of the ABC language.
How to recognise tunes that came from here
Any ABC tunes downloaded from here contain an 'identifier' header line. This is a line that looks like "%%ID:0123cdef" ie, a key of %%ID: followed by a value. Any tune you see containing such a line originated from this site, wherever you see it, and in case of any doubt or disagreement, the version to be found here should be regarded as the most up to date and presumably authoritative unless the person who submitted it (the 'owner') says otherwise. See below for the details of this field.
the Programs
Underneath everything else, this site makes use of external programs to render the notations given here as images, midi, etc. Therefore, this site's understanding of "standard ABC" is defined by what those programs understand by it, and is not discussed further here (see validation for a little more on this).
- Midi
- Midi is generated using abcMIDI.
- Images
- You have some choice of programs when it comes to generating images. You can specify these for each individual
tune, or choose your own default, or fall back on whatever the site is using as a default (currently
abcm2ps).
- abcm2ps. The last time I RTFM on these programs this had a wider range of typesetting and layout options; I tend to prefer it if I'm more interested in the picture than the midi. It's also the only program I know with any support for character-sets other than iso-8859-1. If you need accented characters other than those used in northwestern Europe, you'll probably want to use this.
- Yaps. This parses its ABC in the same way as abcMIDI, and is therefore probably a better choice if you prefer to hear your tunes rather than look at them, since both programs will report the same errors, if any.
Required fields
The ABC format requires that 3 fields (X: T: K:) be present for each tune. The external programs will fail if these are not present. The editor will not allow you to save a tune if these are missing. Apart from these, nothing is required, it's perfectly OK to leave everything else empty. Just fill in whatever you know about it. On the other hand, this format is flexible enough that you should be able to record everything you do know about it. Now there's a challenge. How long before someone comes up with something impossible ? Let me know when you do and we'll see if we can work out a good way to do it, okay ?
A little tweak involving X:
or, the consequences of configurability. You can set the editor page up to hide certain fields, even when they have values. I often find that X: is superfluous to my requirements, and prefer to keep it out of sight in this way. Which leaves me with no way of setting it, and the format requires it ... so a value of "1" is supplied silently in this case to keep things happy. This isn't done for the other required fields.
How this site handles header fields
This is probably more than you ever thought you needed to know. You were probably right, too.
Here is a list of the public fields, with brief comments. Notice that most fields have a 'label'; these are intended to be more helpful for ABC-naïve users than the raw 'keys', and the fields are generally referred to using them, outside the 'raw abc' forms. In a few cases these labels are missing - I realise that there are some of the original keys whose purpose, or even existence, I'm not too clear on - in which case the raw key is used instead, unhelpful or not.
The 'remarks' describe my understanding of the purposes the fields are used for, the sort of information they're expected to hold. I think these are fairly generally (rather than entirely universally) accepted among "the ABC community". Whatever your opinion, and however you're referring to them, I do ask you to please stick with these usages, so as to keep the listboxes working nicely (for all users, whether you want them yourself or not; see below). (If you do have a strong, differing, opinion about any of these, please do contact me and we'll argue it).
Public fields
All the original single-letter ones, of course, plus a handful of extras that I've taken it upon myself to invent because they look useful; as listed in the link above, and discussed below. This means, mostly, that all values for these fields, from all users, will be seen in the listboxes, by all users. This is why I have to encourage people to stick to a single set of conventions for their usage.
Private fields
There may be those who feel a need for meanings and usages of their own that aren't covered by the fields provided. They are, as they should be, entirely free to invent their own, which will be kept, er, private. No values for these fields will be seen by other users, nor will the field names be included in any list offered to other users. I notice there is also the entirely separate 'configure' mechanism that hides particular users' values of the public fields. This is a little tangled, and I think I don't like it. Maybe I should drop the latter in favour of universally-private fields only ???
Defining private fields
I think it was James Allwright's abcMIDI that came up with the idea of writing whatever extra fieldnames you need into the header, preceded by a pair of percent ( '%' ) characters. This is an excellent convention, allowing us to have whatever fields we want, and thereby to confuse ourselves utterly when we come back to a set of tunes in a few years' time and can't remember what we called anything. (It also makes ABC a rather distressing first project to learn SQL on, but never mind that).
The site fully supports this convention. The way it's implemented here is that if it sees a header line starting with
a pair of percent characters, followed by a single word (a combination of any characters except white-space) and
ending in a colon, that word will be treated as a 'header field', and anything that follows the _first_ colon
(including nothing) will be treated as the value of that field. ie, a line
It's worth thinking a little about the names you pick. Being a 'private' field, no-one else sees it - several people could invent the same private fieldname and this site would keep them separate. However, if you were to log in, and download your tunes as ABC, those tunes will contain that field in their headers. If somebody else uses the same fieldname for their different purposes, and mails you some of those; then you've got the same field used for 2 different purposes, and you will probably wish that both of you had given their fields names that were either completely unambiguous about what they were for and how they're used, or sufficiently unique that the other wouldn't have used it. I don't enforce any requirements in this respect, I just suggest that you think about it. Start them with your initials to mark them as yours, maybe ?
It's worth mentioning that the requirement above for the key word to be ended with a colon is significant. There are programs which use a variant of this technique where the colon is absent (in fact, I suspect it's more common, that it's my usage which is the variant). Such lines will not be treated as header values within this site, but will be preserved within the text of the tune, so they will have the intended effect when processed by the relevant program. I need to check this over more thoroughly at some point. That's my intention for what should happen, and I believe it's the case, but I'm not sure I've checked it thoroughly enough. Please contact me (with examples) in case of annoyances with this.
Site-specific headers
As I mentioned above, I've added a few of these '%%' fields, where things I've needed to represent seemed generally applicable. With a couple of exceptions (noted) they seem unambiguous enough that I haven't given them names relating to this site, and no special syntax is looked for in the field values. Nor, so far as I know, do any of these currently have any meaning for any other ABC program.
A few of these are handled in a particular way here, affecting the display in some way :-
- %%Collection
-
This affects the display in considerable ways. See the Collections help page
for details. Results in a 'Collections' page, where tunes are grouped together in this way, and also generates
links back to such a page from View Tune.
On thinking about it, this is cruel and unusual to the point where I wonder if it ought to have a more site-specific name. The use of secondary colons to indicate a hierarchical structuring of the value is a new thing for ABC fields, I think. I'll think harder about this in due course. (Don't worry too much about using it. If I do change the name, any existing values will be preserved; but check before uploading any files that use it). - %%Copyright:
- Because it's important to have one. This receives a small amount of special handling here, in that, when the ABC is being rendered into an image, any value for this field will be shown under the tune. If the value you give includes the word "Copyright" or the © copyright symbol, the text will be left as it is, otherwise the word "Copyright" will be put in front of it. Thus, if you put copyright information into this field, it stays attached to the tune and is visible to all viewers, even if they don't read the ABC, which is as I think it should be. This behaviour is specific to this site, only, the other programs that I know of will ignore this field. But at least the information is there.
- %%Link
-
Anything given as a value for this field will be presented exactly as it is on the View Tune
page. This is, mostly, expected to be an href. I use it with some of the manuscript collections, to show a photocopy
of the page I typed the tune up from; there may be other possible uses (it does not involve providing space to host
such material, you'll have to find that yourself). Write the contents here exactly as you would for an HTML page :-
%%Link: <a href="protocol://machine/path">link text</a> .
While the remainder are just fields like any other, with no particular display (or other) implications :-
- %%Page
- %%TranscriptionNotes
- (see also Z:, who is presumably the writer of any such notes).
- %%Dancenotes
- %%File
- This is definitely too site-specific to have such a general name. Will change this.
see the list of fields for more details.
Pseudo-headers
This is mostly relevant if you want to upload a file of tunes.
There is some database-management type information which is more 'about' the tune than part of it. This is not visible, or available for editing, as ABC headers on this site. However, I think it important for people to be able to download their tunes as ABC and then re-upload them, without losing any information, so I've had to wrap this up as ABC for that purpose. So I refer to them as 'pseudo-fields'. They use the standard '%%' convention, of course, so they shouldn't break anything else.
- %%Private:
- Mark a tune as "private", not to be made visible in the public listings. By default, without this marking, tunes are visible to all comers, but you are allowed to keep a certain proportion of them (50%) to be seen only by yourself (or, to be pedantic, to anyone who logged in using your username and password). This only has one meaning, and thus doesn't take any value, anything after the colon will be ignored. If you don't want it to be private, just don't have such a line.
- %%RenderImageWith:
- Specifies a particular program that this site should use to generate the image for this tune - include a line to this effect in uploaded tunes, or the editor has a set of radio-buttons. Supported values are :- abcm2ps, yaps.
- %%ID:
-
Sets, or attempts to set, the ID number for a tune. This is just what the name looks like, the key that the
entire database system uses to identify the tune. Be careful with this, be very careful. If you take
ABC tunes from this site via "download ABC File", they will include such lines, which identify them as coming from
this site. You are not expected to write these lines for yourself, and whatever value follows the colon should be
left strictly alone, unless you are a) completely sure you know what you're doing, and b) right.
The point is that you could download tunes from here, mix them up with stuff from elsewhere and then submit the resulting file. If you do, you might want them to be treated as accidental (new version rejected), or as deliberate (new overwrites old) (there's a checkbox on the upload form where you say which), but you almost certainly don't want the new and old versions both turning up in the database independently of each other. So we need to know if a tune came from here in the first place, and if so which one it is.
For the sake of completeness, here's what might happen, if you upload a tune containing a %%ID: line.
- If you haven't ticked the 'Accept' checkbox on the upload form, it will rejected.
- Otherwise, the ID will be checked. If it's not within the range of IDs currently in use, it will be rejected. New tune IDs are not assignable this way.
- Otherwise, if the tune exists but doesn't belong to you, it will be rejected.
- Otherwise, it will be accepted, overwriting any previous values.
For the sake of even more completeness - at the moment, the value of this field is recognisable as being 8 characters long, each one being either a number (0-9) or a letters (a-f) (yes, an 8 byte hex number, left-padded with 0s). You don't need to know this, except as a 'spotting these tunes from a distance' rule of thumb. It's not likely to change, but I'm not giving a guarantee because there's no (good) reason for anyone to need one - you never write these things for yourself, and if you're looking for a way to have something recognise it and don't think the key is sufficient, contact me and we'll deal with it properly.
These 2 fields should be present if required in the header of each individual tune they are to apply to, they won't be recognised as "file level" "global" settings (outside a tune header). Nor will they be recognised if you type them in the ABC entry of the tune editor page (there is a separate tick-box for privacy, and you are just plain Not Allowed to change the ID), they apply only to an ABC file upload. That's why I refer to them as 'pseudo' headers. Conversely, they will be included in the ABC generated by an "ABC file download".
A note for ABC2Win users
ABC2Win is an idiosyncratic program, capable of generating ABC that nothing else understands. Various other programs have slowly learnt to cope with some of the problems this gives rise to, but there are still areas where it makes excessive demands on their tolerance. Most notable is the practice of inserting linebreaks between notes and their length-numbers. The "standard" descriptions of ABC (and, as the saying goes, there are many to choose from) say that a linebreak means the end of a staff, so programs that conform to a published standard find themselves told to start a new staff with an unexplained number. This being meaningless, they complain and fail to draw it as intended. This is a common cause of breakage, annoyance and wasted time when importing such tunes into other ABC programs, including those used here.
To give an example, if you have, say,A2 B2 c2 d2 | e2 f2 g2 a2 |]
this should show 8 notes, each of twice the "default" length. If you write it as
A2 B2 c
2 d2 | e2 f2 g2 a2 |]
Error in line <number>: Bad character
<number> 2 d2 | e2 f2 g2 a2 |]