Layout extensions

From HumdrumWiki

This page describes layout extensions for Humdrum files which are used to provide hints on how to display data as graphical music notation. See also Andreas Kornstädt's layout representation which is designed for explicit note-level layout information in parallel **layout spines which accompany **kern spines in the data.

All layout markers start with the string LO: (upper-case "LO" followed by a colon character), and can be encoded in either global or local comments. When encoded as global comments, the layout information applies to the entire score. When encoded in local comments, the layout information applies to a particular spine or sub-spine. Local layout settings may apply specifically to the next note/rest in the given spine, or to that particular spine in general.

The structure of a layout code consists of three fixed parameters separated by colons, followed by optional key/value pairs for additional parameters. The two fixed parameter fields are:

1. LO: -- the marker to indicate the start of a layout code embedded in the local/global comment.
2. A layout code. Official codes (as found listed on this page) are in upper case. Unofficial codes for non-standard uses should be in lower case.

Both tags and layout codes can have characters in the range: [A-Za-z0-9_.-] (letters, numbers, dash, period, and underscore).

Following these three fixed parameters, a series of key/value pairs for optional parameters for the given layout code may be given. Each key/value pair is separated from the fixed parameters and each other by a colon (:). Keys are strings of characters similar to tags and layout codes. Official keys for official layout codes are usually in lowercase (plus single-letter uppercase names). Unofficial keys for official layout codes should be in uppercase and more than one character to avoid overlap. Keys for unofficial layout codes can be in mixed case if the first letter is lower case. Following the key tag is an equals sign (=) followed by the value for the parameter, with no intervening spaces (unless the value starts with a space). Any characters are allowed in the parameter field except for a colon (:) or equals sign (=). If one of those two characters are required, then encode the colon as : and the equals sign as =. Since the ampersand (&) is used as an escape code for the colon and equals code, it therefore must also be escaped using the character sequence &.

Parameter keys following the first two fixed parameters optionally do not need to be associated with a value. In that case the equals sign must be omitted. Any parameter which expects a value but posses an empty string as its value should also not include the equals sign.

Local layout codes should not be mixed with local non-layout codes on a given line in the data so that regular expressions can be used to selectively remove layout codes from the data, such as with the command:

   egrep -v '^!!?LO:|\t!LO:' withlayout.krn > nolayout.krn

or in an informal manner which presumes no other text sequences "</tt>!LO:</tt>" other than within layout markup in comments:

   grep -v '!LO:' withlayout.krn > nolayout.krn

In both of the example grep commands above, the search string must be in single quotes to prevent the command-line interpreter from trying to process the exclamation points (!).

1 Layout examples

!!LO:PB

Meaning: Default layout set, page break at this point in the data.

!!LO:PB:g=1

Meaning: Layout group set "1", page break at this point in the data.

 !!LO:PB:n=5

Meaning: Default layout set, page break, following page is numbered page 5.

  !!LO:PB:g=P

Meaning: Page break for use when the notation is for a single instrumental part.

  !!LO:PB:g=src1

Meaning: Page break for the tag-set src1.

  !!LO:PB:g=src1
  !!LO:PB:g=src2

Meaning: Page break for the two different tag-sets src1 and src2. The page breaks may or may not occur at the same position in the score. The tags src1 and src2 could mean two different editions of the same score which have page breaks in different locations, or it could mean that when printing the score in a certain size, the page breaks should occur a the specified locations, since different amounts of music can be fit on a page depending on its size.

  !!LO:PB:g=src1,src2

Meaning: Page break for the two different group sets src1 and src2. The page breaks for both of these labels occurs at the same point in the score.

2 Official layout codes

The following sections of layout codes are allowed in the third fixed parameter position in a layout comment. Official codes should contain capital letters (plus numbers, dash(-), period (.) and underscore(_)). Unofficial codes should contain at least one lower case letter at the start of the code.

2.1 Fixed-meaning parameters

All layout codes understand the following parameters (or may ignore them when not appropriate):

2.1.1 Group parameter (g)

The g parameter allows for layout codes to be filtered according to text tags. If a layout directive does not contain the g parameter, then the layout directive should always be processed. If the layout directive contains a g parameter value, then that layout directive should only be followed if a tag found in the g list matches to a set of tags which should be processed.

The group parameter value consists of a set of tags which contain only letters [a-zA-z], digits [0-9], dashes, and underscore characters. Multiple groups can be given by separating them by a comma (,), with no space between the comma and the tags.

2.1.2 Subtoken parameter (n)

The n parameter allows for addressing a particular subtoken. Typically subtokens are separated by spaces in a token, such as "8C 8E 8G" for an eighth-note c-major triad chord (multi-stop), but this will depend on the exclusive interpretation format. The n parameter can be used to indicate which subtokens the layout parameter should be applied to. Multiple sub-tokens can be separated by commas (without spaces). The first subtoken is referenced as subtoken "1", which is the left most subtoken in the token. Example:

**dynam
!LO:DY:Y=40:n=1
!LO:DY:Z=20:n=2
mf mp
*-

This means place the "mf" dynamic at Y=40 and the "mp" dynamic at Z=20 (in other words place the mf dynamic under the staff at Y=40, and place the "mp" dynamic over the staff at Z=20.

2.1.3 Positioning parameters (X, x, Y, y, Z, z)

To place objects precisely in the final layout there are 6 parameters: X, x, Y, y, Z, and z. Spacing units are one-tenth of the distance between successive lines on a staff. The values may be floating point, but the fractional part may be ignored. X/x relate to horizontal positioning, while Y/y and Z/z relate to vertical positioning.

3 Staff/systems layout codes

3.1 LO:PB (page break)

PB stands for "page break". It is used to indicate where there is a new page occurring in the score.

Key parameters recognized for use by the PB code (when appropriate):

• num= -- the given value is the page number for the page displayed for data following the given PB code (could be any text as well, such as roman numerals).

Page breaks (and line breaks) should be encoded in global comments. However, page/line breaks for parts can be encoded as local comments, and the tag "P" should be used specifically for this meaning: the default page-break points in the part when a single-instrument part is being produced.

3.2 LO:LB (line break)

LB stands for "line break". This code indicates that the musical system is broken at this point and a new system is starting. A page break (PB) code also functions as a LB code.

LB (and PB) codes must appear just before a barline and after the last note/rest data for the previous measure (although an "invisible" barline can be used to break a line).

  =16
  1c
  !!LO:LB
  =17

Meaning: there is a line break between measure 16 and 17 in the score.

Key parameters understood by the LO:LB code:

3.2.1 LO:LB:i (indented linebreak)

• i -- indent the system on the next line following the line break. In the future, an value may be given specifying the amount of the indent (if an amount is not given, then it is up to the layout-producing program to decide on the distance to indent). The i key parameter for indenting can also be used with LO:PB when it is used as a line-break code.

3.3 LO:HIDE / LO:SHOW

HIDE is used to indicate that a particular part is explicitly not supposed to be displayed on the musical system. Often parts will not be displayed on a system in an orchestral score if their part contains only rests for that particular system (except for the first system in the movement). The HIDE code is not intended for this situation which should be deduced automatically for an explicit or automatic layout of the score, but as a more formal indication that the part should not be displayed. A part can be hidden for two primary reasons:

1. The part contains only rests as described above.
2. The part is implicitly doubling another part. For example, the cellos and basses usually play the same music from the same score. However, the basses are transposing instruments. Therefore, in a Humdrum data file, the two parts should be encoded separately in two separate spines. To generate a graphical score from the Humdrum data, add a !LO:HIDE comment to the bass part to suppress its display in the score.

The LO:SHOW code can be used to turn off the effect of the LO:HIDE code. The SHOW code is also used to force the display of parts when they only contain rests for the entire system, if the layout algorithm would prefer to suppress the part. To return to an undefined display state, both the HIDE and SHOW codes can take an optional key parameter called "auto"

 !LO:HIDE:auto
 !LO:SHOW:auto

Meanings: Any explicit HIDE or SHOW command for the current part is no longer in effect. The prevailing layout algorithm can decide to hide or show the part as it see fit.

HIDE and SHOW codes are intended for use on complete systems. If they occur within the middle of a system (between the start of a system and any notes/rests), then they will not be applied until the next system.

3.4 LO:TX (text)

The LO:TX code is used to place arbitrary text in the score. The "t=" parameter gives the text to place in the score. Other key parameters:

• u -- text is to be placed above the system (if in a global comment) or the staff (if in a local comment).
• d -- text is to be placed below (down) the system (if in a global comment) or the staff (if in a local comment).
• i -- text should be in italic (default is roman).
• b -- text should be in bold (default is roman).
• bi -- text should be in bold italic (default is roman).
• sz= -- the size of the text. Allowed values are "large" or "l" (as in the size of a movement designation, such as "Allegro"), "small" or "s" for 75% of normal, "tiny" or "t" for 50% of normal. If no s= parameter is given, then display in the normal size (using as the font size of text such as "dim." and "cresc.".
• cj -- center the text on the next item found in the Humdrum data score/part. The default justification is left-justify.
• rj -- right-justify the text on the next item found in the Humdrum data score/part. The default justification is left-justify.
• hide -- used to suppress printing of the text, but preserving it in the data, for later display.
• x= -- indicates the diatonic steps above/below the bottom line on the staff. x works in conjunction with u and d. If neither u or d is given, then u will be assumed. With u, the value of x indicates the number of diatonic steps above the top line of the staff on which the text is to be placed. For example: "u:x=0" means to place the baseline of the text on the top line of the staff. "u:x=4" means to place the baseline of the text two ledger lines above the staff (C6 with a treble clef). "u:x=-4" means to place the baseline on the middle line of a five-line staff. For d the direction of "x=" is reversed and in reference to the bottom line of the staff. The text can be placed on the centerline of the 5-line staff with either "u:x=-4" or "d:x=-4". Two ledger lines below the staff is "d:x=4".
• c= the color of the text. Color is either a text label derived from the standard HTML/CSS names: 17 standard color names are: aqua, black, blue, fuchsia, gray, grey, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. Other recognized color names: orange, pink, and brown. Or the color can be a hex RGB triplet prefixed by the "#" character, such as #ff0000 for red, or it can be three numbers from 0 to 100 separated by commas (and no spaces) to describe the RGB values, such as "100,0,0" for red.

Example:

!!LO:TX:d:i:rj:t=D.C. al fine
==

Meaning: place the text "D.C. al fine" below the staff in italics, right-justified on the final barline (which is the next data line following the layout code). Here is an example of some of the text layout features:

**kern	**kern
*clefG2	*clefG2
*k[f#]	*k[f#]
*M4/4	*M4/4
=1-	=1-
4c/	2aa\
4d/	.
4e/	2gg\
4f/	.
!LO:TX:i:rj:t=fine	!
=2||	=2||
!	!LO:TX:bi:z=5:t=ritardando
4g/	2ee\
4a/	.
4b\	2dd\
4cc\	.
=3	=3
4b\	2dd#\
4a/	.
!LO:TX:b:X=-15:Z=15:t=ad lib.	!
!	!LO:TX:Z=15:cj:t=reflectively
4g/	2ee\
4f/	.
=4	=4
4e/	2ff\
4d/	.
2c/;	2gg\;
!LO:TX:i:rj:X=20:t=D.C. al fine	!
=:|!	=:|!
*-	*-
!!muse2ps: z21c200v190,200s^[(..)]^

3.5 LO:SGENO (segno sign)

The LO:SEGNO code will produce a segno sign in a score. Currently the muse2ps program will only recognize the code in a global comment: !!LO:SEGNO. Currently the SEGNO code has no parameters, and currently will only be processed if preceeding a barline.

3.6 LO:REH (rehearsal marks)

The LO:REH code will produce a rehearsal mark. The t= parameter is used to specify the letter or number for the mark.

**kern
*M4/4
=1-
4c
4d
4e
4r
!!LO:REH:t=A
=2
4g
4a
4b\
4cc\
!!LO:REH:t=Aa
=2
4dd\
4dd\
4ff\
4ee\
==
*-

4 Repeat markers

4.1 LO:REP (repeat endings)

The LO:REP code is used to draw ending brackets for 1st, 2nd endings. Parameters are: start which indicates the start of a ending, such at start=1 for start of the first ending. Endings can be terminated with two possibilities: stop=1 will stop the first ending, causing the repeat bracket to be fully closed with a down-tick. open=1 will end a repeat line without a down-tick at its end.

**kern
*M4/4
*>[A,A1,A,A2,B]
*>A
=1-
1c
!!LO:REP:start=1
=2
*>A1
1d
!!LO:REP:start=2:stop=1
=3:|!
*>A2
1e
!!LO:REP:open=2
=4||
*>B
1f
==
*-

5 Note-level layout codes

Layout directions on the note or chord level can be given as local comments occurring immediately before the actual data token (but may be interrupted by global comments, reference records, or additional local comments). They have a similar for to global layout comment, except that they start with one exclamation mark (!). Example:

 !LO:S:u

which means that the slur in the next (non-null) token in the data should go above the notes to which it is attached.

All note-level layout codes have a set of implicit parameter key which are integers representing the nth note in a multi-note token (chords). If no number is given as a parameter key, then the first note (1) in the token is the one to which the layout directive applies. Some note-level layout codes apply to all notes in a chord, so the note number is not needed in those cases. Here is an example code which is applied only to the second note of the following token:

 !LO:X:2

So whatever the X layout code is supposed to do, it will only do it to the second note in the following chord.

5.1 LO:N (note)

N stands for "note". It is used to indicate syle settings for notes. The position parameters X, x, Y, y, Z, and z apply to N layout directives, although only X or x have a conventional function:

**kern
*clefG2
*k[]
=1-
*^
4a\     4cc/
!       !LO:N:X=-5
4a\     4cc/
!       !LO:N:X=5
4a\     4cc/
!       !LO:N:Y=-55
4a\     4cc/
!       !LO:N:z=2
4a\     4cc/
*v      *v
==
*-

5.1.1 LO:N:smy/smY Stem length

The length of stems on notes can be adjusted by using the smy and smY parameters on notes. Both parameters can be given a value which is in units of 1/10th of the distance between staff lines. The smy parameter is used to adjust the stem lengths from the default position of the typesetting program (which may vary between programs), and the smY parameter is used to set the absolute length of the stem. Positive values are away from the notehead, and negative values are towards the notehead (unlike the Y/y which have fixed directions relative to the page).

**kern              **text
*clefG2             *
=1-                 =1-
!LO:TX:Z=20:t=smy   !
!LO:N:smy=-10       !
4d                  -10
4d                  0
!LO:N:smy=10        !
4d                  10
!LO:N:smy=20        !
4d                  20
=2||                =2||
!LO:TX:Z=20:t=smY   !
!LO:N:smY=20        !
4d                  20
!LO:N:smY=30        !
4d                  30
!LO:N:smY=40        !
4d                  40
!LO:N:smY=50        !
4d                  50
==                  ==
*-                  *-

5.1.2 LO:N:bmy/bmY Beam height

When adjusting the stems of multiple notes grouped together with a beam, the bmy and bmY parameters should be used instead of smy and smY (which should only be used on isolated stems). The bmy/bmY layout parameter should occur just before note which starts the beam.

5.1.3 LO:N:vis Visual appearance of notes

A note's visual appearance can be adjusted to be different than that of the logical duration of the note by using the vis parameter. The value for the vis is the **recip rhythm of the visual representation of the note.

**kern
*clefG2
=1-
*^
4f\	4cc/
!	!LO:N:vis=2
4f\	4cc/
!	!LO:N:vis=8
4f\	4cc/
!	!LO:N:vis=4..
4f\	4cc/
!	!LO:N:vis=0
4f\	4cc/
!	!LO:N:vis=000
4f\	4cc/
*v	*v
=
*-

There are several other symbolic values for vis which can be used to display different notehead shapes. The value "dot" is used to replace the entire note with a dot symbol. This allows for old-style notations where a note crosses a barline, and the tied portion of the note is represented by a dot on the other side of the barline:

**kern
4c
4d
4e
!LO:N:vis=2
4f
=
!LO:N:vis=dot
4f
4g
4a
4b
==
*-

A more proper way of doing this with the correct sounding result is to add hidden ties between the two quarter-note F4's. This can be done by hiding the tie between the note:

**kern
4c
4d
4e
!LO:N:vis=2
[y4f
=
!LO:N:vis=dot
4f]y
4g
4a
4b
==
*-

Notes can also be hidden completely by adding a "yy" string to the note.

**kern
4c
4d
4e
!LO:N:vis=2
[y4f
=.
4f]yy
4g
4a
4b
==
*-

Using "x" as the vis value will generate an x-shaped note suitable for percussion notes, or for other visual purposes:

**kern
4c
4d
4e
!LO:N:vis=x
4f
4g
4a
=
*-

5.2 LO:S (slur)

S stands for "slur". It is used to indicate style settings for slurs. See the examples page for slur layout codes.

Key parameters recognized for use by the S code (when appropriate):

• a -- the slur should be placed above the notes which it is attached.
• b -- the slur should be placed below the notes which it is attached.
• ab -- the slur is s-shaped, and starts above the first note to which it is attached, and then attached below the note attached to its endpoint.
• ba -- the slur is s-sharped, and starts below the first note to which it is attached, and then attaches above the note at the slur's endpoint.
• id= -- a slur id number to indicate where the matching endpoint is located in the score. This is used for complicated slur cases, particularly when a slur starts in one voice, and ends in another. But id= may also be used to slur across staves. The value for the id key is any string which does not contain a colon (:) or tab character. The same id value can be used multiple times in a score, as long as slurs which use the same id value do not overlap in the score sequence.

5.3 LO:SC (staccato)

SC stands for "staccato". It is used to indicate style settings for staccatos. See the examples page for staccato layout codes. This code will probably be converted in the future to a more generalized articulation code (probably LO:AR)

Key parameters recognized for use by the S code (when appropriate):

• a -- the staccato should be placed above the notes which it is attached.
• b -- the staccato should be placed below the notes which it is attached.

6 Dynamics codes

6.1 LO:DY (dynamics)

DY stands for "dynamics". It is used to indicate style settings for dynamics (letter abbreviations, such as p and mf). The "DY" code can be applied to dynamics encoded in **dynam (and in the future, **dyn) spines. The directive can also be used in **kern spines where the first non-null token in the same sub-spine contains a quasi-dynamic marking such as "z" for sf or "zz" for sfz which are attached to notes since they are local accentuations of notes rather than actual dynamics.

Examples:

**kern
!LO:DY:X=-10
4czz
*-

Meaning: place the dynamic marking "sfz" one staff-line space to the left of the left-hand side of the quarter-note C4.

**kern   **dynam
!        !LO:DY:Y=35
4c       f
*-       *-

Meaning: place the dynamic marking "f" three and a half staff-line spaces below the bottom of the staff, with the horizontal position determined by the typesetting program.

**kern   **dynam
!        !LO:DY:Z=15:X=-20
4c       p
*-       *-

Meaning: place the dynamic marking "p" one and a half staff-line spaces above the top of the staff, with a horizontal position 2 staff-line spaces before the lefthand side of the quarter-note C4. (The baseline of the text is the reference point for vertical positions, to if Z=0, then the dynamics text will rest on the top line of the staff).

6.1.1 LO:DY key parameters

6.2 LO:HP/LO:HPZ crescendo/decrescendo signs

The style of crescendo/decrescendo signs (also called wedges or hairpins) can be controlled by LO:HP and LO:HPZ for the starting and ending sides of the slur, respectively.

X, x, Y, y, Z, z parameters are similar to other layout codes.

6.2.1 cresc./decresc. text

When you want to display "cresc." instead of a crescendo sign, add an "X" after the markers as in the following example. The cresc. or decresc. can also be indicated as text with the LO:TX directive, but this would be a more analytical encoding of the dynamic marking:

**kern	**dynam
*clefG2	*
*k[]	*
*4/4	*
4c/	p
4d/	<X
4e/	(X
4f/	(X
=	=
4g/	(X
4a/	(X
4b\	[X
4cc\	f
=	=
*-	*-

A dash can be indicated after the cresc./decresc. word by adding the parameter key dash:

**kern	**dynam
*clefG2	*
*k[]	*
*4/4	*
4c/	p
!	!LO:HP:dash
4d/	<X
4e/	(X
4f/	(X
=	=
4g/	(X
4a/	(X
4b\	[X
!	!LO:DY:Y=40
4cc\	f
=	=
*-	*-

The default label cresc./decresc. for interpreted (de)crescendos symbols can be change by giving alternate text with the t parameter:

**kern	**dynam
*clefG2	*
*k[]	*
*4/4	*
4c/	f
!	!LO:HP:dash:t=dim.
4d/	>X
4e/	)X
4f/	)X
=	=
4g/	)X
4a/	)X
4b\	]X
!	!LO:DY:Y=40
4cc\	p
=	=
*-	*-

**kern	**dynam
*clefG2	*
*k[]	*
*4/4	*
4c/	f
!	!LO:HP:dash:t=diminuendo
4d/	>X
4e/	)X
4f/	)X
=	=
4g/	)X
4a/	)X
4b\	]X
!	!LO:DY:Y=40
4cc\	p
=	=
*-	*-