SSCSSS Version 2.0 - Reference

Note this is a summary reference, not a tutorial. Additional explanations and examples are in a tutorial.

Input Files

Output Files - name from "file" line in specification (input) file

Info, source and binaries for gnuplot at: www.gnuplot.info.

Specification File Format

General

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:

  1. file -- file must be first.
  2. option -- No option's are required, but any present must be immediately after file.
  3. voice -- Each specification of waves must start with voice. There must be at least one voice in the input file, but there may be many.
  4. set / wave -- Each voice must be followed by at least one of set or wave. There may be more than one of each and also a combination of each. But, one voice group can only define up to four (4) waves -- whether by set or wave.
  5. offset -- No offset's are required, but any present must be immediately after set.
  6. filter -- No filter's are required, but any present must be immediately after all offset's.
  7. scale -- No scale's are required, but any present must be immediately after the offset or filter being scaled. Only offset's and filter's can be followed by scale.
  8. point -- At least one point is required after each scale. There may be more than one.
  9. formant -- No formant's are required, but any present must be immediately after all filter's.
  10. split -- At least one split must follow each voice (after offset's, filter's. and formant's).
  11. note -- Zero or more note's may follow split.
  12. condition -- At least one condition must follow split (after any note's).
  13. wave -- wave must follow the last condition of the previous set or voice if the voice had not set's.
  14. sample -- Each wave must be followed by at least one sample.
  15. harmonic -- Each sample must be followed by at least one harmonic.

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.

1234567
filename
optionname[p1]
voicenamecategory[bend][low][high] [norm]
set
offsetnumberlevel[phase]
filtertype[p1][p2][p3][p4]
gpointfreqgain
scaleargument
pointp1frequency
formanttype[p1][p2][p3][p4]
gpointfreqgain
splitnotes_per_sample
notecenterlowhigh
conditionoperatorp1[p2]
wave
samplecenterlowhigh[frequency]
harmonicnumberlevel[phase]

Detailed argument descriptions.

  1. file name

    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.

  2. option name [p1]

    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.

  3. voice name category [max_up_pitch_bend] [low_note high_note] [norm]

    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.

  4. set

    Set marks the start of a (new) wave-set specification. Each harmonic is initailized to 0 dba level (max) and 0 phase.

  5. offset harmonic_number level [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.

  6. filter type p1 p2 [p3] [p4]

    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

    typep1p2p3p4
    coscentergainwidth
    trianglecentergainwidth
    highpasscutoffslope
    lowpasscutoffslope
    lowpass_fcutoffslope
    highshelffreqgainslope
    lowshelffreqgainslope
    bandfreq1freq2gainslope
    graph
    gpointfreqgain

    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.


  7. scale argument

    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:


  8. point p1 frequency

    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.

  9. formant type p1 p2 [p3] [p4]

    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.

  10. split notes

    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.

  11. note center low high

    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.

  12. condition operator p1 [p2]

    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.

  13. wave

    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.

  14. sample center_note low_note high_note [frequency]

    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).

  15. harmonic harmonic_number level [phase]

    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.

Parameter units are the following:

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.

Processing Notes

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.