Merge branch 'master' into opz-improvements

.github/workflows/build.yml

@@ -231,7 +231,9 @@ jobs:
         cp -vr ../po/locale locale
         cp -vr ../papers ../${binPath}/furnace.exe ./
         if [ '${{ matrix.config.compiler }}' == 'msvc' ]; then
-          cp -v ../${binPath}/furnace.pdb ./
+          if [ -e ../${binPath}/furnace.pdb ]; then
+            cp -v ../${binPath}/furnace.pdb ./
+          fi
         fi
         sha256sum ../${binPath}/furnace.exe > checksum.txt
 

CMakeLists.txt

@@ -16,7 +16,7 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 
 set(CMAKE_PROJECT_VERSION_MAJOR 0)
 set(CMAKE_PROJECT_VERSION_MINOR 6)
-set(CMAKE_PROJECT_VERSION_PATCH 5)
+set(CMAKE_PROJECT_VERSION_PATCH 6)
 
 set(BUILD_GUI_DEFAULT ON)
 set(USE_SDL2_DEFAULT ON)
@@ -552,6 +552,7 @@ src/engine/platform/sound/nes/fds.c
 src/engine/platform/sound/nes/mmc5.c
 src/engine/platform/sound/vera_psg.c
 src/engine/platform/sound/vera_pcm.c
+src/engine/platform/sound/ymf278b/ymf278.cpp
 
 src/engine/platform/sound/atomicssg/ssg.c
 
@@ -644,6 +645,10 @@ src/engine/platform/sound/ga20/iremga20.cpp
 
 src/engine/platform/sound/sm8521.c
 
+src/engine/platform/sound/supervision.c
+
+src/engine/platform/sound/upd1771c.c
+
 src/engine/platform/sound/d65modified.c
 
 src/engine/platform/sound/ted-sound.c
@@ -665,6 +670,8 @@ src/engine/platform/sound/sid2/wave8580_P_T.cc
 src/engine/platform/sound/sid2/wave8580__ST.cc
 src/engine/platform/sound/sid2/wave.cc
 
+src/engine/platform/sound/sid3.c
+
 src/engine/platform/oplAInterface.cpp
 src/engine/platform/ym2608Interface.cpp
 src/engine/platform/ym2610Interface.cpp
@@ -777,6 +784,8 @@ src/engine/platform/snes.cpp
 src/engine/platform/k007232.cpp
 src/engine/platform/ga20.cpp
 src/engine/platform/sm8521.cpp
+src/engine/platform/supervision.cpp
+src/engine/platform/upd1771c.cpp
 src/engine/platform/pv1000.cpp
 src/engine/platform/k053260.cpp
 src/engine/platform/ted.cpp
@@ -789,6 +798,7 @@ src/engine/platform/gbaminmod.cpp
 src/engine/platform/nds.cpp
 src/engine/platform/bifurcator.cpp
 src/engine/platform/sid2.cpp
+src/engine/platform/sid3.cpp
 src/engine/platform/pcmdac.cpp
 src/engine/platform/dummy.cpp
 

README.md

@@ -108,6 +108,7 @@ for other operating systems, you may [build the source](#developer-info).
   - some bug/quirk implementation for increased playback accuracy through compatibility flags
 - VGM export
 - ZSM export for Commander X16
+- TIunA export for Atari 2600
 - modular layout that you may adapt to your needs
 - audio file export - entire song, per chip or per channel
 - quality emulation cores (Nuked, MAME, SameBoy, Mednafen PCE, NSFplay, puNES, reSID, Stella, SAASound, vgsound_emu and ymfm)

android/app/build.gradle

@@ -15,8 +15,8 @@ android {
         }
         minSdkVersion 21
         targetSdkVersion 26
-        versionCode 214
-        versionName "0.6.5"
+        versionCode 219
+        versionName "0.6.7"
         externalNativeBuild {
             cmake {
                 arguments "-DANDROID_APP_PLATFORM=android-21", "-DANDROID_STL=c++_static", "-DWARNINGS_ARE_ERRORS=ON", "-DWITH_LOCALE=ON", "-DUSE_MOMO=ON"

android/app/src/main/AndroidManifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="org.tildearrow.furnace"
-    android:versionCode="214"
-    android:versionName="0.6.5"
+    android:versionCode="219"
+    android:versionName="0.6.7"
     android:installLocation="auto">
 
     <!-- OpenGL ES 2.0 -->

doc/1-intro/glossary.md

@@ -12,6 +12,8 @@
 
 **asset**: an instrument, wavetable or sample.
 
+**bit**: a single binary on-off value.
+
 **bitbang**: to achieve PCM sound by sending a rapid stream of volume commands to a non-PCM channel.
 
 **bitmask**: a set of bits which represent individual single-bit toggles or groups representing small numbers. these are explained fully in the [hexadecimal primer](hex.md).
@@ -72,6 +74,8 @@
 
 **LFO**: low frequency oscillator. a wave with a slow period (often below hearing range) used to alter other sounds.
 
+**LFSR**: linear-feedback shift register. a method to generate pseudo-random noise that loops, also known as "periodic noise". within a sequence of on-off bits, it does math to combine the bits at specified locations called "taps", then shifts the whole sequence and adds the resulting bit on the end, guaranteeing a different state for the next pass. depending on the locations of the taps, different lengths of noise loops are generated; for short loops, this will affect their tone.
+
 **macro**: a sequence of values automatically applied while a note plays.
 
 **noise bass**: the technique of using a PSG's periodic noise generator with a very short period to create low-frequency sounds.
@@ -86,7 +90,7 @@
 
 **period**: the length of a repeating waveform. as frequency rises, the period shortens.
 
-**periodic noise**: an approximation of random noise generated algorithmically.
+**periodic noise**: an approximation of random noise generated algorithmically with an LFSR.
 - the period is the number of values generated until the algorithm repeats itself.
 
 **phase reset**: to restart a waveform at its initial value.
@@ -128,6 +132,8 @@
 
 **supersaw**: a sound made up of multiple saw waves at slightly different frequencies to achieve a chorusing effect.
 
+**tap**: a specified bit location within an LFSR.
+
 **tick rate**: the number of times per second that the sound engine moves forward. all notes and effects are quantized to this rate.
 - this usually corresponds to the frame rate the system uses for video, approximately 60 for NTSC and 50 for PAL.
 

doc/2-interface/asset-list.md

@@ -13,10 +13,12 @@ buttons from left to right:
   - right-clicking always brings up the menu.
 - **Duplicate**: duplicates the currently selected instrument.
 - **Open**: brings up a file dialog to load a file as a new instrument at the end of the list.
+  - if the file is an instrument bank, a dialog will appear to select which instruments to load.
 - **Save**: brings up a file dialog to save the currently selected instrument.
   - instruments are saved as Furnace instrument (.fui) files.
   - right-clicking brings up a menu with the following options:
     - **save instrument as .dmp...**: saves the selected instrument in DefleMask format.
+    - **save all instruments...**: saves all instruments to the selected folder as .fui files.
 - **Toggle folders/standard view**: enables (and disables) folder view, explained below.
 - **Move up**: moves the currently selected instrument up in the list. pattern data will automatically be adjusted to match.
 - **Move down**: same, but downward.
@@ -41,9 +43,10 @@ everything from the instrument list applies here also, with one major difference
 
 wavetables are saved as Furnace wavetable (.fuw) files. 
 
-- right-clicking the Save button brings up a menu with the following options:
-  - **save wavetable as .dmw...**: saves the selected wavetable in DefleMask format.
-  - **save raw wavetable...**: saves the selected wavetable as raw data.
+right-clicking the Save button brings up a menu with the following options:
+- **save wavetable as .dmw...**: saves the selected wavetable in DefleMask format.
+- **save raw wavetable...**: saves the selected wavetable as raw data.
+- **save all wavetables...**: saves all wavetables to the selected folder as .fuw files.
 
 ## sample list
 
@@ -57,6 +60,7 @@ samples are saved as standard wave (.wav) files.
 
 right-clicking the Save button brings up a menu with the following options:
 - **save raw sample...**: saves the selected sample as raw data.
+- **save all samples...**: saves all samples to the selected folder as .wav files.
 
 right-clicking a sample in the list brings up a menu:
 - **make instrument**: creates a new instrument which is set to use the selected sample.

doc/2-interface/export.md

@@ -68,6 +68,13 @@ the following settings are available:
 - **loop**: enables loop. if disabled, the song won't loop.
 - **optimize size**: removes unnecessary commands to reduce size.
 
+## ROM
+
+depending on the system, this option may appear to allow you to export your song to a working ROM image or code that can be built into one. export options are explained in the system's accompanying documentation.
+
+currently, only one system can be exported this way:
+- [Atari 2600 (TIunA)](../7-systems/tia.md)
+
 ## text
 
 this option allows you to export your song as a text file.

doc/2-interface/keyboard.md

@@ -2,6 +2,8 @@
 
 everything on this list can be configured in the "Keyboard" tab of the Settings dialog.
 
+additionally, everything on this list can be accessed with the "command palette" using the default key combo of `Ctrl-P`.
+
 the keys in the "Global hotkeys" section can be used in any window, although not when a text field is activated.
 
 | action                                                 | default keybind  |
@@ -78,7 +80,7 @@ the keys in the "Global hotkeys" section can be used in any window, although not
 | Close current window                                   | `Shift-Escape`   |
 | Command Palette                                        | `Ctrl-P`         |
 | Recent files (Palette)                                 | —                |
-| Insstruments (Palette)                                 | —                |
+| Instruments (Palette)                                  | —                |
 | Samples (Palette)                                      | —                |
 |                                                        |                  |
 | **Note input**                                         |                  |
@@ -152,6 +154,9 @@ the keys in the "Global hotkeys" section can be used in any window, although not
 | Expand song                                            | —                |
 | Set note input latch                                   | —                |
 | Clear note input latch                                 | —                |
+| Absorb instrument/octave from status at cursor         | —                |
+| Return cursor to previous jump point                   | —                |
+| Reverse recent cursor undo                             | —                |
 |                                                        |                  |
 | **Instrument list**                                    |                  |
 | Add instrument                                         | `Insert`         |

doc/2-interface/settings.md

@@ -93,6 +93,10 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **Export**: select an `.ini` file to save current settings.
 - **Factory Reset**: resets all settings to default and purges settings backups.
 
+### Import
+
+- **Use OPL3 instead of OPL2 for S3M import**: changes which system is used for the import of S3M files that contain FM channels.
+
 ## Audio
 
 ### Output
@@ -501,6 +505,7 @@ below all the binds, select a key from the dropdown list to add it. it will appe
   - **Grid**
   - **Single (with list)**
 - **Use classic macro editor vertical slider**
+- **Automatic macro step size/horizontal zoom**
 
 ### Wave Editor
 
@@ -524,6 +529,8 @@ below all the binds, select a key from the dropdown list to add it. it will appe
 - **Position of Sustain in FM editor:**
   - **Between Decay and Sustain Rate**
   - **After Release Rate**
+  - **After Release Rate, after spacing**
+  - **After TL**
 - **Use separate colors for carriers/modulators in FM editor**
 - **Unsigned FM detune values**: uses the internal representation of detune values, such that detune amounts of -1, -2, and -3 are shown as 5, 6, and 7.
 

doc/3-pattern/effects.md

@@ -12,20 +12,26 @@ however, effects are continuous (unless specified), which means you only need to
 - `FAxy`: **Fast volume slide.** same as `0Axy` above but 4× faster.
 - `F3xx`: **Fine volume slide up.** same as `0Ax0` but 64× slower.
 - `F4xx`: **Fine volume slide down.** same as `0A0x` but 64× slower.
-- `F8xx`: **Single tick volume slide up.** adds `x` to volume on first tick only.
-- `F9xx`: **Single tick volume slide down.** subtracts `x` from volume on first tick only.
+- `F8xx`: **Single tick volume up.** adds `x` to volume.
+- `F9xx`: **Single tick volume down.** subtracts `x` from volume.
+  - ---
+- `D3xx`: **Volume portamento.** slides the volume to the one specified in the volume column. `x` is the slide speed.
+  - a volume _must_ be present with this effect for it to work.
+- `D4xx`: **Volume portamento (fast).** like `D3xx` but 4× faster.
   - ---
 - `07xy`: **Tremolo.** changes volume to be "wavy" with a sine LFO. `x` is the speed. `y` is the depth.
   - tremolo is downward only.
   - maximum tremolo depth is -60 volume steps.
+  - ---
+- `DCxx`: **Delayed mute.** sets channel volume to 0 after `xx` ticks.
 
 ## pitch
 
 - `E5xx`: **Set pitch.** `00` is -1 semitone, `80` is base pitch, `FF` is nearly +1 semitone.
 - `01xx`: **Pitch slide up.**
 - `02xx`: **Pitch slide down.**
-- `F1xx`: **Single tick pitch slide up.**
-- `F2xx`: **Single tick pitch slide down.**
+- `F1xx`: **Single tick pitch up.**
+- `F2xx`: **Single tick pitch down.**
   - ---
 - `03xx`: **Portamento.** slides the currently playing note's pitch toward the new note. `x` is the slide speed.
   - a note _must_ be present with this effect for it to work.
@@ -40,6 +46,7 @@ however, effects are continuous (unless specified), which means you only need to
 - `E8xy`: **Quick legato up**. transposes note up by `y` semitones after `x` ticks.
 - `E9xy`: **Quick legato down**. transposes note down by `y` semitones after `x` ticks.
 - `00xy`: **Arpeggio.** this effect produces a rapid cycle between the current note, the note plus `x` semitones and the note plus `y` semitones.
+  - as an example, start with a chord of C-3, G-3, and D#4. the G-3 and D#4 are 7 and 15 semitones higher than the root note, so the corresponding effect is `007F`.
 - `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values. default is 1.
   - ---
 - `04xy`: **Vibrato.** makes the pitch oscillate. `x` is the speed, while `y` is the depth.
@@ -190,22 +197,22 @@ additionally, [each chip has its own effects](../7-systems/README.md).
 
 the interpretation of duty, wave and extra macros depends on chip/instrument type:
 
-ex | FM     | OPM       | OPZ       | OPLL  | AY-3-8910  | AY8930     | Lynx     | C64        |
----|--------|-----------|-----------|-------|------------|------------|----------|------------|
- D | NoiseF | NoiseFreq |           |       | NoiseFreq  | NoiseFreq  | Duty/Int | Duty       |
- W |        | LFO Shape | LFO Shape | Patch | Waveform   | Waveform   |          | Waveform   |
- 1 |        | AMD       | AMD       |       |            | Duty       |          | FilterMode |
- 2 |        | PMD       | PMD       |       | Envelope   | Envelope   |          | Resonance  |
- 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          |            |
- A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          | Cutoff     |
- B | FB     | FB        | FB        |       |            | Noise AND  |          |            |
- C | FMS    | FMS       | FMS       |       |            | Noise OR   |          |            |
- D | AMS    | AMS       | AMS       |       |            |            |          |            |
- 4 | OpMask | OpMask    |           |       |            |            |          | Special    |
- 5 |        |           | AMD2      |       |            |            |          | Attack     |
- 6 |        |           | PMD2      |       |            |            |          | Decay      |
- 7 |        |           | LFO2Speed |       |            |            |          | Sustain    |
- 8 |        |           | LFO2Shape |       |            |            |          | Release    |
+ex | FM     | OPM       | OPZ       | OPLL  | AY-3-8910  | AY8930     | Lynx     | C64           |
+---|--------|-----------|-----------|-------|------------|------------|----------|---------------|
+ D | NoiseF | NoiseFreq |           |       | NoiseFreq  | NoiseFreq  | Duty/Int | Duty          |
+ W |        | LFO Shape | LFO Shape | Patch | Waveform   | Waveform   |          | Waveform      |
+ 1 |        | AMD       | AMD       |       |            | Duty       |          | FilterMode    |
+ 2 |        | PMD       | PMD       |       | Envelope   | Envelope   |          | Resonance     |
+ 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          | Filter Toggle |
+ A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          | Cutoff        |
+ B | FB     | FB        | FB        |       |            | Noise AND  |          |               |
+ C | FMS    | FMS       | FMS       |       |            | Noise OR   |          |               |
+ D | AMS    | AMS       | AMS       |       |            |            |          |               |
+ 4 | OpMask | OpMask    |           |       |            |            |          | Special       |
+ 5 |        |           | AMD2      |       |            |            |          | Attack        |
+ 6 |        |           | PMD2      |       |            |            |          | Decay         |
+ 7 |        |           | LFO2Speed |       |            |            |          | Sustain       |
+ 8 |        |           | LFO2Shape |       |            |            |          | Release       |
 
 ex | SAA1099  | X1-010     | Namco 163  | FDS       | Sound Unit | ES5506    | MSM6258  |
 ---|----------|------------|------------|-----------|------------|-----------|----------|
@@ -224,19 +231,61 @@ ex | SAA1099  | X1-010     | Namco 163  | FDS       | Sound Unit | ES5506    | M
  7 |          |            |            |           |            | EnvRampK2 |          |
  8 |          |            |            |           |            | Env Mode  |          |
 
-ex | QSound       | SNES      | MSM5232   |
----|--------------|-----------|-----------|
- D | Echo Level   | NoiseFreq | GroupCtrl |
- W |              | Waveform  |           |
- 1 | EchoFeedback | Special   | GroupAtk  |
- 2 | Echo Length  | Gain      | GroupDec  |
- 3 |              |           | Noise     |
- A |              |           |           |
- B |              |           |           |
- C |              |           |           |
- D |              |           |           |
- 4 |              |           |           |
- 5 |              |           |           |
- 6 |              |           |           |
- 7 |              |           |           |
- 8 |              |           |           |
+ex | QSound       | SNES      | MSM5232   | SID2          |
+---|--------------|-----------|-----------|---------------|
+ D | Echo Level   | NoiseFreq | GroupCtrl | Duty          |
+ W |              | Waveform  |           | Waveform      |
+ 1 | EchoFeedback | Special   | GroupAtk  | Filter mode   |
+ 2 | Echo Length  | Gain      | GroupDec  | Resonance     |
+ 3 |              |           | Noise     | Filter toggle |
+ A |              |           |           | Filter cutoff |
+ B |              |           |           |               |
+ C |              |           |           | Noise mode    |
+ D |              |           |           | Wave mix mode |
+ 4 |              |           |           | Special       |
+ 5 |              |           |           | Attack        |
+ 6 |              |           |           | Decay         |
+ 7 |              |           |           | Sustain       |
+ 8 |              |           |           | Release       |
+
+
+SID3 instrument also uses some of the FM operators macros in main macros list:
+
+ex    |   SID3                        |
+------|-------------------------------|
+ D    | Duty                          |
+ W    | Waveform                      |
+ 1    | Special                       |
+ 2    | Attack                        |
+ 3    | Decay                         |
+ A    | Special wave                  |
+ B    | Phase Mod source              |
+ C    | Ring Mod source               |
+ D    | Hard sync source              |
+ 4    | Sustain                       |
+ 5    | Sustain rate                  |
+ 6    | Release                       |
+ 7    | LFSR feedback bits            |
+ 8    | Wave mix mode                 |
+OP1 AM| Key On/Off                    |
+OP2 AM| Noise phase reset             |
+OP3 AM| Envelope reset                |
+OP4 AM| Noise Arpeggio                |
+OP1 AR| Noise Pitch                   |
+OP2 AR| 1-bit noise/PCM mode          |
+OP3 AR| Channel signal inversion      |
+OP4 AR| Feedback                      |
+
+SID3 instrument uses FM operators macros for filters:
+
+ex   |   SID3                        |
+-----|-------------------------------|
+D2R  | Cutoff                        |
+DAM  | Resonance                     |
+DR   | Filter toggle                 |
+DT2  | Distortion level              |
+DT   | Output volume                 |
+DVB  | Connect to channel input      |
+EGT  | Connect to channel output     |
+KSL  | Connection matrix row         |
+KSR  | Filter mode                   |

doc/4-instrument/README.md

@@ -67,6 +67,7 @@ the following instrument types are available:
 - [SegaPCM](segapcm.md) - for use with SegaPCM sample chip.
 - [Seta/Allumer X1-010](x1_010.md) - for use with Wavetable portion in Seta/Allumer X1-010.
 - [SID2](sid2.md) - for use with SID2 fantasy chip.
+- [SID3](sid3.md) - for use with SID3 fantasy chip.
 - [SM8521](sm8521.md) - for use with SM8521 chip, used in Tiger Game.com.
 - [SN76489/Sega PSG](psg.md) - for use with TI SN76489 and derivatives like Sega Master System's PSG.
 - [SNES](snes.md) - for use with SNES.

doc/4-instrument/c64.md

@@ -13,6 +13,8 @@ the C64 instrument editor consists of two tabs: "C64" to control various paramet
 - **Sustain**: sets the volume level at which the sound stops decaying and holds steady (0 to 15).
 - **Release**: determines the rate at which the sound fades out after note off. the higher the value, the longer the release (0 to 15).
 - **Duty**: specifies the width of a pulse wave (0 to 4095).
+- **Reset duty on new note**: overwrite current duty value with the one that is specified in the instrument on new note.
+  - only useful when using relative duty macro.
 - **Ring Modulation**: when enabled, the channel's output will be multiplied with the previous channel's.
 - **Oscillator Sync**: enables oscillator hard sync. as the previous channel's oscillator finishes a cycle, it resets the period of the channel's oscillator, forcing the latter to have the same base frequency. this can produce a harmonically rich sound, the timbre of which can be altered by varying the synchronized oscillator's frequency.
 

doc/4-instrument/fm-opn.md

@@ -39,7 +39,7 @@ these apply to each operator:
 - **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 note 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.
+- **Hardware Envelope Generator (SSG-EG)**: executes the built-in envelope, inherited from AY-3-8910 PSG. speed of execution is controlled via envelope parameters.
 
 ![FM ADSR chart](FM-ADSRchart.png)
 

doc/4-instrument/sid2.md

@@ -14,6 +14,8 @@ the SID2 instrument editor consists of two tabs: "SID2" to control various param
 - **Sustain**: sets the volume level at which the sound stops decaying and holds steady (0 to 15).
 - **Release**: determines the rate at which the sound fades out after note off. the higher the value, the longer the release (0 to 15).
 - **Duty**: specifies the width of a pulse wave (0 to 4095).
+- **Reset duty on new note**: overwrite current duty value with the one that is specified in the instrument on new note.
+  - only useful when using relative duty macro.
 - **Ring Modulation**: when enabled, the channel's output will be multiplied with the previous channel's.
 - **Oscillator Sync**: enables oscillator hard sync. as the previous channel's oscillator finishes a cycle, it resets the period of the channel's oscillator, forcing the latter to have the same base frequency. this can produce a harmonically rich sound, the timbre of which can be altered by varying the synchronized oscillator's frequency.
 

doc/4-instrument/sid3.md

@@ -0,0 +1,142 @@
+# SID3 instrument editor
+
+the SID3 editor is divided into 8 tabs:
+
+- **SID3**: for controlling the basic parameters of SID3 sound source.
+- **Wavetable**: for controlling the wavetable synth.
+- **Sample**: for various sample settings.
+- **Macros (Filter 1)**: for macros controlling parameters of filter 1.
+- **Macros (Filter 2)**: for macros controlling parameters of filter 2.
+- **Macros (Filter 3)**: for macros controlling parameters of filter 3.
+- **Macros (Filter 4)**: for macros controlling parameters of filter 4.
+- **Macros**: for other macros.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## 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.
+
+## SID3
+
+- **Waveform**: allows selecting a waveform.
+  - more than one waveform can be selected at once. in that case a logical AND mix of waves will occur...
+    - although with default mix mode it does occur a bit wrong (like on 8580 SID chip). see below what happens when other modes are in use.
+- **Special wave**: allows selecting a special wave. the wave preview is to the right.
+- **Wavetable channel**: replaces and hides some macros and UI elements, and makes instrument operate with last wavetable/sample channel:
+  - **Waveform** macro now selects a wavetable
+  - **Duty**, **Special Wave**, **Feedback**, **Noise Phase Reset**, **Noise LFSR bits** and **Wave Mix** macros are hidden
+  - **1-Bit Noise** macro now controls wavetable/PCM mode (it becomes **Sample Mode** macro)
+- **Inv. left** and **Inv. right**: invert the signal of corresponding stereo channels.
+- **Attack**: determines the rising time for the sound. the bigger the value, the slower the attack. (0 to 255).
+- **Decay**: determines the diminishing time for the sound. the higher the value, the longer the decay (0 to 255).
+- **Sustain**: sets the volume level at which the sound stops decaying and holds or also decays, but with different speed (0 to 255).
+- **Sustain rate**: sets the speed at which the sound decays after reaching sustain volume level. (0 to 255).
+- **Release**: determines the rate at which the sound fades out after note off. the higher the value, the longer the release (0 to 255).
+- **Wave Mix Mode**: dictates how different waves on the same channel are mixed together.
+- **Duty**: specifies the width of a pulse wave (0 to 65535).
+- **Feedback**: specifies the feedback level (0 to 255).
+- **Reset duty on new note**: overwrite current duty value with the one that is specified in the instrument on new note.
+  - only useful when using relative duty macro.
+- **Absolute Duty Macro**: when enabled, the duty macro will go from 0 to 65535 (in other words, control the duty directly rather than being relative).
+- **Ring Modulation**: when enabled, the channel's output will be multiplied with the source channel's.
+- **Oscillator Sync**: enables oscillator hard sync. as the source channel's oscillator finishes a cycle, it resets the period of the channel's oscillator, forcing the latter to have the same base frequency. this can produce a harmonically rich sound, the timbre of which can be altered by varying the synchronized oscillator's frequency.
+- **Phase Modulation**: when enabled, the channel's phase will be modified with the source channel's signal (signal is taken from filtered channel's output if filters are enabled).
+- **Separate noise pitch**: when enabled, the noise frequency/pitch will be controllable via special macros: **Noise Arpeggio** and **Noise Pitch**.
+
+Then follow controls for each of the 4 filters:
+
+- **Enable filter**: when enabled, this instrument will go through the filter.
+- **Initialize filter**: initializes the filter with the specified parameters:
+  - **Cutoff**: the filter's point in where frequencies are cut off (0 to 65535).
+  - **Resonance**: amplifies or focuses on the cutoff frequency, creating a secondary peak forms and colors the original pitch (0 to 255).
+  - **Filter mode**: sets the filter mode. you may pick one or more of the following:
+    - **low**: a low-pass filter. the lower the cutoff, the darker the sound.
+    - **high**: a high-pass filter. higher cutoff values result in a less "bassy" sound.
+    - **band**: a band-pass filter. cutoff determines which part of the sound is heard (from bass to treble).
+    - multiple filter modes can be selected simultaneously. for example, selecting both "low" and "high" results in a bandstop (notch) filter.
+  - **Output volume**: sets the filter output volume (0 to 255).
+  - **Distortion level**: dictates how hard the signal is distorted (soft clipping). distortion is slightly asymmetrical (0 to 255).
+- **Absolute Cutoff Macro**: when enabled, the cutoff macro will go from 0 to 65535, and it will be absolute.
+- **Change cutoff with pitch**: when enabled, the cutoff will be scaled according to the frequency offset from specified note.
+  - **Decrease cutoff when pitch increases**: if this is enabled, filter cutoff will decrease if you increase the pitch. if this is disabled, filter cutoff will increase if you increase the pitch.
+  - **Cutoff change center note**: this note marks the center frequency at which no cutoff scaling is happening. the further you go from it in each direction, the more the cutoff scaling will be.
+  - **Cutoff change strength**: how much cutoff will be scaled.
+- **Change resonance with pitch**: when enabled, the resonance will be scaled according to the frequency offset from specified note.
+  - **Decrease resonance when pitch increases**: if this is enabled, filter resonance will decrease if you increase the pitch. if this is disabled, filter resonance will increase if you increase the pitch.
+  - **Resonance change center note**: this note marks the center frequency at which no resonance scaling is happening. the further you go from it in each direction, the more the resonance scaling will be.
+  - **Resonance change strength**: how much resonance will be scaled.
+- **Filters connection matrix**: controls routing of the filters' signals.
+  - **In**: this column connects the filters to ADSR sound output.
+  - next 4 columns make up the inter-filters connection matrix.
+  - **Out**: this column connects the filters' output to final channel output.
+
+
+### special noise LFSR configurations
+
+this table contains a list of LFSR configurations that are automatically detected and brought to tune by Furnace. a short description is given. number needs to be pasted into **Noise LFSR bits** macro. it is recommended to place a single bar in **Noise Phase Reset** macro for the consistency of the wave.
+
+| LFSR config  |                                                                   Description                                                                             |
+|--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
+|    524288    | wave very close to [SID2](sid2.md) noise mode 1 wave. tonal, without very harsh overtones.                                                                |
+|  541065280   | wave resembling vocals, has two main tones at least 2 octaves apart                                                                                       |
+|     2068     | wave very close to SID2 noise mode 3 wave. tonal but with harsh timbre.                                                                                   |
+|      66      | wave very close to SID2 noise mode 2 wave. timbre is somewhere in-between SID2's noise mode 1 and noise mode 3 waves.                                     |
+
+if you find more interesting waves, please contact LTVA or tildearrow, so they can be added to Furnace frequency correction routine and to this table.
+
+## Filter `x` macros
+
+- **Cutoff**: filter `x` cutoff sequence.
+- **Resonance**: filter `x` resonance sequence.
+- **Filter toggle**: turns filter `x` on and off.
+- **Filter mode**: select filter `x` mode.
+- **Distortion level**: filter `x` distortion level sequence.
+- **Output Volume**: filter `x` output volume sequence.
+- **Channel Input Connection**: connect filter `x` to channel ADSR output.
+- **Channel Output Connection**: connect filter `x` output to final channel output.
+- **Connection Matrix Row**: connect other filters' outputs to filter `x` input.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Pitch**: fine pitch.
+- **Duty**: pulse width sequence.
+- **Waveform**: select the waveform used by instrument.
+  - in wavetable channel mode controls the wavetable index.
+- **Special Wave**: select the special wave used by instrument.
+- **Noise Arpeggio**: noise pitch sequence.
+  - this macro is visible only if **Separate noise pitch** option is enabled. otherwise noise pitch is controlled by **Arpeggio** and **Pitch** macros.
+- **Noise Pitch**: fine pitch.
+  - this macro is visible only if **Separate noise pitch** option is enabled.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Channel Inversion**: invert signal of left and right channels.
+- **Key On/Off**: envelope release/start again control.
+- **Special**: ring, oscillator sync and phase modulation selector.
+- **Ring Mod Source**: ring modulation source channel.
+- **Hard Sync Source**: oscillator sync source channel.
+- **Phase Mod Source**: phase modulation source channel.
+- **Feedback**: feedback sequence
+- **Phase Reset**: trigger restart of waveform.
+- **Noise Phase Reset**: trigger restart of noise accumulator and LFSR.
+- **Envelope Reset**: trigger restart of envelope (unlike key on/off, envelope is forced to restart from 0 volume level no matter which volume it is outputting now).
+- **Attack**: sets envelope attack speed.
+  - if you modify attack speed when the envelope is in attack phase it immediately changes.
+- **Decay**: sets envelope decay speed.
+  - if you modify decay speed when envelope is in decay phase it immediately changes.
+- **Sustain**: sets envelope sustain level.
+  - if you modify sustain level when envelope is in sustain phase it immediately changes.
+- **Sustain Rate**: sets envelope sustain rate.
+  - if you modify sustain rate when envelope is in sustain phase it immediately changes.
+- **Release**: sets envelope release speed.
+  - if you modify release speed when envelope is in release phase it immediately changes.
+- **Noise LFSR bits**: sets feedback bits of noise LFSR.
+- **1-Bit Noise**: controls noise mode.
+  - in wavetable channel mode it's called **Sample Mode**, and macro controls wave/PCM mode of the last channel.
+- **Wave Mix**: select the waveform mix mode.

doc/7-systems/README.md

@@ -102,6 +102,7 @@ this is the full list of chips that Furnace supports.
 - [SAA1099](saa1099.md)
 - [SegaPCM](segapcm.md)
 - [SID2](sid2.md)
+- [SID3](sid3.md)
 - [SM8521](sm8521.md)
 - [SN76489/Sega PSG](sms.md)
 - [SNES](snes.md)

doc/7-systems/c64.md

@@ -62,6 +62,14 @@ two versions of aforementioned chip exist - 6581 (original chip) and 8580 (impro
 - `21xy`: **set sustain/release.**
   - `x` is the sustain.
   - `y` is the release.
+- `22xx`: **pulse width slide up.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `23xx`: **pulse width slide down.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `24xx`: **filter cutoff slide up.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `25xx`: **filter cutoff slide down.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
 - `3xxx`: **set duty cycle.** `xxx` range is `000` to `FFF`.
 - `4xxx`: **set cutoff.** `xxx` range is `000` to `7FF`.
 

doc/7-systems/nes.md

@@ -20,6 +20,7 @@ the console is powered by the Ricoh 2A03, a CPU with sound generator built-in. i
   - may be `0` or `1` for the noise channel:
     - `0`: long (15-bit LFSR, 32767-step)
     - `1`: short (9-bit LFSR, 93-step)
+      - short noise may sound very different depending on its initial LFSR state. more info can be found at [NESdev](https://forums.nesdev.org/viewtopic.php?t=11535).
 - `13xy`: **setup sweep up.**
   - `x` is the time.
   - `y` is the shift.
@@ -50,7 +51,7 @@ the console is powered by the Ricoh 2A03, a CPU with sound generator built-in. i
 - `18xx`: **set PCM channel mode.**
   - `00`: PCM (software).
   - `01`: DPCM (hardware).
-  - when in DPCM mode, samples will sound muffled (due to its nature), availables pitches are limited, and loop point is ignored.
+  - when in DPCM mode, samples will sound muffled (due to its nature) and available pitches are limited. see "DPCM samples" below.
 - `19xx`: **set triangle linear counter.**
   - `00` to `7F` set the counter.
   - `80` and higher halt it.
@@ -58,7 +59,6 @@ the console is powered by the Ricoh 2A03, a CPU with sound generator built-in. i
   - only works in DPCM mode.
   - see table below for possible values.
 
-
 ## info
 
 this chip uses the [NES](../4-instrument/nes.md) instrument editor.
@@ -70,7 +70,13 @@ the following options are available in the Chip Manager window:
 - **Clock rate**: sets the rate at which the chip will run.
 - **DPCM channel mode**: allows you to set which mode to use for the DPCM channel.
   - DPCM: the default mode, playing 1-bit DPCM samples as supported by the hardware.
-  - PCM: this mode provides crispier samples by writing the delta counter directly. uses a lot of CPU time in console.
+  - PCM: this mode provides crisper 7-bit samples by writing to the delta counter directly. uses a lot of CPU time in console.
+
+## DPCM samples
+
+due to hardware limitations, a loop in a DPCM sample must start on a multiple of 512 samples (512, 1024, 1536...) and have a length that is a multiple of 128 plus 8 samples (136, 264, 392...)
+
+NES DPCM only has 16 preset sample rates, shown in a table below. for help adapting samples to work with this, see the [limited samples guide](../9-guides/limited-samples.md).
 
 ## short noise frequencies (NTSC)
 

doc/7-systems/sid2.md

@@ -1,10 +1,10 @@
 # SID2
 
-a fictional chip created by LTVA. the idea is to fix SID flaws and add more features, but not too much.
+a fictional chip created by LTVA. the idea is to fix [SID](c64.md) flaws and add more features, but not too much.
 
 unlike SID, it has per-channel volume control, better ADSR envelope which doesn't have bugs, more waveform mixing modes and the ability to play tonal noise waves.
 
-filter cutoff and resonance ranges were extended, as well as the frequency - finally the chip can hit B-7 note with default clock speed!
+each channel now has its own independent filter. filter cutoff and resonance ranges were extended, as well as the frequency - finally the chip can hit B-7 note with default clock speed!
 
 ## effects
 
@@ -46,6 +46,14 @@ filter cutoff and resonance ranges were extended, as well as the frequency - fin
     - `9`: phase reset (`y` is a discarded parameter and does not matter)
     - `A`: envelope key on/key off (`y` is `0` (trigger envelope release) or `1` (restart envelope again))
     - `B`: filter on/off (`y` is `0` (disable filter) or `1` (enable filter))
+- `17xx`: **pulse width slide up.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `18xx`: **pulse width slide down.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `19xx`: **filter cutoff slide up.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
+- `1Axx`: **filter cutoff slide down.**
+  - `xx` is speed. if it is `00`, the slide is stopped.
 - `3xxx`: **set duty cycle.** `xxx` range is `000` to `FFF`.
 - `4xxx`: **set cutoff.** `xxx` range is `000` to `FFF`.
 

doc/7-systems/sid3.md

@@ -0,0 +1,123 @@
+# SID3
+
+a fictional chip created by LTVA. the idea is to stay vaguely in [SID](c64.md)-like category of chips, but add a lot of features and more channels.
+
+chip has 6 synth channels and one channel capable of playing wavetable or streamed samples.
+
+each of synth channels has the following:
+
+- two phase accumulator based oscillators, one for tone and one for noise LFSR clocking; frequency range is from 0.001Hz to around 15kHz at default clock speed.
+- 5 waveform types which can be enabled in any combination: pulse (with 16-bit pulse width control), triangle, sawtooth, noise and so called special wave.
+  - there are 58 different special waves, including all [OPL3](opl.md) and [OPZ](opz.md) waveforms, their clipped versions, cubed sawtooth and triangle variations, and more...
+  - noise is generated from 30-bit LFSR. like in C64, eight of the bits are used to form 8-bit noise signal. user can adjust feedback freely, any bit can be feedback bit. some feedback bits configurations produce very short looped noise which is perceived as tone. see SID3 instrument description for notable feedback bits configurations which are automatically detected by Furnace: upon detection noise frequency is adjusted in such a way that fundamental frequency of such tonal noise becomes the note frequency the channel is currently playing (noise stays in tune).
+    - 1-bit noise mode is available for [AY](ay8910.md) fans. it this mode the highest LFSR bit is read as output. by rapidly switching between usual and 1-bit noise modes one can produce interesting rattling-like percussive sound.
+- 5 waveform mixing modes: 8580 SID (C64's combined waves; mode does bitwise AND with noise and special wave), bitwise AND, bitwise OR, bitwise XOR and sum of oscillators' signals.
+- hard sync between channels. each channel can have any other channel as sync source, even itself.
+- ring modulation between channels. each channel can have any other channel as modulation source, even itself. when you self-modulate, you effectively square the signal, but the behavior is a bit different.
+- phase modulation between channels. each channel can have any other channel as modulation source, even itself. when you self-modulate, you have an effect similar to enabling strong feedback. channel output after filters is used as modulation source.
+- ADSR envelope with sustain rate setting (how fast sound decays when envelope is in sustain phase).
+- 4 independent filters. each filter has its own cutoff, resonance, output volume, mode, on/off and distortion setting. each filter can be connected to channel's ADSR output. each filter's output can be routed to the final channel output. each filter output can be connected to each filter's input (full connection matrix).
+  - distortion is a simple asymmetrical distortion with hyperbolic tangent function for positive half of the wave and exponential function for negative half.
+  - several filters can be chained for flexible subtractive synth or to increase filter's slope (which is 12 dB/octave for a single filter).
+  - multiple filter modes can be selected simultaneously. for example, selecting both "low" and "high" results in a bandstop (notch) filter.
+- adjustable feedback. feedback saves two previous channel's outputs and adds them to accumulator on the next step before computing waveform signal.
+- fine control over left and right channel panning.
+- left and right channels' signals can be inverted to create simple "surround" sound.
+
+ADSR can be reset to the start of attack phase. phase of tone and noise oscillators can also be reset, and with noise oscillator reset noise LFSR is also reset to initial state.
+
+wave channel has all these features, except, obviously, waveform generation stage, as well as feedback and noise generator.
+
+## effects
+
+- `1xxx`: **set filter 1 cutoff.** `xxx` range is `000` to `FFF`.
+- `2xxx`: **set filter 2 cutoff.** `xxx` range is `000` to `FFF`.
+- `3xxx`: **set filter 3 cutoff.** `xxx` range is `000` to `FFF`.
+- `4xxx`: **set filter 4 cutoff.** `xxx` range is `000` to `FFF`.
+- `5xxx`: **set duty cycle.** `xxx` range is `000` to `FFF`.
+- `60xx`: **change wave.** lower 5 bits specify the wave:
+  - `bit 0`: triangle
+  - `bit 1`: saw
+  - `bit 2`: pulse
+  - `bit 3`: noise
+  - `bit 4`: special wave
+- `61xx`: **change special wave.** `xx` range is `00` to `39`.
+- `62xx`: **modulation control.** lower 3 bits control the modulation:
+  - `bit 0`: ring modulation
+  - `bit 1`: oscillator sync
+  - `bit 2`: phase modulation
+- `63xy`: **reset duty cycle**:
+  - if `x` is not 0: on new note
+  - if `y` is not 0: now
+- `64xx`: **set ring modulation source channel.** `xx` range is `00` to `07` where `07` means self-modulation and lower values specify a source channel.
+- `65xx`: **set hard sync source channel.** `xx` is `00` to `06`.
+- `66xx`: **set phase modulation source channel.** `xx` is `00` to `06`.
+- `67xx`: **set attack.** `xx` range is `00` to `FF`.
+- `68xx`: **set decay.** `xx` range is `00` to `FF`.
+- `69xx`: **set sustain level.** `xx` range is `00` to `FF`.
+- `6Axx`: **set sustain rate.** `xx` range is `00` to `FF`.
+- `6Bxx`: **set release.** `xx` range is `00` to `FF`.
+- `6Cxx`: **set waveform mix mode.** `xx` range is `00` to `04`.
+- `6Dxx`: **set noise LFSR feedback bits (lower byte).** `xx` range is `00` to `FF`.
+- `6Exx`: **set noise LFSR feedback bits (medium byte).** `xx` range is `00` to `FF`.
+- `6Fxx`: **set noise LFSR feedback bits (higher byte).** `xx` range is `00` to `FF`.
+- `70xx`: **set noise LFSR feedback bits (highest bits).** `xx` range is `00` to `3F`.
+- `71xx`: **set filter 1 resonance.** `xx` range is `00` to `FF`.
+- `72xx`: **set filter 2 resonance.** `xx` range is `00` to `FF`.
+- `73xx`: **set filter 3 resonance.** `xx` range is `00` to `FF`.
+- `74xx`: **set filter 4 resonance.** `xx` range is `00` to `FF`.
+- `75xx`: **set noise/wave channel mode.** `xx` range is `00` to `01`. on synth channels `00` sets usual noise mode and `01` sets 1-bit noise mode. on wave channel `00` sets wavetable mode and `01` sets streamed PCM sample playback mode.
+- `76xx`: **set filter 1 output volume.** `xx` range is `00` to `FF`.
+- `77xx`: **set filter 2 output volume.** `xx` range is `00` to `FF`.
+- `78xx`: **set filter 3 output volume.** `xx` range is `00` to `FF`.
+- `79xx`: **set filter 4 output volume.** `xx` range is `00` to `FF`.
+- `7Axx`: **set filter 1 distortion.** `xx` range is `00` to `FF`.
+- `7Bxx`: **set filter 2 distortion.** `xx` range is `00` to `FF`.
+- `7Cxx`: **set filter 3 distortion.** `xx` range is `00` to `FF`.
+- `7Dxx`: **set filter 4 distortion.** `xx` range is `00` to `FF`.
+- `7Exx`: **set feedback.** `xx` range is `00` to `FF`.
+- `7Fxx`: **channel inversion control.** lower 2 bits control the channel signal inversion:
+  - `bit 0`: invert right channel
+  - `bit 1`: invert left channel
+- `A0xy`: **set filter mode.** `x` is the filter (`0-3`), and lower 3 bits of `y` control the mode:
+  - `bit 0`: low pass
+  - `bit 1`: band pass
+  - `bit 2`: high pass
+- `A1xy`: **set filter connection.** `x` is the filter (`0-3`), and lower 2 bits of `y` control the connection:
+  - `bit 0`: connect filter input to channel's ADSR output
+  - `bit 1`: connect filter's output to final channel output
+- `A2xy`: **set filter connection matrix row.** `x` is the filter (`0-3`), and lower 4 bits of `y` control the inter-filter connections:
+  - `bit 0`: connect filter input to filter 1 output
+  - `bit 1`: connect filter input to filter 2 output
+  - `bit 2`: connect filter input to filter 3 output
+  - `bit 3`: connect filter input to filter 4 output
+- `A3xy`: **enable filter.** `x` is the filter (`0-3`), `y` is either `0` (filter disabled) or `1` (filter enabled).
+- `A4xx`: **pulse width slide up.** `xx` is speed. `A400` stops the slide.
+- `A5xx`: **pulse width slide down.** `xx` is speed. `A500` stops the slide.
+- `A6xx`: **filter 1 cutoff slide up.** `xx` is speed. `A600` stops the slide.
+- `A7xx`: **filter 1 cutoff slide down.** `xx` is speed. `A700` stops the slide.
+- `A8xx`: **filter 2 cutoff slide up.** `xx` is speed. `A800` stops the slide.
+- `A9xx`: **filter 2 cutoff slide down.** `xx` is speed. `A900` stops the slide.
+- `AAxx`: **filter 3 cutoff slide up.** `xx` is speed. `AA00` stops the slide.
+- `ABxx`: **filter 3 cutoff slide down.** `xx` is speed. `AB00` stops the slide.
+- `ACxx`: **filter 4 cutoff slide up.** `xx` is speed. `AC00` stops the slide.
+- `ADxx`: **filter 4 cutoff slide down.** `xx` is speed. `AD00` stops the slide.
+- `AExx`: **tone phase reset.** `xx` is the tick on which the phase reset happens.
+- `AFxx`: **noise phase reset.** `xx` is the tick on which the phase reset happens.
+- `B0xx`: **envelope reset.** `xx` is the tick on which the envelope reset happens.
+- `B1xy`: **filter cutoff scaling control.** `x` is the filter (`0-3`), and lower 2 bits of `y` control the scaling:
+  - `bit 0`: enable cutoff scaling
+  - `bit 1`: inverse cutoff scaling
+- `B2xy`: **filter resonance scaling control.** `x` is the filter (`0-3`), and lower 2 bits of `y` control the scaling:
+  - `bit 0`: enable resonance scaling
+  - `bit 1`: inverse resonance scaling
+
+## info
+
+this chip uses the [SID3](../4-instrument/sid3.md) instrument editor.
+
+## chip config
+
+the following options are available in the Chip Manager window:
+
+- **Quarter clock speed**: make chip run on quarter the default clock rate (1MHz is default). this lowers CPU load almost 4 times at the cost of filters becoming unstable or having different timbre at high cutoff and resonance settings. option affects the chip only in playback mode. when you render module into audio file, option is not applied.

doc/7-systems/tia.md

@@ -27,13 +27,9 @@ Furnace isn't complete without this one...
   - `E`: low pure buzzy
   - `F`: low reedy
 
+## ROM export
 
-
-## info
-
-this chip uses the [TIA](../4-instrument/tia.md) instrument editor.
-
-the arp macro's fixed mode operates differently, writing the direct pitch to the chip. here's a list of pitches.
+a song can be exported to assembly code for use with the TIunA software driver for the Atari 2600. see [TIunA on GitHub](https://github.com/AYCEdemo/twin-tiuna) for explanations of the export options.
 
 ## chip config
 
@@ -47,6 +43,12 @@ the following options are available in the Chip Manager window:
   - **Stereo**: output two channels on left and right.
 - **PAL**: run slower blah blah blah
 
+## info
+
+this chip uses the [TIA](../4-instrument/tia.md) instrument editor.
+
+the arp macro's fixed mode operates differently, writing the direct pitch to the chip. here's a list of pitches.
+
 ### shape 1
 
 | pitch |    NTSC | note | cent |    PAL  | note | cent

doc/7-systems/ym2151.md

@@ -68,9 +68,13 @@ in most arcade boards the chip was used in combination with a PCM chip, like [Se
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
 
 ## info
 

doc/7-systems/ym2203.md

@@ -99,9 +99,17 @@ several variants of this chip were released as well, with more features.
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
+
+## info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md) and [AY-3-8910/SSG](../4-instrument/ay8910.md) instrument editor.
 
 ## extended channel 3
 
@@ -109,9 +117,11 @@ in ExtCh mode, channel 3 is split into one column for each of its four operators
 
 all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
 
-## info
+## SSG-EG
 
-this chip uses the [FM (OPN)](../4-instrument/fm-opn.md) and [AY-3-8910/SSG](../4-instrument/ay8910.md) instrument editor.
+SSG-EG is short for "Software-controlled Sound Generator – Envelope Generator". it is the AY-3-8910/YM2149 envelope generator applied to each individual operator. it makes the operator's envelope play through attack, decay, sustain, and decay 2 until it reaches zero amplitude, at which time SSG triggers. according to the shape of the SSG envelope, the operator's envelope may then either loop or hold, and either of these can be set to invert the envelope (attack decreases and decay increases) when triggered.
+
+a full guide to SSG-EG is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU), this [detailed technical explanation](https://gendev.spritesmind.net/forum/viewtopic.php?t=386&start=106), and this [chart of tunings](https://docs.google.com/spreadsheets/d/1HGKQ08CnLGAjA1U0StJFldod3FkQ3uq86rYy1VBIuZc/).
 
 ## chip config
 

doc/7-systems/ym2608.md

@@ -99,19 +99,29 @@ the YM2610 (OPNB) and YM2610B chips are very similar to this one, but the built-
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
   
+## info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+
 ## extended channel 3
 
 in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
 
 all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
 
-## info
+## SSG-EG
 
-this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+SSG-EG is short for "Software-controlled Sound Generator – Envelope Generator". it is the AY-3-8910/YM2149 envelope generator applied to each individual operator. it makes the operator's envelope play through attack, decay, sustain, and decay 2 until it reaches zero amplitude, at which time SSG triggers. according to the shape of the SSG envelope, the operator's envelope may then either loop or hold, and either of these can be set to invert the envelope (attack decreases and decay increases) when triggered.
+
+a full guide to SSG-EG is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU), this [detailed technical explanation](https://gendev.spritesmind.net/forum/viewtopic.php?t=386&start=106), and this [chart of tunings](https://docs.google.com/spreadsheets/d/1HGKQ08CnLGAjA1U0StJFldod3FkQ3uq86rYy1VBIuZc/).
 
 ## chip config
 

doc/7-systems/ym2610.md

@@ -97,9 +97,17 @@ its soundchip is a 4-in-1: 4ch 4-op FM, YM2149 (AY-3-8910 clone) and [2 differen
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
+
+## info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
 
 ## extended channel 2
 
@@ -107,9 +115,11 @@ in ExtCh mode, channel 2 is split into one column for each of its four operators
 
 all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
 
-## info
+## SSG-EG
 
-this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+SSG-EG is short for "Software-controlled Sound Generator – Envelope Generator". it is the AY-3-8910/YM2149 envelope generator applied to each individual operator. it makes the operator's envelope play through attack, decay, sustain, and decay 2 until it reaches zero amplitude, at which time SSG triggers. according to the shape of the SSG envelope, the operator's envelope may then either loop or hold, and either of these can be set to invert the envelope (attack decreases and decay increases) when triggered.
+
+a full guide to SSG-EG is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU), this [detailed technical explanation](https://gendev.spritesmind.net/forum/viewtopic.php?t=386&start=106), and this [chart of tunings](https://docs.google.com/spreadsheets/d/1HGKQ08CnLGAjA1U0StJFldod3FkQ3uq86rYy1VBIuZc/).
 
 ## chip config
 

doc/7-systems/ym2610b.md

@@ -96,9 +96,17 @@ it is backward compatible with the original chip.
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
+
+## info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
 
 ## extended channel 3
 
@@ -106,9 +114,11 @@ in ExtCh mode, channel 3 is split into one column for each of its four operators
 
 all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
 
-## info
+## SSG-EG
 
-this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+SSG-EG is short for "Software-controlled Sound Generator – Envelope Generator". it is the AY-3-8910/YM2149 envelope generator applied to each individual operator. it makes the operator's envelope play through attack, decay, sustain, and decay 2 until it reaches zero amplitude, at which time SSG triggers. according to the shape of the SSG envelope, the operator's envelope may then either loop or hold, and either of these can be set to invert the envelope (attack decreases and decay increases) when triggered.
+
+a full guide to SSG-EG is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU), this [detailed technical explanation](https://gendev.spritesmind.net/forum/viewtopic.php?t=386&start=106), and this [chart of tunings](https://docs.google.com/spreadsheets/d/1HGKQ08CnLGAjA1U0StJFldod3FkQ3uq86rYy1VBIuZc/).
 
 ## chip config
 

doc/7-systems/ym2612.md

@@ -1,23 +1,8 @@
 # Yamaha YM2612
 
-one of two chips that powered the Sega Genesis. it is a six-channel, four-operator FM synthesizer. channel #6 can be turned into 8-bit PCM player, that via software mixing, thanks to Z80 sound CPU, can play more than one channel of straight-shot samples at once. 
+one of two chips that powered the Sega Genesis. it is a six-channel, four-operator FM synthesizer. channel 6 can be turned into 8-bit PCM player, that via software mixing, thanks to Z80 sound CPU, can play more than one channel of straight-shot samples at once. 
 Furnace also offers DualPCM, a Z80 driver that splits channel 6 into two individual PCM channels with variable pitch. using the console's Z80 processor, these are mixed together in software and streamed to channel 6 in PCM mode with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.
 
-## extended channel 3
-
-in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
-
-all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
-
-## CSM
-
-CSM is short for "Composite Sinusoidal Modeling". CSM works by sending key-on and key-off commands to channel 3 at a specific frequency, controlled by the added "CSM Timer" channel. this can be used to create vocal formants (speech synthesis!) or other complex effects.
-
-CSM is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU).
-
-## DualPCM
-
-thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode splits channel 6 into two individual PCM channels with variable pitch. these are mixed together in software and streamed to channel 6 with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.
 ## effects
 
 - `10xy`: **set LFO parameters.**
@@ -30,10 +15,10 @@ thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode spl
 - `15xx`: **set operator 4 level.**
 - `16xy`: **set multiplier of operator.**
   - `x` is the operator (1-4).
-  - `y` is the new MULT value..
+  - `y` is the new MULT value.
 - `17xx`: **toggle LEGACY sample mode.**
   - this only works on channel 6.
-  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommended. use Sample type instruments instead.**
 - `18xx`: **toggle extended channel 3 mode.**
   - 0 disables it and 1 enables it.
   - only in extended channel 3 chip.
@@ -82,14 +67,40 @@ thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode spl
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
-- `60xx`: **set operator mask.**
-  - `xx` goes from `0` to `F`. it is a bitfield.
-    - each bit corresponds to an operator.
+- `60xy`: **set operator mask.**
+  - enables or disables operators.
+  - if `x` is `0`, `y` ranges from `0` to `F`. it is a bitfield, so `y` is the sum of the active operators' bits:
+    - OP1 is +1, OP2 is +2, OP3 is +4, and OP4 is +8.
+    - for example, having only OP2 and OP4 on would be 2 + 8 = 10, resulting in an `xy` value of `0A`.
+  - if `x` is `1` to `4`, the effect targets that operator; `y` turns it off with a value of `0` and on with a value of `1`.
+    - for example, the effect `6031` enables OP3.
 
 ## info
 
 this chip uses the [FM (OPN)](../4-instrument/fm-opn.md) and [Generic Sample](../4-instrument/sample.md) instrument editors.
 
+## extended channel 3
+
+in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
+
+all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
+
+## CSM
+
+CSM, or "Composite Sine Mode", involves a timer matching the frequency of the note in the "CSM Timer" channel. each time it triggers, it generates key-on and key-off commands to reset the phase of all operators on channel 3 and force their envelopes to restart at the release point. this can be used to create vocal formants (speech synthesis!) or other complex effects. outside this chip's specific implementation, the technique is known as "oscillator sync".
+
+working with CSM is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU).
+
+## DualPCM
+
+thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode splits channel 6 into two individual PCM channels with variable pitch. these are mixed together in software and streamed to channel 6 with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.
+
+## SSG-EG
+
+SSG-EG is short for "Software-controlled Sound Generator – Envelope Generator". it is the AY-3-8910/YM2149 envelope generator applied to each individual operator. it makes the operator's envelope play through attack, decay, sustain, and decay 2 until it reaches zero amplitude, at which time SSG triggers. according to the shape of the SSG envelope, the operator's envelope may then either loop or hold, and either of these can be set to invert the envelope (attack decreases and decay increases) when triggered.
+
+a full guide to SSG-EG is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU), this [detailed technical explanation](https://gendev.spritesmind.net/forum/viewtopic.php?t=386&start=106), and this [chart of tunings](https://docs.google.com/spreadsheets/d/1HGKQ08CnLGAjA1U0StJFldod3FkQ3uq86rYy1VBIuZc/).
+
 ## chip config
 
 the following options are available in the Chip Manager window:

doc/8-advanced/user-systems.md

@@ -12,6 +12,7 @@ chip configuration is exactly as in the [chip manager](chip-manager.md) window.
 
 the **Advanced** field stores additional settings that are set when a new song is started. these are listed in "option=value" format, one per line.
 - `tickRate`: sets tick rate.
+- `chanMask`: sets which channels to hide. written as a comma-separated list of integers
 
 **Save and Close**: as it says.
 

doc/8-advanced/xyosc.md

@@ -2,7 +2,7 @@
 
 also called "vectorscope", this is similar to the normal oscilloscope in that it draws audio output as a waveform, but instead of being one-dimensional and going from left to right, it is plotted in two dimensions (usually X represents left output and Y represents right output).
 
-(TODO: image)
+![oscilloscope (X-Y)](xyosc.png)
 
 right-clicking the X-Y oscilloscope window displays settings:
 - **X Channel**: the output channel which will affect the X (horizontal) axis. default is 1 (left).

doc/9-guides/emulation-cores.md

@@ -3,13 +3,13 @@
 Furnace achieves the authentic sound of videogame hardware by emulating sound chips as accurately as possible, using **emulator cores**. in some cases there are multiple cores to choose from, each with different strengths and weaknesses. here are the major differences between them all.
 
 - **YM2151 core**:
-  - **ymfm**: default playback core. much less CPU usage than Nuked-OPM, but less accurate. recommended for users with last-gen or earlier hardware.
+  - **ymfm**: default playback core. much less CPU usage than Nuked-OPM, but less accurate. recommended for users with mobile, last-gen or earlier hardware.
   - **Nuked-OPM**: default render core. much more accurate than ymfm, due to the emulator being based on an image of the die map taken from a real YM2151. very CPU heavy, only recommended for users with recent hardware.
 
 - **YM2612 core**:
-  - **Nuked-OPN2**: default core. a little lighter on the CPU than Nuked-OPM.
+  - **Nuked-OPN2**: default core. lighter on the CPU than Nuked-OPM, can be used to simulate any variant of YM2612.
   - **ymfm**: same as ymfm above.
-  - **YMF276-LLE**: a new core written by the author of the Nuked cores, specifically focused on YMF276 emulation. it is very slow and not useful for real-time playback.
+  - **YMF276-LLE**: a new core written by the author of the Nuked cores, specifically focused on YMF276 emulation. it is very slow and not useful for real-time playback. Produces audio comparable to output of Sega Mega Drive model 2 and later Fujitsu FM Towns computers, doesn't emulate DAC distortion of the original YM2612.
 
 - **SN76489 core**:
   - **MAME**: default core. less accurate than Nuked, but with lower CPU usage. comes from the MAME emulator project.
@@ -25,7 +25,7 @@ Furnace achieves the authentic sound of videogame hardware by emulating sound ch
 
 - **SID core**:
   - **reSID**: default playback core. a high quality emulation core. somewhat CPU heavy.
-  - **reSIDfp**: default render core. improved version of reSID. the most accurate choice. _extremely_ CPU heavy.
+  - **reSIDfp**: default render core. improved version of reSID. the most accurate choice. _very_ CPU heavy.
   - **dSID**: a lightweight open-source core used in DefleMask. not so accurate but it's very CPU light.
 
 - **POKEY core**:
@@ -35,20 +35,24 @@ Furnace achieves the authentic sound of videogame hardware by emulating sound ch
 - **OPN/OPNA/OPNB cores**:
   - **ymfm only**: lower CPU usage, less accurate FM.
   - **Nuked-OPN2 (FM) + ymfm (SSG/ADPCM)**: default cores. more accurate FM at the cost of more CPU load.
-  - **YM2608-LLE**: a new core written by the author of the Nuked cores. high accuracy, but extremely high CPU usage.
+  - **YM2608-LLE**: a new core written by the author of the Nuked cores. high accuracy, but _extremely_ high CPU usage, far beyond any other emulation core. (over 500% CPU time on 10th gen Intel Core i5!) 
 
 - **OPL/OPL2/Y8950 core**:
   - **Nuked-OPL3**: high quality OPL emulation core. slightly off due to tiny differences between OPL and OPL3, but otherwise it is good.
   - **ymfm**: this core is supposed to use less CPU than Nuked-OPL3, but for some reason it actually doesn't.
-  - **YM3812-LLE**: a new core written by the author of the Nuked cores. it features extremely accurate emulation.
+  - **YM3812-LLE**: a new core written by the author of the Nuked cores. it features _extremely_ accurate emulation.
     - this core uses a *lot* of CPU time. may not be suitable for playback!
 
 - **OPL3 core**:
   - **Nuked-OPL3**: high quality OPL emulation core.
   - **ymfm**: this core is supposed to use less CPU than Nuked-OPL3, but for some reason it actually doesn't.
-  - **YMF262-LLE**: a new core written by the author of the Nuked cores. it features extremely accurate emulation.
+  - **YMF262-LLE**: a new core written by the author of the Nuked cores. it features _extremely_ accurate emulation.
     - this core uses even more CPU than YM3812-LLE. not suitable for playback or even rendering if you're impatient!
 
+- **OPL4 core**:
+  - **Nuked-OPL3 (FM) + openMSX (PCM)**: high quality OPL4 emulation core.
+  - **ymfm**: this core is supposed to use less CPU than Nuked-OPL3, but for some reason it actually doesn't.
+
 - **ESFM core**:
   - **ESFMu**: the ESFM emulator. best choice but CPU intensive.
   - **ESFMu (fast)**: this is a modification of ESFMu to reduce CPU usage at the cost of less accuracy.

papers/clipboard-format.md

@@ -6,7 +6,7 @@ when copying pattern data from Furnace, it's stored in the clipboard as plain te
 org.tildearrow.furnace - Pattern Data (144)
 ```
 
-this top line of text is always the same except for the number in parentheses, which is the internal build number. for example, 0.6.5 is `215`.
+this top line of text is always the same except for the number in parentheses, which is the internal build number. for example, 0.6.7 is `219`.
 
 the second line is a number between 0 and 18 (decimal) which indicates which column the clip starts from.
 - `0`: note.

papers/format.md

@@ -32,6 +32,8 @@ these fields are 0 in format versions prior to 100 (0.6pre1).
 
 the format versions are:
 
+- 219: Furnace 0.6.7
+- 218: Furnace 0.6.6
 - 214: Furnace 0.6.5
 - 212: Furnace 0.6.4
 - 201: Furnace 0.6.3
@@ -189,7 +191,7 @@ size | description
      |   - 0x9c: Virtual Boy - 6 channels
      |   - 0x9d: VRC7 - 6 channels
      |   - 0x9e: YM2610B - 16 channels
-     |   - 0x9f: ZX Spectrum (beeper, tildearrow engine) - 6 channels
+     |   - 0x9f: ZX Spectrum (beeper, SFX-like tildearrow engine) - 6 channels
      |   - 0xa0: YM2612 extended - 9 channels
      |   - 0xa1: Konami SCC - 5 channels
      |   - 0xa2: OPL drums (YM3526) - 11 channels
@@ -204,8 +206,8 @@ size | description
      |   - 0xab: MSM6258 - 1 channel
      |   - 0xac: Commander X16 (VERA) - 17 channels
      |   - 0xad: Bubble System WSG - 2 channels
-     |   - 0xae: OPL4 (YMF278B) - 42 channels (UNAVAILABLE)
-     |   - 0xaf: OPL4 drums (YMF278B) - 44 channels (UNAVAILABLE)
+     |   - 0xae: OPL4 (YMF278B) - 42 channels
+     |   - 0xaf: OPL4 drums (YMF278B) - 44 channels
      |   - 0xb0: Seta/Allumer X1-010 - 16 channels
      |   - 0xb1: Ensoniq ES5506 - 32 channels
      |   - 0xb2: Yamaha Y8950 - 10 channels
@@ -256,8 +258,8 @@ size | description
      |   - 0xe0: QSound - 19 channels
      |   - 0xe1: PS1 - 24 channels (UNAVAILABLE)
      |   - 0xe2: C64 (6581) with PCM - 4 channels (UNAVAILABLE)
-     |   - 0xe3: Watara Supervision - 4 channels (UNAVAILABLE)
-     |   - 0xe4: µPD1771C - 1 channel (UNAVAILABLE)
+     |   - 0xe3: Watara Supervision - 4 channels
+     |   - 0xe4: µPD1771C - 1 channel
      |   - 0xf0: SID2 - 3 channels
      |   - 0xf1: 5E01 - 5 channels
      |   - 0xf5: SID3 - 7 channels
@@ -389,7 +391,7 @@ size | description
   1  | reset arp effect phase on new note (>=184)
   1  | linear volume scaling rounds up (>=188)
   1  | legacy "always set volume" behavior (>=191)
-  1  | reserved
+  1  | legacy sample offset effect (>=200)
  --- | **speed pattern of first song** (>=139)
   1  | length of speed pattern (fail if this is lower than 0 or higher than 16)
  16  | speed pattern (this overrides speed 1 and speed 2 settings)
@@ -588,6 +590,7 @@ size | description
      | - 11: 8-bit μ-law PCM
      | - 12: C219 PCM
      | - 13: IMA ADPCM
+     | - 14: 12-bit PCM (MultiPCM)
      | - 16: 16-bit PCM
   1  | loop direction (>=123) or reserved
      | - 0: forward

papers/newIns.md

@@ -158,9 +158,10 @@ the following feature codes are recognized:
 - `EF`: ESFM ins data
 - `PN`: PowerNoise ins data
 - `S2`: SID2 ins data
+- `S3`: SID3 ins data
 - `EN`: end of features
   - if you find this feature code, stop reading the instrument.
-  - it will usually appear only when there sample/wave lists.
+  - it will usually appear only when there are sample/wave lists.
   - instruments in a .fur shall end with this feature code.
 
 # instrument name (NA)
@@ -335,6 +336,8 @@ size | description
      | - bit 12-15: resonance
      | - bit 0-10: cutoff (0-11 on SID2)
   1  | upper nibble of resonance (for SID2) (>=199)
+     | - bits 0-3 hold this upper nibble
+     | - bit 4: reset duty on new note (>=222)
 ```
 
 ## C64 compatibility note (>=187)
@@ -582,6 +585,11 @@ size | description
   1  | LFO rate
   1  | vibrato depth
   1  | AM depth
+  1  | flags (>=221)
+     | - bit 0: damp
+     | - bit 1: pseudo-reverb
+     | - bit 2: LFO reset
+     | - bit 3: level direct
 ```
 
 # Sound Unit data (SU)
@@ -686,3 +694,78 @@ size | description
      | - bit 4-5: wave mix mode
      | - bit 0-3: volume
 ```
+
+# SID3 data (S3)
+
+```
+size | description
+-----|------------------------------------
+  1  | flags 1
+     | - bit 7: dutyIsAbs
+     | - bit 3: noise on
+     | - bit 2: pulse on
+     | - bit 1: saw on
+     | - bit 0: triangle on
+  1  | attack
+  1  | decay
+  1  | sustain
+  1  | sustain rate
+  1  | release
+  1  | wave mix mode
+  2  | duty
+  1  | flags 2
+     | - bit 7: phase modulation
+     | - bit 6: enable special wave
+     | - bit 5: 1-bit noise
+     | - bit 4: separate noise pitch
+     | - bit 3: do wavetable
+     | - bit 2: reset duty on new note
+     | - bit 1: osc sync
+     | - bit 0: ring mod
+  1  | phase modulation source channel
+  1  | ring modulation source channel
+  1  | hard sync source channel
+  1  | special wave
+  1  | flags 3
+     | - bit 1: left channel signal inversion
+     | - bit 0: right channel signal inversion
+  1  | feedback
+  1  | number of filters
+```
+
+then, `number of filters` times, come settings for each filter:
+
+```
+size | description
+-----|------------------------------------
+  1  | parameters
+     | - bit 7: enable filter
+     | - bit 6: initialize filter
+     | - bit 5: absolute cutoff macro
+     | - bit 4: enable cutoff scaling
+     | - bit 3: decrease cutoff when pitch increases (for cutoff scaling)
+     | - bit 2: scale cutoff only once, on new note
+     | - bit 1: enable resonance scaling
+     | - bit 0: decrease resonance when pitch increases (for resonance scaling)
+  1  | parameters
+     | - bit 7: scale resonance only once, on new note
+  2  | filter cutoff
+  1  | filter resonance
+  1  | filter output volume
+  1  | filter distortion level
+  1  | filter mode:
+     | - bit 5: connect filter output to channel master output
+     | - bit 4: connect filter input to channel ADSR output
+     | - bit 2: band pass
+     | - bit 1: high pass
+     | - bit 0: low pass
+  1  | matrix connection:
+     | - bit 3: connect output of filter 4 to input
+     | - bit 2: connect output of filter 3 to input
+     | - bit 1: connect output of filter 2 to input
+     | - bit 0: connect output of filter 1 to input
+  1  | cutoff scaling level
+  1  | cutoff scaling center note: `0` is `c_5`, `1` is `c+5`, ..., `179` is `B-9`
+  1  | resonance scaling level
+  1  | resonance scaling center note: `0` is `c_5`, `1` is `c+5`, ..., `179` is `B-9` 
+```