Oatmeal

Oatmeal is a simple two-oscillator subtractive synthesizer. This, as you may have gathered, is its documentation; call it a "manual" if you like. Behold:

There are several types of controls; here's how to operate them, so you don't have to spend decades puzzling out the incredibly complex manoeuvers necessary to move the knobs.

• Status bar.

  Look at it. It's at the bottom of the UI. It tells you things worth knowing, such as the (more or less) precise value of the parameter belonging to the control you're hovering over.

• Knobs.

  Because I do not hate you, the knobs are not controlled circularly; grab them with the left mouse button and drag vertically or horizontally; vertically moves them faster. To move them rather more slowly (which will be necessary for precise adjustments on many parameters), hold Ctrl, Shift, or both. Middle click to set them to exactly the central position, right click to set them to the default value.

• Switches.

  Left click to advance the state of a knob, or right click for a context menu to select from all possible values. Middle click or Ctrl + left click to set the knob to the first value in the menu, which is always "off" where applicable.

• Buttons.

  Left click them for things to happen.

• XY pad.

  Drag it around with the left mouse button; hold Ctrl and/or Shift to do so more slowly; middle click to reset it to the center. Hold the right mouse button while dragging to keep the radius constant, moving the value in a circle around the center.

• CC selector.

  Drag with the left mouse button. Do so further to the right to change the value more slowly. Rather more usefully, right click to make it switch to learn mode and move the controller you want it to use.

• Pattern length slider.

  Drag with the left button.

Block-for-block information

Now that the screenshot (of the default skin - Oatmeal comes with a larger skin that is laid out in more or less the same way, and there are some nice third-party skins sprinkled here and there on the web) is almost (or entirely) out of view past the top of your browser window, it's time for some explanations on how things work and what the knobs and things do. First, let's follow the signal path:

• Oscillator block (and noise)

  Upper half, left edge of the UI. This is where sound comes from: two oscillators and one noise source. The following parameters are shared by both oscillators:

  • Waveform. You can choose between sine, sawtooth, pulse (square), triangle, user, and "user PWM". User PWM is somewhat esoteric: two oscillators, one inverted and shifted according to the PWM parameters - the "pulse" setting is actually precisely the same thing applied to the built-in saw waveform. Press the "edit" button below the waveform selector to edit the user waveform for that oscillator; more on this below.
  • Amp. Amplitude of the oscillator.
  • Tpitch (aftertouch > pitch). The effect of note velocity and later pressure changes on the oscillator's pitch; see the "hodgepodge" block below.
  • Pulsewidth, PWM rate, PWM depth. These are ignored unless the waveform is "pulse" or "user PWM", in which case they set the base pulsewidth and the modulation rate and depth. Note the phase settings in the hodgepodge block.

  Other oscillator parameters:

  • Trans (transpose). Transposition of the second oscillator relative to the first (i.e. the voice's pitch).
  • Detune. Constant frequency shift of the second oscillator.
  • Touch (aftertouch > osc amp). The effect of note velocity and pressure changes on both oscillators' amplitude.
  • Oscillator mix. Sets how the oscillators interact: normal (no interaction, just mixing), hardsync (oscillator 2's phase is reset when osc 1's passes zero), and FM (oscillator 1 modulates osc 2; osc 1 is muted).

  The noise section can generate white noise or bandpassed noise. Parameters:

  • Amp. Noise amplitude.
  • Touch. The effect of note velocity and pressure changes on the noise level.
  • Resonance. If this is 0, unfiltered white noise is generated. Higher values increase the resonance of the bandpass filter, making the output purer.
  • Transpose. Transposition of the filter's center frequency relative to the note.

• Filter block

  At the top, just to the right of the oscillator/noise block. Parameters:

  • Filter type.
  • Double (filter doubling). If this is enabled, two copies of the filter are run in parallel. See the "split", "mix", and "speed ratio" parameters.
  • Cutoff. Cutoff or center frequency of the filter.
  • Track (keytracking). In octaves/octave: thus if it is 1, an increase in the voice's pitch of one octave will cause the cutoff to increase by the same amount. By default, this means that a cutoff of 440 Hz and a keytracking factor of 1 results in the cutoff frequency always coinciding with the voice's pitch; but see the "cut ref" parameter in the tuning block.
  • Reso (resonance). Resonance of the filter (if applicable).
  • Split. If doubling is on, the second filter's cutoff frequency will be this much higher than the first's.
  • Mix. If doubling is on, this changes the output amplitude ratio between the two filters.
  • Touch (aftertouch > cutoff). The effect of note velocity and pressure changes on both filters' cutoff frequencies.
  • Mod (envelope modulation). Strength and direction of the filter envelope's effect.
  • Velocity. Effect of note velocity on the envelope modulation depth, not on the filter cutoff itself.
  • Filter envelope. For details, see the envelope block below.
  • Speed ratio. If doubling is on, the second filter's envelope will move at this rate relative to the first's.

• Envelope block

  Just below the filter block; this is the main amplitude envelope of the voice. The filter envelope works the same way, this being:

  • Attack. The time it takes for the level to reach 1.
  • Hold. After reaching 1, the level stays there for this long.
  • Decay 1. The time it takes for the level to reach the breakpoint; however, if the breakpoint is set to 1 (0 dB), this is skipped.
  • Breakpoint. The point reached after the first decay phase (see just above to see what happens if you set this to 0 dB); immediately followed by
  • Decay 2. The time taken for the level to change from the breakpoint to the sustain level.
  • Sustain. Sustain level.
  • Release. Release time.

• Distortion block

  Below the amp envelope block. It should be noted that, depending on the settings, the distortion can actually take place before the filter; see the "mode" parameter below:

  • Type. Hard clip, soft clip (tanh), sine (which can produce fm-like timbres or, failing that, horrible noise), or asymmetric.
  • Mode. This sets where the distortion is applied:
    • Global; i.e. once, after summing all the voices.
    • Per voice, after the filter.
    • Per voice, before the filter.
    • Double; i.e. per voice before the filter and then again after summing the voices.
  • Oversample. Oversamples the distortion to reduce aliasing. I recommend leaving this turned off unless there is audible aliasing; note that not all unpleasant frequency content is aliasing.
  • Pregain.
  • Limit. The level at which the signal is clipped (or the amplitude of the sine).
  • Postgain. In double mode, this is not applied to the per-voice distortion.

• Chorus block

  To the right of the distortion block, the first effect in the chain. Parameters:

  • Mode. Sine, Ramp, and FM are essentially the same thing with different LFO shapes. Irregular is a bit different: the delay times of the voices vary randomly within the given range.
  • Mode (again). Mono, Stereo 1 or Stereo 2. Note that if the chorus is on and this is mono, any panning is lost.
  • Rate. On the normal settings, the LFOs' frequency. In irregular mode, it's a bit less obvious, but still related to the rate at which the delay times vary.
  • Delay. Minimum delay.
  • Range. Delay range. The maximum delay is the minimum delay plus this.
  • Feedback.
  • Mix. Dry/wet mix.
  • Voices. Number of voices to keep track of and add together.

• Delay block

  Above the chorus block; this is a delay or "echo" effect. Parameters:

  • Unit. The unit in which the delay times are given.
  • Quantize. If this is enabled, the delay times are rounded to the nearest integer.
  • Input pan.
  • Rotation. Feedback rotation: the output sample pair is interpreted as a two-dimensional vector and rotated around the origin by this angle before being fed back. Can result in interesting stereo effects; for example, setting this to ±0.5π and turning the input pan all the way in one direction results in what is often referred to as "ping-pong" delay.
  • Dry. Dry output gain.
  • Wet. Wet output gain.
  • Length (left and right). Length of the delay for each channel.
  • Feedback (left and right). Feedback for each channel.
  • Reverse (left and right). Reverse output: "output" means that the buffer is played in reverse, but fed back normally; "feedback" means that both playback and feedback are reversed.
  • Lowpass. Cutoff of the lowpass filter in the feedback loop.
  • Highpass. Cutoff of the highpass filter in the feedback loop.
  • On/off switch.

• Reverb block

  At the top, to the right of the delay block. A reverb, surprisingly enough. Parameters:

  • Room size.
  • Length. The time the reverb takes to decay.
  • Predelay. If this is positive, the wet signal is delayed; otherwise, the dry signal.
  • Early (reflections). Adjusts the strength of the reverb's early reflections, somewhat softening harsh transients on higher settings.
  • Dull(ness). Cutoff of the reverb's internal lowpass filters.
  • Bright(ness). Cutoff of the reverb's internal highpass filters.
  • 1, 2, 3, rotate. Parameters of the reverb model.
  • Dry and wet output gain.
  • On/off switch.

• EQ block

  Right edge, below the reverb and above the hodgepodge. It's a simple 5-band parametric equalizer. Parameters (per band):

  • Type switch. Off, peak/notch, or low/high shelving.
  • Frequency. The band's center frequency.
  • Amp. The gain of the peak/notch or the shelf.
  • Slope. Sharpness of the peak or steepness of the shelf's slope. High values combined with large gains can cause ringing and audible peaking at the shelf edges.

The other blocks don't represent parts of the signal path; rather, they control various other things, such as LFOs and arpeggiation.

• Pitch envelope block

  Hiding in the bottom right corner, this, when enabled, causes each voice's pitch to change over time.

  • Start. The voice's initial pitch, relative to the note frequency.
  • Attack. The time that passes between start and peak; the frequency changes linearly.
  • Peak. The voice's pitch after the attack phase.
  • Decay. The time that passes between peak and sustain; the frequency changes exponentially.
  • Sustain. The pitch after attack and decay, until the voice is released.
  • Release. The rate at which the voice's pitch changes (exponentially) during release.
  • Velocity. Effect of note velocity on the envelope modulation depth, not on the pitch itself.
  • On/off switch.

• Mod envelope blocks

  Two additional per-voice modulation envelopes can be found on the left. Parameters:

  • Attack, Hold, etcetera. The envelope.
  • Mod depth. The strength of the envelope's effect on the chosen target.
  • Mod target. The items to modulate. Most parameters will be modulated in one direction only; the effect on pitch and filter cutoffs is bipolar, with the sustain level as the rest point. If you target the speed of a global LFO, a global phantom mod envelope will be used.
  • Velocity. Effect of note velocity on the envelope modulation depth.

• Tuning block

  Top right. This block offers various ways of adjusting Oatmeal's tuning.

  • Tune. This sets the frequency of middle A, by default 440 Hz.
  • Octave. This ridiculous parameter lets you change the meaning of the word "octave" (and everything that goes with it, such as those parameters that report their value in semitones) as far as the rest of Oatmeal is concerned.
  • Cut ref(erence). This sets the reference frequency (in semitones relative to middle A) used by the filter's keytracking.
  • Pan ref(erence). This sets the reference frequency used for pitch-based panning and envelope scaling - see the hodgepodge block.
  • Notes. Manual adjustment in case you don't want equal temperament.

• LFO block

  Oatmeal has two LFOs, bottom center. The parameters of both are more or less the same:

  • Shape. Sine, saw, square, triangle, smooth random, stepping random, user. As with the oscillators, click the little button labelled "edit" below the selector to edit the user shape.
  • Mode. Each LFO can be used globally or independently per voice, the latter being particularly interesting when the LFO is set to random; when the LFO is global, it can also be made to reset each time a new note is pressed.
  • Unit. The unit in which the rate is given.
  • Rate. The LFO's period. For the random modes, this is the interval at which new values are picked.
  • Quant(ize). If this is on, the period is quantized to whole units.
  • Cut 1. The LFO's effect on the first filter's cutoff; this does not affect the second filter, if doubling is enabled.
  • Cut 2. The second filter's cutoff, if filter doubling is on.
  • Res(onance). Filter resonance.
  • Pitch.
  • Pan.
  • Rate2/1. The LFOs can modulate each other's speed. If a global LFO's rate is set to be modulated by a per-note LFO, a phantom global LFO is used instead.

• XY block

  Oatmeal has one of those XY pads that are all the rage with the kids these days. It's also the only part of it that's directly assignable to MIDI CCs.

  • Mod depth. The strength of the effect of moving along the axis in question on the chosen target:
  • Mod target. The various things the XY pad can modulate.
  • CC selectors. As pointed out above, either set them directly or right click and move the controller in question. However, you can't use the learn feature to set both axes to the same controller - this is in case you have an actual physical item to use for this that is reluctant to send data on only one axis.
  • Vr (XY random radius) and vs (XY random rate). Oatmeal can vary the XY values automatically within a certain range and at a certain speed; the little circle on the display visualises this. Note that if you turn up the range, it'll take a period or two of the set rate to become visible.

• Arpeggiator block

  Oatmeal has a rather odd arpeggiator: notes and pattern are independent of each other, so that the result can be hard to predict.

  • The pattern. The commands here have nothing to do with the notes set below: they operate only on the keys held by the user. In certain modes, the precise value of each step is disregarded and no distinction made except between on and off - see below.
    • Off. Note off, or if already off, do nothing.
    • Up. Next higher note; if there is no higher note, wrap to lowest.
    • Up, no wrap. Next higher note; if there is no higher, no change.
    • Down. Next lower note; if there is no lower note, wrap to highest.
    • Down, no wrap. Next lower note; if there is no lower, no change.
    • Continue. Don't change the note.
    • Continue direction. If the previous note was lower, play the next higher note (and wrap). If the previous note was higher, etc.
    • Continue direction, bounce. Same, but bounce instead of wrapping.
    • Return. Return to the previous note.
    • Return, up. Return to the previous note and go one note up (and wrap).
    • Return, down. Return to the previous note and go one note down (and wrap).
    • Top. Jump to the highest held note.
    • Bottom. Jump to the lowest held note.
    • Up or down. Randomly go one note up or down, wrap.
    • Up or down, no wrap. Randomly go one note up or down, but don't wrap.
    • Random. Randomly choose one of the notes held.
  • Pattern length. Move the slider with the triangular handle to change it.
  • Mode.
    • Pattern. Go through the held notes according to the pattern (see above); maintain a subsequence counter for each held note, going forward through the notes set below (plus the invisible unshifted note) as each note comes up.
    • Pattern (global subseq). Similar, but keep only one global subsequence counter.
    • Chord pattern. Interprets the notes as a chord rather than a subsequence, plays this chord over each held note as it passes them.
    • Chord. Disregards the specific values of the pattern switches and simply plays all held notes in all set transpositions on the non-off steps.
    • Transposed chords. Disregards the specific values of the pattern switches and plays the held chord transposed according to the shifts - chord pattern in reverse, if you will.
  • Unit. Unit in which the arp step is given.
  • Quantize. If this is set, the step is quantized to the nearest integer (or inverse of an integer, if below 1).
  • Step. The step rate of the arpeggiator.
  • Arp notes. Referred to above as "set notes", "transpositions", "shifts" - these are variously interpreted as a subsequence or a chord, depending on the arp mode. Note that you have to explicitly turn them on individually.

• "Hodgepodge" block

  This is where everything else went.

  • Output gain.
  • Velocity sensitivity.
  • Aftertouch mode - note that the internal aftertouch variables get set by note-on velocity as well. This is why the aftertouch mode is initially set to "polyphonic" despite the poor availability of keyboards with polyphonic aftertouch.
  • Max polyphony. The maximum number of voices allowed to play at a time.
  • Polyphony mode. Polyphonic, monophonic, monophonic with legato - the point of "legato" being that the envelopes aren't retriggered if the voice is playing and not releasing.
  • Glide. The time taken for the pitch to slide from one note to the next.
  • Glide mode. The glide time can be scaled to take longer for greater (or smaller) intervals.
  • Bend range. Range of the pitch bend wheel.
  • Transpose. Global transposition.
  • Random pan. Random panning of each voice.
  • Freq > pan. Panning by pitch - higher notes can be automatically panned further to the right (or left).
  • Freq > env speed. Envelope speed scaling by pitch.
  • Random freq. Random pitch variation.
  • Random amp. Random amplitude variation.
  • Osc/PWM/LFO phase. Initial phase on a new voice (or when retriggering).
  • Osc/PWM/LFO rand(om phase). Phase range on a new voice (or when retriggering).
  • Osc/PWM/LFO phase retrigger. Whether to retrigger the phase on an old voice about to play a new note. If this is switched on for the oscillators, clicks are likely.

• MIDI settings page

  

  Accessible through the "midi" button in the lower right corner, this page lets you assign MIDI control changes to various parameters, filter out MIDI channels and so forth.

  • Channel switches. These are the toggle switches on the left, with the numbers; Oatmeal will ignore MIDI events on channels not checked here.
  • Sustain. If this is checked, Oatmeal will notice and use sustain pedals (CC 64).
  • Velocity box. This lets you alter Oatmeal's velocity response curve directly: draw with the left mouse button, hold Shift to make smooth bumps or Ctrl to smooth the present curve. A right click will rescale it so that it touches the top (as well as the bottom, if you're holding Shift). Middle click to reset to the default.
  • Aftertouch box. Use this if you wish to modify Oatmeal's interpretation of any aftertouch magic you may want to invoke. It works the same way as the velocity box.
  • CC selectors, target switches and depth knobs - these modulation settings work the same way as above.

What do the buttons do?

There are several buttons on Oatmeal's GUI, and they do many (well, maybe one or two) exciting things! Let's learn about them.

• Waveform and LFO edit buttons - see below.
• About - displays an about box.
• Skin - lets you select a different skin, if you have any.
• Random - generates a random patch in a less exhaustive, but slightly more useful way than the host could by just randomising all the parameters. Sometimes comes up with almost usable results.
• < and >. These switch to the previous/next program, since some hosts are apparently too silly to include that sort of functionality.
• !. Panic button - kills all notes and resets the effects.
• Reset. Handle with care! Resets the current program to the Init patch.
• Load/save patch/bank. I wonder what these do!
• The MIDI settings page button in the lower right corner is replaced by a button that leads back to the main page if you're on any other page.

Waveform editor

Normal view:

Edit the waveform by drawing with the left mouse button. Hold Shift and click the start and end points to draw a straight line; hold Ctrl for either click (or both) to disregard the mouse's y coordinate at that point and use the waveform's current value instead. Hold Ctrl and draw for local smoothing; the higher up the mouse is, the more smoothing is applied. Right click for a context menu offering you some options detailed below, as well as several presets (plus the generation of random waveforms) and the option to switch to spectral mode:

Magnitude above, phase below. As in normal mode, draw with the left mouse button; but here, holding Shift and dragging results in amplifying or attenuating the harmonics above the cursor, or below the cursor if you hold Ctrl instead. Middle click and drag to scroll.

Apart from the presets, the context menu gives you the following options:

• Revert. Reverts to the last time you either switched presets or used the "apply" or "close" option below.
• Undo. Undoes the last change.
• Close. Closes the waveform editor and saves your changes.
• Apply. Saves your changes for the "revert" option above.
• Copy. Copies the waveform into an internal buffer (not the Windows clipboard) for pasting in other instances of the waveform editor (or as an additional safety against unwanted changes).
• Paste. Pastes the internal buffer.
• Fix. Removes any DC offset in the waveform and rescales it so that the maximum value is 1.
• Soften. Softens the waveform.
• Contract. Contracts peaks.
• Expand. Expands peaks.
• Contract/expand. Alternates between contracting and expanding peaks.
• FM. Applies frequency modulation to the waveform.
• Spectral Blur. Softens the spectrum (not necessarily the waveform).

LFO shape editor

Screenshot:

Draw as in the waveform editor; a middle click closes the LFO editor. Context menu:

• Fix. Offsets and scales so that the minimum and maximum value are 0 and 1.
• Grid. Sets the number of spaces in the grid in the background to facilitate making rhythmic shapes.
• Copy, Paste, Undo etc. as above.

Skinning

Oatmeal is reasonably skinnable. Look at the files in the "oatmeal skins" subdirectory for details; the "default.oms" file will hopefully be somewhat instructive. If you're having problems because Oatmeal is set to an insufficient skin, delete the file "oatmeal skins\current" and it should revert to the default skin.

Acknowledgments

VST is a trademark of Steinberg Media Technologies GmbH.

Because I am lazy, Oatmeal uses Laurent de Soras' FFT code in a few places.

PNG magic for the GUI is supplied by libpng.

Other things

Oatmeal uses sane names for note lengths wherever these are required. For those not accustomed to these, here's a handy-dandy translation chart:

Sensible	Silly
Whole note	Semibreve
Half note	Minim
Quarter note	Crotchet
Eighth note	Quaver
Sixteenth note	Semiquaver
Thirty-second note	Demisemiquaver

Oatmeal is freeware. Pass it around for free all you like (as long as you include this document), but don't sell it without my permission - we wouldn't want people paying money for this garbage, now would we? If you use it for anything very interesting, I'd like to know, but I wouldn't require it even if it were enforceable.

For any further questions, you can reach me by email. You might also check my website, such as it is, for other things. If you'd like to donate for some bizarre reason, the necessary information can be found here.

- f