© Guido Kramann

Login: Passwort:

© Guido Kramann

Login: Passwort:

Syntax -- General

(EN google-translate)

(PL google-translate)

  • The description of the composition is in a simple text document and uses only ASCII characters.
  • Numbers are always positive integer values or zero.
  • Variable names consist of one or maximum two characters.
  • They may come from the character set {a..z,A..Z,0..9}, but only the second character may be a digit.
  • The musical realization is done in real time.
  • The document is reloaded again and again in quick succession in order to immediately take changes into account.
  • The document is run through exactly once at each time step.
  • Consequently, any variables used must have been defined in some previous line.
  • The description language is line-based.
  • Each line forms a unit with a clearly defined meaning.
  • There are six types of line entries in the description of a composition:
  1. Blank lines (are ignored)
  2. Line Comments # (are ignored)
  3. Pulse !
  4. Instruments :
  5. Formulas ~
  6. Playing technique

Formulas are differentiated whether they give their result to a normal variable or to an instrument. In the latter case, a selective division is performed at the end of the formula to determine a pitch.

Each number appearing in a line can also be parameterized by a variable, if this variable was defined before.

Syntax -- The six line types

1) Blank lines are simply skipped.

2) Line COMMENTS #

Line COMMENTS are introduced with # at the beginning of the respective line.

3) PULSE !

PULSE Count up from an initial value t0 in steps measured in milliseconds dt.

The syntax is: t0 dt ! x

The exclamation mark is the characteristic on the basis which a line which represents a pulse is identified. x is an arbitrary variable name over which the pulse can be processed then at other place further down in a formula. Valid variables consist of one or two characters from {abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789}.

  • Only the second character can be a digit.
  • In general, each line type has a special character as characteristic.
  • A pulse line always consists of exactly 4 elements separated by spaces.
  • Example of a line that defines a pulse:
8000 100 ! t
0 8000 ! tm

Code 0-1: Beispiele zu PULSE !


In the instrument line, the base number for each possible instrument is defined, the amplification and stereo direction is defined, the transposition, the range the type of instrument and finally the variable name, under which it can be addressed further down.

The special character that allows a line to be recognized as an instrument definition is the colon :

An instrument line always consists of exactly 14 elements separated by spaces:

In AOGdogmaWEB there are only 11, because CHANNEL, GAINLEFT and GAINRIGHT are not implemented there. The first instrument there is always the xylophone, the second the vibraphone and the third the marimba.


BASISZAHL = 2^p * 3^q * 5^r * 7^s * REST

Before converting a frequency into a midi value, it is multiplied by FACTOR. The value is given in hundredths 100 corresponds to factor 1. Afterwards the TRANSPOSITION is executed in semitone steps. Here 24 is the neutral position and does not lead to a transposition. 12 would lead to a transposition one octave lower. The tonal range is defined by MIDIMIN and MIDIMAX inclusive. Due to the software, certain instrument sounds and several playing variants are available. At the moment these are xylophone, vibraphone and marimba, each in three velocities. CHANNEL==0 means that the xylophone is addressed 1==vibraphone, 2==marimba. Example lines for the definition of instruments:

3 2 1 1 NN 100 19 65 108 0 70 30 : xy
3 2 1 1 NN 100 19 53 89 2 50 50 : ma
3 2 1 1 NN 100 19 45 108 1 15 35 : vb

Code 0-2: Examples for INSTRUMENTS :

  • Variable names have been chosen here to indicate the instrument in question.
  • NN is a previously defined variable that controls REST here.


  • Formulas are always in one row, but can be of any length.
  • At the very front there is the variable name of a pulse or an ordinary variable.
  • Then comes a number followed by an operation. This alternation (number operation number operation ...) is repeated as often as needed.
  • Then follows the special character Tilde ~ and behind it the variable, to which the result is assigned.
  • Examples for Formulas:
tm /18 %3 ~ WW
tm /24 +12 ~ XX
tm /48 +1 *6 +66 ~ YY

t *PP  %72 /3 +4  ~ vb
t +tm *QQ  %XX ~ ma
t +tm *RR  %XX /2 ~ xy

Code 0-3: Examples for FORMULAS ~

In the upper three examples, the result of the calculation is stored in the ordinary variables WW, XX and YY. In the last three lines, the result is assigned to one instrument each. The latter has the effect that the result of the formula calculation is first taken as a divisor of the associated base number for the selective division. The result is then interpreted as frequency and multiplied by FACTOR, converted to a midi value and transposed. Finally, it is checked whether the result lies within the required tonal range of the instrument. If so, the tone is heard. If it is not, you may hear a tone that was determined for the instrument by another formula. The last result that can be played always applies.

Formulas that control instruments can create musical phrases and represent what AOG originally is. All other line types are used to automatically change these formulas over time.

How is a formula interpreted? This can be represented mathematically in a very compact way:

tm /48 +1 *6 +66 ~ YY

corresponds as a mathematical formula:

YY = (((tm/48)+1)*6)+66

Where tm is a time sequence defined above:
0 8000 ! tm

This means:
tm0 = 0ms
tm1 = 8000ms
tm2 = 16000ms

Code 0-4: Second case: Interpretation of formulas whose result is transferred to an ordinary variable.

For formulas that deliver their result to an instrument, the evaluation is somewhat more complex:

t *PP  %72 /3 +4  ~ vb


Base number B is according to the definition of vb above: B=2*2*2*3*3*5*7*NN
Divider z = (((t*PP)%72)/3)+4

If the result is zero for z, no tone is assigned to the instrument.
The following operations will then not be performed.

frequency f = B // z

Where // corresponds to a selective division, which only 
removes the prime factors 2,3,5,7 from B in the same quantity as they appear in the divider z.
As this is central, here is an implementation of // for understanding:

while(f>=2 && f%2==0 && z>=2 && z%2==0) {f=f/2;z=z/2;}
while(f>=3 && f%3==0 && z>=3 && z%3==0) {f=f/3;z=z/3;}
while(f>=5 && f%5==0 && z>=5 && z%5==0) {f=f/5;z=z/5;}
while(f>=7 && f%7==0 && z>=7 && z%7==0) {f=f/7;z=z/7;}

After that, there is still to be done:
f = f * FACTOR
midi = frequency2midi(f)
midi = midi + TRANSPOSITION

if(midi>=MIDIMIN && midi<=MIDIMAX)
    playTone(midi); ...Play the sound on the instrument vb

Code 0-5: Interpretation of formulas whose result is transferred to an instrument.

Permitted operations are:

+ Addition
- Subtraction
* Multiplication
/ Division (returns result, if no remainder exists, otherwise zero)
% Modulo, or rest division, examples: 6%3=0 7%3=1 8%3=2 (returns result if operand is positive, otherwise zero)
| "divides", preserves the intermediate result, if it is divisible by the operand with no remaining rest, else returns zero. 

Code 0-6: Permitted operations and their meaning


The current version has three instruments, each available in samples with three velocities. When a technique formula sends a value of 0, 1, or 2 to an instrument, the instrument is assigned a low soft stroke selected at 0, a medium stroke at 1, or a hard loud stroke at 2.

The same operations can occur as in FORMULA.


16 -DD /2 +CC /4 %3  xy
16 -DD /2 +CC /4 %3  ma
16 -DD /2 +CC /4 %3  vb

Code 0-7: Examples for PLAYING TECHNIQUE

  • The %3 operation at the end provides a value range from 0 to 2.
  • DD and CC are predefined variables (see below).

Restricted language coverage of the web application AOGdogmaWEB

  • To ensure an easy start with AOGdogma, a web application was written.
  • In its text area AOGdogma compositions can be inserted and modified.
  • This text area is cyclically reloaded by the software, so that every modification is immediately sonically implemented.

Compared to the above, the language range of AOGdogmaWEB is limited in the following way: playing technique is not implemented and no variables are predefined, especially not dt, t0, t1, DD and CC, see below.

While AOGdogmaWEB ensures a quick start with AOGdogma, the Java processing sketch AOGdogma offers more extensive possibilities within the "Distributed Libraries" of Processing: There you can animate the performance on demand. Wav-files can be created directly and scores in Lilypond format.

Predefined variables

Predefined variables are:

dt Minimum time step, typically 10 milliseconds. I.e. the script is evaluated every 10 milliseconds. 
   The specifications for PULSE should be integer multiples thereof.

t0 Start time in milliseconds. This value is added to t at 8000 100 ! t
   So if ts is the milliseconds since the start: t = t0 + 8000 + ts/dt 

t1 If a wav-file is modified, or if the boolean variable HAS_AN_END=true (only processing), then 
   the piece ends at this point. (Has no meaning for AOGdogmaWEB)

DD and CC result from the current midi value, so they are not fixed like the formulas for
playing technique may suggest.

DD Maximum pairwise determined dissonance value of the last 12 midi values (no matter in which voice) 
   including the current Midi event. Usually the value is between 0 and 10.
   More information: See source code of the Gradus class in Library ComposingForEveryone

CC Average dissonance value between the current midi event and all 12 previous midi events.
   Expresses how much the new event conflicts with the previous ones.
   More information: See source code of the Gradus class in Library ComposingForEveryone

Code 0-8: Predefined variables and their meaning.