Note this is a summary reference, not a tutorial. Additional explanations and examples are in a tutorial.
Info, source and binaries for gnuplot at: www.gnuplot.info.
Blank lines and lines starting with '#' (for comments) are ignored.
Each line has one or more arguments separated by any combination of one or more spaces or tabs, but at least one space or tab.
The following is a description of the "legal" sequences of lines:
For programmers, the valid sequences of first arguments are described by the following (almost) regular expression.
file option* ( voice must have at least one set/split or wave ( set ( scale point+ )* ( offset ( scale point+ )* )* ( filter gpoint* ( scale point+ )* )* formant* gpoint* ( split note* condition+ )+ )* ( wave ( sample ( harmonic )+ )+ )* )+
The other arguments for each first argument are as follows: ( '[' ']' indicates optional or not always used.) (details for each argument follow the whole list)
"p1" "p2" etc. short for "parameter 1" "parameter 2" etc. "parameter" used for cases where the argument meaning depends on a previous argument, e.g what filter p3 is depends on filter type.
1 | 2 | 3 | 4 | 5 | 6 | 7 |
---|---|---|---|---|---|---|
file | name | |||||
option | name | [p1] | ||||
voice | name | category | [bend] | [low] | [high] | [norm] |
set | ||||||
offset | number | level | [phase] | |||
filter | type | [p1] | [p2] | [p3] | [p4] | |
gpoint | freq | gain | ||||
scale | argument | |||||
point | p1 | frequency | ||||
formant | type | [p1] | [p2] | [p3] | [p4] | |
gpoint | freq | gain | ||||
split | notes_per_sample | |||||
note | center | low | high | |||
condition | operator | p1 | [p2] | |||
wave | ||||||
sample | center | low | high | [frequency] | ||
harmonic | number | level | [phase] |
Upto 8 character name without extension. This name is used with extension "s1m" for the ex wave file and extension "log" for the log file. Since the name "init" is used for the initialized s1m input file, it cannot be used here.
The presence and interpretation of p1 depends on the name. Recognized names are the following:
If an option is specified more than once, the last specification overrides any previous specification.
Name must be 1 to 12 characters. This program does not actually generate EX voice data. However, this name is used to name the samples and waves that presumably will be used together in a voice.
Category is an EX voice / wave / sample category. It is copied to the wave and samples for a voice.
The optional max_up_pitch_bend argument is used for aliasing checks. This is the number of half notes or semi-tones that will be set for bending a pitch up in the EX. The range is 0 to 128. Obviously, this program has no way of "knowing" whether this is actually the setting in the EX.
For "wave" (described below), if a harmonic for a note would alias after being transposed up from the center note to the high note for that sample, then transposed up again by the max_upward_pitch_bend, a warning message is issued.
For "set" (described below), the program will not generate the possibly aliasing harmonics.
Low_note and high_note are not used for "wave", but are required for "set". (wave and set are describe below.) This means that the bend parameter is also required for set, not wave. The set command uses these for setting the lowest and highest notes defined in the EX wave. These are MIDI note numbers, 0 to 127. Also the low cannot be higher than the high.
"norm" may be set to "sample" or "voice". The default is sample, unless the set line is used, then the default is voice. This determines whether normalization is done for individual samples, or for all samples in a voice.
EX waves and the samples they contain can be specified to this program in two ways. A "high level" way via a (wave) set and a "low level" way specifying each harmonic of each sample individually. Wave-sets are specified using the set, offset, filter, formant, scale, point, split, note, and condition lines. Waves are specified by the wave, sample, and harmonic lines. Voices may consist of both. The waves specified by wave-sets are processed internally into wave/sample/harmonic specifications and then processed like waves.
Set marks the start of a (new) wave-set specification. Each harmonic is initailized to 0 dba level (max) and 0 phase.
Offset will adjust the level (and optionally phase) of a single harmonic for a sample. Both level and phase can be scaled across the keyboard. The harmonic number must be >= 1. The level must be between -90 and 90. The phase must be <= 0 and > 1. Phase is interpreted as a fraction of a cycle. Phase defaults to 0 if not specified.
Filter and formants have nearly the same arguments. For filters, the frequencies are in terms of intervals from the first harmonic. For formants, the frequencies are absolute. The parameters for filters can be scaled across the keyboard. The parameters for formants cannot. For both, the action is to adjust harmonic levels before the sample or audio signal is generated. The filters on the EX act on the audio signal, like most filters. Any number of filters/formants can be specified. But, of course, unlike the EX filters they cannot be modified while playing.
filter/formant types and parameters
type | p1 | p2 | p3 | p4 |
---|---|---|---|---|
cos | center | gain | width | |
triangle | center | gain | width | |
highpass | cutoff | slope | ||
lowpass | cutoff | slope | ||
lowpass_f | cutoff | slope | ||
highshelf | freq | gain | slope | |
lowshelf | freq | gain | slope | |
band | freq1 | freq2 | gain | slope |
graph | ||||
gpoint | freq | gain |
type and parameter descriptions
for cos and triangle
for highpass
for lowpass
for lowpass_f
for highshelf
for lowshelf
for band
for graph / gpoint
A filter or formant of type graph must be followed by two or more gpoint lines, Scaling is not permitted. All frequecies below the first point will have the gain of the first point and all frequecies above the last point will have the gain of the last point. The gpoint lines must be ordered by increasing frequency.
The argument of the immediately preceding set, offset, or filter specification which is to be scaled to different values for different samples.
Currently scalable arguments are the following:
When scaling a parameter, the value on the offset or filter specification line is taken as the value for the lowest sample. The frequencies on the point specification lines must be increasing from the frequency for the lowest sample. The value from the last point line is continued to the highest frequency sample, if necessary. Specifying more scaling points than there are samples is allowed, but may not be useful. Also, note that the EX does not interpolate between samples. Specifying fewer scaling points than there are samples does make sense and the program will do linear interpolation between scaling points. The ranges are the same as the ranges for the scaled arguments.
Like filter except center/cutoff/frequency is an absolute frequency, there is no scaling, and the lowpass_f type is not available.
Frequencies between 1 and 20,000.
The set, offset, filter, formant parameters describe a possible set of samples. But, the split and condition specification actually direct the program to create a set of samples (an EX wave) based on the preceding specifications and the split condition specifications. There will be as many waves (and their samples) created as there are split specifications, at least one is required.
The range for notes is 1 to 128 or the string "list". If the value is a number, it is the number of notes per sample and the note list is generated by the program. If the value is "list", a note list must follow.
The number here, or the note list following, determines the number of samples that will be generated for the wave.
The default note list generated by the program set center = low and high to low + notes -1, etc. The default can be overriden by specifying the note center low and high for samples here. (In effect, each note line directs the program to create a sample.)
If specified, all lines must have 0 <= low <= center <= high <= 127. For all lines except the first the current low must = previous high +1.
Given the preceding specifications of harmonics and phases, the condition lines determine which harmonics will be generated for the samples of this split (or wave). The conditions are checked for each harmonic, If more than one condition is specified and none of the conditions are "not", "and", or "or", all conditions must be true for the harmonic to be included.
expressions for wave-split:
=, <, >, <=, >= p1 [frequency] p1 defaults to harmonic #. If frequency is specified, p1 will be treated as frequency. Frequency must be between 1 and 20000. Harmonic must be greater than 0. "=" is less useful with frequency.
% p1 p2 -- harmonic # % p1 = p2.
This condition uses integer arithmetic (no fractions). If the remainder of dividing the harmonic number by p1 is p2, this condition is true. The divisor must be greater than 1 and the remainder must be from 0 to 1 less than the divisor.
not, and, or
Boolean combinations of above interpreted as RPN.
This line, along with the next two, is the other way of specifying EX waves. The wave line, no parameters, indicated the beginning of a wave.
This line specifies a sample to be generated for this wave. The three note numbers are MIDI note numbers. The frequency for the sample is the standard frequency for that MIDI note number, unless a frequency is specified, in which case that frequency is used. This is the frequency of the first harmonic. The center is EX sample editing center. The low and high notes are the EX wave editing low and high notes.
The ranges for center low and high are 0 to 127, Also, low must be <= center and center <= high. The range for frequency is the low frequency (default 1 Hz, may be changed by an option) to half the sampling rate (22050 Hz).
The harmonics for a sample are specified with this line. If not specified, a harmonic will not be generated. The level for the harmonic must be specified. The phase will default to 0 if not specified. The harmonic must be greater than 0 and increasing from one harmonic to the next. Harmonics need not be consecutive. The phase must be >= 0.0 and < 1.0 . Phase is interpreted as a fraction of a cycle.
Name and category parameters are strings - not all digits.
Center_note, low_note, high_note parameters are MIDI note numbers, whole numbers 0 through 127 (middle c is 60 per MIDI specification).
Level and gain parameters are in dba (relative to maximum 0 dba) They may be positive or negative and may be or contain fractions.
Frequency parameters are in Hertz. They must be positive and may be or contain fractions
Phase parameters are in fractions of a full cycle. They must be greater that zero and less than one.
Harmonic numbers are integers equal to or greater than 1.
Center (for filter) and width parameters are octaves. They must be greater than zero and may be or contain fractions.
Except for keeping track of the total number of waves and samples for the s1m file, everything is forgotten from one voice to the next. Note -- for this program wave layer = sample, even though this is not true in general for the EX.
All processing for wave sets is done in the frequency domain by adjusting harmonic levels and phases before the audio samples are generated. Other than conversion to the EX s1m format, there is no audio time domain processing in this program. Note -- the filters etc. in the EX (and most synthesizers) work with audio signals in the time domain.
Wave set processing results in creating the same internal data as might have been specified for waves. (The logws option will put this generated data in the log file in a form that could be fed back in to a later run, presumably after some editing.)
The samples are generated from the wave/sample/harmonic specifications whether from the input file or generated from the wave set.
Samples may be collectively normalized for a voice. This means that some individual samples will not be normalized considered separately, but the level relationships defined in the input file will be maintained across separate waves of the voice.
If samples are normalized by sample, each sample is normalized independently of all other samples.
The logged generated wave set, logged generated waves, and plot options use the same normalization factor as the sample generation.