Appendix I


Reference Records


Reference records are formal ways of encoding "library-type" information pertaining to a Humdrum document. Reference records provide standardized ways of encoding bibliographic information -- suitable for computer-based access.

A perpetual problem with reference information pertains to the language in which information is represented. Humdrum provides comprehensive methods for dealing with multiple languages. These methods are described below, and Humdrum users are encouraged to become familiar with these conventions.

Humdrum reference records are designated by three exclamation marks at the beginning of a line, followed by a multi-letter code, followed by an optional number, followed by a colon, followed by some text.

Over 80 reference codes are pre-defined in Humdrum. Each of these reference records is described below under nine categories: (1) authorship information, (2) performance information, (3) recording information, (4) work identification information, (5) imprint information, (6) copyright information, (7) analytic information, (8) historical information, and (9) representation information. A final section discusses how to cite electronic documents.

Accommodating Different Languages

Humdrum attempts to accommodate all languages. Reference information can be encoded using the original language of the source material or document. In addition, reference information can be encoded in various translations that help end users. Humdrum uses the International Standards Organization ISO 639-2 standard for representing languages. This standard provides 3-letter codes for more than 4,000 existing and historical languages. For example, the ISO standard codes for English, French and Swahili are eng fre and swa respectively. (A table of 50 common languages is given at the end of this appendix.)

Humdrum allows any type of reference information to be encoded in any or all of these languages. In general, the primary reference information is encoded using the original language of the source material. Consider the case of a Friuli folksong (Friuli is a dialect of Italian). The title of the song should be encoded in the original language, but it may also be useful to provide translations in Italian and English.

The principal reference code indicating title is !!!OTL: (see below). Following the OTL reference code, the language of encoding can be indicated by appending an "at" sign (@), followed by the 2-letter ISO 639-1 language code, or a 3-letter ISO 639-2 language code for languages without a two-letter code. Here the title is rendered in three languages:

!!!OTL@@FUR: Ai preit la biele stele
!!!OTL@ITA: Ho pregato la buona stella
!!!OTL@ENG: The Good Star
Notice the use of the double "at" sign (i.e., "@@"). This convention is used to indicate that the language used in the record is Friuli, at it is the original language for the entry. The title can also be encoded without any language designation:
!!!OTL: Ai preit la biele stele
This may implies that the title is already rendered in the original language, or that it uses the preferred language of the encoder.

Authorship Information

!!!COM: Composer's name. In some cases, opinions differ regarding the best spelling of a composer's name. If so, all common spellings should be given -- each alternative separated from the previous by a semicolon. E.g.

!!!COM: Chopin, Fryderyk; Chopin, Frederick

With respect to accents, refer to the discussion concerning the !!!RLN: reference record (see below). If a work was composed by more than one composer, then each composer's name should appear on a separate !!!COM: record with a number designation prior to the colon. For example,

!!!COM1: Composer, A.
!!!COM2: Composer, B.

!!!COA: Attributed composer. This may include attributions known to be false. Several attributions may be combined on a single record by separating each name by a semicolon. Note that if a document contains both !!!COA: and !!!COM: records, then the attributed composer is explicitly assumed to be false.

!!!COS: Suspected composer. This reference code indicates the belief of the editor or producer of the document as to the true identity of the composer(s). If more than one composer is suspected, each name should appear on a separate !!!COS: record with a number designation prior to the colon.

!!!COL: Composer's abbreviated, alias, or stage name. e.g. Madonna.

!!!COC: Composer(s) corporate name. Corporate names may include the names of popular groups (especially when the actual composer is not known). Corporate names may also include business names, e.g. Muzak.

!!!CDT: Composer's dates. The birth and death dates should be encoded using the **Zeit format described in the Humdrum Reference Manual. The **Zeit format provides a highly refined representation, including methods for representing uncertainty, approximation, and boundary dates (e.g. prior to ..., after ...).

!!!CBL: Composer's birth location. Where the composer was born.

!!!CDL: Composer's death location. Where the composer died.

!!!CNT: Nationality of the composer. This reference information is encoded using the language of the nationality. Thus a German composer is encoded as Deutscher rather than "German", and a French composer is encoded as Francais rather than "French." Of course the specific language can be explicitly encoded using the 3-letter language codes described above. (e.g., !!!CNT@@FRE: Francais). Where the composer changed nationality, successive nationalities should be listed (in chronological order) separated by semicolons.

!!!LYR: Lyricist. The name of the lyricist. If more than one lyricist was involved in the work, then each lyricist's name should appear on a separate !!!LYR: record with a number designation prior to the colon. If the composer was also the lyricist, this should be explicitly encoding using the independent !!!LYR: record -- rather than implicitly assumed.

!!!LIB: Librettist. The name of the librettist. If more than one librettist was involved in the work, then each librettist's name should appear on a separate !!!LIB: record with a number designation prior to the colon. If the composer was also the librettist, this should be explicitly encoding using the independent !!!LIB: record -- rather than implicitly assumed.

!!!LAR: Arranger. The name of the arranger. If more than one arranger was involved in the work, then each arranger's name should appear on a separate !!!LAR: record with a number designation prior to the colon.

!!!LOR: Orchestrator. The name of the orchestrator. If more than one orchestrator was involved in the work, then each orchestrator's name should appear on a separate !!!LOR: record with a number designation prior to the colon.

!!!TXO: Original language of vocal/choral text. The name of the language should be encoded in that language. For example, russki rather than Russian.

!!!TXL: Language of the encoded vocal/choral text. The name of the language should be encoded in the language used for encoding. For example, Italiano rather than Italian.

!!!TRN: Translator of text. The name of the translator of any vocal, choral, or dramatic text. If more than one translator was involved in the work, then each translator's name should appear on a separate !!!TRN: record with a number designation prior to the colon.

Recording Information

Humdrum representations may encode information pertaining to sound recordings (such as sound-based analyses). For information derived from sound recordings the following reference records may be pertinent.

!!!RTL: Title of album.

!!!RMM: Manufacturer or sponsoring company. The company or organization responsible for the release, distribution, and/or manufacturing of the recording.

!!!RC#: Recording company's catalogue number. The album's numerical designation.

!!!RRD: Date of release. The release date should be encoded using the **date format described in the Humdrum Reference Manual.

!!!RLC: Place of recording. (Local language should be used.)

!!!RNP: Name of the producer.

!!!RDT: Date of recording. The date of recording should be encoded using the **date format described in the described in the Humdrum Reference Manual.

!!!RT#: Track number.

Performance Information

Humdrum representations may encode performance-activity information rather than (or in addition to) score-related information. If the representation encodes a given performance (such as a MIDI performance), then the following reference records may be pertinent.

!!!MPN: Performer's name. If more than one performer was involved in the work, then each performer's name should appear on a separate !!!MPN: record with a number designation prior to the colon. Note that this record can be used for soloists, and !!!MGN: is used for the name of a group, such as the Chicago Symphony Orchestra, and !!!MCN: is for the conductor of the group.

!!!MPS: Suspected performer. If more than one performer is suspected, each name should appear on a separate !!!MPS: record with a number designation prior to the colon.

!!!MGN: Name of the performance group (ensemble), such as the Juilliard String Quartet.

!!!MRD: Date of performance. The performance date should be encoded using the **date format described in the Humdrum Reference Manual.

!!!MLC: Place of performance. (Local language should be used.)

!!!MCN: Name of the conductor of the performance.

!!!MPD: Date of first performance. The date of first performance should be encoded using the **date format described in the described in the Humdrum Reference Manual.

Work Identification Information

!!!OTL: Title. The title of the specific section or segment encoded in the current file. Titles must be rendered in the original language, e.g. Le sacre du printemps. (Title translations are encoded using other reference records.)

!!!XEN: Translated title (in English). Note that reference codes are also available for translations to languages other than English, French, German, or Japanese, by adding the ISO 639-1 language code after the "X", But preference should be given to the @ system described above which allows multiple languages for any reference record instead of only the work title. So another way of encoding the title is !!!OTL@EN:, or to indicate that the original language is English: !!!OTL@@EN:.

!!!XFR: Translated title (in French).

!!!XDE: Translated title (in German).

!!!XNI: Translated title (in Japanese).

!!!OTP: Popular Title. This reference record encodes well-known or alias titles such as "Pathetique Sonata".

!!!OTA: Alternative title. This reference record encodes earlier or alternate titles.

!!!OPR: Title of larger (or parent) work from which the encoded piece is a part. For example, "Gute Nacht" (OTL) from Winterreise (OPR).

!!!OAC: Act number. For operas and musicals, this reference record encodes the act number as an Arabic (rather than Roman) numeral. The number may be preceded by the word "Act" as in Act 3.

!!!OSC: Scene number. For operas and musicals, this reference record encodes the scene number as an Arabic (rather than Roman) numeral. The number may be preceded by the word "Scene" as in Scene 3.

!!!OMV: Movement number. For multi-movement works such as sonatas and symphonies, this reference record encodes the movement number as an Arabic (rather than Roman) numeral. The number may be preceded by the word "Movement" or "mov." etc., as in mov. 3.

!!!OMD: Movement designation or movement name. Typically movements may be named according to the tempo (e.g. "Allegro ma no troppo") or according to a style, genre or form (e.g. "Fugue"), or according to a programmatic title (e.g. "In Full Flower").

!!!OPS: Opus number. The number may be preceded by the word "Opus" as in Opus 23. Once again, Arabic numerals are used.

!!!ONM: Number. The number may be preceded by the abbreviations "No." or "Nr." as in No. 4.

!!!OVM: Volume. The volume number may be preceded by the abbreviation "Vol." as in Vol. 2. Arabic numbers are used.

!!!ODE: Dedication. Name of person or organization to whom the work is dedicated. If the work was dedicated to more than one person, then each dedicatee's name should appear on a separate !!!ODE: record with a number designation prior to the colon.

!!!OCO: Commission. Name of person or organization that commissioned the work. If the work was commissioned by more than one person, then each commissioner's name should appear on a separate !!!OCO: record with a number designation prior to the colon.

!!!OCL: Collector. Name of person who collected or transcribed the work. If the work was collected by more than one person, then each collector's name should appear on a separate !!!OCL: record with a number designation prior to the colon.

!!!ONB: Free format note related to the title or identity of the encoded work. Nota bene. If more than one such note is encoded, each should appear on a separate !!!ONB: record with a number designation prior to the colon.

!!!ODT: Date of composition. The date (or period) of composition should be encoded using the **date or **Zeit formats described in the Humdrum Reference Manual. The **date and **Zeit formats provides a highly refined representation, including methods for representing uncertainty, approximation, and boundary dates (e.g. prior to ..., after ...).

!!!OCY: Country of composition. Local names should be used, such as `Espana'.

!!!OPC: City, town or village of composition. Local names should be used, such as `Den Haag.'

Group Information

!!!GTL: Group Title. A logical collection of works such as the "London Symphonies" by Haydn, or the four concertos by Vivaldi forming "The Seasons".

!!!GAW: Associated Work. Some works are associated with other works, such as plays, novels, paintings, films, or other musical works. E.g. Mendelssohn's Overture to Shakespeare's Midsummer Night's Dream. This reference allows associated works to be explicitly identified by author and title. E.g.

!!!GAW: Stéphane Mallarmé, L'Après-midi d'un faune; [The Afternoon of a Faun].

!!!GCO: Collection designation. This is a free-form text record that can be used to identify a collection of pieces, such as works appearing in a compendium or anthology. E.g. Norton Scores, Smithsonian Collection, Burkhart Anthology.

Imprint Information

!!!PUB: Publication status. This reference record identifies whether the document has ever been "published". One of the following English terms may appear: published or unpublished.

!!!PPR: First publisher. Name of the first publisher of the work, or the name of the publisher if a specific edition is being encoded.

!!!PTL: Publication title. Title of the publication (volume) from which the work is encoded. To encode linebreaks in the title, use the pipe character (|).

!!!PDT: Date first published. The date of publication should be encoded using the **date format described in the Humdrum Reference Manual.

!!!PPP: Place first published, or the place where the specific edition being encoded was published.

!!!PC#: Publisher's catalogue number. This should not be confused with better known scholarly catalogues, such as those of Köchel, Hoboken, etc.

!!!SCT: Scholarly catalogue abbreviation and number. E.g. BWV 551

!!!SCA: Scholarly catalogue (unabbreviated) name. E.g.Koechel 117.

!!!SMS: Manuscript source name. For unpublished sources, the manuscript source name.

!!!SML: Manuscript location. For unpublished sources, the location of the manuscript source.

!!!SMA: Acknowledgement of manuscript access. This reference information may be used to encode a free format acknowledgement or note of thanks to a given manuscript owner for scholarly or other access.

Copyright Information

!!!YEP: Publisher of electronic edition. This reference identifies the publisher of the electronic document.

!!!YEC: Date and owner of electronic copyright. This reference identifies the year and owner of the copyright for the electronic document.

!!!YER: Date electronic edition released.

!!!YEM: Copyright message. This record conveys any special text related to copyright. It might convey a simple warning (e.g. "All rights reserved."), convey registration or licensing information, or indicate that the document is shareware.

!!!YEN: Country of copyright. This reference identifies the country in which the electronic document was created, or where the copyright was established. In effect, it identifies the country under whose laws the copyright declaration is to be interpreted.

!!!YOR: Original document. This reference identifies any original source or sources from which encoded document was prepared. Note that original documents may themselves be copyrighted, and that permission may be required in order to create an electronic derivative document. Original documents may also have lapsed copyrights.

!!!YOO: Original document owner. If the electronic document was prepared from a copyrighted original document, this reference identifies the copyright owner of the original document. Note that unless the electronic and original documents have the same owner, some licensing agreement or other legal arrangement is necessary in order to create an electronic derivative document.

!!!YOY: Original copyright year. If the electronic document was prepared from a copyrighted original document, this reference identifies the year of copyright for the original document. Note that some licensing agreement or other legal arrangement is necessary in order to create an electronic derivative document.

!!!YOE: Original editor. The editor of the original document from which the electronic edition was prepared. Note that some licensing agreement or other legal arrangement may be necessary in order to create an electronic derivative document.

!!!EED: Electronic Editor. Name of the editor of the electronic document. If more than one editor was involved in the work, then each editor's name should appear on a separate !!!EED: record with a number designation prior to the colon, such as !!!EED2: for the second editor.

!!!ENC: Encoder of the electronic document. This reference identifies the name of the person or persons who encoded the electronic document. (Not to be confused with the electronic editor.) If more than one encoder was involved in the work, then each encoder's name should appear on a separate !!!ENC: record with a number designation prior to the colon, such as !!!ENC2: for the second encoder.

!!!END: Encoding date of the electronic document. This reference gives the date on which the person or persons who encoded the electronic document (see ENC), or the date on which it was substantially encoded. Similar to the EEV, but does not change as the document is ammended.

!!!EMD: Document modification description. This record type is used to chronicle all modifications made to the original electronic document. EMD records should indicate the date of modification, the name of the person making the modification, and a brief description of the type of modification made. For each successive modification, a separate !!!EMD: record should appear with a number designation prior to the colon.

!!!EEV: Electronic edition version. This reference identifies the specific editorial version of the work. e.g. Version 1.3g, or the version date in **date format. Only a single !!!EEV: record can appear in a given electronic document.

!!!EFL: File number. Some files are part of a series or group of related files. This record indicates that the current document is file x in a group of y files. The two numbers are separated by a slash as in:

!!!EFL: 1/4

!!!EST: Encoding status. This record indicates the current status of the document as it is being produced. Free-format text may indicate that the encoding is in-progress, list tasks remaining, or indicate that the encoding is complete. !!!EST: records are normally eliminated prior to distribution of the document.

!!!VTS: Checksum validation number. This reference encodes the checksum number for the file -- excluding the !!!VTS: record itself. When this record is eliminated from the file, any POSIX.2 standard cksum command can be used to determine whether the file originates with the publisher, or whether it has been modified in some way. (See the Humdrum veritas command described in Section 4.) Note that this validation process is easily circumvented by malicious individuals. For true security, the checksum value should be compared with a printed list of checksums provided by the electronic publisher.

Analytic Information

!!!ACO: Collection designation. This is a free-form text record that can be used to identify a collection, set, or group of related works, such as works appearing in a compendium or anthology. E.g. Norton Scores, Smithsonian Collection, Jones Anthology.

!!!AFR: Form designation. This is a free-form text record that can be used to identify the form (if appropriate) of the work. E.g. fuga, sonata-allegro, passacaglia, rounded binary, rondo.

!!!AGN: Genre designation. This is a free-form text record that can be used to identify the genre of the work. E.g. opera, string quartet, barbershop quartet.

!!!AST: Style, period, or type of work designation. This is a free-form text record that can be used to characterize the style, period, or type of work. This reference can include any term or terms deemed appropriate by the producer of the document. Designations might include keywords or keyphrases such as: Baroque, bebop, Ecole Notre Dame, minimalist, serial, reggae, slendro, heterophony, etc.

!!!AMD: Mode Classification. A combined numerical/name system for mode identification -- used especially for medieval monophonic and later polyphonic works. Modes are indicated by numbers from 1 to 12, followed by a semicolon, followed by the corresponding written name (with an initial upper-case character). Permissible mode numbers and names are:

1;Dorian
2;Hypodorian
3;Phyrgian
4;Hypophyrgian
5;Lydian
6;Hypolydian
7;Mixolydian
8;Hypomixolydian
9;Ionian
10;Hypoionian
11;Aeolian
12;Hypoaeolian
Other non-standard mode names can be used at the discretion of the electronic editor.

!!!AMT: Metric Classification. Meters for a file may be classified as one of the following eight categories: simple duple, simple triple, simple quadruple, compound duple, compound triple, compound quadruple, irregular, or various.

!!!AIN: Instrumentation. This reference is used to list all of the instruments (including voice) used in the work. Instruments should be encoded using the abbreviations specified by the *I tandem interpretation described in Appendix II. Instrument codes must appear in alphabetical order separated by spaces. (Note that alphabetical ordering is essential in order to facilitate searches for specific combinations or subsets of instruments using the grep command.) E.g.

!!!AIN: clars corno fagot flt oboe

!!!ARE: Geographical region of origin. This reference identifies the geographical location from which the work originates. Location designations are encoded using the local language. The location begins with the continent designation, and becomes successively more refined. If the information is available, refinement can continue to suburban district or even street address.

!!!ARE: Europa, Mitteleuropa, Deutschland, Wuerttemberg, Sindelfingen
!!!ARE: America, North America, United States of America, Ohio, Columbus

!!!ARL: Geographical location of origin. Like the ARE record, this reference record identifies the geographical location from which a work originates. Location designations are encoded using latitude and longitude values -- suitable for creating maps. The first numerical value indicates latitude (positive values indicating North, negative values indicating South). The second numerical value indicates longitude (positive values only, indicating distance East from the central meridian). A slash separates the latitude and longitude values. A series of trailing characters is used to indicate the degree of accuracy of the location information: % (continent), @ (country), # (province or state), : (town or village). For large regions such as countries or provinces, the geographical center of the region is used.

!!!ARL: 51.5/10.5@

Historical and Background Information

!!!HAO: Aural History. This is a free-form text record used to relay any story or stories about the origin, purpose or background of the work. This reference record is especially useful in ethnomusicological materials, where a particular story accompanies a song. The story may be encoded using several successive HAO records.

!!!HTX: Free-form Translation of Vocal Text. This is a free-form text record used to relay a non-literal translation of a vocal text. This reference record is again especially useful in ethnomusicological materials.

Representation Information

!!!RLN: ASCII language setting. This reference identifies the "language" code in which the file was encoded. This is applicable only to computer platforms which provide "extended ASCII" text capabilities (e.g. Danish or Spanish characters).

!!!RDF: User-defined signifiers. All Humdrum representations provide some signifiers (ASCII characters) that remain undefined. Users are free to use these undefined signifiers as they choose. When undefined signifiers appear in a given document, the !!!RDF**interp: code should be used to specify what the signifiers denote. Notice that the code RDF is followed by the name of the interpretation to which the signifier definition applies. In the following example, the letters "X" and "x" symbols that are defined within a hypothetical **piano representation. E.g.

!!!RDF**piano: X=hands cross, left over right
!!!RDF**piano: x=hands cross, right over left

!!!RDT: Date encoded. This reference uses the Humdrum **date format to identify the date(s) when the document was encoded.

!!!RNB: Representation note. This reference provides a free-format text that conveys some document-specific note related to matters of representation.

!!!RWG: Representation warning. This reference may be used to encode explicit warnings concerning the encoded material.

Electronic Citation

Electronic editions of music might be cited in printed or other documents by including the following information. The "author" (e.g. !!!COM:), the "title" -- either original title (!!!OTL:) or translated title (e.g. !!!XEN:). The editor (!!!EED:), publisher (!!!YEP:), date of publication and copyright owner (!!!YEC:), and electronic version (!!!EEV:), In addition, a full citation ought to include the validation checksum (!!!VTS:). This number will allow others to verify that a particular electronic document is precisely the one cited. A sample electronic citation might be:

Franz Liszt, Hungarian Rhapsody No. 8 in F-sharp minor (solo piano).
Amsterdam: Rijkaard Software Publishers, 1994; H. Vo\o'r\(hc'i\o's\(hc'ek (Ed.),
Electronic edition version 2.1, checksum 891678772.

In Humdrum files it does not matter where reference records appear. Since it is common for users to inspect the beginning of a file in order to check whether the file is being properly processed, the number of reference records at the beginning of the file should be kept to a minimum. A good habit is to place the composer, title of the work, and copyright records at the beginning of the file, and to relegate all other reference records to the end of the file.

ISO Language Codes

The following table provides further language designation codes not identified in the preceding discussion. A complete list of ISO 639-2 language codes is available.

CodeLanguage
@ALBin Albanian
@ARAin Arabic
@ARMin Armenian
@AZEin Azeri
@BENin Bengali
@BULin Bulgarian
@CHIin Chinese
@SCRin Croatian
@CZEin Czech
@DANin Danish
@DUTin Dutch
@ENGin English
@ESTin Estonian
@FINin Finnish
@FREin French
@GLAin Gaelic
@GERin German
@GREin Greek (modern)
@HEBin Hebrew
@HINin Hindi
@HUNin Hungarian
@ICEin Icelandic
@ITAin Italian
@JPNin Japanese
@JAVin Javanese
@KHMin Khmer
@KORin Korean
@LITin Lithuanian
@LATin Latin
@LAVin Latvian
@MALin Malayalam
@MONin Mongolian
@NORin Norwegian
@POLin Polish
@PORin Portugese
@RUMin Romanian
@RUSin Russian
@SCCin Serbian
@SLOin Slovak
@SLVin Slovenian
@SPAin Spanish, Castilian
@SWAin Swahili
@SWEin Swedish
@TAMin Tamil
@THAin Thai
@TIBin Tibetan
@TURin Turkish
@UKRin Ukranian
@URDin Urdu
@VIEin Vietnamese
@WELin Welsh
@XHOin Xhosa
@ZULin Zulu