Merge branch 'master' of https://github.com/tildearrow/furnace into command-palette

.github/workflows/build.yml

@@ -271,7 +271,7 @@ jobs:
         pushd ${{ steps.package-identify.outputs.filename }}
 
         cp -v ../LICENSE LICENSE.txt
-        cp -v ../README.md README.txt
+        cp -v ../res/releaseReadme/unstable-win.txt README.txt
         cp -vr ../papers ../${binPath}/furnace.exe ./
         if [ '${{ matrix.config.compiler }}' == 'msvc' ]; then
           cp -v ../${binPath}/furnace.pdb ./
@@ -285,7 +285,34 @@ jobs:
       run: |
         pushd build
         cpack
-        mv Furnace-*-Darwin.dmg ../${{ steps.package-identify.outputs.filename }}
+
+        mkdir orig
+        mkdir new
+        echo "y" | hdiutil attach Furnace-*-Darwin.dmg -readonly -mount required -mountpoint orig
+
+        cp -v -r orig/Furnace.app new/Furnace.app
+        hdiutil detach orig
+
+        rmdir orig
+        rm Furnace-*-Darwin.dmg
+
+        if [ -e new/Furnace.app/Contents/Resources/bin/furnace ]; then
+          rm -v new/Furnace.app/Contents/Resources/bin/furnace
+          rmdir new/Furnace.app/Contents/Resources/bin
+        fi
+
+        cp -v ../LICENSE new/LICENSE.txt
+        cp -v ../res/releaseReadme/stable-mac.txt new/README
+        cp -v -r ../demos new/demos
+        cp -v -r ../instruments new/instruments
+        cp -v -r ../wavetables new/wavetables
+        cd new
+        wget https://tildearrow.org/furnace/doc/latest/manual.pdf
+        cd ..
+
+        hdiutil create -srcfolder new -volname Furnace -format UDZO furnace.dmg
+        
+        mv furnace.dmg ../${{ steps.package-identify.outputs.filename }}
         popd
 
     - name: Package [Linux]
@@ -317,7 +344,7 @@ jobs:
         cd ..
 
         cp ../../LICENSE .
-        cp ../../README.md .
+        cp ../../res/releaseReadme/unstable-other.txt .
         cp -r ../../papers papers
         rmdir usr
 

.gitignore

@@ -27,5 +27,11 @@ CMakePresets.json
 extern/imgui_patched/examples/
 src/asm/68k/amigatest/*.bin
 src/asm/68k/amigatest/player
+src/check/calc_checksum
 res/binary_to_compressed_c
 res/binary_to_compressed_c.exe
+res/docpdf/manual.html
+res/docpdf/manual.pdf
+res/docpdf/.venv
+res/docpdf/htmldoc/
+res/furnace.appdata.xml

CMakeLists.txt

@@ -8,6 +8,7 @@ project(furnace)
 
 if (APPLE)
   enable_language(OBJC)
+  enable_language(OBJCXX)
 endif()
 
 set(CMAKE_CXX_STANDARD 14)
@@ -25,6 +26,15 @@ set(SYSTEM_SDL2_DEFAULT OFF)
 include(CheckIncludeFile)
 include(TestBigEndian)
 
+execute_process(COMMAND git status RESULT_VARIABLE DONT_HAVE_GIT WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+if (NOT DONT_HAVE_GIT)
+  message(STATUS "Git is available")
+else()
+  message(WARNING "either Git is not available, or this Git repository has not been initialized.
+if you have used the \"Source code\" option in the GitHub release page, you are doing it wrong! unless you manually initialize submodules, the build is guaranteed to FAIL spectacularly!
+read the \"developer info\" section of README.md for more information.")
+endif()
+
 if (ANDROID)
   set(USE_RTMIDI_DEFAULT OFF)
   set(WITH_PORTAUDIO_DEFAULT OFF)
@@ -85,8 +95,10 @@ option(WITH_RENDER_SDL "Whether to build with the SDL_Renderer render backend."
 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})
 option(USE_GLES "Use OpenGL ES for the OpenGL render backend." ${USE_GLES_DEFAULT})
+option(USE_FREETYPE "Use FreeType for font rendering." ON)
 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_FREETYPE "Use a system-installed version of FreeType 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)
@@ -98,7 +110,7 @@ option(WITH_DEMOS "Install demo songs" ON)
 option(WITH_INSTRUMENTS "Install instruments" ON)
 option(WITH_WAVETABLES "Install wavetables" ON)
 
-set(DEPENDENCIES_INCLUDE_DIRS "")
+set(DEPENDENCIES_INCLUDE_DIRS extern/IconFontCppHeaders src/icon)
 
 if (ANDROID AND NOT TERMUX)
   set(DEPENDENCIES_DEFINES "IS_MOBILE")
@@ -182,6 +194,39 @@ else()
   message(STATUS "Using vendored fmt")
 endif()
 
+if (BUILD_GUI AND USE_FREETYPE)
+  # TODO: FIX FIX FIX FIX FIX
+  if (SYSTEM_FREETYPE)
+    if (PKG_CONFIG_FOUND)
+      pkg_check_modules(FREETYPE freetype>=2.0.0)
+      if (FREETYPE_FOUND)
+        list(APPEND DEPENDENCIES_INCLUDE_DIRS ${FMT_INCLUDE_DIRS})
+        list(APPEND DEPENDENCIES_COMPILE_OPTIONS ${FMT_CFLAGS_OTHER})
+        list(APPEND DEPENDENCIES_LIBRARIES ${FMT_LIBRARIES})
+        list(APPEND DEPENDENCIES_LIBRARY_DIRS ${FMT_LIBRARY_DIRS})
+        list(APPEND DEPENDENCIES_LINK_OPTIONS ${FMT_LDFLAGS_OTHER})
+        list(APPEND DEPENDENCIES_LEGACY_LDFLAGS ${FMT_LDFLAGS})
+      endif()
+    endif()
+    if (NOT FREETYPE_FOUND)
+      find_package(freetype REQUIRED)
+      list(APPEND DEPENDENCIES_LIBRARIES freetype::freetype)
+    endif()
+    message(STATUS "Using system-installed FreeType")
+  else()
+    set(FT_DISABLE_BROTLI ON CACHE BOOL "one" FORCE)
+    set(FT_DISABLE_BZIP2 ON CACHE BOOL "two" FORCE)
+    set(FT_DISABLE_HARFBUZZ ON CACHE BOOL "three" FORCE)
+    set(FT_DISABLE_PNG ON CACHE BOOL "four" FORCE)
+    set(FT_DISABLE_ZLIB ON CACHE BOOL "five" FORCE)
+    add_subdirectory(extern/freetype EXCLUDE_FROM_ALL)
+    list(APPEND DEPENDENCIES_INCLUDE_DIRS extern/freetype/include)
+    list(APPEND DEPENDENCIES_LIBRARIES freetype)
+    message(STATUS "Using vendored FreeType")
+  endif()
+  list(APPEND DEPENDENCIES_DEFINES HAVE_FREETYPE)
+endif()
+
 if (USE_SNDFILE)
   list(APPEND DEPENDENCIES_DEFINES HAVE_SNDFILE)
   if (SYSTEM_LIBSNDFILE)
@@ -211,7 +256,7 @@ endif()
 if (WITH_PORTAUDIO)
   if (SYSTEM_PORTAUDIO)
     find_package(PkgConfig REQUIRED)
-    pkg_check_modules(PORTAUDIO REQUIRED portaudio)
+    pkg_check_modules(PORTAUDIO REQUIRED portaudio-2.0)
     list(APPEND DEPENDENCIES_INCLUDE_DIRS ${PORTAUDIO_INCLUDE_DIRS})
     list(APPEND DEPENDENCIES_COMPILE_OPTIONS ${PORTAUDIO_CFLAGS_OTHER})
     list(APPEND DEPENDENCIES_LIBRARIES ${PORTAUDIO_LIBRARIES})
@@ -315,6 +360,11 @@ if (USE_SDL2)
       set(SDL_RENDER_D3D OFF CACHE BOOL "Enable the Direct3D render driver" FORCE)
     endif()
 
+    CHECK_INCLUDE_FILE(GLES/gl.h GLES_GL_FOUND)
+    if (NOT GLES_GL_FOUND AND NOT USE_GLES)
+      set(SDL_OPENGLES OFF CACHE BOOL "Enable OpenGL ES" FORCE)
+    endif()
+
     add_subdirectory(extern/SDL EXCLUDE_FROM_ALL)
     list(APPEND DEPENDENCIES_DEFINES HAVE_SDL2)
     list(APPEND DEPENDENCIES_INCLUDE_DIRS extern/SDL/include)
@@ -357,14 +407,16 @@ endif()
 if (WITH_JACK)
   find_package(PkgConfig REQUIRED)
   pkg_check_modules(JACK REQUIRED jack)
+  list(APPEND AUDIO_SOURCES extern/weakjack/weak_libjack.c)
   list(APPEND AUDIO_SOURCES src/audio/jack.cpp)
   list(APPEND DEPENDENCIES_INCLUDE_DIRS ${JACK_INCLUDE_DIRS})
   list(APPEND DEPENDENCIES_DEFINES HAVE_JACK)
-  list(APPEND DEPENDENCIES_COMPILE_OPTIONS ${JACK_CFLAGS_OTHER})
-  list(APPEND DEPENDENCIES_LIBRARIES ${JACK_LIBRARIES})
-  list(APPEND DEPENDENCIES_LIBRARY_DIRS ${JACK_LIBRARY_DIRS})
-  list(APPEND DEPENDENCIES_LINK_OPTIONS ${JACK_LDFLAGS_OTHER})
-  list(APPEND DEPENDENCIES_LEGACY_LDFLAGS ${JACK_LDFLAGS})
+  list(APPEND DEPENDENCIES_DEFINES USE_WEAK_JACK)
+  #list(APPEND DEPENDENCIES_COMPILE_OPTIONS ${JACK_CFLAGS_OTHER})
+  #list(APPEND DEPENDENCIES_LIBRARIES ${JACK_LIBRARIES})
+  #list(APPEND DEPENDENCIES_LIBRARY_DIRS ${JACK_LIBRARY_DIRS})
+  #list(APPEND DEPENDENCIES_LINK_OPTIONS ${JACK_LDFLAGS_OTHER})
+  #list(APPEND DEPENDENCIES_LEGACY_LDFLAGS ${JACK_LDFLAGS})
   message(STATUS "Building with JACK support")
 else()
   message(STATUS "Building without JACK support")
@@ -437,6 +489,9 @@ extern/Nuked-PSG/ympsg.c
 extern/opm/opm.c
 extern/Nuked-OPLL/opll.c
 extern/opl/opl3.c
+
+src/pch.cpp
+
 src/engine/platform/sound/sn76496.cpp
 src/engine/platform/sound/ay8910.cpp
 src/engine/platform/sound/saa1099.cpp
@@ -550,6 +605,7 @@ 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
@@ -564,6 +620,7 @@ src/engine/filter.cpp
 src/engine/instrument.cpp
 src/engine/macroInt.cpp
 src/engine/pattern.cpp
+src/engine/pitchTable.cpp
 src/engine/playback.cpp
 src/engine/sample.cpp
 src/engine/song.cpp
@@ -761,6 +818,10 @@ if (WIN32 AND NOT SUPPORT_XP)
   list(APPEND GUI_SOURCES extern/nfd-modified/src/nfd_win.cpp)
 endif()
 
+if (USE_FREETYPE)
+  list(APPEND GUI_SOURCES extern/imgui_patched/misc/freetype/imgui_freetype.cpp)
+endif()
+
 if (APPLE)
   list(APPEND GUI_SOURCES extern/nfd-modified/src/nfd_common.cpp)
   list(APPEND GUI_SOURCES src/gui/macstuff.m)
@@ -859,7 +920,6 @@ if (BUILD_GUI)
   list(APPEND DEPENDENCIES_INCLUDE_DIRS
     extern/imgui_patched
     extern/imgui_patched/backends
-    extern/IconFontCppHeaders
     extern/igfd
   )
   if (WIN32 OR APPLE)
@@ -920,6 +980,15 @@ if (WARNINGS_ARE_ERRORS)
   )
 endif()
 
+if (NOT ANDROID OR TERMUX)
+  if (NOT WIN32 AND NOT APPLE)
+    if (NOT DONT_HAVE_GIT)
+      add_custom_command(OUTPUT furnace.appdata.xml COMMAND res/make-appdata.sh ARGS ${CMAKE_SOURCE_DIR}/res/furnace.appdata.xml.in ${CMAKE_BINARY_DIR}/furnace.appdata.xml DEPENDS res/furnace.appdata.xml.in WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+      list(APPEND USED_SOURCES furnace.appdata.xml)
+    endif()
+  endif()
+endif()
+
 if(ANDROID AND NOT TERMUX)
   add_library(furnace SHARED ${USED_SOURCES})
 elseif(WIN32)
@@ -945,12 +1014,29 @@ if (PKG_CONFIG_FOUND AND (SYSTEM_FMT OR SYSTEM_LIBSNDFILE OR SYSTEM_ZLIB OR SYST
   endif()
 endif()
 
+# why 3.16..... why not 3.0?
+if (NOT "${CMAKE_VERSION}" VERSION_LESS "3.16")
+  if (BUILD_GUI)
+  target_precompile_headers(furnace PUBLIC
+    $<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/src/pch.h>
+    $<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/extern/imgui_patched/imgui.h>
+    $<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/extern/imgui_patched/imgui_internal.h>
+  )
+  else()
+    target_precompile_headers(furnace PUBLIC
+      $<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/src/pch.h>
+    )
+  endif()
+endif()
+
 if (NOT ANDROID OR TERMUX)
   if (NOT WIN32 AND NOT APPLE)
     include(GNUInstallDirs)
     install(TARGETS furnace RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
     install(FILES res/furnace.desktop DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
-    install(FILES res/furnace.appdata.xml DESTINATION ${CMAKE_INSTALL_DATADIR}/metainfo)
+    if (NOT DONT_HAVE_GIT)
+      install(FILES ${CMAKE_BINARY_DIR}/furnace.appdata.xml DESTINATION ${CMAKE_INSTALL_DATADIR}/metainfo)
+    endif()
     install(DIRECTORY doc DESTINATION ${CMAKE_INSTALL_DOCDIR})
     install(DIRECTORY papers DESTINATION ${CMAKE_INSTALL_DOCDIR}/other)
     install(FILES LICENSE DESTINATION ${CMAKE_INSTALL_DATADIR}/licenses/furnace)

README.md

@@ -17,7 +17,7 @@ for other operating systems, you may [build the source](#developer-info).
 
 ## features
 
-- over 50 sound chips - and counting:
+- a large selection of sound chips:
   - Yamaha FM chips:
     - YM2151 (OPM)
     - YM2203 (OPN)
@@ -52,6 +52,7 @@ for other operating systems, you may [build the source](#developer-info).
     - Irem GA20
     - Ensoniq ES5506
     - Namco C140
+    - Namco C219
   - wavetable chips:
     - HuC6280 used in PC Engine
     - Konami Bubble System WSG
@@ -102,7 +103,7 @@ for other operating systems, you may [build the source](#developer-info).
 - quality emulation cores (Nuked, MAME, SameBoy, Mednafen PCE, NSFplay, puNES, reSID, Stella, SAASound, vgsound_emu and ymfm)
 - wavetable synthesizer
   - available on wavetable chips
-  - create complex sounds with ease - provide up to two wavetables, select and effect and let go!
+  - create complex sounds with ease - provide up to two wavetables, select an effect and let go!
 - MIDI input support
 - additional features:
   - FM macros!
@@ -127,7 +128,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 90% complete.
+- **help**: check out the [documentation](doc/README.md).
 
 ## packages
 
@@ -135,8 +136,10 @@ for other operating systems, you may [build the source](#developer-info).
 
 some people have provided packages for Unix/Unix-like distributions. here's a list.
 
+- **Flatpak**: yes! Furnace is now available on [Flathub](https://flathub.org/apps/org.tildearrow.furnace) thanks to ColinKinloch.
+
 - **Arch Linux**: [furnace](https://archlinux.org/packages/extra/x86_64/furnace/) is in the official repositories.
-- **FreeBSD**: [a package in ports](https://www.freshports.org/audio/furnace/) is available courtesy of ehaupt (warning: 0.5.8!).
+- **FreeBSD**: [a package in ports](https://www.freshports.org/audio/furnace/) is available courtesy of ehaupt.
 - **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.
@@ -251,7 +254,8 @@ Available options:
 | `USE_SDL2` | `ON` | Build with SDL2 (required to build with GUI) |
 | `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 |
+| `USE_FREETYPE` | `OFF` | Build with FreeType support |
+| `WITH_JACK` | auto\* | 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 |
@@ -259,12 +263,17 @@ Available options:
 | `SYSTEM_RTMIDI` | `OFF` | Use a system-installed version of RtMidi instead of the vendored one |
 | `SYSTEM_ZLIB` | `OFF` | Use a system-installed version of zlib instead of the vendored one |
 | `SYSTEM_SDL2` | `OFF` | Use a system-installed version of SDL2 instead of the vendored one |
+| `SYSTEM_FREETYPE` | `OFF` | Use a system-installed version of SDL2 instead of the vendored one |
 | `SUPPORT_XP` | `OFF` | Build a Windows XP-compatible binary |
-| `WARNINGS_ARE_ERRORS` | `OFF` (but consider enabling this & reporting any errors that arise from it!) | Whether warnings in furnace's C++ code should be treated as errors |
+| `WARNINGS_ARE_ERRORS` | `OFF`\*\* | Whether warnings in furnace's C++ code should be treated as errors |
 | `WITH_DEMOS` | `ON` | Install demo songs on `make install` |
 | `WITH_INSTRUMENTS` | `ON` | Install demo instruments on `make install` |
 | `WITH_WAVETABLES` | `ON` | Install wavetables on `make install` |
 
+(\*) `ON` if system-installed JACK detected, otherwise `OFF`
+
+(\*\*) but consider enabling this & reporting any errors that arise from it!
+
 ## CMake Error
 
 if it says something about a missing subdirectory in `extern`, then either:
@@ -326,7 +335,7 @@ it is in [doc/](doc/README.md).
 
 > is there a tutorial?
 
-sadly, the in-program tutorial isn't ready yet. however, [a video tutorial is available on YouTube](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1), made by Spinning Square Waves.
+[a video tutorial (of a previous version) is available on YouTube](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1), made by Spinning Square Waves.
 
 > I've lost my song!
 

TODO.md

@@ -1,12 +1,21 @@
-# to-do for 0.6pre7
+# to-do
 
-- tutorial?
-- ease-of-use improvements... ideas:
-  - preset compat flags
-  - maybe reduced set of presets for the sake of simplicity
-  - a more preferable highlight/drag system
-  - some speed/intuitive workflow improvements that go a long way 
-  - make .pdf manual out of doc/
-  - break compatibility if it relieves complexity
-- multi-key binds
-- bug fixes
+- add cheat code to insert bruno time (blank)
+
+# THE REAL TO-DO LIST
+
+- Amiga's Period Modulation not working
+- Song is silent after playing an order after loop point
+- Select loaded instrument on open - rewrite because I want a setting...
+- re-engineer volume handling? Sound Unit cries at me
+- finish status view
+- finish auto-clone
+
+once you have done all of this (maybe not the first one) and merged the two or so pending pull requests, release 0.6.1
+
+Furnace is like alcohol...
+
+# and then
+
+- new oscilloscope renderer - custom code that uses texture and fixes two issues: too many vertices, and broken anti-aliasing
+- new pattern renderer - performance improvements

android/app/build.gradle

@@ -15,8 +15,8 @@ android {
         }
         minSdkVersion 21
         targetSdkVersion 26
-        versionCode 169
-        versionName "0.6pre9"
+        versionCode 181
+        versionName "0.6"
         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="169"
-    android:versionName="0.6pre9"
+    android:versionCode="181"
+    android:versionName="0.6"
     android:installLocation="auto">
 
     <!-- OpenGL ES 2.0 -->

doc/1-intro/README.md

@@ -12,9 +12,11 @@ Furnace uses hexadecimal (abbreviated as "hex") numbers frequently. see [this gu
 
 ## interface
 
-Furnace uses a music tracker interface. think of a table with music notes written on it. then that table scrolls up and plays the notes. even experienced tracker musicians might benefit from a quick review of [tracker concepts and terms](concepts.md) before using Furnace.
+Furnace uses a music tracker interface. think of a table with music notes written on it. then that table scrolls up and plays the notes.
+for an introduction to a tracker interface, see [tracker concepts and terms](concepts.md) before using Furnace.
+there's also a [glossary of common terms](glossary.md).
 
-due to its nature of being feature-packed, it may be technical and somewhat difficult to get around. therefore we added a basic mode, which hides several advanced features.
+due to its nature of being feature-packed, it may be technical and somewhat difficult to get around. therefore we added a [basic mode](../2-interface/basic-mode.md), which hides several advanced features.
 
 it also has a flexible windowing system which you may move around and organize.
 
@@ -22,8 +24,6 @@ see [2-interface](../2-interface/README.md) and [3-pattern](../3-pattern/README.
 
 once familiar with the tracker, look to [9-guides](../9-guides/README.md) for useful techniques.
 
+## tutorial?
 
-
-# links
-
-[Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves.
+[Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves. be noted that these may not apply to the current version.

doc/1-intro/concepts.md

@@ -1,36 +1,39 @@
 # concepts and terms
 
-- A **module** is a file for a tracker that contains at least one **song**.
-- Each Furnace module involves at least one **[chip](../7-systems/README.md)**, an emulation of a specific audio processor.
+- a **song** (also called **module**) is a file for a tracker that contains at least one **subsong**.
+- each Furnace song involves at least one **chip**, an emulation of a specific audio processor.
 
 ## tracking
 
-The **[pattern view](../3-pattern/README.md)** is like a spreadsheet that displays the following:
-- Each labeled column represents a **channel** of sound provided by the chips in use.
-- Each **note** starts a sound playing. Within a channel, only one note can play at a time.
-- Each note is assigned an **[instrument](../4-instrument/README.md)** which describes what it will sound like.
-- An **effect** is a command that changes some aspect of playback. It can alter note pitch, volume, timing, and more.
-- An instrument **macro** is an automated sequence of effects that applies to every note of that instrument.
+the **[pattern view](../3-pattern/README.md)** is similar to spreadsheet that displays the following:
+- each labeled column represents a **channel** of sound provided by the chips in use.
+- each **note** starts a sound playing. within a channel, only one note can play at a time.
+- each note is assigned an **[instrument](../4-instrument/README.md)** which describes what it will sound like.
+- an **effect** is a command that changes some aspect of playback. it can alter note pitch, volume, timing, and more.
+- an instrument **macro** is an automated sequence of effects that applies to every note of that instrument.
+- during playback, the **playhead** moves down, scrolling through the pattern view, triggering the notes that it encounters.
 
 ## 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.
-- Each channel has its own unique list of patterns.
-- 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.
+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.
+- each channel has its own unique list of patterns.
+- 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.
+- each pattern is made of the same number of rows as seen in the tracker view.
+- during playback, the **playhead** moves down as described previously. when it reaches the end of the pattern view, it will go to the next order.
+- if the last order is reached and the playhear reaches the end of the pattern view, it will go back to the beginning of the song.
 
 ## 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.
+- during playback, each **row** lasts a number of ticks determined by the song's **speed** value(s).
+- 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)** 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.
+sound 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)** 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)** which are (usually) recordings of sounds, often with defined loop points to allow a note to sustain.
+- some channels use **[wavetables](../5-wave/README.md)**, which are very short samples of fixed length that automatically loop.

doc/1-intro/glossary.md

@@ -0,0 +1,143 @@
+# glossary of common terms
+
+**2-op**, **3-op**, **4-op**...: the number of FM operators used to generate a sound. more operators allow for more complex sounds.
+
+**ADPCM**: adaptive differential pulse code modulation. this is a variety of DPCM with a more complex method of storing the amplitude differences.
+
+**ADSR**: attack, decay, sustain and release. these are elements that comprise a basic envelope.
+
+**algorithm**: the way in which the operators in an FM instrument interact.
+- when two operators connect to the same point, their sounds are added together.
+- when two operators are connected left to right, the left is the modulator and the right is the carrier sound that is modified.
+
+**asset**: an instrument, wavetable or sample.
+
+**bitbang**: to achieve PCM sound by sending a rapid stream of volume commands to a non-PCM channel.
+
+**bitmask**: a set of bits which represent individual single-bit toggles or groups representing small numbers. these are explained fully in the [hexadecimal primer](hex.md).
+
+**BRR**: a lossy sample format used by the SNES. it has a fixed compression ratio; groups of 32 bytes (16 samples) are encoded in 9 bytes each.
+- usually stored in .brr files.
+
+**clipping**: when a sample or playback stream exceeds the maximum or minimum values. this can cause audible distortion.
+- this often occurs when a sample is amplified too much.
+- it can also occur during playback if too much sound is being added together at once. in some cases the mixer can be used to reduce the volume. if this doesn't work, the clipping is caused within the chip's own mixing, and the only solution is to reduce the volumes of the notes being played.
+
+**clock rate**: the timing at which a chip operates, expressed as cycles per second (Hz).
+- changing this may change aspects of how some chips work, most notably pitch.
+- some chips cannot operate at anything other than their designed clock rate.
+
+**cursor (1)**: the marker of input focus. anything typed will happen at the cursor's location.
+
+**cursor (2)**: the pointer controlled by a mouse or similar input. clicking when the cursor(2) is in a valid area will place the cursor(1) there.
+
+**DAC**: digital analog converter. this converts a digital representation of sound into actual output.
+
+**.dmf**: DefleMask Module File.
+- _Furnace:_ .dmf files may be read, and compatibility flags will be set to make them play as accurately as possible, but there may still be glitches.
+- _Furnace:_ .dmf files may be saved, but full compatibility isn't guaranteed and many features will be missing. this isn't recommended unless absolutely necessary.
+
+**.dmp**: DefleMask Preset. an instrument file.
+
+**.dmw**: DefleMask Wavetable. a wavetable file.
+
+**DPCM**: differential/delta pulse code modulation. this is a variety of PCM that stores each amplitude as its difference from the previous.
+
+**duty cycle**: usually called _pulse width._ in a pulse wave, this is the ratio of the high part to the high and low combined.
+
+**feedback**: in FM instruments, this adds some of an operator's output into itself to create complex harmonics.
+- in the algorithm view, an operator with a circle around it is capable of feedback.
+
+**FM**: frequency modulation. this is a method of generating sound that uses one operator's amplitude to modify another operator's frequency.
+- the FM in Yamaha chips is more accurately called _phase modulation,_ which uses a different method of computation to achieve similar results.
+
+**.fui**: a Furnace instrument file.
+
+**.fur**: a Furnace module file.
+
+**.fuw**: a Furnace wavetable file.
+
+**hard-pan**: sounds can only be panned all the way to one side or the other, not in-between.
+
+**Hz**: hertz. a unit representing divisions of one second. 1 Hz means once per second; 100 Hz means one hundred times per second. also, _kHz_ (kilohertz, one thousand per second) and _MHz_ (megahertz, one million per second).
+
+**interpolate**: to fill in the area between two values with a smooth ramp of values in between.
+- some sample-based chips can interpolate, filtering out unwanted harmonics.
+
+**ladder effect**: an inaccurate yet common term for the DAC distortion that affects some Yamaha FM chips.
+
+**LFO**: low frequency oscillator. a wave with a slow period (often below hearing range) used to alter other sounds.
+
+**macro**: a sequence of values automatically applied while a note plays.
+
+**noise bass**: the technique of using a PSG's periodic noise generator with a very short period to create low-frequency sounds.
+
+**normalize**: to adjust the volume of a sample so it is as loud as possible without adding distortion from clipping.
+
+**operator**: in FM, a single oscillator that interacts with other oscillators to generate sound.
+
+**oscillator**: a sine wave or other basic waveform used as sound or to alter sound.
+
+**PCM**: pulse code modulation. a stream of data that represents sound as a rapid sequence of amplitudes.
+
+**period**: the length of a repeating waveform. as frequency rises, the period shortens.
+
+**periodic noise**: an approximation of random noise generated algorithmically.
+- the period is the number of values generated until the algorithm repeats itself.
+
+**phase reset**: to restart a waveform at its initial value.
+- for FM instruments, this restarts the volume envelope also.
+
+**PSG**: programmable sound generator. any sound chip is a PSG, though the term is often used to specifically refer to chips that produce only simple waveforms and noise.
+
+**pulse wave**: a waveform with a period consisting of only two amplitudes, high and low. also known as a rectangular wave.
+
+**pulse width**: sometimes called _duty cycle._ in a pulse wave, this is the ratio of the high part to the high and low combined.
+
+**release**: the part of a note that plays after it's no longer held, or the part of a macro the plays after it stops looping. usually applies at key off.
+
+**resample**: to convert a sample to a different playback rate.
+- this is a "lossy" process; it usually loses some amount of audio quality. the results can't be converted back into the original rate without further loss of quality.
+- resampling to a lower rate reduces the amount of memory required, but strips away higher frequencies in the sound.
+- resampling to a higher rate cannot recover missing frequencies and may add unwanted harmonics along with greater memory requirements.
+
+**raw**: a sample or wavetable file without a header. when loading such a file, the format must be set properly or it will be a mess.
+
+**register**: a memory location within a sound chip. "register view" shows all the relevant memory of all chips in use.
+
+**sample** (1): a digitally recorded sound. usually stored as some variant of PCM.
+- these can take up a lot of room depending on length and sample rate, thus older systems tend to use short, lower quality samples.
+
+**sample** (2): a single value taken from a digitally recorded sound. a sample(1) is made up of samples(2).
+
+**signed**: a digital representation of a number that may be negative or positive.
+- if an imported raw sample sounds recognizable but heavily distorted, it's likely to be unsigned interpreted as signed or vice-versa.
+
+**software mixing**: mixing multiple channels of sound down to a single stream to be sent to a PCM channel.
+- this puts a heavy load on the CPU of the host system, so it was rarely used in games.
+- _Furnace:_ this is used for DualPCM and QuadTone.
+
+**square wave**: a wave consisting of only two values, high and low, with equal durations within the wave's period.
+- this is equivalent to a pulse wave with a duty of 50%.
+
+**supersaw**: a sound made up of multiple saw waves at slightly different frequencies to achieve a chorusing effect.
+
+**tick rate**: the number of times per second that the sound engine moves forward. all notes and effects are quantized to this rate.
+- this usually corresponds to the frame rate the system uses for video, approximately 60 for NTSC and 50 for PAL.
+
+**unsigned**: a digital representation of a number that can only be positive.
+- if an imported raw sample sounds recognizable but heavily distorted, it's likely to be signed interpreted as unsigned or vice-versa.
+
+**.vgm**: Video Game Music. a file containing the log of data sent to a sound chip during sound playback.
+- saving to a .vgm file may be compared to "converting text to outlines" or similar irreversible processes. the results cannot be loaded back into the tracker.
+- different versions of the VGM format have different capabilities, with trade-offs. older versions may lack chips or features; newer versions may not be compatible with some software.
+- samples are stored uncompressed. PCM streams (such as DualPCM) can quickly take up a huge amount of space.
+
+**waveform**: a very short period of repeating sound.
+- the most basic waveform is a sine wave. others include triangle, pulse, saw, and the like.
+
+**wavetable** (1): a very short looping sample.
+
+**wavetable** (2): an ordered group of wavetables(1) used in sequence within a single instrument.
+
+**.zsm**: ZSound Music. a VGM-like file meant specifically for the Commander X16 computer.

doc/1-intro/hex.md

@@ -41,7 +41,7 @@ hex | decimal
  40 | 64
 ```
 
-# hex to decimal
+## hex to decimal
 
 for example, take hexadecimal number `AA`:
 
@@ -67,7 +67,7 @@ now for hexadecimal number `4C5F`:
                                           = 19551
 ```
 
-# decimal to hex
+## decimal to hex
 
 if it's less than 16, just memorize the table at the top of this document.
 
@@ -96,7 +96,37 @@ now for decimal number `69420`:
 = 10F2C
 ```
 
-# hex-decimal table
+## bitmask
+
+a bitmask is a value that actually represents a set of individual binary bits to be toggled, some of which may be grouped to form small binary numbers. these are used by adding up the value of each bit and converting the result to hex. in macros, these are shown in decimal.
+
+bit   |   binary    | decimal
+:-----|:-----------:|--------:
+bit 7 | `1000 0000` | 128
+bit 6 | `0100 0000` |  64
+bit 5 | `0010 0000` |  32
+bit 4 | `0001 0000` |  16
+bit 3 | `0000 1000` |   8
+bit 2 | `0000 0100` |   4
+bit 1 | `0000 0010` |   2
+bit 0 | `0000 0001` |   1
+
+for example, to turn bits 7 and 5 on, and put `110` (decimal 6) in bits 1 to 3:
+
+```
+bit 7 = `1... ....` = 128
+bit 6 = `.0.. ....` =   0
+bit 5 = `..1. ....` =  32
+bit 4 = `...0 ....` =   0
+bit 3 = `.... 1...` =   8
+bit 2 = `.... .1..` =   4
+bit 1 = `.... ..0.` =   0
+bit 0 = `.... ...0` =   0
+``````
+
+added together, the resulting binary is `1010 1100`, which converts to hex as `AC` and to decimal as 172.
+
+## hex to decimal table
 
   hex | `0` | `1` | `2` | `3` | `4` | `5` | `6` | `7` | `8` | `9` | `A` | `B` | `C` | `D` | `E` | `F`
 -----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:

doc/2-interface/README.md

@@ -8,13 +8,13 @@ the default layout of Furnace is depicted below.
 
 ## general info
 
-- [UI components](components.md): recommended reading for all!
+- [UI components](components.md): read first!
 - [global keyboard shortcuts](keyboard.md)
 - [menu bar](menu-bar.md)
 
 ## primary windows
 
-- [order list](order-list.md)
+- [orders](order-list.md)
 - [play/edit controls](play-edit-controls.md)
 - [instrument/wavetable/sample list](asset-list.md)
 - [song information](song-info.md)
@@ -44,4 +44,4 @@ the default layout of Furnace is depicted below.
 ## other topics
 
 - [basic mode](basic-mode.md)
-- [settings](../2-interface/settings.md)
+- [settings](settings.md)

doc/2-interface/asset-list.md

@@ -1,48 +1,59 @@
-# instrument list
+# asset list
+
+an "asset" refers to an instrument, wavetable or sample.
+
+## instrument list
 
 ![instruments window](instruments.png)
 
-Buttons from left to right:
+buttons from left to right:
+
 - **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 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:
+  - 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.
+  - instruments are saved as Furnace instrument (.fui) files.
+  - right-clicking brings up a menu with the following options:
     - **save instrument as .dmp...**: saves the selected instrument in DefleMask format.
-    - **save 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.
-- **Delete**: Deletes the currently selected instrument. Pattern data will be adjusted to use the next available instrument in the list.
+- **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.
+- **Delete**: deletes the currently selected instrument. pattern data will be adjusted to use the next available instrument in the list.
 
 ## folder view
 
 ![instruments window in folder view](instruments-folder.png)
 
-In folder view, the "Move up" and "Move down buttons disappear and a new one appears:
-- **New folder**: Creates a new folder.
+in folder view, the "Move up" and "Move down buttons disappear and a new one appears:
+- **New folder**: creates a new folder.
 
-Instruments may be dragged from folder to folder and even rearranged within folders without changing their associated numbers.
+assets may be dragged from folder to folder and even rearranged within folders without changing their associated numbers.
 
-Right-clicking on a folder allows one to rename or delete it. Deleting a folder does not remove the instruments in it.
+right-clicking on a folder allows one to rename or delete it. deleting a folder does not remove the instruments in it.
 
-# wavetable list
+## wavetable list
 
 ![wavetables window](wavetables.png)
 
-Everything from the instrument list applies here also, with one major difference: Moving waves around with the buttons will change their associated numbers in the list but _not_ in pattern or instrument data. Be careful!
+everything from the instrument list applies here also, with one major difference: moving waves around with the buttons will change their associated numbers in the list but **not** in pattern or instrument data. be careful!
 
-# sample list
+wavetables are saved as Furnace wavetable (.fuw) files. 
+
+- right-clicking the Save button brings up a menu with the following options:
+  - **save wavetable as .dmw...**: saves the selected wavetable in DefleMask format.
+  - **save raw wavetable...**: saves the selected wavetable as raw data.
+
+## sample list
 
 ![samples window](samples.png)
 
-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.
-  - Right-clicking stops the sample playback.
+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.
+  - right-clicking stops the sample playback.
+
+samples are saved as standard wave (.wav) files.
+
+- right-clicking the Save button brings up a menu with the following options:
+  - **save raw sample...**: saves the selected sample as raw data.

doc/2-interface/basic-mode.md

@@ -3,32 +3,34 @@
 Furnace comes with a "basic mode" that can be toggled through the "settings" menu. it disables certain features in Furnace that may look intimidating or confusing for newcomers. if you find that a certain feature of Furnace is missing, see if this setting is enabled or not.
 
 among the features that cannot be accessed in this mode are:
-* file menu:
-  * chip manipulation options (add, configure, change, remove chips)
-* edit menu:
-  * paste special…
-  * operation masking
-  * input latch
-  * find and replace
-* speed window:
-  * virtual tempo
-  * divider
-  * song length
-* song info window:
-  * manual system naming
-  * tuning options
-* right-clicking on the pattern window:
-  * gradient/fade…
-  * scale
-  * randomize
-  * invert values
-  * flip selection
-  * collapse
-  * expand
-* these windows:
-  * mixer
-  * grooves
-  * channels
-  * pattern manager
-  * chip manager
-  * compatibility flags
+
+### edit menu
+- paste special
+- operation masking
+- input latch
+- find and replace
+
+### speed window
+- virtual tempo
+- divider
+- song length
+
+### song info window
+- manual system naming
+- tuning options
+
+### pattern right-click menu
+- gradient/fade
+- scale
+- randomize
+- invert values
+- flip selection
+- collapse
+- expand
+
+### other windows
+- mixer
+- grooves
+- channels
+- pattern manager
+- compatibility flags

doc/2-interface/components.md

@@ -60,9 +60,9 @@ the options are:
 
 drag your mouse cursor to any of the options to dock the window.
 
-if you drag to the sides (marked with blue text), the window will cover that side of the workspace.
+if you drag to the sides, the window will cover that side of the workspace.
 
-if you drag it to a window or empty space (marked with yellow text), five docking positions will appear.
+if you drag it to a window or empty space, five docking positions will appear.
 
 if you drag the window to the center of another window, it will appear as another tab.
 

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

@@ -1,10 +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.
 
+for more details about these effects, see [the effects page](../3-pattern/effects.md).
+
 - **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.
+- menu button: opens a small list of effect categories. toggle each to change whether effects belonging to such categories will be shown in the list.

doc/2-interface/keyboard.md

@@ -1,10 +1,8 @@
 # keyboard
 
-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.
+everything on this list can be configured in the "Keyboard" tab of the Settings dialog.
 
-the keys in the "Global hotkeys" section can be used in any window, though not within text boxes.
+the keys in the "Global hotkeys" section can be used in any window, although not when a text field is activated.
 
 | action                                                 | default keybind  |
 |--------------------------------------------------------|------------------|
@@ -242,15 +240,4 @@ the keys in the "Global hotkeys" section can be used in any window, though not w
 | 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.
+| Set loop to selection                                  | `Ctrl-L`         |

doc/2-interface/menu-bar.md

@@ -2,9 +2,9 @@
 
 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.
+items in _italic_ don't appear in basic mode and are only available in advanced mode.
 
-# file
+## file
 
 - **new...**: creates a new song.
 - **open...**: opens the file picker, allowing you to select a song to open.
@@ -49,10 +49,11 @@ items in _italics_ don't appear in basic mode and are only available in advanced
     - macOS: `~/Library/Application Support/Furnace/backups`
     - Linux/other: `~/.config/furnace/backups`
   - this directory grows in size as you use Furnace. remember to delete old backups periodically to save space.
+  - **do NOT rely on the backup system as auto-save!** you should save a restored backup because Furnace will not save backups of backups.
 
-- **exit**: I think you know what this does.
+- **exit**: closes Furnace.
 
-## export audio
+### export audio
 
 this option allows you to export your song in .wav format. I know I know, no .mp3 or .ogg export yet, but you can use a converter.
 
@@ -70,7 +71,7 @@ and three export choices:
 - **multiple files (one per channel)**: exports the output of each channel to .wav files.
   - useful for usage with a channel visualizer such as corrscope.
 
-## export VGM
+### export VGM
 
 this option allows exporting to a VGM (Video Game Music) file. these can be played back with VGMPlay (for example).
 
@@ -104,7 +105,7 @@ the following settings exist:
 
 click on **click to export** to begin exporting.
 
-## export ZSM
+### export ZSM
 
 ZSM (ZSound Music) is a format designed for the Commander X16 to allow hardware playback.
 it may contain data for either YM2151 or VERA chips.
@@ -120,7 +121,7 @@ the following settings are available:
 
 click on **Begin Export** to... you know.
 
-## export command stream
+### export command stream
 
 this option exports a text or binary file which contains a dump of the internal command stream produced when playing the song.
 
@@ -129,7 +130,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **export (binary)**: exports in Furnace's own command stream format (FCS). see `export-tech.md` in `papers/` for details.
 - **export (text)**: exports the command stream as a text file. only useful for analysis, really.
 
-# edit
+## edit
 
 - **...**: does nothing except prevent accidental clicks on later menu items if the menu is too tall to fit on the program window.
 
@@ -189,9 +190,9 @@ it's not really useful, unless you're a developer and want to use a command stre
 
 - _**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.
+- **clear**: opens a window that allows you to mass-delete things like songs, unused instruments, and the like.
 
-# settings
+## settings
 
 - **full screen**: expands the Furnace window so it covers your screen.
 - **lock layout**: prevents you from dragging/resizing docked windows, or docking more.
@@ -200,7 +201,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **reset layout**: resets the workspace to its defaults.
 - **settings...**: shows the Settings window. these are detailed in [settings.md].
 
-# window
+## window
 
 all these menu items show or hide their associated windows.
 
@@ -212,23 +213,23 @@ 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)_
-- [song comments](comments.md)
+- _[mixer](../8-advanced/mixer.md)_
+- _[grooves](../8-advanced/grooves.md)_
+- _[channels](../8-advanced/channels.md)_
+- _[pattern manager](../8-advanced/pat-manager.md)_
+- _[chip manager](../8-advanced/chip-manager.md)_
+- _[compatibility flags](../8-advanced/compat-flags.md)_
+- [song comments](../8-advanced/comments.md)
 
-- [piano](piano.md)
-- [oscilloscope](osc.md)
-- [oscilloscopes (per-channel)](chanosc.md)
-- [clock](clock.md)
-- [register view](regview.md)
-- [log viewer](log-viewer.md)
-- [stats](stats.md)
+- [piano](../8-advanced/piano.md)
+- [oscilloscope](../8-advanced/osc.md)
+- [oscilloscopes (per-channel)](../8-advanced/chanosc.md)
+- [clock](../8-advanced/clock.md)
+- [register view](../8-advanced/regview.md)
+- [log viewer](../8-advanced/log-viewer.md)
+- [stats](../8-advanced/stats.md)
 
-# help
+## help
 
 - **effect list**: displays the effect list.
 - **debug menu**: this menu contains various debug utilities.
@@ -244,6 +245,6 @@ at the end of the menu bar, more information may be shown:
   - instrument number and name.
   - 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.
+- during playback, these values will be displayed:
+  - `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/order-list.md

@@ -1,21 +1,22 @@
-# order list
+# orders
 
-the order list is a playlist for patterns.
+this window displays the order list. a spreadsheet that contains the order of patterns that will play, from top to bottom.
 
 ![order list](order-list.png)
 
 along the top are the available channels. their abbreviations can be set in the [channels window](../8-advanced/channels.md). the highlighted channel follows the channel the pattern view cursor is in.
 
-along the left are the order numbers. these are referenced with the `0Bxx` command. the highlighted row follows the order the pattern view cursor is in.
+along the left are the order numbers. the highlighted row follows the order the pattern view cursor is in.
 
 each entry in the table is the pattern that will play during that order. these can be changed according to the order edit mode.
 
 hovering over a pattern number will pop up a tooltip showing the name of that pattern, if it has one.
 
-The buttons are as follows:
-- **Add new order**.
-- **Remove order**.
-- **Duplicate order**: adds a new order with patterns matching the selected one directly below it. right-click to "deep clone"; this copies all patterns involved to new ones.
+the buttons are:
+- **Add new order**: adds a new order.
+- **Remove order**: removes the currently selected order.
+- **Duplicate order**: adds a new order with patterns matching the selected one directly below it.
+  - right-click to "deep clone"; this copies all patterns involved to new ones.
 - **Move order up**: swaps the selected order with the one above it.
 - **Move order down**: swaps the selected order with the one below it.
 - **Duplicate order at end of song**: same as "Duplicate order" except the new order is added at the bottom of the list.
@@ -24,6 +25,6 @@ The buttons are as follows:
   - **entire row**: all patterns in the order will change.
 - **Order edit mode**: selects the method of changing orders.
   - **Click to change**: a click will add one to the pattern number. a right-click will subtract one.
-  - **Select and type (don't scroll)**: select a pattern and type.
+  - **Select and type (don't scroll)**: select a pattern number and type.
   - **Select and type (scroll horizontally)**: as above, but after entering two digits, the cursor moves to the next channel.
   - **Select and type (scroll vertically)**: as above, but after entering two digits, the cursor moves to the next order.

doc/2-interface/play-edit-controls.md

@@ -1,24 +1,24 @@
 # play/edit controls
 
-The "Play/Edit Controls" are used to control playback and change parameters of the pattern view.
+the "Play/Edit Controls" are used to control playback and change parameters of the pattern view.
 
-- ![](control-play.png) **Play**: Plays from cursor position.
-- ![](control-stop.png) **Stop**: Stops all playback.
-- ![](control-play-pattern.png) **Play from the beginning of this pattern**: Plays from the start of current pattern.
-- ![](control-play-repeat.png) **Repeat from the beginning of this pattern**: Repeats current pattern from its start.
-- ![](control-step.png) **Step one row**: Plays only the row at cursor position and moves down one.
-- ![](control-edit.png) **Edit**: Toggles edit mode. If off, nothing can be edited in the pattern window. (Great for playing around on the keyboard!)
-- ![](control-metronome.png) **Metronome**: Toggles the metronome, which only sounds during playback.
-- ![](control-repeat.png) **Repeat pattern**: Toggles pattern repeat. During playback while this is on, the current pattern will play over and over instead of following the order list.
-- **Poly**: Turns on polyphony for previewing notes. Toggles to **Mono** for monophony (one note at a time only).
-- **Octave**: Sets current input octave.
-- **Step**: Sets edit step. If this is 1, entering a note or effect will move to the next row. If this is a larger number, rows will be skipped. If this is 0, the cursor will stay in place.
-- **Follow orders**: If on, the selected order in the orders window will follow the song during playback.
-- **Follow pattern**: If on, the cursor will follow playback and the song will scroll by as it plays.
+- ![play](control-play.png) **Play**: plays from cursor position.
+- ![stop](control-stop.png) **Stop**: stops all playback.
+- ![play pattern](control-play-pattern.png) **Play from the beginning of this pattern**: plays from the start of current pattern.
+- ![play repeat](control-play-repeat.png) **Repeat from the beginning of this pattern**: repeats current pattern from its start.
+- ![step](control-step.png) **Step one row**: plays only the row at cursor position and moves down one.
+- ![edit](control-edit.png) **Edit**: toggles edit mode. when turned off, you won't be able to enter notes.
+- ![metronome](control-metronome.png) **Metronome**: toggles the metronome, which only works during playback.
+- ![repeat](control-repeat.png) **Repeat pattern**: toggles pattern repeat. during playback while this is on, the current pattern will play over and over instead of following the order list.
+- **Poly**: turns on polyphony for previewing notes. toggles to **Mono** for monophony (one note at a time only).
+- **Octave**: sets current input octave.
+- **Step**: sets edit step. if this is 1, entering a note or effect will move to the next row. if this is a larger number, rows will be skipped. if this is 0, the cursor will stay in place.
+- **Follow orders**: if on, the selected order in the orders window will follow the song during playback.
+- **Follow pattern**: if on, the cursor will follow playback and the song will scroll by as it plays.
 
 ## layouts
 
-The layout can be changed in Settings > Appearance to one of these:
+the layout can be changed in Settings > Appearance to one of these:
 
 ### classic
 

doc/2-interface/settings.md

@@ -13,6 +13,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **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.
+- **Per-channel oscilloscope threads**: runs the per-channel oscilloscope in separate threads for a performance boost when there are lots of channels.
 
 ### File
 
@@ -31,8 +32,10 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
     - **Loops**: number of additional times to play through `0Bxx` song loop.
     - **Fade out (seconds)**: length of fade out after final loop.
   - **Remember last values**
+- **Store instrument name in .fui**: when enabled, saving an instrument will store its name. this may increase file size.
+- **Load instrument name from .fui**: when enabled, loading an instrument will use the stored name (if present). otherwise, it will use the file name.
 
-### Chip
+### New Song
 
 - **Initial system**: the system of chips loaded on starting Furnace.
   - **Current system**: sets current chips as default.
@@ -58,9 +61,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 
 ### Behavior
 
-- **New instruments are blank**
-
-
+- **New instruments are blank**: when enabled, adding FM instruments will make them blank (rather than loading the default one).
 
 ## Audio
 
@@ -106,7 +107,11 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 
 ### Metronome
 
-- **Metronome volume**
+- **Volume**: sets volume of metronome.
+
+### Sample preview
+
+- **Volume**: sets volume of sample preview.
 
 ## MIDI
 
@@ -141,19 +146,6 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
   - **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**
-    - **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**: 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.
@@ -187,19 +179,12 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 
 ### 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).
+- **Playback Core(s)**: core(s) to use for playback.
+- **Render Core(s)**: core(s) to use when exporting audio.
 
-- **PC Speaker strategy**: this is covered in the [PC speaker system doc](../7-systems/pcspkr.md).
+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 page](../7-systems/pcspkr.md).
 
 ## Keyboard
 
@@ -208,11 +193,22 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **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
 
+a list of keybinds is displayed.
+- click on a keybind. then enter a key or key combination to change it.
+- right-click to clear the keybind.
+- the full list is in the [keyboard](keyboard.md) page.
 
+#### 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.
 
 ## Interface
 
@@ -222,7 +218,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
   - **Import**: reads a .ini layout file.
   - **Export**: writes current layout to a .ini file.
   - **Reset**: resets layout to default.
-- **Allow docking editors**
+- **Allow docking editors**: when enabled, you'll be able to dock instrument/wave/sample 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**
@@ -241,56 +237,57 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **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**
+- **Note preview behavior:** allows you to disable note preview when entering notes in the pattern.
+  - **Never**: don't preview notes at all.
+  - **When cursor is in Note column**: only when the cursor is in the Note column
+  - **When cursor is in Note column or not in edit mode**: erm... yeah.
+  - **Always**: always preview notes.
 - **Allow dragging selection:**
-  - **No**
-  - **Yes**
-  - **Yes (while holding Ctrl only)**
+  - **No**: don't allow drag-and-drop.
+  - **Yes**: allow drag-and-drop.
+  - **Yes (while holding Ctrl only)**: allow drag-and-drop but only when holding Control (Command on macOS).
 - **Toggle channel solo on:** selects which interactions with a channel header will toggle solo for that channel.
   - Right-click or double click
   - Right-click
   - Double-click
-- **Double click selects entire column**
+- **Double click selects entire column**: when enabled, double clicking on a cell of the pattern will select the 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.
+- **Insert pushes entire channel row**: when enabled, pressing Insert will push the entire channel rather than the column at the cursor position.
+- **Pull delete affects entire channel row**: when enabled, pull deleting (Backspace by default) will pull the entire channel rather than the column at the cursor position.
+- **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. for example:
   - 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**
-
+  - **Move down**: after entering an effect (or effect value), the cursor moves down.
+  - **Move to effect value (otherwise move down)**: after entering an effect, the cursor moves to its value. if entering a value, the cursor moves down.
+  - **Move to effect value/next effect and wrap around**: after entering an effect or effect value, the cursor moves right. if it was on the last column, it jumps back to the first effect.
+- **Delete effect value when deleting effect**: if enabled, deleting effect will also delete its value.
+- **Change current instrument when changing instrument column (absorb)**: if enabled, typing on the instrument column will also select the instrument you've typed.
+- **Remove instrument value when inserting note off/release**: if enabled, inserting a note off or release on a row that has instrument value will remove the instrument value.
+- **Remove volume value when inserting note off/release**: same as above, but for volume.
 
 ### 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**
+- **Wrap horizontally:** selects what to do when the cursor hits horizontal boundaries.
+  - **No**: don't wrap the cursor.
+  - **Yes**: wrap the cursor.
+  - **Yes, and move to next/prev row**: wrap the cursor and move it to the other row.
+- **Wrap vertically:** selects what to do when the cursor hits vertical boundaries.
+  - **No**: don't wrap the cursor.
+  - **Yes**: wrap the cursor.
+  - **Yes, and move to next/prev pattern**: wrap the cursor and go to the next/previous order.
+  - **Yes, and move to next/prev pattern (wrap around)**: same as the previous option, but also wraps around the song.
+- **Cursor movement keys behavior:** allows you to select how much will the cursor move by when pressing cursor movement keys.
+  - **Move by one**: guess.
+  - **Move by Edit Step**: guess.
+- **Move cursor by edit step on delete**: when deleting, moves the cursor by Edit Step.
+- **Move cursor by edit step on insert (push)**: when inserting, moves the cursor by Edit Step.
+- **Move cursor up on backspace-delete**: when pull deleting (Backspace by default), moves cursor up.
+- **Move cursor to end of clipboard content when pasting**: allows you to choose what happens after pasting.
+  - if on, the cursor will move to the end of the clipboard content.
+  - if off, the cursor won't move.
 
 ### Scrolling
 
@@ -303,8 +300,6 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **Don't scroll when moving cursor**
 - **Move cursor with scroll wheel**
 
-
-
 ## Appearance
 
 ### Scaling
@@ -315,18 +310,32 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 
 ### Text
 
-- **Main font**: overall interface font.\
-  **Header font**: font for section headers.\
-  **Pattern font** font for the pattern view, the order list, and related.
+- **Font renderer**: this allows you to select which font renderer library to use. there are two choices:
+  - **stb_truetype**: the original font renderer used in Furnace 0.6 and before.
+  - **FreeType**: this font renderer has support for more font formats and provides more settings. introduced in Furnace 0.6.1.
+- **Main font**: font for the user interface.
+- **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**\
-  **Display Korean characters**
-  - only toggle these options if you have enough graphics memory.
+- **Display Japanese characters**, **Display Chinese (Simplified) characters**, **Display Chinese (Traditional) characters** and **Display Korean characters**: only toggle these options if you have enough graphics memory.
   - these are a temporary solution until dynamic font atlas is implemented in Dear ImGui.
 
+#### FreeType-specific settings
+
+- **Anti-aliased fonts**: when enabled, fonts will be rendered smooth.
+- **Support bitmap fonts**: this option allows you to enable the loading of bitmap fonts.
+  - be noted that this may force non-bitmap fonts to undesired sizes!
+- **Hinting**: this option allows you to define how crisp fonts are rendered.
+  - **Off**: disable font hinting. at small sizes, fonts may be blurry.
+  - **Slight**: enable slight font hinting.
+  - **Normal**: enable font hinting.
+  - **Full**: enable harsh font hinting. fonts may look ugly/distorted to some people.
+- **Auto-hinter**: some fonts contain hinting data, but some don't. this allows you to select what happens.
+  - **Disable**: only rely upon font hinting data.
+  - **Enable**: prefer font hinting data if present.
+  - **Force**: ignore font hinting data.
+
 ### Program
 
 - **Title bar:**

doc/2-interface/song-info.md

@@ -1,51 +1,53 @@
 # song info
 
-- **Name**: The track's title.
-- **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 in advanced mode, it can be changed to anything one wants. The **Auto** button will provide a guess based on the chips in use.
+- **Name**: the track's title.
+- **Author**: the author(s) of this track.
+- **Album**: the associated album name (or the name of the game the song is from).
+- **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.
+all of this metadata will be included in a VGM export. this isn't the case for an audio 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. Available only in advanced mode.
+- _**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
+## subsongs
 
-This window allows one to create **subsongs** - multiple individual songs within a single file. Each song has its own order list and patterns, but all songs within a file share the same chips, samples, and so forth.
+this window allows one to create **subsongs** - multiple individual songs within a single file. each song has its own order list and patterns, but all songs within a file share the same chips, samples, and so forth.
 
-- The drop-down box selects the current subsong.
-- The **`+`** button adds a new subsong.
-- The **`−`** button permanently deletes the current subsong (unless it's the only one).
-- **Name**: Title of the current subsong.
-- The box at the bottom can store any arbitrary text, like a separate "Comments" box for the current subsong.
+- the drop-down box selects the current subsong.
+- the **`+`** button adds a new subsong.
+- the **`−`** button permanently deletes the current subsong (unless it's the only one).
+- **Name**: title of the current subsong.
+- the box at the bottom can store any arbitrary text, like a separate "Comments" box for the current subsong.
 
-# speed
+## speed
 
-There are multiple ways to set the tempo of a song.
+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.
+items in _italic_ 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.
+**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.
 
-**Speed**: The number of ticks per row.
-- Clicking the "Speed" button changes to more complex modes covered in the [grooves] page.
+**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:
-- 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.
+_**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.
+- another way to accomplish this with more control over the results is to use grooves. see the page on [grooves](../8-advanced/grooves.md) for details.
 
-_**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.
-- The second value represents the number of rows per measure.
-- These don't have to line up with the music's actual beats and measures. Set them as preferred for tracking. _Note:_ These values are used for the metronome and calculating BPM.
+**Highlight**: sets the pattern row highlights:
+- the first value represents the number of rows per beat.
+- the second value represents the number of rows per measure.
+- these don't have to line up with the music's actual beats and measures. set them as preferred for tracking.
+  - note: these values are used for the metronome and calculating BPM.
 
-**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.)
+**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

@@ -1,6 +1,6 @@
-# patterns
+# pattern
 
-the pattern view allows you to edit the song.
+the pattern view allows you to edit the song's patterns.
 
 ![pattern view](pattern.png)
 
@@ -24,7 +24,7 @@ you may change the cursor position by clicking anywhere on the pattern.
 
 to select an area, press and hold the left mouse button. then drag the mouse and release the button to finish selection.
 
-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.
+right-clicking within the pattern view brings up a pop-up menu with most options from the [edit menu](../2-interface/menu-bar.md).
 
 
 
@@ -44,30 +44,30 @@ clicking the `++` at the top left corner of the pattern view cycles through thre
   - **-**: 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.
+- **Pattern names**: displays pattern names (per channel). 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
+## input
 
-## note 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.
+- **note off** (`OFF`) turns off the last played note in that channel (key off for FM/hardware envelope; note cut otherwise).
+- **note release** (`===`) triggers macro release (and in FM/hardware envelope channels it also triggers key off).
+- **macro release** (`REL`) does the same as above, but does not trigger key off in FM/hardware envelope channels.
 - **toggle edit** enables and disables editing. when editing is enabled, the cursor's row will be shaded red.
 
-## instrument/volume input
+### 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
+### effect input
 
 works like the instrument/volume input.
 
@@ -80,7 +80,7 @@ here's [a list of effect types](effects.md).
 
 
 
-# keyboard shortcuts
+## keyboard shortcuts
 
 these are the default key functions. all keys are configurable in the Keyboard tab of the Settings window.
 

doc/3-pattern/effects.md

@@ -1,14 +1,14 @@
 # effect list
 
-most of the effect numbers are from ProTracker / FastTracker 2.
+some of the effect numbers are taken from ProTracker / FastTracker 2.
 
 however, effects are continuous, which means you only need to type it once and then stop it with an effect value of `00` or no effect value at all.
 
 ## volume
 
 - `0Axy`: **Volume slide.**
-  - If `x` is 0 then this slides volume down by `y` each tick.
-  - If `y` is 0 then this slides volume up by `x` each tick.
+  - if `x` is 0 then this slides volume down by `y` each tick.
+  - if `y` is 0 then this slides volume up by `x` each tick.
 - `FAxy`: **Fast volume slide.** same as `0Axy` above but 4× faster.
 - `F3xx`: **Fine volume slide up.** same as `0Ax0` but 64× slower.
 - `F4xx`: **Fine volume slide down.** same as `0A0x` but 64× slower.
@@ -16,8 +16,8 @@ however, effects are continuous, which means you only need to type it once and t
 - `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.
+  - tremolo is downward only.
+  - maximum tremolo depth is -60 volume steps.
 
 ## pitch
 
@@ -38,11 +38,11 @@ however, effects are continuous, which means you only need to type it once and t
 - `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.
+  - maximum vibrato depth is ±1 semitone.
 - `E3xx`: **Set vibrato direction.** `xx` may be one of the following:
-  - `00`: Up and down. default.
-  - `01`: Up only.
-  - `02`: Down only.
+  - `00`: up and down. default.
+  - `01`: up only.
+  - `02`: down only.
 - `E4xx`: **Set vibrato range** in 1/16th of a semitone. 
 
 ## panning
@@ -63,7 +63,7 @@ not all chips support these effects.
 
 ## time
 
-- `09xx`: **Set speed/groove.** if no grooves are defined, this sets speed. If alternating speeds are active, this sets the first speed.
+- `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).
@@ -79,20 +79,21 @@ not all chips support these effects.
 ## note
 
 - `0Cxx`: **Retrigger.** repeats current note every `xx` ticks.
-  - This effect is not continuous; it must be entered on every row.
-- `ECxx`: **Note cut.** ends current note after `xx` ticks. For FM instruments, it's equivalent to a "key off".
+  - this effect is not continuous; it must be entered on every row.
+- `ECxx`: **Note cut.** ends current note after `xx` ticks. for FM instruments, it's equivalent to a "key off".
 - `EDxx`: **Note delay.** delays note by `x` ticks.
 
 ## other
 
 - `9xxx`: **Set sample position.** jumps current sample to position `xxx * 0x100`.
-  - Not all chips support this effect.
+  - not all chips support this effect.
 - `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.**\
-  `F6xx`: **Enable macro.** see macro table at the end of this document for possible values.
+- `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).
 
@@ -147,19 +148,53 @@ additionally, [each chip has its own effects](../7-systems/README.md).
 
 the interpretation of duty, wave and extra macros depends on chip/instrument type:
 
-ex | FM     | OPM       | OPZ       | OPLL  | AY-3-8910  | AY8930     | Lynx     | C64        | SAA1099  | X1-010     | Namco 163  | FDS       | Sound Unit | ES5506    | MSM6258  | QSound       | SNES      | MSM5232   |
----|--------|-----------|-----------|-------|------------|------------|----------|------------|----------|------------|------------|-----------|------------|-----------|----------|--------------|-----------|-----------|
- D | NoiseF | NoiseFreq |           |       | NoiseFreq  | NoiseFreq  | Duty/Int | Duty       |          |            | Wave Pos   |           | Duty       | Filt Mode | FreqDiv  | Echo Level   | NoiseFreq | GroupCtrl |
- W |        | LFO Shape | LFO Shape | Patch | Waveform   | Waveform   |          | Waveform   | Waveform | Waveform   | Waveform   | Waveform  | Waveform   |           |          |              | Waveform  |           |
- 1 |        | AMD       | AMD       |       |            | Duty       |          | FilterMode | Envelope | EnvMode    | WaveLen    | Mod Depth | Cutoff     | Filter K1 | ClockDiv | EchoFeedback | Special   | GroupAtk  |
- 2 |        | PMD       | PMD       |       | Envelope   | Envelope   |          | Resonance  |          | Envelope   | WaveUpdate | Mod Speed | Resonance  | Filter K2 |          | Echo Length  | Gain      | GroupDec  |
- 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          | Special    |          | AutoEnvNum | WaveLoad W |           | Control    | Env Count |          |              |           | Noise     |
- A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          |            |          | AutoEnvDen | WaveLoad P |           |            | Control   |          |              |           |           |
- B | FB     | FB        | FB        |       |            | Noise AND  |          |            |          |            | WaveLoad L |           |            |           |          |              |           |           |
- C | FMS    | FMS       | FMS       |       |            | Noise OR   |          |            |          |            | WaveLoad T |           |            |           |          |              |           |           |
- D | AMS    | AMS       | AMS       |       |            |            |          |            |          |            |            |           |            |           |          |              |           |           |
- 4 | OpMask | OpMask    |           |       |            |            |          | Test/Gate  |          |            |            |           | PResetTime | EnvRampL  |          |              |           |           |
- 5 |        |           | AMD2      |       |            |            |          |            |          |            |            |           |            | EnvRampR  |          |              |           |           |
- 6 |        |           | PMD2      |       |            |            |          |            |          |            |            |           |            | EnvRampK1 |          |              |           |           |
- 7 |        |           | LFO2Speed |       |            |            |          |            |          |            |            |           |            | EnvRampK2 |          |              |           |           |
- 8 |        |           | LFO2Shape |       |            |            |          |            |          |            |            |           |            | Env Mode  |          |              |           |           |
+ex | FM     | OPM       | OPZ       | OPLL  | AY-3-8910  | AY8930     | Lynx     | C64        |
+---|--------|-----------|-----------|-------|------------|------------|----------|------------|
+ D | NoiseF | NoiseFreq |           |       | NoiseFreq  | NoiseFreq  | Duty/Int | Duty       |
+ W |        | LFO Shape | LFO Shape | Patch | Waveform   | Waveform   |          | Waveform   |
+ 1 |        | AMD       | AMD       |       |            | Duty       |          | FilterMode |
+ 2 |        | PMD       | PMD       |       | Envelope   | Envelope   |          | Resonance  |
+ 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          | Special    |
+ A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          |            |
+ B | FB     | FB        | FB        |       |            | Noise AND  |          |            |
+ C | FMS    | FMS       | FMS       |       |            | Noise OR   |          |            |
+ D | AMS    | AMS       | AMS       |       |            |            |          |            |
+ 4 | OpMask | OpMask    |           |       |            |            |          | Test/Gate  |
+ 5 |        |           | AMD2      |       |            |            |          |            |
+ 6 |        |           | PMD2      |       |            |            |          |            |
+ 7 |        |           | LFO2Speed |       |            |            |          |            |
+ 8 |        |           | LFO2Shape |       |            |            |          |            |
+
+ex | SAA1099  | X1-010     | Namco 163  | FDS       | Sound Unit | ES5506    | MSM6258  |
+---|----------|------------|------------|-----------|------------|-----------|----------|
+ D |          |            | Wave Pos   |           | Duty       | Filt Mode | FreqDiv  |
+ W | Waveform | Waveform   | Waveform   | Waveform  | Waveform   |           |          |
+ 1 | Envelope | EnvMode    | WaveLen    | Mod Depth | Cutoff     | Filter K1 | ClockDiv |
+ 2 |          | Envelope   | WaveUpdate | Mod Speed | Resonance  | Filter K2 |          |
+ 3 |          | AutoEnvNum | WaveLoad W |           | Control    | Env Count |          |
+ A |          | AutoEnvDen | WaveLoad P |           |            | Control   |          |
+ B |          |            | WaveLoad L |           |            |           |          |
+ C |          |            | WaveLoad T |           |            |           |          |
+ D |          |            |            |           |            |           |          |
+ 4 |          |            |            |           | PResetTime | EnvRampL  |          |
+ 5 |          |            |            |           |            | EnvRampR  |          |
+ 6 |          |            |            |           |            | EnvRampK1 |          |
+ 7 |          |            |            |           |            | EnvRampK2 |          |
+ 8 |          |            |            |           |            | Env Mode  |          |
+
+ex | QSound       | SNES      | MSM5232   |
+---|--------------|-----------|-----------|
+ D | Echo Level   | NoiseFreq | GroupCtrl |
+ W |              | Waveform  |           |
+ 1 | EchoFeedback | Special   | GroupAtk  |
+ 2 | Echo Length  | Gain      | GroupDec  |
+ 3 |              |           | Noise     |
+ A |              |           |           |
+ B |              |           |           |
+ C |              |           |           |
+ D |              |           |           |
+ 4 |              |           |           |
+ 5 |              |           |           |
+ 6 |              |           |           |
+ 7 |              |           |           |
+ 8 |              |           |           |

doc/4-instrument/8930.md

@@ -1,16 +0,0 @@
-# AY8930 instrument editor
-
-AY8930 instrument editor consists of these macros.
-
-- **Volume**: volume sequence
-- **Arpeggio**: pitch in half-steps
-- **Noise Freq**: AY8930 noise generator frequency sequence
-- **Waveform**: selector of sound type: pulse wave tone, noise or envelope generator
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
-- **Duty**: duty cycle of a pulse wave sequence
-- **Envelope**: allows shaping an envelope
-- **AutoEnv Num**: sets the envelope to the channel's frequency multiplied by numerator
-- **AutoEnv Den**: sets the envelope to the channel's frequency divided by denominator
-- **Noise AND Mask**: alters the shape/frequency of the noise generator, allowing to produce various interesting sound effects and even PWM phasing
-- **Noise OR Mask**: see above

doc/4-instrument/README.md

@@ -12,81 +12,115 @@ the instrument editor always starts with this section:
 - **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:
+## instrument types
 
-- [FM synthesis](fm.md) - for use with YM2612, YM2151 and FM block portion of YM2610.
-- [PSG](psg.md) - for use with TI SN76489 and derivatives like Sega Master System's PSG.
-- [NES](nes.md) - for use with NES.
+the following instrument types are available:
+
+- [SN76489/Sega PSG](psg.md) - for use with TI SN76489 and derivatives like Sega Master System's PSG.
+- [FM (OPN)](fm-opn.md) - for use with YM2612, YM2203, YM2608, YM2610 and YM2610B.
 - [Game Boy](game-boy.md) - for use with Game Boy APU.
-- [PC Engine / TurboGrafx-16](pce.md) - for use with PC Engine's wavetable synthesizer.
-- [WonderSwan](wonderswan.md) - for use with WonderSwan's wavetable synthesizer.
-- [AY8930](8930.md) - for use with Microchip AY8930 E-PSG sound source.
-- [Commodore 64](c64.md) - for use with Commodore 64 SID.
-- [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source.
+- [C64](c64.md) - for use with Commodore 64 SID.
+- [Generic Sample](sample.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.
+- [PC Engine](pce.md) - for use with PC Engine's wavetable synthesizer.
+- [AY-3-8910/SSG](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610.
+- [AY8930](ay8930.md) - for use with Microchip AY8930 E-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.
-- [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.
+- [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source.
+- [VIC](vic.md) - for use with VIC-20 sound chip.
+- [PET](pet.md) - for use with Commodore PET.
+- [VRC6](vrc6.md) - for use with VRC6's PSG sound source.
+- [FM (OPLL)](fm-opll.md) - for use with YM2413.
+- [FM (OPL)](fm-opll.md) - for use with YM3526 (OPL), YM3812 (OPL2) and YMF262 (OPL3).
+- [FDS](fds.md) - for use with Famicom Disk System sound source.
+- [Virtual Boy](virtual-boy.md) - for use with Virtual Boy.
+- [Namco 163](n163.md) - for use with Namco 163.
+- [Konami SCC/Bubble System WSG](scc.md) - for use with Konami SCC and Wavetable portion in Bubble System's sound hardware.
+- [FM (OPZ)](fm-opz.md) - for use with YM2414.
+- [POKEY](pokey.md) - for use with Atari 8-bit computers and their POKEY sound source.
+- [Beeper](beeper.md) - for use with PC Speaker and ZX Spectrum Beeper (SFX-like engine).
+- [WonderSwan](wonderswan.md) - for use with WonderSwan's wavetable synthesizer.
 - [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.
-- [Konami SCC / Bubble System WSG](scc.md) - for use with Konami SCC and Wavetable portion in Bubble System's sound hardware.
-- [Namco 163](n163.md) - for use with Namco 163.
-- [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.
+- [ES5506](es5506.md) - for use with Ensoniq ES5506 sound chip.
+- [SNES](snes.md) - for use with SNES.
+- [Sound Unit](su.md) - for use with Sound Unit chip.
+- [Namco WSG](wsg.md) - for use with Namco WSG wavetable chips, including C15 and C30.
+- [FM (OPM)](fm-opm.md) - for use with YM2151.
+- [NES](nes.md) - for use with NES.
+- [MSM6258](msm6258.md) - for use with MSM6258 sample chip.
+- [MSM6295](msm6295.md) - for use with MSM6295 sample chip.
+- [ADPCM-A](adpcm-a.md) - for use with ADPCM-A sample chip.
+- [ADPCM-B](adpcm-b.md) - for use with ADPCM-B sample chip.
+- [SegaPCM](segapcm.md) - for use with SegaPCM sample chip.
+- [QSound](qsound.md) - for use with QSound sample chip.
+- [YMZ280B](ymz280b.md) - for use with YMZ280B sample chip.
+- [RF5C68](rf5c68.md) - for use with RF5C68 sample chip.
+- [MSM5232](msm5232.md) - for use with MSM5232 PSG sound source.
+- [T6W28](t6w28.md) - for use with Toshiba T6W28 PSG sound source.
+- [K007232](k007232.md) - for use with K007232 sample chip.
+- [GA20](ga20.md) - for use with GA20 sample chip.
+- [Pokémon Mini/QuadTone](pokemini.md) - for use with these systems.
+- [SM8521](sm8521.md) - for use with SM8521 chip, used in Tiger Game.com.
+- [PV-1000](pv1000.md) - for use with Casio PV-1000.
+- [K053260](k053260.md) - for use with K053260 sample chip.
+- [TED](ted.md) - for use with Commodore Plus/4 and Commodore 16's TED chip.
+- [C140](c140.md) - for use with C140 sample chip.
+- [C219](c219.md) - for use with C219 sample chip.
 
+## macros
 
-# macros
+macros are incredibly versatile tools for automating instrument parameters.
 
-Macros are incredibly versatile tools for automating instrument parameters.
-
-After creating an instrument, open the Instrument Editor and select the "Macros" tab. There may be multiple macro tabs to control individual FM operators and such.
+after creating an instrument, open the Instrument Editor and select the "Macros" tab. there may be multiple macro tabs to control individual FM operators and such.
 
 ![macro view](macroview.png)
 
-The very first numeric entry sets the visible width of the bars in sequence-type macros. The scrollbar affects the view of all macros at once. There's a matching scrollbar at the bottom underneath all the macros.
+the very first numeric entry sets the visible width of the bars in sequence-type macros. the scrollbar affects the view of all macros at once. there's a matching scrollbar at the bottom underneath all the macros.
 
-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. 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.
+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. 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.
+- release mode. this determines how macro release is handled:
+  - **Active**: jumps to release position.
+  - **Passive**: does not jump to release position. if release position hasn't been reached yet, there will be a delay.
 
 ## macro types
 
-Every macro can be defined though one of three methods, selectable with the leftmost button under the macro type label:
+every macro can be defined though one of three methods, selectable with the leftmost button under the macro type label:
 
-- ![](macro-button-seq.png) **Sequence:** displayed as a bar graph, this is a sequence of numeric values.
-- ![](macro-button-ADSR.png) **ADSR:** this is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time.
-- ![](macro-button-LFO.png) **LFO:** the Low Frequency Oscillator generates a repeating wave of values.
+- ![sequence](macro-button-seq.png) **Sequence:** displayed as a bar graph, this is a sequence of numeric values.
+- ![ADSR](macro-button-ADSR.png) **ADSR:** this is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time.
+- ![LFO](macro-button-LFO.png) **LFO:** the Low Frequency Oscillator generates a repeating wave of values.
 
-Some macros are "bitmap" style. They represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
+some macros are "bitmap" style. they represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
 
 ### sequence
 
 ![sequence macro editor](macro-seq.png)
 
-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 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.
+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.
+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 entered in the pattern, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods.
+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 entered in the pattern, `@` values will be played at that exact note. this is especially useful for noise instruments with preset periods.
 
 ### ADSR
 
 ![ADSR macro editor](macro-ADSR.png)
 
 - **Bottom** and **Top** determine the range of outputs generated by the macro. (Bottom can be larger than Top to invert the envelope!) All outputs will be between these two values.
-- Attack, Decay, Sustain, SusDecay, and Release accept inputs between 0 to 255. These are scaled to the distance between Bottom and Top.
+- attack, Decay, Sustain, SusDecay, and Release accept inputs between 0 to 255. these are scaled to the distance between Bottom and Top.
 - **Attack** is how much the value moves toward Top with each tick.
 - **Hold** sets how many ticks to stay at Top before Decay.
 - **Decay** is how much the value moves to the Sustain level.
@@ -104,31 +138,25 @@ Finally, the sequence of values can be directly edited in the text box at the bo
 - **Bottom** and **Top** determine the range of values generated by the macro. (Bottom can be larger than Top to invert the waveform!)
 - **Speed** is how quickly the values change - the frequency of the oscillator.
 - **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.
+- **Shape** is the waveform used. triangle is the default, and Saw and Square are exactly as they say.
 
 
 
-# wavetable
+## wavetable
 
-This tab appears for PC Engine, FDS, Namco WSG, and other wavetable-based instruments.
+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.
+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).
+to use the wavetable synthesizer, refer to [the wavetable synthesizer section](wavesynth.md).
 
 
-# sample
+## sample
 
-This tab appears for Generic PCM, SNES, Amiga, and other sample-based instruments.
+this tab appears for Generic PCM DAC, Amiga and SNES.
 
 ![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.
-  - 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.
-
+see the [Generic Sample section](sample.md) for more information.

doc/4-instrument/adpcm-a.md

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

doc/4-instrument/adpcm-b.md

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

doc/4-instrument/amiga.md

@@ -1,18 +0,0 @@
-# Amiga/PCM sound source instrument editor
-
-The Generic Sample 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. 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/ay8910.md

@@ -1,13 +1,30 @@
 # AY-3-8910 instrument editor
 
-The AY-3-8910 instrument editor consists of these macros.
+the AY-3-8910 instrument editor consists of two tabs.
 
-- **Volume**: volume levels sequence
-- **Arpeggio**: pitch sequence
-- **Noise Freq**: AY-3-8910 noise generator frequency sequence
-- **Waveform**: selector of sound type - square wave tone, noise or envelope generator
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
-- **Envelope**: allows shaping an envelope
-- **AutoEnv Num**: sets the envelope to the channel's frequency multiplied by numerator
-- **AutoEnv Den**: sets the envelope to the channel's frequency multiplied by denominator
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+note that using samples on AY is CPU expensive!
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise Freq**: noise generator frequency sequence.
+  - note: global!
+- **Waveform**: selector of sound type - square wave tone, noise and/or envelope generator.
+  - you may select more than one option.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of **envelope**.
+- **Envelope**: configures the hardware envelope.
+  - **enable**: sets whether envelope is enabled.
+  - **direction**: flips the envelope's direction.
+  - **alternate**: when enabled, the envelope will change direction once it hits a boundary.
+  - **hold**: sets whether the envelope should stop when hitting boundary, or loop.
+- **AutoEnv Num**: sets the envelope to the channel's frequency multiplied by numerator.
+- **AutoEnv Den**: sets the envelope to the channel's frequency multiplied by denominator.
+  - these two must be set in order for AutoEnv to work!

doc/4-instrument/ay8930.md

@@ -0,0 +1,33 @@
+# AY8930 instrument editor
+
+the AY8930 instrument editor consists of two tabs.
+
+## Sample
+
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+note that using samples on AY is CPU expensive!
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise Freq**: noise generator frequency sequence.
+  - note: global!
+- **Waveform**: selector of sound type - square wave tone, noise and/or envelope generator.
+  - you may select more than one option.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of **envelope**.
+- **Duty**: duty cycle sequence.
+- **Envelope**: configures the hardware envelope.
+  - **enable**: sets whether envelope is enabled.
+  - **direction**: flips the envelope's direction.
+  - **alternate**: when enabled, the envelope will change direction once it hits a boundary.
+  - **hold**: sets whether the envelope should stop when hitting boundary, or loop.
+- **AutoEnv Num**: sets the envelope to the channel's frequency multiplied by numerator.
+- **AutoEnv Den**: sets the envelope to the channel's frequency multiplied by denominator.
+  - these two must be set in order for AutoEnv to work!
+- **Noise AND Mask**: alters the shape/frequency of the noise generator, allowing to produce various interesting sound effects and even PWM phasing.
+- **Noise OR Mask**: see above.

doc/4-instrument/beeper.md

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

doc/4-instrument/c140.md

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

doc/4-instrument/c219.md

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

doc/4-instrument/c64.md

@@ -1,35 +1,48 @@
 # C64 SID instrument editor
 
-The C64 instrument editor consists of two tabs: "C64" to control various parameters of sound channels, and "Macros" containing several macros.
+the C64 instrument editor consists of two tabs: "C64" to control various parameters of sound channels, and "Macros" containing several macros.
 
 ## C64
 
-- **Waveform**: allows selecting a waveform. NOTE: more than one waveform can be selected at once, logical AND mix of waves will be produced, with an exception of a noise waveform, it can't be mixed.
-- **Attack**: determines the rising time for the sound. The bigger the value, the slower the attack. (0-15 range)
-- **Decay**: Determines the diminishing time for the sound. The higher the value, the longer the decay. It's the initial amplitude decay rate. (0-15 range)
-- **Sustain**: Sets the volume level at which the sound stops decaying and holds steady. (0-15 range)
-- **Release**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the longer the release. (0-15 range)
-- **Ring Modulation**: enables the ring modulation affecting the instrument.
-- **Duty**: specifies the width of a pulse wave. (0-4095 range)
-- **Oscillator Sync**: enables the oscillator hard sync. As one oscillator finishes a cycle, it resets the period of another oscillator, forcing the latter to have the same base frequency. This can produce a harmonically rich sound, the timbre of which can be altered by varying the synced oscillator's frequency.
-- **Enable filter**: enables analogue filter affecting the instrument
+- **Waveform**: allows selecting a waveform.
+  - more than one waveform can be selected at once. in that case logical AND mix of waves will occur.
+  - noise is an exception. it cannot be used with any of the other waveforms.
+- **Attack**: determines the rising time for the sound. the bigger the value, the slower the attack. (0 to 15).
+- **Decay**: determines the diminishing time for the sound. the higher the value, the longer the decay (0 to 15).
+- **Sustain**: sets the volume level at which the sound stops decaying and holds steady (0 to 15).
+- **Release**: determines the rate at which the sound fades out after note off. the higher the value, the longer the release (0 to 15).
+
+- **Duty**: specifies the width of a pulse wave (0 to 4095).
+
+- **Ring Modulation**: when enabled, the channel's output will be multiplied with the previous channel's.
+- **Oscillator Sync**: enables oscillator hard sync. as the previous channel's oscillator finishes a cycle, it resets the period of the channel's oscillator, forcing the latter to have the same base frequency. this can produce a harmonically rich sound, the timbre of which can be altered by varying the synchronized oscillator's frequency.
+
+- **Enable filter**: when enabled, this instrument will go through the filter.
 - **Initialize filter**: initializes the filter with the specified parameters:
-- **Cutoff**: defines the "intensity" of a filter, to put in in layman terms (0-2047 range)
-- **Resonance**: defines an additional controlled amplification of that cutoff frequency, creating a secondary peak forms and colors the original pitch. (0-15 range)
-- **Filter mode**: determined the filter mode NOTE: SID's filter is multi-mode, you can mix different modes together (like low and high-pass filters at once) CH3-OFF disables the channel 3, for no reason whatsoever lmao
-- **Volume Macro is Cutoff Macro**: turns a volume macro in a macros tab into a filter cutoff macro.
-- **Absolute Cutoff Macro**: changes the behaviour of a cutoff macro from the old-style, compatible to much more define-able.
-- **Absolute Duty Macro**: changes the behaviour of a duty cycle macro from the old-style, compatible to much more definable.
-- **Don't test/gate before new note**: Don't reset the envelope to zero when a new note starts. (Read "Test/Gate" below for more info.)
+  - **Cutoff**: the filter's point in where frequencies are cut off (0 to 2047).
+  - **Resonance**: amplifies or focuses on the cutoff frequency, creating a secondary peak forms and colors the original pitch (0 to 15).
+  - **Filter mode**: sets the filter mode. you may pick one or more of the following:
+    - **low**: a low-pass filter. the lower the cutoff, the darker the sound.
+    - **high**: a high-pass filter. higher cutoff values result in a less "bassy" sound.
+    - **band**: a band-pass filter. cutoff determines which part of the sound is heard (from bass to treble).
+    - **ch3off**: mutes channel 3 when enabled. not sure why is this part of the chip's design, but it is.
+
+- **Volume Macro is Cutoff Macro**: turns the volume macro in the Macros tab into a filter cutoff macro.
+  - volume control is global (affects entire chip output), hence the option.
+- **Absolute Cutoff Macro**: when enabled, the cutoff macro will go from 0 to 2047, and it will be absolute (in other words, control the cutoff directly rather than being relative).
+- **Absolute Duty Macro**: when enabled, the duty macro will go from 0 to 4095.
+- **Don't test before new note**: this option disables the one-tick hard reset and test bit before a new note.
 
 ## Macros
 
-- **Volume**: volume sequence (WARNING: Volume sequence is global for ALL three channels!!)
-- **Arpeggio**: pitch sequence
-- **Duty**: pulse duty cycle sequence
-- **Waveform**: select the waveform used by instrument
-- **Pitch**: fine pitch
-- **Filter mode**: select the filter mode/sequence
-- **Resonance**: filter resonance sequence
-- **Special**: ring and oscillator sync selector
-- **Test/Gate**: When on, the TEST bit resets and locks Oscillator 1 at zero until cleared. The GATE bit controls Oscillator 1's envelope: Gate on runs through the envelope's attack, delay, and sustain; Gate off is envelope release.
+- **Volume**: volume sequence.
+  - warning: volume sequence is global! this means it controls the chip's volume and therefore affects all channels.
+  - this macro becomes **Cutoff** when the **Volume Macro is Cutoff Macro** option is enabled in the C64 tab.
+- **Arpeggio**: pitch sequence.
+- **Duty**: pulse width sequence.
+- **Waveform**: select the waveform used by instrument.
+- **Pitch**: fine pitch.
+- **Filter mode**: select the filter mode.
+- **Resonance**: filter resonance sequence.
+- **Special**: ring and oscillator sync selector.
+- **Test/Gate**: when on, the test bit is set, which mutes the channel.

doc/4-instrument/es5506.md

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

doc/4-instrument/fds.md

@@ -0,0 +1,29 @@
+# FDS instrument editor
+
+the FDS instrument editor contains three tabs: FDS, Wavetable and Macros.
+
+## FDS
+
+here you can edit FDS-specific settings.
+
+- **Compatibility mode**: DO NOT ENABLE. this exists for DefleMask compatibility. leave it alone.
+
+- **Modulation depth**: sets frequency modulation depth.
+- **Modulation speed**: sets frequency modulation speed.
+- **Modulation table**: this allows you to define a waveform for frequency modulation.
+  - the range is -4 to 3.
+  - a value of -4 will reset the modulator.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Waveform**: wavetable sequence.
+- **Pitch**: fine pitch.
+- **Mod Depth**: modulation depth.
+- **Mod Speed**: modulation speed.
+- **Mod Position**: sets position of modulator.

doc/4-instrument/fm-opl.md

@@ -0,0 +1,71 @@
+# 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 (only when 4-op flag is set and only on OPL3!).
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4 (only when 4-op flag is set and only on OPL3!).
+- **Macros**: for other macros (volume/arp/pitch/pan).
+
+## FM
+
+the OPL synthesizers are nominally two-operator (OPL3 supports 4-operator mode on up to six channels), meaning it takes two oscillators to produce a single sound.
+
+these apply to the instrument as a whole:
+- **Algorithm (ALG)**: 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.
+- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
+
+- **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.
+- **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 to 15).
+- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 15).
+- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
+- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
+- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 63 (decimal) the smallest. a change of one unit is about 0.75 dB.
+- **Key Scale Level (KSL)**: also known as "Level Scale". determines the degree to which the amplitude decreases according to the pitch.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Key Scale Rate (KSR)**: also known as "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch.
+- **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
+  - note that values 11, 13 and 14 behave as 10, 12 and 12 respectively.
+- **Waveform Select (WS)**: changes the waveform of the operator (OPL2 and OPL3 only, 0-3 range on OPL2 and 0-7 on OPL3).
+- **Vibrato (VIB)**: makes the operator affected by LFO vibrato.
+
+## macros
+
+these macros allow you to control several parameters of FM per tick.
+
+## FM Macros
+
+all parameters are listed above.
+
+## OP1-OP4 Macros
+
+all parameters are listed above.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning**: enables output on left/right/rear channels. OPL3 only.
+- **Pitch**: fine pitch.
+  - **Relative**: when enabled, pitch changes are relative to the current pitch.
+- **Phase Reset**: restarts all operators and resets the waveform to its start.
+
+## OPL (drums) instrument editor
+
+this is similar to the OPL instrument editor, but sets the parameters of snare, tom, top and hi-hat directly once a drums instrument is activated.

doc/4-instrument/fm-opll.md

@@ -0,0 +1,74 @@
+# 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 other macros (volume/arp/pitch/patch).
+
+## FM
+
+the OPLL synthesizer is two-operator, meaning it takes two oscillators to produce a single sound.
+however, unlike the other FM chips, only one custom patch may be set at a time, shared among all 9 channels.
+
+but don't worry! there also are 15 preset patches that you may select at any time.
+
+these apply to the instrument as a whole:
+- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
+- **Sustain (SUS)**: enables the sustain flag (sets the release rate to 5).
+- **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.
+  - this is the selector for the preset patches I mentioned before.
+  - once a preset patch is selected, only the volume is configurable.
+  - only one user-specified patch may be applied at a time!
+
+if you select the special Drums patch, you may use the instrument in Drums mode of OPLL. an extra setting also appears:
+- **Fixed frequency mode**: allows you to set a fixed frequency for the drum channels.
+
+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 to 15).
+- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 15).
+- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
+- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
+- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 63 (decimal) the smallest. a change of one unit is about 0.75 dB.
+  - in the case of the second operator, it goes from 0 to 15 instead.
+- **Key Scale Level (KSL)**: also known as "Level Scale". determines the degree to which the amplitude decreases according to the pitch.
+
+![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)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
+  - note that values 11, 13 and 14 behave as 10, 12 and 12 respectively.
+- **Vibrato (VIB)**: makes the operator affected by LFO vibrato.
+
+## macros
+
+these macros allow you to control several parameters of FM per tick.
+
+## FM Macros
+
+all parameters are listed above.
+
+## OP1-OP4 Macros
+
+all parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: pitch change sequence.
+- **Patch**: changes the playing preset mid-note.
+  - through use of this macro, you may unlock different glitched sounds. useful for distortion guitars!
+- **Pitch**: fine pitch.
+  - **Relative**: when enabled, pitch changes are relative to the current pitch.
+- **Phase Reset**: restarts all operators and resets the waveform to its start.
+
+
+## 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/fm-opm.md

@@ -0,0 +1,78 @@
+# FM (OPM) instrument editor
+
+the FM editor is divided into 7 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
+- **Macros**: for other macros (volume/arp/pitch/noise).
+
+## FM
+
+OPM is four-operator, meaning it takes four oscillators to produce a single sound.
+
+these apply to the instrument as a whole:
+- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
+- **Algorithm (ALG)**: determines how operators are connected to each other (0 to 7).
+  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - right-click to switch to a preview display of the waveform generated on a new note:
+    - left-click restarts the preview.
+    - middle-click pauses and unpauses the preview.
+    - right-click returns to algorithm view.
+
+- **LFO > Freq (FMS)**: determines how much will LFO have an effect in frequency (0 to 7).
+- **LFO > Amp (AMS)**: determines how much will LFO have an effect in volume (0 to 3).
+  - only applies to operators which have AM turned on.
+
+these apply to each operator:
+- the crossed-arrows button can be dragged to rearrange operators.
+- the **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
+- **Amplitude Modulation (AM)**: makes the operator volume affected by LFO.
+- **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 31).
+- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 31).
+- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. this is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
+- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. a change of one unit is about 0.75 dB.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (RS/KS)**: also known as "Key Scale" or "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
+- **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
+- **Fine Detune (DT)**: shifts the pitch a little (0 to 7).
+- **Coarse Detune (DT2)**: shifts the pitch by tens of cents (0 to 3).
+
+
+## macros
+
+these macros allow you to control several parameters of FM per tick.
+
+## FM Macros
+
+- **AM Depth**: amplitude modulation depth.
+- **PM Depth**: pitch modulation depth.
+- **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
+
+- **Arpeggio**: pitch sequence.
+- **Noise Frequency**: specifies the noise frequency.
+  - this only applies to operator 4 of channel 8!
+- **Panning**: toggles output on left and right channels.
+- **Pitch**: fine pitch.
+  - **Relative**: when enabled, pitch changes are relative to the current pitch.
+- **Phase Reset**: restarts all operators and resets the waveform to its start.
+
+
+## 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/fm-opn.md

@@ -0,0 +1,75 @@
+# FM (OPN) instrument editor
+
+the FM editor is divided into 7 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
+- **Macros**: for other macros (volume/arp/pitch).
+
+## FM
+
+OPN is four-operator, meaning it takes four oscillators to produce a single sound.
+
+these apply to the instrument as a whole:
+- **Algorithm (ALG)**: determines how operators are connected to each other (0 to 7).
+  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - right-click to switch to a preview display of the waveform generated on a new note:
+    - left-click restarts the preview.
+    - middle-click pauses and unpauses the preview.
+    - right-click returns to algorithm view.
+- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
+
+- **LFO > Freq (FMS)**: determines how much will LFO have an effect in frequency (0 to 7).
+- **LFO > Amp (AMS)**: determines how much will LFO have an effect in volume (0 to 3).
+  - only applies to operators which have AM turned on.
+  - does not apply to YM2203.
+
+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's volume affected by LFO.
+  - does not apply to YM2203.
+- **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 31).
+- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 31).
+- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. this is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
+- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. a change of one unit is about 0.75 dB.
+- **Hardware Envelope Generator (SSG-EG)**: executes the built-in envelope, inherited from AY-3-8910 PSG. speed of execution is controlled via Decay Rate.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (RS/KS)**: also known as "Key Scale" or "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
+- **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
+- **Fine Detune (DT)**: shifts the pitch a little (0 to 7).
+
+
+## macros
+
+these macros allow you to control several parameters of FM per tick.
+
+## FM Macros
+
+- **LFO Speed**: LFO frequency.
+- **OpMask**: toggles each operator.
+
+## OP1-OP4 Macros
+
+all parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: pitch change sequence in semitones.
+- **Panning**: toggles output on left and right channels.
+- **Pitch**: fine pitch.
+  - **Relative**: when enabled, pitch changes are relative to the current pitch.
+- **Phase Reset**: restarts all operators and resets the waveform to its start.
+
+
+## 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/fm-opz.md

@@ -0,0 +1,102 @@
+# FM (OPZ) instrument editor
+
+the FM editor is divided into 7 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4
+- **Macros**: for other macros (volume/arp/pitch/noise).
+
+## FM
+
+OPZ is four-operator, meaning it takes four oscillators to produce a single sound.
+
+these apply to the instrument as a whole:
+- **Algorithm (ALG)**: determines how operators are connected to each other (0 to 7).
+  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - right-click to switch to a preview display of the waveform generated on a new note:
+    - left-click restarts the preview.
+    - middle-click pauses and unpauses the preview.
+    - right-click returns to algorithm view.
+- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
+
+- **LFO > Freq (FMS/PMS)**: determines how much will LFO have an effect in frequency (0 to 7).
+- **LFO > Amp (AM)**: determines how much will LFO have an effect in volume (0 to 3).
+- **LFO2 > Freq (FMS/PMS2)**: determines how much will the second LFO have an effect in frequency (0 to 7).
+- **LFO2 > Amp (AMS2)**: determines how much will the second LFO have an effect in volume (0 to 3).
+
+- **Request from TX81Z**: if a Yamaha TX81Z is plugged in as MIDI input and output device, this sends a SysEx to the device in order to fetch its current voice.
+
+these apply to each operator:
+- the crossed-arrows button can be dragged to rearrange operators.
+- **Amplitude Modulation (AM)**: makes the operator's volume affected by LFO.
+- **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 31).
+- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 31).
+- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
+- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. this is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
+- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
+- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. a change of one unit is about 0.75 dB.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (RS/KS)**: also known as "Rate Scale" or "Key Scale". determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
+- **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
+- **Fine Frequency Multiplier (Fine)**: a fine control for MULT.
+- **Envelope Generator Shift (EGS)**: adds a "handicap" to the envelope. in other words, the minimum volume of the operator.
+  - 0: no change
+  - 1: -12dB
+  - 2: -24dB
+  - 3: -48dB
+  - does not apply for OP4.
+- **Reverb (REV)**: not a true reverb. extends release time, giving a slight reverb-like effect to the operator.
+- **Fine Detune (DT)**: shifts the pitch a little (0 to 7).
+- **Waveform Select (WS)**: changes the waveform of the operator.
+- **Coarse Detune (DT2)**: shifts the pitch by tens of cents (0 to 3).
+
+#### I am familiar with Yamaha TX81Z. where's LS and KVS?
+
+these are software effects.
+- you may use TL effects to simulate LS.
+- you may access a KVS-like feature by clicking on the algorithm preview.
+
+### fixed frequency mode
+
+each operator has a Fixed Frequency mode. once enabled, the operator runs at the specified frequency regardless of the note.
+
+
+## macros
+
+these macros allow you to control several parameters of FM per tick.
+
+## FM Macros
+
+- **AM Depth**: amplitude modulation depth.
+- **PM Depth**: pitch modulation depth.
+- **LFO Speed**: LFO frequency.
+- **LFO Shape**: LFO shape. choose between saw, square, triangle, and random.
+- **AM Depth 2**: amplitude modulation depth (second LFO).
+- **PM Depth 2**: pitch modulation depth (second LFO).
+- **LFO2 Speed**: LFO 2 frequency.
+- **LFO2 Shape**: LFO 2 shape. choose between saw, square, triangle, and random.
+
+## OP1-OP4 Macros
+
+most parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: pitch change sequence in semitones.
+- **Noise Frequency**: specifies the noise frequency.
+  - this only applies to operator 4 of channel 8!
+- **Panning**: toggles output on left and right channels.
+- **Pitch**: fine pitch.
+  - **Relative**: when enabled, pitch changes are relative to the current pitch.
+- **Phase Reset**: restarts all operators and resets the waveform to its start. effectively the same as a `0Cxx` retrigger.
+
+
+## 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/fm.md

@@ -1,77 +0,0 @@
-# FM synthesis instrument editor
-
-The FM editor is divided into 7 tabs:
-
-- **FM**: for controlling the basic parameters of FM sound source.
-- **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
-- **Macros (OP1)**: for macros controlling FM parameters of operator 1
-- **Macros (OP2)**: for macros controlling FM parameters of operator 2
-- **Macros (OP3)**: for macros controlling FM parameters of operator 3
-- **Macros (OP4)**: for macros controlling FM parameters of operator 4
-- **Macros**: for miscellaneous macros controlling volume, arpeggio, and YM2151 noise generator.
-
-## FM
-
-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)
-- **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)
-- **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.
-
-![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) 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
-
-- **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.
-
-
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,66 +0,0 @@
-# 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/ga20.md

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

doc/4-instrument/game-boy.md

@@ -1,25 +1,58 @@
 # Game Boy instrument editor
 
-GB instrument editor consists of two tabs: one controlling envelope of sound channels and macro tab containing several macros.
+the Game Boy instrument editor consists of three tabs: one controlling envelope of sound channels, another for the wave synth and macro tab containing several macros.
 
 ## Game Boy
 
-- **Use software envelope**: switch to volume macro instead of envelope
-- **Initialize envelope on every note**: forces a volume reset on each new note
-- **Volume**: initial channel volume (range 0-15)
-- **Length**: envelope decay/attack duration (range 0-7)
-- **Sound Length**: cuts off sound after specified length, overriding the Length value
+- **Use software envelope**: switch to volume macro instead of envelope.
+  - this exploits a bug in the Game Boy sound hardware in order to have software envelopes ("zombie mode").
+  - only a couple emulators have accurate reproduction of this bug.
+- **Initialize envelope on every note**: forces a volume reset on each new note.
+- **Volume**: initial channel volume (0 to 15).
+- **Length**: envelope decay/attack duration (0 to 7)
+- **Sound Length**: cuts off channel after specified length, overriding the Length value.
 
-- **Up and Down radio buttons**: Up makes the envelope an attack, down makes it decay. _Note:_ For envelope attack to have any effect, start at a lower volume!
+- **Direction**: up makes the envelope an attack. down makes it decay.
+  - note: for attack to have effect, start at a lower volume.
 
-- **Hardware Sequence**: (document this)
+- **Hardware Sequence**: this allows you to define a sequence of hardware envelope changes for creating complex envelopes. see the next section for more information.
+
+### hardware sequence
+
+Furnace provides a sequencer for the hardware envelope. this way you can define timed envelope changes which may be used for simulating ADSR, adding simple release, and other things.
+
+the sequence consists of a list of "commands".
+
+the `+` button adds a new command, which may be one of the following:
+
+- **Envelope**: sets envelope values and retriggers note. it is highly recommended to have this as the first command.
+- **Sweep**: sets sweep parameters. only works on the first channel.
+- **Wait**: waits a specific number of ticks.
+- **Wait for Release**: waits until the note is released with `===` or `REL`.
+- **Loop**: goes to a previous position in the sequence.
+- **Loop until Release**: same as Loop, but doesn't have effect after releasing the note.
+
+each command in the sequence is represented in three columns:
+
+- **Tick**: the tick this command will execute, followed by position in the sequence.
+- **Command**: the command and its parameters.
+- **Move/Remove**: allows you to move the command, or remove it.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+notes:
+- only for Wave channel.
+- on Game Boy, using the wave synth may result in clicking and/or phase resets. by default Furnace attempts to mitigate this problem though, but some clicking may still be audible.
 
 ## Macros
 
-- **Volume**: volume sequence. _Note:_ This only appears if "Use software envelope" is checked.
-- **Arpeggio**: pitch in half-steps
-- **Duty/Noise**: pulse wave duty cycle or noise mode sequence
-- **Waveform**: ch3 wavetable sequence
-- **Panning**: output for left and right channels
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
+- **Volume**: volume sequence.
+  - note: this only appears if "Use software envelope" is checked.
+- **Arpeggio**: pitch sequence.
+- **Duty/Noise**: pulse wave duty cycle or noise mode sequence.
+- **Waveform**: channel 3 wavetable sequence.
+- **Panning**: output for left and right channels.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/k007232.md

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

doc/4-instrument/k053260.md

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

doc/4-instrument/lynx.md

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

doc/4-instrument/msm5232.md

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

doc/4-instrument/msm6258.md

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

doc/4-instrument/msm6295.md

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

doc/4-instrument/n163.md

@@ -1,6 +1,6 @@
 # Namco 163 instrument editor
 
-The Namco 163 instrument editor consists of two tabs: "Namco 163" for control of various waveform parameters, and "Macro" containing several macros.
+the Namco 163 instrument editor consists of three tabs: "Namco 163" for control of various waveform parameters, "Wavetable" for control of the wave synth and "Macro" containing several macros.
 
 ## Namco 163
 
@@ -12,15 +12,20 @@ The Namco 163 instrument editor consists of two tabs: "Namco 163" for control of
 - **Position**: determines the waveform position in RAM.
 - **Length**: determines the waveform length in RAM.
 
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+note that setting the Update Rate to something greater than 1 and playing the instrument in two channels may result in conflicts.
+
 ## Macros
 
-- **Volume**: volume levels sequence
-- **Arpeggio**: pitch sequence
-- **Wave Pos**: sets waveform seek position in RAM
-- **Waveform**: sets waveform source for playback immediately or update later
-- **Panning**: output for left and right channels
-- **Pitch**: fine pitch
-- **Wave Length**: sets waveform length
+- **Volume**: volume levels sequence.
+- **Arpeggio**: pitch sequence.
+- **Wave Pos**: sets waveform seek position in RAM.
+- **Waveform**: sets waveform.
+- **Pitch**: fine pitch.
+- **Wave Length**: sets waveform length.
 <!--
 - **Phase Reset**: trigger restart of waveform
 -->

doc/4-instrument/nes.md

@@ -1,18 +1,52 @@
-# Standard instrument editor
+# NES instrument editor
 
-The instrument editor for NES consists of these macros:
+the NES instrument editor consists of two tabs.
 
-- **Volume**: volume.
-- **Arpeggio**: pitch in half-steps.
-- **Duty**: duty cycle and noise mode.
+## DPCM
+
+this tab is somewhat similar to [the Sample instrument editor](sample.md), but it has been tailored for use with NES' DPCM channel.
+
+- **Sample**: specifies which sample should be assigned to the instrument.
+- **Use sample map**: enables mapping different samples to notes. see next section for more information.
+  - when this option is disabled, 16 notes (from C-0 to D#1 and repeating) will map to the DPCM channel's 16 possible pitches.
+
+### sample map
+
+the sample map allows you to set a sample for each note.
+
+after enabling this option, a table appears with the contents of the sample map.
+- the first column represents the input note.
+- the second column allows you to type in a sample number for each note.
+  - you may press Delete to clear it.
+- the third one is used to set the DPCM pitch at which the specified sample will play.
+  - for possible values, refer to the table below.
+  - you may press Delete to clear it. if no value is specified, the last pitch is used.
+- the fourth column allows you to set the initial delta counter value when playing the sample.
+  - this is an hexadecimal number.
+  - the range is `00` to `7F`.
+  - you may press Delete to clear it. if no value is specified, the delta counter isn't altered.
+- the fifth and last column provides a combo box for selecting a sample.
+
+you may right-click anywhere in the number, pitch and delta columns for additional options:
+- **set entire map to this pitch**: sets the DPCM pitch of all notes to the selected cell's.
+- **set entire map to this delta counter value**: sets the initial delta counter value of all notes to the selected cell's.
+- **set entire map to this sample**: sets the sample number of all notes to the selected cell's.
+- **reset pitches**: resets the sample map's DPCM pitches to defaults (15).
+- **clear delta counter values**: removes all delta counter values from the map.
+- **clear map samples**: removes all samples from the map.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty/Noise**: duty cycle and noise mode.
   - pulse duty cycles:
     - `0`: 12.5%
     - `1`: 25%
     - `2`: 50%
     - `3`: 75%
   - noise modes:
-    - `0`: long noise.
-    - `1`: short noise.
-- **Panning**: output for left and right channels.
+    - `0`: long noise
+    - `1`: short noise
 - **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/pce.md

@@ -1,14 +1,27 @@
 # NEC PC Engine instrument editor
 
-The PCE instrument editor consists of these macros:
+the PCE instrument editor contains three tabs: Sample, Wavetable and Macros.
 
-- **Volume**: volume sequence
-- **Arpeggio**: pitch in half-steps
-- **Noise**: enable noise mode (ch5 and ch6 only)
-- **Waveform**: wavetable sequence
-- **Panning (left)**: output level for left channel
-- **Panning (right)**: output level for right channel
-- **Pitch**: fine pitch
-- **Phase Reset**: trigger restart of waveform
+## Sample
 
-It also has wavetable synthesizer support, but unfortunately, it clicks a lot when in use on the HuC6280.
+for sample settings, see [the Sample instrument editor](sample.md).
+
+the only differences are the lack of an "Use wavetable" option, and the presence of a "Use sample" one.
+
+## Wavetable
+
+this allows you to enable and configure the Furnace wavetable synthesizer. see [this page](wavesynth.md) for more information.
+
+note: on PC Engine, using the wave synth may result in clicking and/or phase resets. by default Furnace attempts to mitigate this problem though.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise**: enable noise mode.
+  - only on channels 5 and 6.
+- **Waveform**: wavetable 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/pet.md

@@ -0,0 +1,8 @@
+# Commodore PET instrument editor
+
+the PET instrument editor consists of these macros:
+
+- **Volume**: volume sequence (on/off).
+- **Arpeggio**: pitch sequence.
+- **Waveform**: an 8×1 waveform.
+- **Pitch**: fine pitch sequence.

doc/4-instrument/pokemini.md

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