Introduction

BoxyLady user manual

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 '.BoxLady.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 the characters '_' and ':'.

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. ob is standard CD format, 44.1 kHz. sr, hi and HI are one, two, and four times the program's default sample rate, also set at 44.1 kHz. instrument is equivalent to HI but also sets the instrument flag, indicating that this slot is designed to be used as an instrument as opposed to passage of music. lo and LO are half and quarter. Note that despite being in capitals, LO and HI are not metasyntactical variables in this context.

A user-specified sample rate can be specified by Hz=FREQ.

Slots containing audio data have two 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.

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. This is all best explained by examples.

Plain list of tokens
fred jim shiela
"Function" token 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. Music data can require [] and <> as explained elsewhere.

Several commonly used functions are encountered are explained here. All these require a series of parameters.

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.

vib(FREQ AMP OFFSET TARGET): As above, allowing for pitch slide, where TARGET is a final target frequency given as a multiplier of FREQ (i.e. not in Hz).

Both wave and phaser can be specified as (off) which implies zero frequency and constant unit value.

ENV(AT AA DT DA ST SA FT)represents an amplitude envelope. ENV might be e or envelope depending on context. Here, AT, DT, ST, and FT are the durations (s) of the attack, decay, sustain, and fade stages of a musical note. AA, 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.

STEREO(L R): L and R are amplitudes pertaining to a left and right channel. STEREO(off) implies a default, central stereo position. There are several different STEREO functions.

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.

--version: prints version and licence information. †

--help: prints command line usage instructions. †

--messages LEVEL sets the verbosity level, where LEVEL can be one of none errors messages verbose. †

--noboot: causes parsing of any default local files to be skipped.

--envshow: displays the instructions parsed by the program before any script files are reached.

† Can also be used in outer (sample) mode.