Merge branch 'master' into sysmgrtooltip_syschaninfo

.github/workflows/build.yml

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

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)
@@ -136,6 +136,7 @@ option(WITH_INSTRUMENTS "Install instruments" ON)
 option(WITH_WAVETABLES "Install wavetables" ON)
 option(SHOW_OPEN_ASSETS_MENU_ENTRY "Show option to open built-in assets directory (on supported platforms)" OFF)
 option(CONSOLE_SUBSYSTEM "Build Furnace with Console subsystem on Windows" OFF)
+option(FLATPAK_WORKAROUNDS "Enable Flatpak-specific workaround for system file picker" OFF)
 if (APPLE)
   option(FORCE_APPLE_BIN "Force enable binary installation to /bin" OFF)
   option(MAKE_BUNDLE "Make a bundle" OFF)
@@ -159,6 +160,10 @@ if (IS_BIG_ENDIAN)
   list(APPEND DEPENDENCIES_DEFINES "TA_BIG_ENDIAN")
 endif()
 
+if (FLATPAK_WORKAROUNDS)
+  list(APPEND DEPENDENCIES_DEFINES "FLATPAK_WORKAROUNDS")
+endif()
+
 set(DEPENDENCIES_COMPILE_OPTIONS "")
 set(DEPENDENCIES_LIBRARIES "")
 set(DEPENDENCIES_LIBRARY_DIRS "")
@@ -552,6 +557,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 +650,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 +675,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
@@ -717,8 +729,6 @@ src/engine/wavetable.cpp
 src/engine/waveSynth.cpp
 src/engine/wavOps.cpp
 src/engine/vgmOps.cpp
-src/engine/zsmOps.cpp
-src/engine/zsm.cpp
 
 src/engine/platform/abstract.cpp
 src/engine/platform/genesis.cpp
@@ -779,6 +789,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
@@ -791,12 +803,15 @@ 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
 
 src/engine/export/abstract.cpp
 src/engine/export/amigaValidation.cpp
+src/engine/export/sapr.cpp
 src/engine/export/tiuna.cpp
+src/engine/export/zsm.cpp
 
 src/engine/effect/abstract.cpp
 src/engine/effect/dummy.cpp

README.md

@@ -4,7 +4,7 @@
 
 the biggest multi-system chiptune tracker ever made!
 
-[downloads](#downloads) | [discussion/help](#quick-references) | [developer info](#developer-info) | [Unix/Linux packages](#packages) | [FAQ](#frequently-asked-questions)
+[downloads](#downloads) | [discussion/help](#quick-references) | [developer info](#developer-info) | [Unix/Linux packages](#packages)
 
 ---
 ## downloads
@@ -36,7 +36,7 @@ for other operating systems, you may [build the source](#developer-info).
     - AY-3-8910/YM2149(F) used in several computers and game consoles
     - Commodore VIC used in the VIC-20
     - Microchip AY8930
-    - TI SN76489 used in Sega Master System and BBC Micro
+    - TI SN76489 used in Sega Master System, BBC Micro, and many others
     - PC Speaker
     - Philips SAA1099 used in SAM Coupé
     - OKI MSM5232 used in some arcade boards
@@ -98,7 +98,7 @@ for other operating systems, you may [build the source](#developer-info).
     - Generic PCM DAC
 - mix and match sound chips!
   - over 200 ready to use presets from computers, game consoles and arcade boards...
-  - ...or create your own - up to 32 of them or a total of 128 channels!
+  - ...or create your own presets - up to 32 chips or a total of 128 channels!
 - DefleMask compatibility
   - loads .dmf modules from all versions (beta 1 to 1.1.9)
   - saves .dmf modules - both modern and legacy
@@ -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)
@@ -137,8 +138,8 @@ for other operating systems, you may [build the source](#developer-info).
 ---
 # quick references
 
-- **discussion**: see the [Discussions](https://github.com/tildearrow/furnace/discussions) section.
-- **help**: check out the [documentation](doc/README.md).
+- **help**: check out the [documentation](doc/README.md), [quick start guide](doc/1-intro/quickstart.md), and [frequently asked questions (FAQ)](doc/1-intro/faq.md).
+- **discussion**: see the [Discussions](https://github.com/tildearrow/furnace/discussions) section, or the [Discord](https://discord.gg/QhA26dXD23).
 
 ## packages
 
@@ -330,73 +331,7 @@ this will play a compatible file and enable the commands view.
 **note that console mode may not work correctly on Windows. you may have to quit using the Task Manager.**
 
 ---
-# frequently asked questions
 
-> where's the manual?
-
-it is in [doc/](doc/README.md).
-
-> is there a tutorial?
-
-[a video tutorial of tracker concepts is available on YouTube](https://www.youtube.com/watch?v=Q37XuOLz0jw). thanks Button Masher!
-
-> can I import VGM or NSF?
-
-nope. it's a feature that's been requested many times, but I don't have plans to implement that yet.
-
-for NSF import, you can use [a modified version of FamiTracker called NSFImport](http://rainwarrior.ca/projects/nes/nsfimport.html), and then import the resulting .ftm into Furnace.
-it's all speed 1 though, so don't expect any songs to be nicely laid out with instruments and all.
-
-> how about MIDI? can I import these?
-
-nope. it's not implemented.
-
-also, Furnace isn't a MIDI tracker.
-
-> it doesn't open under macOS!
-
-this is due to Apple's application signing policy. a workaround is to right click on the Furnace app icon and select Open.
-
-> it says "Furnace" is damaged and can't be opened!
-
-**as of Monterey, this workaround no longer works (especially on ARM).** yeah, Apple has decided to be strict on the matter.
-if you happen to be on that version (or later), use this workaround instead (on a Terminal):
-
-```
-xattr -d com.apple.quarantine /path/to/Furnace.app
-```
-
-(replace /path/to/ with the path where Furnace.app is located)
-
-you may need to log out and/or reboot after doing this.
-
-> I've lost my song!
-
-Furnace keeps backups of the songs you've worked on before. go to **file > restore backup**.
-
-> .spc export?
-
-**not yet!** coming in 0.7 though, eventually...
-
-> ROM export?
-
-**not yet!** coming in 0.7 though, eventually...
-
-> Roland MT-32 support?
-
-MT-32 is used with MIDI in 99.999% of situations. it lacks a direct register interface.
-
-also, Furnace is not a MIDI tracker....
-
-> my .dmf song sounds odd at a certain point
-
-Furnace's .dmf compatibility isn't perfect and it's mostly because DefleMask does things different.
-
-> my song sounds terrible after saving as .dmf!
-
-you should only save as .dmf if you're really sure, because the DefleMask format has several limitations. save in Furnace song format instead (.fur).
-
----
 # footnotes
 
 copyright (C) 2021-2024 tildearrow and contributors.

TODO.md

@@ -1,3 +1,7 @@
+# to-do for 0.6.8
+
+- OPL3 mute fix
+
 # to-do long term
 
 - CSM macros

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/README.md

@@ -29,3 +29,7 @@ once familiar with the tracker, look to [9-guides](../9-guides/README.md) for us
 [How to Learn Chiptune Trackers](https://www.youtube.com/watch?v=Q37XuOLz0jw): video tutorial created by Button Masher. covers the basic mechanics of chiptune tracking using Furnace for demonstration.
 
 [Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves. be noted that these may not apply to the current version.
+
+## for more information
+
+see the [frequently asked questions](faq.md).

doc/1-intro/faq.md

@@ -0,0 +1,130 @@
+# frequently asked questions
+
+## general
+
+### how do I use Furnace?
+
+the [quick start guide](quickstart.md) and [concepts list](concepts.md) are great first steps in getting used to the tracker way. after that, try exploring the demo songs to learn more about how to get the sounds you want.
+
+### is there an Android build?
+
+yes and no. Furnace can be successfully built for Android and it even has some rudimentary touch UI support, but it's extremely unfinished and extremely unsupported. there are many good reasons that it's not in the official releases yet.
+
+### is there an iOS build?
+
+nope.
+
+### will Furnace ever have a piano roll or DAW interface?
+
+there are no plans for this.
+
+### I've lost my song – what do I do?
+
+Furnace keeps backups of the songs you've worked on before. go to **file > restore backup**.
+
+## workflow
+
+### how do I compose in 6/8, 5/4, or other time signatures?
+
+set the pattern length to a multiple of the number of beats (6 or 5 as mentioned above). don't forget to change the row highlight values to match!
+
+### how do I do triplets, quintuplets, or other tuplets?
+
+there are two common methods:
+- use delay commands (`EDxx`) to offset notes into their correct places. this is good for the occasional set of tuplets, but if you expect to use a lot of them...
+- plan ahead for the song to have them by making your pattern length a multiple of that number. remember to adjust row highlight values to match.
+
+depending on the tempo of the song, it may only be possible to get perfectly even tuplets by changing the tick rate. mind that this may hinder playback in games or sound engines that use the vertical blank interval for their timing.
+
+### why do certain notes not play low enough, high enough, or in tune?
+
+each chip has its own set of limitations regarding what frequencies it can play. if these limits are likely to be found in normal tracking, they'll be mentioned in [that chip's documentation](../7-systems/).
+
+### can I add effects to the output like EQ or reverb?
+
+not yet, but it's in the early development stage.
+
+## chips
+
+### will Furnace support the Sony PlayStation?
+
+it's in the plans, with no target date.
+
+### will Furnace support the Sega Saturn?
+
+it also is in the plans, with no target date.
+
+### will Furnace support the Nintendo 64?
+
+the N64 lacks any form of audio synthesizer chip. many games use MIDI or XM or other such formats internally, but everything is mixed in software and sent to a simple stereo DAC.
+
+### will Furnace support this obscure PCM-only chip?
+
+probably not, as with very few exceptions these are effectively all the same.
+
+### will Furnace support the Roland MT-32?
+
+no. MT-32 is used with MIDI in 99.999% of situations. it lacks a direct register interface.
+
+also, Furnace is not a MIDI tracker....
+
+## importing
+
+### will Furnace import MIDI files?
+
+nope. Furnace is not a MIDI tracker.
+
+### why does this imported file sound wrong?
+
+There are fundamental differences between formats that cannot be directly translated. an import should always be considered the starting point of a conversion, not a final product.
+
+### can I import VGM or NSF?
+
+nope. it's a feature that's been requested many times, but there are no plans to implement it.
+
+for NSF import, you can use [a modified version of FamiTracker called NSFImport](http://rainwarrior.ca/projects/nes/nsfimport.html) and then import the resulting .ftm into Furnace.
+it's all speed 1 though, so don't expect any songs to be nicely laid out with instruments and all.
+
+### how can I use an SF2 soundfont?
+
+one way is to use [OpenMPT](https://openmpt.org/) to open the SF2 file, and save WAV files from there. [Polyphone](https://www.polyphone.io/) is another way.
+
+### how do I import instruments from this SNES game?
+
+use [split700](https://github.com/gocha/split700) to extract the BRR samples from an SPC. there is presently no way to import envelopes or other parameters.
+
+### how do I import instruments from this Sega Genesis game?
+
+extract FM patches from a VGM file using [vgm2pre](https://github.com/vgmtool/vgm2pre) or similar tool. bear in mind that these are only the parameters for the FM synth, and the way the instrument is heard in-game may include pitch bends or other effects that can't be extracted.
+
+for PSG instruments, see the next question.
+
+### how do I import instruments from this NES/SMS/GB/C64/etc. game?
+
+PSG chips (such as those in the systems mentioned) don't have any inherent concept of instruments or patches. all of that is handled in software, and each sound driver has its own way of doing things. generally, the only option is to recreate the instrument from scratch.
+
+## exporting
+
+### will Furnace export MIDI files?
+
+nope. Furnace is not a MIDI tracker.
+
+### why does this exported VGM sound weird when I play it in other software?
+
+just as Furnace offers a choice of emulation cores, VGM players may use different cores with varying degrees of accuracy. also, some aspects of a song may not be supported by the VGM format, such as chip clock speeds.
+
+### why does this exported DMF sound wrong in DefleMask?
+
+while Furnace did start life as a DMF player, it's grown in functionality quite a bit, and many Furnace features simply don't exist in that format. there are also cases where the emulation cores in DefleMask sound different from those available in Furnace.
+
+### when will Furnace be able to export to a ROM for a particular system or an emulated music format?
+
+each system will need its own method of converting Furnace songs into code that can be played back on hardware. this requires writing a driver for the hardware in question, which is no small task. that having been said, there are several efforts in progress, both for direct export from Furnace itself and external converters such as [furSPC](https://github.com/AnnoyedArt1256/furSPC), [furNES](https://github.com/AnnoyedArt1256/furNES), and [furC64](https://github.com/AnnoyedArt1256/furC64).
+
+### can Furnace export MP3/OGG/FLAC files?
+
+not presently. for now, use an external converter such as FFmpeg.
+
+## other
+
+if a question isn't answered within this manual, check in the [GitHub Discussions](https://github.com/tildearrow/furnace/discussions) to see if it's answered there, and post if needed.

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).
@@ -27,9 +29,9 @@
 - changing this may change aspects of how some chips work, most notably pitch.
 - some chips cannot operate at anything other than their designed clock rate.
 
-**cursor (1)**: the marker of input focus. anything typed will happen at the cursor's location.
+**cursor** (1): the marker of input focus. anything typed will happen at the cursor's location.
 
-**cursor (2)**: the pointer controlled by a mouse or similar input. clicking when the cursor(2) is in a valid area will place the cursor(1) there.
+**cursor** (2): the pointer controlled by a mouse or similar input. clicking when the cursor(2) is in a valid area will place the cursor(1) there.
 
 **DAC**: digital analog converter. this converts a digital representation of sound into actual output.
 
@@ -59,7 +61,7 @@
 
 **.fuw**: a Furnace wavetable file.
 
-**hard-pan**: sounds can only be panned all the way to one side or the other, not in-between.
+**hard-pan**: sounds can only be panned to the center, 100% left, or 100% right. this often appears in the instrument editor's panning macro as on/off toggles for the left and right channels.
 
 **Hz**: hertz. a unit representing divisions of one second. 1 Hz means once per second; 100 Hz means one hundred times per second. also, _kHz_ (kilohertz, one thousand per second) and _MHz_ (megahertz, one million per second).
 
@@ -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/1-intro/hex.md

@@ -2,44 +2,40 @@
 
 the hexadecimal numeral system differs from the decimal system by having 16 digits rather than 10:
 
-```
-hex| decimal
----|---------
- 0 | 0
- 1 | 1
- 2 | 2
- 3 | 3
- 4 | 4
- 5 | 5
- 6 | 6
- 7 | 7
- 8 | 8
- 9 | 9
- A | 10
- B | 11
- C | 12
- D | 13
- E | 14
- F | 15
-```
+hex | dec
+:--:|---:
+`0` | 0
+`1` | 1
+`2` | 2
+`3` | 3
+`4` | 4
+`5` | 5
+`6` | 6
+`7` | 7
+`8` | 8
+`9` | 9
+`A` | 10
+`B` | 11
+`C` | 12
+`D` | 13
+`E` | 14
+`F` | 15
 
 when there is more than one digit, these are multiplied by 16, 256, 4096 and so on rather than 10, 100, 1000:
 
-```
-hex | decimal
-----|---------
- 00 | 0
- 04 | 4
- 08 | 8
- 0F | 15
- 10 | 16
- 11 | 17
- 12 | 18
- 13 | 19
- 20 | 32
- 30 | 48
- 40 | 64
-```
+ hex | dec
+:---:|---:
+`00` | 0
+`04` | 4
+`08` | 8
+`0F` | 15
+`10` | 16
+`11` | 17
+`12` | 18
+`13` | 19
+`20` | 32
+`30` | 48
+`40` | 64
 
 ## hex to decimal
 
@@ -101,7 +97,7 @@ now for decimal number `69420`:
 a bitmask is a value that actually represents a set of individual binary bits to be toggled, some of which may be grouped to form small binary numbers. these are used by adding up the value of each bit and converting the result to hex. in macros, these are shown in decimal.
 
 bit   |   binary    | decimal
-:-----|:-----------:|--------:
+:----:|:-----------:|--------:
 bit 7 | `1000 0000` | 128
 bit 6 | `0100 0000` |  64
 bit 5 | `0010 0000` |  32
@@ -113,16 +109,16 @@ bit 0 | `0000 0001` |   1
 
 for example, to turn bits 7 and 5 on, and put `110` (decimal 6) in bits 1 to 3:
 
-```
-bit 7 = `1... ....` = 128
-bit 6 = `.0.. ....` =   0
-bit 5 = `..1. ....` =  32
-bit 4 = `...0 ....` =   0
-bit 3 = `.... 1...` =   8
-bit 2 = `.... .1..` =   4
-bit 1 = `.... ..0.` =   0
-bit 0 = `.... ...0` =   0
-``````
+bit   |   binary    | decimal
+:----:|:-----------:|--------:
+bit 7 | `1... ....` | 128
+bit 6 | `.0.. ....` |   0
+bit 5 | `..1. ....` |  32
+bit 4 | `...0 ....` |   0
+bit 3 | `.... 1...` |   8
+bit 2 | `.... .1..` |   4
+bit 1 | `.... ..0.` |   0
+bit 0 | `.... ...0` |   0
 
 added together, the resulting binary is `1010 1100`, which converts to hex as `AC` and to decimal as 172.
 

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

@@ -81,8 +81,6 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
   - **Full (short when loading song)**: shows animated musical intro unless started with a song (command line, double-clicking a .fur file, etc.)
   - **Full (always)**: always shows animated musical intro.
 - **Disable fade-in during start-up**
-- **About screen party time**
-  - _warning:_ may cause epileptic seizures.
 
 ### Behavior
 
@@ -93,6 +91,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
@@ -292,9 +294,14 @@ below all the binds, select a key from the dropdown list to add it. it will appe
   - **Yes**: allow drag-and-drop.
   - **Yes (while holding Ctrl only)**: allow drag-and-drop but only when holding Control (Command on macOS).
 - **Toggle channel solo on:** selects which interactions with a channel header will toggle solo for that channel.
-  - Right-click or double click
-  - Right-click
-  - Double-click
+  - **Right-click or double click**
+  - **Right-click**
+  - **Double-click**
+- **Modifier for alternate wheel-scrolling (vertical/zoom/slider-input)**: selects which key to hold for alternate scrolling of interface elements that support it.
+  - **Ctrl or Meta/Cmd**
+  - **Ctrl**
+  - **Meta/Cmd**
+  - **Alt**
 - **Double click selects entire column**: when enabled, double clicking on a cell of the pattern will select the entire column.
 
 ### Cursor behavior
@@ -484,7 +491,7 @@ below all the binds, select a key from the dropdown list to add it. it will appe
 
 - **Unified instrument/wavetable/sample list**: combines all three types of assets into one list.
   - the buttons act as appropriate to the currently selected asset or header.
-- **Horizontal instrument list**: when there are more instruments than there is room to display them...
+- **Horizontal instrument/wavetable list**: when there are more instruments/wavetables than there is room to display them...
   - if on, scroll horizontally through multiple columns.
   - if off, scroll vertically in one long column.
   - only appears if "Unified instrument/wavetable/sample list" is off.
@@ -501,6 +508,10 @@ 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**
+- **Macro step size/horizontal zoom:**
+  - **Manual**
+  - **Automatic per macro**
+  - **Automatic (use longest macro)**
 
 ### Wave Editor
 
@@ -524,6 +535,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.
@@ -191,12 +198,12 @@ 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 |          |            |
+ 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   |          |               |
@@ -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/k007232.md

@@ -1,6 +1,6 @@
 # Konami K007232 instrument editor
 
-the K007232 instrument editor contains three tabs: Sample and Macros.
+the K007232 instrument editor contains two tabs: Sample and Macros.
 
 ## Sample
 

doc/4-instrument/k053260.md

@@ -1,6 +1,6 @@
 # K053260 instrument editor
 
-the K053260 instrument editor contains three tabs: Sample and Macros.
+the K053260 instrument editor contains two tabs: Sample and Macros.
 
 ## Sample
 

doc/4-instrument/multipcm.md

@@ -0,0 +1,37 @@
+# MultiPCM instrument editor
+
+the MultiPCM instrument editor contains three tabs: Sample, MultiPCM and Macros.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+## MultiPCM
+
+MultiPCM contains an ADSR envelope, not unlike Yamaha OPN/OPM envelpes, and simple LFO, also similiar to that found in OPN.
+you may use this tab to set up ES5506-specific parameters:
+
+- **AR**: sets attack rate.
+- **D1R**: sets Decay 1 rate.
+- **DL**: sets Decay Level (analogue of Sustain Level on OPN chips).
+- **D2R**: sets Decay 2 rate (a.k.a. SR, Sustain Rate).
+- **RR**: sets release rate.
+- **LFO rate**: sets speed of LFO.
+- **PM Depth**: sets depth of LFO vibrato.
+- **AM Depth**: sets depth of LFO tremolo/amplitude modulation.
+- **Damp**: enforce quickly fading out the sample over 11 ms.
+- **Pseudo Reverb**: enables reverb-like effect.
+- **LFO Reset**: disables and resets LFO.
+- **Disable volume change ramp**: if set to "on", volume change interpolation is disabled.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Filter Mode**: sets filter mode.
+- **Panning**: output level for left and right channels (from -3 to +3).
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.
+- **LFO Speed**: sequence of LFO speeds.
+- **LFO Vib depth**: LFO vibrato sequence.
+- **LFO Vib depth**: LFO tremolo sequence.

doc/4-instrument/psg.md

@@ -1,6 +1,6 @@
 # Sega PSG instrument editor
 
-the instrument editor for Sega PSG (SMS, and other TI SN76489 derivatives) consists of these macros:
+the instrument editor for Sega PSG, SMS, and other TI SN76489 derivatives consists of these macros:
 
 - **Volume**: volume sequence.
 - **Arpeggio**: pitch sequence.

doc/4-instrument/rf5c68.md

@@ -1,6 +1,6 @@
 # Ricoh RF5C68 instrument editor
 
-the RF5C68 instrument editor contains three tabs: Sample and Macros.
+the RF5C68 instrument editor contains two tabs: Sample and Macros.
 
 ## Sample
 

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/4-instrument/watarasv.md

@@ -0,0 +1,17 @@
+# Watara Supervision instrument editor
+
+the Watara Supervision instrument editor consists of two tabs: one controlling sample channel assignments and macro tab containing several macros.
+
+## Sample
+
+for sample settings, see the the [Sample instrument editor](sample.md).
+
+the only differences are the lack of a "Use wavetable" option, and the presence of a "Use sample" one.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty/Noise**: pulse wave duty cycle or noise mode sequence.
+- **Noise/PCM Pan**: output for left and right channels for noise and PCM channels.
+- **Pitch**: fine pitch.

doc/6-sample/README.md

@@ -61,7 +61,7 @@ if you need to use more samples, you may change the sample bank using effect `EB
 due to limitations in some of those sound chips, some restrictions exist:
 
 - Amiga: maximum frequency is 31469Hz, but anything over 28867 will sound glitchy on hardware. sample lengths and loop will be set to an even number, and your sample can't be longer than 131070.
-- NES: if on DPCM mode, only a limited selection of frequencies is available, and loop position isn't supported (only entire sample).
+- NES: if on DPCM mode, only a limited selection of frequencies is available.
 - SegaPCM: your sample can't be longer than 65535, and the maximum frequency is 31.25KHz.
 - QSound: your sample can't be longer than 65535, and the loop length shall not be greater than 32767.
 - ADPCM-A: no looping supported. your samples will play at around 18.518KHz.

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/genesis.md

@@ -1,65 +0,0 @@
-# Sega Genesis/Mega Drive
-
-a video game console that showed itself as the first true rival to Nintendo's video game market near-monopoly in the US during the '80s.
-
-this console is powered by two sound chips: the [Yamaha YM2612](ym2612.md) and [a derivative of the SN76489](sms.md).
-
-## effects
-
-- `10xy`: **set LFO parameters.**
-  - `x` toggles the LFO.
-  - `y` sets its speed.
-- `11xx`: **set feedback of channel.**
-- `12xx`: **set operator 1 level.**
-- `13xx`: **set operator 2 level.**
-- `14xx`: **set operator 3 level.**
-- `15xx`: **set operator 4 level.**
-- `16xy`: **set multiplier of operator.**
-  - `x` is the operator (1-4).
-  - `y` is the new MULT value..
-- `17xx`: **enable PCM channel.**
-  - this only works on channel 6.
-  - _this effect is here for compatibility reasons!_ it is otherwise recommended to use Sample type instruments (which automatically enable PCM mode when used).
-- `18xx`: **toggle extended channel 3 mode.**
-  - `0` disables it and `1` enables it.
-  - only in extended channel 3 chip.
-- `19xx`: **set attack of all operators.**
-- `1Axx`: **set attack of operator 1.**
-- `1Bxx`: **set attack of operator 2.**
-- `1Cxx`: **set attack of operator 3.**
-- `1Dxx`: **set attack of operator 4.**
-- `20xy`: **set PSG noise mode.**
-  - `x` controls whether to inherit frequency from PSG channel 3.
-    - `0`: use one of 3 preset frequencies (`C`: A-2; `C#`: A-3; `D`: A-4).
-    - `1`: use frequency of PSG channel 3.
-  - `y` controls whether to select noise or thin pulse.
-    - `0`: thin pulse.
-    - `1`: noise.
-
-
-
-## system modes
-
-## 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 2-op 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
-
-[info here.](ym2612.md)
-
-## Sega CD
-
-this isn't a mode so much as a chip configuration. it adds the [Ricoh RF5C68](ricoh.md) found in the Sega CD add-on, providing 8 channels of PCM.
-
-## chip config
-
-see [YM2612](ym2612.md) and [SN76489](sms.md) for respective configuration.

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/opl.md

@@ -7,11 +7,15 @@ however, it also had a [drums mode](opll.md), and later chips in the series adde
 
 the original OPL (Yamaha YM3526) was present as an expansion for the Commodore 64 and MSX computers (erm, a variant of it). it only had 9 two-operator channels and drums mode.
 
+Y8950 is essentially the same chip, but with one additional channel for ADPCM sample playback, behaving in a similar way as the one found in YM2608.
+
 its successor, the OPL2 (Yamaha YM3812), added 3 more waveforms and was one of the more popular chips because it was present on the AdLib card for PC.
 later Creative would borrow the chip to make the Sound Blaster, and totally destroyed AdLib's dominance.
 
 the OPL3 (Yamaha YMF262) added 9 more channels, 4 more waveforms, rudimentary 4-operator mode (pairing up to 12 channels to make up to six 4-operator channels), quadraphonic output and some other things.
 
+the OPL4 (Yamaha YMF278) retains the FM block from OPL3, but adds 24 sample channels on top! samples are 44100 Hz, can be between 8, 12 or 16-bit, stereo (with 16 different levels) and can read PCM data from ROM or SRAM (up to 4 MB).
+
 afterwards everyone moved to Windows and software mixed PCM streaming...
 
 ## effects
@@ -24,9 +28,9 @@ afterwards everyone moved to Windows and software mixed PCM streaming...
 - `12xx`: **set operator 1 level.**
 - `13xx`: **set operator 2 level.**
 - `14xx`: **set operator 3 level.**
-  - only in 4-op mode (OPL3).
+  - only in 4-op mode (OPL3 and OPL4).
 - `15xx`: **set operator 4 level.**
-  - only in 4-op mode (OPL3).
+  - only in 4-op mode (OPL3 and OPL4).
 - `16xy`: **set multiplier of operator.**
   - `x` is the operator (1-4; last 2 operators only in 4-op mode).
   - `y` is the new MULT value..
@@ -81,7 +85,7 @@ afterwards everyone moved to Windows and software mixed PCM streaming...
 
 ## info
 
-this chip uses the [FM (OPL)](../4-instrument/fm-opl.md) instrument editor.
+these chips use the [FM (OPL)](../4-instrument/fm-opl.md) instrument editor. Y8950 ADPCM uses [Generic Sample](../4-instrument/sample.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
 
 when two channels are joined for 4-op mode, the channel bar will show `4OP` on a bracket tying them together.
 
@@ -95,3 +99,7 @@ additionally, in OPL3:
 
 - **Chip type**: sets the chip model. OPL3-L uses resampling.
 - **Compatible panning**: for compatibility with old Furnace.
+
+additionally, in OPL4:
+
+- **RAM Size**: sets the RAM size for sample storage

doc/7-systems/pokey.md

@@ -44,6 +44,10 @@ when two channels are joined for filtered output, the channel bar will show `fil
 
 when two channels are joined for wide period range, the channel bar will show `16-bit` on a bracket tying them together.
 
+## ROM export
+
+a song can be exported as SAP-R, a compressed register dump. more details on the format are available (in Polish) at [its page on the Atariki wiki](http://atariki.krap.pl/index.php/SAP_%28format_pliku%29).
+
 ## chip config
 
 the following options are available in the Chip Manager window:

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 a 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,125 @@
+# SID3
+
+a fictional chip created by LTVA. the idea is to stay vaguely in the [SID](c64.md)-like category of chips, but add a lot of features and more channels.
+
+the 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 a feedback bit. some feedback bits' configurations produce very short looped noise which is perceived as tone. see the [SID3 instrument description](../4-instrument/sid3.md) for notable feedback bit 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 an accumulator on the next step before computing the 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 at 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. this option affects the chip only in playback mode. when rendering a module into an audio file, this 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/watarasv.md

@@ -0,0 +1,23 @@
+# Watara Supervision
+
+a failed competitor of Game Boy, straight from Taiwan. released in 1992, it had a tilting screen, $50 price tag, very fast 4 MHz 6502-like CPU, framebuffer graphics and sound capabilities similia to Game Boy.
+
+these are 2 pulse wave channels (same as on GB), barely working PCM channel and noise channel, also not unlike Game Boy. no hardware envelopes or zombie mode, though
+## effects
+
+- `12xx`: **set duty cycle/noise mode.**
+  - range is `0` to `3 ` for pulses and `0` to `1` for noise.
+## info
+
+this chip uses the [Watara Supervision](../4-instrument/vatarasv.md) and [Generic Sample](../4-instrument/sample.md) instrument editors.
+
+### sample info
+
+sample channel is 4-bit DMA channel with 4 frequencies assigned to sample octaves (C2, C3, C4, C5; C, C#, D, D# in furnace respectively). max sample size is 4 kilobytes (8192 samples).
+
+## chip config
+
+the following options are available in the Chip Manager window:
+
+- **Swap noise duty cycles**: enabled by default. when enabled, short noise is on odd-indexed duty cycles, like on Game Boy, rather than even.
+- **Stereo pulse waves**: disabled by default. when enabled, it forces pulse channel 1 to the right output channel and second pulse to the left output channel.

doc/7-systems/ym2151.md

@@ -68,6 +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.**
+- `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,6 +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.**
+- `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
 
@@ -106,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,6 +99,17 @@ 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.**
+- `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 +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), [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,6 +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.**
+- `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
 
@@ -104,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,6 +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.**
+- `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
 
@@ -103,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,11 +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.**
+- `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: