Version 1.4. Revision: October, 2005
Please be aware that this manual is not yet finished. I have to write more and currently it only documents the minimun to start with the LDP language.
For describing the LDP language, in this document I use tags in English, but they are not yet implemented: only the Spanish tags are understood by the parser. LenMus started as a project written in Spanish. The syntax for LDP was also based on Spanish words. As LenMus moved to open source it became clear the need to use tags in English in the program. But LenMus aims at facilitating the user to use his/her own language. Therefore, it was decided to introduce support for set of tags in any other language. Currently this support is not yet available (but I hope to be able to include it as part of 3.0 release).
The LenMus LDP notation language is a general purpose formal language for representing music scores in a platform independent, plain-text and human-readable way. This language is named LDP because I named it after the Spanish acronym for 'Lenguaje de Descripción de Partituras', that is 'Language to Describe Scores'. Why to define a new language instead of using a existing one such as MIDI, MusicXML ?
At the time the LenMus project started it was finally decide to design a new language because:
Nevertheless it was not the objective of the LenMus Project to develop a new representation language. LDP is a pragmatic approach and its development has the direct benefit of forcing me to study un depth the problems to represent music and to enter this information by using an alfanumeric keyborad. Although the internal language for the LenMus project is LDP, the LenMus program will incluye facilities to import and export music scores to MusicXML. Wherever possible, I tried to follow MusicXML structure so that translation to/from LDP and MusicXML would be easily programmed.
Let's see how a very simple score is encoded. The score will be just one measure, in G clef, time signature will be C major (no accidentals) and time signature will be 4 by 4. The measure will have a whole c note. Here is how it would look:
![]() |
(Score (Vers 1.4) (NumInstruments 1) (Instrument 1 (NumParts 1) (Part 1 (m 1 (Clef Sol) (Key Do) (TimeSign 4 4) (n c4 r) ) ) ) )
Let's analyse this code. First note that in LDP all the information is structured as elements. An element is a list of keywords and data values enclosed in parenthesis. An element always starts with a keyword (i.e. NumInstruments) and it is followed by data items. These data items can be just simple data (single word values, such as '1' or 'Sol') or complex data: other elements -- those of you with an information science background will note that this is a LISP like syntax --
Blank space, indentation, tabs and line breaks have no meaning: they are just a visual help for humans to improve readability, and you can use them at your desire or not use them at all. For example, the previous score can be written in a single line as:
(Score (Vers 1.4)(NumInstruments 1)(Instrument 1 (NumParts 1)(Part 1 (m 1 ... ))
Or in two lines, for example as:
(Score (Vers 1.4)(NumInstruments 1)(Instrument 1 (NumParts 1)(Part 1 (m 1 ... ))
The only rule is that you can not break keywords or simple data values. So you can not write, for example,
( S c o r e ( ...))
In the example, we can note that all the score is a list starting with the keyword 'score'. The first data item of this element is also a list, '(Vers 1.4)': it starts with the keyword 'Vers' and has only a simple data item, the number 1.4.
To improve human legibility and understandig it is allowed to include comments. Two consecutive slash characters (//) will be interpreted as the start of a comment and all text until the end of the line will be ignored. For example:
(Score (Vers 1.4) // version 1.4 of LDP is used (NumInstruments 1) // start of score: it will have one voice (Instrument 1 // Start of music for the first voice (NumParts 1) // It is going to be described in a single block (Part 1 // start this only block (m 1 // first measure (the measure number is optional) (Clef Sol) // Clef: Sol (G on line 2) (Key Do) // Key signature: Do (C major) (TimeSign 4 4) // Time signature: 4 4 (n c4 w) // Note. Pitch: C4, duration: w (whole note) ) ) ) )
LDP supports to use a customized set of tags for each language, so that, for example, if you would prefer to encode the scores using tags in Spanish instead of tags in English, you would write:
(Score //the Score and Language tags are the only non-translatable (Language es ISO-8859-1) //specifies to use the Spanish set of tags (Vers 1.4) (NumInstrumentos 1) (Instrumento 1 (NumPartes 1) (Parte 1 (c 1 //note the keyword 'c' (compas) instead of 'm' (measure) (Clave Sol) //note the keyword 'Clave' instead of 'Clef' (Tonalidad Do) (Metrica 4 4) (n c4 r) // duration: r (redonda = whole note) ) ) ) )
To describe the language, Backus Naur like form (BNF) syntax rules will be used. The meta-symbols used are the following:
{ alpha | beta | gamma }means the value can be either alpha, beta o gamma, but only one of them.
Clef := (Clef clef_name [visible] )means that an element of type clef must start with the keyword clef and must be followed by a clef name; optionally, after the clef name it could come an element of type visible.
number := digit+means that a number is a sequence of digits; at least one digit is necessary.
LDP language is case sensitive, so for example, "score", "Score" and "SCORE" will not be taken as the same token.
To reduce the work for typing a score some elements allow a collapsed syntax.
This abbreviation consists on supressing the parenthesis and any blank space, so the element
is reduced to a string. For example,
if element <algo> allows collapsing, then
writting (algo 3 nx)
would be equivalent to writting
algo3nx
,
writting (algo +)
would be equivalent to writting
algo+
, or
writting (algo -)
would be equivalent to writting
algo-
.
A Score is, basically, a collection of Instruments and some optional information such as the title or the author.
score := (Score Version [Language] [Credits] NumInstruments Instrument* )
The Version element is just a number to indicate the LDP language version used to encode the score. For example:
(Version 1.4) the score is encoded using LDP version 1.4
In case you would like to use a different set of tags than the English set or to use non Western characters (ISO-8859-1) the Language element allows to specify these characteristics.
Language := (Language LanguageCode Charset )
Charser := Any ISO charset code name, i.e. "ISO-8859-1"
LanguageCode := Any language code, i.e. "es"
Examples:
(Language es iso-8895-1) use the Spanish set of tags (Language en iso-8895-1) use the English set of tags
The element NumInstruments is used to state the number of voices or instruments to use in the score. It defines the structure of the score. There will be as many Instrument elements as stated in the NumInstruments tags. And each Instrument element will describe the music for a voice.
An Instrument is a collection of Parts, each one describing a block of music for that instrument.
Instrument := (Instrument [ InstrName | number ] NumParts [MIDI_Info] Part+ )
A Part is just a collection of consecutive measures.
Part := (Part number [ NumStaves ] Measure* )
A Measure is a collection of diferent objects, mainly Notes and Rests, but also other elements, such as Clefs or KeySignatures, are possible.
Measure := (m [number] { Note | Rest | Attribute | Notation | Barline | Shift | Option }* )
Attribute := { Clef | KeySignature | TimeSignature }
To simplify writting music in LDP, it is not mandatory to specify a barline at the end of each measure when it is a normal barline (simple line). If no barline is specified it is always assumed to be a simple barline. Otherwise a barline type must be specified. You can specify a barline to be 'invisible' (that is, it will not be rendered, as if it did not exist).
Barline := (Barline Barline_type [Visible] )
Barline_type := { Simple | Double | End | Start | StartRepetition | EndRepetition | DoubleRepetition }
Example:
(m (n c4 n)(n e4 c)(Barline End))
Clef := (Clef {Sol | Fa4 | Fa3 | Do1 | Do2 | Do3 | Do4 | Percussion } [ Visible ] )
Examples:
(Clef Sol) (Clef Fa4)
Key := (Key Key_name [Visible] )
Key_name := A tag from the following table:
Key_name | Key signature | Kae_name | Key signature |
Do | C major | Lam | A minor |
Sol | G major | Mim | E minor |
Re | D major | Sim | B minor |
La | A major | Fa+m | F sharp minor |
Mi | E major | Do+m | C sharp minor |
Si | B major | Sol+m | G sharp minor |
Fa+ | F sharp major | Re+m | D sharp minor |
Do+ | C sharp major | La+m | A sharp minor |
Do- | C flat major | La-m | A flat minor |
Sol- | G flat major | Mi-m | E flat minor |
Re- | D flat major | Si-m | B flat minor |
La- | A flat major | Fa-m | F flat minor |
Mi- | E flat major | Do-m | C flat minor |
Si- | B flat major | Sol-m | G flat minor |
Fa | F major | Re-m | D flat minor |
TimeSignature := (TimeSign TopNumber BottomNumber [Visible] )
Rests can be considered as notes with no pitch, so in LDP notes and rests are instances of a more general concept: noterests. A noterest is either a note or a rest.
The minimum information required to represent notes is its pitch and its duration.
Note := (n pitch duration )
For rests only its duration is needed.
Rest := (s duration )
The pitch is represented by combining the notename, the octave and the accidentals.
The notename is a letter that represents the diatonic step: c d e f g a b
The octave is an integer number indicating the octave of the note, where octave 4 is the central one (a4 = 440Hz). All octaves start with notename c and ends in notename b, so note c4 is the c note just below the a4 note. Octaves range is 0 to 9.
Accidentals are represented by combinations of the signs plus (+), minus (-) and equal (=). They representent, respectively, sharps, flats, and naturals. So, for example, ++ represents a double sharp, and =- represents a natural flat.
With all this, the pitch is just the combination of the previous signs. Examples:
+c4 a sharp C4 note (C of octave 4, the central C) --b3 a double flat B3 note (B of octave 3, the B inmediatly below C4)
Important: In LDP accidentals are not absolute (as in MusicXML) but relative to the context. That is, you must write or not an accidental following the same rules than when you write music by hand in lined music paper. You have to write only those accidental that are not implied by the key signature or that are not implied for a previous accidental in the same measure.
Then, in the following example:
(c1 (Key Fa) (n b4 n))
the eighth b4 note will be a flat b4, as it is in F major key.
It is also possible to specify pitch as a number, and this will be interpreted as the absolute MIDI pitch. For example, 43 will be the central c note (c4). This way of encoding pitch is discouraged as some musical information is lost. This facility has been included to facilitate importing MIDI files and scores written by other programs. Possibly this feature will removed from the language in future versions.
A character to specify the note or rest type (whole, quarter, eighth, ...) followed by dots in case the note or rest is dotted
English US (English UK) | Spanish |
d - double whole, long (breve) | d - cuadrada |
w - whole (semibreve) | r - redonda |
h - half (minim) | b - blanca |
q - quarter (crochet) | n - negra |
e - eighth, 8th (quaver) | c - corchea |
s - sixteenth, 16th (semiquaver) | s - semicorchea |
t - 32th (demisemiquaver) | f - fusa |
x - 64th (hemidemisemiquaver) | m - semifusa |
o - 128th (?) | g - garrapatea |
f - 256th (?) | p - semigarrapatea |
For example: q.
means a dotted quatter note and e..
means
a double dotted eighth note
A notation is the way to describe any additional characteristic affecting the element being described, for example, a note. Notations are classified into three cathegories:
Traditional_notation := { Tie | Caesura | Articulation | Beamed | Tuplet }
Notations are encoded in collapsed syntax, that is, a notation is just a string of one or more characters without blank spaces. The first character determines the type of notation and the remaining characters, when exist, indicates additional characteristics. The following table shows the currently implemented notations:
l | Tied to next note | c | Caesura |
a | Articulations | g | Beamed group |
t | Tuplet |
A character "L" indicates the start of a tie that will end in the next comming note of the same voice, staff and pitch than the one on wich this notation is included. No additional parameters are needed. Example:
(n c4 n l)(n c4 c)(n e4 c)
A quarter C4 note tied to an eighth one, followed by an eighth E4 note.
A character "C" indicates that the rest or note has a caesura. No additional parameters are needed. Example:
(n c4 n c)
Is a quarter C4 note with caesura.
When several consecutive notes have their stems beamed together this is coded by a notation g (group). The first parameter is a plus sign (+) or a minus sign (-) to mean, respectively, that it is the start or the end of a group. After this sign other parameters are possible. When the only parameters specified are the start/end sign, the g element admits a collapsed syntax g+ in the starting note and a notation g- in the endind one. Example:
(n c4 n g+)(n d4 c)(n e4 c g-)
A group of beamed notes, formed by a quarter C4 note, an eighth D4 note and an eighth E4 note.
A tuplet is a group of notes whose duration is modified; normally a graphic element (a tuplet bracked and/or a number) marks this group of notes. The notes in a tuplet are usually beamed together but this is not always the case.
In LDP, to specify the notes that form a tuplet, a notation t (tuplet) must be included in the first and the last notes of the tuplet.
The first parameter is a plus sign (+) or a minus sign (-) to signal, respectively, that it is the start or the end of a tuplet. After the plus sign there must be a number to indicate the tuplet type. For example:
(n c4 c (t + 3)) (n d4 c) (n e4 c (t -))
This example is a triplet of eight notes, that is, the three notes must be played in the time normally allotted for two eight notes.
Additional parameters could be introduced in future to deal with renderization options.
As tuplets are very frequent, to simplify the writting, the tuplet element allows for a collapsed syntax:
(t -) can be written as t-
(t + x) can be written as tx
So, the previous example can be written as:
(n c4 c t3) (n d4 c) (n e4 c t-)
Notation t does not implies beaming. Therefore notations t and g must be combined as needed. Examples:
(n c4 c g+) (n d4 s t3) (n c4 s) (n b3 s t- g-)
(n c4 s g+ t3) (n d4 s t3) (n e3 s t-) (n f4 s t3) (n g4 s) (n a4 s t- g-)
LenMus started as a project written in Spanish. The syntax for LDP was also based on Spanish words. For describing the LDP language, in this document I have used tags in English, but they are not yet implemented in the parser: only the Spanish tags are understood by the parser. As LenMus aims at facilitating the user to use his/her own language it was decided to introduce support for set of tags in any other language. Currently this support is not yet available (but I hope to be able to include it as part of 3.1 release). Meanwhile, if you would like to read or write an LDP score, here is a table with the Spanish tags to use instead of the English ones used in this LDP reference manual.
Element | English tag | Spanish tag |
Barline | Barline | Barra |
Barline types | ||
Simple | Simple | |
Double | Doble | |
Start | Inicio | |
End | Fin | |
StartRepetition | InicioRepeticion | |
EndRepetition | FinRepeticion | |
DoubleRepetition | DobleRepeticion | |
Clef | Clef | Clave |
Instrument | Instrument | Instrumento |
Key signature | Key | Tonalidad |
Measure | m (measure) | c (compas) |
Note | n (note) | n (nota) |
Num.Instruments | NumInstr | NumInstr |
Part | Part | Parte |
Rest | r (rest) | s (silencio) |
Time signature | TimeSign | Metrica |