hum2abc manpage

COMMAND

hum2abc -- Convert Humdrum files into ABC plus files which can be converted into PostScript graphical music notation with abcm2ps.

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

-A thru -Z string		Single-character capital letter options will place the given text string into a header record in the output abc file. These options override most (but not all) automatically generated sing-letter abc records. For example to set the title on the command-line to "Hunting Song", you would use the option: -T "Hunting Song". This example would override the automatic generation of title using the !!!OTL: bibliographic record in the input data.
-m number		Write number mesures of music on each text line of the abc output. Usually the number of measures in a text line maps to the number of measures in a system. Hum2abc, however, does not decide this information and instead uses the abcm2ps directive "%%continueall" to allow abcm2ps to decide how to break measures between systems. The default value is one measure per text line.
-n number		Write bar numbers every number measures. If number = 0, then print the measure number at the start of each system (default). If number = -1 or "none", then no measure numbers will be printed. Measures will be numbered automatically unless measure numbers are found in the Humdrum file in the first spine of data. Adding a "b" to the end of a number is equivalent to also using the --box" option to draw a box around each measure number.
--box		Draw a box around measure numbers.
--debug		Print debugging comments along with the output data.
--dir directory		Convert all files in the specified directory. By default, all files which contain the string ".krn" will be converted, this can be changed by using the "--mask" option. If "--dir" is given, then any list of files on the command-line will be ignored.
--filenum string		Append any number found in the input filename to the beginning of the title. The first non-zero number plus any text after the number in the input filename before the file extension will be displayed in the title of the work. The string value is a set of characters which will be placed between the number and the title. For example if --filenum "." is used, and the filename is file03.krn, Then the string "3. " will be prepended to the title string. --filenum "" would prepend "3 " to the title.
--filetitle		Prepend filename (without extension) to title record (T:).
--footer string		Footer string to place at the bottom of each output page when music is printed graphically. The format of the string is the same as the abcm2ps command. The string contains three parts, separated by two tab characters: "left-text tab center-text tab right-text". Several special markers can be used: $D  current date & time $P page number $d date & time of source file   $P0  even page numbers only $F name of file $P1 odd page numbers only $T title of music $V abcm2ps version used to print \n newline (footer/header pieces can be on up to two lines)
--header string		Header string to place at the top of each output page when music is printed graphically. See instructions for --footer.
--label		Explicitly print the bar number in the abc data (so that it is easy to locate measures when debugging or editing).
--landscape		Rotate the music 90 degrees into landscape mode.
--mask pattern		Used in conjunction with the "--dir" option. Specifies a pattern present in files which will be converted in a directory. The default pattern is ".krn".
--no-autoformat		Match the number of measures of music on a text line to match the number of measures printed on a line in the graphical music. Using this option will turn of the automatic layout calculations done by abcm2ps.
--no-invisible		Make all normally invisible items visible (such as invisible rests for layer alignments).
--no-veritas		Turn off veritas checking and printing in abc header.
-p string		Transmit a set of extended abc parameters to abcm2ps. For example, to left-align the title instead of having it centered, then the option would be -p "%%titleleft". If more than one parameter setting needs to be specified, separate them with the string "\n": -p "%%titleleft\n%%titlefont Times-Italic 20". A full listing of all abcm2ps parameters can be found here. Abcm2ps parameters which can be set directly by options to hum2abc should not be set at the same time by both methods. Only the last -p option on the command-line will be recognized.
--scale number		Sets the printed music magnification. The default value is 0.75. -s is an alias for --scale.
--spacing number		Sets the abcm2ps parameter "%%notespacingfactor. The default value is 1.414. Lowering the value towards 1.0 will spread out the music and lower the density of the music. Raising the value towards 2.0 will compress the music, allowing for more notes on a system.
--TT string		Build a title from multiple reference records. Reference records will replace @{key} patterns in the string.

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 comman 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 accientals 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. (There is a bug in abcm2ps which causes dashed slurs to become solid when a newline occurs).
• 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. 1: The Happy Farmer".
• !!!hum2abc: if this bibliogrphic 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 designiations, 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.

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 they should not.

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 avaliable on the hum2abc examples page

The compiled hum2abc program can be downloaded for the following platforms:
• Linux (i386 processors) compiled on 3 Dec 2008.

The source code for the program was last modified on 3 Dec 2008.