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

.gitignore

@@ -15,6 +15,8 @@ test/songs/
 test/delta/
 test/result/
 test/assert_delta
+android/local.properties
+android/.idea/
 android/.gradle/
 android/app/build/
 android/app/.cxx/

CMakeLists.txt

@@ -455,6 +455,8 @@ src/engine/platform/sound/c64_fp/WaveformCalculator.cpp
 src/engine/platform/sound/c64_fp/WaveformGenerator.cpp
 src/engine/platform/sound/c64_fp/resample/SincResampler.cpp
 
+src/engine/platform/sound/c64_d/dsid.c
+
 src/engine/platform/sound/tia/AudioChannel.cpp
 src/engine/platform/sound/tia/Audio.cpp
 
@@ -804,7 +806,6 @@ if (BUILD_GUI)
   list(APPEND USED_SOURCES ${GUI_SOURCES})
   list(APPEND DEPENDENCIES_INCLUDE_DIRS
     extern/imgui_patched
-    extern/imgui_conf
     extern/imgui_patched/backends
     extern/IconFontCppHeaders
     extern/igfd
@@ -861,7 +862,7 @@ endif()
 string(REPLACE ";" " " WARNING_FLAGS_STRING "${WARNING_FLAGS}")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${WARNING_FLAGS_STRING}")
 if (WARNINGS_ARE_ERRORS)
-  message(WARNING
+  message(STATUS
     "Treating all warnings in furnace's C++ code as errors! "
     "Please report any errors you encounter on the bug tracker."
   )
@@ -876,7 +877,7 @@ else()
 endif()
 
 target_include_directories(furnace SYSTEM PRIVATE ${DEPENDENCIES_INCLUDE_DIRS})
-target_compile_definitions(furnace PRIVATE ${DEPENDENCIES_DEFINES} IMGUI_USER_CONFIG="imconfig_fur.h")
+target_compile_definitions(furnace PRIVATE ${DEPENDENCIES_DEFINES})
 target_compile_options(furnace PRIVATE ${DEPENDENCIES_COMPILE_OPTIONS})
 target_link_libraries(furnace PRIVATE ${DEPENDENCIES_LIBRARIES})
 if (PKG_CONFIG_FOUND AND (SYSTEM_FMT OR SYSTEM_LIBSNDFILE OR SYSTEM_ZLIB OR SYSTEM_SDL2 OR SYSTEM_RTMIDI OR WITH_JACK))

README.md

@@ -9,7 +9,9 @@ the biggest multi-system chiptune tracker ever made!
 ---
 ## downloads
 
-check out the [Releases](https://github.com/tildearrow/furnace/releases) page. available for Windows, macOS and Linux (AppImage).
+check out the [Releases](https://github.com/tildearrow/furnace/releases) page. available for Windows, macOS and Linux.
+
+for other operating systems, you may [build the source](#developer-info).
 
 [see here](https://nightly.link/tildearrow/furnace/workflows/build/master) for the latest unstable build.
 
@@ -79,6 +81,7 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
   - modern/fantasy:
     - Commander X16 VERA
     - tildearrow Sound Unit
+    - Generic PCM DAC
 - mix and match sound chips!
   - over 200 ready to use presets from computers, game consoles and arcade boards...
   - ...or create your own - up to 32 of them or a total of 128 channels!
@@ -90,6 +93,7 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
   - clean-room design (guesswork and ABX tests only, no decompilation involved)
   - some bug/quirk implementation for increased playback accuracy through compatibility flags
 - VGM export
+- ZSM export for Commander X16
 - modular layout that you may adapt to your needs
 - audio file export - entire song, per chip or per channel
 - quality emulation cores (Nuked, MAME, SameBoy, Mednafen PCE, NSFplay, puNES, reSID, Stella, SAASound, vgsound_emu and ymfm)
@@ -120,11 +124,11 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
 # 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 incomplete though.
+- **help**: check out the [documentation](doc/README.md). it's about 80% complete.
 
 ## packages
 
-[![Packaging status](https://repology.org/badge/tiny-repos/furnace.svg)](https://repology.org/project/furnace/versions)
+[![Packaging status](https://repology.org/badge/vertical-allrepos/furnace.svg)](https://repology.org/project/furnace/versions)
 
 some people have provided packages for Unix/Unix-like distributions. here's a list.
 
@@ -156,6 +160,7 @@ otherwise, you may also need the following:
 - libx11
 - libasound
 - libGL
+- any other libraries which may be used by SDL
 
 some Linux distributions (e.g. Ubuntu or openSUSE) will require you to install the `-dev` versions of these.
 
@@ -255,6 +260,17 @@ Available options:
 | `WITH_INSTRUMENTS` | `ON` | Install demo instruments on `make install` |
 | `WITH_WAVETABLES` | `ON` | Install wavetables on `make install` |
 
+## CMake Error
+
+if it says something about a missing subdirectory in `extern`, then either:
+
+1. you didn't set up submodules, or
+2. you downloaded the source as a .zip or .tar.gz. don't do this.
+
+if 1, you may run `git submodule update --init --recursive`. this will initialize submodules.
+
+if 2, clone this repo.
+
 ## console usage
 
 (note: if on Windows, type `furnace.exe` instead, or `Debug\furnace.exe` on MSVC)
@@ -289,7 +305,7 @@ this is due to Apple's application signing policy. a workaround is to right clic
 > it says "Furnace" is damaged and can't be opened!
 
 **as of Monterey, this workaround no longer works (especially on ARM).** yeah, Apple has decided to be strict on the matter.
-if you happen to be on that version, use this workaround instead (on a Terminal):
+if you happen to be on that version (or later), use this workaround instead (on a Terminal):
 
 ```
 xattr -d com.apple.quarantine /path/to/Furnace.app
@@ -301,7 +317,7 @@ you may need to log out and/or reboot after doing this.
 
 > where's the manual?
 
-see [doc/](doc/README.md). it's kind of incomplete though.
+it is in [doc/](doc/README.md).
 
 > is there a tutorial?
 

TODO.md

@@ -1,16 +1,12 @@
-# to-do for 0.6pre6
+# to-do for 0.6pre7
 
 - tutorial?
 - ease-of-use improvements... ideas:
   - preset compat flags
-  - setting to toggle the Choose a System screen on new project
   - 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 
-  - Had a hard time finding the docs on github and in Furnace's folder.
   - make .pdf manual out of doc/
-  - you're going too slow; please run
   - break compatibility if it relieves complexity
-- ins/wave/sample organization (folders and all)
 - multi-key binds
 - bug fixes

android/app/build.gradle

@@ -15,11 +15,11 @@ android {
         }
         minSdkVersion 21
         targetSdkVersion 26
-        versionCode 158
-        versionName "0.6pre5"
+        versionCode 162
+        versionName "0.6pre7"
         externalNativeBuild {
             cmake {
-                arguments "-DANDROID_APP_PLATFORM=android-21", "-DANDROID_STL=c++_static"
+                arguments "-DANDROID_APP_PLATFORM=android-21", "-DANDROID_STL=c++_static", "-DWARNINGS_ARE_ERRORS=ON"
                 // abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
                 abiFilters 'arm64-v8a'
             }

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="158"
-    android:versionName="0.6pre5"
+    android:versionCode="162"
+    android:versionName="0.6pre7"
     android:installLocation="auto">
 
     <!-- OpenGL ES 2.0 -->

doc/1-intro/README.md

@@ -12,7 +12,7 @@ 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.
+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.
 
 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.
 

doc/1-intro/concepts.md

@@ -0,0 +1,36 @@
+# 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## sound
+
+Different chips have different capabilities. Even within the same chip, each channel may have its own ways of making sound.
+- Some channels use one or more waveform **generators** (sine, square, noise...) to build up a sound.
+- Of special note are **[FM (frequency modulation)](../4-instrument/fm.md)** channels, which use a number of generators called **operators** that can interact to make very complex sounds.
+- Some channels use **[samples](../6-sample/README.md)** - recordings of sounds, often with defined loop points to allow a note to sustain.
+- Some channels use **[wavetables](../5-wave/README.md)**, which are like very short samples of fixed length that automatically loop.

doc/2-interface/README.md

@@ -36,6 +36,7 @@ advanced topics:
 
 other topics:
 
+- [settings](../2-interface/settings.md)
 - [UI components](components.md)
 - [global keyboard shortcuts](keyboard.md)
 - [basic mode](basic-mode.md)

doc/2-interface/asset-list.md

@@ -3,21 +3,21 @@
 ![instruments window](instruments.png)
 
 Buttons from left to right:
-- **Add:** Creates a new, default instrument.
-- **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.
-- **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.
+- **Add**: Creates a new, default instrument.
+- **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.
+- **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.
+- **New folder**: Creates a new folder.
 
 Instruments may be dragged from folder to folder and even rearranged within folders without changing their associated numbers.
 
@@ -34,5 +34,5 @@ Everything from the instrument list applies here also, with one major difference
 ![samples window](samples.png)
 
 Everything from the wavetables list applies here also, with the addition of two buttons:
-- **Preview:** Plays the selected sample at its default note.
-- **Stop preview:** Stops the sample playback.
+- **Preview**: Plays the selected sample at its default note.
+- **Stop preview**: Stops the sample playback.

doc/2-interface/basic-mode.md

@@ -1,6 +1,6 @@
 # basic mode
 
-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.
+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:

doc/2-interface/menu-bar.md

@@ -8,6 +8,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
 - **open...**: opens the file picker, allowing you to select a song to open.
 - **open recent**: contains a list of the songs you've opened before.
   - **clear history**: this option erases the file history.
+
 - **save**: saves the current song.
   - opens the file picker if this is a new song, or a backup.
 - **save as...**: opens the file picker, allowing you to save the song under a different name.
@@ -29,12 +30,14 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
     - Arcade (YM2151 + SegaPCM 5-channel compatibility)
     - Neo Geo CD (DefleMask 1.0+)
   - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
+
 - **export audio...**: export your song to a .wav file. see next section for more details.
 - **export VGM...**: export your song to a .vgm file. see next section for more details.
 - **export ZSM...**: export your song to a .zsm file. see next section for more details.
   - only available when there's a YM2151 and/or VERA.
 - **export command stream...**: export song data to a command stream file. see next section for more details.
   - this option is for developers.
+  
 - **add chip...**: add a chip to the current song.
 - **configure chip...**: set a chip's parameters.
   - for a list of parameters, see [7-systems](../7-systems/README.md).
@@ -42,6 +45,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
   - **Preserve channel positions**: enable this option to make sure Furnace does not auto-arrange/delete channels to compensate for differing channel counts. this can be useful for doing ports, e.g. from Genesis to PC-98.
 - **remove chip...**: remove a chip.
   - **Preserve channel positions**: same thing as above.
+
 - **restore backup**: restore a previously saved backup.
   - Furnace keeps up to 5 backups of a song.
   - the backup directory is located in:
@@ -49,6 +53,7 @@ the menu bar allows you to select five menus: file, edit, settings, window and h
     - 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.
+
 - **exit**: I think you know what this does.
 
 ## export audio
@@ -131,6 +136,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 
 - **undo**: reverts the last action.
 - **redo**: repeats what you undid previously.
+
 - **cut**: moves the current selection in the pattern view to clipboard.
 - **copy**: copies the current selection in the pattern view to clipboard.
 - **paste**: inserts the clipboard's contents in the cursor position.
@@ -147,11 +153,16 @@ it's not really useful, unless you're a developer and want to use a command stre
   - if the selection is tall, it will select the entire column.
   - if a column is already selected, it will select the entire channel.
   - if a channel is already selected, it will select the entire pattern.
+
 - **operation mask**: this is an advanced feature. see [this page](../3-pattern/opmask.md) for more information.
 - **input latch**: this is an advanced feature. see [this page](../3-pattern/inputlatch.md) for more information.
+
 - **note/octave up/down**: transposes notes in the current selection.
+
 - **values up/down**: changes values in the current selection by ±1 or ±16.
+
 - **transpose**: transpose notes or change values by a specific amount.
+
 - **interpolate**: fills in gaps in the selection by interpolation between values.
 - **change instrument**: changes the instrument number in a selection.
 - **gradient/fade**: replace the selection with a "gradient" that goes from the beginning of the selection to the end.
@@ -163,17 +174,22 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **randomize**: replaces the selection with random values.
   - does not affect the note column.
 - **invert values**: `00` becomes `FF`, `01` becomes `FE`, `02` becomes `FD` and so on.
+
 - **flip selection**: flips the selection so it is backwards.
 - **collapse/expand amount**: allows you to specify how much to collapse/expand in the next options.
 - **collapse**: shrinks the selected contents.
 - **expand**: expands the selected contents.
+
 - **collapse pattern**: same as collapse, but affects the entire pattern.
 - **expand pattern**: same as expand, but affects the entire pattern.
+
 - **collapse song**: same as collapse, but affects the entire song.
   - it also changes speeds and pattern length to compensate.
 - **expand song**: same as expand, but affects the entire song.
   - it also changes speeds and pattern length to compensate.
+
 - **find/replace**: opens the Find/Replace window. see [this page](../3-pattern/find-replace.md) for more information.
+
 - **clear**: allows you to mass-delete things like songs, instruments and the like.
 
 # settings
@@ -183,7 +199,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **basic mode**: toggles [Basic Mode](basic-mode.md).
 - **visualizer**: toggles pattern view particle effects when the song plays.
 - **reset layout**: resets the workspace to its defaults.
-- **settings...**: opens the Settings window.
+- **settings...**: opens the Settings window. these are detailed in [settings.md].
 
 # window
 
@@ -202,9 +218,11 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **chip manager**: shows/hides the Chip Manager window.
 - **compatibility flags**: shows/hides the Compatibility Flags window.
 - **song comments**: shows/hides the Song Comments window.
-- **instrument editor**: shows/hides the Instrument Editor.
+
+- **instrument editor**: shows/hides the Instrument Editor
 - **wavetable editor**: shows/hides the Wavetable Editor.
 - **sample editor**: shows/hides the Sample Editor.
+
 - **play/edit controls**: shows/hides the Play/Edit Controls.
 - **piano/input pad**: shows/hides the Piano/Input Pad window.
 - **oscilloscope (master)**: shows/hides the oscilloscope.

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

@@ -2,19 +2,19 @@
 
 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.
+- ![](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.
 
 ## layouts
 

doc/2-interface/settings.md

@@ -0,0 +1,387 @@
+# settings
+
+settings are saved when clicking the **OK** button at the bottom of the dialog.
+
+
+
+# General
+
+- **Workspace layout**
+  - **Import**: reads a .ini layout file.
+  - **Export**: writes current layout to a .ini file.
+  - **Reset**: resets layout to default.
+
+- **Initial system**: the system of chips loaded on starting Furnace.
+  - **Current system**: sets current chips as default.
+  - **Randomize**: set default to a random system.
+    - this will not choose a random system at each start.
+  - **Reset to defaults**: sets default to "Sega Genesis/Mega Drive".
+  - **Name**: name for the default system. may be set to any text.
+  - system configuration: same as in the [chip manager](../8-advanced/chip-manager.md) and [mixer](../8-advanced/mixer.md).
+
+- **Play intro on start-up:**
+  - **No**: skips intro entirely.
+  - **Short**: shows silent title screen briefly.
+  - **Full (short when loading song)**: shows animated musical intro unless started with a song (command line, double-clicking a .fur file, etc.)
+  - **Full (always)**: always shows animated musical intro.
+- **When creating new song**:
+  - **Display system preset selector**
+  - **Start with initial system**
+
+- **Double-click time (seconds)**: maximum time between mouse clicks to recognize them as a double-click.
+- **Toggle channel solo on:** select which interactions with a channel header will toggle solo for that channel.
+- **Push value when overwriting instead of clearing it**: in the order list and pattern editors, typing into an already-filled value will shift digits instead of starting fresh.
+  - if off: moving the cursor onto the value `A5` and typing a "B" results in `0B`.
+  - if on: with the cursor on the value `A5` and typing a "B" results in `5B`.
+- **Move cursor up on backspace-delete**
+- **Move cursor by edit step on delete**
+- **Change current instrument when changing instrument column (absorb)**
+- **Delete effect value when deleting effect**
+- **Change order when scrolling outside of pattern bounds**:
+  - if off, the pattern edit cursor will stay locked within the current order.
+  - if on, moving the cursor past the edge of the previous or next order will move to that order.
+- **Move cursor by edit step on insert (push)**
+- **Move cursor to end of clipboard content when pasting**
+- **Don't scroll when moving cursor**
+- **Double click selects entire column**
+- **Allow docking editors**
+- **Don't raise pattern editor on click**
+- **Focus pattern editor when selecting instrument**
+- **Restart song when changing chip properties**
+- **Use system file picker**: use native OS file dialog instead of Furnace's.
+- **Only allow window movement when clicking on title bar**
+- **Enable event delay**
+  - may cause issues with high-polling-rate mice when previewing notes.
+- **Power-saving mode**
+  - saves power by lowering the frame rate to 2fps when idle.
+  - may cause issues under Mesa drivers!
+- **Disable threaded input (restart after changing!)**
+  - threaded input processes key presses for note preview on a separate thread (on supported platforms), which reduces latency.
+  - however, crashes have been reported when threaded input is on. enable this option if that is the case.
+- **Remember window position**
+  - remembers the window's last position on start-up.
+- **New instruments are blank**
+- **Save unused patterns**
+- **Compress when saving**
+  - use zlib to compress saved songs.
+- **Cursor follows current order when moving it**
+  - applies when playback is stopped.
+- **Audio export loop/fade out time:**
+  - **Set to these values on start-up:**
+    - **Loops**: number of additional times to play through `0Bxx` song loop.
+    - **Fade out (seconds)**: length of fade out after final loop.
+  - **Remember last values**
+- **Note preview behavior:**
+  - **Never**
+  - **When cursor is in Note column**
+  - **When cursor is in Note column or not in edit mode**
+  - **Always**
+- **Wrap pattern cursor horizontally:**
+  - **No**
+  - **Yes**
+  - **Yes, and move to next/prev row**
+- **Wrap pattern cursor vertically:**
+  - **No**
+  - **Yes**
+  - **Yes, and move to next/prev pattern**
+- **Cursor movement keys behavior:**
+  - **Move by one**
+  - **Move by Edit Step**
+- **Effect input cursor behavior:**
+  - **Move down**
+  - **Move to effect value (otherwise move down)**
+  - **Move to effect value/next effect and wrap around**
+- **Allow dragging selection:**
+  - **No**
+  - **Yes**
+  - **Yes (while holding Ctrl only)**
+
+
+
+# Audio/MIDI
+
+- **Backend**: select SDL or JACK for audio output.
+  - only appears on Linux, or MacOS compiled with JACK support
+- **Device**: audio device for playback.
+- **Sample rate**
+- **Outputs**: select number of audio outputs created, up to 16.
+  - only appears when Backend is JACK.
+- **Channels**: number of output channels to use.
+- **Buffer size**: size of buffer in both samples and milliseconds.
+- **Quality**: selects quality of resampling. low quality reduces CPU load.
+- **Metronome volume**
+- **Low-latency mode (experimental!)**: reduces latency by running the engine faster than the tick rate. useful for live playback/jam mode.
+  - _warning:_ experimental! may produce glitches. only enable if your buffer size is small (10ms or less).
+- **Force mono audio**
+- **Software clipping**: clips output to nominal range (-1.0 to 1.0) before passing it to the audio device.
+  - this avoids activating Windows' built-in limiter.
+- **want:** displays requested audio configuration.
+- **got:** displays actual audio configuration returned by audio backend.
+
+- **MIDI input**
+- **MIDI output**
+- **MIDI input settings**
+  - **Note input**
+  - **Velocity input**
+  - **Map MIDI channels to direct channels**
+  - **Map Yamaha FM voice data to instruments**
+  - **Program change is instrument selection**
+  - **Value input style**:
+    - **Disabled/custom**
+    - **Two octaves (0 is C-4, F is D#5)**
+    - **Raw (note number is value)**
+    - **Two octaves alternate (lower keys are 0-9, upper keys are A-F)**
+    - **Use dual control change (one for each nibble)**
+      - **CC of upper nibble**
+      - **CC of lower nibble**
+    - **Use 14-bit control change**
+      - **MSB CC**
+      - **LSB CC**
+    - **Use single control change**
+      - **Control**
+  - **Per-column control change**
+    - **Instrument**\
+      **Volume**\
+      **Effect `x` type**\
+      **Effect `x` value**
+      - **Disabled/custom**
+      - **Use dual control change (one for each nibble)**
+        - **CC of upper nibble**
+        - **CC of lower nibble**
+      - **Use 14-bit control change**
+        - **MSB CC**
+        - **LSB CC**
+      - **Use single control change (imprecise)**
+        - **Control**
+  - **Volume curve**
+  - **Actions:**
+    - **`+`** button: adds a new action.
+    - window-with-arrow button: new action with learning! press a button or move a slider/knob/something on your device.
+    - each action has the following:
+      - **Type**
+      - **Channel**
+      - **Note/Control**
+      - **Velocity/Value**
+      - **Action**
+      - **Learn**
+      - **Remove**
+
+- **MIDI output settings**
+  - **Output mode:**
+    - **Off (use for TX81Z)**
+    - **Melodic**
+  - **Send Program Change**
+  - **Send MIDI clock**
+  - **Send MIDI timecode**
+    - **Timecode frame rate:**
+      - **Closest to Tick Rate**
+      - **Film (24fps)**
+      - **PAL (25fps)**
+      - **NTSC drop (29.97fps)**
+      - **NTSC non-drop (30fps)**
+
+# Emulation
+- **Arcade/YM2151 core**
+  - **ymfm**
+  - **Nuked-OPM**
+- **Genesis/YM2612 core**
+  - **Nuked-OPN2**
+  - **ymfm**
+- **SN76489 core**
+  - **MAME**
+  - **Nuked-PSG Mod**
+- **NES core**
+  - **puNES**
+  - **NSFplay**
+- **FDS core**
+  - **puNES**
+  - **NSFplay**
+- **SID core**
+  - **reSID**
+  - **reSIDfp**
+- **POKEY core**
+  - **Atari800 (mzpokeysnd)**
+  - **ASAP (C++ port)**
+- **OPN/OPNA/OPNB cores**
+  - **ymfm only**
+  - **Nuked-OPN2 (FM) + ymfm (SSG/ADPCM)**
+
+- **PC Speaker strategy:**
+  - **evdev SND_TONE**
+  - **KIOCSOUND on /dev/tty1**
+  - **/dev/port**
+  - **KIOCSOUND on standard output**
+  - **outb()**
+
+- **Sample ROMs:**
+  - **OPL4 YRW801 path**
+  - **MultiPCM TG100 path**
+  - **MultiPCM MU5 path**
+
+
+
+# Appearance
+
+- **Render driver**
+- **Automatic UI scaling factor**: automatically match the OS's UI scaling.
+- **UI scaling factor**: only if "Automatic UI scaling factor" is off.
+- **Main font**: if "Custom...", a file path selector will appear beneath.
+- **Size**
+- **Pattern font**: if "Custom...", a file path selector will appear beneath.
+- **Size**
+- **Icon 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.
+  - these are a temporary solution until dynamic font atlas is implemented in Dear ImGui.
+
+- **Number of recent files**
+
+- **Pattern view labels:**
+- **Note off (3-char)**: default is `OFF`
+- **Note release (3-char)**: default is `===`.
+- **Macro release (3-char)**: default is `REL`.
+- **Empty field (3-char)**: default is `...`.
+- **Empty field (2-char)**: default is `..`.
+
+- **Orders row number format:**
+  - **Decimal**
+  - **Hexadecimal**
+- **Pattern row number format:**
+  - **Decimal**
+  - **Hexadecimal**
+- **FM parameter names:**
+  - **Friendly**
+  - **Technical**
+  - **Technical (alternate)**
+
+- **Title bar:**
+  - **Furnace**
+  - **Song Name - Furnace**
+  - **file_name.fur - Furnace**
+  - **/path/to/file.fur - Furnace**
+- **Display system name on title bar**
+- **Display chip names instead of "multi-system" in title bar**
+- **Status bar:**
+  - **Cursor details**
+  - **File path**
+  - **Cursor details or file path**
+  - **Nothing**
+- **Play/edit controls layout:**
+  - **Classic**
+  - **Compact**
+  - **Compact (vertical)**
+  - **Split**
+- **Position of buttons in Orders:**
+  - **Top**
+  - **Left**
+  - **Right**
+- **FM parameter editor layout:**
+  - **Modern**
+  - **Compact (2x2, classic)**
+  - **Compact (1x4)**
+  - **Compact (4x1)**
+  - **Alternate (2x2)**
+  - **Alternate (1x4)**
+  - **Alternate (4x1)**
+- **Position of Sustain in FM editor:**
+  - **Between Decay and Sustain Rate**
+  - **After Release Rate**
+- **Macro editor layout:**
+  - **Unified**
+  - **Mobile**
+  - **Grid**
+  - **Single (with list)**
+  - **Single (combo box)**
+
+- **Namco 163 chip name**
+
+- **Channel colors:**
+  - **Single**
+  - **Channel type**
+  - **Instrument type**
+- **Channel name colors:**
+  - **Single**
+  - **Channel type**
+  - **Instrument type**
+- **Channel style:**
+  - **Classic**
+  - **Line**
+  - **Round**
+  - **Split button**
+  - **Square border**
+  - **Round border**
+- **Channel volume bar:**
+  - **None**
+  - **Simple**
+  - **Stereo**
+  - **Real**
+  - **Real (stereo)**
+- **Channel feedback style:**
+  - **Off**
+  - **Note**
+  - **Volume**
+  - **Active**
+- **Channel font:**
+  - **Regular**
+  - **Monospace**
+- **Center channel name**
+
+- **Colorize instrument editor using instrument type**
+- **Use separate colors for carriers/modulators in FM editor**
+- **Unified instrument/wavetable/sample list**
+- **Horizontal instrument list**
+- **Use standard OPL waveform names**
+- **Overflow pattern highlights**
+- **Display previous/next pattern**
+- **Use German notation**: display `B` notes as `H`, and `A#` notes as `B`.
+- **Single-digit effects for 00-0F**
+- **Center pattern view**: centers pattern horizontally in view.
+- **Unsigned FM detune values**
+- **Highlight channel at cursor in Orders**
+- **About screen party time**
+  - _warning:_ may cause epileptic seizures.
+
+- **Use compact wave editor**
+- **Use classic macro editor vertical slider**
+- **Rounded window corners**
+- **Rounded buttons**
+- **Rounded menu corners**
+- **Borders around widgets**
+- **Disable fade-in during start-up**
+  
+- **Oscilloscope settings:**
+  - **Rounded corners**
+  - **Fill entire window**
+  - **Waveform goes out of bounds**
+  - **Border**
+
+- **Pattern view spacing after:**
+  - **Note**
+  - **Instrument**
+  - **Volume**
+  - **Effect**
+  - **Effect value**
+- **Color scheme**
+  - **Import**
+  - **Export**
+  - **Reset defaults**
+  - **General**
+    - **Color scheme type:**
+      - **Dark**
+      - **Light**
+    - **Frame shading**
+  - several more categories...
+
+
+
+# Keyboard
+
+- **Import**
+- **Export**
+- **Reset defaults**
+- several categories of keybinds...
+  - click on a keybind then enter a key or key combination to change it
+  - right-click to clear the keybind

doc/2-interface/song-info.md

@@ -1,49 +1,49 @@
 # song info
 
-- "Name" is for the track's title.
-- "Author" is used to list the contributors to a song. If the song is a cover of someone else's track, it's customary to list their name first, followed by `[cv. YourName]`.
-- "Album" can be used to store the associated album name, the name of the game the song is from, or whatever.
-- "System" is for the game or computer the track is designed for. This is automatically set when creating a new tune, but it can be changed to anything one wants. The "Auto" button will provide a guess based on the chips in use.
+- **Name**: The track's title.
+- **Author**: List of contributors to a song. If the song is a cover of someone else's track, it's customary to list their name first, followed by `[cv. YourName]`.
+- **Album**: The associated album name, the name of the game the song is from, or whatever.
+- **System**: The game console or computer the track is designed for. This is automatically set when creating a new tune, but it can be changed to anything one wants. The **Auto** button will provide a guess based on the chips in use.
 
 All of this metadata will be included in a VGM export. This isn't the case for a WAV export, however.
 
-"Tuning (A-4)" allows one to set tuning based on the note A-4, which should be 440 in most cases. Opening an Amiga MOD will set it to 436 for hardware compatibility.
+**Tuning (A-4)**: Set tuning based on the note A-4, which should be 440 in most cases. Opening an Amiga MOD will set it to 436 for hardware compatibility.
 
 # 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" sets the title of 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
 
 There are multiple ways to set the tempo of a song.
 
-**Tick Rate** sets the frequency of ticks per second, the rate at which notes and effects are processed.
-- All values are allowed for all chips, but most chips have hardware limitations that mean they should stay at either 60 (approximately NTSC) or 50 (exactly PAL).
+**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** sets the number of ticks per row.
+**Speed**: The number of ticks per row.
 - Clicking the "Speed" button changes to more complex modes covered in the [grooves] page.
 
-**Virtual Tempo** simulates any arbitrary tempo without altering the tick rate. It does this by adding or skipping ticks to approximate the tempo. The two numbers represent a ratio applied to the actual tick rate. Example:
+**Virtual Tempo**: Simulates any arbitrary tempo without altering the tick rate. It does this by adding or skipping ticks to approximate the tempo. The two numbers represent a ratio applied to the actual tick rate. Example:
 - Set tick rate to 150 BPM (60 Hz) and speed to 6.
 - Set the first virtual tempo number (numerator) to 200.
 - Set the second virtual tempo number (denominator) to 150.
 - The track will play at 200 BPM.
 - The ratio doesn't have to match BPM numbers. Set the numerator to 4 and the denominator to 5, and the virtual BPM becomes 150 × 4/5 = 120.
 
-**Divider** changes the effective tick rate. A tick rate of 60Hz and a divisor of 6 will result in ticks lasting a tenth of a second each!
+**Divider**: Changes the effective tick rate. A tick rate of 60Hz and a divisor of 6 will result in ticks lasting a tenth of a second each!
 
-**Highlight** sets the pattern row highlights:
+**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** is 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** shows 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/effects.md

@@ -1,78 +1,99 @@
 # effect list
 
-most of the effect numbers are 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`.
+most of the effect numbers are from ProTracker / FastTracker 2.
 
-- `00xy`: arpeggio. after using this effect the channel will rapidly switch between `note`, `note+x` and `note+y`.
-- `01xx`: slide up.
-- `02xx`: slide down.
-- `03xx`: note portamento.
-  - a note must be present for this effect to work.
-- `04xy`: vibrato. `x` is the speed, while `y` is the depth.
-  - maximum vibrato depth is ±1 semitone.
-- `07xy`: tremolo. `x` is the speed, while `y` is the depth.
-  - maximum tremolo depth is -60 volume steps.
-- `08xy`: set panning. `x` is the left channel and `y` is the right one.
-  - not all chips support this effect.
-- `80xx`: set panning (linear). this effect behaves more like other trackers:
+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.
+- `FAxy`: **Fast volume slide.** same as `0Axy` above but 4× faster.
+- `F3xx`: **Fine volume slide up.** same as `0Ax0` but 64× slower.
+- `F4xx`: **Fine volume slide down.** same as `0A0x` but 64× slower.
+- `F8xx`: **Single tick volume slide up.** adds `x` to volume on first tick only.
+- `F9xx`: **Single tick volume slide down.** subtracts `x` from volume on first tick only.
+
+- `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.
+
+## pitch
+
+- `E5xx`: **Set pitch.** `00` is -1 semitone, `80` is base pitch, `FF` is nearly +1 semitone.
+- `01xx`: **Pitch slide up.**
+- `02xx`: **Pitch slide down.**
+- `F1xx`: **Single tick pitch slide up.**
+- `F2xx`: **Single tick pitch slide down.**
+
+- `03xx`: **Portamento.** slides the current note's pitch to the specified note.  `x` is the slide speed.
+  - A note _must_ be present for this effect to work.
+- `E1xy`: **Note slide up.** `x` is the speed, while `y` is how many semitones to slide up.
+- `E2xy`: **Note slide down.** `x` is the speed, while `y` is how many semitones to slide down.
+
+- `EAxx`: **Toggle legato.** while on, notes instantly change the pitch of the currrently playing sound instead of starting it over.
+- `00xy`: **Arpeggio.** after using this effect the channel will rapidly switch between semitone values of `note`, `note + x` and `note + y`.
+- `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values. default is 1.
+
+- `04xy`: **Vibrato.** changes pitch to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth.
+  - Maximum vibrato depth is ±1 semitone.
+- `E3xx`: **Set vibrato direction.** `xx` may be one of the following:
+  - `00`: Up and down. default.
+  - `01`: Up only.
+  - `02`: Down only.
+- `E4xx`: **Set vibrato range** in 1/16th of a semitone. 
+
+## panning
+
+not all chips support these effects.
+
+- `08xy`: **Set panning.** changes stereo volumes independently. `x` is the left channel and `y` is the right one.
+- `88xy`: **Set rear panning.** changes rear channel volumes independently. `x` is the rear left channel and `y` is the rear right one.
+- `81xx`: **Set volume of left channel** (from `00` to `FF`).
+- `82xx`: **Set volume of right channel** (from `00` to `FF`).
+- `89xx`: **Set volume of rear left channel** (from `00` to `FF`).
+- `8Axx`: **Set volume of rear right channel** (from `00` to `FF`).
+
+- `80xx`: **Set panning (linear).** this effect behaves more like other trackers:
   - `00` is left.
   - `80` is center.
   - `FF` is right.
-  - not all chips support this effect.
-- `81xx`: set volume of left channel (from `00` to `FF`).
-  - not all chips support this effect.
-- `82xx`: set volume of right channel (from `00` to `FF`).
-  - not all chips support this effect.
-- `09xx`: set speed 1.
-- `0Axy`: volume slide.
-  - if `x` is 0 then this is a slide down.
-  - if `y` is 0 then this is a slide up.
-- `0Bxx`: jump to pattern.
-- `0Cxx`: retrigger note every `xx` ticks.
-  - this effect is not continuous.
-- `0Dxx`: jump to next pattern.
-- `0Fxx`: set speed 2.
 
-- `9xxx`: set sample position to `xxx`\*0x100.
-  - not all chips support this effect.
+## time
 
-- `Cxxx`: change song Hz.
-  - `xxx` may be from `000` to `3ff`.
+- `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.
 
-- `E0xx`: set arpeggio tick.
-  - this sets the number of ticks between arpeggio values.
-- `E1xy`: note slide up. `x` is the speed, while `y` is how many semitones to slide up.
-- `E2xy`: note slide down. `x` is the speed, while `y` is how many semitones to slide down.
-- `E3xx`: set vibrato direction. `xx` may be one of the following:
-  - `00`: up and down.
-  - `01`: up only.
-  - `02`: down only.
-- `E4xx`: set vibrato range in 1/16th of a semitone.
-- `E5xx`: set pitch. `80` is 0 cents.
-  - range is ±1 semitone.
-- `EAxx`: toggle legato.
-- `EBxx`: set sample bank.
-  - does not apply on Amiga.
-- `ECxx`: note off after `xx` ticks.
-- `EDxx`: delay note by `xx` ticks.
-- `EExx`: send external command.
-  - this effect is currently incomplete.
-- `F0xx`: change song Hz by BPM value.
-- `F1xx`: single tick slide up.
-- `F2xx`: single tick slide down.
-- `F3xx`: fine volume slide up (64x slower than `0Axy`).
-- `F4xx`: fine volume slide down (64x slower than `0Axy`).
-- `F5xx`: disable macro.
-  - see macro table at the end of this document for possible values.
-- `F6xx`: enable macro.
-- `F8xx`: single tick volume slide up.
-- `F9xx`: single tick volume slide down.
-- `FAxy`: fast volume slide (4x faster than `0Axy`).
-  - if `x` is 0 then this is a slide down.
-  - if `y` is 0 then this is a slide up.
-- `FFxx`: end of song/stop playback.
+- `Cxxx`: **Set tick rate.** changes tick rate to `xxx` Hz (ticks per second).
+  - `xxx` may be from `000` to `3FF`.
+- `F0xx`: **Set BPM.** changes tick rate according to beats per minute. range is `01` to `FF`.
 
-additionally each chip has its own effects. [click here for more details](../7-systems/README.md).
+- `0Bxx`: **Jump to order.** `x` is the order to play after the current row.
+  - this marks the end of a loop with order `x` as the loop start.
+- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order.
+  - this can be used to shorten the current order.
+- `FFxx`: **Stop song.** stops playback and ends the song. `x` is ignored.
+
+## 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".
+- `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.
+- `EBxx`: **Set sample bank.**
+  - Does not apply on Amiga.
+- `EExx`: **Send external command.**
+  - This effect is currently incomplete.
+- `F5xx`: **Disable macro.** see macro table at the end of this document for possible values.
+- `F6xx`: **Enable macro.**
+
+additionally, [each chip has its own effects](../7-systems/README.md).
 
 ## macro table
 
@@ -98,8 +119,8 @@ ID | macro
 11 | extra 6
 12 | extra 7
 13 | extra 8
----|-----------------------------
-20 | **operator 1 macros** - AM
+|   | **operator 1 macros**
+20 | AM
 21 | AR
 22 | DR
 23 | MULT
@@ -119,10 +140,9 @@ ID | macro
 31 | VIB
 32 | WS
 33 | KSR
----|-----------------------------
-40 | operator 2 macros
-60 | operator 3 macros
-80 | operator 4 macros
+40 | **operator 2 macros**
+60 | **operator 3 macros**
+80 | **operator 4 macros**
 
 the interpretation of duty, wave and extra macros depends on chip/instrument type:
 

doc/4-instrument/8930.md

@@ -2,15 +2,15 @@
 
 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
+- **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

@@ -10,26 +10,27 @@ double-click to open the instrument editor.
 
 every instrument can be renamed and have its type changed.
 
-depending on the instrument type, there are currently 13 different types of an instrument editor:
+depending on the instrument type, there are many different types of instrument editor:
 
 - [FM synthesis](fm.md) - for use with YM2612, YM2151 and FM block portion of YM2610.
 - [Standard](standard.md) - for use with NES and Sega Master System's PSG sound source and its derivatives. 
 - [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.
+- [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.
 - [TIA](tia.md) - for use with Atari 2600 chip.
 - [AY-3-8910](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610.
-- [Amiga/sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
+- [Amiga / sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
 - [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.
+- [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.
 
 
 # macros
@@ -52,9 +53,9 @@ Each macro has two buttons on the left.
 
 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.
+- ![](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.
 
 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.
 
@@ -77,14 +78,15 @@ Finally, the sequence of values can be directly edited in the text box at the bo
 
 ![ADSR macro editor](macro-ADSR.png)
 
-- **Bottom** and **Top** determine the range of values generated by the macro. (Bottom can be larger than Top to invert the envelope!) All generated values will fall between these two points.
-- **Attack** is how quickly the value goes from Bottom to Top. A 0 means nothing will change; a 255 instantly jumps to the Top value.
-- **Hold** sets how many ticks the note will wait at Top before decay.
-- **Decay** is how quickly the value moves to the Sustain level.
-- **Sustain** is the where the value will stay while the note is held until SusTime has passed.
-- **SusTime** is how many ticks until SusDecay.
-- **SusDecay** is the rate at which the value moves toward Bottom while the note is held.
-- **Release** is the rate at which the value moves toward Bottom after the note is released.
+- **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** 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.
+- **Sustain** is how far from Bottom the value stays while the note is held.
+- **SusTime** is how many ticks to stay at Sustain until SusDecay.
+- **SusDecay** is how much the value moves toward Bottom with each tick while the note is held.
+- **Release** is how much the value moves toward Bottom with each tick after the note is released.
 
 ![macro ADSR chart](macro-ADSRchart.png)
 
@@ -93,6 +95,19 @@ Finally, the sequence of values can be directly edited in the text box at the bo
 ![LFO macro editor](macro-LFO.png)
 
 - **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.
+- **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.
+
+# samples
+
+This tab appears for Generic PCM, SNES, Amiga, and other sample-based instruments.
+
+![](sample-map.png)
+
+- **Initial Sample**: the sample that the instrument will use.
+- **Use wavetable**: instead of samples, use wavetables. this causes the [Wavetables](../5-wave/README.md) tab to appear next to Sample.
+  - depending on the system and use of the wavetable synthesizer, this may or may not be reproducible on hardware.
+- **Use sample map**: assigns a sample to each note.
+  - samples will be played at their default pitch.
+  - to set a note's sample, click the list entry in the `#` column then type the number of the sample.

doc/4-instrument/amiga.md

@@ -1,17 +1,17 @@
-# Amiga/PCM sound sourceinstrument editor
+# Amiga/PCM sound source instrument editor
 
 The PCM instrument editor consists of a sample selector and several macros:
 
 # Amiga/sample
 
-- [Initial sample] - specifies which sample should be assigned to the instrument, or the first one in the sequence
+- **Initial sample**: specifies which sample should be assigned to the instrument, or the first one in the sequence
 
 # Macros
 
-- [Volume] - volume sequence WARNING: it works only on Amiga system, as of version 0.5.5!!
-- [Arpeggio] - pitch sequence
-- [Waveform] - sample sequence
-- [Panning (left)] - output level for left channel
-- [Panning (right)] - output level for right channel
-- [Pitch] - fine pitch
-- [Phase Reset] - trigger restart of waveform
+- **Volume**: volume sequence. _warning:_ it works only on Amiga system, as of version 0.5.5!
+- **Arpeggio**: pitch sequence
+- **Waveform**: sample sequence
+- **Panning (left)**: output level for left channel
+- **Panning (right)**: output level for right channel
+- **Pitch**: fine pitch
+- **Phase Reset**: trigger restart of waveform

doc/4-instrument/ay8910.md

@@ -2,12 +2,12 @@
 
 The AY-3-8910 instrument editor consists of these macros.
 
-- [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
+- **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

doc/4-instrument/c64.md

@@ -4,32 +4,32 @@ The C64 instrument editor consists of two tabs: "C64" to control various paramet
 
 ## 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
-- [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.)
+- **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
+- **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.)
 
 ## 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 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.

doc/4-instrument/fm.md

@@ -2,47 +2,46 @@
 
 FM editor is divided into 7 tabs:
 
-- [FM] - for controlling the basic parameters of FM sound source.
-- [Macros (FM)]- for macros controlling algorithm, feedback and LFO 
-- [Macros (OP1)] - for macros controlling FM paramets of operator 1
-- [Macros (OP2)] - for macros controlling FM paramets of operator 2
-- [Macros (OP3)] - for macros controlling FM paramets of operator 3
-- [Macros (OP4)] - for macros controlling FM paramets of operator 4
-- [Macros] - for miscellaneous macros controlling volume, argeggio and YM2151 noise generator.
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, feedback and LFO 
+- **Macros (OP1)**: for macros controlling FM paramets of operator 1
+- **Macros (OP2)**: for macros controlling FM paramets of operator 2
+- **Macros (OP3)**: for macros controlling FM paramets of operator 3
+- **Macros (OP4)**: for macros controlling FM paramets of operator 4
+- **Macros**: for miscellaneous macros controlling volume, argeggio and YM2151 noise generator.
 
 ## FM
 
 FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen sliders:
 
-- [Attack Rate (AR)] - determines the rising time for the sound. The bigger the value, the faster the attack. (0-31 range)
-- [Decay Rate (DR)]- Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-31 range)
-- [Secondary Decay Rate (DR2)/Sustain Rate (SR)] - Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-31 range)
-- [Release Rate (RR)] - Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
-- [Sustain Level(SL)] - Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
-- [Total Level (TL)] - Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
-- [Envelope Scale (KSR)] - A parameter that determines the degree to which the envelope execution speed increases according to the pitch. (0-3 range)
-- [Frequency Multiplier (MULT)] - Determines the operator frequency in relation to the pitch. (0-15 range)
-- [Fine Detune (DT)] - Shifts the pitch a little (0-7 range)
-- [Coarse Detune (DT2)] - Shifts the pitch by tens of cents (0-3 range) WARNING: this parameter affects only YM2151 sound source!!!
-- [Hardware Envelope Generator (SSG-EG)] - Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate. WARNING: this parameter affects only YM2610/YM2612 sound source!!!
-- [Algorithm (AL)] - Determines how operators are connected to each other. (0-7 range)
-- [Feedback (FB)] - Determines the amount of signal whick operator 1 returns to itself. (0-7 range)
-- [Amplitude Modulation (AM)] - Makes the operator affected by LFO.
-- [LFO Frequency Sensitivity] - Determines the amount of LFO frequency changes. (0-7 range)
-- [LFO Amplitude Sensitivity (AM)] - Determines the amount of LFO frequency changes. (0-3 range)
+- **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-31 range)
+- **Decay Rate (DR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-31 range)
+- **Secondary Decay Rate (DR2)/Sustain Rate (SR)**: Determines the diminishing time for the sound. The higher the value, the shorter the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-31 range)
+- **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
+- **Sustain Level(SL)**: Determines the point at which the sound ceases to decay and changes to a sound having a constant level. The sustain level is expressed as a fraction of the maximum level. (0-15 range)
+- **Total Level (TL)**: Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
+- **Envelope Scale (KSR)**: A parameter that determines the degree to which the envelope execution speed increases according to the pitch. (0-3 range)
+- **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-15 range)
+- **Fine Detune (DT)**: Shifts the pitch a little (0-7 range)
+- **Coarse Detune (DT2)**: Shifts the pitch by tens of cents (0-3 range) WARNING: this parameter affects only YM2151 sound source!!!
+- **Hardware Envelope Generator (SSG-EG)**: Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate. WARNING: this parameter affects only YM2610/YM2612 sound source!!!
+- **Algorithm (AL)**: Determines how operators are connected to each other. (0-7 range)
+- **Feedback (FB)**: Determines the amount of signal whick operator 1 returns to itself. (0-7 range)
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO.
+- **LFO Frequency Sensitivity**: Determines the amount of LFO frequency changes. (0-7 range)
+- **LFO Amplitude Sensitivity (AM)**: Determines the amount of LFO frequency changes. (0-3 range)
 
 ## Macros
 
 Macros define the sequence of values passed to the given parameter. Via macro, aside previously mentioned parameters, the following can be controlled:
 
-- LFO Frequency
-- LFO waveform selection WARNING: this parameter affects only YM2151 sound source!!!
-- Amplitude Modulation Depth WARNING: this parameter affects only YM2151 sound source!!!
-- Frequency Modulation Depth WARNING: this parameter affects only YM2151 sound source!!!
-- Arpeggio Macro: pitch change sequence in semitones. Two modes are available:  
-Absolute (default) - Executes the pitch with absolute change based on the pitch of the actual note.
-Fixed - Executes at the pitch specified in the sequence regardless of the note pitch.
-- Noise Frequency: specifies the noise frequency in noise mode of YM2151's Channel 8 Operator 4 special mode.
+- **LFO Frequency**
+- **LFO Waveform**: _WARNING:_ this parameter affects only YM2151 sound source!
+- **Amplitude Modulation Depth**: _WARNING:_ this parameter affects only YM2151 sound source!
+- **Frequency Modulation Depth**: _WARNING:_ this parameter affects only YM2151 sound source!
+- **Arpeggio Macro**: Pitch change sequence in semitones. Two modes are available:  
+  - **Absolute** (default): Executes the pitch with absolute change based on the pitch of the actual note.
+  - **Fixed**: Executes at the pitch specified in the sequence regardless of the note pitch.
+- **Noise Frequency**: specifies the noise frequency in noise mode of YM2151's Channel 8 Operator 4 special mode.
 
-Loop
-You can loop the execution of part of a sequence. Left-click anywhere on the Loop line at the bottom of the editor to create a loop. You can move the start and end points of the loop by dragging both ends of the loop.
+Looping: You can loop the execution of part of a sequence. Left-click anywhere on the Loop line at the bottom of the editor to create a loop. You can move the start and end points of the loop by dragging both ends of the loop. Rigkt-click to remove the loop.

doc/4-instrument/game-boy.md

@@ -4,22 +4,22 @@ GB instrument editor consists of two tabs: one controlling envelope of sound cha
 
 ## 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
+- **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
 
-- [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!
+- **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!
 
-- [Hardware Sequence] - (document this)
+- **Hardware Sequence**: (document this)
 
 ## 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 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

doc/4-instrument/lynx.md

@@ -2,13 +2,13 @@
 
 Atari Lynx instrument editor consists of these 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
+- **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
 
 ## Audio generation description
 

doc/4-instrument/n163.md

@@ -4,27 +4,27 @@ The Namco 163 instrument editor consists of two tabs: "Namco 163" for control of
 
 ## Namco 163
 
-- [Waveform] - Determines the initial waveform for playing.
-- [Offset] - Determines the initial waveform position will be load to RAM.
-- [Length] - Determines the initial waveform length will be load to RAM.
-- [Load waveform before playback] - Determines the load initial waveform into RAM before playback.
-- [Update waveforms into RAM when every waveform changes] - Determines the update every different waveform changes in playback.
+- **Waveform**: Determines the initial waveform for playing.
+- **Offset**: Determines the initial waveform position will be load to RAM.
+- **Length**: Determines the initial waveform length will be load to RAM.
+- **Load waveform before playback**: Determines the load initial waveform into RAM before playback.
+- **Update waveforms into RAM when every waveform changes**: Determines the update every different waveform changes in playback.
 
 
 ## Macros
 
-- [Volume] - volume levels sequence
-- [Arpeggio]- pitch sequence
-- [Waveform] - sets waveform source for playback immediately or update later
-- [Panning] - output for left and right channels
-- [Pitch] - fine pitch
-- [Phase Reset] - trigger restart of waveform
+- **Volume**: volume levels sequence
+- **Arpeggio**: pitch sequence
+- **Waveform**: sets waveform source for playback immediately or update later
+- **Panning**: output for left and right channels
+- **Pitch**: fine pitch
+- **Phase Reset**: trigger restart of waveform
 <!--
-- [Waveform pos.] - sets the waveform source address in RAM for playback (single nibble unit)
-- [Waveform len.] - sets the waveform source length for playback (4 nibble unit)
-- [Waveform update] - sets the waveform update trigger behavior for playback
-- [Waveform to load] - sets waveform source for load to RAM immediately or later
-- [Wave pos. to load] - sets address of waveform for load to RAM (single nibble unit)
-- [Wave len. to load] - sets length of waveform for load to RAM (4 nibble unit)
-- [Waveform load] - sets the waveform load trigger behavior
+- **Waveform pos.**: sets the waveform source address in RAM for playback (single nibble unit)
+- **Waveform len.**: sets the waveform source length for playback (4 nibble unit)
+- **Waveform update**: sets the waveform update trigger behavior for playback
+- **Waveform to load**: sets waveform source for load to RAM immediately or later
+- **Wave pos. to load**: sets address of waveform for load to RAM (single nibble unit)
+- **Wave len. to load**: sets length of waveform for load to RAM (4 nibble unit)
+- **Waveform load**: sets the waveform load trigger behavior
 -->

doc/4-instrument/pce.md

@@ -2,13 +2,13 @@
 
 The PCE instrument editor consists of these 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
+- **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
 
 It also has wavetable synthesizer support, but unfortunately, it clicks a lot when in use on the HuC6280.

doc/4-instrument/pv1000.md

@@ -0,0 +1,7 @@
+# PV-1000 instrument editor
+
+The instrument editor for the Casio PV-1000 consists of these macros:
+
+- **Volume**: volume
+- **Arpeggio**: pitch in half-steps
+- **Pitch**: fine pitch

doc/4-instrument/saa.md

@@ -2,11 +2,11 @@
 
 The SAA1099 instrument editor consists of these macros:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequence
-- [Duty/Noise] - noise generator frequency
-- [Waveform] - selector between tone and noise
-- [Panning (left)] - output level for left channel
-- [Panning (right)] - output level for right channel
-- [Pitch] - fine pitch
-- [Envelope] - envelope generator shape
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequence
+- **Duty/Noise**: noise generator frequency
+- **Waveform**: selector between tone and noise
+- **Panning (left)**: output level for left channel
+- **Panning (right)**: output level for right channel
+- **Pitch**: fine pitch
+- **Envelope**: envelope generator shape

doc/4-instrument/scc.md

@@ -2,7 +2,7 @@
 
 The SCC/Bubble System WSG instrument editor consists of these macros:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequence
-- [Waveform] - spicifies wavetables sequence
-- [Pitch] - fine pitch
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequence
+- **Waveform**: spicifies wavetables sequence
+- **Pitch**: fine pitch

doc/4-instrument/snes.md

@@ -0,0 +1,46 @@
+# SNES instrument editor
+
+these tabs are unique to the editor for SNES instruments.
+
+
+
+# SNES
+
+**Use envelope** enables the ADSR volume envelope. if it's on:
+
+- **A**: attack rate.
+- **D**: decay rate.
+- **S**: sustain level.
+- **D2**: decay rate during sustain.
+- **R**: release rate.
+- **Sustain/release mode**:
+  - **Direct**: note release acts as note cut.
+  - **Effective (linear decrease)**: after release, volume lowers by subtractions of 1/64 steps.
+  - **Effective (exponential decrease)**: after release, volume decays exponentially. see [gain chart](../7-systems/snes.md).
+  - **Delayed (write R on release)**: after release, waits until A and D have completed before starting exponential decrease.
+
+if envelope is off, select gain mode as described below.
+
+
+
+# Macros
+
+- **Volume**: volume.
+- **Arpeggio**: pitch in half-steps.
+- **Noise Freq**: preset frequency of noise generator.
+- **Waveform**: waveform.
+- **Panning (left)**: output level of left channel.
+- **Panning (right)**: output level of right channel.
+- **Pitch**: fine pitch.
+- **Special**: bitmap of flags.
+  - invert left: inverts output of left channel.
+  - invert right: inverts output of right channel.
+  - pitch mod: modulates pitch using previous channel's output.
+  - echo: enables echo.
+  - noise: enables noise generator.
+- **Gain**: sets mode and value of gain.
+  - 0 - 127: direct gain from 0 to 127
+  - 128 - 159: linear gain from -0 to -31
+  - 160 - 191: exponential gain from -0 to -31
+  - 192 - 223: linear gain from +0 to +31
+  - 224 - 255: exponential gain from +0 to +31

doc/4-instrument/standard.md

@@ -2,9 +2,9 @@
 
 The instrument editor for NES and PSG (SMS, MSX, and such) consists of these macros:
 
-- [Volume] - volume
-- [Arpeggio] - pitch in half-steps
-- [Duty] - duty cycle and noise mode for NES channels. _Note:_ This has no effect on Sega Master System.
-- [Panning] - output for left and right channels
-- [Pitch] - fine pitch
-- [Phase Reset] - trigger restart of waveform
+- **Volume**: volume
+- **Arpeggio**: pitch in half-steps
+- **Duty**: duty cycle and noise mode for NES channels. _Note:_ This has no effect on Sega Master System.
+- **Panning**: output for left and right channels
+- **Pitch**: fine pitch
+- **Phase Reset**: trigger restart of waveform

doc/4-instrument/tia.md

@@ -2,7 +2,7 @@
 
 The TIA instrument editor consists of these macros:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequencr
-- [Waveform] - 1-bit polynomial pattern type sequence
-- [Pitch] - "fine" pitch
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequencr
+- **Waveform**: 1-bit polynomial pattern type sequence
+- **Pitch**: "fine" pitch

doc/4-instrument/vera.md

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

doc/4-instrument/vrc6.md

@@ -2,10 +2,10 @@
 
 The VRC6 (regular) instrument editor consists of these macros:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequence
-- [Duty] - specifies duty cycle for pulse wave channels
-- [Pitch] - fine pitch
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequence
+- **Duty**: specifies duty cycle for pulse wave channels
+- **Pitch**: fine pitch
 
 ## VRC6 (saw) instrument editor
 

doc/4-instrument/wonderswan.md

@@ -2,7 +2,7 @@
 
 WS instrument editor consists of only four macros, similar to PCE but with different volume and noise range:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequencr
-- [Noise] - noise LFSR tap sequence
-- [Waveform] - spicifies wavetables sequence
+- **Volume**: volume sequence
+- **Arpeggio**: pitch sequencr
+- **Noise**: noise LFSR tap sequence
+- **Waveform**: spicifies wavetables sequence