Add a READMEv1.3

1 files changed, 119 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..77c0720
--- /dev/null
+++ b/README.md
@@ -0,0 +1,119 @@
+# README
+
+[STEPPER][stepper-itch] is a 16-step sequencer for the Game Boy Advance (GBA).
+
+It features an intuitive workflow inspired by [Elektron instruments][elektron]
+with per-trigger parametrization that allows access to the 4 DMG sound channels
+in the console (2 square waves channels, 1 custom wave channel and 1 noise
+channel). Supports 4 banks of 8 patterns that can be queued for live
+performance.
+
+### Controls
+
+- D-Pad: Moves the cursor.
+- Start: Start/Stop the sequence.
+- Select: Context dependent mod key. Used for:
+    - Quick saving the current bank.
+    - Copy pasting.
+    - Adjusting notes by octaves.
+    - Adjusting bpm by multiples of 10.
+- B: Toggles channels/triggers and play/pause/stop, switches banks and patterns.
+- A: Hold it to adjust trigger parameters.
+- L/R: Change trigger notes, parameter values, or BPM.
+
+### Save/Load
+
+STEPPER supports up to 4 banks of 8 patterns each. The current bank is saved by
+switching banks or selecting the current one in the bank section. The banks are
+saved to the SRAM and upon launching STEPPER the last saved state will be
+loaded. Use "Select + Start" to quick save the current bank.
+
+### Patterns
+
+Patterns can be changed or edited by navigating to the left column with the
+cursor. Pressing the B button will queue a pattern to run on the next cycle. The
+queued pattern will be highlighted in blue. Only on pattern can be chained at
+the moment.
+
+We can edit different patterns other than the one that is currently playing. The
+pattern we are currently editing is represented by a grey/blue cursor whilst the
+one in play is highlighted in white.
+
+Each pattern stores information about active channels and their trigger notes
+and parameters. BPM can also be stored independently for each pattern.
+
+### Note selection
+
+Notes can be changed by pressing "L" or "R" over an active trigger. If the
+cursor is on the channel selection mode, "L" and "R" will transpose all trigger
+notes instead. Holding "Select" while adjusting notes will make it jump by an
+octave instead of a semitone.
+
+### Parameters
+
+Channels 1 and 2 allow us to control the square wave duty cycle and envelope
+(Initial volume, direction and time). Additionally, channel 1 can access the
+"sweep" parameters, which when the time is not zero allows for some interesting
+FX.
+
+Channel 3 is the wave channel. In this channel we have access to 2 programmable
+waves that can be edited manually or selected with 4 available presets (sine,
+saw, square, random). The waves can be played independently (mode A or B) or one
+after another (Mode A + B). This channel has no volume envelope thus a note will
+keep playing until it encounters an active trigger with zero volume or
+a different pitch.
+
+Channel 4 is the noise channel, mostly used for percussive effects. It uses an
+envelope to shape the sound and has two modes of operation. Mode A is more
+rounder and mode B sounds more metallic.
+
+Adjust the parameters by holding "A" hovering over a trig. Parameters are stored
+per trigger and adjusted individually for each of them. If the cursor is on
+channel selection mode, when adjusting the channel parameters these will be
+copied to all 16 triggers. Note that this global adjustment is not stored when
+saving banks and patterns. The grey color on the global adjustment helps
+differentiate between trigs and channel parameters. A compatible trig/parameter
+can be pasted into a channel to apply it to all triggers.
+
+### Copy/Paste
+
+The GBA has a limited set of controls but using STEPPER's contextual clipboard
+we can greatly speedup the editing workflow. We can use "Select + B" (Copy) or
+"Select + A" (Paste) to perform clipboard operations.
+
+If the cursor is selecting a pattern, the entire pattern will be copied,
+including active channels, triggers and parameters. Patterns can only be pasted
+in other patterns.
+
+Channels can be copied to other patterns or channels. If the paste destination
+is a channel other than the original one, only the notes and active triggers
+will be copied. If the channel is of the same type, all the parameters will also
+carry over.
+
+Copying a trigger transfer its pitch (note), active state (on/off) and its
+parameter settings (Assuming the target is compatible, as explained above). If
+we only want to copy the parameters, hold "A" to enter parameter select mode and
+press "Select" to copy them. Now you can paste them to any compatible trigger.
+
+Note that the clipboard doesn't currently transfer between banks due to the
+platform's limitations.
+
+### Using other gear and synchronization
+
+Currently STEPPER has no MIDI sync but I've began research on implementing CV
+gate out using the GBA's link cable. No ETA for this, since I'm missing a few
+things to test my theories in hardware, but I'll keep you all posted. In the
+future something like [ArduinoBoy][arduboy] could be implemented to provide this
+functionality, but in the meantime STEPPER can work with other gear by manually
+timing the playing head using a click/metronome or sampling patterns from
+STEPPER to later arrange it into a full song in your DAW or sampler of choice.
+The latter is my preferred approach.
+
+Keep in mind that the BPM reported by STEPPER can be a bit off since it uses
+whole integer values for timing adjustments, meaning that you may need to set up
+your DAW/sampler to a fractional BPM value or use time stretching to get the
+loops perfectly in time (For example 107 BPM in STEPPER and 107.6 on your DAW).
+
+[arduboy]: https://github.com/trash80/Arduinoboy
+[stepper-itch]: https://badd10de.itch.io/stepper-gba
+[elektron]: https://www.elektron.se/en