otomatalabs/furnace
7
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Split NES and PSG instrument docs.

Browse source
This commit is contained in:
Electric Keet 2023-07-13 17:19:00 -07:00 committed by GitHub
parent ed7265645d
commit 7cfdad6367
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 146 additions and 113 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

227
doc/4-instrument/README.md
View file

@ -1,113 +1,114 @@
# instrument list # instrument list
![instrument list](list.png) ![instrument list](list.png)
click on an instrument to select it. click on an instrument to select it.
double-click to open the instrument editor. double-click to open the instrument editor.
# instrument editor # instrument editor
every instrument can be renamed and have its type changed. every instrument can be renamed and have its type changed.
depending on the instrument type, there are many different types of instrument editor: depending on the instrument type, there are many different types of instrument editor:
- [FM synthesis](fm.md) - for use with YM2612, YM2151 and FM block portion of YM2610. - [FM synthesis](fm.md) - for use with YM2612, YM2151 and FM block portion of YM2610.
- [Standard](standard.md) - for use with NES and Sega Master System's PSG sound source and its derivatives. - [PSG](psg.md) - for use with TI SN76489 and derivatives like Sega Master System's PSG.
- [Game Boy](game-boy.md) - for use with Game Boy APU. - [NES](nes.md) - for use with NES.
- [PC Engine / TurboGrafx-16](pce.md) - for use with PC Engine's wavetable synthesizer. - [Game Boy](game-boy.md) - for use with Game Boy APU.
- [WonderSwan](wonderswan.md) - for use with WonderSwan's wavetable synthesizer. - [PC Engine / TurboGrafx-16](pce.md) - for use with PC Engine's wavetable synthesizer.
- [AY8930](8930.md) - for use with Microchip AY8930 E-PSG sound source. - [WonderSwan](wonderswan.md) - for use with WonderSwan's wavetable synthesizer.
- [Commodore 64](c64.md) - for use with Commodore 64 SID. - [AY8930](8930.md) - for use with Microchip AY8930 E-PSG sound source.
- [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source. - [Commodore 64](c64.md) - for use with Commodore 64 SID.
- [TIA](tia.md) - for use with Atari 2600 chip. - [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source.
- [AY-3-8910](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610. - [TIA](tia.md) - for use with Atari 2600 chip.
- [Amiga / sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode. - [AY-3-8910](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610.
- [Atari Lynx](lynx.md) - for use with Atari Lynx handheld console. - [Amiga / sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
- [VERA](vera.md) - for use with Commander X16 VERA. - [Atari Lynx](lynx.md) - for use with Atari Lynx handheld console.
- [Seta/Allumer X1-010](x1_010.md) - for use with Wavetable portion in Seta/Allumer X1-010. - [VERA](vera.md) - for use with Commander X16 VERA.
- [Konami SCC / Bubble System WSG](scc.md) - for use with Konami SCC and Wavetable portion in Bubble System's sound hardware. - [Seta/Allumer X1-010](x1_010.md) - for use with Wavetable portion in Seta/Allumer X1-010.
- [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.
- [Konami VRC6](vrc6.md) - for use with VRC6's PSG sound source. - [Namco 163](n163.md) - for use with Namco 163.
- [SNES](snes.md) - for use with SNES S-APU. - [Konami VRC6](vrc6.md) - for use with VRC6's PSG sound source.
- [Casio PV-1000](pv1000.md) - for use with Casio PV-1000. - [SNES](snes.md) - for use with SNES S-APU.
- [Casio PV-1000](pv1000.md) - for use with Casio PV-1000.
# macros
# macros
Macros are incredibly versatile tools for automating instrument parameters.
Macros are incredibly versatile tools for automating instrument parameters.
After creating an instrument, open the Instrument Editor and select the "Macros" tab. There may be multiple macro tabs to control individual FM operators and such.
After creating an instrument, open the Instrument Editor and select the "Macros" tab. There may be multiple macro tabs to control individual FM operators and such.
![macro view](macroview.png)
![macro view](macroview.png)
The very first numeric entry sets the visible width of the bars in sequence-type macros. The scrollbar affects the view of all macros at once. There's a matching scrollbar at the bottom underneath all the macros.
The very first numeric entry sets the visible width of the bars in sequence-type macros. The scrollbar affects the view of all macros at once. There's a matching scrollbar at the bottom underneath all the macros.
Each macro has two buttons on the left.
- Macro type (explained below). Each macro has two buttons on the left.
- Timing editor, which pops up a small dialog: - Macro type (explained below).
- Step Length (ticks): Determines how many ticks pass before each change of value. - Timing editor, which pops up a small dialog:
- Delay: Delays the start of the macro until this many ticks have passed. - Step Length (ticks): Determines how many ticks pass before each change of value.
- Delay: Delays the start of the macro until this many ticks have passed.
## macro types
## macro types
Every macro can be defined though one of three methods, selectable with the leftmost button under the macro type label:
Every macro can be defined though one of three methods, selectable with the leftmost button under the macro type label:
- ![](macro-button-seq.png) **Sequence:** displayed as a bar graph, this is a sequence of numeric values.
- ![](macro-button-ADSR.png) **ADSR:** this is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time. - ![](macro-button-seq.png) **Sequence:** displayed as a bar graph, this is a sequence of numeric values.
- ![](macro-button-LFO.png) **LFO:** the Low Frequency Oscillator generates a repeating wave of values. - ![](macro-button-ADSR.png) **ADSR:** this is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time.
- ![](macro-button-LFO.png) **LFO:** the Low Frequency Oscillator generates a repeating wave of values.
Some macros are "bitmap" style. They represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
Some macros are "bitmap" style. They represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
### sequence
### sequence
![sequence macro editor](macro-seq.png)
![sequence macro editor](macro-seq.png)
The number between the macro type label and the macro type button is the macro length in steps. The `-` and `+` buttons change the length of the macro. Start out by adding at least a few steps.
The number between the macro type label and the macro type button is the macro length in steps. The `-` and `+` buttons change the length of the macro. Start out by adding at least a few steps.
The values of the macro can be drawn in the "bar graph box". Just beneath the box is shorter bar graph.
- Click to set the start point of a loop; the end point is the last value or release point. Right-click to remove the loop. The values of the macro can be drawn in the "bar graph box". Just beneath the box is shorter bar graph.
- Shift-click to set the release point. When played, the macro will hold here until the note is released. Right-click to remove the release point. - Click to set the start point of a loop; the end point is the last value or release point. Right-click to remove the loop.
- Shift-click to set the release point. When played, the macro will hold here until the note is released. Right-click to remove the release point.
Finally, the sequence of values can be directly edited in the text box at the bottom.
- The loop start is entered as a `|`. Finally, the sequence of values can be directly edited in the text box at the bottom.
- The release point is entered as a `/`. - The loop start is entered as a `|`.
- In arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). No matter the note played, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods. - The release point is entered as a `/`.
- In arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). No matter the note played, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods.
### ADSR
### ADSR
![ADSR macro editor](macro-ADSR.png)
![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. - **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** is how much the value moves toward Top with each tick. - Attack, Decay, Sustain, SusDecay, and Release accept inputs between 0 to 255. These are scaled to the distance between Bottom and Top.
- **Hold** sets how many ticks to stay at Top before Decay. - **Attack** is how much the value moves toward Top with each tick.
- **Decay** is how much the value moves to the Sustain level. - **Hold** sets how many ticks to stay at Top before Decay.
- **Sustain** is how far from Bottom the value stays while the note is held. - **Decay** is how much the value moves to the Sustain level.
- **SusTime** is how many ticks to stay at Sustain until SusDecay. - **Sustain** is how far from Bottom the value stays while the note is held.
- **SusDecay** is how much the value moves toward Bottom with each tick while the note is held. - **SusTime** is how many ticks to stay at Sustain until SusDecay.
- **Release** is how much the value moves toward Bottom with each tick after the note is released. - **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)
![macro ADSR chart](macro-ADSRchart.png)
### LFO
### LFO
![LFO macro editor](macro-LFO.png)
![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. - **Bottom** and **Top** determine the range of values generated by the macro. (Bottom can be larger than Top to invert the waveform!)
- **Phase** is which part of the waveform the macro will start at, measured in 1/1024 increments. - **Speed** is how quickly the values change - the frequency of the oscillator.
- **Shape** is the waveform used. Triangle is the default, and Saw and Square are exactly as they say. - **Phase** is which part of the waveform the macro will start at, measured in 1/1024 increments.
- **Shape** is the waveform used. Triangle is the default, and Saw and Square are exactly as they say.
# samples
# samples
This tab appears for Generic PCM, SNES, Amiga, and other sample-based instruments.
This tab appears for Generic PCM, SNES, Amiga, and other sample-based instruments.
![](sample-map.png)
![](sample-map.png)
- **Initial Sample**: the sample that the instrument will use.
- **Use wavetable**: instead of samples, use wavetables. this causes the [Wavetables](../5-wave/README.md) tab to appear next to Sample. - **Initial Sample**: the sample that the instrument will use.
- depending on the system and use of the wavetable synthesizer, this may or may not be reproducible on hardware. - **Use wavetable**: instead of samples, use wavetables. this causes the [Wavetables](../5-wave/README.md) tab to appear next to Sample.
- **Use sample map**: assigns a sample to each note. - depending on the system and use of the wavetable synthesizer, this may or may not be reproducible on hardware.
- samples will be played at their default pitch. - **Use sample map**: assigns a sample to each note.
- to set a note's sample, click the list entry in the `#` column then type the number of the sample. - samples will be played at their default pitch.
- to set a note's sample, click the list entry in the `#` column then type the number of the sample.

18
doc/4-instrument/nes.md Normal file
View file

@ -0,0 +1,18 @@
# Standard instrument editor
The instrument editor for NES consists of these macros:
- **Volume**: volume.
- **Arpeggio**: pitch in half-steps.
- **Duty**: duty cycle and noise mode.
- pulse duty cycles:
- `0`: 12.5%
- `1`: 25%
- `2`: 50%
- `3`: 75%
- noise modes:
- `0`: long noise.
- `1`: short noise.
- **Panning**: output for left and right channels.
- **Pitch**: fine pitch.
- **Phase Reset**: trigger restart of waveform.

14
doc/4-instrument/psg.md Normal file
View file

@ -0,0 +1,14 @@
# PSG instrument editor
The instrument editor for PSG (SMS, MSX, and other TI SN76489 derivatives) consists of these macros:
- **Volume**: volume.
- **Arpeggio**: pitch in half-steps.
- **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.
- **Pitch**: fine pitch.
- **Phase Reset**: trigger restart of waveform.