GUI: fix sample preview needle visible when switch

ing samples

.gitattributes

@@ -0,0 +1 @@
+*.sfd text

.github/issue_template.md

@@ -1 +1,39 @@
-<!-- NOTICE: if you are going to write a suggestion, see the Discussions section instead. any suggestions posted in Issues will be closed. -->
+# IMPORTANT NOTICE
+
+1. this section is exclusively for ISSUES related to Furnace (bugs, major annoyances and others).
+2. this section is NOT for Suggestions, Questions, Showcase or any other Discussions that do not meet the criteria and definition of an ISSUE.
+  - see the Discussions section if you wish to submit these.
+3. check whether your issue has been reported already.
+  - go to the Issues section, and use the search bar that appears on top of the Issues list.
+4. include the following information:
+  - version of Furnace (help > about)
+  - operating system (and version)
+  - whether you have downloaded Furnace, or built it from source.
+5. provide these details if you believe the issue is operating system and/or computer-specific:
+  - CPU model
+    - Windows: go to Control Panel > System.
+    - macOS: go to the Apple menu and select About This Mac...
+    - Linux: use `lscpu` or `cat /proc/cpuinfo`.
+  - graphics card (and driver version)
+    - Windows: open `dxdiag` and observe the Render tab.
+    - macOS: go to the Apple menu and select About This Mac...
+      - this information is not always shown.
+      - this information is not necessary if you use an Apple silicon Mac.
+    - Linux: use `glxinfo | grep OpenGL`.
+6. if your issue is an abnormal program termination (a "Crash"), you must provide additional details:
+  - the furnace_crash.txt file that is created by Furnace after a Crash. this file is located in the following paths:
+    - Windows: `C:\Users\<username>\furnace_crash.txt`
+    - Linux/other: `/tmp/furnace_crash.txt`
+    - on macOS this file is not generated. you may retrieve information about the Crash by clicking on "Report..." or "Show Details" in the "quit unexpectedly" dialog that appears following the Crash.
+      - make sure to remove any personal information for privacy reasons.
+      - be sure to select "Don't Send" afterwards.
+  - the furnace.log file located in:
+    - Windows: `C:\Users\<username>\AppData\Roaming\furnace\furnace.log`
+    - macOS: `~/Library/Application Support/furnace/furnace.log`
+    - Linux: `~/.config/furnace/furnace.log`
+    - make sure to remove any personal information for privacy reasons.
+
+BY SUBMITTING A TICKET, YOU HEREBY AGREE TO COMPLY WITH THESE TERMS.
+FAILURE TO DO SO MAY RESULT IN YOUR TICKET BEING DECLARED VOID.
+
+***END OF NOTICE*** --- REMOVE THIS NOTICE AFTER READING!

.gitignore

@@ -6,6 +6,7 @@ release/
 t/
 winbuild/
 win32build/
+xpbuild/
 macbuild/
 linuxbuild/
 *.swp
@@ -26,3 +27,5 @@ CMakePresets.json
 extern/imgui_patched/examples/
 src/asm/68k/amigatest/*.bin
 src/asm/68k/amigatest/player
+res/binary_to_compressed_c
+res/binary_to_compressed_c.exe

.gitmodules

@@ -12,3 +12,6 @@
 [submodule "extern/adpcm"]
 	path = extern/adpcm
 	url = https://github.com/superctr/adpcm
+[submodule "extern/portaudio"]
+	path = extern/portaudio
+	url = https://github.com/PortAudio/portaudio.git

CMakeLists.txt

@@ -27,6 +27,7 @@ include(TestBigEndian)
 
 if (ANDROID)
   set(USE_RTMIDI_DEFAULT OFF)
+  set(WITH_PORTAUDIO_DEFAULT OFF)
   set(USE_BACKWARD_DEFAULT OFF)
   find_library(TERMUX rt)
   if (TERMUX)
@@ -34,6 +35,7 @@ if (ANDROID)
   endif()
 else()
   set(USE_RTMIDI_DEFAULT ON)
+  set(WITH_PORTAUDIO_DEFAULT ON)
   if (WIN32 OR APPLE)
     set(USE_BACKWARD_DEFAULT ON)
   else()
@@ -78,6 +80,7 @@ option(USE_SDL2 "Build with SDL2. Required to build with GUI." ${USE_SDL2_DEFAUL
 option(USE_SNDFILE "Build with libsndfile. Required in order to work with audio files." ${USE_SNDFILE_DEFAULT})
 option(USE_BACKWARD "Use backward-cpp to print a backtrace on crash/abort." ${USE_BACKWARD_DEFAULT})
 option(WITH_JACK "Whether to build with JACK support. Auto-detects if JACK is available" ${WITH_JACK_DEFAULT})
+option(WITH_PORTAUDIO "Whether to build with PortAudio for audio output." ${WITH_PORTAUDIO_DEFAULT})
 option(WITH_RENDER_SDL "Whether to build with the SDL_Renderer render backend." ${WITH_RENDER_SDL_DEFAULT})
 option(WITH_RENDER_OPENGL "Whether to build with the OpenGL render backend." ${WITH_RENDER_OPENGL_DEFAULT})
 option(WITH_RENDER_DX11 "Whether to build with the DirectX 11 render backend." ${WITH_RENDER_DX11_DEFAULT})
@@ -85,6 +88,7 @@ option(USE_GLES "Use OpenGL ES for the OpenGL render backend." ${USE_GLES_DEFAUL
 option(SYSTEM_FFTW "Use a system-installed version of FFTW instead of the vendored one" OFF)
 option(SYSTEM_FMT "Use a system-installed version of fmt instead of the vendored one" OFF)
 option(SYSTEM_LIBSNDFILE "Use a system-installed version of libsndfile instead of the vendored one" OFF)
+option(SYSTEM_PORTAUDIO "Use a system-installed version of PortAudio instead of the vendored one" OFF)
 option(SYSTEM_RTMIDI "Use a system-installed version of RtMidi instead of the vendored one" OFF)
 option(SYSTEM_ZLIB "Use a system-installed version of zlib instead of the vendored one" OFF)
 option(SYSTEM_SDL2 "Use a system-installed version of SDL2 instead of the vendored one" ${SYSTEM_SDL2_DEFAULT})
@@ -204,6 +208,27 @@ else()
   message(STATUS "Not using libsndfile")
 endif()
 
+if (WITH_PORTAUDIO)
+  if (SYSTEM_PORTAUDIO)
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(PORTAUDIO REQUIRED portaudio)
+    list(APPEND DEPENDENCIES_INCLUDE_DIRS ${PORTAUDIO_INCLUDE_DIRS})
+    list(APPEND DEPENDENCIES_COMPILE_OPTIONS ${PORTAUDIO_CFLAGS_OTHER})
+    list(APPEND DEPENDENCIES_LIBRARIES ${PORTAUDIO_LIBRARIES})
+    list(APPEND DEPENDENCIES_LIBRARY_DIRS ${PORTAUDIO_LIBRARY_DIRS})
+    list(APPEND DEPENDENCIES_LINK_OPTIONS ${PORTAUDIO_LDFLAGS_OTHER})
+    list(APPEND DEPENDENCIES_LEGACY_LDFLAGS ${PORTAUDIO_LDFLAGS})
+    message(STATUS "Using system-installed PortAudio")
+  else()
+    set(PA_BUILD_SHARED_LIBS OFF CACHE BOOL "Build dynamic library" FORCE)
+    # don't - Furnace has its own implementation
+    set(PA_USE_JACK OFF CACHE BOOL "Enable support for JACK Audio Connection Kit" FORCE)
+    add_subdirectory(extern/portaudio EXCLUDE_FROM_ALL)
+    list(APPEND DEPENDENCIES_LIBRARIES PortAudio)
+    message(STATUS "Using vendored PortAudio")
+  endif()
+endif()
+
 if (USE_RTMIDI)
   if (SYSTEM_RTMIDI)
     find_package(PkgConfig REQUIRED)
@@ -283,6 +308,13 @@ if (USE_SDL2)
     #   If you link SDL statically, you also need to define HAVE_LIBC so it builds with the C runtime that your application uses.
     #   This should probably go in a FAQ.
     set(SDL_LIBC ON CACHE BOOL "Tell SDL that we want it to use our C runtime (required for proper static linking)" FORCE)
+
+    # https://github.com/tildearrow/furnace/issues/1237
+    # enabling this will result in SDL finding the Direct3D headers, forcing _WIN32_WINNT to an undesirable value (which makes the Wine headers define GetTickCount64)
+    if (SUPPORT_XP)
+      set(SDL_RENDER_D3D OFF CACHE BOOL "Enable the Direct3D render driver" FORCE)
+    endif()
+
     add_subdirectory(extern/SDL EXCLUDE_FROM_ALL)
     list(APPEND DEPENDENCIES_DEFINES HAVE_SDL2)
     list(APPEND DEPENDENCIES_INCLUDE_DIRS extern/SDL/include)
@@ -338,6 +370,14 @@ else()
   message(STATUS "Building without JACK support")
 endif()
 
+if (WITH_PORTAUDIO)
+  list(APPEND AUDIO_SOURCES src/audio/pa.cpp)
+  message(STATUS "Building with PortAudio")
+  list(APPEND DEPENDENCIES_DEFINES HAVE_PA)
+else()
+  message(STATUS "Building without PortAudio")
+endif()
+
 if (USE_RTMIDI)
   list(APPEND AUDIO_SOURCES src/audio/rtmidi.cpp)
   message(STATUS "Building with RtMidi")
@@ -498,6 +538,10 @@ src/engine/platform/sound/sm8521.c
 
 src/engine/platform/sound/d65modified.c
 
+src/engine/platform/sound/ted-sound.c
+
+src/engine/platform/sound/c140_c219.c
+
 src/engine/platform/oplAInterface.cpp
 src/engine/platform/ym2608Interface.cpp
 src/engine/platform/ym2610Interface.cpp
@@ -506,7 +550,9 @@ src/engine/blip_buf.c
 src/engine/brrUtils.c
 src/engine/safeReader.cpp
 src/engine/safeWriter.cpp
+src/engine/workPool.cpp
 src/engine/cmdStream.cpp
+src/engine/cmdStreamOps.cpp
 src/engine/config.cpp
 src/engine/configEngine.cpp
 src/engine/dispatchContainer.cpp
@@ -514,6 +560,7 @@ src/engine/engine.cpp
 src/engine/export.cpp
 src/engine/fileOps.cpp
 src/engine/fileOpsIns.cpp
+src/engine/fileOpsSample.cpp
 src/engine/filter.cpp
 src/engine/instrument.cpp
 src/engine/macroInt.cpp
@@ -524,6 +571,7 @@ src/engine/song.cpp
 src/engine/sysDef.cpp
 src/engine/wavetable.cpp
 src/engine/waveSynth.cpp
+src/engine/wavOps.cpp
 src/engine/vgmOps.cpp
 src/engine/zsmOps.cpp
 src/engine/zsm.cpp
@@ -589,6 +637,8 @@ src/engine/platform/ga20.cpp
 src/engine/platform/sm8521.cpp
 src/engine/platform/pv1000.cpp
 src/engine/platform/k053260.cpp
+src/engine/platform/ted.cpp
+src/engine/platform/c140.cpp
 src/engine/platform/pcmdac.cpp
 src/engine/platform/dummy.cpp
 
@@ -636,6 +686,7 @@ src/gui/font_proggyClean.cpp
 src/gui/font_ptMono.cpp
 src/gui/font_unifont.cpp
 src/gui/font_icon.cpp
+src/gui/font_furicon.cpp
 src/gui/fonts.cpp
 
 src/gui/image_icon.cpp
@@ -696,6 +747,7 @@ src/gui/subSongs.cpp
 src/gui/sysConf.cpp
 src/gui/sysEx.cpp
 src/gui/sysManager.cpp
+src/gui/sysPartNumber.cpp
 src/gui/sysPicker.cpp
 src/gui/tutorial.cpp
 src/gui/util.cpp

README.md

@@ -48,8 +48,10 @@ for other operating systems, you may [build the source](#developer-info).
     - Ricoh RF5C68 used in Sega CD and FM Towns
     - OKI MSM6258 and MSM6295
     - Konami K007232
+    - Konami K053260
     - Irem GA20
     - Ensoniq ES5506
+    - Namco C140
   - wavetable chips:
     - HuC6280 used in PC Engine
     - Konami Bubble System WSG
@@ -73,6 +75,7 @@ for other operating systems, you may [build the source](#developer-info).
     - QuadTone engine
   - Pokémon Mini
   - Commodore PET
+  - TED used in Commodore Plus/4
   - Casio PV-1000
   - TIA used in Atari 2600
   - POKEY used in Atari 8-bit computers
@@ -124,7 +127,7 @@ for other operating systems, you may [build the source](#developer-info).
 # quick references
 
 - **discussion**: see the [Discussions](https://github.com/tildearrow/furnace/discussions) section, the [official Revolt](https://rvlt.gg/GRPS6tmc) or the [official Discord server](https://discord.gg/EfrwT2wq7z).
-- **help**: check out the [documentation](doc/README.md). it's about 80% complete.
+- **help**: check out the [documentation](doc/README.md). it's about 90% complete.
 
 ## packages
 
@@ -136,6 +139,7 @@ some people have provided packages for Unix/Unix-like distributions. here's a li
 - **FreeBSD**: [a package in ports](https://www.freshports.org/audio/furnace/) is available courtesy of ehaupt (warning: 0.5.8!).
 - **Nix**: [package](https://search.nixos.org/packages?channel=unstable&show=furnace&from=0&size=50&sort=relevance&type=packages&query=furnace) thanks to OPNA2608.
 - **openSUSE**: [a package](https://software.opensuse.org/package/furnace) is available, courtesy of fpesari.
+- **Void Linux**: [furnace](https://github.com/void-linux/void-packages/tree/master/srcpkgs/furnace) is available in the official repository.
 
 ---
 # developer info
@@ -248,6 +252,7 @@ Available options:
 | `USE_SNDFILE` | `ON` | Build with libsndfile (required in order to work with audio files) |
 | `USE_BACKWARD` | `ON` | Use backward-cpp to print a backtrace on crash/abort |
 | `WITH_JACK` | `ON` if system-installed JACK detected, otherwise `OFF` | Whether to build with JACK support. Auto-detects if JACK is available |
+| `WITH_PORTAUDIO` | `ON` | Whether to build with PortAudio. |
 | `SYSTEM_FFTW` | `OFF` | Use a system-installed version of FFTW instead of the vendored one |
 | `SYSTEM_FMT` | `OFF` | Use a system-installed version of fmt instead of the vendored one |
 | `SYSTEM_LIBSNDFILE` | `OFF` | Use a system-installed version of libsndfile instead of the vendored one |

android/app/build.gradle

@@ -15,8 +15,8 @@ android {
         }
         minSdkVersion 21
         targetSdkVersion 26
-        versionCode 162
-        versionName "0.6pre7"
+        versionCode 169
+        versionName "0.6pre9"
         externalNativeBuild {
             cmake {
                 arguments "-DANDROID_APP_PLATFORM=android-21", "-DANDROID_STL=c++_static", "-DWARNINGS_ARE_ERRORS=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="162"
-    android:versionName="0.6pre7"
+    android:versionCode="169"
+    android:versionName="0.6pre9"
     android:installLocation="auto">
 
     <!-- OpenGL ES 2.0 -->

doc/1-intro/README.md

@@ -20,4 +20,10 @@ it also has a flexible windowing system which you may move around and organize.
 
 see [2-interface](../2-interface/README.md) and [3-pattern](../3-pattern/README.md) for more information.
 
-once familiar with the tracker, look to [9-guides](../9-guides/README.md) for useful techniques.
+once familiar with the tracker, look to [9-guides](../9-guides/README.md) for useful techniques.
+
+
+
+# links
+
+[Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves.

doc/1-intro/concepts.md

@@ -15,22 +15,22 @@ The **[pattern view](../3-pattern/README.md)** is like a spreadsheet that displa
 ## structure
 
 The **order list** is a smaller spreadsheet showing the overall song structure.
-- A song is made up of a list of **orders**.
-- An **order** is a set of numbered **patterns** used for each channel.
+- A song is made up of a list of orders.
+- An **order** is a set of numbered patterns used for each channel.
 - Each channel has its own unique list of patterns.
-- Each pattern contains note and effect data for that channel only.
+- Each **pattern** contains note and effect data for that channel only.
 - Patterns may be used multiple times in the order list. Changing a pattern's data in one order will affect the same pattern used in other orders.
 
 ## time
 
-- Each pattern is made of the same number of **rows** as seen in the tracker view.
-- During playback, Each row lasts a number of **ticks** determined by its **speed** value.
-- A tick is the smallest measure of time to which all note, effect, and macro times are quantized.
+- Each pattern is made of the same number of rows as seen in the tracker view.
+- During playback, each **row** lasts a number of ticks determined by its **speed** value.
+- A **tick** is the smallest measure of time to which all note, effect, and macro times are quantized.
 
 ## sound
 
 Different chips have different capabilities. Even within the same chip, each channel may have its own ways of making sound.
 - Some channels use one or more waveform **generators** (sine, square, noise...) to build up a sound.
 - Of special note are **[FM (frequency modulation)](../4-instrument/fm.md)** channels, which use a number of generators called **operators** that can interact to make very complex sounds.
-- Some channels use **[samples](../6-sample/README.md)** - recordings of sounds, often with defined loop points to allow a note to sustain.
+- Some channels use **[samples](../6-sample/README.md)** which are recordings of sounds, often with defined loop points to allow a note to sustain.
 - Some channels use **[wavetables](../5-wave/README.md)**, which are like very short samples of fixed length that automatically loop.

doc/2-interface/README.md

@@ -6,19 +6,25 @@ the default layout of Furnace is depicted below.
 
 ![interface](interface1.png)
 
-primary topics:
+## general info
 
+- [UI components](components.md): recommended reading for all!
+- [global keyboard shortcuts](keyboard.md)
 - [menu bar](menu-bar.md)
+
+## primary windows
+
 - [order list](order-list.md)
 - [play/edit controls](play-edit-controls.md)
 - [instrument/wavetable/sample list](asset-list.md)
 - [song information](song-info.md)
+- [effect list window](effect-list-window.md)
 - [pattern view](../3-pattern/README.md)
 - [instrument editor](../4-instrument/README.md)
 - [wavetable editor](../5-wave/README.md)
 - [sample editor](../6-sample/README.md)
 
-advanced topics:
+## advanced topics
 
 - [mixer](../8-advanced/mixer.md)
 - [grooves](../8-advanced/grooves.md)
@@ -35,9 +41,7 @@ advanced topics:
 - [log viewer](../8-advanced/log-viewer.md)
 - [statistics](../8-advanced/stats.md)
 
-other topics:
+## other topics
 
-- [settings](../2-interface/settings.md)
-- [UI components](components.md)
-- [global keyboard shortcuts](keyboard.md)
 - [basic mode](basic-mode.md)
+- [settings](../2-interface/settings.md)

doc/2-interface/asset-list.md

@@ -3,10 +3,20 @@
 ![instruments window](instruments.png)
 
 Buttons from left to right:
-- **Add**: Creates a new, default instrument.
+- **Add**: pops up a menu to select which type of instrument to add. if only one instrument type is available, the menu is skipped.
+  - If the "Display instrument type menu when adding instrument" setting is disabled, this skips the menu and creates an instrument according to the chip under the cursor.
+  - 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.
-- **Save**: Brings up a file dialog to save the currently selected instrument.
+- **Save**: Brings up a file dialog to save the currently selected asset.
+  - Instruments are saved as Furnace instrument (.fui) files.
+  - Wavetables are saved as Furnace wavetable (.fuw) files. 
+  - Samples are saved as standard wave (.wav) files.
+  - Right-clicking brings up a menu with the applicable items from this list:
+    - **save instrument as .dmp...**: saves the selected instrument in DefleMask format.
+    - **save wavetable as .dmw...**: saves the selected wavetable in DefleMask format.
+    - **save raw wavetable...**: saves the selected wavetable as raw data.
+    - **save raw sample...**: saves the selected sample as raw data.
 - **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.
@@ -33,6 +43,6 @@ Everything from the instrument list applies here also, with one major difference
 
 ![samples window](samples.png)
 
-Everything from the wavetables list applies here also, with the addition of two buttons:
+Everything from the wavetables list applies here also, with the addition of one button before the Delete button:
 - **Preview**: Plays the selected sample at its default note.
-- **Stop preview**: Stops the sample playback.
+  - Right-clicking stops the sample playback.

doc/2-interface/components.md

@@ -1,6 +1,35 @@
 # UI components
 
-the user interface consists of several components. this paper describes some of them.
+the user interface consists of several kinds of components, some of which benefit from explanation.
+
+## text fields
+
+text fields are able to hold... text.
+
+click on a text field to start editing, and click away to stop editing.
+
+the following keyboard shortcuts work while on a text field:
+
+- `Ctrl-X`: cut
+- `Ctrl-C`: copy
+- `Ctrl-V`: paste
+- `Ctrl-A`: select all
+
+(replace Ctrl with Command on macOS)
+
+## number input fields
+
+these work similar to text fields, but you may only input numbers.
+
+they also usually have `+` and `-` buttons which allow you to increase/decrease the amount when clicked (and rapidly do so when click-holding).
+
+## sliders
+
+sliders are used for controlling values in a quick manner by being dragged.
+
+using the scroll wheel while holding Ctrl will change the slider's value by small amounts.
+
+right-clicking or Ctrl-clicking or a slider (Command-click on macOS) will turn it into a number input field for a short period of time, allowing you to input precise values.
 
 ## windows
 
@@ -16,7 +45,7 @@ to resize a window, drag the bottom right corner (marked by a triangular tab) or
 to collapse a window, click on the triangle in the title bar.
 clicking again expands it.
 
-to close a window, click on the `X` at the top right corner.
+to close a window, click on the `X` at the top right corner, or select it from the "window" menu.
 
 ### arrangement and docking
 
@@ -55,30 +84,3 @@ selecting this option will hide the tab bar of that window.
 to bring it back, click on the top left corner.
 
 to undock a window, drag its tab away from where it is docked. then it will be floating again.
-
-## text fields
-
-text fields are able to hold... text.
-
-click on a text field to start editing, and click away to stop editing.
-
-the following keyboard shortcuts work while on a text field:
-
-- `Ctrl-X`: cut
-- `Ctrl-C`: copy
-- `Ctrl-V`: paste
-- `Ctrl-A`: select all
-
-(replace Ctrl with Command on macOS)
-
-## number input fields
-
-these work similar to text fields, but you may only input numbers.
-
-they also usually have two buttons which allow you to increase/decrease the amount when clicked (and rapidly do so when click-holding).
-
-## sliders
-
-sliders are used for controlling values in a quick manner by being dragged.
-
-alternatively, right-clicking or Ctrl-clicking or a slider (Command-click on macOS) will turn it into a number input field for a short period of time, allowing you to input fine values.

doc/2-interface/effect-list-window.md

@@ -0,0 +1,10 @@
+# effect list window
+
+(for more details about these effects, see [the effects page](../3-pattern/effects.md))
+
+![effect list window](effect-list.png)
+
+this window provides a list of the effects that are available.
+
+- **Chip at cursor**: the currently selected chip. the list only shows available effects for this chip.
+- menu button: opens a small list of effect categories. toggle each to change whether they're shown in the list.

doc/2-interface/keyboard.md

@@ -1,15 +1,256 @@
-# global keyboard shortcuts
+# keyboard
 
-this is a list of available shortcuts that may be used at any time, regardless of currently focused window.
+everything on this list can be configured in the "Keyboard" tab of the Settings dialog:
+- click on a keybind then enter a key or key combination to change it.
+- right-click to clear the keybind.
 
-key        | action
------------|-----------------------
-Ctrl-O     | open file
-Ctrl-S     | save file
-Enter      | play/stop song
-F5/F6      |  "
-Shift-Enter| play from cursor position
-F7         |  "
-Ctrl-Enter | play one row
-NumPad `/` | decrease octave
-NumPad `*` | increase octave
+the keys in the "Global hotkeys" section can be used in any window, though not within text boxes.
+
+| action                                                 | default keybind  |
+|--------------------------------------------------------|------------------|
+| **Global hotkeys**                                     |                  |
+| New                                                    | `Ctrl-N`         |
+| Clear song data                                        | —                |
+| Open file                                              | `Ctrl-O`         |
+| Restore backup                                         | —                |
+| Save file                                              | `Ctrl-S`         |
+| Save as                                                | `Ctrl-Shift-S`   |
+| Undo                                                   | `Ctrl-Z`         |
+| Redo                                                   | `Ctrl-Y`         |
+| Play/Stop (toggle)                                     | `Return`         |
+| Play                                                   | —                |
+| Stop                                                   | —                |
+| Play (from beginning)                                  | `F5`             |
+| Play (repeat pattern)                                  | —                |
+| Play from cursor                                       | `Shift-Return`   |
+| Step row                                               | `Ctrl-Return`    |
+| Octave up                                              | `Keypad *`       |
+| Octave down                                            | `Keypad /`       |
+| Previous instrument                                    | `Shift-Keypad /` |
+| Next instrument                                        | `Shift-Keypad *` |
+| Increase edit step                                     | `Ctrl-Keypad *`  |
+| Decrease edit step                                     | `Ctrl-Keypad /`  |
+| Toggle edit mode                                       | `Space`          |
+| Metronome                                              | `Ctrl-M`         |
+| Toggle repeat pattern                                  | —                |
+| Follow orders                                          | —                |
+| Follow pattern                                         | —                |
+| Toggle full-screen                                     | `F11`            |
+| Request voice from TX81Z                               | —                |
+| Panic                                                  | `F12`            |
+|                                                        |                  |
+| **Window activation**                                  |                  |
+| Find/Replace                                           | Ctrl-F           |
+| Settings                                               | —                |
+| Song Information                                       | —                |
+| Subsongs                                               | —                |
+| Speed                                                  | —                |
+| Instrument List                                        | —                |
+| Wavetable List                                         | —                |
+| Sample List                                            | —                |
+| Orders                                                 | —                |
+| Pattern                                                | —                |
+| Mixer                                                  | —                |
+| Grooves                                                | —                |
+| Channels                                               | —                |
+| Pattern Manager                                        | —                |
+| Chip Manager                                           | —                |
+| Compatibility Flags                                    | —                |
+| Song Comments                                          | —                |
+| Instrument Editor                                      | —                |
+| Wavetable Editor                                       | —                |
+| Sample Editor                                          | —                |
+| Edit Controls                                          | —                |
+| Piano                                                  | —                |
+| Oscilloscope (master)                                  | —                |
+| Oscilloscope (per-channel)                             | —                |
+| Volume Meter                                           | —                |
+| Clock                                                  | —                |
+| Register View                                          | —                |
+| Log Viewer                                             | —                |
+| Statistics                                             | —                |
+| Effect List                                            | —                |
+| Debug Menu                                             | `Ctrl-Shift-D`   |
+| About                                                  | —                |
+| Collapse/expand current window                         | —                |
+| Close current window                                   | `Shift-Escape`   |
+|                                                        |                  |
+| **Note input**                                         |                  |
+| _see "note input" section after table_                 |                  |
+|                                                        |                  |
+| **Pattern**                                            |                  |
+| Transpose (+1)                                         | `Ctrl-F2`        |
+| Transpose (-1)                                         | `Ctrl-F1`        |
+| Transpose (+1 octave)                                  | `Ctrl-F4`        |
+| Transpose (-1 octave)                                  | `Ctrl-F3`        |
+| Increase values (+1)                                   | `Ctrl-Shift-F2`  |
+| Increase values (-1)                                   | `Ctrl-Shift-F1`  |
+| Increase values (+16)                                  | `Ctrl-Shift-F4`  |
+| Increase values (-16)                                  | `Ctrl-Shift-F3`  |
+| Select all                                             | `Ctrl-A`         |
+| Cut                                                    | `Ctrl-X`         |
+| Copy                                                   | `Ctrl-C`         |
+| Paste                                                  | `Ctrl-V`         |
+| Paste Mix (foreground)                                 | `Ctrl-Shift-V`   |
+| Paste Mix (background)                                 | —                |
+| Paste Flood                                            | —                |
+| Paste Overflow                                         | —                |
+| Move cursor up                                         | `Up`             |
+| Move cursor down                                       | `Down`           |
+| Move cursor left                                       | `Left`           |
+| Move cursor right                                      | `Right`          |
+| Move cursor up by one (override Edit Step)             | `Shift-Home`     |
+| Move cursor down by one (override Edit Step)           | `Shift-End`      |
+| Move cursor to previous channel                        | —                |
+| Move cursor to next channel                            | —                |
+| Move cursor to next channel (overflow)                 | —                |
+| Move cursor to previous channel (overflow)             | —                |
+| Move cursor to beginning of pattern                    | `Home`           |
+| Move cursor to end of pattern                          | `End`            |
+| Move cursor up (coarse)                                | `PageUp`         |
+| Move cursor down (coarse)                              | `PageDown`       |
+| Expand selection upwards                               | `Shift-Up`       |
+| Expand selection downwards                             | `Shift-Down`     |
+| Expand selection to the left                           | `Shift-Left`     |
+| Expand selection to the right                          | `Shift-Right`    |
+| Expand selection upwards by one (override Edit Step)   | —                |
+| Expand selection downwards by one (override Edit Step) | —                |
+| Expand selection to beginning of pattern               | —                |
+| Expand selection to end of pattern                     | —                |
+| Expand selection upwards (coarse)                      | `Shift-PageUp`   |
+| Expand selection downwards (coarse)                    | `Shift-PageDown` |
+| Delete                                                 | `Delete`         |
+| Pull delete                                            | `Backspace`      |
+| Insert                                                 | `Insert`         |
+| Mute channel at cursor                                 | `Alt-F9`         |
+| Solo channel at cursor                                 | `Alt-F10`        |
+| Unmute all channels                                    | `Alt-Shift-F9`   |
+| Go to next order                                       | —                |
+| Go to previous order                                   | —                |
+| Collapse channel at cursor                             | —                |
+| Increase effect columns                                | —                |
+| Decrease effect columns                                | —                |
+| Interpolate                                            | —                |
+| Fade                                                   | —                |
+| Invert values                                          | —                |
+| Flip selection                                         | —                |
+| Collapse rows                                          | —                |
+| Expand rows                                            | —                |
+| Collapse pattern                                       | —                |
+| Expand pattern                                         | —                |
+| Collapse song                                          | —                |
+| Expand song                                            | —                |
+| Set note input latch                                   | —                |
+| Clear note input latch                                 | —                |
+|                                                        |                  |
+| **Instrument list**                                    |                  |
+| Add                                                    | `Insert`         |
+| Duplicate                                              | `Ctrl-D`         |
+| Open                                                   | —                |
+| Open (replace current)                                 | —                |
+| Save                                                   | —                |
+| Save (.dmp)                                            | —                |
+| Move up                                                | `Shift-Up`       |
+| Move down                                              | `Shift-Down`     |
+| Delete                                                 | —                |
+| Edit                                                   | `Shift-Return`   |
+| Cursor up                                              | `Up`             |
+| Cursor down                                            | `Down`           |
+| Toggle folders/standard view                           | `Ctrl-V`         |
+|                                                        |                  |
+| **Wavetable list**                                     |                  |
+| Add                                                    | `Insert`         |
+| Duplicate                                              | `Ctrl-D`         |
+| Open                                                   | —                |
+| Open (replace current)                                 | —                |
+| Save                                                   | —                |
+| Save (.dmw)                                            | —                |
+| Save (raw)                                             | —                |
+| Move up                                                | `Shift-Up`       |
+| Move down                                              | `Shift-Down`     |
+| Delete                                                 | —                |
+| Edit                                                   | `Shift-Return`   |
+| Cursor up                                              | `Up`             |
+| Cursor down                                            | `Down`           |
+| Toggle folders/standard view                           | `Ctrl-V`         |
+|                                                        |                  |
+| **Sample list**                                        |                  |
+| Add                                                    | `Insert`         |
+| Duplicate                                              | `Ctrl-D`         |
+| Create wavetable from selection                        | `Ctrl-W`         |
+| Open                                                   | —                |
+| Open (replace current)                                 | —                |
+| Import raw data                                        | —                |
+| Import raw data (replace current)                      | —                |
+| Save                                                   | —                |
+| Save (raw)                                             | —                |
+| Move up                                                | `Shift-Up`       |
+| Move down                                              | `Shift-Down`     |
+| Delete                                                 | —                |
+| Edit                                                   | `Shift-Return`   |
+| Cursor up                                              | `Up`             |
+| Cursor down                                            | `Down`           |
+| Preview                                                | —                |
+| Stop preview                                           | —                |
+| Toggle folders/standard view                           | `Ctrl-V`         |
+|                                                        |                  |
+| **Orders**                                             |                  |
+| Previous order                                         | `Up`             |
+| Next order                                             | `Down`           |
+| Cursor left                                            | `Left`           |
+| Cursor right                                           | `Right`          |
+| Increase value                                         | —                |
+| Decrease value                                         | —                |
+| Switch edit mode                                       | —                |
+| Toggle alter entire row                                | `Ctrl-L`         |
+| Add                                                    | `Insert`         |
+| Duplicate                                              | `Ctrl-D`         |
+| Deep clone                                             | `Ctrl-Shift-D`   |
+| Duplicate to end of song                               | `Ctrl-E`         |
+| Deep clone to end of song                              | `Ctrl-Shift-E`   |
+| Remove                                                 | `Delete`         |
+| Move up                                                | `Shift-Up`       |
+| Move down                                              | `Shift-Down`     |
+| Replay                                                 | —                |
+|                                                        |                  |
+| **Sample editor**                                      |                  |
+| Edit mode: Select                                      | `Shift-I`        |
+| Edit mode: Draw                                        | `Shift-D`        |
+| Cut                                                    | `Ctrl-X`         |
+| Copy                                                   | `Ctrl-C`         |
+| Paste                                                  | `Ctrl-V`         |
+| Paste replace                                          | `Ctrl-Shift-V`   |
+| Paste mix                                              | `Ctrl-Alt-V`     |
+| Select all                                             | `Ctrl-A`         |
+| Resize                                                 | `Ctrl-R`         |
+| Resample                                               | `Ctrl-E`         |
+| Amplify                                                | `Ctrl-B`         |
+| Normalize                                              | `Ctrl-N`         |
+| Fade in                                                | `Ctrl-I`         |
+| Fade out                                               | `Ctrl-O`         |
+| Insert silence                                         | `Insert`         |
+| Apply silence                                          | `Shift-Delete`   |
+| Delete                                                 | `Delete`         |
+| Trim                                                   | `Ctrl-Delete`    |
+| Reverse                                                | `Ctrl-T`         |
+| Invert                                                 | `Ctrl-Shift-T`   |
+| Signed/unsigned exchange                               | `Ctrl-U`         |
+| Apply filter                                           | `Ctrl-F`         |
+| Preview sample                                         | —                |
+| Stop sample preview                                    | —                |
+| Zoom in                                                | `Ctrl-=`         |
+| Zoom out                                               | `Ctrl--`         |
+| Toggle auto-zoom                                       | `Ctrl-0`         |
+| Create instrument from sample                          | —                |
+| Set loop to selection                                  | `Ctrl-l`         |
+
+## note input
+
+the settings for note input keybinds operate differently. each entry in the list of keybinds is made of the following:
+- **Key**: key assignment.
+- **Type**: type of note input. left-click cycles through "Note", "Note off", "Note release", and "Macro release".
+  - _note:_ the list is sorted by type. on changing a key's type, it will instantly move to its new sorting position!
+- **Value**: number of semitones above C at the current octave. only appears for note type binds.
+- **Remove**: removes the keybind from the list.
+
+below all the binds, select a key from the dropdown list to add it. it will appear at or near the top of the list as a note with value 0.

doc/2-interface/menu-bar.md

@@ -2,12 +2,14 @@
 
 the menu bar allows you to select from five menus: file, edit, settings, window and help.
 
+items in _italics_ don't appear in basic mode and are only available in advanced mode.
+
 # file
 
-- **new...**: create a new song.
+- **new...**: creates a new song.
 - **open...**: opens the file picker, allowing you to select a song to open.
 - **open recent**: contains a list of the songs you've opened before.
-  - **clear history**: this option erases the file history.
+  - **clear history**: erases the file history.
 
 - **save**: saves the current song.
   - opens the file picker if this is a new song, or a backup.
@@ -31,22 +33,16 @@ the menu bar allows you to select from five menus: file, edit, settings, window
     - Neo Geo CD (DefleMask 1.0+)
   - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
 
-- **export audio...**: export your song to a .wav file. see next section for more details.
-- **export VGM...**: export your song to a .vgm file. see next section for more details.
-- **export ZSM...**: export your song to a .zsm file. see next section for more details.
+- **export audio...**: opens the file picker, allowing you to export your song to a .wav file. see next section for more details.
+- **export VGM...**: opens the file picker, allowing you to export your song to a .vgm file. see next section for more details.
+- **export ZSM...**: opens the file picker, allowing you to export your song to a .zsm file. see next section for more details.
   - only available when there's a YM2151 and/or VERA.
 - **export command stream...**: export song data to a command stream file. see next section for more details.
   - this option is for developers.
-  
-- **add chip...**: add a chip to the current song.
-- **configure chip...**: set a chip's parameters.
-  - for a list of parameters, see [7-systems](../7-systems/README.md).
-- **change chip...**: change a chip to another.
-  - **Preserve channel positions**: enable this option to make sure Furnace does not auto-arrange/delete channels to compensate for differing channel counts. this can be useful for doing ports, e.g. from Genesis to PC-98.
-- **remove chip...**: remove a chip.
-  - **Preserve channel positions**: same thing as above.
 
-- **restore backup**: restore a previously saved backup.
+- **manage chips**: opens the [Chip Manager](../8-advanced/chip-manager.md) dialog.
+
+- **restore backup**: restores a previously saved backup.
   - Furnace keeps up to 5 backups of a song.
   - the backup directory is located in:
     - Windows: `%USERPROFILE%\AppData\Roaming\furnace\backups`
@@ -85,8 +81,8 @@ the following settings exist:
   - other versions may not support all chips.
   - use this option if you need to export for a quirky player or parser.
     - for example, RYMCast is picky with format versions. if you're going to use this player, select 1.60.
-- **loop**: writes loop. if disabled, the resulting file won't loop.
-- **loop trail**: this option allows you to set how much of the song is written after it loops.
+- **loop**: includes loop information. if disabled, the resulting file won't loop.
+- **loop trail**: sets how much of the song is written after it loops.
   - the reason this exists is to work around a VGM format limitation in where post-loop state isn't recorded at all.
   - this may change the song length as it appears on a player.
   - **auto-detect**: detect how much to write automatically.
@@ -99,10 +95,10 @@ the following settings exist:
   - some chips will not be available, either because VGM doesn't support these yet, or because you selected an old format version.
 - **add pattern change hints**: this option adds a "hint" when a pattern change occurs. only useful if you're a developer.
   - the format of the "hint" data block that gets written is: `67 66 FE ll ll ll ll 01 oo rr pp pp pp ...`
-    - ll: length, a 32-bit little-endian number
-    - oo: order
-    - rr: initial row (a 0Dxx effect is able to select a different row)
-    - pp: pattern index (one per channel)
+    - `ll`: length, a 32-bit little-endian number
+    - `oo`: order
+    - `rr`: initial row (a 0Dxx effect is able to select a different row)
+    - `pp`: pattern index (one per channel)
 - **direct stream mode**: this option allows DualPCM to work. don't use this for other chips.
   - may or may not play well with hardware VGM players.
 
@@ -120,6 +116,7 @@ the following settings are available:
   - I suggest you use the same rate as the song's.
   - apparently ZSM doesn't support changing the rate mid-song.
 - **loop**: enables loop. if disabled, the song won't loop.
+- **optimize size**: removes unnecessary commands to reduce size.
 
 click on **Begin Export** to... you know.
 
@@ -134,13 +131,15 @@ it's not really useful, unless you're a developer and want to use a command stre
 
 # edit
 
+- **...**: does nothing except prevent accidental clicks on later menu items if the menu is too tall to fit on the program window.
+
 - **undo**: reverts the last action.
 - **redo**: repeats what you undid previously.
 
 - **cut**: moves the current selection in the pattern view to clipboard.
 - **copy**: copies the current selection in the pattern view to clipboard.
 - **paste**: inserts the clipboard's contents in the cursor position.
-- **paste special...**: variants of the paste feature.
+- _**paste special...**:_ variants of the paste feature.
   - **paste mix**: inserts the clipboard's contents in the cursor position, but does not erase the occupied region.
   - **paste mix (background)**: does the same thing as paste mix, but doesn't alter content which is already there.
   - **paste with ins (foreground)**: same thing as paste mix, but changes the instrument.
@@ -154,8 +153,8 @@ it's not really useful, unless you're a developer and want to use a command stre
   - if a column is already selected, it will select the entire channel.
   - if a channel is already selected, it will select the entire pattern.
 
-- **operation mask**: toggles which columns will be affected by the listed operations. [more information here.](../8-advanced/opmask.md)
-- **input latch**: determines which data are placed along with a note. [more information here.](../8-advanced/inputlatch.md)
+- _**operation mask**:_ toggles which columns will be affected by the listed operations. [more information here.](../8-advanced/opmask.md)
+- _**input latch**:_ determines which data are placed along with a note. [more information here.](../8-advanced/inputlatch.md)
 
 - **note/octave up/down**: transposes notes in the current selection.
 
@@ -188,7 +187,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **expand song**: same as expand, but affects the entire song.
   - it also changes speeds and pattern length to compensate.
 
-- **find/replace**: shows [the Find/Replace window](../8-advanced/find-replace.md).
+- _**find/replace**:_ shows [the Find/Replace window](../8-advanced/find-replace.md).
 
 - **clear**: allows you to mass-delete things like songs, instruments and the like.
 
@@ -213,12 +212,12 @@ all these menu items show or hide their associated windows.
 - [samples](../6-sample/README.md)
 - [orders](order-list.md)
 - [pattern](../3-pattern/README.md)
-- [mixer](mixer.md)
-- [grooves](grooves.md)
-- [channels](channels.md)
-- [pattern manager](pat-manager.md)
-- [chip manager](chip-manager.md)
-- [compatibility flags](compat-flags.md)
+- _[mixer](mixer.md)_
+- _[grooves](grooves.md)_
+- _[channels](channels.md)_
+- _[pattern manager](pat-manager.md)_
+- _[chip manager](chip-manager.md)_
+- _[compatibility flags](compat-flags.md)_
 - [song comments](comments.md)
 
 - [piano](piano.md)
@@ -246,5 +245,5 @@ at the end of the menu bar, more information may be shown:
   - volume in decimal, hex, and percentage.
   - effect type and description.
 - during playback, the current values of the following will be listed:\
-  speed/groove @ tick rate (BPM) | order | row | elapsed time.
+  > speed/groove @ tick rate (BPM) | order | row | elapsed time.
 - if any changes or edits have been made but not yet saved, "modified" will appear.

doc/2-interface/settings.md

@@ -1,235 +1,325 @@
 # settings
 
-settings are saved when clicking the **OK** button at the bottom of the dialog.
+settings are saved when clicking the **OK** or **Apply** buttons at the bottom of the dialog.
 
+## General
 
+### Program
 
-# General
+- **Render backend**: changing this may help with performace issues.
+- **Late render clear**: this option is only useful when using old versions of Mesa drivers. it force-waits for VBlank by clearing after present, reducing latency.
+- **Power-saving mode**: saves power by lowering the frame rate to 2fps when idle.
+  - may cause issues under Mesa drivers!
+- **Disable threaded input (restart after changing!)**: processes key presses for note preview on a separate thread (on supported platforms), which reduces latency.
+  - however, crashes have been reported when threaded input is on. enable this option if that is the case.
+- **Enable event delay**: may cause issues with high-polling-rate mice when previewing notes.
 
-- **Workspace layout**
-  - **Import**: reads a .ini layout file.
-  - **Export**: writes current layout to a .ini file.
-  - **Reset**: resets layout to default.
+### File
+
+- **Use system file picker**: uses native OS file dialog instead of Furnace's.
+- **Number of recent files**: number of files that will be remembered in the _open recent..._ menu.
+- **Compress when saving**: uses zlib to compress saved songs.
+- **Save unused patterns**: stores unused patterns in a saved song.
+- **Use new pattern format when saving**: stores patterns in the new, optimized and smaller format. only disable if you need to work with older versions of Furnace.
+- **Don't apply compatibility flags when loading .dmf**: does exactly what the option says. your .dmf songs may not play correctly after enabled.
+- **Play after opening song:**
+  - No
+  - Only if already playing
+  - Yes
+- **Audio export loop/fade out time:**
+  - **Set to these values on start-up:**
+    - **Loops**: number of additional times to play through `0Bxx` song loop.
+    - **Fade out (seconds)**: length of fade out after final loop.
+  - **Remember last values**
+
+### Chip
 
 - **Initial system**: the system of chips loaded on starting Furnace.
   - **Current system**: sets current chips as default.
-  - **Randomize**: set default to a random system.
+  - **Randomize**: sets default to a random system.
     - this will not choose a random system at each start.
   - **Reset to defaults**: sets default to "Sega Genesis/Mega Drive".
   - **Name**: name for the default system. may be set to any text.
-  - system configuration: same as in the [chip manager](../8-advanced/chip-manager.md) and [mixer](../8-advanced/mixer.md).
+  - **Configure**: same as in the [chip manager](../8-advanced/chip-manager.md) and [mixer](../8-advanced/mixer.md).
+- **When creating new song**:
+  - **Display system preset selector**
+  - **Start with initial system**
+
+### Start-up
 
 - **Play intro on start-up:**
   - **No**: skips intro entirely.
   - **Short**: shows silent title screen briefly.
   - **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.
-- **When creating new song**:
-  - **Display system preset selector**
-  - **Start with initial system**
+- **Disable fade-in during start-up**
+- **About screen party time**
+  - _warning:_ may cause epileptic seizures.
+
+### Behavior
 
-- **Double-click time (seconds)**: maximum time between mouse clicks to recognize them as a double-click.
-- **Toggle channel solo on:** select which interactions with a channel header will toggle solo for that channel.
-- **Push value when overwriting instead of clearing it**: in the order list and pattern editors, typing into an already-filled value will shift digits instead of starting fresh.
-  - if off: moving the cursor onto the value `A5` and typing a "B" results in `0B`.
-  - if on: with the cursor on the value `A5` and typing a "B" results in `5B`.
-- **Move cursor up on backspace-delete**
-- **Move cursor by edit step on delete**
-- **Change current instrument when changing instrument column (absorb)**
-- **Delete effect value when deleting effect**
-- **Change order when scrolling outside of pattern bounds**:
-  - if off, the pattern edit cursor will stay locked within the current order.
-  - if on, moving the cursor past the edge of the previous or next order will move to that order.
-- **Move cursor by edit step on insert (push)**
-- **Move cursor to end of clipboard content when pasting**
-- **Don't scroll when moving cursor**
-- **Double click selects entire column**
-- **Allow docking editors**
-- **Don't raise pattern editor on click**
-- **Focus pattern editor when selecting instrument**
-- **Restart song when changing chip properties**
-- **Use system file picker**: use native OS file dialog instead of Furnace's.
-- **Only allow window movement when clicking on title bar**
-- **Enable event delay**
-  - may cause issues with high-polling-rate mice when previewing notes.
-- **Power-saving mode**
-  - saves power by lowering the frame rate to 2fps when idle.
-  - may cause issues under Mesa drivers!
-- **Disable threaded input (restart after changing!)**
-  - threaded input processes key presses for note preview on a separate thread (on supported platforms), which reduces latency.
-  - however, crashes have been reported when threaded input is on. enable this option if that is the case.
-- **Remember window position**
-  - remembers the window's last position on start-up.
 - **New instruments are blank**
-- **Save unused patterns**
-- **Compress when saving**
-  - use zlib to compress saved songs.
-- **Cursor follows current order when moving it**
-  - applies when playback is stopped.
-- **Audio export loop/fade out time:**
-  - **Set to these values on start-up:**
-    - **Loops**: number of additional times to play through `0Bxx` song loop.
-    - **Fade out (seconds)**: length of fade out after final loop.
-  - **Remember last values**
-- **Note preview behavior:**
-  - **Never**
-  - **When cursor is in Note column**
-  - **When cursor is in Note column or not in edit mode**
-  - **Always**
-- **Wrap pattern cursor horizontally:**
-  - **No**
-  - **Yes**
-  - **Yes, and move to next/prev row**
-- **Wrap pattern cursor vertically:**
-  - **No**
-  - **Yes**
-  - **Yes, and move to next/prev pattern**
-- **Cursor movement keys behavior:**
-  - **Move by one**
-  - **Move by Edit Step**
-- **Effect input cursor behavior:**
-  - **Move down**
-  - **Move to effect value (otherwise move down)**
-  - **Move to effect value/next effect and wrap around**
-- **Allow dragging selection:**
-  - **No**
-  - **Yes**
-  - **Yes (while holding Ctrl only)**
 
 
 
-# Audio/MIDI
+## Audio
 
-- **Backend**: select SDL or JACK for audio output.
-  - only appears on Linux, or MacOS compiled with JACK support
+### Output
+
+- **Backend**: selects a different backend for audio output.
+  - SDL: the default one.
+  - JACK: the JACK Audio Connection Kit (low-latency audio server). only appears on Linux, or MacOS compiled with JACK support.
+  - PortAudio: this may or may not perform better than the SDL backend.
+- **Driver**: select a different audio driver if you're having problems with the default one.
+  - only appears when Backend is SDL.
 - **Device**: audio device for playback.
-- **Sample rate**
-- **Outputs**: select number of audio outputs created, up to 16.
+  - if using PortAudio backend, devices will be prefixed with the audio API that PortAudio is going to use:
+    - Windows WASAPI: a modern audio API available on Windows Vista and later, featuring an (optional) Exclusive Mode. be noted that your buffer size setting may be ignored.
+    - Windows WDM-KS: low-latency, direct to hardware output mechanism. may not work all the time and prevents your audio device from being used for anything else!
+    - Windows DirectSound: this is the worst choice. best to move on.
+    - MME: an old audio API. doesn't have Exclusive Mode.
+    - Core Audio: the only choice in macOS.
+    - ALSA: low-level audio output on Linux. may prevent other applications from using your audio device.
+- **Sample rate**: audio output rate.
+  - a lower rate decreases quality and isn't really beneficial.
+  - if using PortAudio backend, be careful about this value.
+- **Outputs**: number of audio outputs created, up to 16.
   - only appears when Backend is JACK.
-- **Channels**: number of output channels to use.
+- **Channels**: mono, stereo or something.
 - **Buffer size**: size of buffer in both samples and milliseconds.
-- **Quality**: selects quality of resampling. low quality reduces CPU load.
-- **Metronome volume**
+  - setting this to a low value may cause stuttering/glitches in playback (known as "underruns" or "xruns").
+  - setting this to a high value increases latency.
+- **Exclusive mode**: enables Exclusive Mode, which may offer latency improvements.
+  - only available on WASAPI devices in the PortAudio backend!
 - **Low-latency mode (experimental!)**: reduces latency by running the engine faster than the tick rate. useful for live playback/jam mode.
-  - _warning:_ experimental! may produce glitches. only enable if your buffer size is small (10ms or less).
-- **Force mono audio**
-- **Software clipping**: clips output to nominal range (-1.0 to 1.0) before passing it to the audio device.
-  - this avoids activating Windows' built-in limiter.
+  - only enable if your buffer size is small (10ms or less).
+- **Force mono audio**: use if you're unable to hear stereo audio (e.g. single speaker or hearing loss in one ear).
 - **want:** displays requested audio configuration.
 - **got:** displays actual audio configuration returned by audio backend.
 
-- **MIDI input**
-- **MIDI output**
-- **MIDI input settings**
-  - **Note input**
-  - **Velocity input**
-  - **Map MIDI channels to direct channels**
-  - **Map Yamaha FM voice data to instruments**
-  - **Program change is instrument selection**
-  - **Value input style**:
+### Mixing
+
+- **Quality**: selects quality of resampling. low quality reduces CPU load by a small amount.
+- **Software clipping**: clips output to nominal range (-1.0 to 1.0) before passing it to the audio device.
+  - this avoids activating Windows' built-in limiter.
+  - this option shall be enabled when using PortAudio backend with a DirectSound device.
+
+### Metronome
+
+- **Metronome volume**
+
+## MIDI
+
+### MIDI input
+
+- **MIDI input**: input device.
+- **Note input**: enables note input. disable if you intend to use this device only for binding actions.
+- **Velocity input**: enables velocity input when entering notes in the pattern.
+- **Map MIDI channels to direct channels**: when enabled, notes from MIDI channels will be mapped to channels rather than the cursor position.
+- **Map Yamaha FM voice data to instruments**: when enabled, Furnace will listen for any transmitted Yamaha SysEx patches.
+  - this option is only useful if you have a Yamaha FM synthesizer (e.g. TX81Z).
+  - selecting a voice or using the "Voice Transmit?" option will send a patch, and Furnace will create a new instrument with its data.
+  - this may also be triggered by clicking on "Receive from TX81Z" in the instrument editor (OPZ only).
+- **Program change is instrument selection**: changes the current instrument when a program change event is received.
+- **Value input style**: changes the way values are entered when the pattern cursor is not in the Note column. the following styles are available:
+  - **Disabled/custom**: no value input through MIDI.
+  - **Two octaves (0 is C-4, F is D#5)**: maps keys in two octaves to single nibble input. the layout is:
+    - ` - octave n -- octave n+1 -`
+    - ` 1 3   6 8 A   D F   # # # `
+    - `0 2 4 5 7 9 B C E # # # # #`
+  - **Raw (note number is value)**: the note number becomes the input value. not useful if you want to input anything above 7F.
+  - **Two octaves alternate (lower keys are 0-9, upper keys are A-F)**: maps keys in two octaves, but with a different layout:
+    - ` - octave n -- octave n+1 -`
+    - ` A B   C D E   F #   # # # `
+    - `0 1 2 3 4 5 6 7 8 9 # # # #`
+  - **Use dual control change (one for each nibble)**: maps two control change events to the nibbles of a value.
+    - **CC of upper nibble**: select the CC number that will change the upper nibble.
+    - **CC of lower nibble**: select the CC number that will change the lower nibble.
+  - **Use 14-bit control change**: maps two control change events that together form a single 14-bit CC. some MIDI controllers do these.
+    - **MSB CC**: select the CC containing the upper portion of the control.
+    - **LSB CC**: select the CC containing the lower portion of the control.
+  - **Use single control change**: maps one control change event. not useful if you want to input odd numbers.
+    - **Control**: select the CC number that will change the value.
+- **Per-column control change**: when enabled, you can map several control change events to a channel's columns.
+  - **Instrument**\
+    **Volume**\
+    **Effect `x` type**\
+    **Effect `x` value**
     - **Disabled/custom**
-    - **Two octaves (0 is C-4, F is D#5)**
-    - **Raw (note number is value)**
-    - **Two octaves alternate (lower keys are 0-9, upper keys are A-F)**
     - **Use dual control change (one for each nibble)**
       - **CC of upper nibble**
       - **CC of lower nibble**
     - **Use 14-bit control change**
       - **MSB CC**
       - **LSB CC**
-    - **Use single control change**
+    - **Use single control change (imprecise)**
       - **Control**
-  - **Per-column control change**
-    - **Instrument**\
-      **Volume**\
-      **Effect `x` type**\
-      **Effect `x` value**
-      - **Disabled/custom**
-      - **Use dual control change (one for each nibble)**
-        - **CC of upper nibble**
-        - **CC of lower nibble**
-      - **Use 14-bit control change**
-        - **MSB CC**
-        - **LSB CC**
-      - **Use single control change (imprecise)**
-        - **Control**
-  - **Volume curve**
-  - **Actions:**
-    - **`+`** button: adds a new action.
-    - window-with-arrow button: new action with learning! press a button or move a slider/knob/something on your device.
-    - each action has the following:
-      - **Type**
-      - **Channel**
-      - **Note/Control**
-      - **Velocity/Value**
-      - **Action**
-      - **Learn**
-      - **Remove**
+- **Volume curve**: adjust the velocity to volume curve.
+- **Actions**: this allows you to bind note input and control change events to actions.
+  - **`+`** button: adds a new action.
+  - window-with-arrow button: new action with learning! press a button or move a slider/knob/something on your device.
+  - each action has the following:
+    - **Type**: type of event.
+    - **Channel**: channel of event.
+    - **Note/Control**: the note/control change number.
+    - **Velocity/Value**: the velocity or control value
+    - **Action**: the GUI action to perform.
+    - **Learn**: after clicking on this button, do something in your MIDI device and Furnace will map that to this action.
+    - **Remove**: remove this action.
 
-- **MIDI output settings**
-  - **Output mode:**
-    - **Off (use for TX81Z)**
-    - **Melodic**
-  - **Send Program Change**
-  - **Send MIDI clock**
-  - **Send MIDI timecode**
-    - **Timecode frame rate:**
-      - **Closest to Tick Rate**
-      - **Film (24fps)**
-      - **PAL (25fps)**
-      - **NTSC drop (29.97fps)**
-      - **NTSC non-drop (30fps)**
+### MIDI output
 
-# Emulation
-- **Arcade/YM2151 core**
-  - **ymfm**
-  - **Nuked-OPM**
-- **Genesis/YM2612 core**
-  - **Nuked-OPN2**
-  - **ymfm**
-- **SN76489 core**
-  - **MAME**
-  - **Nuked-PSG Mod**
-- **NES core**
-  - **puNES**
-  - **NSFplay**
-- **FDS core**
-  - **puNES**
-  - **NSFplay**
-- **SID core**
-  - **reSID**
-  - **reSIDfp**
-- **POKEY core**
-  - **Atari800 (mzpokeysnd)**
-  - **ASAP (C++ port)**
-- **OPN/OPNA/OPNB cores**
-  - **ymfm only**
-  - **Nuked-OPN2 (FM) + ymfm (SSG/ADPCM)**
+- **MIDI output**: output device.
+- **Output mode:**
+  - **Off (use for TX81Z)**: don't output anything. use if you plan to use Furnace as sync master, or the "Receive from TX81Z" button in the OPZ instrument editor.
+  - **Melodic**: output MIDI events.
+- **Send Program Change**: output program change events when instrument change commands occur.
+- **Send MIDI clock**: output MIDI beat clock.
+- **Send MIDI timecode**: output MIDI timecode.
+  - **Timecode frame rate**: sets the timing standard used for MIDI timecode.
+    - **Closest to Tick Rate**: automatically sets the rate based on the song's Tick Rate.
+    - **Film (24fps)**: output at 24 codes per second.
+    - **PAL (25fps)**: output at 25 codes per second.
+    - **NTSC drop (29.97fps)**: output at ~29.97 codes per second, skipping frames 0 and 1 of each minute that doesn't divide by 10.
+    - **NTSC non-drop (30fps)**: output at 30 codes per second.
 
-- **PC Speaker strategy:**
-  - **evdev SND_TONE**
-  - **KIOCSOUND on /dev/tty1**
-  - **/dev/port**
-  - **KIOCSOUND on standard output**
-  - **outb()**
+## Emulation
 
-- **Sample ROMs:**
-  - **OPL4 YRW801 path**
-  - **MultiPCM TG100 path**
-  - **MultiPCM MU5 path**
+### Cores
+
+- **Arcade/YM2151 core**\
+  **Genesis/YM2612 core**\
+  **SN76489 core**\
+  **NES core**\
+  **FDS core**\
+  **SID core**\
+  **POKEY core**\
+  **OPN/OPNA/OPNB cores**:
+  - **Playback Core(s)**: core(s) to use for realtime playback.
+  - **Render Core(s)**: core(s) to use for exporting audio.
+  - all of these are covered in the [guide to choosing emulation cores](../9-guides/emulation-cores.md).
+
+- **PC Speaker strategy**: this is covered in the [PC speaker system doc](../7-systems/pcspkr.md).
+
+## Keyboard
+
+### Keyboard
+
+- **Import**
+- **Export**
+- **Reset defaults**
+- [grouped list of keybinds...](keyboard.md)
+  - click on a keybind then enter a key or key combination to change it
+  - right-click to clear the keybind
 
 
 
-# Appearance
+## Interface
 
-- **Render driver**
-- **Automatic UI scaling factor**: automatically match the OS's UI scaling.
-- **UI scaling factor**: only if "Automatic UI scaling factor" is off.
-- **Main font**: if "Custom...", a file path selector will appear beneath.
-- **Size**
-- **Pattern font**: if "Custom...", a file path selector will appear beneath.
-- **Size**
+### Layout
+
+- **Workspace layout**
+  - **Import**: reads a .ini layout file.
+  - **Export**: writes current layout to a .ini file.
+  - **Reset**: resets layout to default.
+- **Allow docking editors**
+- **Remember window position**: remembers the window's last position on start-up.
+- **Only allow window movement when clicking on title bar**
+- **Center pop-up windows**
+- **Play/edit controls layout:**
+  - **Classic**
+  - **Compact**
+  - **Compact (vertical)**
+  - **Split**
+- **Position of buttons in Orders:**
+  - **Top**
+  - **Left**
+  - **Right**
+
+### Mouse
+
+- **Double-click time (seconds)**: maximum time between mouse clicks to recognize them as a double-click.
+- **Don't raise pattern editor on click**
+- **Focus pattern editor when selecting instrument**
+- **Note preview behavior:**
+  - **Never**
+  - **When cursor is in Note column**
+  - **When cursor is in Note column or not in edit mode**
+  - **Always**
+- **Allow dragging selection:**
+  - **No**
+  - **Yes**
+  - **Yes (while holding Ctrl only)**
+- **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
+- **Double click selects entire column**
+
+### Cursor behavior
+
+- **Insert pushes entire channel row**
+- **Pull delete affects entire channel row**
+- **Push value when overwriting instead of clearing it**: in the order list and pattern editors, typing into an already-filled value will shift digits instead of starting fresh.
+  - if off: moving the cursor onto the value `A5` and typing a "B" results in `0B`.
+  - if on: moving the cursor onto the value `A5` and typing a "B" results in `5B`.
+- **Effect input behavior:**
+  - **Move down**
+  - **Move to effect value (otherwise move down)**
+  - **Move to effect value/next effect and wrap around**
+- **Delete effect value when deleting effect**
+- **Change current instrument when changing instrument column (absorb)**
+- **Remove instrument value when inserting note off/release**
+- **Remove volume value when inserting note off/release**
+
+
+### Cursor movement
+
+- **Wrap horizontally:**
+  - **No**
+  - **Yes**
+  - **Yes, and move to next/prev row**
+- **Wrap vertically:**
+  - **No**
+  - **Yes**
+  - **Yes, and move to next/prev pattern**
+  - **Yes, and move to next/prev pattern (wrap around)**
+- **Cursor movement keys behavior:**
+  - **Move by one**
+  - **Move by Edit Step**
+- **Move cursor by edit step on delete**
+- **Move cursor by edit step on insert (push)**
+- **Move cursor up on backspace-delete**
+- **Move cursor to end of clipboard content when pasting**
+
+### Scrolling
+
+- **Change order when scrolling outside of pattern bounds**:
+  - **No**: the pattern edit cursor will stay locked within the current order.
+  - **Yes**: moving the cursor past the edge of the previous or next order will move to that order, but not past the start or end of a song.
+  - **Yes, and wrap around song**: as above, but will wrap from song end to start.
+- **Cursor follows current order when moving it**
+  - applies when playback is stopped.
+- **Don't scroll when moving cursor**
+- **Move cursor with scroll wheel**
+
+
+
+## Appearance
+
+### Scaling
+
+- **Automatic UI scaling factor**: automatically matches the OS's UI scaling.
+- **UI scaling factor**: only appears if "Automatic UI scaling factor" is off.
 - **Icon size**
+
+### Text
+
+- **Main font**: overall interface font.\
+  **Header font**: font for section headers.\
+  **Pattern font** font for the pattern view, the order list, and related.
+  - if "Custom...", a file path selector will appear.
+  - **Size**: font size.
 - **Display Japanese characters**\
   **Display Chinese (Simplified) characters**\
   **Display Chinese (Traditional) characters**\
@@ -237,25 +327,7 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - only toggle these options if you have enough graphics memory.
   - these are a temporary solution until dynamic font atlas is implemented in Dear ImGui.
 
-- **Number of recent files**
-
-- **Pattern view labels:**
-- **Note off (3-char)**: default is `OFF`
-- **Note release (3-char)**: default is `===`.
-- **Macro release (3-char)**: default is `REL`.
-- **Empty field (3-char)**: default is `...`.
-- **Empty field (2-char)**: default is `..`.
-
-- **Orders row number format:**
-  - **Decimal**
-  - **Hexadecimal**
-- **Pattern row number format:**
-  - **Decimal**
-  - **Hexadecimal**
-- **FM parameter names:**
-  - **Friendly**
-  - **Technical**
-  - **Technical (alternate)**
+### Program
 
 - **Title bar:**
   - **Furnace**
@@ -269,44 +341,43 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - **File path**
   - **Cursor details or file path**
   - **Nothing**
-- **Play/edit controls layout:**
-  - **Classic**
-  - **Compact**
-  - **Compact (vertical)**
-  - **Split**
-- **Position of buttons in Orders:**
-  - **Top**
-  - **Left**
-  - **Right**
-- **FM parameter editor layout:**
-  - **Modern**
-  - **Compact (2x2, classic)**
-  - **Compact (1x4)**
-  - **Compact (4x1)**
-  - **Alternate (2x2)**
-  - **Alternate (1x4)**
-  - **Alternate (4x1)**
-- **Position of Sustain in FM editor:**
-  - **Between Decay and Sustain Rate**
-  - **After Release Rate**
-- **Macro editor layout:**
-  - **Unified**
-  - **Mobile**
-  - **Grid**
-  - **Single (with list)**
-  - **Single (combo box)**
+- **Capitalize menu bar**
+- **Display add/configure/change/remove chip menus in File menu**: if enabled, the "manage chips" item in the file menu is split into the four listed items for quick access.
 
-- **Namco 163 chip name**
+### Orders
 
-- **Channel colors:**
-  - **Single**
-  - **Channel type**
-  - **Instrument type**
-- **Channel name colors:**
-  - **Single**
-  - **Channel type**
-  - **Instrument type**
-- **Channel style:**
+- **Highlight channel at cursor in Orders**
+- **Orders row number format:**
+  - **Decimal**
+  - **Hexadecimal**
+
+### Pattern
+
+- **Center pattern view**: centers pattern horizontally in view.
+- **Overflow pattern highlights**
+- **Display previous/next pattern**
+- **Pattern row number format:**
+  - **Decimal**
+  - **Hexadecimal**
+- **Pattern view labels:**
+  - **Note off (3-char)**: default is `OFF`
+  - **Note release (3-char)**: default is `===`.
+  - **Macro release (3-char)**: default is `REL`.
+  - **Empty field (3-char)**: default is `...`.
+  - **Empty field (2-char)**: default is `..`.
+- **Pattern view spacing after:** number of pixels of space between columns.
+  - **Note**
+  - **Instrument**
+  - **Volume**
+  - **Effect**
+  - **Effect value**
+- **Single-digit effects for 00-0F**
+- **Use flats instead of sharps**
+- **Use German notation**: display `B` notes as `H`, and `A#` notes as `B`.
+
+### Channel
+
+- **Channel style:** sets the appearance of channel headers in pattern view.
   - **Classic**
   - **Line**
   - **Round**
@@ -328,60 +399,101 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - **Regular**
   - **Monospace**
 - **Center channel name**
+- **Channel colors:**
+  - **Single**
+  - **Channel type**
+  - **Instrument type**
+- **Channel name colors:**
+  - **Single**
+  - **Channel type**
+  - **Instrument type**
 
+### Assets
+
+- **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...
+  - 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.
+- **Instrument list icon style:**
+  - **None**
+  - **Graphical icons**
+  - **Letter icons**
 - **Colorize instrument editor using instrument type**
-- **Use separate colors for carriers/modulators in FM editor**
-- **Unified instrument/wavetable/sample list**
-- **Horizontal instrument list**
-- **Use standard OPL waveform names**
-- **Overflow pattern highlights**
-- **Display previous/next pattern**
-- **Use German notation**: display `B` notes as `H`, and `A#` notes as `B`.
-- **Single-digit effects for 00-0F**
-- **Center pattern view**: centers pattern horizontally in view.
-- **Unsigned FM detune values**
-- **Highlight channel at cursor in Orders**
-- **About screen party time**
-  - _warning:_ may cause epileptic seizures.
+- **Display instrument type menu when adding instrument**
+  - if turned off, the menu can still be opened by right-clicking the add button.
+
+### Macro Editor
+
+- **Macro editor layout:**
+  - **Unified**
+  - **Grid**
+  - **Single (with list)**
+- **Use classic macro editor vertical slider**
+
+### Wave Editor
 
 - **Use compact wave editor**
-- **Use classic macro editor vertical slider**
+
+### FM Editor
+
+- **FM parameter names:**
+  - **Friendly**
+  - **Technical**
+  - **Technical (alternate)**
+- **Use standard OPL waveform names**
+- **FM parameter editor layout:**
+  - **Modern**
+  - **Compact (2x2, classic)**
+  - **Compact (1x4)**
+  - **Compact (4x1)**
+  - **Alternate (2x2)**
+  - **Alternate (1x4)**
+  - **Alternate (4x1)**
+- **Position of Sustain in FM editor:**
+  - **Between Decay and Sustain Rate**
+  - **After Release Rate**
+- **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.
+
+### Statistics
+
+- **Chip memory usage unit:** unit for displaying memory usage in the Statistics window.
+  - **Bytes**
+  - **Kilobytes**
+
+### Oscilloscope
+
+- **Rounded corners**
+- **Border**
+- **Mono**: displays a single monaural waveform of all sound mixed together.
+  - if turned off, waves will be drawn on top of each other for each output channel. 
+  - all colors are configurable via _Settings > Color > Color scheme > Oscilloscope > Wave (non-mono)._
+- **Anti-aliased**: smoothes the lines of the waveform.
+  - slight performance cost and slightly buggy.
+- **Fill entire window**: removes the gap between the waveform and the edge of the window.
+- **Waveform goes out of bounds**: allows the waveform to draw past the top and bottom of the oscilloscope.
+
+### Windows
+
 - **Rounded window corners**
 - **Rounded buttons**
 - **Rounded menu corners**
-- **Borders around widgets**
-- **Disable fade-in during start-up**
-  
-- **Oscilloscope settings:**
-  - **Rounded corners**
-  - **Fill entire window**
-  - **Waveform goes out of bounds**
-  - **Border**
-
-- **Pattern view spacing after:**
-  - **Note**
-  - **Instrument**
-  - **Volume**
-  - **Effect**
-  - **Effect value**
-- **Color scheme**
-  - **Import**
-  - **Export**
-  - **Reset defaults**
-  - **General**
-    - **Color scheme type:**
-      - **Dark**
-      - **Light**
-    - **Frame shading**
-  - several more categories...
+- **Borders around widgets**: draws thin borders on buttons, checkboxes, text widgets, and the like.
 
 
 
-# Keyboard
+## Color
+
+### Color scheme
 
 - **Import**
 - **Export**
 - **Reset defaults**
-- several categories of keybinds...
-  - click on a keybind then enter a key or key combination to change it
-  - right-click to clear the keybind
+- **General**
+  - **Color scheme type:**
+    - **Dark**
+    - **Light**
+  - **Frame shading**: applies a gradient effect to buttons and input boxes.
+- several more categories...

doc/2-interface/song-info.md

@@ -1,13 +1,13 @@
 # song info
 
 - **Name**: The track's title.
-- **Author**: List of contributors to a song. If the song is a cover of someone else's track, it's customary to list their name first, followed by `[cv. YourName]`.
+- **Author**: List of contributors to a song. If the song is a cover of someone else's work, it's customary to list their name first, followed by `[cv. YourName]`.
 - **Album**: The associated album name, the name of the game the song is from, or whatever.
-- **System**: The game console or computer the track is designed for. This is automatically set when creating a new tune, but it can be changed to anything one wants. The **Auto** button will provide a guess based on the chips in use.
+- **System**: The game console or computer the track is designed for. This is automatically set when creating a new tune, but in advanced mode, it can be changed to anything one wants. The **Auto** button will provide a guess based on the chips in use.
 
 All of this metadata will be included in a VGM export. This isn't the case for a WAV export, however.
 
-**Tuning (A-4)**: Set tuning based on the note A-4, which should be 440 in most cases. Opening an Amiga MOD will set it to 436 for hardware compatibility.
+- _**Tuning (A-4)**:_ Set tuning based on the note A-4, which should be 440 in most cases. Opening an Amiga MOD will set it to 436 for hardware compatibility. Available only in advanced mode.
 
 # subsongs
 
@@ -23,6 +23,8 @@ This window allows one to create **subsongs** - multiple individual songs within
 
 There are multiple ways to set the tempo of a song.
 
+Items in _italics_ don't appear in basic mode and are only available in advanced mode.
+
 **Tick Rate**: The frequency of ticks per second, thus the rate at which notes and effects are processed.
 - All values are allowed for all chips, though most chips have hardware limitations that mean they should stay at either 60 (approximately NTSC) or 50 (exactly PAL).
 - Clicking the Tick Rate button switches to a more traditional **Base Tempo** BPM setting.
@@ -30,14 +32,14 @@ There are multiple ways to set the tempo of a song.
 **Speed**: The number of ticks per row.
 - Clicking the "Speed" button changes to more complex modes covered in the [grooves] page.
 
-**Virtual Tempo**: Simulates any arbitrary tempo without altering the tick rate. It does this by adding or skipping ticks to approximate the tempo. The two numbers represent a ratio applied to the actual tick rate. Example:
+_**Virtual Tempo**:_ Simulates any arbitrary tempo without altering the tick rate. It does this by adding or skipping ticks to approximate the tempo. The two numbers represent a ratio applied to the actual tick rate. Example:
 - Set tick rate to 150 BPM (60 Hz) and speed to 6.
 - Set the first virtual tempo number (numerator) to 200.
 - Set the second virtual tempo number (denominator) to 150.
 - The track will play at 200 BPM.
 - The ratio doesn't have to match BPM numbers. Set the numerator to 4 and the denominator to 5, and the virtual BPM becomes 150 × 4/5 = 120.
 
-**Divider**: Changes the effective tick rate. A tick rate of 60Hz and a divisor of 6 will result in ticks lasting a tenth of a second each!
+_**Divider**:_ Changes the effective tick rate. A tick rate of 60Hz and a divisor of 6 will result in ticks lasting a tenth of a second each!
 
 **Highlight**: Sets the pattern row highlights:
 - The first value represents the number of rows per beat.
@@ -46,4 +48,4 @@ There are multiple ways to set the tempo of a song.
 
 **Pattern Length**: The length of each pattern in rows. This affects all patterns in the song, and every pattern must be the same length. (Individual patterns can be cut short by `0Bxx`, `0Dxx`, and `FFxx` commands.)
 
-**Song Length**: How many orders are in the order list. Decreasing it will hide the orders at the bottom. Increasing it will restore those orders; increasing it further will add new orders of all `00` patterns.
+_**Song Length**:_ How many orders are in the order list. Decreasing it will hide the orders at the bottom. Increasing it will restore those orders; increasing it further will add new orders of all `00` patterns.

doc/3-pattern/README.md

@@ -4,41 +4,85 @@ the pattern view allows you to edit the song.
 
 ![pattern view](pattern.png)
 
-a pattern consists of columns ("channels") and rows.
+a pattern consists of columns ("channels") and numbered rows.
 each column has several subcolumns in this order:
 
 1. note
 2. instrument
 3. volume
-4. effect and effect value (several)
+4. effects, split into effect type and effect value
 
 all columns are represented in hexadecimal, except for the note column.
 
-# managing channels
+row highlights show beats and measures, and are configured in the [the Speed window](../2-interface/song-info.md).
 
-you may mute channels, toggle solo mode, collapse channels or even hide them.
 
-clicking on a channel name mutes that channel.
 
-double-clicking or right-clicking it enables solo mode, in where only that channel will be audible.
-
-clicking the `++` at the top left corner of the pattern view displays additional buttons for channel configuration:
-
-![channel bar](channelbar.png)
-
-to rename and/or hide channels, see the Channels window (window > channels).
-
-![channels](channels.png)
-
-# cursor and selection
+## cursor and selection
 
 you may change the cursor position by clicking anywhere on the pattern.
 
-to select, press and hold the left mouse button. then drag the mouse and release the button to finish selection.
+to select an area, press and hold the left mouse button. then drag the mouse and release the button to finish selection.
 
-# keyboard layout
+right-clicking within the pattern view brings up a pop-up menu with everything in the [edit menu](../2-interface/menu-bar.md) that makes sense for entering data or altering a selected area.
 
-## shortcuts
+
+
+## channel bar
+
+using the channel bar, you may adjust several aspects of the channel display.
+
+![channel bar](channelbar.png)
+
+clicking on a channel name mutes that channel.
+
+double-clicking or right-clicking it enables solo mode, in which only that channel will be audible.
+
+clicking the `++` at the top left corner of the pattern view cycles through three channel bar view modes:
+- **Compact**: shows only channel names.
+- **Expanded**: as shown above. adds buttons:
+  - **-**: collapse visible columns. changes to **+** when columns are hidden; click to expand them.
+  - **<**: disables the last effect column and hides it. effects are not deleted...
+  - **>**: adds an effects column. if one previously existed, its contents will be preserved.
+- **Pattern names**: adds a text field with which one can name the current pattern. pattern names are also visible when hovering over a pattern in the order list.
+
+right-clicking the `++` toggles the visualizer, which is active only during playback.
+
+to rename and/or hide channels, open [the Channels window](../8-advanced/channels.md) via the window menu.
+
+
+# input
+
+## note input
+
+![keyboard](keyboard.png)
+
+- pressing any of the respective keys will insert a note at the cursor's location, then advance to the next row (or otherwise according to the Edit Step.)
+- **note off** turns off the last played note in that channel (key off for FM; note cut otherwise).
+- **note release** triggers macro release (and in FM channels it also triggers key off).
+- **macro release** does the same as above, but does not trigger key off in FM channels.
+- **toggle edit** enables and disables editing. when editing is enabled, the cursor's row will be shaded red.
+
+## instrument/volume input
+
+type any hexadecimal number (0-9 and A-F). the cursor will move by the Edit Step when a suitable value is entered.
+
+## effect input
+
+works like the instrument/volume input.
+
+each effect column has two subcolumns: effect and effect value.
+if the effect value is not present, it is treated as `00`.
+
+most effects run until canceled using an effect of the same type with effect value `00`, with some exceptions.
+
+here's [a list of effect types](effects.md).
+
+
+
+# keyboard shortcuts
+
+these are the default key functions. all keys are configurable in the Keyboard tab of the Settings window.
 
 key         | action
 ------------|-----------------------------------------------------------------
@@ -68,27 +112,3 @@ Ctrl-F2     | transpose selection (+1 semitone)
 Ctrl-F3     | transpose selection (-1 octave)
 Ctrl-F4     | transpose selection (+1 octave)
 Space       | toggle note input (edit)
-
-## note input
-
-![keyboard](keyboard.png)
-
-- pressing any of the respective keys will insert a note at the cursor's location, and then advance it by the Edit Step.
-- note off turns off the last played note in that channel (key off on FM; note cut otherwise).
-- note release triggers macro release (and in FM channels it also triggers key off).
-- macro release does the same as above, but does not trigger key off in FM channels.
-
-## instrument/volume input
-
-type any hexadecimal number (0-9 and A-F). the cursor will move by the Edit Step when a suitable value is entered.
-
-## effect input
-
-works like the instrument/volume input.
-
-each effect column has two subcolumns: effect and effect value.
-if the effect value is not present, it is treated as `00`.
-
-most effects run until canceled using an effect of the same type with effect value `00`, with some exceptions.
-
-for a list of effects [click here](effects.md).

doc/3-pattern/effects.md

@@ -14,7 +14,7 @@ however, effects are continuous, which means you only need to type it once and t
 - `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.
-
+  - ---
 - `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.
@@ -26,16 +26,17 @@ however, effects are continuous, which means you only need to type it once and t
 - `02xx`: **Pitch slide down.**
 - `F1xx`: **Single tick pitch slide up.**
 - `F2xx`: **Single tick pitch slide down.**
-
-- `03xx`: **Portamento.** slides the current note's pitch to the specified note.  `x` is the slide speed.
-  - A note _must_ be present for this effect to work.
+  - ---
+- `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.
+  - the effect stops automatically when it reaches the new note.
 - `E1xy`: **Note slide up.** `x` is the speed, while `y` is how many semitones to slide up.
 - `E2xy`: **Note slide down.** `x` is the speed, while `y` is how many semitones to slide down.
-
-- `EAxx`: **Toggle legato.** while on, notes instantly change the pitch of the currrently playing sound instead of starting it over.
+  - ---
+- `EAxx`: **Toggle legato.** while on, new notes instantly change the pitch of the currently playing sound instead of starting it over.
 - `00xy`: **Arpeggio.** after using this effect the channel will rapidly switch between semitone values of `note`, `note + x` and `note + y`.
 - `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values. default is 1.
-
+  - ---
 - `04xy`: **Vibrato.** changes pitch to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth.
   - Maximum vibrato depth is ±1 semitone.
 - `E3xx`: **Set vibrato direction.** `xx` may be one of the following:
@@ -54,7 +55,7 @@ not all chips support these effects.
 - `82xx`: **Set volume of right channel** (from `00` to `FF`).
 - `89xx`: **Set volume of rear left channel** (from `00` to `FF`).
 - `8Axx`: **Set volume of rear right channel** (from `00` to `FF`).
-
+  - ---
 - `80xx`: **Set panning (linear).** this effect behaves more like other trackers:
   - `00` is left.
   - `80` is center.
@@ -64,15 +65,15 @@ not all chips support these effects.
 
 - `09xx`: **Set speed/groove.** if no grooves are defined, this sets speed. If alternating speeds are active, this sets the first speed.
 - `0Fxx`: **Set speed 2.** during alternating speeds or a groove, this sets the second speed.
-
+  - ---
 - `Cxxx`: **Set tick rate.** changes tick rate to `xxx` Hz (ticks per second).
   - `xxx` may be from `000` to `3FF`.
 - `F0xx`: **Set BPM.** changes tick rate according to beats per minute. range is `01` to `FF`.
-
+  - ---
 - `0Bxx`: **Jump to order.** `x` is the order to play after the current row.
   - this marks the end of a loop with order `x` as the loop start.
-- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order.
-  - this can be used to shorten the current order.
+- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order. `x` is the row at which to start playing the next pattern.
+  - this can be used to shorten the current order as though it had a different pattern length.
 - `FFxx`: **Stop song.** stops playback and ends the song. `x` is ignored.
 
 ## note
@@ -86,12 +87,12 @@ not all chips support these effects.
 
 - `9xxx`: **Set sample position.** jumps current sample to position `xxx * 0x100`.
   - Not all chips support this effect.
-- `EBxx`: **Set sample bank.**
-  - Does not apply on Amiga.
+- `EBxx`: **Set LEGACY sample mode bank.** selects sample bank. used only for compatibility.
+  - does not apply on Amiga.
 - `EExx`: **Send external command.**
-  - This effect is currently incomplete.
-- `F5xx`: **Disable macro.** see macro table at the end of this document for possible values.
-- `F6xx`: **Enable macro.**
+  - this effect is currently incomplete.
+- `F5xx`: **Disable macro.**\
+  `F6xx`: **Enable macro.** see macro table at the end of this document for possible values.
 
 additionally, [each chip has its own effects](../7-systems/README.md).
 

doc/4-instrument/README.md

@@ -1,14 +1,16 @@
-# instrument list
-
-![instrument list](list.png)
-
-click on an instrument to select it.
-
-double-click to open the instrument editor.
-
 # instrument editor
 
-every instrument can be renamed and have its type changed.
+the instrument editor always starts with this section:
+
+![top of instrument editor](instrument-editor-top.png)
+
+- top-left numeric dropdown: instrument selector.
+- folder icon: open an instrument file.
+- save icon: save current instrument as a file.
+  - right-clicking gives the option to save a .dmp format DefleMask preset.
+- **Name**: instrument name.
+- **Type**: the system for which the instrument is intended.
+  - if changed, all applicable settings and macros will remain as they are. numbers will not be adjusted.
 
 depending on the instrument type, there are many different types of instrument editor:
 
@@ -23,7 +25,7 @@ depending on the instrument type, there are many different types of instrument e
 - [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source.
 - [TIA](tia.md) - for use with Atari 2600 chip.
 - [AY-3-8910](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610.
-- [Amiga / sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
+- [Generic Sample](amiga.md) for controlling Amiga and other sample channels/chips like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
 - [Atari Lynx](lynx.md) - for use with Atari Lynx handheld console.
 - [VERA](vera.md) - for use with Commander X16 VERA.
 - [Seta/Allumer X1-010](x1_010.md) - for use with Wavetable portion in Seta/Allumer X1-010.
@@ -32,6 +34,7 @@ depending on the instrument type, there are many different types of instrument e
 - [Konami VRC6](vrc6.md) - for use with VRC6's PSG sound source.
 - [SNES](snes.md) - for use with SNES S-APU.
 - [Casio PV-1000](pv1000.md) - for use with Casio PV-1000.
+- [C140](c140.md) for use with Namco C140.
 
 
 # macros
@@ -47,8 +50,9 @@ The very first numeric entry sets the visible width of the bars in sequence-type
 Each macro has two buttons on the left.
 - Macro type (explained below).
 - Timing editor, which pops up a small dialog:
-  - Step Length (ticks): Determines how many ticks pass before each change of value.
-  - Delay: Delays the start of the macro until this many ticks have passed.
+  - Step Length (ticks): Determines how many ticks pass before each change of value. Default is 1.
+  - Delay: Delays the start of the macro until this many ticks have passed. Default is 0.
+  - The button is highlighted if either of these is set differently from default.
 
 ## macro types
 
@@ -66,14 +70,16 @@ Some macros are "bitmap" style. They represent a number of "bits" that can be to
 
 The number between the macro type label and the macro type button is the macro length in steps. The `-` and `+` buttons change the length of the macro. Start out by adding at least a few steps.
 
-The values of the macro can be drawn in the "bar graph box". Just beneath the box is shorter bar graph.
-- Click to set the start point of a loop; the end point is the last value or release point. Right-click to remove the loop.
-- Shift-click to set the release point. When played, the macro will hold here until the note is released. Right-click to remove the release point.
+The values of the macro can be drawn in the "bar graph" box.
+
+Just beneath the box is a shorter bar that controls looping.
+- Click to set the start point of a loop; the end point is the last value or release point. It appears as half-height bars. Right-click to remove the loop.
+- Shift-click to set the release point. When played, the macro will hold here until the note is released. It appears as a full-height bar. Right-click to remove the release point.
 
 Finally, the sequence of values can be directly edited in the text box at the bottom.
 - The loop start is entered as a `|`.
 - The release point is entered as a `/`.
-- In arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). No matter the note played, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods.
+- In arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). No matter the note entered in the pattern, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods.
 
 ### ADSR
 
@@ -100,15 +106,29 @@ Finally, the sequence of values can be directly edited in the text box at the bo
 - **Phase** is which part of the waveform the macro will start at, measured in 1/1024 increments.
 - **Shape** is the waveform used. Triangle is the default, and Saw and Square are exactly as they say.
 
-# samples
+
+
+# wavetable
+
+This tab appears for PC Engine, FDS, Namco WSG, and other wavetable-based instruments.
+
+![wavetable tab](wavetable.png)
+
+When **Enable synthesizer** is off, the wavetable used for the instrument may be selected by creating a Waveform macro with a single value.
+
+To use the wavetable synthesizer, refer to the bottom part of [the wavetable documentation](../5-wave/README.md).
+
+
+# sample
 
 This tab appears for Generic PCM, SNES, Amiga, and other sample-based instruments.
 
-![](sample-map.png)
+![sample tab](sample-map.png)
 
 - **Initial Sample**: the sample that the instrument will use.
 - **Use wavetable**: instead of samples, use wavetables. this causes the [Wavetables](../5-wave/README.md) tab to appear next to Sample.
   - depending on the system and use of the wavetable synthesizer, this may or may not be reproducible on hardware.
 - **Use sample map**: assigns a sample to each note.
-  - samples will be played at their default pitch.
-  - to set a note's sample, click the list entry in the `#` column then type the number of the sample.
+  - to set a note's sample, click the list entry in the "#" column then type the number of the sample.
+  - to set the pitch at which a sample is played, click the list entry in the "note" column and press the key for the new note.
+

doc/4-instrument/amiga.md

@@ -1,17 +1,18 @@
 # Amiga/PCM sound source instrument editor
 
-The PCM instrument editor consists of a sample selector and several macros:
+The Generic Sample instrument editor consists of a sample selector and several macros:
 
-# Amiga/sample
+# Sample
 
 - **Initial sample**: specifies which sample should be assigned to the instrument, or the first one in the sequence
+- **Use sample map**: enables mapping different samples to notes.
 
 # Macros
 
-- **Volume**: volume sequence. _warning:_ it works only on Amiga system, as of version 0.5.5!
-- **Arpeggio**: pitch sequence
-- **Waveform**: sample sequence
-- **Panning (left)**: output level for left channel
-- **Panning (right)**: output level for right channel
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
+- **Volume**: volume sequence. does not apply to some chips.
+- **Arpeggio**: pitch sequence.
+- **Waveform**: waveform sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/c140.md

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

doc/4-instrument/fm.md

@@ -1,47 +1,77 @@
 # FM synthesis instrument editor
 
-FM editor is divided into 7 tabs:
+The FM editor is divided into 7 tabs:
 
 - **FM**: for controlling the basic parameters of FM sound source.
 - **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
-- **Macros (OP1)**: for macros controlling FM paramets of operator 1
-- **Macros (OP2)**: for macros controlling FM paramets of operator 2
-- **Macros (OP3)**: for macros controlling FM paramets of operator 3
-- **Macros (OP4)**: for macros controlling FM paramets of operator 4
-- **Macros**: for miscellaneous macros controlling volume, argeggio and YM2151 noise generator.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and YM2151 noise generator.
 
 ## FM
 
-FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen sliders:
+The FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound.
 
+These apply to the instrument as a whole:
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself. (0-7 range)
+- **Algorithm (AL)**: Determines how operators are connected to each other. (0-7 range)
+  - Left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - Right-click to switch to a preview display of the waveform generated on a new note:
+    - Left-click restarts the preview.
+    - Middle-click pauses and unpauses the preview.
+    - Right-click returns to algorithm view.
+
+- **LFO Frequency Sensitivity**: Determines the amount of LFO frequency changes. (0-7 range)
+- **LFO Amplitude Sensitivity (AM)**: Determines the amount of LFO amplitude changes. (0-3 range)
+
+These apply to each operator:
+- The crossed-arrows button can be dragged to rearrange operators.
+- The **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO.
+- **Hardware Envelope Generator (SSG-EG)**: Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate. YM2610/YM2612 sound source only.
 - **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-31 range)
 - **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-31 range)
-- **Secondary Decay Rate (DR2)/Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-31 range)
+- **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
+- **Secondary Decay Rate (DR2) / Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-31 range)
 - **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
-- **Sustain Level(SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
 - **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.
-- **Envelope Scale (KSR)**: A parameter that determines the degree to which the envelope execution speed increases according to the pitch. (0-3 range)
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (KSR)**: Also known as "Key Scale". Determines the degree to which the envelope execution speed increases according to the pitch. (0-3 range)
 - **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-15 range)
-- **Fine Detune (DT)**: Shifts the pitch a little (0-7 range)
-- **Coarse Detune (DT2)**: Shifts the pitch by tens of cents (0-3 range) WARNING: this parameter affects only YM2151 sound source!!!
-- **Hardware Envelope Generator (SSG-EG)**: Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate. WARNING: this parameter affects only YM2610/YM2612 sound source!!!
-- **Algorithm (AL)**: Determines how operators are connected to each other. (0-7 range)
-- **Feedback (FB)**: Determines the amount of signal whick operator 1 returns to itself. (0-7 range)
-- **Amplitude Modulation (AM)**: Makes the operator affected by LFO.
-- **LFO Frequency Sensitivity**: Determines the amount of LFO frequency changes. (0-7 range)
-- **LFO Amplitude Sensitivity (AM)**: Determines the amount of LFO frequency changes. (0-3 range)
+- **Fine Detune (DT)**: Shifts the pitch a little. (0-7 range)
+- **Coarse Detune (DT2)**: Shifts the pitch by tens of cents. (0-3 range) YM2151 sound source only.
+
+
+## macros
+
+Macros define the sequence of values passed to the given parameter. Via macro, along with the previously mentioned parameters, the following can be controlled:
+
+## FM Macros
+
+- **AM Depth**: amplitude modulation depth. YM2151 sound source only.
+- **PM Depth**: pitch modulation depth. YM2151 sound source only.
+- **LFO Speed**: LFO frequency.
+- **LFO Shape**: LFO shape. Choose between saw, square, triangle, and random.
+- **OpMask**: toggles each operator.
+
+## OP1-OP4 Macros
+
+All parameters are listed above.
 
 ## Macros
 
-Macros define the sequence of values passed to the given parameter. Via macro, aside previously mentioned parameters, the following can be controlled:
-
-- **LFO Frequency**
-- **LFO Waveform**: _WARNING:_ this parameter affects only YM2151 sound source!
-- **Amplitude Modulation Depth**: _WARNING:_ this parameter affects only YM2151 sound source!
-- **Frequency Modulation Depth**: _WARNING:_ this parameter affects only YM2151 sound source!
-- **Arpeggio Macro**: Pitch change sequence in semitones. Two modes are available:  
-  - **Absolute** (default): Executes the pitch with absolute change based on the pitch of the actual note.
-  - **Fixed**: Executes at the pitch specified in the sequence regardless of the note pitch.
+- **Arpeggio**: Pitch change sequence in semitones.
 - **Noise Frequency**: specifies the noise frequency in noise mode of YM2151's Channel 8 Operator 4 special mode.
+- **Panning**: toggles output on left and right channels.
+- **Pitch**: fine pitch.
+  - **Relative**: pitch changes are relative to the current pitch, not the note's base pitch.
+- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
 
-Looping: You can loop the execution of part of a sequence. Left-click anywhere on the Loop line at the bottom of the editor to create a loop. You can move the start and end points of the loop by dragging both ends of the loop. Rigkt-click to remove the loop.
+
+# links
+
+[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. This was made for DefleMask, but all the same principles apply.

doc/4-instrument/fmopl.md

@@ -0,0 +1,70 @@
+# OPL FM synthesis instrument editor
+
+The OPL FM editor is divided into 7 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm and feedback
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3 (Warning: only when 4-op flag is set, only on OPL3!)
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4 (Warning: only when 4-op flag is set, only on OPL3!)
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and YMF262 panning.
+
+## FM
+
+The OPL synthesizers are nominally two-operator (OPL3 supports limited 4-operator mode), meaning it takes two oscillators to produce a single sound.
+
+These apply to the instrument as a whole:
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself. (0-7 range)
+- **Algorithm (AL)**: Determines how operators are connected to each other. (0-1 range and OPL1 and OPL2, 0-3 range on OPL3 4op mode)
+  - Left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - Right-click to switch to a preview display of the waveform generated on a new note:
+    - Left-click restarts the preview.
+    - Middle-click pauses and unpauses the preview.
+    - Right-click returns to algorithm view.
+
+- **4-op**: Enables 4-operator FM instrument editor mode (ONLY ON OPL3)
+- **Drums**: Enables OPL drum mode editor
+
+These apply to each operator:
+- The crossed-arrows button can be dragged to rearrange operators.
+- The **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO tremolo.
+- **Sustain flag (SUS)**: When enabled, value of Sustain Level is in effect.
+- **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-15 range)
+- **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-315 range)
+- **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
+- **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
+- **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 63 (decimal) the smallest. A change of one unit is about 0.75 dB.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (KSR)**: Also known as "Key Scale". Determines the degree to which the envelope execution speed increases according to the pitch.
+- **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-10, 12, 15 range)
+- **Waveform select (WS)**: Changes the waveform generated by oscillator (OPL2 and OPL3 only, 0-7 range)
+- **Pitch Modulation (VIB)**: Makes the operator affected by LFO vibrato.
+
+## macros
+
+Macros define the sequence of values passed to the given parameter. Via macro, along with the previously mentioned parameters, the following can be controlled:
+
+## FM Macros
+
+All parameters are listed above.
+
+## OP1-OP4 Macros
+
+All parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: Pitch change sequence in semitones.
+- **Panning**: toggles output on left and right channels. (OPL3 only!)
+- **Pitch**: fine pitch.
+  - **Relative**: pitch changes are relative to the current pitch, not the note's base pitch.
+- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
+
+
+# links
+
+[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. This was made for DefleMask, but all the same principles apply.

doc/4-instrument/fmopll.md

@@ -0,0 +1,66 @@
+# OPLL FM synthesis instrument editor
+
+The OPLL FM editor is divided into 5 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, waveform and feedback
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and preset.
+
+## FM
+
+The OPLL synthesizer is two-operator, meaning it takes two oscillators to produce a single sound.
+
+These apply to the instrument as a whole:
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself. (0-7 range)
+- **Sustain (SUS)**: enables the sustain flag (sets the release rate to 5) 
+- algorithm: shows the connection of operators (though they are always connected the same way).
+  - Right-click to switch to a preview display of the waveform generated on a new note:
+    - Left-click restarts the preview.
+    - Middle-click pauses and unpauses the preview.
+    - Right-click returns to algorithm view.
+- **DC (half-sine carrier)**: Sets the waveform produced by carrier operator to half-sine
+- **DM (half-sine modulator)**: Sets the waveform produced by modulator operator to half-sine
+- preset dropdown: selects OPLL preset instrument.
+
+These apply to each operator:
+- The crossed-arrows button can be dragged to rearrange operators.
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO tremolo.
+- **Envelope generator sustain flag (EGS)**: When enabled, value of Sustain Level is in effect.
+- **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-15 range)
+- **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-15 range)
+- **Sustain Level (SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
+- **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
+- **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 63 (decimal) the smallest. A change of one unit is about 0.75 dB.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (KSR)**: Also known as "Key Scale". Determines the degree to which the envelope execution speed increases according to the pitch.
+- **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-10, 12, 15 range)
+- **Pitch Modulation (VIB)**: Makes the operator affected by LFO vibrato.
+
+## macros
+
+Macros define the sequence of values passed to the given parameter. Via macro, along with the previously mentioned parameters, the following can be controlled:
+
+## FM Macros
+
+All parameters are listed above.
+
+## OP1-OP4 Macros
+
+All parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: Pitch change sequence in semitones.
+- **Patch**: changes the playing preset mid-note
+- **Pitch**: fine pitch.
+  - **Relative**: pitch changes are relative to the current pitch, not the note's base pitch.
+- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
+
+
+# links
+
+[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. This was made for DefleMask, but all the same principles apply.

doc/4-instrument/n163.md

@@ -5,11 +5,11 @@ The Namco 163 instrument editor consists of two tabs: "Namco 163" for control of
 ## Namco 163
 
 - **Load waveform**: if enabled, a waveform will be loaded when this instrument plays.
-  - if it isn't then only the offset/length change.
+  - if it isn't then only the position/length change.
 - **Waveform**: determines the waveform that will be loaded.
   - only appears when Load waveform is enabled.
-- **Per-channel wave offset/length**: when enabled, the offset/length settings are split per channel.
-- **Offset**: determines the waveform position in RAM.
+- **Per-channel wave position/length**: when enabled, the position/length settings are split per channel.
+- **Position**: determines the waveform position in RAM.
 - **Length**: determines the waveform length in RAM.
 
 ## Macros

doc/4-instrument/psg.md

@@ -1,6 +1,6 @@
-# PSG instrument editor
+# Sega PSG instrument editor
 
-The instrument editor for PSG (SMS, MSX, 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.
 - **Arpeggio**: pitch in half-steps.
@@ -11,4 +11,4 @@ The instrument editor for PSG (SMS, MSX, and other TI SN76489 derivatives) consi
   - `3`: long noise, use channel 3 for frequency.
 - **Panning**: output for left and right channels.
 - **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/saa.md

@@ -9,4 +9,12 @@ The SAA1099 instrument editor consists of these macros:
 - **Panning (left)**: output level for left channel
 - **Panning (right)**: output level for right channel
 - **Pitch**: fine pitch
-- **Envelope**: envelope generator shape
+- **Envelope**: envelope generator settings:
+  enable: enables the envelope generator
+  N/A: has no effect
+  fixed: toggles whether to use a fixed frequency or lock to the frequency of channel 2 or 5
+  resolution: increases the envelope generator pitch resolution
+  direction: inverts the waveform around Y axis
+  cut: cuts the waveform (producing saw wave out of tri wave)
+  loop: toggles wheteher evelope is one-off or constantly looping
+  mirror: sets whether the right output will mirror the left one

doc/4-instrument/snes.md

@@ -19,7 +19,15 @@ these tabs are unique to the editor for SNES instruments.
   - **Effective (exponential decrease)**: after release, volume decays exponentially. see [gain chart](../7-systems/snes.md).
   - **Delayed (write R on release)**: after release, waits until A and D have completed before starting exponential decrease.
 
-if envelope is off, select gain mode as described below.
+if envelope is off:
+- **Gain Mode**: selects gain mode.
+  - **Direct**: direct gain from 0 to 127
+  - **Decrease (linear)**: linear gain from -0 to -31
+  - **Decrease (logarithmic)**: exponential gain from -0 to -31
+  - **Increase (linear)**: linear gain from +0 to +31
+  - **Increase (bent line)**: exponential gain from +0 to +31
+  - _note:_ using decrease modes will not produce any sound unless a Gain macro is set. The first tick must be the initial gain, and the second tick must be the decrease gain value. gain values are as described in the Macros section below.
+- **Gain**: value of gain.
 
 
 

doc/4-instrument/ted.md

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

doc/4-instrument/wsg.md

@@ -0,0 +1,11 @@
+# Namco WSG instrument editor
+
+The Namco WSG/C15/C30 instrument editor consists of these macros:
+
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequence
+- **Waveform**: specifies wavetable sequence
+- **Noise**: specifies noise pitch (WARNING: only on C30!)
+- **Panning (left)**: output level of left channel
+- **Panning (right)**: output level of right channel
+- **Pitch**: fine pitch