themebuilderx manpage

COMMAND

themebuilderx -- Create search entries for use with themax

--poly		Extract multiple monophonic entries from a polyphonic data file.
-E		Suppress extra fields (key and meter descriptions)
-r		Include rhythmic fields in output
-p		Include pitch fields in output (default behavior)
-P		Suppress pitch fields in output (used in conjuction with -r to output only rhythmic entries)
-a		Output all data fields (equivalent to -pr).
-f string		Extract particular features which is a string containing any of the following feature types (case sensitive): PGC, RC, PRC, 12I, 12P, SD, P, MI, RGC, RRC, IOI, DUR, BLV, MLV, MLI, MGC, MPS.
-t file		Subsitute the filename in the first column of output data with a different string (typically a control number for database management).
-l #		Limit the number of notes processed for the entry to first # of the file.

Themebuilderx is used to generate a search index which is used as input into the themax command. Themebuilderx is used to generate search indexes for ThemeFinder but can also be used for other applications, or interfacing with directly on the command line. The original themebuilder command was written in AWK by David Huron, utilizing other Humdrum tools. The "x" version is a backwards compatible implementation in C++ which is stand-alone (extracts search features without dependencies on other command-line tools), and adds rhythmic and polyphonic feature extensions.

As an example, consider the following 6 Humdrum files:

ex1.krn **kern *clefG2 *k[f#] *G: *M4/4 *met(C) =1- 4.dd 8cc 4b 4g =2 4f# 4a 4g 4b =3 4a 4cc 4b 4dd =4 4d 4f# 4g 4g == *-

ex2.krn **kern *clefG2 *k[] *C: *M4/4 *met(C) =1- (8cc 8r 8g 8r 8e 8r 8r 8a =2 8d 8r 8r 8g 8c) 8r 8r (8ee =3 8f 8r 8r 8dd 8e 8r 8r 8cc =4 8dL 8a 8A 8BJ 8dL 8cJ 4r == *-

ex3.krn **kern *clefG2 *k[f#c#g#] *f#: *M4/4 (8bL 8ddJ =1 4.cc# 8b 8aL 8g#J 8aL 8cc#J =2 4b 4a 4g#) (8g#L 8aJ =3 8bL 8cc#J 4dd 4cc# 8bL 8cc#J =4 2a 2g# =5 2a) 4r == *-

ex4.krn **kern *clefG2 *k[b-e-a-] *E-: *M2/4 =1- [2e- =2 4e-] 8fL 8gJ =3 [2a- =4 4a-] 8b-L 8a-J =5 4g 8a-L 8gJ =6 4f 8e-L 8fJ =7 [2g =8 4g] 4r == *-

ex5.krn **kern *clefF4 *k[f#c#g#d#] *E: *M2/8 =1- ([4E =2 8EL] 16F#L 16EJJ =3 [4D# =4 8D#]L 16EL 16D#JJ =5 16C#LL 16BB 16C# 16D#JJ =6 16ELL 16F# 16G# 16F#JJ =7 8EL 8D#J =8 8E) 8r == *-

ex6.krn **kern *clefC3 *k[b-] *F: *M2/4 =1- (8F'L 8G' 8A' 8B-'J =2 8c'L 8A'J 4F) =3 (4f 8eL 8dJ =4 2c) =5 (8F'L 8G' 8A' 8B-'J =6 8c'L 8A'J 4F) =7 4c^ 4D^ =8 2F; == *-

Passing these files to themebuilderx will generate a search entry line for each file:

ex1.krn ZG= {m2m1m4m1p3m2p4m2p3m1p3m12p4p1p0 #ddDdUdUdUdUDUus :DDDDUDUDUDUDUUS %5431721324355711 }xM2xm2xM3xm2Xm3xM2XM3xM2Xm3xm2Xm3xP8XM3Xm2P1 j20B7697B90B22677 JD C B G F# A G B A C B D D F# G G M4/4quadruplesimple ex2.krn ZC= {m5m3p5m7p5m7p16m11p9m10p8m10p7m12p2p3m2 #DDUDUDUDUDUDUDuUd :DDUDUDUDUDUDUDUUD %153625134231266721 }xP4xm3XP4xP5XP4xP5XM10xM7XM6xm7Xm6xm7XP5xP8XM2Xm3xM2 j074927045240299B20 JC G E A D G C E F D E C D A A B D C M4/4quadruplesimple ex3.krn zF#= {p3m1m2m2m1p1p4m2m2m1p0p1p2p2p1m1m2p2m4m1p1 #UdddduUdddsuuuudduDdu :UDDDDUUDDDSUUUUDDUDDU %4654323543223456545323 }Xm3xm2xM2xM2xm2Xm2XM3xM2xM2xm2P1Xm2XM2XM2Xm2xm2xM2XM2xM3xm2Xm2 jB21B9891B9889B121B1989 JB D C# B A G# A C# B A G# G# A B C# D C# B C# A G# A M4/4quadruplesimple ex4.krn ZE-= {p2p2p1p2m2m1p1m1m2m2p2p2 #uuuudduddduu :UUUUDDUDDDUU %1234543432123 }XM2XM2Xm2XM2xM2xm2Xm2xm2xM2xM2XM2XM2 j3578A87875357 JEb F G Ab Bb Ab G Ab G F Eb F G M2/4duplesimple ex5.krn ZE= {p2m2m1p1m1m2m2p2p2p1p2p2m2m2m1p1 #udduddduuuuudddu :UDDUDDDUUUUUDDDU %12171765671232171 }XM2xM2xm2Xm2xm2xM2xM2XM2XM2Xm2XM2XM2xM2xM2xm2Xm2 j4643431B134686434 JE F# E D# E D# C# B C# D# E F# G# F# E D# E M2/8duplesimple ex6.krn ZF= {p2p2p1p2m3m4p12m1m2m2m7p2p2p1p2m3m4p7m10p3 #uuuuDDUdddDuuuuDDUDU :UUUUDDUDDDDUUUUDDUDU %123453117651234531561 }XM2XM2Xm2XM2xm3xM3XP8xm2xM2xM2xP5XM2XM2Xm2XM2xm3xM3XP5xm7Xm3 j579A0955420579A095025 JF G A Bb C A F F E D C F G A Bb C A F C D F M2/4duplesimple

Each line contains multiple fields separated by a tab character, and each line starts with a unique tag character to facilitate searches in the thema command. The default entries on each line are:

1. filename
2. key -- starting with uppercase Z for major modes or lowercase z for minor modes, then the tonic note of the key (in uppercase), terminated by an equals sign (=). Example: ZG= which represents G major. Note that there must be a key designation record in the file in order for the key to be extracted into the index.
3. twelve-tone interval -- starting with an open curlybrace ({), then a string of intervals without spaces, using m (minus) for falling melodic intervals, p (positive) for rising intervals (p is also used before repeated notes). Example: {m2m1m4m1p3m2p4m2p3m1p3m12p4p1p0
4. pitch refined contour -- starting with # and followed by five possible charcters: d = down a diatonic step, D = down a diatonic leap (greater than an interval of a 2nd), s = same pitch (repeated note), u = up a step, U = up a leap. Example: #ddDdUdUdUdUDUus
5. pitch gross contour -- a three-level description of the melodic contour (as opposed to 5 for refined contour). The data field starts with a colon (:), and then has three possible characters: U = up (next note is a higher pitch than the current note), S = same or repeated note, D = down. Example: :DDDDUDUDUDUDUUS
6. scale degree -- starts with a percent sign (%) followed by the numbers 1 through 7 to indicate the seven diatonic steps of a major or minor scale. Accidentals are ignored, so both C and C# in C major are labeled as 1. Example: %5431721324355711 Note that there must be a key designation record in the file in order for the scale degrees to be extracted from the data.
7. musical interval -- abbreviations of the standard names for musical intervals. This field stats with a right curlybrace (}), followed by a sequence of intervals without spaces which consist of three parts: (1) the interval direction (x for down, X for up), (2) the quality of the diatonic interval (M=major, m=minor, P=perfect, A=augmented, d=diminished, and (3) the diatonic distance as a number, such as 3 for a third. Example: }xM2xm2xM3xm2Xm3xM2XM3xM2Xm3xm2Xm3xP8XM3Xm2P1
8. twelve-tone pitch class. Starting with a j, then followed by the absolute pitch classes, starting with C = 0, C-sharp/D-flat = 1, D = 2. For two digit pitch classes, letters of the alphabet are substituted: A-sharp/B-flat = 10 -> A, and B/C-flat = 11 -> B. Example: j20B7697B90B22677
9. diatonic pitch class -- Starting with J and followed by the pitch class names. This field is the only one which separates individual notes by spaces. Diatonic pitch names are in upper case (A through G) followed by an accidentals: # for sharps/double sharps, and - for flats/double flats. Example: JD C B G F# A G B A C B D D F# G G
10. metric description: starting with an M, followed by the numberic values for the time signature, and then followed by quadruple, triple, etc/ which describes the type of metric cycle, followed by simple or compound depending on if the top number in the time signature is divisible by 3. Example: M4/4quadruplesimple

Rhythmic analysis option

Adding the -r adds rhythmic analysis entries to the output data:

1. duration gross contour (~)
2. duration refined contour (^)
3. duration (as an inter-onset-interval) (!)
4. beat level (&)
5. metric level (`)
6. metric refined contour (')
7. metric gross contour (@)
8. beat position (=)

Polyphonic option

Polyphonic data extraction can be done by using the --poly option. This option extracts multiple entries for a file, with one line for each **kern spine in the file.

Currently, only the primary track of a spine is used for building an index. For example, here is a file with two spines of **kern data:

poly.krn **kern **kern *M4/4 *M4/4 *k[] *k[] *C: *C: =1- =1- * *^ 4c 4ee 8g . . 8a 4d 4cc 8b . . 8a 4e 4a 8g# . . 8f# 4f 4f 4fn * *v *v =2 =2 4g 4d 4a 4B 4b 2c 4cc . == == *- *-

Running the command "themebuilderx --poly poly.krn" will generate two entries:

poly.krn::1 ZC= {p2p2p1p2p2p2p1 #uuuuuuu :UUUUUUU %12345671 }XM2XM2Xm2XM2XM2XM2Xm2 j024579B0 JC D E F G A B C M4/4quadruplesimple poly.krn::2 ZC= {m4m3m4m3m3p1 #DDDDDu :DDDDDU %3164271 }xM3xm3xM3xm3xm3Xm2 j40952B0 JE C A F D B C M4/4quadruplesimple

Each entry adds a double colon (::) after the filename (or text string substitution when using the -t option), followed by the spine number from which the indexing data was extracted. Note that the second column of data in the second spine is currently ignored.

Example usages of the themebuilderx program are available on the themebuilderx 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

thememakerx, themax

The compiled themebuilderx program can be downloaded for the following platforms:
• Linux (i386 processors) statically compiled on 30 Aug 2010.
• Mac OS X/i386 compiled on 25 May 2010.

The source code for the program was last modified on 1 Sep 2010. Click here to go to the full source-code download page.