The NeXT Music Kitä SynthPatch Library 
(release 1.0)
	
ã NeXT Inc., 1989 
		David A.  Jaffe and Michael McNabb

This document describes the 1.0 release of the NeXT Music Kit SynthPatch Library.  The Library contains a number of SynthPatches (software instruments) for doing synthesis in a variety of ways.  Some are simple and many of these can be run at once in real time.  Other are more complex, allowing fewer real-time instances.

[Comments specific to the CCRMA Summer Course are given in italics, surrounded by brackets.]

Below, we give a brief description of each SynthPatch followed by a detailed description of its parameters.  Since many SynthPatches have parameters in common, the common parameters are grouped at the end of this document.  Also at the end of the document is a description of the NeXT Timbre Data Base and its contents.  The parameter groups are:

Standard Parameters - Recognized by all SynthPatches.
Standard Oscillator Parameters - Recognized by most SynthPatches.
Vibrato Parameters - Recognized by SynthPatches with vibrato.
FM Parameters - Recognized by FM SynthPatches.
Double FM Parameters - Recognized by bi-modulator FM SynthPatches.
Noise Modulation Parameters - Recognized by FM noise SynthPatches.
MIDI Panning Parameters -Recognized by SynthPatches that support MIDI panning.

The patches listed below are those that come pre-loaded into the playscore program and the ScorePlayer application.  A number of other SynthPatches are provided in the Library, but these are of limited use and are mostly minor variations of those described below.  For example, Fm1 is just like Fm1i except that it uses a less expensive lower-quality oscillator.  Fm1 is used primarily in dense musical textures where the number of voices is more important than the sound quality.

[The CCRMA Summer Course uses a special program, midi-dsp-playscore, that is able to do both MIDI and DSP synthesis at the same time.]

Note that MIDI parameters are always optional and default to "no effect".  For example, if velocity is omitted, no attenuation or boost of the amplitude occurs.  All parameters have default values.  All parameters are reset to their default values at the end of a phrase.  The exception is that parameters set with noteUpdates without noteTags are sticky.  

Naming Conventions

A consistant naming convention using abbreviations makes it easy to remember the synthesis technique each patch represents.  These conventions are best illustrated  by example.  The abbreviations are given in bold-face type in the descriptions:

   Wave1	-  Wavetable synthesis with 1 non-interpolating (drop-sample) oscillator.
   Wave1i	-  Wavetable synthesis with 1 interpolating (high-quality) oscillator.
   Wave1vi  -  Wavetable synthesis with 1 interpolating osc. and random and
	    sinusoidal vibrato.
   DBWave1vi - Same as Wave1vi, but with access to the Timbre Data Base.
   Fm1vi      -  Fm synthesis with 1 modulator, vibrato, and interpolating carrier.
   Fm2pvi    -  Fm synthesis with 2 modulators in parallel, vibrato, and interpolating 
	    carrier.
   Fm2cvi    -  Fm synthesis with 2 modulators in cascade, vibrato, and interpolating 
	    carrier.
   Fm2cnvi  -  Like Fm2cvi, but with an additional noise modulator.

Pluck

Pluck implements a Plucked string with fine-tuning of pitch and dynamics, as described in Jaffe/Smith, and Karplus/Strong, "The Music Machine", MIT Press, 1989.  Pluck creates a sound suggesting a struck or plucked string.  It uses a delay line to represent the string.  The lower the pitch, the more delay memory it needs.  The implication is that a passage with many low notes may have problems running out of DSP memory.  Pluck does dynamic allocation of its delay memory.  This may result in some loss of memory over time due to DSP memory fragmentation.  

Parameters as defined in Standard Parameters.  Also:

lowestFreq - This parameter is used to warn the synthpatch what the lowest freq that may appear in the phrase will be so that it can allocate an appropriate amount of delay memory.  It is only used in the first note of a phrase.
sustain - In range 0.0:1.0.  1 means "sustain forever".  0 is the default and gives a moderate sustain.
pickNoise - In seconds (duration of initial pick noise).  Default is a period of time equal to one period at the fundamental frequency.
decay - Time constant of additional decay beyond the natural decay of the string.  A value of 0.0 indicates no additional decay.  This value is given in units of t60.  (t60 is the time for a note to decay to -60dB of its original amplitude.) Default is 0.0.
bright -  Brightness of the pluck.  In range 0.0:1.0.  1.0 is very bright.  Default is 0.5.
velocity -  This is a Standard Parameter (see below).  However, note that Pluck uses this parameter to scales brightness as well as amplitude.  In range 0:127.  Default is 64.
amp -  This is a Standard Parameter (see below).  Note that this parameter applies only to the initial pluck.  Attempts to change the amplitude after the pluck have no effect.  Also, note that the resultant amplitude may be lower than a comparable setting in other SynthPatches, due to the indeterminate nature of the noise used for the attack.  Default is 0.1.
ampRel - Time in seconds at end of note (after noteOff) for string to damp to -60dB of 
original amplitude.  Default is 0.15.

Wave1i

Wave1i is a single-interpolating-oscillator wavetable SynthPatch with an amplitude and frequency envelope.  
  
Parameters as defined in Standard Parameters and  Standard Oscillator Parameters.

Wave1vi

Wave1vi  is like Wave1i, but it also includes vibrato.
   
Parameters as defined in Standard Parameters, Standard Oscillator Parameters, and Vibrato Parameters.

DBWave1vi

DBWave1vi is similar to Wave1vi, but has access to the Timbre Data Base.

Parameters as defined in Parameters as defined in Standard Parameters, Standard Oscillator Parameters, and Vibrato Parameters.  Also:

waveform0 - Waveform when balance is 0.  Default is a sine wave.
waveform1 - Waveform when balance is 1.  Default is a sine wave.  waveform1 is a synonym for waveform.
controlChange - MIDI balance (controller 8) interpolates between two timbres, waveform0 and waveform1.  When the companion parameter, controlVal is 0 the result is waveform0.  When controlVal is 127 (the default), the result is waveform1.  Values between produce a linearly-interpolated timbre.  Setting the balanceSensitivity parameter to less than 1.0 reduces the maximum proportion of waveform1.  Since any change in balance in this SynthPatch results in a new wavetable being sent to the DSP, there are limitations as to how quickly and smoothly it can be done.  Frequent changes may disturb timing.  Setting wavelen to 128 or 64 helps.  If you are doing a great deal of wave table interpolation, you should use DBWave2vi.
controlVal - See controlChange.
balanceSensitivity - In the range 0.0:1.0.  Default is 1.0.

DBWave2vi 

DBWave2vi is a dual-interpolating-oscillator wavetable SynthPatch with dynamic interpolation between the two oscillators, and amplitude and frequency envelopes.  It has access to the NeXT Timbre Data Base (see chart #8).

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, Vibrato Parameters, and MIDI Panning Parameters.  Also:

waveformEnv  - wavetable cross-fading envelope
waveform0 - The waveform when waveformEnv is 0.  Defaults to sine 
waveform1 - The waveform when waveformEnv is 1.  Defaults to sine 
waveformAtt - Waveform envelope attack time.
waveformRel - Waveform envelope balance release time.  

Fm1i

Fm1i is a single-modulator frequency modulation SynthPatch with an interpolating-oscillator for a carrier, and envelopes on amplitude, frequency, and FM index.
  
Parameters as defined in Standard Parameters, Standard Oscillator Parameters, and FM Parameters.

Fm1vi

Fm1vi is like Fm1i, but includes vibrato.

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, FM Parameters, and Vibrato Parameters.

DBFm1vi

DBFm1vi is like Fm1vi, but it supports the Timbre Data Base (see chart #8) on both the carrier and modulator waveforms.

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, FM Parameters, and Vibrato Parameters.  Also:

velocity - In addition to the usual amplitude scaling, velocity scales the strength of  the FM modulation.  The default velocity (64) has no effect on FM index.  
waveform0 - Carrier waveform when balance is 0.
waveform1 - Carrier waveform when balance is 1.  waveform1 is a synonym for waveform.
controlChange - MIDI balance (controller 8) interpolates between two timbres, waveform0 and waveform1.  When the companion parameter, controlVal is 0 the result is waveform0.  When controlVal is 127 (the default), the result is waveform1.  Values between produce a linearly-interpolated timbre.  Setting the balanceSensitivity parameter to less than 1.0 reduces the maximum proportion of waveform1.  Since any change in balance in this SynthPatch results in a new wavetable being sent to the DSP, there are limitations as to how quickly and smoothly it can be done.  Frequent changes may disturb timing.  Setting wavelen to 128 or 64 helps.  If you are doing a great deal of wave table interpolation, you should use DBWave2vi.
controlVal - See controlChange.
balanceSensitivity - In the range 0.0:1.0.  Default is 1.0.

Fm2cvi

Fm2cvi is a cascade-modulator frequency modulation SynthPatch, with an interpolating-oscillator as a carrier.  It provides for envelopes on amplitude, frequency, and a separate envelope on each modulator's FM index.  It also supports vibrato.  

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, Vibrato Parameters, FM Parameters, and Double-FM Parameters.  Also:

velocity - In addition to the usual amplitude scaling, velocity scales the strength of the FM modulation.  The default velocity (64) has no effect on FM index.  

afterTouch - As defined in FM Parameters.  However, note that afterTouch applies here only to the cascade modulator's index.

Fm2cnvi

Similar to Fm2cvi, but also includes a noise source modulating the frequency of the two wavetable modulators.  The noise has its own amplitude envelope.

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, Vibrato Parameters, FM Parameters,  Double-FM Parameters, Noise Modulator Parameters, and MIDI Panning Parameters.  Also:

velocity - In addition to the usual amplitude scaling, velocity scales the strength of the FM modulation.  The default velocity (64) has no effect on FM index.  

afterTouch - As defined in FM Parameters.  However, note that afterTouch applies here only to the cascade modulator's index.

Fm2pvi 

Fm2pvi is a parallel-modulator frequency modulation SynthPatch, with an interpolating-oscillator as a carrier.  It provides for envelopes on amplitude, frequency, and a separate envelope on each modulator's FM index.  It also supports vibrato.  

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, Vibrato Parameters, FM Parameters,  Double-FM Parameters, and MIDI Panning Parameters.  Also:

controlChange - MIDI balance (controller 8) changes the relative effect of the two modulators.  If the companion parameter, controlVal, has a value of 0, only the first modulator has an effect.  If controlVal is 1, only the second modulator has an effect.  The default value is 64 which corresponds to both modulators at full level.  The depth of the effect of MIDI balance is controlled with the parameter balanceSensitivity.  
controlVal - See controlChange.
balanceSensitivity - In the range 0.0:1.0.  The default is 1.0.  If balanceSensitivity is 0.0, MIDI balance has no effect.

Fm2pnvi

Similar to Fm2pvi, but also includes a noise source modulating the frequency of the two wavetable modulators.  The noise has its own amplitude envelope.

Parameters as defined in Standard Parameters, Standard Oscillator Parameters, Vibrato Parameters, FM Parameters,  Double-FM Parameters, Noise Modulation Parameters, and MIDI Panning Parameters.  Also:

controlChange, controlVal, and balanceSensitivity as defined for Fm2pvi above.

	Standard Parameters

These parameters are implemented by all the SynthPatches:

freq - Frequency in Hz.  freq1 is a synonym for freq.  Default is A440.
keyNum - The MIDI key number, an alternative to freq.  If both freq and keyNum are present, freq, takes precedence.  In the range 0:127.
pitchBend - Modifies frequency (or keyNum) as a 14 bit integer.  A value of MIDI_ZEROBEND (defined as 0x2000 in <midi/midi_types.h>) gives no  bend.  0 is maximum negative bend.  0x3fff is maximum positive bend.  See TuningSystem class for details.  May give unexpected results when combined with frequency envelopes.  Default is MIDI_ZEROBEND.
pitchBendSensitivity - A value of 0.0 means pitchBend has no effect.  A value of 1.0 means pitch bend corresponds to plus or minus a semitone.  Larger values give larger pitch deviation.  Default is 3.0, except in Pluck, which uses a default of 1.0.  (This inconsistancy will be fixed in a future release.)
bearing - Left/right panning of signal.  In range -45.0:45.0.  -45.0 is far left.  Default is 0.0.
amp - Amplitude.  In the range 0.0:1.0.  amp1 is a synonym for amp.  Default is 0.1.
velocity - A MIDI parameter.  In range 0:127.  The default is 64.  Velocity scales amplitude by an amount deteremined by velocitySensitivity.  Some SynthPatches also scale brightness or FM index based on velocity.  
velocitySensitivity - In range 0.0:1.0.  Default is 0.5.  When velocitySensitivity is 0, velocity has no effect.
controlChange - This parameter is the MIDI controller number to be affected.  It is used in conjunction with the parameter controlVal, which provides the value the controller is set to.  The SynthPatches implement various MIDI controllers, as described in each patch's description.  
controlVal - See controlChange.

Standard Oscillator-Based SynthPatch Parameters

These parameters are implemented by all the SynthPatches except Pluck.  

ampEnv - Amplitude envelope.  Default is an envelope that is always a constant 1.0.
amp0 - Amplitude when the envelope is at 0.0.  amp is amplitude when the envelope is at 1.0.  amp1 is a synonym for amp.  Default is 0.0.
ampAtt - Time of attack portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
ampRel - Time of release portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
freqEnv - Frequency envelope.  Default is an envelope that is always a constant 1.0.
freq0 -Fundamental frequency when the envelope is at 0.  freq is frequency when the envelope is at 1.  freq1 is a synonym for freq.  Default is 0.0.
freqAtt -Time of attack portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
freqRel -Time of release portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
portamento - Portamento time.  In a phrase, the transition time to a note from the immediately preceding note.  Overrides the time values of the first segment of the envelopes.  Note that portamento is applied after the attack-time parameters.
waveform	- WaveTable used for the oscillator (only the carrier, in the case of FM).  Defaults to sine.  Note that the WaveTable you supply is normalized so that its peak amplitude is 1.0.
waveLen - Length of wavetable.  Defaults to an optimal value.  May only be set at the start of a phrase or with a noteUpdate that has no noteTag.
phase - Initial phase of wavetable in degrees.  Rarely needed.  Default is 0.0.
controlChange -  MIDI volume (controller 7) adjusts output volume as an attenuation  on the final output signal.  In the range 0:127.  Its value is given by the companion parameter controlVal.  The default for MIDI volume is 127.
controlVal - See controlChange.

  Vibrato Parameters
	
Both sinusoidal and random vibrato are supported.  (Note: we eventually plan to provide periodic vibrato using arbitrary waveTables.)

svibFreq - Sinusoidal vibrato rate in hz.  Default is 0.0.
svibAmp- Sinusoidal vibrato amplitude as a percentage of the fundamental frequency.  In the range 0.0:1.0.  Default is 0.0.
svibFreq0 - See below.  Default is 0.0.
svibAmp0 - See below.  Default is 0.0.
rvibAmp - Random vibrato amplitude as roughly a percentage of the fundamental frequency.  In the range 0.0:1.0.  Default is 0.0.
controlChange - MIDI modulation wheel (controller 1) interpolates simultaneously between svibAmp0 and svibAmp, and svibFreq0 and svibFreq.  The default value (127) results in svibFreq and svibAmp.  The value is given by the companion parameter controlVal.  In the range 0:127.
controlVal - See controlChange.

FM Parameters

These parameters are implemented by all FM SynthPatches:

cRatio - Carrier frequency scaler.  The resulting carrier frequency is cRatio multiplied by the freq parameter (or the frequency derived from the keyNum parameter).  c1Ratio is a synonym.  Default is 1.0.
m1Ratio - Modulator frequency scaler.  The resulting modulator frequency is m1Ratio multiplied by the freq parameter.  Default is 1.0.
m1Ind - Modulation index.  If an envelope, is specified, this is the index when the envelope is at 1.  m1Ind1 is synonym for m1Ind.  Default is 2.0.
m1IndEnv - Modulation index envelope.  Default is a constant value of 1.0.
m1Ind0 - Modulation index when envelope is at 0.0.  m1Ind is index when envelope is at 1.0.  Default is 0.0.
m1IndAtt -Time of attack portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
m1IndRel - Time of release portion of envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
m1Waveform - Modulator wave table.  Default is sine wave.
m1Phase - Initial phase in degrees of modulator wavetable.  Rarely needed.  Default is 0.0.
bright - Brightness, a multiplier on fm index.  Defaults to 1.0.
afterTouch - MIDI afterTouch (also called channel pressure) attenuates the  amount of frequency modulation.  In the range 0:127.  A value of 127 (the default) produces no attenuation.
afterTouchSensitivity - Controls the amount of attenuation caused by afterTouch.  If afterTouchSensitivity is 1.0 and afterTouch is 0, modulation is 0.  If afterTouchSensitivity is .5 and afterTouch is 0, modulation is half the normal amount.  Default sensitivity is 0.5.  

Double-FM Parameters

These  parameters are implemented by SynthPatches Fm2pvi, Fm2pnvi, Fm2cvi, and Fm2cnvi.  All of these SynthPatches have two modulators, although the configuration of the modulators varies.

m2Ratio - Scaler on second modulator frequency.  Defaults to 2 for Fm2cvi and Fm2cnvi.  Defaults to 1 for Fm2pvi and Fm2pnvi.  The resulting modulator frequency is the value of m2Ratio multiplied by the freq parameter.
m2Ind - Index of 2nd modulator.  If there's an envelope on the index of the 2nd modulator, this is the index when the envelope is at 1.  m2Ind1 is synonym for m2Ind.  
m2IndEnv - Frequency modulation index envelope for the second modulator.  
m2Ind0 - Modulation index for the second modulator when envelope is at 0.  m2Ind is the index when envelope is at 1.
m2IndAtt - Time of attack portion of second modulator index envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
m2IndRel - Time of release portion of second modulator index envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
m2Waveform - Second modulator WaveTable.  Defaults to sine.
m2Phase - Initial phase in degrees of modulator wavetable.  Rarely needed.  Defaults to 0.0.

Noise Modulation Parameters

These parameters are implemented by the SynthPatches Fm2pnvi and Fm2cnvi.

noiseAmp - Amplitude of noise modulator.  If a noise amplitude envelope is provided, this is the amplitude of the noise when the envelope is 1.  noiseAmp1 is a synonym for the parameter noiseAmp.  Default is 0.007.
noiseAmpEnv - Noise amplitude envelope.  Default is a constant value of 1.0.
noiseAmp0 - Noise amplitude when noise envelope is at 0.0.  noiseAmp is the value when the noise envelope is at 1.0.  Default is 0.0.
noiseAmpAtt - Time of attack portion of noise envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
noiseAmpRel - Time of release portion of noise envelope in seconds.  If this parameter is not present, the times in the envelope are used verbatim.
controlChange -  MIDI breath controller (controller 2) attenuates the output of  the noise modulator.  The value is obtained from companion parameter, controlVal.  The range is 0:127 and the default is 127, indicating no attenuation.  The effect of this parameter depends on the parameter breathSensitivity.
controlVal - See controlChange
breathSensitivity - Controls how much affect the breath controller has.  Default is 0.5.
 
MIDI Panning Parameters

The MIDI panning parameters are implemented by the more complex SynthPatches: Fm2cvi, Fm2pvi, Fm2cnvi, Fm2pnvi, DBFm1vi, DBWave1vi and DBWave2vi.

controlChange - MIDI pan (controller 10) has the same effect as bearing.  If the panSensitivity is 1.0, a MIDI pan value of  0 is full left and 127 is full right.  If the value of  panSensitivity is less than 1.0, the pan range is narrowed toward the center.  The value is set by the companion parameter, controlVal.  
controlVal - See controlChange.
panSensitivity - In the range 0.0:1.0.  Default is 1.0.

The NeXT Timbre Data Base

The NeXT Timbre Data Base is a set of spectra derived from recordings of musical instruments and voices in various ranges.  The Data Base was created by Michael McNabb.  

The SynthPatches that support the Data Base are DBWave1vi, DBWave2vi, and DBFm1vi.  ("DB" stands for "Data Base".)  Note that the use of the Data Base is strictly optional in these instruments.  For example, if the Data Base is not used, DBWave1vi acts just like Wave1vi.  That is, the waveform parameter may be passed either an ordinary WaveTable (as in Wave1vi) or a timbre string (as defined below).

To use the Data Base, you specify a timbre as a string (such as "SA", including the quotation marks) to the SynthPatch's  waveform parameter.  SynthPatches with multiple waveform parameters accept multiple timbre strings.  Each timbre string represents a group of WaveTables, one for approximately every whole step in the normal range of the voice or instrument.  The SynthPatch selects the WaveTable appropriate to the frequency.  By default, the WaveTable selection is based on the parameter freq1 (synonym for freq, or MIDI keynum).   By prefixing a timbre string with the zero character, e.g., "0SA", the timbre will be selected based on the freq0 parameter instead.

The various timbre groups have different numbers of WaveTables, as given in the chart below.  Internally, the WaveTables for a particular timbre group are numbered sequentially, with 1 corresponding to the WaveTable for the bottom of the range of that timbre.  Specific WaveTables in a timbre group can be requested by adding a numeric suffix.  In this manner, the automatic selection based on frequencycan be overridden.  For example, the timbre group "BA" (bass voice singing "AH") consists of 15 timbres.  The timbre string "BA12" requests the 12th WaveTable, independent of the frequency.  

Some of the timbres are actually recordings of the attack of an instrument.  These are best used with the SynthPatch DBWave2vi, which can interpolate between timbres.  Note also that for realism, appropriate envelopes, attack/decay values and vibrato must be used.

Here are the string keywords for the timbres currently in the timbre database.  Note that case is significant.  The number in parentheses is the number of WaveTables for that timbre.  The normal range of the timbre corresponds to that of the corresponding instrument.  For example, "BA" is normally used from about c2 to about d4.

     "BA"	Bass voice "AH" (15)
     "BE"	Bass voice "EH" (14)
     "BO"	Bass voice "OH" (15)
     "BU"	Bass voice "OO" (15)
     "TA"	Tenor voice "AH" (12)
     "TE"	Tenor voice "EH"  (12)
     "TI"	Tenor voice "EE" (12)
     "TO"	Tenor voice "OH" (12)
     "TU"	Tenor voice "OO" (12)
     "SA"	Soprano voice "AH" (13)
     "SE"	Soprano voice "EH" (13)
     "SI"	Soprano voice "EE" (13) 
     "SO"	Soprano voice "OH" (13)
     "SU"	Soprano voice "OO" (13)
     "VCA"	Cello attack (53)
     "VCS"	Cello steady-state (53)
     "VNA"	Violin attack (56)
     "VNS"	Violin steady-state (56) 
     "TR"	Trumpet (31)
     "BN"	Bassoon (41)
     "AS"	Alto Sax (31)
     "SS"	Soprano Sax (31) 
     "BC"	Bass Clarinet (47)
     "CL"	Clarinet (45)
     "EH"	English Horn (32)
     "OB"	Oboe (33)
     "PN"	Piano (62)
     "TW"	Triangle wave (31)
     "SW"	Sawtooth wave (35)
     "IW"	Impulse wave (29)