Humdrum Extras

hum2abc manpage


COMMAND

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

SYNOPSIS

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

OPTIONS

-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 single-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 measures 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 $Ppage number
    $ddate & time of source file   $P0 even page numbers only
    $Fname of file $P1odd page numbers only
    $Ttitle of music $Vabcm2ps version used to print
    \nnewline (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.
--no-tempo Do not include tempo markings with movement designations when creating a Q record.
--no-mark Do not mark (with color) notes if they contain marks.
--no-slur Do not print any slurs. ABC/abcm2ps cannot display slurs which start and stop in different spines/sub-spines, so this option is useful if unmated slurs continue to the end/start of the composition.
-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. A temporary non-standard abcm2ps option called %%nostems is actually parsed by the hum2abc program to globally suppress the printing of stems on noteheads in the file. By default hum2abc will not place stems on notes with no rhythms, but by using the %%nostems parameter, notes with rhythmic values will also be printed without stems.
--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.

DESCRIPTION

    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.

EXAMPLES

ONLINE DATA

    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:
    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

DOWNLOAD

    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.