diff --git a/doc/1-intro/README.md b/doc/1-intro/README.md index c21ad355b..34658ece3 100644 --- a/doc/1-intro/README.md +++ b/doc/1-intro/README.md @@ -12,7 +12,7 @@ Furnace uses hexadecimal (abbreviated as "hex") numbers frequently. see [this gu ## interface -Furnace uses a music tracker interface. think of a table with music notes written on it. then that table scrolls up and plays the notes. +Furnace uses a music tracker interface. think of a table with music notes written on it. then that table scrolls up and plays the notes. even experienced tracker musicians might benefit from a quick review of [tracker concepts and terms](concepts.md) before using Furnace. due to its nature of being feature-packed, it may be technical and somewhat difficult to get around. therefore we added a basic mode, which hides several advanced features. diff --git a/doc/1-intro/concepts.md b/doc/1-intro/concepts.md new file mode 100644 index 000000000..cee6e9adf --- /dev/null +++ b/doc/1-intro/concepts.md @@ -0,0 +1,36 @@ +# concepts and terms + +- A **module** is a file for a tracker that contains at least one **song**. +- Each Furnace module involves at least one **[chip](../7-systems/README.md)**, an emulation of a specific audio processor. + +## tracking + +The **[pattern view](../3-pattern/README.md)** is like a spreadsheet that displays the following: +- Each labeled column represents a **channel** of sound provided by the chips in use. +- Each **note** starts a sound playing. Within a channel, only one note can play at a time. +- Each note is assigned an **[instrument](../4-instrument/README.md)** which describes what it will sound like. +- An **effect** is a command that changes some aspect of playback. It can alter note pitch, volume, timing, and more. +- An instrument **macro** is an automated sequence of effects that applies to every note of that instrument. + +## structure + +The **order list** is a smaller spreadsheet showing the overall song structure. +- A song is made up of a list of **orders**. +- An **order** is a set of numbered **patterns** used for each channel. +- Each channel has its own unique list of patterns. +- Each pattern contains note and effect data for that channel only. +- Patterns may be used multiple times in the order list. Changing a pattern's data in one order will affect the same pattern used in other orders. + +## time + +- Each pattern is made of the same number of **rows** as seen in the tracker view. +- During playback, Each row lasts a number of **ticks** determined by its **speed** value. +- A tick is the smallest measure of time to which all note, effect, and macro times are quantized. + +## sound + +Different chips have different capabilities. Even within the same chip, each channel may have its own ways of making sound. +- Some channels use one or more waveform **generators** (sine, square, noise...) to build up a sound. +- Of special note are **[FM (frequency modulation)](../4-instrument/fm.md)** channels, which use a number of generators called **operators** that can interact to make very complex sounds. +- Some channels use **[samples](../6-sample/README.md)** – recordings of sounds, often with defined loop points to allow a note to sustain. +- Some channels use **[wavetables](../5-wave/README.md)**, which are like very short samples of fixed length that automatically loop. \ No newline at end of file diff --git a/doc/3-pattern/effects.md b/doc/3-pattern/effects.md index c7a54fd49..518e7abff 100644 --- a/doc/3-pattern/effects.md +++ b/doc/3-pattern/effects.md @@ -1,78 +1,97 @@ # effect list -most of the effect numbers are from ProTracker/FastTracker 2. -however, effects are continuous, which means you only need to type it once and then stop it with an effect value of `00`. +Most of the effect numbers are from ProTracker / FastTracker 2. -- **`00xy`**: arpeggio. after using this effect the channel will rapidly switch between `note`, `note+x` and `note+y`. -- **`01xx`**: slide up. -- **`02xx`**: slide down. -- **`03xx`**: note portamento. - - a note must be present for this effect to work. -- **`04xy`**: vibrato. `x` is the speed, while `y` is the depth. - - maximum vibrato depth is ±1 semitone. -- **`07xy`**: tremolo. `x` is the speed, while `y` is the depth. - - maximum tremolo depth is -60 volume steps. -- **`08xy`**: set panning. `x` is the left channel and `y` is the right one. - - not all chips support this effect. -- **`80xx`**: set panning (linear). this effect behaves more like other trackers: +However, effects are continuous, which means you only need to type it once and then stop it with an effect value of `00` or no effect value at all. + +## volume + +- `0Axy`: **Volume slide.** + - If `x` is 0 then this is a slide down. + - If `y` is 0 then this is a slide up. +- `F8xx`: **Single tick volume slide up.** +- `F9xx`: **Single tick volume slide down.** +- `F3xx`: **Fine volume slide up.** 64× slower than `0Axy`. +- `F4xx`: **Fine volume slide down.** 64x slower than `0Axy`. +- `FAxy`: **Fast volume slide.** 4× faster than `0Axy`. + - If `x` is 0 then this is a slide down. + - If `y` is 0 then this is a slide up. + +- `07xy`: **Tremolo.** Changes volume to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth. + - Maximum tremolo depth is -60 volume steps. + +## pitch + +- `E5xx`: **Set pitch.** `00 is -1 semitone, `80` is base pitch, `FF` is nearly +1 semitone. +- `01xx`: **Pitch slide up.** +- `02xx`: **Pitch slide down.** +- `F1xx`: **Single tick pitch slide up.** +- `F2xx`: **Single tick pitch slide down.** + +- `03xx`: **Portamento.** Slides the current note's pitch to the specified note. + - A note _must_ be present for this effect to work. +- `E1xy`: **Note slide up.** `x` is the speed, while `y` is how many semitones to slide up. +- `E2xy`: **Note slide down.** `x` is the speed, while `y` is how many semitones to slide down. +- `EAxx`: **Toggle legato.** While on, notes instantly change the pitch of the currrently playing sound instead of starting it over. +- `00xy`: **Arpeggio.** After using this effect the channel will rapidly switch between semitone values of `note`, `note + x` and `note + y`. +- `E0xx`: **Set arpeggio speed.** This sets the number of ticks between arpeggio values. + +- `04xy`: **Vibrato.** Changes pitch to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth. + - Maximum vibrato depth is ±1 semitone. +- `E3xx`: **Set vibrato direction.** `xx` may be one of the following: + - `00`: Up and down. + - `01`: Up only. + - `02`: Down only. +- `E4xx`: **Set vibrato range** in 1/16th of a semitone. + +## panning + +Not all chips support these effects. + +- `08xy`: **Set panning.** Changes stereo volumes independently. `x` is the left channel and `y` is the right one. +- `88xy`: **Set rear panning.** Changes rear channel volumes independently. `x` is the rear left channel and `y` is the rear right one. + +- `80xx`: **Set panning (linear).** This effect behaves more like other trackers: - `00` is left. - `80` is center. - `FF` is right. - - not all chips support this effect. -- **`81xx`**: set volume of left channel (from `00` to `FF`). - - not all chips support this effect. -- **`82xx`**: set volume of right channel (from `00` to `FF`). - - not all chips support this effect. -- **`09xx`**: set speed 1. -- **`0Axy`**: volume slide. - - if `x` is 0 then this is a slide down. - - if `y` is 0 then this is a slide up. -- **`0Bxx`**: jump to pattern. -- **`0Cxx`**: retrigger note every `xx` ticks. - - this effect is not continuous. -- **`0Dxx`**: jump to next pattern. -- **`0Fxx`**: set speed 2. +- `81xx`: **Set volume of left channel** (from `00` to `FF`). +- `82xx`: **Set volume of right channel** (from `00` to `FF`). +- `89xx`: **Set volume of rear left channel** (from `00` to `FF`). +- `8Axx`: **Set volume of rear right channel** (from `00` to `FF`). -- **`9xxx`**: set sample position to `xxx`\*0x100. - - not all chips support this effect. +## time -- **`Cxxx`**: change song Hz. +- `09xx`: **Set speed/groove.** If no grooves are defined, this sets speed. If alternating speeds are active, this sets the first speed. +- `0Fxx`: **Set speed 2.** During alternating speeds or a groove, this sets the second speed. + +- `Cxxx`: **Set tick rate.** Changes tick rate to `xxx` Hz (ticks per second). - `xxx` may be from `000` to `3ff`. +- `F0xx`: **Set BPM.** Changes tick rate according to beats per minute. -- **`E0xx`**: set arpeggio tick. - - this sets the number of ticks between arpeggio values. -- **`E1xy`**: note slide up. `x` is the speed, while `y` is how many semitones to slide up. -- **`E2xy`**: note slide down. `x` is the speed, while `y` is how many semitones to slide down. -- **`E3xx`**: set vibrato direction. `xx` may be one of the following: - - `00`: up and down. - - `01`: up only. - - `02`: down only. -- **`E4xx`**: set vibrato range in 1/16th of a semitone. -- **`E5xx`**: set pitch. `80` is 0 cents. - - range is ±1 semitone. -- **`EAxx`**: toggle legato. -- **`EBxx`**: set sample bank. - - does not apply on Amiga. -- **`ECxx`**: note off after `xx` ticks. -- **`EDxx`**: delay note by `xx` ticks. -- **`EExx`**: send external command. - - this effect is currently incomplete. -- **`F0xx`**: change song Hz by BPM value. -- **`F1xx`**: single tick slide up. -- **`F2xx`**: single tick slide down. -- **`F3xx`**: fine volume slide up (64x slower than `0Axy`). -- **`F4xx`**: fine volume slide down (64x slower than `0Axy`). -- **`F5xx`**: disable macro. - - see macro table at the end of this document for possible values. -- **`F6xx`**: enable macro. -- **`F8xx`**: single tick volume slide up. -- **`F9xx`**: single tick volume slide down. -- **`FAxy`**: fast volume slide (4x faster than `0Axy`). - - if `x` is 0 then this is a slide down. - - if `y` is 0 then this is a slide up. -- **`FFxx`**: end of song/stop playback. +- `0Bxx`: **Jump to order.** This can be used to loop a song. +- `0Dxx`: **Jump to next pattern.** This can be used to shorten the current order. +- `FFxx`: **Stop song.** Stops playback and ends the song. -additionally each chip has its own effects. [click here for more details](../7-systems/README.md). +## note + +- `0Cxx`: **Retrigger.** Repeats current note every `xx` ticks. + - This effect is not continuous; it must be entered on every row. +- `ECxx`: **Note cut.** Ends current note after `xx` ticks. For FM instruments, it's equivalent to a "key off". +- `EDxx`: **Note delay.** Delays note by `x` ticks. + +## other + +- `9xxx`: **Set sample position.** Jumps current sample to position `xxx \* 0x100`. + - Not all chips support this effect. +- `EBxx`: **Set sample bank.** + - Does not apply on Amiga. +- `EExx`: **Send external command.** + - This effect is currently incomplete. +- `F5xx`: **Disable macro.** See macro table at the end of this document for possible values. +- `F6xx`: **Enable macro.** + +Additionally, [each chip has its own effects](../7-systems/README.md). ## macro table @@ -98,8 +117,8 @@ ID | macro 11 | extra 6 12 | extra 7 13 | extra 8 ----|----------------------------- -20 | **operator 1 macros** - AM +| | **operator 1 macros** +20 | AM 21 | AR 22 | DR 23 | MULT @@ -119,10 +138,9 @@ ID | macro 31 | VIB 32 | WS 33 | KSR ----|----------------------------- -40 | operator 2 macros -60 | operator 3 macros -80 | operator 4 macros +40 | **operator 2 macros** +60 | **operator 3 macros** +80 | **operator 4 macros** the interpretation of duty, wave and extra macros depends on chip/instrument type: