etc
/
furnace
mirror of https://github.com/tildearrow/furnace.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update documentation

This commit is contained in:
tildearrow 2022-01-16 01:10:43 -05:00
parent c09ce1892b
commit ed5279f96c
25 changed files with 541 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
papers/doc/1-intro/README.md
View File

@ -1,5 +1,5 @@
# introduction
furnace is a tool which allows you to compose music using the sound chips of several video game consoles from the 8/16-bit era.
Furnace is a tool which allows you to compose music using emulated sound chips from the 8/16-bit era.
the motivation behind this project is the fact that TODO!
it has a music tracker interface. think of a piano roll, or a table that scrolls up and plays the notes.

3
papers/doc/2-interface/README.md Normal file
View File

@ -0,0 +1,3 @@
# interface
TODO

15
papers/doc/3-pattern/README.md Normal file
View File

@ -0,0 +1,15 @@
# patterns
a pattern consists of columns ("channels") and rows.
each column has several subcolumns in this order:
1. note
2. instrument
3. volume
4. effect and effect value (several)
clicking on the top left corner of the pattern view allows you to increase or decrease the number of effect columns a channel has (max 4 per channel).
all columns are represented in hexadecimal, except for the note column.
for a list of effects [click here](effects.md).

50
papers/doc/3-pattern/effects.md Normal file
View File

@ -0,0 +1,50 @@
# effect list
most of the effect numbers are from ProTracker/FastTracker 2.
however, effects are continuous, which means you only need to type it once and then stop it with an effect value of `00`.
- `00xy`: arpeggio. after using this effect the channel will rapidly switch between `note`, `note+x` and `note+y`.
- `01xx`: slide up.
- `02xx`: slide down.
- `03xx`: note portamento.
- a note must be present for this effect to work.
- `04xy`: vibrato. `x` is the speed, while `y` is the depth.
- maximum vibrato depth is ±1 semitone.
- `08xy`: set panning. `x` is the left channel and `y` is the right one.
- not all platforms support this effect.
- `09xx`: set speed 1.
- `0Axy`: volume slide.
- if `x` is 0 then this is a slide down.
- if `y` is 0 then this is a slide up.
- `0Bxx`: jump to pattern.
- `0Cxx`: retrigger note every `xx` ticks.
- this effect is not continuous.
- `0Dxx`: jump to next pattern.
- `0Fxx`: set speed 2.
- `Cxxx`: change song Hz.
- `xxx` may be from `000` to `3ff`.
- `E0xx`: set arpeggio tick.
- this sets the number of ticks between arpeggio values.
- `E1xy`: note slide up. `x` is the speed, while `y` is how many semitones to slide up.
- `E2xy`: note slide down. `x` is the speed, while `y` is how many semitones to slide down.
- `E3xx`: set vibrato direction. `xx` may be one of the following:
- `00`: up and down.
- `01`: up only.
- `02`: down only.
- `E4xx`: set vibrato range in 1/16th of a semitone.
- `E5xx`: set pitch. `80` is 0 cents.
- range is ±1 semitone.
- `EAxx`: toggle legato.
- `EBxx`: set sample bank.
- does not apply on Amiga platform.
- `ECxx`: note off after `xx` ticks.
- `EDxx`: delay note by `xx` ticks.
- `EExx`: send external command.
- currently not used, but this eventually will allow you to do special things after I add VGM export.
- `EFxx`: add or subtract global pitch.
- this effect is rather weird. use with caution.
- `80` is center.
additionally each system/platform has its own effects. more details in another section of the manual.

3
papers/doc/4-instrument/README.md Normal file
View File

@ -0,0 +1,3 @@
# instrument editor
TODO

3
papers/doc/5-wave/README.md Normal file
View File

@ -0,0 +1,3 @@
# wavetable editor
TODO

3
papers/doc/6-sample/README.md Normal file
View File

@ -0,0 +1,3 @@
# sample editor
TODO

21
papers/doc/7-systems/README.md Normal file
View File

@ -0,0 +1,21 @@
# systems/platforms
this is a list of systems (platforms) that Furnace supports, including each platform's effects.
- [Sega Genesis/Mega Drive](genesis.md)
- [Sega Master System](sms.md)
- [Game Boy](game-boy.md)
- [PC Engine/TurboGrafx-16](pce.md)
- [NES](nes.md)
- [Commodore 64](c64.md)
- [Arcade (YM2151/PCM)](arcade.md)
- [Neo Geo/YM2610](ym2610.md)
- [AY-3-8910](ay8910.md)
- [Amiga](amiga.md)
- [Yamaha YM2612 standalone](ym2612.md)
- [Yamaha YM2151 standalone](ym2151.md)
- [Atari 2600](tia.md)
- [Philips SAA1099](saa1099.md)
- [Microchip AY8930](ay8930.md)
Furnace also reads .dmf files with the [Yamaha YMU759](ymu759.md) system, but does not emulate the chip at all.

9
papers/doc/7-systems/amiga.md Normal file
View File

@ -0,0 +1,9 @@
# Commodore Amiga
a computer with a desktop OS, lifelike graphics and 4 channels of PCM sound in 1985? no way!
in this very computer music trackers were born...
# effects
none. as of this moment the Amiga doesn't need any effects in particular, but some may be added in a future.

30
papers/doc/7-systems/arcade.md Normal file
View File

@ -0,0 +1,30 @@
# Arcade (Yamaha YM2151/PCM)
this chip combination was used in the Sega OutRun, X and Y arcade boards, and perhaps a few others.
the actual PCM chip had 16 channels, but the number has been cut to 5 in DefleMask for seemingly arbitrary reasons. a platform with all 16 channels may be coming soon.
# effects
- `10xx`: set noise frequency of channel 8 operator 4. 00 disables noise while 01 to 20 enables it.
- `11xx`: set feedback of channel.
- `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 mutliplier.
- `17xx`: set LFO speed.
- `18xx`: set LFO waveform. `xx` may be one of the following:
- `00`: saw
- `01`: square
- `02`: triangle
- `03`: noise
- `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.
- `20xx`: set PCM frequency.
- only works on the PCM channels.
- `xx` is a 256th fraction of 31250Hz.

35
papers/doc/7-systems/ay8910.md Normal file
View File

@ -0,0 +1,35 @@
# General Instrument AY-3-8910
this chip was used in several home computers (ZX Spectrum, MSX, Amstrad CPC, Atari ST, etc.), video game consoles (Intellivision and Vectrex), arcade boards and even slot machines!
the chip's powerful sound comes from the envelope...
# effects
- `20xx`: set channel mode. `xx` may be one of the following:
- `00`: square
- `01`: noise
- `02`: square and noise
- `03`: envelope
- `04`: envelope and square
- `05`: envelope and noise
- `06`: envelope and square and noise
- `07`: nothing
- `21xx`: set noise frequency. `xx` is a value between 00 and 1F.
- `22xy`: set envelope mode.
- `x` sets the envelope shape, which may be one of the following:
- `0: \___` decay
- `4: /___` attack once
- `8: \\\\` saw
- `9: \___` decay
- `A: \/\/` inverse obelisco
- `B: \¯¯¯` decay once
- `C: ////` inverse saw
- `D: /¯¯¯` attack
- `E: /\/\` obelisco
- `F: /___` attack once
- if `y` is 1 then the envelope will affect this channel.
- `23xx`: set envelope period low byte.
- `24xx`: set envelope period high byte.
- `25xx`: slide envelope period up.
- `26xx`: slide envelope period down.

39
papers/doc/7-systems/ay8930.md Normal file
View File

@ -0,0 +1,39 @@
# Microchip AY8930
a backwards-compatible successor to the AY-3-8910, with increased volume resolution, duty cycle control, three envelopes and highly configurable noise generator.
sadly, this soundchip has only ever observed minimal success, and has remained rather obscure since.
it is known for being used in the Covox Sound Master, which didn't sell well either.
while emulation of this chip is mostly complete, the additional noise setup registers are not emulated (yet). whether it ever has been emulated at some point in a now-abandoned tracker with similar goal as Furnace is unknown.
# effects
- `12xx`: set channel duty cycle. `xx` is a value between 00 and 08.
- `20xx`: set channel mode. `xx` may be one of the following:
- `00`: square
- `01`: noise
- `02`: square and noise
- `03`: envelope
- `04`: envelope and square
- `05`: envelope and noise
- `06`: envelope and square and noise
- `07`: nothing
- `21xx`: set noise frequency. `xx` is a value between 00 and FF.
- `22xy`: set envelope mode.
- `x` sets the envelope shape, which may be one of the following:
- `0: \___` decay
- `4: /___` attack once
- `8: \\\\` saw
- `9: \___` decay
- `A: \/\/` inverse obelisco
- `B: \¯¯¯` decay once
- `C: ////` inverse saw
- `D: /¯¯¯` attack
- `E: /\/\` obelisco
- `F: /___` attack once
- if `y` is 1 then the envelope will affect this channel.
- `23xx`: set envelope period low byte.
- `24xx`: set envelope period high byte.
- `25xx`: slide envelope period up.
- `26xx`: slide envelope period down.

57
papers/doc/7-systems/c64.md Normal file
View File

@ -0,0 +1,57 @@
# Commodore 64
a home computer with a synthesizer-grade sound chip of which people took decades to master.
very popular in Europe and mostly due to the demoscene, which stretched the machine's limbs to no end.
# effects
- `10xx`: change wave. the following values are accepted:
- `00`: nothing
- `01`: triangle
- `02`: saw
- `03`: triangle and saw
- `04`: pulse
- `05`: pulse and triangle
- `06`: pulse and saw
- `07`: pulse and triangle and saw
- `08`: noise
- `11xx`: set coarse cutoff. `xx` may be a value between 00 to 64.
- **this effect only exists for compatibility reasons, and its use is discouraged.**
- use effect `4xxx` instead.
- `12xx`: set coarse duty cycle. `xx` may be a value between 00 to 64.
- **this effect only exists for compatibility reasons, and its use is discouraged.**
- use effect `3xxx` instead.
- `13xx`: set resonance. `xx` may be a value between 00 and 0F.
- `14xx`: set filter mode. the following values are accepted:
- `00`: filter off
- `01`: low pass
- `02`: band pass
- `03`: low+band pass
- `04`: high pass
- `05`: band reject/stop/notch
- `06`: high+band pass
- `07`: all pass
- `15xx`: set envelope reset time.
- this is the amount of ticks the channel turns off before a note occurs in order to reset the envelope safely.
- if `xx` is 0 or higher than the song speed, the envelope will not reset.
- `1Axx`: disable envelope reset for this channel.
- `1Bxy`: reset cutoff:
- if `x` is not 0: on new note
- if `y` is not 0: now
- this effect is not necessary if the instrument's cutoff macro is absolute.
- `1Cxy`: reset duty cycle:
- if `x` is not 0: on new note
- if `y` is not 0: now
- this effect is not necessary if the instrument's duty macro is absolute.
- `1Exy`: change additional parameters.
- `x` may be one of the following:
- `0`: attack (`y` from 0 to F)
- `1`: decay (`y` from 0 to F)
- `2`: sustain (`y` from 0 to F)
- `3`: release (`y` from 0 to F)
- `4`: ring modulation (`y` is 0 or 1)
- `5`: oscillator sync (`y` is 0 or 1)
- `6`: disable channel 3 (`y` is 0 or 1)
- `3xxx`: set duty cycle. `xxx` range is 000-FFF
- `4xxx`: set cutoff. `xxx` range is 000-7FF.

18
papers/doc/7-systems/game-boy.md Normal file
View File

@ -0,0 +1,18 @@
# Game Boy
the Nintendo Game Boy is one of the most successful portable game systems ever made.
with stereo sound, two pulse channels, a wave channel and a noise one it packed some serious punch.
# effects
- `10xx`: change wave.
- `11xx`: set noise length. `xx` may be one of:
- 0: long
- 1: short
- `12xx`: set duty cycle (from 0 to 3).
- `13xy`: setup sweep (pulse channels only).
- `x` is the time.
- `y` is the shift.
- set to 0 to disable it.
- `14xx`: set sweep direction. 0 is up and 1 is down.

36
papers/doc/7-systems/genesis.md Normal file
View File

@ -0,0 +1,36 @@
# Sega Genesis/Mega Drive
a video game console that showed itself as the first true rival to Nintendo's video game market near-monopoly in the US during the '80's.
this console is powered by two sound chips: the Yamaha YM2612 and a derivative of the SN76489.
# effects
- `10xy`: set LFO parameters.
- `x` toggles the LFO.
- `y` sets its speed.
- `11xx`: set feedback of channel.
- `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 mutliplier.
- `17xx`: enable PCM channel.
- this only works on channel 6.
- `18xx`: toggle extended channel 3 mode.
- 0 disables it and 1 enables it.
- only in extended channel 3 platform.
- `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 PSG noise mode.
- `x` controls whether to inherit frequency from PSG channel 3.
- 0: use one of 3 preset frequencies (C: A-2; C#: A-3; D: A-4).
- 1: use frequency of PSG channel 3.
- `y` controls whether to select noise or thin pulse.
- 0: thin pulse.
- 1: noise.

10
papers/doc/7-systems/nes.md Normal file
View File

@ -0,0 +1,10 @@
# NES
the console from Nintendo that plays Super Mario Bros. and helped revive the agonizing video game market in the US during mid-80s.
also known as Famicom.
# effects
- `12xx`: set duty cycle or noise mode of channel.
- may be 0-3 for the pulse channels and 0-1 for the noise channel.

19
papers/doc/7-systems/pce.md Normal file
View File

@ -0,0 +1,19 @@
# PC Engine/TurboGrafx-16
a console from NEC that attempted to enter the fierce battle between Nintendo and Sega, but because its capabilities are a mix of third and fourth generation, it failed to last long.
it has 6 wavetable channels and the last two ones also double as noise channels.
furthermore, it has some PCM!
# effects
- `10xx`: change wave.
- `11xx`: toggle noise mode. only available in the last two channels.
- `12xx`: setup LFO. the following values are accepted:
- `00`: LFO disabled.
- `01`: LFO enabled, shift 0.
- `02`: LFO enabled, shift 4.
- `03`: LFO enabled, shift 8.
- when LFO is enabled, channel 2 is muted and its output is passed to channel 1's frequency.
- `13xx`: set LFO speed.
- `17xx`: toggle PCM mode.

27
papers/doc/7-systems/saa1099.md Normal file
View File

@ -0,0 +1,27 @@
# Philips SAA1099
this was used by the Game Blaster and SAM Coupé. it's pretty similar to the AY-3-8910, but has stereo sound, twice the channels and two envelopes, both of which are highly flexible.
# effects
- `10xy`: set channel mode.
- `x` toggles noise.
- `y` toggles square.
- this effect affects either the first 3 or last 3 channels, depending on where it is placed.
- `11xx`: set noise frequency.
- this effect affects either the first 3 or last 3 channels, depending on where it is placed.
- `12xx`: setup envelope. this is a bitmask.
- bit 7 toggles the envelope.
- bit 5 toggles whether to use a fixed frequency or lock to the frequency of channel 2 or 5.
- bit 4 sets the envelope resolution.
- bits 1 to 3 set the envelope shape:
- `000`: always off
- `001`: always on
- `010`: down
- `011`: down loop (saw)
- `100`: up down
- `101`: up down loop (triangle)
- `110`: up then off
- `111`: up loop (reverse saw)
- bit 0 sets whether the right output will mirror the left one.
- this effect affects either the first 3 or last 3 channels, depending on where it is placed.

17
papers/doc/7-systems/sms.md Normal file
View File

@ -0,0 +1,17 @@
# Sega Master System
the predecessor to Genesis.
surely had better graphics than NES, but its sound is subject of several jokes.
this console is powered by a derivative of the Texas Instruments SN76489.
# effects
- `20xy`: set noise mode.
- `x` controls whether to inherit frequency from hannel 3.
- 0: use one of 3 preset frequencies (C: A-2; C#: A-3; D: A-4).
- 1: use frequency of channel 3.
- `y` controls whether to select noise or thin pulse.
- 0: thin pulse.
- 1: noise.

12
papers/doc/7-systems/tia.md Normal file
View File

@ -0,0 +1,12 @@
# Atari 2600 (TIA)
help me! I can't even get this character in where I want!
I've spent hours debugging the issue, counting every possible cycle and I still cannot get it right!
only 2 channels and 31 frequencies?!
Furnace isn't complete without this one...
# effects
none. we don't need no freakin' effects.

26
papers/doc/7-systems/ym2151.md Normal file
View File

@ -0,0 +1,26 @@
# Yamaha YM2151
the sound chip powering the Arcade platform, available for standalone use if you want to make X68000 music or pair it with a 16-channel Sega PCM when it comes.
# effects
- `10xx`: set noise frequency of channel 8 operator 4. 00 disables noise while 01 to 20 enables it.
- `11xx`: set feedback of channel.
- `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 mutliplier.
- `17xx`: set LFO speed.
- `18xx`: set LFO waveform. `xx` may be one of the following:
- `00`: saw
- `01`: square
- `02`: triangle
- `03`: noise
- `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.

54
papers/doc/7-systems/ym2610.md Normal file
View File

@ -0,0 +1,54 @@
# Neo Geo/Yamaha YM2610
originally an arcade board, but SNK shortly adapted it to a rather expensive video game console with the world's biggest cartridges because some people liked the system so much they wanted a home version of it.
its soundchip is a 3-in-1: FM, YM2149 (AY-3-8910 clone) and ADPCM in a single package!
# effects
- `10xy`: set LFO parameters.
- `x` toggles the LFO.
- `y` sets its speed.
- `11xx`: set feedback of channel.
- `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 mutliplier.
- `18xx`: toggle extended channel 2 mode.
- 0 disables it and 1 enables it.
- only in extended channel 2 platform.
- `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.
- `20xx`: set SSG channel mode. `xx` may be one of the following:
- `00`: square
- `01`: noise
- `02`: square and noise
- `03`: envelope
- `04`: envelope and square
- `05`: envelope and noise
- `06`: envelope and square and noise
- `07`: nothing
- `21xx`: set noise frequency. `xx` is a value between 00 and 1F.
- `22xy`: set envelope mode.
- `x` sets the envelope shape, which may be one of the following:
- `0: \___` decay
- `4: /___` attack once
- `8: \\\\` saw
- `9: \___` decay
- `A: \/\/` inverse obelisco
- `B: \¯¯¯` decay once
- `C: ////` inverse saw
- `D: /¯¯¯` attack
- `E: /\/\` obelisco
- `F: /___` attack once
- if `y` is 1 then the envelope will affect this channel.
- `23xx`: set envelope period low byte.
- `24xx`: set envelope period high byte.
- `25xx`: slide envelope period up.
- `26xx`: slide envelope period down.

27
papers/doc/7-systems/ym2612.md Normal file
View File

@ -0,0 +1,27 @@
# Yamaha YM2612
one of two chips that powered the Sega Genesis.
# effects
- `10xy`: set LFO parameters.
- `x` toggles the LFO.
- `y` sets its speed.
- `11xx`: set feedback of channel.
- `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 mutliplier.
- `17xx`: enable PCM channel.
- this only works on channel 6.
- `18xx`: toggle extended channel 3 mode.
- 0 disables it and 1 enables it.
- only in extended channel 3 platform.
- `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.

16
papers/doc/7-systems/ymu759.md Normal file
View File

@ -0,0 +1,16 @@
# Yamaha YMU759
the Yamaha YMU759 is a sound chip designed for feature phones during the early 2000s.
it is also known as MA-2.
sadly Yamaha didn't care about these chips too much, and the register specs were completely unavailable, which means the YMU759 is totally unsupported and unemulated besides Yamaha's official emulator for it built into MidRadio.
hence Furnace does not emulate the chip (and doesn't even let you add it to a song).
# effects
since this chip is so abandoned, there isn't any support for it.
even DefleMask dropped support for the chip in version 0.11, which just shows how poorly the chip has been treated, both by Yamaha themselves and the community.
hey, at least it was the spark that ignited the idea of DefleMask.

10
papers/doc/README.md
View File

@ -1,3 +1,11 @@
# Furnace user manual
TOOOODOOOOOOOO
this documentation is a work in progress! expect several sections to be incomplete.
1. [introduction](1-intro/README.md)
2. [interface](2-interface/README.md)
3. [patterns](3-pattern/README.md)
4. [instruments](4-instrument/README.md)
5. [wavetables](5-wave/README.md)
6. [samples](6-sample/README.md)
7. [list of systems/platforms](7-systems/README.md)