furnace/doc/4-instrument/fm-opn.md

# FM (OPN) instrument editor

the FM editor is divided into 7 tabs:

- **FM**: for controlling the basic parameters of FM sound source.
- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
- **Macros**: for other macros (volume/arp/pitch).

## FM

OPN is four-operator, meaning it takes four oscillators to produce a single sound.

these apply to the instrument as a whole:
- **Algorithm (ALG)**: determines how operators are connected to each other (0 to 7).
  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
  - right-click to switch to a preview display of the waveform generated on a new note:
    - left-click restarts the preview.
    - middle-click pauses and unpauses the preview.
    - right-click returns to algorithm view.
- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).

- **LFO > Freq (FMS)**: determines how much will LFO have an effect in frequency (0 to 7).
- **LFO > Amp (AMS)**: determines how much will LFO have an effect in volume (0 to 3).
  - only applies to operators which have AM turned on.
  - does not apply to YM2203.

these apply to each operator:
- the crossed-arrows button can be dragged to rearrange operators.
- the **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
- **Amplitude Modulation (AM)**: makes the operator's volume affected by LFO.
  - does not apply to YM2203.
- **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 31).
- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 31).
- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. this is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. a change of one unit is about 0.75 dB.
- **Hardware Envelope Generator (SSG-EG)**: executes the built-in envelope, inherited from AY-3-8910 PSG. speed of execution is controlled via Decay Rate.

![FM ADSR chart](FM-ADSRchart.png)

- **Envelope Scale (RS/KS)**: also known as "Key Scale" or "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
- **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
- **Fine Detune (DT)**: shifts the pitch a little (0 to 7).


## macros

these macros allow you to control several parameters of FM per tick.

## FM Macros

- **LFO Speed**: LFO frequency.
- **OpMask**: toggles each operator.

## OP1-OP4 Macros

all parameters are listed above.

## Macros

- **Arpeggio**: pitch change sequence in semitones.
- **Panning**: toggles output on left and right channels.
- **Pitch**: fine pitch.
  - **Relative**: when enabled, pitch changes are relative to the current pitch.
- **Phase Reset**: restarts all operators and resets the waveform to its start.


## links

[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. this was made for DefleMask, but all the same principles apply.
-												more doc updates

											
										
										
											2023-09-09 09:27:48 +00:00
+								# FM (OPN) instrument editor
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								the FM editor is divided into 7 tabs:
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												Fixing something I botched.

Hey, all those files I thought I clobbered!

											
										
										
											2023-06-24 01:13:37 +00:00
+								- **FM**: for controlling the basic parameters of FM sound source.
-												doc finalization: instrument

											
										
										
											2023-09-10 04:11:43 +00:00
+								- **Macros (FM)**: for macros controlling algorithm, feedback and LFO.
 								- **Macros (OP1)**: for macros controlling FM parameters of operator 1.
 								- **Macros (OP2)**: for macros controlling FM parameters of operator 2.
 								- **Macros (OP3)**: for macros controlling FM parameters of operator 3.
 								- **Macros (OP4)**: for macros controlling FM parameters of operator 4.
-												Revert "Revert "Revert "Fixed typos" (#1121)""

This reverts commit fb61309ac72c5bed7673319562cb4e04d4190963.

											
										
										
											2023-09-13 04:28:45 +00:00
+								- **Macros**: for other macros (volume/arp/pitch).
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
 								## FM
-												doc updates

mostly instrument

											
										
										
											2023-09-10 01:07:05 +00:00
+								OPN is four-operator, meaning it takes four oscillators to produce a single sound.
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								these apply to the instrument as a whole:
 								- **Algorithm (ALG)**: determines how operators are connected to each other (0 to 7).
 								  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
 								  - right-click to switch to a preview display of the waveform generated on a new note:
 								    - left-click restarts the preview.
 								    - middle-click pauses and unpauses the preview.
 								    - right-click returns to algorithm view.
 								- **Feedback (FB)**: determines how many times operator 1 returns its output to itself (0 to 7).
 								- **LFO > Freq (FMS)**: determines how much will LFO have an effect in frequency (0 to 7).
 								- **LFO > Amp (AMS)**: determines how much will LFO have an effect in volume (0 to 3).
-												doc updates

mostly instrument

											
										
										
											2023-09-10 01:07:05 +00:00
+								  - only applies to operators which have AM turned on.
-												more doc updates

											
										
										
											2023-09-09 09:27:48 +00:00
+								  - does not apply to YM2203.
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								these apply to each operator:
 								- the crossed-arrows button can be dragged to rearrange operators.
 								- the **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
 								- **Amplitude Modulation (AM)**: makes the operator's volume affected by LFO.
-												more doc updates

											
										
										
											2023-09-09 09:27:48 +00:00
+								  - does not apply to YM2203.
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 31).
 								- **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 31).
 								- **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
 								- **Decay Rate 2 (D2R) / Sustain Rate (SR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. this is the long "tail" of the sound that continues as long as the key is depressed (0 to 31).
 								- **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
-												A change

											
										
										
											2023-09-10 22:12:07 +00:00
+								- **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. a change of one unit is about 0.75 dB.
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Hardware Envelope Generator (SSG-EG)**: executes the built-in envelope, inherited from AY-3-8910 PSG. speed of execution is controlled via Decay Rate.
-												FM ADSR chart and tutorial link.

Also several minor text and formatting tweaks.

											
										
										
											2023-07-23 18:33:30 +00:00
 								![FM ADSR chart](FM-ADSRchart.png)
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Envelope Scale (RS/KS)**: also known as "Key Scale" or "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch (0 to 3).
-												Revert "Revert "Revert "Fixed typos" (#1121)""

This reverts commit fb61309ac72c5bed7673319562cb4e04d4190963.

											
										
										
											2023-09-13 04:28:45 +00:00
+								- **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.
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Fine Detune (DT)**: shifts the pitch a little (0 to 7).
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												FM ADSR chart and tutorial link.

Also several minor text and formatting tweaks.

											
										
										
											2023-07-23 18:33:30 +00:00
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
+								## macros
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												Revert "Revert "Revert "Fixed typos" (#1121)""

This reverts commit fb61309ac72c5bed7673319562cb4e04d4190963.

											
										
										
											2023-09-13 04:28:45 +00:00
+								these macros allow you to control several parameters of FM per tick.
-												add instrument docs
											
										
										
											2022-02-04 21:05:25 +00:00
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
+								## FM Macros
 								- **LFO Speed**: LFO frequency.
 								- **OpMask**: toggles each operator.
-												Fixing something I botched.

Hey, all those files I thought I clobbered!

											
										
										
											2023-06-24 01:13:37 +00:00
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
+								## OP1-OP4 Macros
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								all parameters are listed above.
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
 								## Macros
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Arpeggio**: pitch change sequence in semitones.
-												Making the macros match.

											
										
										
											2023-07-23 20:17:31 +00:00
+								- **Panning**: toggles output on left and right channels.
 								- **Pitch**: fine pitch.
-												doc updates

mostly instrument

											
										
										
											2023-09-10 01:07:05 +00:00
+								  - **Relative**: when enabled, pitch changes are relative to the current pitch.
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								- **Phase Reset**: restarts all operators and resets the waveform to its start.
-												FM ADSR chart and tutorial link.

Also several minor text and formatting tweaks.

											
										
										
											2023-07-23 18:33:30 +00:00
-												only one header per doc file

											
										
										
											2023-09-11 00:34:13 +00:00
+								## links
-												FM ADSR chart and tutorial link.

Also several minor text and formatting tweaks.

											
										
										
											2023-07-23 18:33:30 +00:00
-												De-capitalization of docs (and little typo fixes)

There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold.

											
										
										
											2023-09-10 17:16:55 +00:00
+								[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. this was made for DefleMask, but all the same principles apply.