doc finalization: instrument

doc/4-instrument/adpcm-a.md

@@ -0,0 +1,16 @@
+# ADPCM-A instrument editor
+
+The ADPCM-A instrument editor contains two tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+note that samples on ADPCM-A are tied to one frequency.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Global Volume**: sets the global volume of the ADPCM-A part.
+- **Panning**: toggle left/right output.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/adpcm-b.md

@@ -0,0 +1,15 @@
+# ADPCM-B instrument editor
+
+The ADPCM-B instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning**: toggle left/right output.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/beeper.md

@@ -0,0 +1,9 @@
+# beeper instrument editor
+
+used in PC Speaker and ZX Spectrum (SFX-like engine).
+
+- **Volume**: on-off volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Pulse Width**: pulse width sequence.
+  - only on ZX Spectrum.
+- **Pitch**: fine pitch.

doc/4-instrument/c140.md

@@ -1,17 +1,16 @@
 # Namco C140 instrument editor
 
-the Namco C140 instrument editor consists of a sample selector and several macros:
+The Namco C140 instrument editor contains three tabs: Sample and Macros.
 
-# Sample
+## Sample
 
-- **Initial sample**: specifies which sample should be assigned to the instrument, or the first one in the sequence.
-- **Use sample map**: enables mapping different samples to notes.
+for sample settings, see [the Sample instrument editor](sample.md).
 
-# Macros
+## Macros
 
 - **Volume**: volume sequence.
 - **Arpeggio**: pitch sequence.
 - **Panning (left)**: output level for left channel.
 - **Panning (right)**: output level for right channel.
 - **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of sample.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/c219.md

@@ -0,0 +1,20 @@
+# Namco C219 instrument editor
+
+The Namco C219 instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Control**: channel control sequence:
+  - **surround**: invert the right output for a surround effect.
+  - **invert**: invert both outputs. when used together with surround, this inverts just the left output.
+  - **noise**: toggles noise mode.
+  - setting control bits restart the sample!
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.

doc/4-instrument/es5506.md

@@ -0,0 +1,43 @@
+# Ensoniq ES5506 instrument editor
+
+The ES5506 instrument editor contains three tabs: Sample, ES5506 and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## ES5506
+
+ES5506 contains a filter, which is somewhat configurable.
+there's also a hardware envelope, but it's probably most useful for smoothing.
+
+you may use this tab to set up ES5506-specific parameters:
+
+- **Filter Mode**: sets filter mode.
+  - **HP/K2, HP/K2**: run high-pass twice using filter K2.
+  - **HP/K2, LP/K1**: run high-pass using filter K2, and then low-pass using filter K1.
+  - **LP/K2, LP/K2**: run low-pass twice using filter K2.
+  - **LP/K2, LP/K1**: run low-pass using filter K2, and then again using filter K1.
+- **Filter K1**: set coefficient 1 (K1). effectively controls cutoff.
+- **Filter K2**: set coefficient 2 (K2). effectively controls cutoff.
+- **Envelope count**: set length of hardware envelope (it's very short even at highest value).
+- **Left Volume Ramp**: how much to change left volume on every envelope step.
+- **Right Volume Ramp**: how much to change right volume on every envelope step.
+- **Filter K1 Ramp**: how much to change filter K1 every envelope step.
+- **Filter K2 Ramp**: how much to change filter K2 on every envelope step.
+- **K1 Ramp Slowdown**: increases length of K1 ramp.
+- **K2 Ramp Slowdown**: increases length of K2 ramp.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Filter Mode**: sets filter mode.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.
+- **Filter K1**: K1 sequence.
+- **Filter K2**: K2 sequence.
+- **Outputs**: ES5506 has 6 stereo output (total 12). select which pair of outputs to use.
+- **Control**: reverse/pause sequence.

doc/4-instrument/fm-opl.md

@@ -3,11 +3,11 @@
 The OPL FM editor is divided into 7 tabs:
 
 - **FM**: for controlling the basic parameters of FM sound source.
-- **Macros (FM)**: for macros controlling algorithm and feedback
-- **Macros (OP1)**: for macros controlling FM parameters of operator 1
-- **Macros (OP2)**: for macros controlling FM parameters of operator 2
-- **Macros (OP3)**: for macros controlling FM parameters of operator 3 (only when 4-op flag is set and only on OPL3!)
-- **Macros (OP4)**: for macros controlling FM parameters of operator 4 (only when 4-op flag is set and only on OPL3!)
+- **Macros (FM)**: for macros controlling algorithm and feedback.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3 (only when 4-op flag is set and only on OPL3!).
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4 (only when 4-op flag is set and only on OPL3!).
 - **Macros**: for miscellaneous macros controlling volume, arpeggio, and OPL3 panning.
 
 ## FM
@@ -41,7 +41,7 @@ These apply to each operator:
 
 - **Key Scale Rate (KSR)**: Also known as "Rate Scale". Determines the degree to which the envelope execution speed increases according to the pitch.
 - **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch (0-15 range but be noted that 11, 13 and 14 have no effect!).
-- **Waveform Select (WS)**: Changes the waveform generated by oscillator (OPL2 and OPL3 only, 0-3 range on OPL2 and 0-7 on OPL3).
+- **Waveform Select (WS)**: Changes the waveform of the operator (OPL2 and OPL3 only, 0-3 range on OPL2 and 0-7 on OPL3).
 - **Vibrato (VIB)**: Makes the operator affected by LFO vibrato.
 
 ## macros
@@ -64,3 +64,7 @@ All parameters are listed above.
 - **Pitch**: fine pitch.
   - **Relative**: when enabled, pitch changes are relative to the current pitch.
 - **Phase Reset**: restarts all operators and resets the waveform to its start.
+
+# OPL (drums) instrument editor
+
+this is similar to the OPL instrument editor, but sets the parameters of snare, tom, top and hi-hat directly once a drums instrument is activated.

doc/4-instrument/fm-opll.md

@@ -3,9 +3,9 @@
 The OPLL FM editor is divided into 5 tabs:
 
 - **FM**: for controlling the basic parameters of FM sound source.
-- **Macros (FM)**: for macros controlling algorithm, waveform and feedback
-- **Macros (OP1)**: for macros controlling FM parameters of operator 1
-- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros (FM)**: for macros controlling algorithm, waveform and feedback.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
 - **Macros**: for miscellaneous macros controlling volume, arpeggio, and preset.
 
 ## FM

doc/4-instrument/fm-opm.md

@@ -3,16 +3,16 @@
 The FM editor is divided into 7 tabs:
 
 - **FM**: for controlling the basic parameters of FM sound source.
-- **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
-- **Macros (OP1)**: for macros controlling FM parameters of operator 1
-- **Macros (OP2)**: for macros controlling FM parameters of operator 2
-- **Macros (OP3)**: for macros controlling FM parameters of operator 3
-- **Macros (OP4)**: for macros controlling FM parameters of operator 4
-- **Macros**: for miscellaneous macros controlling volume, arpeggio, and YM2151 noise generator.
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and noise generator.
 
 ## FM
 
-The FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound.
+OPM is four-operator, meaning it takes four oscillators to produce a single sound.
 
 These apply to the instrument as a whole:
 - **Feedback (FB)**: Determines how many times operator 1 returns its output to itself (0 to 7).
@@ -23,17 +23,18 @@ These apply to the instrument as a whole:
     - Middle-click pauses and unpauses the preview.
     - Right-click returns to algorithm view.
 
-- **LFO Frequency Sensitivity**: Determines the amount of LFO frequency changes (0 to 7).
-- **LFO Amplitude Sensitivity (AM)**: Determines the amount of LFO amplitude changes (0 to 3).
+- **LFO > Freq (FMS)**: Determines how much will LFO have an effect in frequency (0 to 7).
+- **LFO > Amp (AMS)**: Determines how much will LFO have an effect in volume (0 to 3).
+  - only applies to operators which have AM turned on.
 
 These apply to each operator:
 - The crossed-arrows button can be dragged to rearrange operators.
 - The **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
-- **Amplitude Modulation (AM)**: Makes the operator affected by LFO.
+- **Amplitude Modulation (AM)**: Makes the operator volume affected by LFO.
 - **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack (0 to 31).
 - **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate (0 to 31).
 - **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level (0 to 15).
-- **Secondary Decay Rate (DR2) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
 - **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release (0 to 15).
 - **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
 
@@ -63,13 +64,13 @@ All parameters are listed above.
 
 ## Macros
 
-- **Arpeggio**: Pitch change sequence in semitones.
+- **Arpeggio**: pitch sequence.
 - **Noise Frequency**: specifies the noise frequency.
   - this only applies to operator 4 of channel 8!
 - **Panning**: toggles output on left and right channels.
 - **Pitch**: fine pitch.
   - **Relative**: when enabled, pitch changes are relative to the current pitch.
-- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
+- **Phase Reset**: restarts all operators and resets the waveform to its start.
 
 
 # links

doc/4-instrument/fm-opn.md

@@ -3,11 +3,11 @@
 The FM editor is divided into 7 tabs:
 
 - **FM**: for controlling the basic parameters of FM sound source.
-- **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
-- **Macros (OP1)**: for macros controlling FM parameters of operator 1
-- **Macros (OP2)**: for macros controlling FM parameters of operator 2
-- **Macros (OP3)**: for macros controlling FM parameters of operator 3
-- **Macros (OP4)**: for macros controlling FM parameters of operator 4
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
 - **Macros**: for miscellaneous macros controlling volume, arpeggio, and pitch.
 
 ## FM
@@ -36,7 +36,7 @@ These apply to each operator:
 - **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack (0 to 31).
 - **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate (0 to 31).
 - **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level (0 to 15).
-- **Decay Rate 2 (DR2) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
 - **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release (0 to 15).
 - **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
 - **Hardware Envelope Generator (SSG-EG)**: Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate.

doc/4-instrument/fm-opz.md

@@ -12,32 +12,31 @@ The FM editor is divided into 7 tabs:
 
 ## FM
 
-The FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound.
+OPZ is four-operator, meaning it takes four oscillators to produce a single sound.
 
 These apply to the instrument as a whole:
-- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself (0 to 7).
 - **Algorithm (ALG)**: Determines how operators are connected to each other (0 to 7).
   - Left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
   - Right-click to switch to a preview display of the waveform generated on a new note:
     - Left-click restarts the preview.
     - Middle-click pauses and unpauses the preview.
     - Right-click returns to algorithm view.
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself (0 to 7).
 
-- **LFO Frequency Sensitivity (FMS/PMS)**: Determines the amount of LFO frequency changes (0 to 7).
-- **LFO Amplitude Sensitivity (AM)**: Determines the amount of LFO amplitude changes (0 to 3).
-- **LFO Frequency Sensitivity 2 (FMS/PMS2)**: Determines the amount of second LFO frequency changes (0 to 7).
-- **LFO Amplitude Sensitivity 2 (AMS2)**: Determines the amount of second LFO amplitude changes (0 to 3).
+- **LFO > Freq (FMS/PMS)**: Determines how much will LFO have an effect in frequency (0 to 7).
+- **LFO > Amp (AM)**: Determines how much will LFO have an effect in volume (0 to 3).
+- **LFO2 > Freq (FMS/PMS2)**: Determines how much will the second LFO have an effect in frequency (0 to 7).
+- **LFO2 > Amp (AMS2)**: Determines how much will the second LFO have an effect in volume (0 to 3).
 
 - **Request from TX81Z**: if a Yamaha TX81Z is plugged in as MIDI input and output device, this sends a SysEx to the device in order to fetch its current voice.
 
 These apply to each operator:
 - The crossed-arrows button can be dragged to rearrange operators.
-- The **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
-- **Amplitude Modulation (AM)**: Makes the operator affected by LFO.
+- **Amplitude Modulation (AM)**: Makes the operator's volume affected by LFO.
 - **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack (0 to 31).
 - **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate (0 to 31).
 - **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level (0 to 15).
-- **Secondary Decay Rate (DR2) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
 - **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release (0 to 15).
 - **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
 
@@ -46,7 +45,7 @@ These apply to each operator:
 - **Envelope Scale (RS/KS)**: Also known as "Key Scale" or "Rate Scale". Determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
 - **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch (0 to 15).
 - **Fine Frequency Multiplier (Fine)**: a fine control for MULT.
-- **Envelope Generator Shift (EGS)**: adds a "handicap" to the envelope. in other words, the minimum value.
+- **Envelope Generator Shift (EGS)**: adds a "handicap" to the envelope. in other words, the minimum volume of the operator.
   - 0: no change
   - 1: -12dB
   - 2: -24dB
@@ -54,8 +53,15 @@ These apply to each operator:
   - does not apply for OP4.
 - **Reverb (REV)**: not a true reverb. extends release time, giving a slight reverb-like effect to the operator.
 - **Fine Detune (DT)**: Shifts the pitch a little (0 to 7).
+- **Waveform Select (WS)**: Changes the waveform of the operator (OPL2 and OPL3 only, 0-3 range on OPL2 and 0-7 on OPL3).
 - **Coarse Detune (DT2)**: Shifts the pitch by tens of cents (0 to 3).
 
+#### I am familiar with Yamaha TX81Z. where's LS and KVS?
+
+these are software effects.
+- you may use TL effects to simulate LS.
+- you may access a KVS-like feature by clicking on the algorithm preview.
+
 ### fixed frequency mode
 
 each operator has a Fixed Frequency mode. once enabled, the operator runs at the specified frequency regardless of the note.
@@ -78,7 +84,7 @@ Macros define the sequence of values passed to the given parameter. Via macro, a
 
 ## OP1-OP4 Macros
 
-All parameters are listed above.
+most parameters are listed above.
 
 ## Macros
 

doc/4-instrument/ga20.md

@@ -0,0 +1,14 @@
+# Irem GA20 instrument editor
+
+The GA20 instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/game-boy.md

@@ -50,7 +50,7 @@ notes:
 
 - **Volume**: volume sequence.
   - note: this only appears if "Use software envelope" is checked.
-- **Arpeggio**: pitch in half-steps.
+- **Arpeggio**: pitch sequence.
 - **Duty/Noise**: pulse wave duty cycle or noise mode sequence.
 - **Waveform**: channel 3 wavetable sequence.
 - **Panning**: output for left and right channels.

doc/4-instrument/k007232.md

@@ -0,0 +1,16 @@
+# Konami K007232 instrument editor
+
+The K007232 instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/k053260.md

@@ -0,0 +1,15 @@
+# K053260 instrument editor
+
+The K053260 instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning**: stereo panning sequence.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/lynx.md

@@ -1,28 +1,38 @@
 # Atari Lynx instrument editor
 
-Atari Lynx instrument editor consists of these macros:
+Atari Lynx instrument editor consists of two tabs: Sample and Macros.
 
-- **Volume**: volume sequence
-- **Arpeggio**: pitch in half-steps
-- **Duty/Int**: bit pattern for LFSR taps and integration
-- **Panning (left)**: output level for left channel
-- **Panning (right)**: output level for right channel
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
+## Sample
 
-## Audio generation description
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+note that using samples on Lynx is CPU expensive!
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty/Int**: bit pattern for LFSR taps and integration.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform/LFSR reset.
+
+## audio generation description
 
 Atari Lynx generates sound using a 12-bit linear feedback shift register with configurable tap. Nine separate bits can be enabled to be the source of feedback: 0, 1, 2, 3, 4, 5, 7, 10 and 11. To generate _any_ sound at least one bit _must_ be enabled.
 
-### Square wave
+### square wave
 
 The LFSR is shifted at the rate define by sound pitch and generates square wave by setting channel output value to +volume or -volume, depending on the bit shifted in.
 
-### Triangle wave
+### triangle wave
 
 Alternatively when "int" bit is set sound wave is generated by adding or subtracting volume from output effectively producing triangle wave.
 
-#### How triangle wave works?
+#### how triangle wave works?
 
 Hint: To obtain triangle set bits "int" and "11" in "Duty/Int" sequence and set volume to about 22.
 By enabling 11th tap bit the value shifted in is negated after 11 bit is shifted in hence the volume is added for 11 cycles and then subtracted for 11 cycles.

doc/4-instrument/msm5232.md

@@ -0,0 +1,16 @@
+# MSM5232 instrument editor
+
+The instrument editor for MSM5232 consists of these macros:
+
+- **Volume**: volume sequence.
+  - only has effect when the envelope mode of a group is set to External.
+- **Arpeggio**: pitch sequence.
+- **Group Ctrl**: group control sequence:
+  - **sustain**: enable sustain mode.
+  - **2'**: enable 2' overtone.
+  - **4'**: enable 4' overtone.
+  - **8'**: enable 8' overtone.
+  - **16'**: enable 16' overtone.
+- **Group Attack**: set attack rate of group.
+- **Group Decay**: set decay rate of group.
+- **Noise**: toggle noise mode.

doc/4-instrument/msm6258.md

@@ -0,0 +1,19 @@
+# MSM6258 instrument editor
+
+The MSM6258 instrument editor contains two tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+note that samples on MSM6258 are tied to one frequency.
+
+## Macros
+
+- **Frequency Divider**: selects the frequency divider for the output.
+  - `0`: divide by 512.
+  - `1`: divide by 768.
+  - `2`: divide by 1024.
+- **Panning**: toggle left/right output.
+- **Phase Reset**: trigger restart of sample.
+- **Clock Divider**: clock divider sequence. when it is 1, the clock is divided by half.

doc/4-instrument/msm6295.md

@@ -0,0 +1,17 @@
+# MSM6295 instrument editor
+
+The MSM6295 instrument editor contains two tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+note that samples on MSM6295 are tied to one frequency.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Frequency Divider**: selects the frequency divider for the output.
+  - `0`: divide by 132.
+  - `1`: divide by 165.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/nes.md

@@ -1,18 +1,17 @@
-# Standard instrument editor
+# NES instrument editor
 
 The instrument editor for NES consists of these macros:
 
-- **Volume**: volume.
-- **Arpeggio**: pitch in half-steps.
-- **Duty**: duty cycle and noise mode.
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty/Noise**: duty cycle and noise mode.
   - pulse duty cycles:
     - `0`: 12.5%
     - `1`: 25%
     - `2`: 50%
     - `3`: 75%
   - noise modes:
-    - `0`: long noise.
-    - `1`: short noise.
-- **Panning**: output for left and right channels.
+    - `0`: long noise
+    - `1`: short noise
 - **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/pokemini.md

@@ -0,0 +1,8 @@
+# Pokémon Mini/QuadTone instrument editor
+
+used in these two chips/systems. these macros are available:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Pulse Width**: pulse width sequence.
+- **Pitch**: fine pitch.

doc/4-instrument/pokey.md

@@ -0,0 +1,25 @@
+# Atari POKEY instrument editor
+
+The instrument editor for POKEY consists of these macros:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **AUDCTL**: audio control register sequence:
+  - **poly9**: reduces size of LFSR. only on noise waveforms!
+  - **high1**: runs channel 1 at 1.79MHz.
+  - **high3**: runs channel 3 at 1.79MHz.
+  - **16-bit 1+2**: enables 16-bit frequency mode by combining channels 1 and 2.
+  - **16-bit 3+4**: enables 16-bit frequency mode by combining channels 3 and 4.
+  - **filter 1+3**: applies a high-pass "filter" by combining channels 1 and 3.
+  - **filter 2+4**: applies a high-pass "filter" by combining channels 2 and 4.
+  - **15KHz**: runs channels at 15KHz.
+- **Waveform**: wave selection sequence:
+  - 0: harsh noise (poly5+17)
+  - 1: square buzz (poly5)
+  - 2: weird noise (poly4+5)
+  - 3: square buzz (poly5)
+  - 4: soft noise (poly17)
+  - 5: square
+  - 6: bass (poly4)
+  - 7: buzz (poly4)
+- **Pitch**: fine pitch.

doc/4-instrument/psg.md

@@ -2,8 +2,8 @@
 
 The instrument editor for Sega PSG (SMS, and other TI SN76489 derivatives) consists of these macros:
 
-- **Volume**: volume.
-- **Arpeggio**: pitch in half-steps.
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
 - **Duty**: noise mode.
   - `0`: short noise; preset frequencies.
   - `1`: long noise; preset frequencies.

doc/4-instrument/pv1000.md

@@ -2,6 +2,6 @@
 
 The instrument editor for the Casio PV-1000 consists of these macros:
 
-- **Volume**: volume
-- **Arpeggio**: pitch in half-steps
-- **Pitch**: fine pitch
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Pitch**: fine pitch.

doc/4-instrument/qsound.md

@@ -0,0 +1,21 @@
+# Capcom QSound instrument editor
+
+The QSound instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Echo Level**: echo wet volume sequence.
+- **Panning**: stereo panning sequence.
+- **Surround**: toggles whether QSound algorithm is enabled.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.
+- **Echo Feedback**: echo feedback sequence.
+  - note: global!
+- **Echo Length**: echo length sequence.
+  - note: global!

doc/4-instrument/rf5c68.md

@@ -0,0 +1,16 @@
+# Ricoh RF5C68 instrument editor
+
+The RF5C68 instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/segapcm.md

@@ -0,0 +1,16 @@
+# SegaPCM instrument editor
+
+The SegaPCM instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/sm8521.md

@@ -0,0 +1,14 @@
+# SM8521 instrument editor
+
+The SM8521 instrument editor contains two tabs: Wavetable and Macros.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Waveform**: wavetable sequence.
+- **Pitch**: fine pitch.

doc/4-instrument/snes.md

@@ -1,42 +1,51 @@
 # SNES instrument editor
 
-these tabs are unique to the editor for SNES instruments.
+these four tabs are unique to the editor for SNES instruments.
 
+## Sample
 
+for sample settings, see [the Sample instrument editor](sample.md).
 
-# SNES
+## SNES
 
-**Use envelope** enables the ADSR volume envelope. if it's on:
+**Use envelope** enables the ADSR volume envelope. if it is on:
 
 - **A**: attack rate.
 - **D**: decay rate.
 - **S**: sustain level.
 - **D2**: decay rate during sustain.
+  - only appears when Sustain/release mode is Effective or Delayed.
 - **R**: release rate.
 - **Sustain/release mode**:
   - **Direct**: note release acts as note cut.
   - **Effective (linear decrease)**: after release, volume lowers by subtractions of 1/64 steps.
   - **Effective (exponential decrease)**: after release, volume decays exponentially. see [gain chart](../7-systems/snes.md).
-  - **Delayed (write R on release)**: after release, waits until A and D have completed before starting exponential decrease.
+  - **Delayed (write R on release)**: after release, waits until A and D have completed before starting release.
 
 if envelope is off:
 - **Gain Mode**: selects gain mode.
-  - **Direct**: direct gain from 0 to 127
-  - **Decrease (linear)**: linear gain from -0 to -31
-  - **Decrease (logarithmic)**: exponential gain from -0 to -31
-  - **Increase (linear)**: linear gain from +0 to +31
-  - **Increase (bent line)**: exponential gain from +0 to +31
-  - _note:_ using decrease modes will not produce any sound unless a Gain macro is set. The first tick must be the initial gain, and the second tick must be the decrease gain value. gain values are as described in the Macros section below.
+  - **Direct**: direct gain from 0 to 127.
+  - **Decrease (linear)**: linear gain from -0 to -31.
+  - **Decrease (logarithmic)**: exponential gain from -0 to -31.
+    - note: using decrease modes will not produce any sound unless a Gain macro is set. The first tick must be the initial gain, and the second tick must be the decrease gain value. gain values are as described in the Macros section below.
+  - **Increase (linear)**: linear gain from +0 to +31.
+  - **Increase (bent line)**: inverse exponential gain from +0 to +31.
 - **Gain**: value of gain.
 
+## Wavetable
 
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
 
-# Macros
+only active when Use wavetable is enabled in the Sample tab.
 
-- **Volume**: volume.
-- **Arpeggio**: pitch in half-steps.
-- **Noise Freq**: preset frequency of noise generator.
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise Freq**: frequency of noise generator.
+  - note: global!
 - **Waveform**: waveform.
+  - only effective when Use wavetable is enabled.
 - **Panning (left)**: output level of left channel.
 - **Panning (right)**: output level of right channel.
 - **Pitch**: fine pitch.
@@ -47,8 +56,8 @@ if envelope is off:
   - echo: enables echo.
   - noise: enables noise generator.
 - **Gain**: sets mode and value of gain.
-  - 0 - 127: direct gain from 0 to 127
-  - 128 - 159: linear gain from -0 to -31
-  - 160 - 191: exponential gain from -0 to -31
-  - 192 - 223: linear gain from +0 to +31
-  - 224 - 255: exponential gain from +0 to +31
+  - 0 to 127: direct gain from 0 to 127.
+  - 128 to 159: linear gain from -0 to -31 (decrease linear).
+  - 160 to 191: exponential gain from -0 to -31 (decrease exponential).
+  - 192 to 223: linear gain from +0 to +31 (increase linear).
+  - 224 to 255: exponential gain from +0 to +31 (increase bent line).

doc/4-instrument/su.md

@@ -0,0 +1,42 @@
+# tildearrow Sound Unit instrument editor
+
+this instrument editor has two tabs.
+
+## Sound Unit
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the differences are:
+- the lack of an "Use wavetable" option
+- the presence of a "Use sample" one
+- the presence of a "**Switch roles of frequency and phase reset timer**" option. when enabled, this writes frequency to the phase reset timer register rather than the frequency register
+  - this may be used to create sync-like effects.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty/Noise**: waveform duty cycle sequence.
+- **Waveform**: select waveform.
+  - `0`: pulse wave
+  - `1`: sawtooth
+  - `2`: sine wave
+  - `3`: triangle wave
+  - `4`: noise
+  - `5`: periodic noise
+  - `6`: XOR sine
+  - `7`: XOR triangle
+- **Panning**: stereo panning sequence.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.
+- **Cutoff**: set filter cutoff.
+- **Resonance**: set filter resonance.
+  - values that are too high may distort the output!
+- **Control**: filter parameter/ring mod sequence.
+  - **band pass**: a band-pass filter. cutoff determines which part of the sound is heard (from bass to treble).
+  - **high pass**: a high-pass filter. higher cutoff values result in a less "bassy" sound.
+  - **low pass**: a low-pass filter. the lower the cutoff, the darker the sound.
+  - **ring mod**: enable ring modulation with previous channel.
+    - note: square wave goes from 0 to volume, so in that case it acts more like amplitude modulation.
+- **Phase Reset Timer**: sets the phase reset timer.
+  - if the "Switch roles of frequency and phase reset timer" option in the Sound Unit tab is enabled, this macro controls the frequency register instead.

doc/4-instrument/t6w28.md

@@ -0,0 +1,13 @@
+# T6W28 instrument editor
+
+The instrument editor for T6W28 consists of these macros:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise Type**: noise type sequence:
+  - `0`: short noise
+  - `1`: long noise
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/ted.md

@@ -2,10 +2,12 @@
 
 TED instrument editor consists of these macros:
 
-- **Volume**: volume sequence. **global!**
-- **Arpeggio**: pitch sequence
-- **Square/Noise**: select whether square, noise or nothing will be output
+- **Volume**: volume sequence.
+  - note: global! affects entire chip.
+- **Arpeggio**: pitch sequence.
+- **Square/Noise**: select whether square, noise or nothing will be output.
   - noise only available on channel 2
   - if square and noise are enabled, square takes precedence.
-- **Pitch**: "fine" pitch
-- **Phase Reset**: trigger restart of waveform. **global!**
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.
+  - note: global! triggers both channels...

doc/4-instrument/vera.md

@@ -2,9 +2,9 @@
 
 VERA instrument editor consists of these macros:
 
-- **Volume**: volume sequence
-- **Arpeggio**: pitch sequence
-- **Duty**: pulse duty cycle sequence
-- **Waveform**: select the waveform used by instrument
-- **Panning**: output for left and right channels
-- **Pitch**: fine pitch
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty**: pulse duty cycle sequence.
+- **Waveform**: select the waveform used by instrument.
+- **Panning**: toggles left/right output.
+- **Pitch**: fine pitch.

doc/4-instrument/wonderswan.md

@@ -1,8 +1,27 @@
 # WonderSwan instrument editor
 
-WS instrument editor consists of only four macros, similar to PCE but with different volume and noise range:
+the WonderSwan instrument editor contains three tabs: Sample, Wavetable and Macros.
 
-- **Volume**: volume sequence
-- **Arpeggio**: pitch sequencr
-- **Noise**: noise LFSR tap sequence
-- **Waveform**: spicifies wavetables sequence
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+only on channel 2!
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## Macros
+
+these are similar to PC Engine, with some differences.
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise**: set noise size.
+  - only on channel 4.
+- **Waveform**: wave sequence.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/wsg.md

@@ -1,11 +1,20 @@
 # Namco WSG instrument editor
 
-The Namco WSG/C15/C30 instrument editor consists of these macros:
+The Namco WSG/C15/C30 instrument editor consists of two tabs: Wavetable and Macros.
 
-- **Volume**: volume sequence
-- **Arpeggio**: pitch sequence
-- **Waveform**: specifies wavetable sequence
-- **Noise**: specifies noise pitch (WARNING: only on C30!)
-- **Panning (left)**: output level of left channel
-- **Panning (right)**: output level of right channel
-- **Pitch**: fine pitch
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise**: specifies noise pitch.
+  - only applicable for Namco C30, and even so, only on the last 4 channels.
+- **Waveform**: specifies wavetable sequence.
+- **Panning (left)**: output level of left channel.
+  - Namco C30 only.
+- **Panning (right)**: output level of right channel.
+  - Namco C30 only.
+- **Pitch**: fine pitch.

doc/4-instrument/x1_010.md

@@ -1,11 +1,30 @@
 # X1-010 instrument editor
 
-X1-010 instrument editor consists of these macros.
+X1-010 instrument editor contains three tabs: Sample, Wavetable and Macros.
 
-- **Volume**: volume levels sequence
-- **Arpeggio**: pitch sequence
-- **Waveform**: specifies wavetables sequence
-- **Envelope Mode**: allows shaping an envelope
-- **Envelope**: specifies envelope shape sequence, it's also wavetable.
-- **Auto envelope numerator**: sets the envelope to the channel's frequency multiplied by numerator
-- **Auto envelope denominator**: sets the envelope to the channel's frequency divided by denominator
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+there also is a "Sample bank slot" setting, but I think that does nothing for now.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## Macros
+
+- **Volume**: volume levels sequence.
+- **Arpeggio**: pitch sequence.
+- **Waveform**: waveform selection sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Envelope Mode**: sets up envelope. the way it works is kind of complicated and even I don't understand how it works, so it's not documented for now.
+- **Envelope**: specifies which wavetable should be used for envelope.
+- **AutoEnv Num**: sets the envelope to the channel's frequency multiplied by numerator.
+- **AutoEnv Den**: sets the envelope to the channel's frequency divided by denominator.
+  - the X1-010 hardware envelope is considerably slower than AY's. beware!
+  - these two must be set in order for AutoEnv to work!

doc/4-instrument/ymz280b.md

@@ -0,0 +1,15 @@
+# YMZ280B instrument editor
+
+The YMZ280B instrument editor contains three tabs: Sample and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning**: stereo panning sequence.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.