TheMatrix
    Modular Synthesizer for OasysPCI

    ______________________________
     
    I. Common Abbreviations
    The following abbreviations are often used on the control panel to save space.

    AM: Amplitude Modulation
    Amt: Amount
    Ctrl: Control
    Env: Envelope
    Ext: External
    FM: Frequency Modulation
    Freq: Frequency
    Kbd: Keyboard
    LFO: Low Frequency Oscillator
    LPF or LPFilt: LowPass Filter
    MMF or MMFilt: MultiMode Filter
    Mod: Modulation
    Osc: Oscillator
    OscMix: Oscillator Mixer
    PWM: Pulse Width Modulation
    Sens: Sensitivity
    Smpl: Sample
    Src: Source
    Vel: Velocity

    They are somtimes combined as well, ie. ExtModAmt or Vel Sens.
     
    II. About Matrix Routing

    This is the heart of TheMatrix. This section allows you to route various sections' outputs to other sections' inputs, much like you would on a hardware modular synthesizer.

    Instead of using patch cables and I/O jacks TheMatrix uses the Matrix Routing module, where every modulation input has a pull down menu for selecting what signal output will be received there. This is somewhat like an Oasys PCI version of the EMS patch pin matrix.

    Using this method has some advantages in that you can look at the central routing module and immediately get a clear idea of where signals are being routed, as well as dispensing with the need for a "multiples" module since you can inherently patch an output to multiple inputs.

    Modulation inputs typically have scalers (or modulation amounts) in the section being modulated.
     
    III. Sections Overview
      1. Signal Sources
      The Signal Sources module is the general-purpose raw tone generating module. There are three sound sources and a master control:
        A. Master
          Tune: Master tuning for the oscillators in cents. +/-100.
          Glide: Time it takes for the oscillators to glide from one pitch to another when their Glide switch is on. 0-100.
        B. Oscillator 1
          Glide: AKA portamento. This is a switch that will toggle on/off gliding from one note to another at a speed set in the master section.
          Frequency: Frequency of the Oscillator in semitones. +/-48.
          Mod Amt: Amount of frequency modulation by the source set in the matrix router. 0-100.
          Saw-Pulse-Sine: A three way fader for waveshape. All the way counter-clockwise is Saw, 12:00 is Pulse, and all the way clockwise is Sine.
          Pulse Width: Initial duty cycle of the pulse waveform. 0-100.
          PWM Amt: Amount of Pulse Width Modulation by the source set in the Matrix Router. 0-100.
          Sync->2: This switch turns on Oscillator sync, which will cause Oscillator 1 to reset it's phase whenever Oscillator 2 starts it's duty cycle. The result is that Oscillator 2 will control Oscillator 1's pitch, and changing the frequency of Oscillator 1 will change it's timbre.
        C. Oscillator 2
          Glide: AKA portamento. This is a switch that will toggle on/off gliding from one note to another at a speed set in the master section.
          Frequency: Frequency of the Oscillator in semitones. +/-48.
          Mod Amt: Amount of frequency modulation by the source set in the matrix router. 0-100.
          Key Track: Adjusts Oscillator 2's pitch tracking across the keyboard. +/-100.
          Fine: Fine tuning of Oscillator 2 in cents +/-100
          Saw-Pulse-Sine: A three way fader for waveshape. All the way counter-clockwise is Saw, 12:00 is Pulse, and all the way clockwise is Sine.
          Pulse Width: Initial duty cycle of the pulse waveform. 0-100.
          PWM Amt: Amount of Pulse Width Modulation by the source set in the Matrix Router. 0-100.
          Low Freq: Switch that shifts Oscillator 2 into low frequency mode, making it useful as another LFO mod source.
        D. Noise
          Color: Continuously variable noise tone color. lower values will make the noise darker, as well as more "speckly" and uneven. 0-100.

      2. Mix
      The Mix module is where signals can be added together for use in other places, there are two mixers:
        A. Osc Mix
        The Osc Mix is a three channel mixer hard-wired to Oscillator 1, Oscillator 2, and the Noise source.
          Osc1: level that Oscillator 1 will be mixed with the other sources. Negative values will invert the signal. +/-100.
          Osc2: level that Oscillator 2 will be mixed with the other sources. Negative values will invert the signal. +/-100.
          Noise: level that the Noise source will be mixed with the other sources. Negative values will invert the signal. +/-100
          AM Amt: Amount of Amplitude Modulation by the source selected in the Matrix Router, applied to the overall OscMix output. 0-100.
        B. Mixer
        The Mixer is a general-purpose two channel mixer with adjustable headroom. The inputs to the two channels are selected in the Matrix Router.
          Input 1: level that Input 1 will be mixed with the other source. Negative values will invert the signal. +/-100.
          Headroom: this setting will reduce the overall level of the Mixer output anywhere from 0dB to 24dB. This is allows it to safely mix a variety of signals without risking digital clipping.
          Input 2: level that Input 2 will be mixed with the other source. Negative values will invert the signal. +/-100.

      3. Envelopes
      The Envelopes module generates time-based control signals from note-ons:
        A. ADSR 1
        Attack/Decay/Sustain/Envelope
          Attack: time from note-on that it takes to reach maximum value. 0-100.
          Decay: time from end of attack stage to reach sustain value. 0-100.
          Sustain: value held at the end of the decay stage until the end of the note gate. 0-100.
          Release: time to return to a value of 0 from the end of the note gate. 0-100.
        B. ADSR 2
        Attack/Decay/Sustain/Envelope
          Attack: time from note-on that it takes to reach maximum value. 0-100.
          Decay: time from end of attack stage to reach sustain value. 0-100.
          Sustain: value held at the end of the decay stage until the end of the note gate. 0-100.
          Release: time to return to a value of 0 from the end of the note gate. 0-100.
        C. ADS Env
        Attack/Decay/Sustain Envelope.
          Attack: time from note-on that it takes to reach maximum value. 0-100.
          Decay: time from end of attack stage to reach sustain value. 0-100.
          Sustain: value held at the end of the decay stage until the end of the note gate. 0-100.
          Decay Switch: when this switch is turned on is turned on, the ADS envelope will have a Release value equal to it's Decay time.

      4. Filters
      The Filters module subtracts frequencies from the filter inputs to create new timbres:
        A. Lowpass
        24dB/octave lowpass filter with a moog-like sound.
          Cutoff: Sets the frequency at which the high-frequency rolloff begins. 0-100.
          Emphasis (aka resonance): Amount of peaking at the cutoff frequency. 0-100.
          Freq Mod 1: Amount that the cutoff frequency is modulated by the Mod 1 source selected in the Matrix Router. 0-100.
          Freq Mod 2: Amount that the cutoff frequency is modulated by the Mod 2 source selected in the Matrix Router. 0-100.
          Kbd.Ctrl.1: This switch turns on keyboard tracking to a depth of 1/3.
          Kbd.Ctrl.2: This switch turns on keyboard tracking to a depth of 2/3.
          Overdrive: This menu lets you select various settings for the sound of overloading a filter input. From purest to most distorted, the settings are Clean, Dirty, and Filthy.
        B. MultiMode
        Multi-mode multi-slope filter with extensive modulation.
          Cutoff: Sets the frequency at which the rolloff begins for the high or low pass filters, sets the center frequency for bandpass. 0-100.
          Resonance: Amount of peaking at the cutoff frequency. 0-100.
          Mod 1 Amt: Amount that the cutoff frequency is modulated by the Mod 1 source selected in the Matrix Router. Negative Values invert the signal. +/-100.
          Mod 2 Amt: Amount that the cutoff frequency is modulated by the Mod 2 source selected in the Matrix Router. Negative Values invert the signal. +/-100.
          Key Track: Amount that the cutoff frequency tracks across the keyboard. 0-100.
          LP/BP/HP: Three way continuous fader between filter modes. All the way counterclockwise is lowpass which fades to bandpass at 12:00 (vertical) which fades to highpass all the way clockwise. This allows you to get filter responses that aren't strictly in the realm of common filter modes, with varying amounts of the mixed types.
          Mod Amt: Amount of modulation between filter modes by the modulation source set in the Matrix Router. 0-100.
          2>2/4/2: 3 way continuous fader selects the attenuation curve around the cutoff frequency. 2>2 (all the way counterclockwise) is two 12dB/octave filters in serial configuration, 4 is a single 24dB/octave filter, and 2 is a single 12dB/octave filter. The fader allows you to mix seamlessly between these responses for unusual rolloff curves and resonance characteristics.
          Mod Amt: Amount of modulation between filter response curves by the modulation source set in the Matrix Router. 0-100.

      5. LFOs
      Low Frequency Oscillators to generate modulation signals:
        A. LFO1
        Selectable tempo sync or manual frequency control, external frequency modulation, selectable sample source for the sample and hold.
          Manual Tempo: Sets the tempo of the LFO when the LFO Control selector is set to "Manual Tempo". 40-240BPM.
          Subdivision: Menu that sets the note value of a single cycle of the LFO waveform when the LFO Control is set to either "Manual Tempo" or "MIDI Tempo". 1/32, 1/32 dotted, 1/16, 1/16 dotted, 1/16 triplet, 1/8, 1/8 dotted, 1/8 triplet, 1/4, 1/4 dotted, 1/4 triplet, 1/2, 1/2 dotted, 1/2 triplet, 1 whole note, 2 whole notes.
          LFO Control: Selector that sets the source for the LFO's frequency. Frequency Knob, Manual Tempo, MIDI Tempo.
          Waveform: Menu for selecting the waveshape of the LFO. Also selectable here is the Sample & Hold (SmplAndHold). At the beginning of each LFO clock cycle, the Sample & Hold will sample the value at it's sample input (selectable in the Matrix Router) and hold it at the LFO output until the next LFO cycle begins. With Noise as the sample source, you get classic S&H burbles and randomness. With other things like Oscillators or LFOs as sources, you get more pattern-like results. Triangle, Sine, Saw up, Saw Down, Square, SmplAndHold.
          Shape: Varies the curvature of the LFO output from logarithmic to linear to exponential. Negative values narrow the width of the waveform, positive values widen it, at 0 the waveform will remain unchanged. +/-100.
          Smoothing: Rounds the sharp edges of the LFO output's waveform, similar to the effect of a lowpass filter. The higher the value the more smoothing is applied. 0-100.
          Frequency: Knob sets the frequency of the LFO when the LFO Control selector is set to Frequency Knob. 0-20Hz.
          Frequency Mod: menu that sets a modulation source like Mod Wheel, Aftertouch, or Key Track for the LFO Frequency when the LFO Control selector is set to Frequency Knob.
          Mod Amount: Amount of frequency modulation by the source set in the Frequency Mod menu when the LFO Control selector is set to Frequency Knob. +/-20Hz.
          ExtModAmt: Amount of LFO frequency modulation by the source set in the Matrix Router. This is effective regardless of the setting in the LFO Control selector. +/-100.
          Initial Phase: Sets the point in the waveform cycle that the LFO will begin at and return to when the phase is reset. +/-180.
          Phase Reset: Menu that sets the mod source which will reset the phase of the LFO. Typical settings are Note Gate, MIDI Start/Stop, or any of the continuous controllers.
        B. LFO2
        Selectable tempo sync or manual frequency control, external frequency modulation, selectable sample source for the sample and hold.
          Waveform: Menu for selecting the waveshape of the LFO. Also selectable here is the Sample & Hold (SmplAndHold). At the beginning of each LFO clock cycle, the Sample & Hold will sample the value at it's sample input (selectable in the Matrix Router) and hold it at the LFO output until the next LFO cycle begins. With Noise as the sample source, you get classic S&H burbles and randomness. With other things like Oscillators or LFOs as sources, you get more pattern-like results. Triangle, Sine, Saw up, Saw Down, Square, SmplAndHold.
          Shape: Varies the curvature of the LFO output from logarithmic to linear to exponential. Negative values narrow the width of the waveform, positive values widen it, at 0 the waveform will remain unchanged. +/-100.
          Smoothing: Rounds the sharp edges of the LFO output's waveform, similar to the effect of a lowpass filter. The higher the value the more smoothing is applied. 0-100.
          LFO Control: Selector that sets the source for the LFO's frequency. Frequency Knob, Manual Tempo, MIDI Tempo.
          Frequency: Knob sets the frequency of the LFO when the LFO Control selector is set to Frequency Knob. 0-20Hz.
          Frequency Mod: menu that sets a modulation source like Mod Wheel, Aftertouch, or Key Track for the LFO Frequency when the LFO Control selector is set to Frequency Knob.
          Mod Amount: Amount of frequency modulation by the source set in the Frequency Mod menu when the LFO Control selector is set to Frequency Knob. +/-20Hz.
          Manual Tempo: Sets the tempo of the LFO when the LFO Control selector is set to "Manual Tempo". 40-240BPM.
          Subdivision: Menu that sets the note value of a single cycle of the LFO waveform when the LFO Control is set to either "Manual Tempo" or "MIDI Tempo". 1/32, 1/32 dotted, 1/16, 1/16 dotted, 1/16 triplet, 1/8, 1/8 dotted, 1/8 triplet, 1/4, 1/4 dotted, 1/4 triplet, 1/2, 1/2 dotted, 1/2 triplet, 1 whole note, 2 whole notes.
          Phase Reset: Menu that sets the mod source which will reset the phase of the LFO. Typical settings are Note Gate, MIDI Start/Stop, or any of the continuous controllers.
          Initial Phase: Sets the point in the waveform cycle that the LFO will begin at and return to when the phase is reset. +/-180.
          ExtModAmt: Amount of LFO frequency modulation by the source set in the Matrix Router. This is effective regardless of the setting in the LFO Control selector. +/-100.

      6. Amplifier
        A. Amplifier
        where you control the final amplitude levels before output.
          Volume: Overall output level. -Inf to +12dB.
          Vel Sens: Velocity sensitivity of the amp. A velocity value of 127 will cause the signal to reach the amplitude set on the Volume knob, the difference between this and a 0 velocity note is determined by the value of this knob.
          AM Amt: Amount of Amplitude Modulation by the source set in the Matrix Router.

      7. Matrix Routing
      This is where you set up your patch's signal path by routing the outputs of modules to the inputs on others, for both control signals and audio signals. The routing menus are arranged by module input, ie, all of the lowpass filter input mod routings are in one row. The menu names correspond to the modulation or audio input, the selections in the menu are modulation or audio outputs which can be routed to that input.
        A. Oscillator 1
          FM: Off, Noise, Osc2, Mixer, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
          PWM: Off, Noise, Osc2, Mixer, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
        B. Oscillator 2
          FM: Off, Noise, Osc1, Mixer, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
          PWM: Off, Noise, Osc1, Mixer, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
        C. Mixer
          OscMix AM In: Off, Osc1, Osc2, Noise, OscMix, Mixer, LFO1, LFO2.
          Mix In 1: Off, Noise, Osc1, Osc2, MMFilt, LPFilt, OscMix, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
          Mix In 2: Off, Noise, Osc1, Osc2, MMFilt, LPFilt, OscMix, ADSR1, ADSR2, ADS Env, LFO1, LFO2.
        D. LPF
          Mod 1: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer, OscMix, Osc1, Osc2, Noise.
          Mod 2: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer, OscMix, Osc1, Osc2, Noise.
          Audio In: Off, OscMix, Osc1, Osc2, Noise, MMFilt.
        E. MMF
          Mod1: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer, OscMix, Osc1, Osc2, Noise.
          Mod2: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer, OscMix, Osc1, Osc2, Noise.
          Audio In: Off, OscMix, Osc1, Osc2, Noise, LPFilt.
          TypeMod: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer.
          ModeMod: Off, ADSR1, ADSR2, ADS Env, LFO1, LFO2, Mixer.
        F: LFO1
          Mod: Off, ADSR1, ADSR2, ADS Env, LFO2, Mixer.
          Smpl Src (sample source): Off, Osc1, Osc2, MMFilt, LPFilt, OscMix, ADSR1, ADSR2, ADS Env, LFO2, Noise.
        G: LFO2
          Mod: Off, ADSR1, ADSR2, ADS Env, LFO1, Mixer.
          Smpl Src (sample source): Off, Osc1, Osc2, MMFilt, LPFilt, OscMix, ADSR1, ADSR2, ADS Env, LFO1, Noise.
        H: Amp
          AM In: Off, Osc1, Osc2, Noise, OscMix, Mixer, LFO1, LFO2.
          Env In: Off, ADSR1, ADSR2, ADS Env, Mixer.
          Audio In: Off, LPFilt, MMFilt, Mixer, OscMix.
    IV. Credits
        Thanks to Dan Phillips for doing some synthkit routing abstraction gruntwork and bouncing a lot of ideas around that ended up in the final version, Joe F. and Nev for contributing some killer multis for the release.