SYNOPSIS
OPTIONS
DESCRIPTIONThe addref program is used to manage reference records (also called bibliographic records) in Humdrum files. In particular, the addref program takes reference records from a text file and incorporates those records into a Humdrum file. Various features of the reference record file allow for automatic placement of reference records at various points in the output file. The addref program can also automatically insert key and tempo interpretations at any location in the output file. [more info] Reference records are stored in a file which is loaded into the program using the -r option. In addition, a secondary reference record file (for movement-specific records) can be loaded with the -m option, or they can be included in the primary reference record file and accessed using the -t option. The reference record file can contain both global comments (lines containing two or more exclamation marks (!) at the beginning), and bibliographic records which start with three exclamation marks followed by a key/value pair separated by a colon (:). Basic UsageIn the reference record file, lines starting with an at sign (@) are meta markers used to instruct the computer about where to insert the reference records in the input file. The two primary meta-markers are: @TOP
@BOTTOM
Reference records found before @TOP (or any other meta-marker) will be placed in the @TOP region section automatically. A reference record file containing no meta-markers is equivalent to a file containing one @TOP marker at the top of the file. The @BOTTOM marker is not needed if there are no reference records to be placed at the bottom of the file. A file with no @TOP or @BOTTOM markers will have all of the reference records placed at the top of the output data. Here are two example inputs to the addref program. The first file contains the reference records which are to be added to the input Humdrum file, shown to the right.
Using the command addref -r reffile input > output produces the following result:
Special meta codesThere are a few meta-markers which control the insertion/replacement of tandem interpretations.
The @KEY and @TEMPO data will overwrite any existing key/tempo interpretations in the input Humdrum file. These markers can go in any location in the reference record file, and are not part of the @TOP and @BOTTOM segmentation system (some limitations on the location are given further below).
addref -r reffile input > output
Key interpretations will try to insert themselves immediately after a key signature interpretations, such as *k[b-e-] for B-flat major or G minor. Likewise, tempo interpretations will try to insert themselves after time signatures or metrical indications, such as *M2/2 or *met(C|). By default, the key or tempo marking will go at the top of the data, but including additional fields on the data line line will allow the key/tempo mark to be placed in other locations in the file. This is done by adding whitespace after the mark and then a location marker which can be either an absolute beat location (quarter notes from the start of the file), or a measure/beat location. For example, to place a key interpretation at the start of the fourth measure, these seven location marks are equivalent (if the meter is 4/4 and there are no pickup beats):
16
16.0
a16
a16.0
m4
m4b1
m4b1.0
"a" stands for absolute beat units for score time. A numeric value without a preceding letter code is also assumed to be using "a". In this case the 16th quarter note is equivalent to the first beat of the 4th measure. "a" time values are always a count of quarter notes since the start of the data, where the first note in the file (even if it starts on an off-beat) is at "a0" (which can also be abbreviated "0"). Negative "a" values are in reference to the end of the data. "m" is for measure number. When using measure locations, the measure number must be present in the data (use barnum to add measure numbers if necessary). Measure numbers can have decimal points after them, but the fractional part is interpreted in a special way: the decimal value means to place the data that many barlines after the (first) barline marked with the specified measure number. This is used, for example, when measures are split with a repeat sign. The repeat signed barline will not have a number (unless you choose to place one there). So for example, if the previous bar number is 17, and a repeat barline is unnumbered, you can add a tempo marking after the repeat barline by using the location "m17.1". The "m17" portion refers to measure 17, and the ".1" means one barline after the measure labeled 17."b" is for a particular beat number within the given measure, starting at 1 for the first beat. The rhythmic duration of a beat is dependent on the time signature. 4/4 beats are one quarter-note wide, 2/2 beats (cut time) beats are a half-note wide. Time signatures where the numerator's factorization contains a three will be considered compound meters. For example, the beat duration in 6/8 is a dotted quarter note, and for 6/4 meters, the beat will be considered to be the dotted half-note. To break this metric rule, add the duration of the beat after the time signature, such as *M6/8:8 which means that there are 6 beats in a 6/8 measure, each beat equivalent to an 8th note. In compound meters, unequal beats are listed in sequence and separated by commas. For example 5/8 with two beats of a quarter and dotted-quarter duration would be encoded as *M5/8:4,4. (dot included in interpretation). However, when specifying "a" times, note that the rhythmic unit remains a quarter note, even in compound meters such as 6/8. The "a", "m" and "b" letter codes are case-sensitive, with capital letters functions to be implemented in the future (perhaps for placing the data after the specified location rather than before it. Note that "a" and "b" time indications cannot be used when the music does not contain **kern data, or the **kern data does not contain parsable rhythmic syntax. The following example inserts two tempo markings into the file: the first at the start of the music, and the second just before the data for the third beat of the first measure:
addref -r reffile input > output
output: Selective spine insertion of key and tempo interpretationsBy default, the key and tempo interpretations will be inserted into all spines of data. If you want to limit tempo or key interpretations to **kern spines, you can add a fourth parameter onto the @KEY and @TEMPO data. The fourth parameter is a list of exclusive interpretations into which the data should be inserted. For example:
addref -r reffile input > outputoutput: In this case, the @KEY entry is applied only to **kern spines, The first @TEMPO entry is applied to both **kern spines and **dynam spines, and the second @TEMPO entry is applied to all spines by indicating ** as the third parameter (or leaving the third parameter blank). Since the first @TEMPO entry and the @KEY entry did not originally have an explicit location, a "0" was added to indicate that they are to be placed at the start of the data. To prevent tempo or key signature interpretations from being duplicated in secondary spines due to the presence of split spines, then use the -P option. Separate work and movement reference record filesOften, reference records can be shared across several Humdrum file, such as when a work (a piano sonata in these examples) consists of multiple movements. Each movement will have common reference records (such as a composer and a title), while also having records specific to the movement (such as the !!!OMD: record). Here is an example of how to split the above example into the work-related records and movement-related records:
Then other movement files can be created for the rest of the sonata:
addref -r work.ref -m mvmt1.ref mvmt1.krn > mvmt1-new.krn
addref -r work.ref -m mvmt2.ref mvmt2.krn > mvmt2-new.krn
addref -r work.ref -m mvmt3.ref mvmt3.krn > mvmt3-new.krn
@TOP and @BOTTOM sections in the movement reference record file will be inserted at the locations specified respectively by @MOVEMENT-TOP and @MOVEMENT-BOTTOM. If the two @MOVEMENT are not given in the work file, then the movement records will automatically be inserted after the @TOP and @BOTTOM contents. Composite work / movement fileIt may be more convenient to have one reference record file which contains both the work-related records as well the records for each of the possible movements. Therefore, a single file may also be created which contains the information for both the entire work and the separate movements. In this case the @KEY and @TEMPO entries are local to a particular movement, and they should be inserted after either the @TOP or @BOTTOM markers for a particular movement. When encoding multiple movement records in a single reference file, the work records generally will be labeled with @TOP and @BOTTOM, while the movements will be listed with identifying labels after their @TOP and @BOTTOM markers. For combining multiple movement records into a single file, the @TOP and @BOTTOM markers can contain labels which are separated (without whitespace) from the TOP and BOTTOM strings by a colon (:). The -t option can be used to expand the reference records with a particular movement tag. For example "-t 1" will use the @TOP:1 and @BOTTOM:1 markers when inserting the first movements reference records. The TOP/BOTTOM labels are arbitrary strings which can contain any letters, digits, dash (-), or underscore (_). For the combined reference record file, these are the commands to insert the reference records into the individual movements:
addref -r work.ref -t 1 mvmt1.krn > mvmt1-new.krn
addref -r work.ref -t 2 mvmt2.krn > mvmt2-new.krn
addref -r work.ref -t 3 mvmt3.krn > mvmt3-new.krn
If there are no labels on successive TOP/BOTTOM markers in a file, then the addref program will internally enumerate them, and they can be referenced by integers starting at "1" for the second occurrence of TOP/BOTTOM found in the file. The first TOP/BOTTOM segments will be presumed to be for the work reference records. A list of movement tags found in a reference record file can be generated by using the -l (lowercase L) option. For the above multi-movement example, the result would be:
Multiple Humdrum file input mode When more than one input Humdrum file is given as command-line arguments to addref, the files will be interpreted as individual movements. These movement files will be paired sequentially with movement sections found in a multi-movement reference record file. If there are more input files than movement sections in the reference record file, an error will occur. If there are fewer files than movement sections, then the first file will match to the first movment section found in the file, and so on. The --path option allows for automatic filename saving of output. If a multi-movement input is given, or the --path option is given for a single input, then filenames will be extracted from the tags Reference records in the middle of the dataFor the case where reference records (or global comments) are required to be placed somewhere in the middle of the data, you may use the @MIDDLE marker. Following the @MIDDLE marker is a location indication using "a", "m" and possibly "b" according to their usage for @KEY and @TEMPO markers. @MIDDLE markers will generally not be used on the work level in a multi-movement piece, so they do not require movement labels. Instead, @MIDDLE markers will belong to the movement according to the first previous line containing a @TOP or @BOTTOM marker. Here is an example of placing a reference record in the middle of some data:
This would cause the reference record "!!!OMD: Allegro" to be inserted at the start of the measure explicitly labeled 11 in the input Humdrum file. Sort order preferencesA list of bibliographic markers can be added in a particular sequence in the output file by using the -s option in order to sort references records found in the file into a particular ordering. This allows a standardization of the ordering across repertories. Typically the -s option would be applied after the reference records have been inserted into a file, but the -s option can be used to post-process the output file as well. Example: addref -s sortfile input > output
Duplicate entries will be preserved, such as two !!!COM: entries. The sort file can contain sort ordering for language codes, but these can also be handled automatically. For example, the sort order for records starting !!!ONB are: !!!ONB: (plain opus nota bene record), !!!ONB#: (where # is a number which would be sorted numerically), !!!ONB@@lang which is the start of an original language indication, !!!ONB@lang: where multiple languages would be sorted alphabetically by their language code. In the example sort file given above, @TOP and @BOTTOM codes were inserted in order to sort records into separate sections at the top and bottom of the file. If no @TOP or @BOTTOM markers are found in the sort file, then records will be sorted locally to the top or bottom of the file and not moved to a different place in the file. Using the -S (capital S) option will use the default sorting rules, so an explicit sorting file is not required. Any reference record which is not found in the sort list will be place alphabetically at the bottom of the @TOP or @BOTTOM sections of the file. Extraction of bibliographic recordsThe -x option can take a Humdrum file containing reference records (plus tempo and key interpretations) to generate a reference record file. Multiple files can be input in order to generate a multi-movement reference record file. Example:addref -x input > output.ref
Other optionsBlank line insertionThe -B option can be used to include blank lines found in the reference file. Note, however, that blank lines are not officially allowed in Humdrum files. Example:
Reference record preservationIf you do not want to overwrite bibliographic records which are present in the input Humdrum file with records which are present in the reference file (but may want to add new reference records found in the reference file), you can use the -p option. Example:
Updating of existing reference recordIf you want to preserve existing reference records and their locations in the input file, but only replace the contents of the records if they appear in the reference record file, then use the -u option. Any reference record types which are present in the record file but not found in the input Humdrum file will be suppressed in the output. Example:
Reference record unionIf you want to insert additional reference records to an existing file, but the new reference records contain the same reference keys, they will normally replace existing records in the file. However, if you specify the -U option, then additional reference records will be added without removal or changing of the original records. For example if an input file has a !!!COM: record, and the record file also has a !!!COM:, then both records will be present in the output. If you only want the duplicates present if they are not identical between the two input files, and a single records if they are the same, then use the -D option to suppress identical duplicates. Future ideas@MAKE: for automated calls to the program from internally stored instructions.EXAMPLESDOWNLOADThe source code for the program was last modified on . Click here to go to the full source-code download page. |
