A description of how to encode scale degrees in **deg and **degree spines.

Scale degrees can be encoded in Humdrum data using the **deg or **degree exclusive interpretations. The difference between these two representation is that *degree also encodes octave information, while **deg does not.

Scale degrees

Here is a basic example of encoding scale degrees, which are integers in the range from 1 through 7:

Scale degrees are relative to the tonic of a key. Below are the scale degrees for E major, where scale degree 1 now represents the pitch class E instead of C in C major.

The interpretation *E: means E major. You should preferably include this key designation in both **kern and **deg spines for more detailed analyses. Other examples of keys include *B-: for B♭ major and *F#: for F♯ major. Minor keys use a lower-case letter for the tonic (see discussion for minor keys below).


Rests can be indicated by the letter r. As an extension to the **deg data format, the letter R can be added after r to indicate that the rest is longer than a particular threshold that is given by a tandem interpretation such as *irest<4 which means small (ignored) rests are shorter than a quarter note (represented in the data at r, or explicitly by rr to differentiate between unthresholded rests which are always a single r. Rests a quarter note or larger are then labeled as rR for a “big” rest. The threshold can also be inclusive such as *irest<=4 which means that small rests are a quarter note or shorter, while big rests are greater than a quarter note. Note that the rhythm value given in the *irest interpretation is in the form of a **recip value.

In the first **deg spine, rests less than a quarter note are labeled rr, while rests a quarter note or larger are labeled as rR. In the second **deg spine, rests a quarter note and shorter are labeled with rr and rests longer than a quarter note are labeled as rR.

Rests are not currently rendered in music notation and are primarily useful for analysis of scale degree melodic contours. The rest duration threshold can be used to allow melodic approaches and departures across small rests. The default setting is *irest<0, meaning that rests of any duration cannot be crossed when calculating melodic approach or departure contours.

More information is given below for how approaches and departures can encode rest information into the non-rest scale degree tokens.

If you want to display rests in music notation, add a zero after r, rr or rR. This will cause scale degree “0” to be displayed in the music notation:

This 0 rest labeling can be done automatically with the shed filter. In the following example long rests are marked in the score with 0 while the short rests remain unmarked:


If the **degree exclusive interpretation is used, octave information will be displayed as subscripts after the scale degree:

Octave subscripts can be suppressed by adding an *Xoctave interpretation. The *octave interpretation can be used to display octave information again:

Using shed filter with scale degrees

If you are using **degree data but do not want to see the octave information in the musical score, the shed filter is an easy way of removing them before printing (but they remain in the original file):

Meaning of the components in the shed filter:

Component Meaning
-x degree Only process **degree spines.
-e Use the following sed-like regular expression substitution
“…” quotes are optional in this case, but it is usually a good idea to include them always. They are required if spaces are found in the regular expression or substitution, for example.
s/X/Y/g Substitute whenever pattern X is found in the string, replace it with the string Y, and do this for all cases on the line (g = “global”).
\/\d+ This is the search string which means a slash followed by one or more digits. The backslash in front of the characters are required to two reasons. For the slash, it is needed to avoid confusing it with the outer s/X/Y/g delimiter between the X and the Y. A plain d without a slash means the letter d, while \d means one of the digits from 0 through 9.
  There is nothing between the last two slashes which means replace the match (X) with nothing.

By default, the input Humdrum data in score (left side of the editor) remains unchanged when there are filters in the file. If you want to see the result of the filter, press control-c (Windows) or option-c (MacOS) to “compile” the filter and replace the original file with the output of the filtering process. The !!!filter: line will change to !!!filter: to indicate that the filter has already been processed.

To convert **degree spines to **deg spines, you can use this filter:

!!!filter: shed -x degree -e "s/\/\d+//g; s/^degree$/deg/X"

The X qualifier on the second substitution command means only process exclusive interpretation tokens.

If you want to see the literal text of a **deg or **degree spine, then use this filter:

!!!filter: shed -e "s/degree/cdata-degree/X"

“cdata” means “chord-like data”, and the subtype is degree (which is optional).

Chromatic alterations

A plus sign (+) can be added after the scale degree number to indicate that it is one semitone higher than the default position in the current key. Two plus signs (++) means that the scale degree is two semitones above the default position in the key.

Likewise - and -- (minus signs) can be used to indicate that the scale degree is one or two semitones lower than the default position for the degree in the key.

Displaying alterations as accidentals

It is still to be decided if the accidental should come before or after the scale degree in the music notation display (and/or should there be a tandem interpretation to control which side the scale degree the accidental should be displayed. It is also still to be decided if the accidental should be relative or absolute. In the current implementation it is relative, meaning that it indicates the number of semitones in the alteration. An absolute display (not implemented) would be to show the accidental of the pitch class in the music notation. Absolute display will be more complicated since the key designation is required before the scale degree in order to determine the default scale degree accidental first.

If you want to display alteration accidentals after scale degrees, use the *accR interpretation (“accidentals reversed”):

Displaying alterations as arrows

To display alterations as up/down arrows after the scale degrees, use the *arr tandem interpretation. *Xarr can be used to return to the default accidental display for alterations.

Notice that two semitone alterations are displayed as a double-tailed arrow.

If you want to display alteration arrows in front of scale degress rather than in front, use the *arrR interpretations (“arrows reversed”):

Styling scale degrees

By default scale degrees are displayed as plain numbers, but other notation rendering styles can be given to them.


Circles can be drawn around scale degrees by adding the *circ interpretation. This style can be canceled by the interpretation *Xcirc. Circles are typically drawn around scale degrees of a bass line.


Boxes can be drawn around scale degrees by adding the *box interpretation. This style can be canceled by the interpretation *Xbox.

Boxes and circles are currently mutually exclusive, so only the most recent *box or *circ interpretation will be followed. This may change in the future, so if you only want circles or boxes to be displayed on a scale degree and not both, use *Xcirc before *box, and *Xbox before *circ to maintain a consistent rendering in the future.


Hats (carets, circumflexes) can be drawn above scale degrees by adding the *hat interpretation. This style can be canceled by the interpretation *Xhat. Hats are typically given to the melodic part’s scale degrees.

Proper display of the hat will depend on what font is used; otherwise, the hat will follow the digit.

Staff placement

By default scale degrees are displayed below the staff, but they can be show above by adding the *above interpretation. The *below interpretation can move the degree display below the staff again.

Scale degrees in minor keys

Minor keys use a lowercase letter in their key designations, such as *c: for C minor and *f#: for F♯ minor. Note that the harmonic minor is the prototype scale for minor keys (not the natural minor). The harmonic minor has a major 7th interval between the tonic and the 7th scale degree, forming a lead tone to the tonic.

To allow conversion between harmonic and natural minors, add H after a 7 scale degree to confirm that it is a major seventh above the first scale degree (or a minor second below the first scale degree). To encode a 7th scale degree in a natural minor key, add N after the 7 for a minor seventh above or major second below the first scale degree.

7N implies B-flat, and since the display is set to C harmonic minor, the N causes a flat to be displayed for the 7th scale degree (N or H on any other scale degree will be ignored).

Major/minor mode markers

If you want to have local information about the modality of each scale degree, append ‘m’ for minor scale degrees, or M for major scale degrees. These markers are for analyses, and do not affect rendering of scale degrees in music notation.

Harmonic and natural minor

If you want to display the scale degrees in music notation using the natural minor scale, add the interpretation *minnat. This means that the scale degrees are based on the natural minor scale, with 7 and 7N meaning a minor 7th and 7+ and 7H meaning a major seventh. The interpretation *minhar can be used to explicitly indicate that the harmonic minor is the prototype scale (or you can switch between the two systems in a single spine by alternating between *minnat and *minhar.

Melodic approach and departure

Signifiers can be added to scale degree tokens that encode the basic melodic contour the note of the scale degree forms with the previous and/or next notes.

Melodic approach

Add ^ before the scale degree if the note is approached by a step up from a lower note (by an interval of a second with any chromatic alteration). Use ^^ to indicate that the note is approached by a leap from a lower note (a third or lower than the current note).

The v signifier indicates an approach down by step, and vv means down by leap.

Stepwise motion is indicated by a thin diagonal arrow pointing in the direction of the approach. Leaps are displayed as thick diagonal arrows, also pointing in the direction of the approach.

Melodic departure

Add a single quote (') after the scale degree and alteration if the note is followed by a step up to a higher note (by an interval of a second). Use two single quotes ('') to indicate that the note is departed by a leap to a higher note (a third or higher than the current note).

A comma (,) signifier indicates a departure down by step, and double comma ,, means down by leap.

Stepwise motion is indicated by a thin diagonal arrow pointing in the direction of the departure. Leaps are displayed as thick diagonal arrows, also pointing in the direction of the departure.

Both approaches and departures can be encoded and displayed at the same time:

Gross versus refined contours

The Humdrum Toolkit deg tool does not distinguish between leaps and steps (so these currently have to be encoded by hand). Instead the signifier ^ is used for both leaps and steps, as well as for v.

To explicitly indicate that the melodic contours do not distinguish between steps and leaps, add the *gross tandem interpretation to indicate that the data encodes gross melodic contours.

If you want to explicitly indicate that the data does encode refined contours (i.e., distinguishing between steps and leaps), then add the *refined tandem interpretation. The presence of double signifiers for melodic contours will otherwise indirectly indicate that refined melodic contours are being encoded.

If you have data encoded with both leaps and steps, but you want to show both with the same arrow style, then the shed filter can be used to select thin or thick arrows for both steps and leaps:

Here is an example to show all approaches as thick arrows:

Contours across rests

The Humdrum Toolkit command deg will not cross over rests to calculate melodic approaches; however, for a proposed extension to deg analysis, here is a representation system for rests breaking up melodic contours (both approaching and departing).

A tandem interpretation can be given in a scale degree spine that describes the duration of rest that can be ignored when calculating melodic contour intervals. For example, the interpretation *irest<4 means that any rests less than a quarter before the scale degree note can be ignored when calculating contours:

Hide melodic contours

If the **deg tokens contain melodic contour information, then you can use the *Xdir tandem interpretation to hide this information from the rendered score:

The *dir tandem interpretation can be used to start showing the melodic contour information again.

An alternate method of hiding particular contours, add a y after the contour signifier:

(Highlighting melodic peaks and troughs.)

Here is an example using the shed filter to remove display of all contours:

Contours across slur/phrase boundaries

In a future extension to the deg command, phrases ({}), slurs ((), and/or fermatas (;) can be encoded in **deg data in order to disallow labeling melodic contours to cross them.

Repeated notes

Implement and describe repeated notes, probably using " for melodic approaches to indicate that the scale degree is approached by a perfect unison. There is a visual problem with the leap up departure, which are two single quotes (''). Also _ could be used to indicate that the current note is tied to the previous note.

Melodic contours across rests

Melodic contours are usually short-circuited by rests that come between the note of the scale degree and a potential approach or departure pitch. A proposed extension to the **deg representation is to categories these rests into two basic categories of short rests that are allowed to be ignored and long rests that cannot be crossed when calculating melodic contour approaches and departures.

The information about the rest can be embedded in the scale degree tokens (p means “pause”):

signifier meaning
p The approach contour crosses a short rest
pp The approach contour crosses a long rest
P The departure contour crosses a short rest
PP The departure contour crosses a long rest

The p or P qualifiers should come before the melodic contour information.

This information is not rendered in music notation (at least currently), but the shed filter can be used to remove melodic contours. Here is an example of removing melodic contours when they cross a large rest:

Here is an example of suppressing melodic contours across any rest type:

Font styling

There are several font-styling interpretations that are described in this section.

Font size

The font size of scale degrees can be set by the *fs: interpretation followed by a font size, such as *fs:80%:

In addition to percentages, there are several symbolic font sizes that can be used:

fontsize percentage
smallest 60%
smaller 75%
small 89%
normal 100%
large 120%
larger 150%
largest 200%

Font style

Scale degrees can be displayed in italic and/or bold:

Font color

Any SVG/web color code can be used to add color to degree display in music notation:

  • crimson is a symbolic color name
  • #00f2 is a hex color code (single digits): the first 0 for the amount of red (none), the second 0 for the amount of green (none), the third number is for the amount of blue (maximum), and the optional last digit 2 is the amount of opacity (12.5%).
  • hsl(180,100%,25%) is a color description in terms of hue (0–360), saturation (0%–100%) and brightness (light).

Solfège display of scale degrees

Scale degrees can alternately be display as chromatic movable-do solfège syllables by adding the *solf tandem interpretation to the **deg data. Use *Xsolf to stop displaying as solfège.

Chromatic alterations with use the following system. in C major, C is do while C♯ di; E is mi while E♭ is me:

flatter   sharper
ra   di
me   ri
se   fi
le   si
te   li

Note that doubly altered notes are not directly represented as well as some singly altered note such as 1-, 3+, 4- and 7+ in a major key.

Hide scale degrees

If scale degrees need to be hidden for some reason in the music notation, there are two possible methods of hiding them: (1) append yy to the token to hide it, or (2) use the *hide interpretation to hide all following scale degrees (*Xhide to start showing them again).

Here is an example of hiding individual tokens:

Here is an example of using *hide, in this case to hide scale degrees that don’t have any useful function in the key:

Scale degrees that have an alteration could also be hidden automatically with the shed filter:

Possible uses of this feature is to encode scale degrees in separate columns for different keys, and show only the degrees in the active key, possibly showing both scale degrees during a modulation between the keys:

In the future key labels will be shown in the notation, making it easier to read. The top row is for scale degrees in C major while the second row is for G major.

Here is an example of using the shed filter to hide degrees automatically in multiple spines if the are altered:


Currently only the first note in a chord token will be displayed. The chord filter can be used to sort chords from high-to-low or low-to-high when giving the data to the deg tool.

Displaying degree data as plain text

The **deg or **degree spine can be renamed to **cdata, or more specifically to **cdata-deg or **cdata-degree. Displaying as **cdata (chord-like data) will show the tokens as text in the notation:

The -deg suffix on **cdata is optional. It will be conveyed to the final SVG image as the deg class, and with this information the degree data can be extracted from the SVG image or stylized with CSS in the image.

Here is an example of automating the display of **deg data as text instead of formatted scale degrees:

Embedded verovio options

There are additional layout controls provided by verovio that can be used to refine the notation. Here is an example, first without the option:

And now with the verovio option:

!!!verovio: topMarginHarm 10

(still working on this example)

Tips for creating a deg score

Documentation for how to create a score with degree data on the command line with the Humdrum Toolkit deg tool will go here.

To do

  • Implement key labels at key designation changes.
  • Implement horizontal lines between degrees.
  • melodic approaches across rests
  • differentiate between repeated notes, secondary tied notes, initial notes

Signifier summary