The bulk of a hymnbook table of contents file will be hymn elements. Each hymn element represents one hymn or song and includes its reference number, one or more titles (possibly in a variety of languages), the MIDI files used for the hymn, the number of verses to repeat, what kind of dynamic profile to use, and whether the music is copyright and used under license.
Add a hymn element to the Test hymnbook. Select the last element in the hymnbook (export, if you’ve been following along) and select Insert / Element / After. Set the element name to “hymn” (without the quotes) and leave the value blank. Now add some attributes. Select Insert / Attribute / Child and set the attribute name to “num” and the value to “001”. Add another attribute (Insert / Attribute / After) named “stanzas” with value “3”. Add another attribute named “profile” with value “cs”, and a final attribute named “copyright” with value “true”. This is the beginning of a hymn. The document so far looks like this:
Hymn Attributes
num attribute
The “num” attribute is required. Its value is a number in the range 1 to 999. If you don’t include it Gloria will not add the hymn to the hymnbook. This is the number the user enters to select this hymn. Hymn numbers don’t have to be in order in the table of contents file. You can have a hymn element with number 36 immediately followed by hymn number 17, although for general sanity you should probably add hymns in ascending order by number. Hymn numbers can go unused. You can have numbers 85, 86 and 88, with no number 87, for example.
Each number must be unique within the hymnbook. If more than one hymn element has the same number, the later element will replace the earlier one.
The num attribute is allowed in the hymn element and the external element.
stanzas attribute
The “stanzas” attribute is required. Its value is a number in the range 1 to 15. If you don’t include it Gloria will use a default of 1 and add a warning message to the log file (if enabled). The resulting hymn will be valid. The stanzas value is the number of times the verse / chorus is repeated. Generally this is the number of times the main MIDI file is repeated, although the presence of a second version and / or new key MIDI file will distribute the repetition over multiple files. See the section on File Naming Convention and Structure for further discussion on how this works.
The stanzas attribute is only allowed in the hymn element and must be preceded by a valid num attribute.
profile attribute
The “profile” attribute is optional. Its value is the name of an alternate profile for the dynamic range of played notes. The only recognized value is “cs”. All other values (or omitting this attribute altogether) will apply the default dynamic range to this hymn. This chart illustrates the difference between the default and cs profiles:
The MIDI note-on velocity specifies how loud the note should be played. It has a range of 1 to 127 (0 means note off). The cs profile covers about 21dB over the full MIDI velocity range. The quietest notes will be 21dB below the loudest notes. On the other hand, the default profile covers the full 96dB range provided by Gloria’s 16-bit audio system. Above the midpoint (velocity 64) the two profiles are roughly equivalent. But below velocity 64 the default profile quickly gets very quiet.
If you know how to take advantage of an extended dynamic range then by all means do so. But for most applications you’ll get the best results by always using the cs profile.
The profile attribute is only allowed in the hymn element and must be preceded by a valid num attribute.
copyright attribute
The “copyright” attribute is optional. Include it and set its value to “true” to indicate hymn elements where the music is held under copyright. You must have a license from copyright holders to distribute such music. The presence or absence of the copyright attribute doesn’t affect the operation of Gloria in any way. Gloria has no way of knowing what licensing agreements are in place. The attribute exists as a means of record-keeping and accounting for royalties. If you distribute copyright music you are responsible for securing the necessary mechanical licenses and for paying the royalties. Without licensing you may be liable for expensive infringement claims.
Any value for the copyright attribute other than “true” is interpreted as false.
The copyright attribute is only allowed in the hymn element and must be preceded by a valid num attribute.