This page is primarily intended for developers of other music apps to enable exporting songs to the .singsong format.
JSON (JavaScript Object Notation)
.singsong files are based in JSON. Each .singsong file contains 1 song, which can contain multiple forms of the same song. The file is a JSON object with 3 properties: "metaData", "sections" and "forms".
'metaData'
The "metaData" property contains an object with the following optional properties. 'title' - a string with the title of the work. Technically, this is optional, but I don't know how you're going to know which song is which without a title. 'copyright' - a string with any copyright information 'lyricists' - an array of strings, each with the name of a lyricist 'composers' - an array of strings, each with the name of a composer 'arrangers' - an array of strings, each with the name of an arranger 'artists' - an array of strings, each with the name of an artist. The artist field should be treated as a 'made famous by' when that person has no other responsibility for the content of the song. Except for the rare singer/song-writer combos, this field is how most people 'know' about a particular song. 'about' - a string containing any additional information
In general, a name should not be listed in multiple fields, but should take on the field with the highest precedence. The precedence order from highest to lowest is: composers, lyricists, arrangers, artists.
Programs which display these values will insert commas between values in the array when display them together, so to avoid confusion, please don't use comma-forms of the names. Instead use a properly ordered name. I.e. use "Michael W. Smith" not "Smith, Michael W."
'forms'
Conceptually, a 'form' is sequence of 'sections' which describe the linear playback of a song. In JSON, the 'forms' property is an array of objects, each of which has the following two properties:
'name' - optional. the string name of the form as read by a person 'sections' - required, an array of 'form section' objects
The 'form section' object has one property: 'index' - required, an integer index of the section as referenced in the song's array of sections.
The form-section object will have other fields added in the future, that's why each form is not merely an array of integers. The index is optional, but will soon become optional when a specific new feature is added. So watch out if you're writing an importer.
Forms are how Lead Singing knows to order the sections when playing back a song. Order the form sections objects to refer to the sections they play in the order they are played. If you delete a section from the song, then forms which reference sections later in the song's sections array after the one deleted will need to have their index adjusted. It's an editor's job to make sure the indexes are consistent with the sections.
'Sections'
The song's 'sections' property is an array of section objects, which has the following 3 properties:
'name' - an optional string which names the section. Typical names are "Verse 1", "Chorus" or "Bridge". 'continuities' - required, an array of 'musical continuities', described later. 'tracks' - required, an array of tracks described later. A track is designed to be able to be performed by a single musician.
Musical COntinuities
A 'musical continuity' is a range of music in which time signatures, key signatures and tempo remain constant. A section may have multiple musical continuities performed in order. Changes from one musical continuity to the next apply across all the tracks in a same section.
'beatsPerMeasure' - required - an integer number of 'beats' in each measure. These are not "quarter notes", which don't carry the beat in compound time signatures or 2/2 time. This is the number of baton taps, or metronome clicks, or foot stomping in the measure. i.e. the number of quarter notes in 3/4 time, the number of half notes in 2/2 time, or the number of dotted quarters in 12/8 time.
'leading' - optional - an integral rational number (described later) of the number of beats before the first full measure. i.e. the number of pick up beats. 'trailing' - optional - an integral rational number of the number of beats in the continuity after the first full measure. Typically, leading + trailing = beatsPerMeasure, and typically, these values are identical for all measures in a song.
'measures' - required. the number of measures containing beatsPerMeasure in the continuity. This excludes leading & trailing beats.
'tempo' - required - an object with one field , 'beatsPerSecond', which is a floating point number of the number of beats, as defined by 'beatsPerMeasure', per second. For instance, 60 bpm, the json would be
"tempo":{"beatsPerSecond":1.0}
The tempo field will gain additional fields in the future, related to continuous tempo changes.
"key" - required, an object which describes the key signature in which notes are interpreted.
Key Signature
A key signature describes the repeating consistent set of notes.It has the following properties:
"baseNote" - required, an integer count of the number of half steps from A 440 of the root note of the key. For instance, middle C is "-9". The exact pitch of the final intoned note is taken by adding the key base note to the relative pitch, so it does matter which octave you use to select the base note. In general, I suggest octave from the A below middle C to the Ab above middle C, which gives a general range of values from -12 to -1.
"intervals" - optional. An array of integers which represent half step intervals between non-accidental notes in one octave of the key signature. For major and minor scales, this is [2,2,1,2,2,2,1]. I know what you're thinking, "Wouldn't a minor scale be different?". No. Key signatures exist to reduce the number of accidentals. Every minor key has a relative major, and the vast majority of music composed in minor keys minimizes its accidental count when written in the key of the relative major. When omitted, the major intervals are assumed. Lead Singing currently supports only half and whole step intervals, so augmented intervals, i.e. from harmonic minor scales, should be decomposed into half and whole step intervals.
Integral Rationals
A rational number is expressed in the form "numerator/denominator", where numerator and denominator are integers. As stored in the json, it is always an array in which the first member is an integer, but the rest of the array can differ, so it takes on one of 3 forms:
[n] - an array of a single integer. The integer is the numerator, and the denominator is assumed to be '1'. [n, d] - an array of 2 integers. The first integer is still the numerator, and the denominator is the 2nd integer. [i,[fn,fd]] - this is a "mixed fraction", in which the first integer represents a whole number to which the second array as its own rational number is added to. To convert to a mere numerator and denominator, n = i * fd + fn, and d = fd. Currently, Lead Singing will not save rationals in this form, it merely makes human creation of files easier.
Track
The musical contents of a track are designed to be performed by a single performer. For now, this means only 1 simultaneous note at a time is allowed, since we are currently only supporting vocal tracks. In json, a track is an object with the following properties:
"name" - optional, a string name of the track. When importing from MusicXML, this is the part name, otherwise it is "Melody".
At a future time, Lead Singing may gain multi-part support, and when that happens, further guidance will be provided on the meaning of consistent of altered track names across multiple sections. For now, only a single track is supported, and it is recommended that they all have the same name.
"auditoryGroups" - required. an array of "auditory groups".
Auditory Group
An object which describes the musical intonation of a single syllable. For non-lyrical elements, this can be a sequence of notes which are implicitly slurred together.
"start" - required, a rational with the number of beats since the section began. "lyric" - optional. a string with the text of the syllable to be sung. You should not include verse numbers, verse names, hyphens or spaces. However, trailing punctuation, such as ".,;!", etc... may be useful when inferring line breaks. "-" - optional, a string representing hyphenation of this syllable. possible values are "|" no hyphens, the assumed value if omitted "-|" hyphen before the syllable "|-" hyphen after the syllable "-|-" hyphens before and after the syllable.
"notes" - required, an array of note objects, expressed as array for compactness.
Ok, 'notes' is what you've been waiting for. A note object is expressed as an array. The first item is an integer, which is the pitch of the note expressed in half steps above the base note of the key. The second element in the array is a rational number describing the duration of the note in beats.
As an example, the 4th note of the scale and 3 eighth notes long would be [5,[3,2]] Because the 4th is 5 half steps above the base pitch, thus the "5", and an eighth note is half a beat (assuming the quarter note gets the beat), thus the [3,2].
Multiple notes slurred together form the 'notes' array "notes":[[5,[3,2]] or "notes":[[5,[3,2],[7,[1,2]],[9,[1]]
Additional Comments
You'll note that rests are not explicitly notated. They are simply the lack of notes. To make computer interpreters easier, please order all auditory groups in a track in increasing start time of the groups.
Similarly, we don't explicitly notate swing beats, articulation, or grace notes. The duration of the json note is the intended actual duration of the sung note, not the duration of the sung note + an implicit rest before the next note. In general, most people single notes between 3/4 to 7/8 as long as they're notated in Traditional Music Notation. So when importing from other musical formats, we calculate a likely duration of the notes based on explicit articulation & syllabic values. For instance, a half note won't last full 2 beats when imported. If notes are explicitly legato, we'll make their sung duration longer, to match the full duration of the file's notated duration property. If staccato, we'll shorten them to around half of the notated duration. But if lyrics are hyphenated to the next note, we'll also fill their durations, unless staccato is explicit. We will also not reduce the duration of notes when we detect their lyric syllable is unusually long and their duration is unusually short, to avoid graphic representations which must be very wide merely to support guttural words in short notes.
You'll note we don't support explicitly referring to staves. Because the Lead Singing staff is based on the intervals in the key signature, displays relative pitch, is intended for vocal performance, and automatically adjusts its bounds to include all the notes in the form of the song, explicit staves are useless.
We also don't explicitly notate accidentals. In Lead Singing, all notes which are not common notes of the key signature get an accidental mark. In part this is why note pitches are notated in half steps relative to the key signature. If at some future time, someone convinces me that microtonal pitches are not as painful to the ear and as distasteful to listen to for everyone else as they are for me, then I will support them by altering the requirement that pitches be integers such that floating point numbers are as allowed as well. For now, I will be pleasantly surprised if everyone in your congregation actually manages to sing the pitches as notated without microtonal errors.
Bar lines are implicit, and the result of the continuity's beatsPerMeasure, leading & trailing properties. So when working with the file format, don't forget to sum leading and trialing beats in a section when crossing musical continuity transitions. Note's start beats properties reset to zero at the beginning of a section, not the beginning of a musical continuity. The 'measures' property refers to the number of full measures, and does not include implicit measures created from non-zero values of leading and trailing beats.
Dynamics are out of scope for now. Surveys indicate that congregants will be so happy to finally sing the right notes & rhythms that they will simply sing at the top of their lungs.
We hope to introduce gradual tempo changes in a future version.
There are no multiple verse numbers for auditory groups in a given section. Each iteration of a verse with different lyrics is itself a different section.
Similarly, there are no repeats, codas, segnos, endings... etc.. A 'form' precisely describes the sequential order of performance of the sections.
There is no support for spoken words. This app is called "Lead singing" not "responsive reading".
Notice that there is no support for fonts or other page-layout-like behavior. #1 this is because we aren't printing pages. Font sizes and exact layout dimensions are not calculated until the screen for the presentation is selected. In the far future, we'd love to be able to support changing fonts and other stylistic elements in presentations, but that is out of scope for now.
Currently we don't support cue notes. However, I believe musical cueing is very important, especially for untrained singers, so I want to support cue notes at some time in the future.