hum2abc manpage

COMMAND

hum2abc -- Convert to ABC+ data for graphical music printing with abcm2ps.

hum2abc [options] [input(s)] [> output]

hum2abc is useful for printing Humdrum scores and can be considered a replacement of the ms command in the Humdrum Toolkit. The program converts Humdrum data into ABC-plus data which can then be printed graphically using the program abcm2ps.

If multiple inputs are given, then all will be converted. Each of the converted files will sequentially be given a new X: number. If no input files are given, then standard input will be used to read a Humdrum file, which will typically come via a command pipe.

Single-letter abc header records

A:   (geographical Area) or (lyrics Author)    B:   (Book) C: (composer) D: (Discography) F: (Filename) G: (Group) H: (History) I: (Information) K: (initial Key) L: (default note Length) M: (initial Meter)

N: (Notes) O: (Origin) P: (Parts) Q: (tempo) R: (Rhythm) S: (Source) T: (title) W: (Words) X: (tune reference number) Z:   (transcription note)

In abc files, some records can occur multiple times. For example, the first T: record signifies the title of the music, while the second T: in the header record indicates the sub-title for the music. You cannot give two -T options on the command line, because the second one would just replace the first one. In order to specify a title and sub-title from the command line you can insert a newline character into the title string, followed by the literal contents of the sub-title record, staring with the T: label. For example:

    hum2abc -T "O Waly, Waly\nT: The Water Is Wide"
 

Will cause these lines in the header record:

    T: O Waly, Waly
    T: The Water Is Wide
 

**kern Translation Notes

• Invisible rests are indicated in **kern data by placing a y after the r character which signifies a rest. Invisible rests are primarily used to align secondary layers of musical voices on a staff. These invisible rests can be revealed in the graphical notation by using the --no-invisible option.
• Cautionary accidentals are indicated by placing an "X" immediately after the accidental sign in **kern data. **kern notes always list the sounding accidental of the notes, while abc encodes the printed accidentals, so cautionary accidentals are necessary for printing purposes. A cautionary accidental is an accidental which would not normally be printed according to the key signature, but which is useful for reminding performers of the correct accidental (such as in the measure after a note alteration).
• Grace notes -- grace notes (which do not have any logical duration) are indicated by placing a "q" in the note token if a slash is to be drawn on the note in graphical printouts, or a "Q" if no slash is to be printed.
• Beams -- beams in Humdrum **kern data are started with L and ended with J. Hum2abc can understand two types of beaming style: (1) explicit beams which are the official encoding method in **kern, and (2) lazy encoding, where only on L is used to start any amount of beaming, and J is used to end any number of beams. Using the explicit beam descriptions complicated sub-beamings are possible. With sloppy beaming information, secondary beams will not be broken to indicate sub-groupings of notes.
• Phrase markers "{" and "}" are currently rendered as dashed slurs above the staff. This may change to brackets or some other style in the future.
• First/second endings
• System bracing -- currently if a file contains exactly two spines of musical data, a system brace will be automatically added to the output. In the future a !!!SYS: record will be defined so that various braces and brackets can be used to group staves in the system.
• !!!title: -- If this bibliographic record is present, then it will override the !!!OTL: record for printing the title of the piece. The contents of the !!!title: can contain special markers such as @{key}. If so, the contents of bibliographic record key will replace that string in the !!!title: record. For example, with these bibliographic records:

       !!!OTL: The Happy Farmer
       !!!ONM: 5
       !!!title: No. @{ONM}: @{OTL}
   

  Then the final title will be "No. 5: The Happy Farmer".
• !!!hum2abc: if this bibliographic record is present in a Humdrum file, then command-line options on this line will be used by hum2abc when converting the file into abc data. Actual command-line options will override any options found in this type of record. Multiple records of this type can be placed in a Humdrum file and will be used. Later lines found in the file will override earlier ones. So, you can append options to a file to override any which are already found in the file. Alternatively, you can prepend this record to a Humdrum file in order to avoid replacing explicit conversion instructions found in the file.

Accented characters

Accented characters written in HTML encodings such as é will automatically be converted to their abc equivalent (the current list is not complete yet). In this case é will be converted to \'e which will be printed as é. Alternatively, you can use abc encoded characters directly in the Humdrum input file for titles, movement designations, composer's name, etc.

Embedded command-line options

Command-line options to hum2abc can be stored inside of a Humdrum file in a !!!hum2abc: bibliographic record. There can be multiple hum2abc records in the input file, and the contents of all records will be parsed. If the same option (such as setting the measure number scheme) is set, the the last one found in the file will be the one used. Embedded options can be overridden by user-supplied command-line options used when running the program.

Marked notes

Programs such as theloc can mark notes which are the result of search matches. Marks are user-assignable characters ( i, l, N, U, V, Z, @, +, |, <, and >) in **kern data.

If an input Humdrum file has an RDF reference record anywhere in the file (or more than one RDF record with different marker characters) in one of the forms (free form text starting with match or mark):

 !!!RDF**kern: @= match
 !!!RDF**kern: += mark 

The hum2abc program will encode the notehead of any notes marked in this case with "@" or "+" will be colored red. The marking color can be changed by adding anywhere in the text of the reference record a string in the form color="#fffff", where fffff is a hex-number value for red/green/blue bytes. color="ff0000" means red, color="#00ff00" means green, and color="#0000ff" means blue. If a single note contains more than one mark, it will be colored according to the first mark found in the note token string.

Here is an example of applying a specific color to marked notes:

 !!!RDF**kern: @= matched note, color="#ff5555"
 !!!RDF**kern: += marked note, color="#5555ff"

Rests cannot be colored by the abcm2ps program.

Running abcm2ps

Example usages of hum2abc in conjunction with abcm2ps:

     hum2abc file.krn > file.abc; abcm2ps -O= file.abc; ps2pdf file.ps
 

The abcm2ps option "-O=" means save the output PostScript file using the same filename base as the input. So in this case, a file called file.ps will be created by abcm2ps.

abcm2ps cannot receive standard input, but hum2abc can:

     transpose -t +P5 file.krn | hum2abc > transpose.abc
     abcm2ps -O= transpose.abc; ps2pdf file.ps
 

Special Cases

Multi-bar rests

If the input file contains one **kern spine, then when there are more than two measures containing only rests, a multi-bar rest measure will be printed. The current algorithm is simple, and will not split properly. For example, if two measure rests contain a repeat sign between them, a two-bar multi-rest measure will be printed, although it should not since it hides the repeat barline.

Tips

-M none

This option supresses the printing of a time signature at the start of the music.

Limitations

• abcm2ps can only handle 2 layers per staff.
• abcm2ps cannot process slurs/ties which start/end in different layers.

Test and example uses of the hum2abc program can be seen on this kernscores webpage.

More example usages of the hum2abc program are available on the hum2abc examples page

Input arguments or piped data which are expected to be Humdrum files can also be web addresses. For example, if a program can process files like this:

       program file.krn

It can also read the data over the web:

       program http://www.some-computer.com/some-directory/file.krn

Piped data works in a somewhat similar manner:

       cat file.krn | program

is equivalent to a web file using ths form:

       echo http://www.some-computer.com/some-directory/file.krn | program

Besides the http:// protocol, there is another special resource indicator prefix called humdrum:// which downloads data from the kernscores website. For example, using the URI humdrum://brandenburg/bwv1046a.krn:

      program humdrum://brandenburg/bwv1046a.krn

will download the URL:

http://kern.humdrum.org/cgi-bin/ksdata?file=bwv1046a.krn&l=/brandenburg&format=kern
Which is found in the Musedata Bach Brandenburg Concerto collection.

This online-access of Humdrum data can also interface with the classical Humdrum Toolkit commands by using humcat to download the data from the kernscores website. For example, try the command pipeline:

      humcat humdrum://brandenburg/bwv1046a.krn | census -k

The compiled hum2abc program can be downloaded for the following platforms:
• Linux (i386 processors) (dynamically linked) compiled on 28 Jun 2012.
• Windows compiled on 29 Jun 2012.
• Mac OS X/i386 compiled on 13 Nov 2013.
• Mac OS X/PowerPC (version 10.2 and higher) compiled on 13 May 2009.

The source code for the program was last modified on 14 Dec 2012. Click here to go to the full source-code download page.