||This program accepts commands and expressions in a language.  If you enter something not recognized as a command, or explicitly prefixed with "|", it will be treated as a language construct, either a function definition or a function call.  The complete and authoritative reference is the source code.  Failing that, the file NOTES is very complete (it is a project diary).  Or you can just use the online help (this).
language|language reference|The main ggb language provides a way for defining functions using a certain set of expressions and other functions, including some builtins.  Pretty much all numbers are represented in fixed-point (16.15 bits) for efficiency.  In general it is also compiled for speed (ggb generates C code when a function is first used and then invokes gcc and then dynamically links the compiled function as if it were a builtin).  It can also be used in interpretted mode, which does not allow access to term sequences, but does allow access to stereo signals.
language values|syntax for numerical values and simple expressions|ggb recognizes decimal numbers and simple expressions, using the familiar operators such as +, -, *, /.  Reasonable order of operations rules, including the use of parentheses exist, but note that things right-associate by default.  It is generally important to be careful about the order that operations are performed, even if you are seeking an equivalent result, to avoid rounding error (allowing an intermediate value to exceed 2^16 or relying on accuracy below 2^-15 may fail silently but often very loudly).  Also note that in interpretted code you may use curly braces, as in { left value, right value } to define stereo values (all values in interpretted mode are stereo, just equal on left and right by default).  You may also define values as 'xyz' where x is the note (A-G); y is one of - (normal), # (sharp), or b (flat); and z is the octave (0-A).  Notes evaluate to the numerical value of the frequency of the note (i.e. 'A-5' is 440.0).  You may also use strings ("fred"), but pretty much just as the filename argument to the builtin waveform().
language functions|syntax for defining and using functions|In ggb you define a function with   funcname[arg1,arg2] = expression;   or alternatively you may use := to indicate that funcname will be compiled for speed.  When a function is compiled, every function it calls is inlined to generate the most efficient code, so they are compiled regardless of how they are defined.  A function with zero arguments is like a constant, i.e.   const[] = value;   To invoke a function, you would use   funcname(arg1,arg2).  The parentheses may be left off entirely if there are no arguments.
language time|how time and the special variables t and t_ work|To get an efficient implementation of fixed point audio, t (the time in seconds since the beginning of the evaluation of this expression) must always appear multiplied by another value, and this multiplication is then strength reduced to an addition that occurs every time a consecutive sample is computed (and also loops around to 0.0 above 1.0, to help feed look up tables).  The builtins are generally designed so that one cycle is completed between 0.0 and 1.0, and also feature oversampling to work well with this strength reduction.  For example, a sine wave at 440Hz would be sin(440*t).  However, due to fixed point rounding errors, computing the step every sample is only accurate for relatively high frequencies (say from 10Hz up?).  Multiplication by t_ instead of t is only evaluated every 100 cycles, so it is totally useless for anything over 441Hz (really best much lower).  It is used most often for envelopes or slower effects like vibrator.  If you wanted a vibrato effect of +/-10Hz at 0.5Hz it could be sin((10*sin(0.5*t_)+440)*t).  Note that once a value has been multiplied by t it should generally be passed to a builtin immediately -- adding a phase shift (for example) would not generally have the intended effect.
language builtins|the builtin functions and how to use them|
language builtins sin|sin(t) = 1Hz sine wave, 2^17 samples in a lookup table|
language builtins cos|cos(t) = 180 degrees out of phase 1Hz sine wave|
language builtins white|white() = noise (just calls random())|
language builtins waveform|waveform(2*t,"fred.gga") = sample one octave up|
language termseq|term sequence, the way to vary over time|This is the fundamental inspiration for ggb.  You can specify an expression that is a sequence of terms, the value of the expression is each term in sequence.  For example: [dur1: term1, dur2: term2, dur3: term3 and so on].  The expression has the value of term1 for the first dur1 seconds, and so on.  t and t_ essentially reset to zero at the beginning of each term.  If two colons are used instead of one, it waits (up to a 10ms) for a zero crossing in the term before continuing, to avoid clicking.  If a duration is -1 then that term is used until a note up event is seen.  If a single colon appears after the closing brace, the whole sequence will repeat (with some caveats).  Term sequences are extremely flexible and can be used in almost any situation and provide the natural tool for implementing ADSR envelopes.  It is important that most 'normal' instruments use a term sequence somewhere, otherwise notes will never end.
format|a description of some file formats used by ggb|
format evt|simplified MIDI event file|This file contains the most simple text-based MIDI stream.  Events occur one per line, with any unrecognized text ignored.  Lines can be "N<note>,<velocity>" which represents a note down event for the specified midi note (0-127) with a specified velocity (also 0-127).  "U<note>" specifies a note up event for that note (the same as "N<note>,0").  "T<delay>" indicates a delay of a specified number of miliseconds.  "S<sysex number>" indicates a sysex event, which is handled through whatever mappings are active during playback.
format trk|an abstract heirarchical tracker format|.trk format files contain a series of definitions, one definition per line.  Blank lines and lines beginning with "#" are ignored.  A tracker file contains a number of dictionaries (identified by an alphanumeric name), each of which in turn consists of up to 52 definitions (lettered "a" to "z" and their uppercase counterparts).  When a tracker file is loaded, all definitions in the "main" dictionary are executed immediately, and these typically call upon other definitions.  A definition line consists of a dictionary name followed by an underscore followed by a single lower-case letter, then the definition content (for details see the sub-topics).  All events in a tracker file occur in a certain number of ticks specified by the "rate" command, so it is traditional to put a "main_a: rate 4000" or similar definition to specify the clock.
format trk command|the command definitions|A definition of the form "dict_z: command", when executed, will run the specified command immediately as though it were typed into the command line.  There is one special feature, if an @ is present at the end of the command followed by a number, then after that many ticks a note up event is generated.  For example, "main_b: inst(440,1.0) @ 3" will define a "b" entry in the "main" dictionary that will play a middle A on the main instrument and sustain for 3 ticks before release.
format trk sequence|the sequence definitions|A definition of the form "dict1_z dict2 16 [abc]" will define an entry "z" in the dictionary "dict1" which, when executed, will play a, then b, then c entries from "dict2" in sequence, pausing for 16 ticks between them.  If a space is encountered between the brackets, it pauses for 16 ticks without starting a new event.  If a 0 tick pause is specified, all events inside of the brackets are started simultaneously.  In this manner you could, for example, define a "cmaj" dictionary that contains entries a, b, and c that contain command definitions to start notes playing at C, E, and G respectively, and so on for "fmaj" and "gmaj".  Then you could define a "bassline" dictionary that contains arpeggios in these 3 keys: "bassline_a cmaj 4 [abcb]" then "bassline_b fmaj 4 [abcb]" and so on.  Then you could define the bass line for the whole song as "main_b bassline 16 [aacbaacbaaaaccbb]" and so on.  This is just a sample of the organizational capacities of the .trk format.
format trk extended|the extended sequence definitions|A definition of the form "dict1_z 16 {\ninst('A-5',1.0);\ninst('B-5',1.0);\n}" is an extended sequence definition.  It is essentially the same as a normal sequence definition except instead of having single-character commands coming from a single source dictionary, every beat gets a full line and may be any normal command or a dictionary entry to play preceded by a colon (such as ":dict1_x").  Note that the first line must end at the { and the last line must be an } alone on its own line.
format trk parameters|dictionary parameters|When a dictionary is referenced as the source dictionary for a sequence definition, it may be followed immediately by parameters in paretheses, separated by commas.  These will be macro substituted for $0-$9 in any command definitions in that dictionary.  For unspecified arguments, if the source dictionary and the definition dictionary are the same, it will inherit the same arguments it was called with.  Otherwise, unspecified arguments get the default value defined by statements like "dict_0: 1.0".  Parameters may also be passed when invoking a specific definition from an extended sequence definition.
format gga|the GGA compatible sample format|This is a headerless file containing little-endian 16-bit samples in stereo pairs sampled at 44.1kHz.  Sox recognizes it as "-t raw -r 44100 -s -w -c 2"
quit|command: ends ggb|
stop|command: stops currently proceeding events (sounds, etc)|
stop sound|stop currently playing sounds|
stop tracker|stop currently playing tracker files|
stop midi|stops playback of recorded MIDI events|
stop pattern|stops playback of patterns|
stop all|stops all sounds and all sources of sounds|
load|command: reads in a file as a sequence of language statements|
source|command: reads in a file as a sequence of commands|
map|command: maps MIDI key events to commands|Used as either "map <event #> <command>" to map a SYSEX event to a command (like a macro), or "map note <note #> <function name>" to map an individual note to a two-argument call of the specified function.  A blank mapping undefines the mapping, restoring default handling (ignore SYSEX, play notes).
show|command: displays running program status|
show sounds|displays playing sounds|
show functions|displays defined functions|
show maps|displays defined mappings|
show tracker|shows active trackers|
show midi|shows whether MIDI playback/record is active|
freq|command: load a new frequency table|Takes two arguments: steps and base.  steps is the number of notes per octave, base is the frequency of the lowest C ("C-0").  The default is "freq 12 8.1758".
play|command: play a tracker (.trk) file|Plays the specified .trk file throuh once.  It takes an optional number after the filename which is the number of ticks to skip at the beginning of the song (so you do not have to listen to the intro over and over).  See help on format trk.
loop|command: loop a tracker (.trk) file|Plays the specified .trk file on repeat (like for developing loops).  This feature is most useful when used in conjunction with the "load" command.  It takes an optional number after the filename which is the number of ticks to skip at the beginning of the song (so you do not have to listen to the intro over and over).  See help on format trk.
rate|command: set the tracker rate|The tracker playback rate is specified in ticks per minute.  This is mostly a helper command to be used within .trk files.  To see how ticks are used, see help for format trk.
dev|command: change audio output device|changes the audio device that output is sent to
mrecord|command: records a sequence of MIDI events to a file|Used as "mrecord <filename>" to record MIDI events to the given filename (extension .evt added).  See the help for "format evt."
mplay|command: plays a sequence of MIDI events from a file|Used as "mplay <filename>" to play the given MIDI event file file (extension .evt added).  See the help for "format evt."
write|command: saves the audio waveform output to a file|Saves the output in GGA-compatible format (see help on format gga).  To stop writing to this file, either quit ggb or do write without an argument.
mic|command: set the microphone record level|Input from a microphone (see MIC_FILE in snd.h) is mixed in with the main output if this value is greater than 0.0.  1.0 means unity gain and will likely cause clipping.
inst|command: manipulate the list of instrument functions|The instrument list is a conveniently walkable (i.e., from MIDI SYSEX events using the map command) list of available instruments.  When one is used from this list, it is as if "inst[x,y] := inst expression" were typed.
inst add|add an expression to the list of instrument functions|
inst next|set the inst[] function to the next one in the list|
inst prev|set the inst[] function to the previous one in the list|
inst show|display the list of language expressions|
inst goto|skip to a specific expression by number|
inst reset|reset to empty instrument list|
keyboard|command: toggle on-screen keyboard|
path|command: set search path|most files can be found in a search path, specified with colons separating directories to search.  Run "path" with no arguments to see the current path.
cachedir|command: set cache path|ggb will save compiled .so files in this directory.  Run with no arguments to see the current cache directory.
sound|command: turn the sound output on or off (i.e., "sound on")|
pattern|command: manipulate "patterns"|Patterns store what can be considered loops (which are a specified number of "measures" long) that can be entered and layered interactively.  Patterns are indexed by number.  If "pattern" is immediately followed by a subcommand, the subcommand applies to a default pattern, which is generally the last pattern used.  If there is a numeric argument inserted before the subcommand, the corresponding pattern is selected.
pattern new|create a new pattern|The first optional parameter is the number of measures in the new pattern, which defaults to 1.  The second optional parameter is a sequence of MIDI note events with timing information.  Each note event consists of "offset,note,velocity,duration".  Offset is the offset in miliseconds from the start of the pattern, note is the MIDI note value (0-127), velocity is the MIDI velocity (0-127), and duration is the time in miliseconds before the MIDI note up event.  If no sequence of MIDI note events is specified, it will begin recording MIDI events them from the keyboard.  If a pattern number is explicitly specified, it is overwritten.  Otherwise, a new pattern is created.
pattern tempo|change the duration of a "measure"|If no argument is specified, it begins playing the currently active patterns and sets the measure end time when the first MIDI note event is received.  Otherwise a single numeric argument specifies the length (in miliseconds) of a measure.
pattern mute|toggles the mute flag for a specified pattern|
pattern start|starts looping playback of all unmuted patterns
pattern stop|stops all pattern playback|
pattern write|save pattern information to a file|Writes all patterns (or a single one if one is explicitly specified) to a named file (with the default extension of ".pat").  The pattern file can then be loaded with "source", as it will consist of just a sequence of "pattern" commands.
pattern shift|shift a specified pattern in time|Takes a single optional argument, the number of miliseconds to delay the specified pattern by (negative offsets are accepted).  If the argument is omitted, it will shift the pattern note events to begin at offset 0.  This command would be used to correct a pattern that is slightly out of sync.
pattern inst|specifies the instrument function for pattern playback|Takes a function to be used instead of "inst" when playing back the specified pattern.
pattern measures|sets the number of measures in the pattern after the fact|Has a single
pattern rhythm|impose an artificial rhythm upon a pattern|The parameters are floating point numbers specifying a fraction of a measure.  The first parameter specifies the duration of the rest before the sequence, then further parameters specify the duration of the rest between notes (the duration of the notes is unchanged by this command).  If there are fewer parameters than notes, they are reused in sequence.
pattern list|display list of all patterns with status information|
