Introduction
BoxyLady is a music sequencer package to convert plain-text instructions (.box format script files) into digital music (WAV files). Input files can also include music files in WAV format.
To run BoxyLady type BoxyLady SOURCE from the command line, where SOURCE is a script file containing music instructions. Further command line options are explained below.
BoxyLady scripts can also include 'library' script files. Furthermore, at start up, the file '.BoxyLady.box' is attempted to be loaded (if it exists) from the user home directory.
The rest of these documents explain the commands possible in the script files. Commands are given in lower case, and metasyntactic variables in bold. All commands are denoted by blue text.
BoxyLady maintains a list of named "slots". Each slot may represent a sound effect patch, a macro, a sequence of music, and so on. Slots are always referred to by their unique name: names specified by the user can only contain alphanumeric characters and characters from the following set: :._- .
Sample types
Slots containing audio data are stored in 1 or 2 interleaved channels consisting of 16-bit data. In script files, each sample is considered to have values ranging from -1 to +1.
Several sample rates are defined. CDDA is standard CD format, 44.1 kHz, and DVDA is standard DVD format, 48 kHz. standard, double, quadruple, and octuple are one, two, four, and eight times the program's default sample rate, also set at 44.1 kHz. instrument is equivalent to quadruple but also sets the loop flag, indicating that this slot is designed to be used as an instrument as opposed to passage of music. half and quarter are half and quarter. Other sample rates include telephone at 8 kHz, with wideband and 32k at double and quadruple this value.
A user-specified sample rate can be specified by user(Hz=FREQ).
Sample format strings can also contain Boolean values for start_anywhere, loop, and loop_start. If loop is set, samples used as intstruments will repeat once the end is reached, starting from loop_start, which defaults to zero. If start_anywhere is set, samples used as instruments are started at any point, adding variety.
Slots containing audio data have three duration parameters. The p-time is the physical length in seconds. The t-time is the duration in terms of musical tempo that the patch will occupy if daisychained together. p-time may be longer to allow for reverb. t-time may be longer than p-time similarly. The m-time is the amount of space currently allocated for the slot by the programme to allow for efficient expansion.
All volume measurements are linear unless otherwise stated in the range 0-1. Negative or out-of range amplitudes can be used for amplification and inversion. All frequency offsets are given in proportions of a cycle. All time units are in seconds.
Input file syntax
Input files consist a series of white-space delimited tokens. For using program functions, tokens can be nested within tokens if surrounded by (), <> "", {}, or [], with no white space between the opening delimeter and the parent token. Tokens can also consist of a key–value pair, separated by an = sign with no white spaces. @NAME automatically produces a key value pair @=NAME commonly used to represent slot names. Tokens delimeted by "" cannot nest but can contain white-space. Some special sequences can be used in these: \\ represents a backslash, \n a new line, and \" represents a double quotes. This is all best explained by examples.
- Plain list of tokens
- fred jim shiela
- "Function" with no arguments
- list()
- "Function" with argument list
- delete(fred jim shiela)
- Key–value pair
- sharon=tracey
- Alternate form for the above
- sharon(tracey)
- Yet another alternative
- sharon=(tracey)
- Token containing whitespace
- filename="my documents/sharon.txt"
- Alternate filename without whitespace
- filename(sharon.txt)
- Reference to a slot name
- @tracey
Named parameters can generally be used in functions in any order. Nameless ones must be specified in the correct order.
Most functions require () or "" to be used as delimeters. (Though sharon(tracey) might be used as an alternative for sharon=tracey, the reverse isn't true.) Music data can require [], {}, and <> as explained elsewhere.
Common values
Several commonly used functions are encountered are explained here. All these require a series of parameters.
In most cases, amplitude and volume-like values can be specified in one of three forms: X dB=Y Np=Z. X is an amplitude, typically in the range 0-1, and small values are frequently encountered since volume perception in human hearing is close to logarithmic in scaling. Y is a value in decibels, typically negative where 0 dB is maximum power. Np is a value in Nepers, typically negative again, where 0 Np is maximum amplitude.
wave(FREQ AMP OFFSET) represents a cosine wave where FREQ is the frequency of a cosine wave (in Hz), AMP is the amplitude (1.0 meaning full volume) and OFFSET is an amount by which the waveform is advanced in the time domain, as a decimal fraction of a cycle. The final two parameters are optional (default to 1, 0).
vib(FREQ VAMP OFFSET BEND BEND_T): As above, allowing for pitch bend, where BEND is a given as a multiplier of FREQ per second (i.e. not in Hz) for a duration BEND_T. The final 4 parameters are optional (default to 1, 0, 1, 0) and may not be used for all functions. Pitch bends are exponential across time (linear in pitch space), whereas vibrato is applied linearly, i.e. (X*(1-VAMP)) to (X*(1+VAMP)).
Both wave and vib can be specified as (off) which implies zero frequency and amplitude.
ENV(AT AA HT HA DT DA ST SA FT) represents an amplitude envelope. ENV might be e, env or envelope depending on context. Here, AT, HT, DT, ST, and FT are the durations (s) of the attack, hold, decay, sustain, and fade/release stages of a musical note. AA, HA, DA, and SA are the target amplitudes to be reached at the end of each stage. The initial and final amplitudes are by definition 0. A value of ENV(off) implies no envelope and a constant unit value. Alternate simpler formats are ENV(AT AA DT DA ST SA FT) (as seen on the BBC Micro!), ENV(AT AA DT DA FT), ENV(AT AA FT), ENV(AT FT) (where AA=1), and ENV(AT) (where FT=AT and AA=1).
STEREO(L R): L and R are amplitudes pertaining to a left and right channel. Alternatively, STEREO(POS) sets a particular stereo position of off (1 1), L (1 0), or R (0 1). STEREO(AMP) sets both channels to the same value. There are several different STEREO functions.
Boolean values can be specified as T TRUE F FALSE
FREQ_RATIO represents one of the following options: RATIO c=CENTS f(NUM DENOM) o(OCTAVE) mO(MILLIOCTAVE). I.e. a plain positive number, a number of cents (where 1200 cents is equivalent to a ratio of 2), a fraction given by NUM/DENOM, a number of octaves, or a number of millioctaves.
Running BoxyLady
The BoxyLady command can be followed, when typed at the command line, with a string of options detailed below. Most of these do not require parameters. In addition, if any parsing of music files is required (as is usually the case!) one or more source script files should be provided in the command line. Options and source files can be specified in any order.
SOURCE_FILE: where a local or absolute filename is given. Source files are generally given the file extension .box. More than one source file can be specified, in which case they are parsed in the order listed.
--noboot -n: causes parsing of any default local files to be skipped.
--envshow -e: displays the BoxyLady instructions used by the program during initialisation.
--outer 'SOURCE' -o 'SOURCE': causes SOURCE to be directly executed as BoxyLady commands (after any initialisation).
--quick 'SOURCE' -q 'SOURCE': causes SOURCE to be directly executed as notes mode commands (after any initialisation) as if using quick(SOURCE).
--version -v: prints version and licence information. †
--help -h: prints command line usage instructions. †
--messages LEVEL -h LEVEL: sets the verbosity level, where LEVEL can be one of none errors messages verbose. †
--interactive -i: causes input to be sourced from the console and executed as BoxyLady commands (after any initialisation). Each line of input must be complete (unlike in a source code file), with no multi-line commands. †
† Can also be used in outer (sample) mode, as a function with parentheses, e.g. --version()
Multiple sources of input (e.g. several files, or -o, -q, or -i input) are executed in order, after initialisation.