On first parsing a script file, BoxyLady begins in an outer sample mode. Sample mode allows loading and saving of samples, libraries, and management of the program. Commands exist that move the program into other modes, such as global mode, synth mode, gamut mode, and sequence AKA "notes" mode.
Synth mode is entered by synth(COMMANDS). In synth mode, sound generators can be applied to one or more samples.
Notes mode is entered by seq(@SLOT type(FORMAT) channels=CHANNELS music=MUSIC). Here, SLOT is the new slot to be created, which must be a currently unused slot name, 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 []. Music expressions as detailed later.
Definitions can be created while in sample mode for use within notes mode (and therefore count as notes mode themselves) or as subroutines within sample mode. These are defined as def(NAME1=(COMMANDS1) NAME2=(COMMANDS2) ...) where as many name–command pairs can be defined as required in one def() block. All names must be currently unassigned to a slot.
User keyboard input to define a definition can be requested with input(NAME), which are created then using def.
Libraries are loaded from sample mode by library("FILENAME"). The commands inside are evaluated in sample mode. ––library("FILENAME") is similar, although does not raise an error if the file is not found.
Global mode is entered by global(COMMANDS). Global mode sets global default values used when parsing music expressions. As such, it uses the same commands as sequence mode, with the important exception that commands that cause music to be actually created may not be used (either silently ignored or error raised).
This section explains those commands available in outer (sample) mode that do not relate to processing of samples
BoxyLady(X.Y.Z) checks the version of the program against that specified, and warns if they do not match. This function is intended to be used at the head of an input file as a "magic number".
rem("TEXT") denotes comments. The whole of the argument is treated as a comment and skipped.
echo("TEXT") sends the argument to standard output as a comment.
echo(@SLOT) shows the contents of SLOT. If this is definition, it is listed. If it is a sample, a graphical summary is given.
correl_plot(@SLOT) shows correlation information between left and right channels of a sample, for debugging purposes.
exit() terminates parsing of the current input file or macro. Also terminates keyboard input if requested by the --i command-line argument. quit() is similar but quits the programme outright.
list(OPTIONS) prints a summary list of the contents of all slots. Information printed depends on the slot type. Units are in Hz, seconds, and Mb as appropriate. The flags G and I indicate whether gating and looping (for instrument samples) are set. System and locked slots are indicated by S and L.
If OPTIONS contains *, then all slots are shown, otherwise system ones are hidden.
defrag() trims music samples such that their m-length is equal to their p-length.
default:sample_rate(FREQ) sets the default sample rate, relative to which sample rates sr hi HI instrument are calculated. The built in default value is 44.1 kHz, equal to CD sampling rate for sample rate sr.
default:interpolation(BOOL) if TRUE (the default behaviour), then sample overlaying uses linear interpolation between source sample points.
default:max_instrument_length(D) sets the maximum allowed instrument length duration, generated by instrument(...). Beyond this, instrument samples are truncated. The default is 16 seconds.
default:standard_pitch(F) sets the assumed default pitch for the tuning system, in Hz. The default is 440 Hz.
show_state() displays global variables, and the default metadata list for creating new samples.
seed(val=VAL) seeds the random number generator to the value given by VAL. If not specified, the system clock is used instead.
Commands beginning with two dashes are reserved for internal use. But note the following Easter Egg.
--poem() prints a poem on the console.
default:metadata(key=KEY mp3=MP3 wav=WAV value=VALUE) sets a default metadata table entry for creating new samples. The default value of the named entry KEY is to be VALUE (which can be an empty string), and the variable to use in MP3 conversion strings is MP3. A RIFF tag WAV is used, which should be four characters long.
Several commands can handle samples or files by using external programs to BoxyLady.
ext("COMMAND") runs COMMAND as an operating system shell command.
terminal() starts an operating system terminal.
command:terminal(COMMAND) sets the shell command to be used when starting a terminal.
command:mp3 sets the command string used to convert WAV to MP3 via an external program, such as Sox. The command string should contain the following tokens if any of the matching metadata tags are used: %title %album %track %artist %year and %genre. The source and destination filenames replace the tokens %source and %dest. The default behaviour is just to echo the parameters to the console, however this may be overriden by standard .box libraries.
play(file=FILE arg=ARG) calls an external program to play FILE or render it in some other fashion on the console. If FILE is absent, no actual action is performed.
play(@SLOT arg=ARG mono) is similar, but saves SLOT to a temporary file first. Temporary files are removed. If mono is present, the sound is mixed to a mono track before saving, which can be useful to check for interference that might cause problems with loudspeakers rather than headphones.
quick(NOTES_MODE_DATA) generates a slot called "quick" using the music data provided, then plays this as above. Mostly for testing purposes.
command:play sets the command string used to play a WAV via an external program, such as Sox. It should contain the following tokens: %file and %arg, which are replaced by FILE and ARG respectively. As above, default behaviour is to echo parameters, overriden in libraries.
external(@SLOT command=COMMAND) is used for filtering SLOT through an external program such as Sox. COMMAND is an operating system shell command containing the following tokens: %source and %dest which are replaced by real temporary filenames by BoxyLady. Before calling COMMAND, SLOT is saved to a temporary file (%source), and after the command, SLOT is loaded back from another temporary file (%dest). Flags for SLOT are preserved. Temporary files are removed.
As an example, the following will reverse the contents of sample "tiny" using Sox:
external(@tiny command="sox %source %dest reverse")