Notes mode is entered by seq(@SLOT type(FORMAT_TYPE_LIST) channels=CHANNELS music=MUSIC), and is also of revelance when creating defintions with def. Here, SLOT is the new slot to be created, FORMAT is a sample type (see earlier), CHANNELS should be 1 or 2 for mono or stereo, and MUSIC contains actual music data, delimited by <> or [].
The FORMAT block can also contain gate=BOOL where BOOL is TRUE or FALSE, defaulting to TRUE if unspecified. If true, then the normal behaviour of gating overlaid music samples to avoid audible clicks is enabled.
Contexts
Before going further into notes mode, it is necessary to describe music contexts, which are the stacked sets of parameters describing the current state of the notes interpreter, in terms of time point, volume, chosen instrument, and so on. A new context is created each time a block of musical notation is surrounded by the delimeters <> or [] (corresponding to chords mode and tune mode). Each context inherits from its parent context the current state of the parser. See the following pseudocode where a b c etc. are notes and AAA BBB etc. are commands that alter the state.
[b AAA c d <BBB e f CCC g a> b] c
Here, at b, the new context inherits from the state defined by global. All notes produced after AAA are affected by that, but only within this block defined by []. The command BBB only applies within the angled brackets, and the command CCC only applies within the angled brackets from the point at which it is issued.
The delimeters {} can be used to create new nested contexts without specifying a change to chords or tune mode.
Definitions created with def and other places where () are used as brackets do not automatically create a new context and it is as if they were typed directly into the context from which they are included (with \SLOT). However, delimeters can be used within definitions to create new nested contexts there. Definitions do not themselves produce audio data in their slot, only in the slot from which they are called.
Some functions may allow [] <> or {} to be used as delimeters.
The following variables are maintained within the context:
- Chords mode versus tune mode
- Most recent note value used
- Currently selected instrument; post-processing slot
- Current note duration value/reverberation settings
- Volume: amp and amp2; amplitude adjustment for pitch settings
- Stereo setting
- Envelope; adjustment setting; gating setting
- Staccato and articulations settings
- Tempo/Ralentando settings
- Crescendo settings
- Tranposition pitch/salendo settings
- Fidato/fidando settings
- Tuning type/gamut
- Phaser/vibrato/pitch bend/glide settings
- Scratch settings
- Tremolo settings
- Arpeggiation setting
- Precision settings; offset
- Beats and beat position
- auto_stereo settings
A key property of contexts are their time pointer and length pointers. These behave differently within chords mode and tune mode contexts.
Within [], each note (or nested context) advances the time pointer by its length, and the length pointer by the same, forming a tune.
Thus, in the example above, the duration of the whole context is 4 beats long.
Within <> , the time pointer is not advanced by each note, but the length pointer is updated so as to be the maximum length of any note (or context) nested within it. This can be used to form chords or polyphony. The following pseudocodes show alternate ways to form a three-beat tune with two voices. One form is probably more useful in polyphony, the other in homophony.
[<c f> <d g> <c f>]
<[c d c] [f g f]>
Notation for musical notes
The following page explains how to put musical notes together to form a tune. This following section explains the basics of musical notation in the program. This has a lot in common with GNU Lilypond, but with important differences.
Pitch
Musical notes are generated (using the currently selected instrument, see later) by a b c d e f g. Sharps, flats, and double sharps and flats are generated with as gis ges gisis geses.
By default, the parser moves to a note "nearest" the previous note, ignoring any accidentals. Thus c f represents a fourth step up, whereas cis ges represents a doubly augmented fourth step down.
Apostrophe and comma marks can be added after a note to indicate octave steps upwards and downwards. Thus c c' c,, represents an octave step up, followed by two down. c g' will move upwards a fifth.
Half sharps and flats can also be produced: from double flat to double sharp (on G) in half step intervals, use geses geseh ges geh g gih gis gisih gisis.
For more unusual effects, one-third and one-sixth tones are also available using the gradation ges get gets g gits git gis.
The most recent note can be repeated using +, to which articulations can be added like normal notes.
Rests are generated with r which behaves otherwise like a note.
If the core library is loaded, commands \british allow use of British-style accidental names, in the form of b bb # x.
Duration
The duration of any subsequent notes is specified by a duration command. These are specified as an integer number indicating the denominator of a fraction of a semibreve. Thus 1 2 3 4 6 8 12 16 represent in order: semibreve, minim, triplet minim, crotchet (quarter note), triplet crotchets, quaver (eighth note), triplet quavers, semiquaver.
Dots can be added to lengthen notes by half, three quarters, etc. e.g. 4. 8... Colons can be added to double the length of notes, e.g. 5:.
Small amounts can be subtracted from note values using the syntax 2 -(16.), which can simplify snaps and tuplets.
Longer or more awkward durations can be generated by D(NUM DENOM). This creates a note NUM/DENOM semibreves (whole notes) long. D(QUARTERS) simply selects a number of quarter notes/crotchets, again using the current tempo.
0 on its own indicates that following notes will have zero length. No sound is produced, however such silent notes can be used to indicate the start pitch of pitch bends.
Notes following 0 take no time at all, not even in arpeggios. All other side-effects of note generation (e.g. possibly calling defined macros!) do occur.
Barlines as a visual aid and cross checking for formatting source files can be given by |. See beats(...) for more.
Alternative to the above format for durations, durations can be entered in seconds by choosing tempo_mode(time).
If the core library is loaded, commands \breve \breve. \longa \longa. \maxima \maxima. are available in notes mode to set longer durations.
Expressive effects
BoxyLady has a reasonable selection of expressive effects available to be mixed and matched. The following are applied directly to notes, although a selection of functions also provides expressive effects.
Articulation
Note values can be followed by a hyphen and then several symbols representing articulation. ces-. ces-' ces-p represent staccato, short staccato, and portato. ces-^ ces-- represent a strong and mild accent. These two pairs of articulations can be used in combination, e.g. ces--..
ces-v indicates a slightly quieter note (negative accent), and ces-, combines this with a staccato for a phrasing effect.
ces-l (lowercase L) indicates legato (full duration), counteracting global or local staccato settings set elsewhere.
ces-_ sets reverberation for notes beyond the time duration specified. Reverberation cannot be used with "instrument" samples set to loop. This will generate an error as the programme cannot work out when to finish such notes!
Slurs and bends
BoxyLady will attempt to smooth notes joined by slurs by preserving the position in the instrument sample, position in the envelope, use of gating, vibrato phase, and scratch() phase. Slurs can encompass several notes in the current context only (i.e. not across different levels of nesting of contexts created by <> {} or []). Lots of things will disrupt the smooth effect and lead to gating clicks, such as use of precision(time=X). Slurs will not work correctly with note-by-note instrument synthesis. Determining in advance under precisely what circumstances slurs will and will not work correctly is difficult, so most debugging here is left to the user.
Portamento (see notes functions) is a smooth pitch transmission between two notes. Portamento can be applied only to slurred notes and is turned off by default.
ces-* starts a slur.
ces-! ends a slur previously started by ces-*. Subsequent notes are not slurred.
ces-~ indicates a pitch glide should fill the whole duration of the note. These can occur within slurs, or on a stand-alone note.
New expressive effects can be defined with articulations(...).
Notes for Lilypond users
Lilypond users will have noticed similarities in the notation between Lilypond and BoxyLady. This is deliberate and my intention is that in the future conversion between the two systems might be made more easy this way. However there are some sneaky differences in the way music expressions are dealt with that can lead to unexpected results in BoxyLady.
The regex expression ([abcdefgris',]+)([0-9.]+)\s might be helpful!
Chords using < > do not change the outside context, therefore subsequent notes will relate to the pitch used prior to the chord. In Lilypond, chords act as a note and subsequent notes will relate to their pitch.
Global effects do not occur from most functions at local scope in BoxyLady. For example, a rallentando will only affect music in the current context or ones nested within it, not globally.