Merge branch 'master' of https://github.com/tildearrow/furnace into nmk112

.github/workflows/build.yml

@@ -2,7 +2,7 @@ name: Build furnace
 
 on:
   push:
-    branches: master
+    branches: [master, esfm-contest]
   pull_request:
     branches: master
 

CMakeLists.txt

@@ -492,6 +492,8 @@ extern/opl/opl3.c
 extern/YM3812-LLE/fmopl2.c
 extern/YMF262-LLE/fmopl3.c
 extern/YMF276-LLE/fmopn2.c
+extern/ESFMu/esfm.c
+extern/ESFMu/esfm_registers.c
 
 src/pch.cpp
 
@@ -700,6 +702,7 @@ src/engine/platform/pv1000.cpp
 src/engine/platform/k053260.cpp
 src/engine/platform/ted.cpp
 src/engine/platform/c140.cpp
+src/engine/platform/esfm.cpp
 src/engine/platform/pcmdac.cpp
 src/engine/platform/dummy.cpp
 
@@ -779,6 +782,7 @@ src/gui/doAction.cpp
 src/gui/editing.cpp
 src/gui/editControls.cpp
 src/gui/effectList.cpp
+src/gui/exportOptions.cpp
 src/gui/findReplace.cpp
 src/gui/fmPreview.cpp
 src/gui/gradient.cpp

README.md

@@ -80,7 +80,8 @@ for other operating systems, you may [build the source](#developer-info).
   - Casio PV-1000
   - TIA used in Atari 2600
   - POKEY used in Atari 8-bit computers
-  - Game Boy
+  - **Game Boy**
+    - including SOFTWARE ENVELOPES (zombie mode)
   - Virtual Boy
   - modern/fantasy:
     - Commander X16 VERA
@@ -360,7 +361,7 @@ you should only save as .dmf if you're really sure, because the DefleMask format
 ---
 # footnotes
 
-copyright (C) 2021-2023 tildearrow and contributors.
+copyright (C) 2021-2024 tildearrow and contributors.
 
 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
 

TODO.md

@@ -1,15 +1,12 @@
 # to-do
 
-- add cheat code to insert bruno time (blank)
-
-# THE REAL TO-DO LIST
-
+- finish color import improvements (settings refactor)
+- new undo stuff
+- fix some bugs
 - finish auto-clone
 
 once you have done all of this (maybe not the first one), 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

doc/2-interface/settings.md

@@ -123,22 +123,21 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **Note input**: enables note input. disable if you intend to use this device only for binding actions.
 - **Velocity input**: enables velocity input when entering notes in the pattern.
 - **Map MIDI channels to direct channels**: when enabled, notes from MIDI channels will be mapped to channels rather than the cursor position.
+- **Program change pass-through**: when enabled, program change events are sent to each channel as instrument change commands.
+  - this option is only available when the previous one is enabled.
 - **Map Yamaha FM voice data to instruments**: when enabled, Furnace will listen for any transmitted Yamaha SysEx patches.
   - this option is only useful if you have a Yamaha FM synthesizer (e.g. TX81Z).
   - selecting a voice or using the "Voice Transmit?" option will send a patch, and Furnace will create a new instrument with its data.
   - this may also be triggered by clicking on "Receive from TX81Z" in the instrument editor (OPZ only).
 - **Program change is instrument selection**: changes the current instrument when a program change event is received.
+  - this option is not available when "Program change pass-through" is enabled.
 - **Value input style**: changes the way values are entered when the pattern cursor is not in the Note column. the following styles are available:
   - **Disabled/custom**: no value input through MIDI.
   - **Two octaves (0 is C-4, F is D#5)**: maps keys in two octaves to single nibble input. the layout is:
-    - ` - octave n -- octave n+1 -`
-    - ` 1 3   6 8 A   D F   # # # `
-    - `0 2 4 5 7 9 B C E # # # # #`
+    ![two octaves layout 1](MIDI-value-input-1.png)
   - **Raw (note number is value)**: the note number becomes the input value. not useful if you want to input anything above 7F.
   - **Two octaves alternate (lower keys are 0-9, upper keys are A-F)**: maps keys in two octaves, but with a different layout:
-    - ` - octave n -- octave n+1 -`
-    - ` A B   C D E   F #   # # # `
-    - `0 1 2 3 4 5 6 7 8 9 # # # #`
+    ![two octaves layout 2](MIDI-value-input-2.png)
   - **Use dual control change (one for each nibble)**: maps two control change events to the nibbles of a value.
     - **CC of upper nibble**: select the CC number that will change the upper nibble.
     - **CC of lower nibble**: select the CC number that will change the lower nibble.
@@ -149,6 +148,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
     - **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.
 - **Volume curve**: adjust the velocity to volume curve.
+  - the default is 2.0, which matches General MIDI standard.
 - **Actions**: this allows you to bind note input and control change events to actions.
   - **`+`** button: adds a new action.
   - window-with-arrow button: new action with learning! press a button or move a slider/knob/something on your device.
@@ -498,7 +498,7 @@ below all the binds, select a key from the dropdown list to add it. it will appe
 - **Rounded window corners**
 - **Rounded buttons**
 - **Rounded menu corners**
-- **Borders around widgets**: draws thin borders on buttons, checkboxes, text widgets, and the like.
+- **Borders around widgets**: draws borders on buttons, checkboxes, text widgets, and the like.
 
 
 
@@ -509,6 +509,7 @@ below all the binds, select a key from the dropdown list to add it. it will appe
 - **Import**
 - **Export**
 - **Reset defaults**
+- **Guru mode**: exposes all color options (instead of accent colors).
 - **General**
   - **Color scheme type:**
     - **Dark**

doc/3-pattern/effects.md

@@ -93,6 +93,7 @@ not all chips support these effects.
   - this effect is currently incomplete.
 - `F5xx`: **Disable macro.**
 - `F6xx`: **Enable macro.**
+- `F7xx`: **Restart macro.**
   - see macro table at the end of this document for possible values.
 
 additionally, [each chip has its own effects](../7-systems/README.md).

doc/4-instrument/README.md

@@ -1,186 +1,222 @@
-# instrument editor
-
-the instrument editor always starts with this section:
-
-![top of instrument editor](instrument-editor-top.png)
-
-- top-left numeric dropdown: instrument selector.
-- folder icon: open an instrument file.
-- save icon: save current instrument as a file.
-  - right-clicking gives the option to save a .dmp format DefleMask preset.
-- **Name**: instrument name.
-- **Type**: the system for which the instrument is intended.
-  - if changed, all applicable settings and macros will remain as they are. numbers will not be adjusted.
-
-## instrument types
-
-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.
-- [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.
-- [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.
-- [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 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.
-
-![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.
-
-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:
-
-- ![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.
-
-### sequence
-
-![sequence macro editor](macro-seq.png)
-
-![clipped sequence macro editor](macro-seq-clip.png)
-
-![bitmask sequence macro editor](macro-seq-bitmask.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 values of the macro can be drawn in the "bar graph" box.
-- arpeggio and pitch macros may have values above or below the visible area; small chevrons will be shown until they are scrolled into view.
-- bitmask-style macros show labels for each of their bits, and these are edited as toggles.
-
-arpeggio macros have a short bar for setting whether to interpret the values as being "relative" or "fixed".
-- by default, values are offsets **relative** to the note.
-- if clicked on, a value becomes **fixed** and will be played at its corresponding note without regard to the note entered into the pattern.
-  - values are counted from `C-0`. for example, a fixed value of 48 produces a `C-4` note.
-  - fixed values are especially useful for noise instruments with preset periods.
-
-below this is a short bar that controls macro loop and release.
-- 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 a fixed value as described above.
-- in bitmask-style macros, the values are added up in binary and converted to decimal. see [the hexadecimal guide](../1-intro/hex.md) for more info.
-
-in all cases except bitmask macros, right-clicking on the graph opens up an editing menu:
-- **copy**: copies the macro.
-- **paste**: pastes the macro in the clipboard.
-- **clear**: clears the macro.
-- **clear contents**: resets all values to 0.
-- **offset**:
-  - **X**: slides the data "horizontally" within the macro, filling the gap with zeroes. data moved past the start or end is lost.
-  - **Y**: increases or decreases all values, clipping them if they would move past the allowed range.
-- **scale**:
-  - **X**: stretches the macro.
-  - **Y**: multiplies all values by the scale factor, clipping them if they would exceed the allowed range.
-- **randomize**: replaces all values with random values between **Min** and **Max**.
-
-### 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** 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)
-
-### LFO
-
-![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.
-- **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.
-
-
-
-## wavetable
-
-this tab appears for PC Engine, FDS, Namco WSG, and other wavetable-based instruments.
-
-![wavetable tab](wavetable.png)
-
-when **Enable synthesizer** is off, the wavetable used for the instrument may be selected by creating a Waveform macro with a single value.
-
-to use the wavetable synthesizer, refer to [the wavetable synthesizer section](wavesynth.md).
-
-
-## sample
-
-this tab appears for Generic PCM DAC, Amiga and SNES.
-
-![sample tab](sample-map.png)
-
-see the [Generic Sample section](sample.md) for more information.
+# instrument editor
+
+the instrument editor allows you to edit instruments.
+it can be activated by double-clicking on an instrument in the instrument list.
+
+alternatively, window > instrument editor displays it.
+
+## main
+
+![top of instrument editor](instrument-editor-top.png)
+
+**TODO: add descriptions to buttons in the image. it really needs them.**
+
+- **Instrument Selector**: displays a list of instruments in the song.
+- **Open**: open an instrument file.
+- **Save**: save current instrument to a file.
+  - right-click to see additional options, such as saving in DefleMask preset format (.dmp).
+- **Name**: changes the instrument name.
+- **Type**: changes the instrument type (usually chip-specific).
+  - if changed, all applicable settings and macros will remain unchanged.
+  - you may have to adjust them afterwards.
+
+## instrument types
+
+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.
+- [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.
+- [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).
+- [FM (ESFM)](fm-esfm.md) - for use with ESFM.
+- [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.
+- [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 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.
+
+![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 is a matching scrollbar at the bottom underneath all the macros.
+
+each macro has the following parameters:
+- macro type (explained below)
+- timing options:
+  - **Step Length (ticks)**: determines the number of ticks between macro steps. default is 1.
+  - **Delay**: delays the macro until this many ticks have elapsed. default is 0.
+  - the button is highlighted if either of these parameters is set to non-default values.
+- release mode: determines how macro release (`===` or `REL` in the pattern) is handled:
+  - **Active**: jumps to release position on release.
+  - **Passive**: does not jump to release position. this will result in delay if release position has not been reached yet.
+
+## macro types
+
+there are three macro types:
+
+- ![sequence](macro-button-seq.png) **Sequence:** a sequence of numeric values.
+- ![ADSR](macro-button-ADSR.png) **ADSR:** this is an attack/decay/sustain/release envelope.
+- ![LFO](macro-button-LFO.png) **LFO:** Low Frequency Oscillator.
+
+### sequence
+
+this is the most basic macro type. when the instrument is played, every value in the macro will be output sequentially, from left to right.
+
+![sequence macro editor](macro-seq.png)
+
+![clipped sequence macro editor](macro-seq-clip.png)
+
+![bitmask sequence macro editor](macro-seq-bitmask.png)
+
+**TODO: once again, text in the image. this sucks.**
+
+the Length field allows you to set the number of steps in the sequence.
+
+the sequence view allows you to edit the macro.
+- press and hold the left mouse button to start drawing. release to stop drawing.
+- press and hold the right mouse button to draw a line.
+  - the start point will be set to the cursor position.
+  - move the cursor to change the end point.
+  - release to finish drawing the line.
+
+the sequence view may be adjusted using the following combinations:
+- hold Ctrl and use the scroll wheel to zoom horizontally.
+- hold Ctrl-Shift and use the scroll wheel to zoom vertically.
+- the scrollbar at the right allows you to scroll vertically (if possible).
+- you may hold Shift and use the scroll wheel to scroll vertically as well.
+
+right-click on the sequence view to open a menu:
+- **copy**: copy this macro to clipboard.
+- **paste**: pastes the macro.
+- **clear**: clears the macro.
+- **clear contents**: resets all values to 0.
+- **offset**:
+  - **X**: slides the data "horizontally" within the macro, filling the gap with zeroes. data moved past the start or end is lost.
+  - **Y**: increases or decreases all values, clipping them if they would move past the allowed range.
+- **scale**:
+  - **X**: stretches the macro.
+  - **Y**: multiplies all values by the scale factor, clipping them if they would exceed the allowed range.
+- **randomize**: replaces all values with random values between **Min** and **Max**.
+
+arpeggio and pitch macros may have values above or below the visible area. indicators will be shown until they are scrolled into view.
+
+bitmask-style macros show labels for each of their bits. these are edited as toggles.
+- drawing lines is not possible in these macros.
+
+under the sequence view there is a bar that allows you to set loop and release points.
+- click to set the loop start point; the end point is the last step or release point.
+  - right-click to remove the loop point.
+- shift-click to set the release point.
+  - the macro will stop at the release point until the note is released (`===` or `REL`).
+    - if the loop point is set, and it is placed before the release point, the macro will loop until note release instead.
+  - shift-right-click to remove the release point.
+
+arpeggio macros have an additional bar under the sequence view to set steps to "relative" or "fixed":
+- by default, step values are offsets **relative** to the note.
+- if clicked on, a step value becomes **fixed** and will be played at its corresponding note without regard to the currently playing note.
+  - values are counted from `C-0`. for example, a fixed value of 48 produces a `C-4` note.
+  - fixed values are especially useful for noise or percussion.
+
+the sequence can be edited in the text input field at the very bottom. the following symbols have special meanings:
+- `|`: loop point.
+- `/`: release point.
+- in arpeggio macros, `@` prefixed to a value indicates that it is a fixed value as described above.
+
+in bitmask-style macros, the values are added up in binary and converted to decimal.
+
+### ADSR
+
+![ADSR macro editor](macro-ADSR.png)
+
+- **Bottom** and **Top** determine the macro's output range (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.
+  - the output starts at Bottom.
+  - **Attack** is how much the output moves toward Top with each tick.
+  - **Hold** sets how many ticks to stay at Top before Decay.
+  - **Decay** is how much the output moves to the Sustain level.
+  - **Sustain** is how far from Bottom the value stays while the note is on.
+  - **SusTime** is how many ticks to stay at Sustain until SusDecay.
+  - **SusDecay** is how much the output moves toward Bottom with each tick while the note is on.
+  - **Release** is how much the output moves toward Bottom with each tick after the note is released.
+
+![macro ADSR chart](macro-ADSRchart.png)
+
+### LFO
+
+![LFO macro editor](macro-LFO.png)
+
+- **Bottom** and **Top** determine the macro's output range (Bottom can be larger than Top to invert the waveform!).
+- **Speed** is how quickly the LFO position moves.
+- **Phase** defines the starting LFO position, measured in 1/1024 increments.
+- **Shape** is the waveform of the LFO. there are three waveforms:
+  - Triangle: Bottom > Top > Bottom.
+  - Saw: moves from Bottom to Top, and then jumps back to Bottom.
+  - Square: alternates between Bottom and Top.
+
+
+
+## wavetable
+
+this tab appears for PC Engine, FDS, Namco WSG, and other wavetable-based instruments.
+
+![wavetable tab](wavetable.png)
+
+when **Enable synthesizer** is off, the wavetable used for the instrument may be selected by creating a Waveform macro with a single value.
+
+to use the wavetable synthesizer, refer to [the wavetable synthesizer section](wavesynth.md).
+
+
+## sample
+
+this tab appears for Generic PCM DAC, Amiga and SNES.
+
+![sample tab](sample-map.png)
+
+see the [Generic Sample section](sample.md) for more information.

doc/4-instrument/beeper.md

@@ -1,9 +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.
+# 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/fm-esfm.md

@@ -0,0 +1,77 @@
+# ESFM instrument editor
+
+the ESFM editor is divided into 6 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **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/pan/noise mode).
+
+## FM
+
+ESFM is four-operator, but it is different from the rest of FM chips.
+
+the concept of an algorithm does not exist in ESFM. instead, modulation routing is arbitrary, with each operator having output level and modulation input parameters.
+
+these apply to the instrument as a whole:
+- **OP4 Noise Mode**: determines the mode used to produce noise in operator 4.
+  - Normal: noise is disabled.
+  - Snare: takes the snare noise generation mode from OPL. square + noise.
+  - HiHat: ring modulates with operator 3 and adds noise.
+  - Top: ring modulates with operator 3 and double pitch modulation input.
+    - this mode is not emulated correctly. subject to change!
+
+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.
+- **AM Depth (AMD)**: when enabled, LFO tremolo is deeper.
+- **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.
+- **Output Level (OL)**: determines the volume at which the operator will be output.
+- **Modulation Input (MI)**: determines how much to take from the previous operator for modulation.
+  - this controls feedback level in the case of operator 1.
+- **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 (0 to 7).
+- **Vibrato (VIB)**: makes the operator affected by LFO vibrato.
+- **FM Depth (FMD)**: when enabled, vibrato is deeper.
+
+- **Tune**: sets the coarse tune of the operator.
+- **Detune**: sets the fine tune of the operator.
+
+- **Left (L)**: output on the left channel.
+- **Right (R)**: output on the right channel.
+
+### 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.
+
+## OP1-OP4 Macros
+
+all parameters are listed above.
+
+## Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **OP4 Noise Mode**: noise mode sequence.
+- **Panning**: enables output on left/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.

doc/4-instrument/msm5232.md

@@ -1,16 +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.
+# 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/nes.md

@@ -1,52 +1,52 @@
-# NES instrument editor
-
-the NES instrument editor consists of two tabs.
-
-## 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
-- **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+# NES instrument editor
+
+the NES instrument editor consists of two tabs.
+
+## 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
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/pokemini.md

@@ -1,8 +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.
+# 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.

doc/4-instrument/pokey.md

@@ -1,25 +1,25 @@
-# Atari POKEY instrument editor
-
-the instrument editor for POKEY consists of these macros:
-
-- **Volume**: volume sequence.
-- **Arpeggio**: pitch sequence.
-- **AUDCTL**: audio control register sequence:
-  - **poly9**: reduces size of LFSR. only on noise waveforms!
-  - **high1**: runs channel 1 at 1.79MHz.
-  - **high3**: runs channel 3 at 1.79MHz.
-  - **16-bit 1+2**: enables 16-bit frequency mode by combining channels 1 and 2.
-  - **16-bit 3+4**: enables 16-bit frequency mode by combining channels 3 and 4.
-  - **filter 1+3**: applies a high-pass "filter" by combining channels 1 and 3.
-  - **filter 2+4**: applies a high-pass "filter" by combining channels 2 and 4.
-  - **15KHz**: runs channels at 15KHz.
-- **Waveform**: wave selection sequence:
-  - 0: harsh noise (poly5+17)
-  - 1: square buzz (poly5)
-  - 2: weird noise (poly4+5)
-  - 3: square buzz (poly5)
-  - 4: soft noise (poly17)
-  - 5: square
-  - 6: bass (poly4)
-  - 7: buzz (poly4)
-- **Pitch**: fine pitch.
+# Atari POKEY instrument editor
+
+the instrument editor for POKEY consists of these macros:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **AUDCTL**: audio control register sequence:
+  - **poly9**: reduces size of LFSR. only on noise waveforms!
+  - **high1**: runs channel 1 at 1.79MHz.
+  - **high3**: runs channel 3 at 1.79MHz.
+  - **16-bit 1+2**: enables 16-bit frequency mode by combining channels 1 and 2.
+  - **16-bit 3+4**: enables 16-bit frequency mode by combining channels 3 and 4.
+  - **filter 1+3**: applies a high-pass "filter" by combining channels 1 and 3.
+  - **filter 2+4**: applies a high-pass "filter" by combining channels 2 and 4.
+  - **15KHz**: runs channels at 15KHz.
+- **Waveform**: wave selection sequence:
+  - 0: harsh noise (poly5+17)
+  - 1: square buzz (poly5)
+  - 2: weird noise (poly4+5)
+  - 3: square buzz (poly5)
+  - 4: soft noise (poly17)
+  - 5: square
+  - 6: bass (poly4)
+  - 7: buzz (poly4)
+- **Pitch**: fine pitch.

doc/4-instrument/psg.md

@@ -1,15 +1,15 @@
-# Sega PSG instrument editor
-
-the instrument editor for Sega PSG (SMS, and other TI SN76489 derivatives) consists of these macros:
-
-- **Volume**: volume sequence.
-- **Arpeggio**: pitch sequence.
-- **Duty**: noise mode.
-  - `0`: short noise; preset frequencies.
-  - `1`: long noise; preset frequencies.
-  - `2`: short noise; use channel 3 for frequency.
-  - `3`: long noise; use channel 3 for frequency.
-- **Panning**: output for left and right channels.
-  - only on Game Gear!
-- **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+# Sega PSG instrument editor
+
+the instrument editor for Sega PSG (SMS, and other TI SN76489 derivatives) consists of these macros:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Duty**: noise mode.
+  - `0`: short noise; preset frequencies.
+  - `1`: long noise; preset frequencies.
+  - `2`: short noise; use channel 3 for frequency.
+  - `3`: long noise; use channel 3 for frequency.
+- **Panning**: output for left and right channels.
+  - only on Game Gear!
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/t6w28.md

@@ -1,13 +1,13 @@
-# T6W28 instrument editor
-
-the instrument editor for T6W28 consists of these macros:
-
-- **Volume**: volume sequence.
-- **Arpeggio**: pitch sequence.
-- **Noise Type**: noise type sequence:
-  - `0`: short noise
-  - `1`: long noise
-- **Panning (left)**: output level for left channel.
-- **Panning (right)**: output level for right channel.
-- **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform.
+# T6W28 instrument editor
+
+the instrument editor for T6W28 consists of these macros:
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Noise Type**: noise type sequence:
+  - `0`: short noise
+  - `1`: long noise
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of waveform.

doc/7-systems/README.md

@@ -108,8 +108,9 @@ this is the full list of chips that Furnace supports.
 - [VRC6](vrc6.md)
 - [WonderSwan](wonderswan.md)
 - [X1-010](x1-010.md)
-- [VRC7, Y8950, YM3526, YM3812 and YMF262 (OPL)](opl.md)
-- [YM2413 (OPLL)](opll.md)
+- [Y8950, YM3526, YM3812 and YMF262 (OPL)](opl.md)
+- [ESFM](esfm.md)
+- [VRC7 and YM2413 (OPLL)](opll.md)
 - [YM2414 (OPZ)](opz.md)
 - [YM2151 (OPM)](ym2151.md)
 - [YM2203 (OPN)](ym2203.md)

doc/7-systems/dac.md

@@ -1,13 +1,13 @@
-# Generic PCM DAC
-
-a sample channel, with freely selectable rate, mono/stereo and bit depth settings.
-
-with it, you can emulate PCM DACs found in Williams arcade boards, Sound Blasters, MSX TurboR, Atari STe, NEC PC-9801-86, among others.
-
-## effects
-
-none yet.
-
-## info
-
-this chip uses the [Generic Sample](../4-instrument/sample.md) instrument editor.
+# Generic PCM DAC
+
+a sample channel, with freely selectable rate, mono/stereo and bit depth settings.
+
+with it, you can emulate PCM DACs found in Williams arcade boards, Sound Blasters, MSX TurboR, Atari STe, NEC PC-9801-86, among others.
+
+## effects
+
+none yet.
+
+## info
+
+this chip uses the [Generic Sample](../4-instrument/sample.md) instrument editor.

doc/7-systems/es5506.md

@@ -1,46 +1,46 @@
-# Ensoniq ES5506 (OTTO)
-
-sample-based synthesis chip used in a bunch of Taito arcade machines and PC sound cards like Soundscape Elite. a variant of it was the heart of the well-known Gravis Ultrasound.
-
-it has a whopping 32 channels of 16-bit PCM and:
-
-- real time digital filters
-- linear interpolation
-- loop start and stop positions for each voice (bidirectional and reverse looping)
-- internal volume multiplication and stereo panning
-- hardware support for short envelopes
-
-## effects
-
-- `10xx`: **set waveform.**
-- `11xx`: **set filter mode.** values are `0` through `3`.
-- `120x`: **set pause (bit 0).** pauses the sample until the bit is unset; it will then resume where it left off.
-- `14xx`: **set filter coefficient K1 low byte.**
-- `15xx`: **set filter coefficient K1 high byte.**
-- `16xx`: **set filter coefficient K2 low byte.**
-- `17xx`: **set filter coefficient K2 high byte.**
-- `18xx`: **set filter coefficient K1 slide up.**
-- `19xx`: **set filter coefficient K1 slide down.**
-- `1Axx`: **set filter coefficient K2 slide up.**
-- `1Bxx`: **set filter coefficient K2 slide down.**
-- `20xx`: **set envelope count.**
-- `22xx`: **set envelope left volume ramp.**
-- `23xx`: **set envelope right volume ramp.**
-- `24xx`: **set envelope filter coefficient K1 ramp.**
-- `25xx`: **set envelope filter coefficient K1 ramp (slower).**
-- `26xx`: **set envelope filter coefficient K2 ramp.**
-- `27xx`: **set envelope filter coefficient K2 ramp (slower).**
-- `3xxx`: **set coarse filter coefficient K1.**
-- `4xxx`: **set coarse filter coefficient K2.**
-- `81xx`: **set panning (left channel).**
-- `82xx`: **set panning (right channel).**
-- `88xx`: **set panning (rear channels).**
-- `89xx`: **set panning (rear left channel).**
-- `8Axx`: **set panning (rear right channel).**
-- `9xxx`: **set sample offset.**
-  - resets sample position to `xxx * 0x100`.
-- `DFxx`: **set sample playback direction.**
-
-## info
-
-this chip uses the [ES5506](../4-instrument/es5506.md) instrument editor.
+# Ensoniq ES5506 (OTTO)
+
+sample-based synthesis chip used in a bunch of Taito arcade machines and PC sound cards like Soundscape Elite. a variant of it was the heart of the well-known Gravis Ultrasound.
+
+it has a whopping 32 channels of 16-bit PCM and:
+
+- real time digital filters
+- linear interpolation
+- loop start and stop positions for each voice (bidirectional and reverse looping)
+- internal volume multiplication and stereo panning
+- hardware support for short envelopes
+
+## effects
+
+- `10xx`: **set waveform.**
+- `11xx`: **set filter mode.** values are `0` through `3`.
+- `120x`: **set pause (bit 0).** pauses the sample until the bit is unset; it will then resume where it left off.
+- `14xx`: **set filter coefficient K1 low byte.**
+- `15xx`: **set filter coefficient K1 high byte.**
+- `16xx`: **set filter coefficient K2 low byte.**
+- `17xx`: **set filter coefficient K2 high byte.**
+- `18xx`: **set filter coefficient K1 slide up.**
+- `19xx`: **set filter coefficient K1 slide down.**
+- `1Axx`: **set filter coefficient K2 slide up.**
+- `1Bxx`: **set filter coefficient K2 slide down.**
+- `20xx`: **set envelope count.**
+- `22xx`: **set envelope left volume ramp.**
+- `23xx`: **set envelope right volume ramp.**
+- `24xx`: **set envelope filter coefficient K1 ramp.**
+- `25xx`: **set envelope filter coefficient K1 ramp (slower).**
+- `26xx`: **set envelope filter coefficient K2 ramp.**
+- `27xx`: **set envelope filter coefficient K2 ramp (slower).**
+- `3xxx`: **set coarse filter coefficient K1.**
+- `4xxx`: **set coarse filter coefficient K2.**
+- `81xx`: **set panning (left channel).**
+- `82xx`: **set panning (right channel).**
+- `88xx`: **set panning (rear channels).**
+- `89xx`: **set panning (rear left channel).**
+- `8Axx`: **set panning (rear right channel).**
+- `9xxx`: **set sample offset.**
+  - resets sample position to `xxx * 0x100`.
+- `DFxx`: **set sample playback direction.**
+
+## info
+
+this chip uses the [ES5506](../4-instrument/es5506.md) instrument editor.

doc/7-systems/esfm.md

@@ -0,0 +1,101 @@
+# ESS ESFM
+
+an enhanced version of Yamaha's OPL3, adding many features which weren't present on the original chip, such as 4-op on all channels, coarse/fine detune, per-op panning, envelope delay, noise generator and advanced modulation routing (no more algorithms!).
+
+the technology was present in many of ESS' sound cards (the ES1xxx series in particular).
+
+## effects
+
+- `10xy`: **set AM depth.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is either `0` (1dB, shallow) or `1` (4.8dB, deep).
+- `12xx`: **set operator 1 level.**
+- `13xx`: **set operator 2 level.**
+- `14xx`: **set operator 3 level.**
+- `15xx`: **set operator 4 level.**
+- `16xy`: **set multiplier of operator.**
+  - `x` is the operator (1-4).
+  - `y` is the new MULT value..
+- `17xy`: **set vibrato depth.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is either `0` (normal) or `1` (double).
+- `19xx`: **set attack of all operators.**
+- `1Axx`: **set attack of operator 1.**
+- `1Bxx`: **set attack of operator 2.**
+- `1Cxx`: **set attack of operator 3.**
+- `1Dxx`: **set attack of operator 4.**
+- `20xy`: **set panning of operator 1.**
+  - `x` determines whether to output on left.
+  - `y` determines whether to output on right.
+- `21xy`: **set panning of operator 2.**
+  - `x` determines whether to output on left.
+  - `y` determines whether to output on right.
+- `22xy`: **set panning of operator 3.**
+  - `x` determines whether to output on left.
+  - `y` determines whether to output on right.
+- `23xy`: **set panning of operator 4.**
+  - `x` determines whether to output on left.
+  - `y` determines whether to output on right.
+- `24xy`: **set output level of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `25xy`: **set modulation input level of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `26xy`: **set envelope delay of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `27xx`: **set operator 4 noise mode.**
+  - `0`: noise off
+  - `1`: square + noise
+  - `2`: ring mod from operator 3 + noise
+  - `3`: ring mod from operator 3 + double pitch modulation input
+    - note: emulation issues. subject to change!
+- `2Axy`: **set waveform of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `2Exx`: **enable envelope hard reset.**
+- `2Fxy`: **set fixed frequency block (octave).**
+  - `x` is the operator from 1 to 4.
+  - `y` is the block/octave from 0 to 7.
+- `3xyy`: **set fixed frequency f-num.**
+  - `x` contains operator number and high bits of f-num may be any of the following:
+    - `0` to `3` for operator 1
+    - `4` to `7` for operator 2
+    - `8` to `B` for operator 3
+    - `C` to `F` for operator 4
+  - `y` are the lower bits of f-num.
+- `40xx`: **set operator 1 detune.**
+- `41xx`: **set operator 1 detune.**
+- `42xx`: **set operator 1 detune.**
+- `43xx`: **set operator 1 detune.**
+- `50xy`: **set AM of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` determines whether AM is on.
+- `51xy`: **set SL of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `52xy`: **set RR of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `53xy`: **set VIB of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` determines whether VIB is on.
+- `54xy`: **set KSL of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` is the value.
+- `55xy`: **set SUS of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` determines whether SUS is on.
+- `56xx`: **set DR of all operators.**
+- `57xx`: **set DR of operator 1.**
+- `58xx`: **set DR of operator 2.**
+- `59xx`: **set DR of operator 3.**
+- `5Axx`: **set DR of operator 4.**
+- `5Bxy`: **set KSR of operator.**
+  - `x` is the operator from 1 to 4. a value of `0` means "all operators".
+  - `y` determines whether KSR is on.
+
+## info
+
+this chip uses the [FM (ESFM)](../4-instrument/fm-esfm.md) instrument editor.

doc/7-systems/n163.md

@@ -6,7 +6,7 @@ it has 256 nibbles (128 bytes) of internal RAM which is shared between channel s
 
 wavetables are variable in size and may be allocated anywhere in RAM. at least 128 nibbles (64 bytes) can be dedicated to waves, with more available if not all channels are used - waveform RAM area becomes smaller as more channels are activated, since channel registers consume 8 bytes for each channel.
 
-Namco 163 uses time-division multiplexing for its output. this means that only one channel is output per sample (like OPLL and OPN2). therefore, its sound quality gets worse as more channels are activated.
+Namco 163 uses time-division multiplexing (TDM) for its output. this means that only one channel is output per sample (like OPLL and OPN2). therefore, its sound quality gets worse as more channels are activated.
 
 ## waveform load position versus waveform position
 
@@ -39,6 +39,13 @@ if the waveform changes (e.g. ins change, wave macro or wave synth), or the **lo
   - make sure to use `21xx` first!
 - `21xx`: **set position for 20xx.**
 
+## chip options
+
+- **Initial channel limit**: sets the number of channels that will be active. higher values reduce volume and make TDM artifacts more noticeable.
+- **Disable hissing**: remove TDM artifacts by mixing. sacrifices some accuracy!
+- **Scale frequency to wave length**: automatically adjusts note frequency to account for differing waveform lengths.
+  - if disabled, note frequencies ignore waveveform length. this is how FamiTracker behaves.
+
 ## info
 
 this chip uses the [Namco 163](../4-instrument/n163.md) instrument editor.

doc/7-systems/opll.md

@@ -15,8 +15,8 @@ the YM2413 is equipped with the following features:
 - a drum/percussion mode, replacing the last 3 voices with 5 rhythm channels, with drum mode tones hard-defined in the chip itself, like FM instruments. only pitch might be altered.
   - drum mode works like following: FM channel 7 is for Kick Drum, which is a normal FM channel but routed through mixer twice for 2× volume, like all drum sounds. FM channel 8 splits to Snare, Drum, and Hi-Hat. Snare Drum is the carrier and it works with a special 1 bit noise generator combined with a square wave, all possible by overriding phase-generator with some different synthesis method. Hi-Hat is the modulator and it works with the noise generator and also the special synthesis. channel 9 splits to Top-Cymbal and Tom-Tom, Top-Cymbal is the carrier and only has the special synthesis, while Tom-Tom is basically a 1op wave. 
   - special synthesis mentioned already is: 5 square waves are gathered from 4×, 64× and 128× the pitch of channel 8 and 16× and 64× the pitch of channel 9 and they go through a process where 2 HH bits OR'd together, then 1 HH and 1 TC bit OR'd, then the two TC bits OR'd together, and those 3 results get XOR'd.
-- 1 user-definable patch (this patch can be changed throughout the course of the song)
-- 15 pre-defined patches which can all be used at the same time
+- **1 user-definable patch (this patch can be changed throughout the course of the song)**
+- **15 pre-defined patches which can all be used at the same time**
 - support for ADSR on both the modulator and the carrier
 - sine and half-sine based FM synthesis
 - 9 octave note control

doc/8-advanced/chanosc.md

@@ -33,6 +33,7 @@ right-clicking the view will display the configuration view shown above:
   - `%v`: volume (decimal)
   - `%V`: volume (percentage)
   - `%b`: volume (hex)
+  - `%l`: new line
   - `%%`: percent sign
 
 click on OK to return to the main view.

doc/README.md

@@ -27,7 +27,7 @@ the index follows.
 
 ## information
 
-copyright © 2023 tildearrow and other authors.
+copyright © 2024 tildearrow and other authors.
 
 this documentation is under the [Creative Commons Attribution 3.0 Unported](https://creativecommons.org/licenses/by/3.0/) license.
 you may reproduce, modify and/or distribute this documentation provided this copyright notice (including license and attribution) is present and any necessary disclaimers whether modifications have been made.

extern/ESFMu/.gitignore

@@ -0,0 +1 @@
+test_scripts/*

extern/ESFMu/LICENSE

@@ -0,0 +1,504 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+    USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random
+  Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!

extern/ESFMu/README.md

@@ -0,0 +1,67 @@
+# ESFMu
+
+An emulator for the ESS "ESFM" enhanced OPL3 clone, based on Nuke.YKT's **Nuked OPL3** and reverse-engineering efforts from the community.
+
+## Acknowledgements
+
+I'd like to thank:
+
+- **Nuke.YKT**
+  - Developer of **Nuked OPL3**, which was the basis for **ESFMu**'s code and also a great learning resource on Yamaha FM synthesis for myself.
+  - Nuke.YKT also gives shoutouts on behalf of **Nuked OPL3** to:
+    >- MAME Development Team(Jarek Burczynski, Tatsuyuki Satoh):
+    >    - Feedback and Rhythm part calculation information.
+    >- forums.submarine.org.uk(carbon14, opl3):
+    >    - Tremolo and phase generator calculation information.
+    >- OPLx decapsulated(Matthew Gambrell, Olli Niemitalo):
+    >    - OPL2 ROMs.
+    >- siliconpr0n.org(John McMaster, digshadow):
+    >    - YMF262 and VRC VII decaps and die shots.
+- **rainwarrior**
+  - For performing the initial research on ESFM drivers and documenting ESS's patent on native mode operator organization.
+- **jwt27**
+  - For kickstarting the ESFM research project and compiling rainwarrior's findings and more in an accessible document ("ESFM Demystified").
+- **pachuco/CatButts**
+  - For documenting ESS's patent on ESFM's feedback implementation, which was vital in getting **ESFMu**'s sound output to be accurate.
+- And everybody who helped out with real hardware testing
+
+## Usage
+
+To use **ESFMu**:
+
+- include the **esfm.h** header file into your source code
+- include the **esfm.c** and **esfm_registers.c** files into your build and link process
+- declare or allocate a variable of type `esfm_chip` somewhere in your code - this will hold the chip's state
+- use the function interface defined in **esfm.h** to interact with the `esfm_chip` structure
+
+## Function interface
+
+If you're familiar with **Nuked OPL3**, you'll find many similarities in the function interface provided by **ESFMu**. There are a few things to point out, however:
+
+### Buffered writes
+
+Just like **Nuked OPL3**, **ESFMu** offers buffered register writes. However, it offers them in two flavors: "legacy" and fast.
+
+The fast buffered register writes (`ESFM_write_reg_buffered_fast`) are recommended, since they offer minimal latency which is close to the behavior you'd get with the actual ESS drivers on Windows.
+
+The "legacy" buffered register writes are only recommended for specific cases, such as programs seeking for a shortcut to emulate the write delays from some sound drivers.
+
+### Port-level access
+
+Unlike **Nuked OPL3**, **ESFMu** actually allows port-level access to the ESFM interface. This is relevant because the ESFM port interface is actually modal, meaning that its behavior changes depending on whether the chip is set to emulation (OPL3 compatibility) mode or native (ESFM) mode.
+
+Using port-level access allows for applications to not need to keep track of whether the chip is in native mode or not, nor to perform the port handling logic on their side.
+
+Applications that use the register-level access, on the other hand, need to take care to either stick to only one of the operating modes (either native or emulation), or handle the port mapping logic on their own side.
+
+### Register readback
+
+ESFM allows for register contents to be read back through its ports, and **ESFMu** implements this functionality, both via dedicated register read functions and via the port read interface.
+
+Note that in ESFM, register contents can only be read back when the chip is set to native (ESFM) mode, not when the chip is in emulation mode (i.e. OPL3 compatibility mode).
+
+## Licensing
+
+**ESFMu** is highly based on **Nuked OPL3**, which is licensed under the GNU Lesser General Public License version 2.1 or later. Therefore, **ESFMu** is licensed under the same license.
+
+If you'd like to obtain a grant to use **ESFMu** under different terms, you should get in contact with [Nuke.YKT](https://github.com/nukeykt) (author of **Nuked OPL3**) as well as with [Kagamiin~](https://github.com/Kagamiin) (yours truly).

extern/ESFMu/esfm.h

@@ -0,0 +1,310 @@
+/*
+ * ESFMu: emulator for the ESS "ESFM" enhanced OPL3 clone
+ * Copyright (C) 2023 Kagamiin~
+ *
+ * ESFMu is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * ESFMu is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with ESFMu. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/*
+ * ESFMu wouldn't have been possible without the hard work and dedication of
+ * the retro computer hardware research and preservation community.
+ *
+ * I'd like to thank:
+ *  - Nuke.YKT
+ *        Developer of Nuked OPL3, which was the basis for ESFMu's code and
+ *        also a great learning resource on Yamaha FM synthesis for myself.
+ *        Nuke.YKT also gives shoutouts on behalf of Nuked OPL3 to:
+ *        - MAME Development Team(Jarek Burczynski, Tatsuyuki Satoh):
+ *              Feedback and Rhythm part calculation information.
+ *        - forums.submarine.org.uk(carbon14, opl3):
+ *              Tremolo and phase generator calculation information.
+ *        - OPLx decapsulated(Matthew Gambrell, Olli Niemitalo):
+ *              OPL2 ROMs.
+ *        - siliconpr0n.org(John McMaster, digshadow):
+ *              YMF262 and VRC VII decaps and die shots.
+ * - rainwarrior
+ *       For performing the initial research on ESFM drivers and documenting
+ *       ESS's patent on native mode operator organization.
+ * - jwt27
+ *       For kickstarting the ESFM research project and compiling rainwarrior's
+ *       findings and more in an accessible document ("ESFM Demystified").
+ * - pachuco/CatButts
+ *       For documenting ESS's patent on ESFM's feedback implementation, which
+ *       was vital in getting ESFMu's sound output to be accurate.
+ * - And everybody who helped out with real hardware testing
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct _esfm_slot esfm_slot;
+typedef struct _esfm_slot_internal esfm_slot_internal;
+typedef struct _esfm_channel esfm_channel;
+typedef struct _esfm_chip esfm_chip;
+
+
+void ESFM_init (esfm_chip *chip);
+void ESFM_write_reg (esfm_chip *chip, uint16_t address, uint8_t data);
+void ESFM_write_reg_buffered (esfm_chip *chip, uint16_t address, uint8_t data);
+void ESFM_write_reg_buffered_fast (esfm_chip *chip, uint16_t address, uint8_t data);
+void ESFM_write_port (esfm_chip *chip, uint8_t offset, uint8_t data);
+uint8_t ESFM_readback_reg (esfm_chip *chip, uint16_t address);
+uint8_t ESFM_read_port (esfm_chip *chip, uint8_t offset);
+void ESFM_generate(esfm_chip *chip, int16_t *buf);
+void ESFM_generate_stream(esfm_chip *chip, int16_t *sndptr, uint32_t num_samples);
+int16_t ESFM_get_channel_output_native(esfm_chip *chip, int channel_idx);
+
+
+// These are fake types just for syntax sugar.
+// Beware of their underlying types when reading/writing to them.
+#ifndef __NO_ESFM_FAST_TYPES
+#ifndef __ESFM_FAST_TYPES
+#define __ESFM_FAST_TYPES
+#endif
+#endif
+
+#ifdef __ESFM_FAST_TYPES
+
+typedef uint_fast8_t flag;
+typedef uint_fast8_t uint2;
+typedef uint_fast8_t uint3;
+typedef uint_fast8_t uint4;
+typedef uint_fast8_t uint5;
+typedef uint_fast8_t uint6;
+typedef uint_fast8_t uint8;
+typedef uint_fast16_t uint9;
+typedef uint_fast16_t uint10;
+typedef uint_fast16_t uint11;
+typedef uint_fast16_t uint12;
+typedef uint_fast16_t uint16;
+typedef uint_fast32_t uint19;
+typedef uint_fast32_t uint23;
+typedef uint_fast32_t uint32;
+typedef uint_fast64_t uint36;
+
+typedef int_fast16_t int13;
+typedef int_fast16_t int14;
+typedef int_fast16_t int16;
+typedef int_fast32_t int32;
+
+#else
+typedef uint8_t flag;
+typedef uint8_t uint2;
+typedef uint8_t uint3;
+typedef uint8_t uint4;
+typedef uint8_t uint5;
+typedef uint8_t uint6;
+typedef uint8_t uint8;
+typedef uint16_t uint9;
+typedef uint16_t uint10;
+typedef uint16_t uint11;
+typedef uint16_t uint12;
+typedef uint16_t uint16;
+typedef uint32_t uint19;
+typedef uint32_t uint23;
+typedef uint32_t uint32;
+typedef uint64_t uint36;
+
+typedef int16_t int13;
+typedef int16_t int14;
+typedef int16_t int16;
+typedef int32_t int32;
+
+#endif
+
+enum eg_states
+{
+	EG_ATTACK,
+	EG_DECAY,
+	EG_SUSTAIN,
+	EG_RELEASE
+};
+
+
+typedef struct _esfm_write_buf
+{
+	uint64_t timestamp;
+	uint16_t address;
+	uint8_t data;
+	flag valid;
+
+} esfm_write_buf;
+
+typedef struct _emu_slot_channel_mapping
+{
+	int channel_idx;
+	int slot_idx;
+
+} emu_slot_channel_mapping;
+
+typedef struct _esfm_slot_internal
+{
+	uint9 eg_position;
+	uint9 eg_ksl_offset;
+	uint10 eg_output;
+
+	uint4 keyscale;
+
+	int13 output;
+	int13 emu_output_enable;
+	int13 emu_mod_enable;
+	int13 feedback_buf;
+	int13 *mod_input;
+
+	uint19 phase_acc;
+	uint10 phase_out;
+	flag phase_reset;
+	flag *key_on;
+	flag key_on_gate;
+
+	uint2 eg_state;
+	flag eg_delay_run;
+	flag eg_delay_transitioned_10;
+	flag eg_delay_transitioned_10_gate;
+	flag eg_delay_transitioned_01;
+	flag eg_delay_transitioned_01_gate;
+	uint16 eg_delay_counter;
+	uint16 eg_delay_counter_compare;
+
+} esfm_slot_internal;
+
+struct _esfm_slot
+{
+	// Metadata
+	esfm_channel *channel;
+	esfm_chip *chip;
+	uint2 slot_idx;
+
+	// Register data
+	int13 out_enable[2];
+	uint10 f_num;
+	uint3 block;
+	uint3 output_level;
+	// a.k.a. feedback level in emu mode
+	uint3 mod_in_level;
+
+	uint6 t_level;
+	uint4 mult;
+	uint3 waveform;
+	// Only for 4th slot
+	uint2 rhy_noise;
+
+	uint4 attack_rate;
+	uint4 decay_rate;
+	uint4 sustain_lvl;
+	uint4 release_rate;
+
+	flag tremolo_en;
+	flag tremolo_deep;
+	flag vibrato_en;
+	flag vibrato_deep;
+	flag emu_connection_typ;
+	flag env_sustaining;
+	flag ksr;
+	uint2 ksl;
+	uint3 env_delay;
+	// overlaps with env_delay bit 0
+	// TODO: check if emu mode only uses this, or if it actually overwrites the channel field used by native mode
+	flag emu_key_on;
+
+	// Internal state
+	esfm_slot_internal in;
+};
+
+struct _esfm_channel
+{
+	esfm_chip *chip;
+	esfm_slot slots[4];
+	uint5 channel_idx;
+	int16 output[2];
+	flag key_on;
+	flag emu_mode_4op_enable;
+	// Only for 17th and 18th channels
+	flag key_on_2;
+	flag emu_mode_4op_enable_2;
+};
+
+#define ESFM_WRITEBUF_SIZE 1024
+#define ESFM_WRITEBUF_DELAY 2
+
+struct _esfm_chip
+{
+	esfm_channel channels[18];
+	int32 output_accm[2];
+	uint_fast16_t addr_latch;
+
+	flag emu_wavesel_enable;
+	flag emu_newmode;
+	flag native_mode;
+
+	flag keyscale_mode;
+
+	// Global state
+	uint36 eg_timer;
+	uint10 global_timer;
+	uint8 eg_clocks;
+	flag eg_tick;
+	flag eg_timer_overflow;
+	uint8 tremolo;
+	uint8 tremolo_pos;
+	uint8 vibrato_pos;
+	uint23 lfsr;
+
+	flag rm_hh_bit2;
+	flag rm_hh_bit3;
+	flag rm_hh_bit7;
+	flag rm_hh_bit8;
+	flag rm_tc_bit3;
+	flag rm_tc_bit5;
+
+	// 0xbd register in emulation mode, exposed in 0x4bd in native mode
+	// ("bass drum" register)
+	uint8 emu_rhy_mode_flags;
+
+	flag emu_vibrato_deep;
+	flag emu_tremolo_deep;
+
+	uint8 timer_reload[2];
+	uint8 timer_counter[2];
+	flag timer_enable[2];
+	flag timer_mask[2];
+	flag timer_overflow[2];
+	flag irq_bit;
+
+	// Halts the envelope generators from advancing.
+	flag test_bit_eg_halt;
+	/*
+	 * Activates some sort of waveform test mode that amplifies the output volume greatly
+	 * and continuously shifts the waveform table downwards, possibly also outputting the
+	 * waveform's derivative? (it's so weird!)
+	 */
+	flag test_bit_distort;
+	// Appears to attenuate the output by about 3 dB.
+	flag test_bit_attenuate;
+	// Resets all phase generators and holds them in the reset state while this bit is set.
+	flag test_bit_phase_stop_reset;
+
+	esfm_write_buf write_buf[ESFM_WRITEBUF_SIZE];
+	size_t write_buf_start;
+	size_t write_buf_end;
+	uint64_t write_buf_timestamp;
+};
+
+#ifdef __cplusplus
+}
+#endif