voo version 1.0 beta

; Language created by Nick Wilkinson.
; voo Language Specifications

; voo uses several characters that do not appear on a standard keyboard [See EOF].
; This is a compromise aimed at making voo readable to a musician.
; voo is unlike any other scripting language because the syntax is based on written music.

; A voo file should begin with the text 'voo version 1.0 beta'.
; Single line comments begin with a semicolon.

; In voo files all pieces of music must begin with a title wrapped in double quotes.
; The pitch of the notes is written on the next line, and the rhythm on the line below that.

; Line 0  Title (or other text)
; Line 1  Pitch values
; Line 2  Rhythmic duration

; To specify the playback instrument to be used,
; the instrument name should be placed in square brackets at the start of the line 1.

; [violin]  Pitch values
;  Rhythm

; The instruments available will vary depending on the sound library.
;_____________________________________________________________________
;
; NOTE - voo is case sensitive.
; Note names use the upper case letters A to G.
; A B C D E F G

; The default beat value is a quarter note indicated by a single bullet point.
;       

; Notes values should line up visually with the letter names above.
; This is not forced but it makes it easier to locate errors.
; Using word wrap should be avoided.
; In most editors the code will wrap automatically after so many characters.
; This does not effect playback but it is wise to avoid using unecessary white spaces.

"Ascending Scale"
 C D E F G A B
       
;_____________________________________________________________________
;
; Middle C marks the start of the 4th octave, which is set to the default note range.
; To change the octave range, the number of the octave must be placed immediately before the notes affected.
; All notes from that point on will sound higher or lower accordingly.

"Octave Note Range Transition"
 A B 5C D E F G A
         

"Descending Octave Range Transition"
 C B A G F E D 3C
         

; voo scripts currently support a note range of just over seven octaves From 0A to 8C.

"Ascending the Full Range in Octaves"
 0A 1C 2C 3C 4C 5C 6C 7C 8C
                  
;_____________________________________________________________________
;
; Note durations are related to one another by powers of two.
; voo supports all the following note values.

; L  Upper case L  Long  equivalent to two whole notes (not used)
; o  Lower case o  Whole note  open note
;   Lower case thorn  Half note  open note with a stem
;   Bullet point  Quarter note  closed note
; -  Minus sign  Eighth note  single flag
; =  Equals sign  Sixteenth note  double Flag
;   Sword  Thirty-second note  tripple flag
;   Double sword  Sixty-fourth note  quadruple flag (very rare)

; Each note in the list lasts for half the duration of the one above.

"Relative Note Values"
 3F E F E E F F E E E E F F F F
  o       - - - - - - - -
;_____________________________________________________________________
;
; Bar lines are used to separate groups of notes and are represented by a vertical bar.
; It is good practice to include bar lines, but you may also leave them out in voo (not recommended).

"Bar Lines"
 C C C   G G G   C C C
    |    |   
;_____________________________________________________________________
;
; To indicate the number of beats in each bar you should use a time signature in brackets.
; A time signature is like a fraction where the dividend represents the number of beats in each bar.
; The divisor represents the value of each beat and must be a power of 2 between 1 and 64.

"Time signature"
       C C C   D D D   E E E   G G G
 (3/4)    |    |    |   

; You can change the time signature as often as you like.

"Irregular Timing"
       C C C C D D D D       E E E       G G G G G
 (4/4)    |   |(3/4)   |(5/2)     

; It is quite common to encounter an incomplete bar at the start and the end of a phrase.
; The total duration of these incomplete bars should be equal to the duration of a full bar.

"Incomplete Bars"
      5D C  4B G G   A D D   G
 (3/4) - - |    |    | 
;_____________________________________________________________________
;
; The default speed of the music (or tempo) is 125 quarter note beats per minute (bpm).
; To change the tempo place the new bpm in brackets on the lower line.

"Changing the Tempo"
 C D E F      G A B     5C
     (84)    (42) 

; You can also change the tempo by changing current beat value (unique to voo).
; The new note value is placed in brackets.

"Beat Value Changes"
 C D     E F G     A B 5C
   ()    ()    

; In a standard score, both the beat and the bpm are set with a single instruction.
; Shown below - a quarter note is set to 150 bpm.

"Setting the Tempo"
        C D E F G A B C
 (150)        
;_____________________________________________________________________
;
; Rests or silences are indicated by commas in the upper line (in place of the note names).
; The duration of each rest must also be written in the rhythm underneath.

"Incorporating Rests"
       G , F E , D C
 (80)       O

; A phrase can also start with a rest.

"Starting With a Rest"
       ,  FEFE F
 (60) L  ==== o
;_____________________________________________________________________
;

; Sharps and flats are indicated by the hash symbol and the lower case letter b respectively.

"Sharps and Flats"
 [Classical Guitar] E D C# 3Bb A G# A ,
             (110)            

; E# is the same as F, and B# is the same as C.
; Likewise Fb is the same as E, and Cb is the same as B

"Same Notes - Different Spelling"
  E F , Fb E# ,  B 5C , 4Cb 5B#
    o     o     o     
; E F   E  F     B  C    B   C  <<< actual notes
;_____________________________________________________________________
;
; If you sharpen a note, that note remains sharp until the sharp is cancelled.
; The same applies if you flatten a note.

"Sustained Inflection"
 (80) C C C C# C  C  C  C  D D D D Eb E  E  E
       - - - -  -  -  -  -  - - - - -  -  -  -
;      C C C C# C# C# C# C# D D D D Eb Eb Eb Eb  <<< actual notes
;_____________________________________________________________________
;

; A sharp or flat can be cancelled using the natural symbol represented by lower case z.

"The Natural Symbol"
 5D Db C 4Bb A Bz 5C C# Dz
                o

; Normally sharps, flats and naturals only affect one particular note frequency and not necessarily notes in other octaves.
; This is not the case in voo. All subsequent instances of the note are affected regardless of octave.
; This avoids any ambiguity and the need for disambiguation.
;_____________________________________________________________________
;

; It is possible to set all the notes F to F# by default.
; This can be done by using a key signature in brackets.

"Key Signatures"
 (1#) D E F  G
          
;     D E F# G  <<< actual notes

; Several combinations can be set using the following recognised key signatures.

; (0#)  C major  C  D  E  F  G  A  B  C
; (1#)  G major  G  A  B  C  D  E  F# G
; (2#)  D major  D  E  F# G  A  B  C# D
; (3#)  A major  A  B  C# D  E  F# G# A
; (4#)  E major  E  F# G# A  B  C# D# E
; (5#)  B major  B  C# D# E  F# G# A# B
; (6#)  F# major  F# G# A# B  C# D# E# F#
; (7#)  C# major  C# D# E# F# G# A# B# C#

; (0b)  C major  C  D  E  F  G  A  B  C
; (1b)  F major  F  G  A  Bb C  D  E  F
; (2b)  Bb major  Bb C  D  Eb F  G  A  Bb
; (3b)  Eb major  Eb F  G  Ab Bb C  D  Eb
; (4b)  Ab major  Ab Bb C  Db Eb F  G  Ab
; (5b)  Db major  Db Eb F  Gb Ab Bb C  Db
; (6b)  Gb major  Gb Ab Bb C  Db Eb Fb G
; (7b)  Cb major  Cb Db Eb Fb Gb Ab Bb Cb
;_____________________________________________________________________
;
; Accidentals are notes that do not appear in the key.
; Sharps, flats and naturals are all possible accidentals.

"Accidentals"
 (3b)  E  G F A  G   B  Az Ez
 (5/4)        |     
;      Eb G F Ab G   Bb A  E  <<< actual notes

When crossing a bar line all accidentals are cancelled.

"Crossing Bar Lines"
 (1#)  Fz E D C#  D C 3B A   G G G F   G
 (4/4)      |      |     | o
;      F  E D C#  D C B  A   G G G F#  G  <<< actual notes
;_____________________________________________________________________
;
; There are several ways to repeat sections of music in voo.
; The simplest is to use start and end repeat marks - each represented by a colon.
; Start repeats are placed immediately after a bar line and the end repeat immediately before one.

"Repeat Marks"
          E F G A   A G F E    E
 (2/2) |:     |     :| o
;         E F G A   A G F E    E F G A   A G F E    E  <<< result

; A repeat section can begin with an incomplete bar.

"Repeat Section With a Lead-in"
       C    E   G E   G F    E   D C ,
 (3/4)  |:  |   |   :|  |   
;      C    E   G E   G F    E   G E   G F    E   D C  <<< result

; Repeat marks can not be used for nested loops - voo is not a programming language.
; You can specify the number of repeats by placing a number after an end repeat.

"Multiple Repeat Sections"
                 A B C   D
 (3/2) (100) |:    | o. :3|
;                A B C   D  A B C   D  A B C   D  <<< result

; Unlike written music, the start repeat must always be indicated in voo.
;_____________________________________________________________________
;
; If you wish to repeat a single bar then use a bar repeat represented by the percent symbol.

"Bar Repeats"
       G A       B
 (2/4)   | % | 
;      G A  G A  B  <<< result

; To repeat multiple bars place the number of bars to repeat after the percent symbol.

"Multiple Bar Repeats"
       A A   BB B  5C C   D
 (2/4)   | --  |   |  | %4
;      A A   BB B   C C   D   A A   BB B   C C   D  <<< result

; Bar repeats may be placed inside repeat sections.

"Bar Repeats Within Repeat Sections"
       ,    C D E        F
 (3/4)  |:    | % :| 
;           C D E  C D E  C D E  C D E  F  <<< result
;_____________________________________________________________________
;
; Placing a dot after a note increases the notes duration by half.

"Dotted Notes"
       C D E   F    F  E D   C
 (3/4)    | . | . -  | .

; A double dot placed after a note increases its duration by three quarters.

"The Double Dot"
       C   D   D E F G
 (4/4) .. - |    
;_____________________________________________________________________
;
; The duration of a note can also be extended using a tie represented by underscore.
; A note followed immediately by a tie has an additional duration equal to the following note.
; Pitch values are only indicated for the first of the tied note pair.

"Ties"
  A    B
  _  _-
; .   .  <<< actual duration

; Any number of notes can be tied together and ties also work across bar lines.

"Multiple Ties"
       A         B
 (2/4) _ | _ | 
;      o            <<< actual duration
;_____________________________________________________________________
;
; Ties also work across section repeat marks.
; If you enter a repeat section with a tie, you must use a tie at both ends of the repeat section.

"Ties Over Repeat Marks"
  A            B
  _ |: _ :| 
; o..            <<< actual duration

; Never add a tie to a bar that contains a bar repeat.

"Ties Across Bar Repeats"
       C           D
 (3/4) ._ | % |  
;      o..           <<< actual duration
;_____________________________________________________________________
;
; Tuplets are rhythmic divisions which last a fraction of a single note.
; Tuplets are indicated by a number immediately following the note.
; One quarter note can be divided into three eighth note triplets.

"Triplets"
       C D   C  D  E  C  D  E
 (2/4)   | -3 -3 -3 -3 -3 -3

; A quarter note can also be divided into 5 sixteenth note quintuplets.

"Quintuplets"
       C D   C  D  E  F  G  C  D  E  F  G
 (2/4)   | =5 =5 =5 =5 =5 =5 =5 =5 =5 =5

; A tuplet division may never be a power of 2.
;_____________________________________________________________________
;
; Supported tuplet divisions are as follows:

; Note    Divisions 
;         3       5to7    9to15  17to31   33to63  65to127 129to255
;        
; =              
; -       =              
;        -       =              
;               -       =              
; o                     -       =              
; L       o                     -       =              

; A sixteenth note (=) can only be divided into the following tuplets:
; 3 5 6 7

; Each of the next four tuplet values are considered out of bounds in voo:
; L3 o5 9 17

; Tuplet values beyond 7 are very rare.
; Generally only prime numbers are used, but there is no clearly defined rule.
;_____________________________________________________________________
;
; You can use a tuplet repeat symbol indicated by the plus sign following the tuplet.
; This shorthand symbol is native to voo.

"Tuplet Repeats"
       C D   C  D  E  F  G  G  F  E  D  C
 (2/4)   | =5+            =5+
;        | =5 =5 =5 =5 =5 =5 =5 =5 =5 =5  <<< actual rhythm

; When using tuplet repeat commands, all the note names must still be typed out in the melody.

"Tuplet Repeat Rules"
 G G G G G G G
 7+
;_____________________________________________________________________
;
; Da Capo means repeat from the start of the piece and is written 'DC' exactly as it is in music.
; DC may only be used once.

"Da Capo"
       C D E F   G
 (4/4)     | o DC
;       C D E F   G    C D E F   G  <<< result

; With Da Capo all repeat marks are ignored the last time round.
; This does not apply to bar repeats.

"Ignoring Section Repeats"
          C D E F    G
 (4/4) |:     :| o DC
;          C D E F    C D E F  G  C D E F  G <<< result
;_____________________________________________________________________
;
; In voo the end of the piece is indicated by the French word fin.
; In music it is common to use the Italian word fine.

"Final Phrase"
       C 3G G  A G    B 4C
 (4/4)  -  -   _|   fin

; The word fin is always ignored unless the following instruction appears  /fin (al fine)
; In voo DC/fin means Repeat from the start to the finish.
; fin can appear at any position in the piece.

"End in the Middle"
       E D | C fin | G | DC/fin
 (2/4)            
;      E D   C       G   E D C <<< result
;_____________________________________________________________________
;
; Segno is the Italian word for sign. This is indicated by the the symbol .
;  is ignored until the following instruction appears  DS (del segno)
; DS means from the sign (similar to GoTo in programming) and can only be used once.
;  must always preceed DS [DS]

      D   C   E G   E    G    A B  5C
(3/4)  |     | . |  DS   | 
;     D   C   E G   E    G  E G   E   G A B  C <<< result

; As with Da Capo, section repeat marks are ignored the last time round.

"Ignoring Repeats with DS"
         C    D E F    G C
 (4/4)   |:    :|   DS
;        C    D E F    D E F  G C  C  D E F  G C  <<< result

; DS/fin is the same as DC/fin except you repeat from the sign instead of from the start.
; finDS/fin
;_____________________________________________________________________
;
; The coda in music is an end section tagged on to the end of a melody.
; In voo the upper case letter  is used to indicate the coda.

"The Coda"
       G F E D  C    , G A G   Bb
 (4/4)    | o |     | .

; The symbol  is ignored until one of the following instructions is encountered - DC/ or DS/
; DC/ means from the start to the coda sign.

       E E   F F   F   G              A   G#
 (3/4)   |     | ._|  DC/ |  | .
;      E E   F F   F   G         E E   F F  A  G#  <<< result

; It is good practice to place a bar line before the final coda, regardless of the number of beats.
; DS/ means from the segno to the coda sign.

       C   D   E F   G   A         B 5C
 (4/4)  |       |  DS/ |   
;      C   D   E F   G   A    E F   G   A  B C  <<< result
;_____________________________________________________________________
;
; voo supports double sharps and double flats.
; Double sharps are written as lower case letter x, and double flats are written as bb.

"Double Sharps"
 (5#) Fx G
        
;     G  G#  <<< actual notes

"Double Flats"
 (7b) B  Bbb
      Bb A  <<< actual notes
;_____________________________________________________________________
;
; Besides changing the tempo suddenly, you can also accelerate gradually using accel.
; The final bpm should be given otherwise the accel command is unclear.

"Acceleration"
              E D C 3B A G# F       E
 (140) accel          (200) o

; If the final bpm is not given then the interpreter ought to accelerate continuously.
; In this case the final tempo will be determined automatically.

; Caution is advised when using acceleration into or out of repeating sections.
; Acceleration can not be repeated once the final tempo has been reached.
; It is the responsibility of the user to reset the tempo where necessary to get the desired effects.

; The opposite of accel is ritardando or rit.

"Ritardando"
            E D C 3B A G# F       E
 (200) rit          (140) o
;_____________________________________________________________________
;
; Glissando means to slide from one note to another.
; In voo gliss can be interpreted as play all notes between the start note and end note.
; In reality all frequencies within the range are produced on some instruments.

"Slide Up"
  C       F
   gliss 
; C C# D D# E F  <<< resulting notes
; =5+      <<< resulting rhythm

"Slide Down"
  A       F#
   gliss 
; A Ab G F#  <<< resulting notes
; 3+       <<< resulting rhythm

; Glissando can introduce highly complex rhythmic divisions.

"Complex Results"
 5C        4C#
  .. gliss =
; 5C 4B Bb A Ab G Gb F E Eb D C#  <<< resulting notes
; 11.. 11.. 11.. 11.. 11.. 11.. 11.. 11.. 11.. 11.. 11.. =  <<< resulting rhythm

; A sophisticated interpreter may be able to differentiate between gliss on violin and gliss on guitar.
;_____________________________________________________________________
;
; To create 1st 2nd and 3rd time repeats use superscript characters   and .
; These characters must go immediately after the bar line.

"1st 2nd and 3rd Time Round"
          C    3Bb 4D E     Bb B B B    G F E   Bb
 (3/4) |: . |      :|    - - :|    | .
;         C Bb D E C Bb Bb Bb Bb C G F E Bb  <<< result

; You can use different combinations as shown below:

; |:  |  :|  :| 
; |:  |  :|  :| 
; |:  |  :4| 

; You can use the command etc to exit on the last time round if the section repeats many times.

"Last Time Round"
          F C         F     D
 (2/4) |:   |etc  :7| 
;         F C F F C F F C F F C F F C F F C F F C D  <<< result

; Generally it is not advised to use DC or DS with a section containing 1st 2nd and 3rd repeats.
; With DC and DS, the interpreter ought to skip past etc and only play the final repeat.
; Composers often add instructions to avoid ambiguity but there is no room for ambiguity in voo.
;_____________________________________________________________________
;
; Dynamic markings are currently included in the voo language.
; The following standard terms are included.

; ppp  almost inaudible
; pp  very quiet
; p  piano or quiet
; mp  moderately quiet
; m  moderately loud
;   forte or loud
;   very loud
;   as loud as possible

; Dynamics are written in the line containing the rhythm immediately before the affected notes.

; (4/4) mp     |  o

; You can instruct the notes to get louder using cresc...

; (4/4) (80) ppp cresc o_| % | % |  o

; ...or quieter using dim.

; (4/4) (80)  dim  | % | % | ppp o

; It is the intention that future voo interpreters will be able to work with dynamics.
; voo may remain beta for a while before all the potential quirks have been ironed out.
;_____________________________________________________________________
;
; To override the default accentuation within a bar, use the greater than symbol >.
; This symbol must be placed immediately before all accented notes within the affected bar.

 "Bernstein"
       G G G 5C C C |       4A  F  D
 (6/8) - - -  - - - | (3/4) > > >
;_____________________________________________________________________
;
; Multiple parts are supported.
; Each voice or instrument is written in the consecutive line notation described above
; Each double line pair is written below the previous.

; Line 0  Title (or other text)
; Line 1  [Instrument 1] Pitch values
; Line 2  Rhythm for Instrument 1
; Line 3  [Instrument 2] Pitch values
; Line 4  Rhythm for Instrument 2

; Care must be taken with changes in tempo when synchonising multiple voices.
; voo does not do this for you, and it is often necessary to write playback instructions in all voices.
;_____________________________________________________________________
;
; Features currently not supported in voo version 1.0 beta
; Multiple line wrap
; Lyrics
;_____________________________________________________________________
;
; Reserved symbols and keywords unavailable in voo version 1.0 beta
; ~  mordent
; tr  trill
; harm  harmonic
;   common time
; ^  up
; v  down
; ||  double bar line
; '  pause
;   dotted bar line
; \  unassigned
;_____________________________________________________________________
;
; AscII chracters used in voo 1.0 beta which do not appear on a standard computer keyboard.

;   0131
;   0134
;   0135
;   0149
;   0167
;   0178
;   0179
;   0185
;   0216
;   0254

; To type these characters activate Num Lock, hold down the alt key and type the ascii code using the number keypad.
; You may prefer to use a suitable virtual keyboard ==>
; http://www.autoitscript.com/forum/topic/135167-win-1252-extended-keyboard/page__p__942959
