SPEC.md

   1 Reactogon Design
   2 ================
   3
   4 2016-05-18: INCOMPLETE, but should give an idea. Refine/structure better
   5 as see fit.
   6
   7 Target levels
   8 -------------
   9 - [ ] Baseline: text interface only, not necessarily (very) interactive,
  10       but at the very least able to record a performance as a MIDI file.
  11 - [ ] Basic system with a GUI running on a Linux desktop. At least able
  12       to generate sound
  13 - [ ] Full-featured system with GUI running on a Linux desktop.
  14 - [ ] Mobile version, subject to cooperation with Ivan/Keera Studios
  15
  16 Feature Summary
  17 ---------------
  18
  19 * Modelled after the original Reactogon
  20 * Up to 16 layers. Each layer an extended version of the original Reactogon.
  21   Extensions include:
  22   - Each tile has an associated "repeat count" n. The play head stays
  23     on the title for n clock ticks, repeating any basic action for
  24     each tick, before moving on (possibly in new direction).
  25     Specifically, this means that n = 1 is the normal behaviour and
  26     n = 0 means the play head moves on immediately without performing any
  27     action.
  28   - User-defined "groove" per layer. E.g. every other beat can be delayed for
  29     a swing feel.
  30   - Accented (more strongly played) notes.
  31   - Slide (kind of slide *could* even depend on direction of the play head!)
  32     (not going to work well for polymorphic layers probably. But the MIDI
  33     translator could simply ignore slide messages until the current one is
  34     done. Then everything OK as long as no overlapping slides.)
  35   - MIDI CC/program change can be sent for a note
  36   - Two tempo-synched LFOs per layer
  37   - Bank and Program
  38   - Volume slider
  39   - Pan pot
  40   - Layer transposition
  41   - A layer can be set to be unpitched: the pitch of all output notes
  42     are set to a specific pitch (useful for e.g. rythm layers).
  43   - Muting and Soloing of layers
  44 * MIDI integration
  45   - synchronization to external MIDI clock if selected and available
  46   - start, stop, continue: send and receive
  47   - each layer transposed in response to note on message on designated channel
  48   - designated MIDI channel for each layer for output:
  49     + note on/off
  50     + program change
  51     + volume
  52     + pan
  53     + mapping of LFOs to specific MIDI CC (including volume or pan which
  54       overrides the static values).
  55     + pitch bend
  56 * Dynamic addition/deletion of layers(?) Or simply a fixed number of layers?
  57 * Overall control/performance tab. For ecach layer:
  58   - Volume
  59   - Pan
  60   - Mute (inhibits all MIDI out messages, but layer continues to run)
  61   - Solo (messages from all other layers inhibited, but mute status
  62     preserved; only one layer at a time can be soloed)
  63   These controls duplicated on each layer
  64 * Saving & loading of configurations
  65 * Loading of individual layers from stored configurations.
  66 * Directly recolrding to/generating a MIDI file. Record button?
  67
  68 Clocking
  69 --------
  70 The system beat, relative to which the overall tempo is given (in BPM)
  71 is defined to be one quarter note.
  72
  73 The layer beats is specified separately but defaults to one quarter note.
  74
  75 A beats per par is also specified per layer. Together with the layer beat
  76 this gives the time signature (of sorts) for a layer.
  77
  78 The system tempo is either set internally, in BPM, or synched to an external
  79 MIDI clock.
  80
  81 Sufficiently flexible swing could be specified per layer by specifying
  82 how much earlier or later beats 2, 3 and 4 should be relative to a straight
  83 beat, i.e. three numbers between say -90% and 90%. A standard swing
  84 beat would thus be given by 50, 0 50.
  85
  86 Only beat numbers as defined by the layer's beats per bar would be used,
  87 and beat numbers beyond 4 would be played straight.
  88
  89 Or one might want to allow the number of numbers to be beats per bar minus 1.
  90
  91 Overall Structure
  92 -----------------
  93                               ------------------
  94                               |                |
  95                 Model <----> GUI <-----        |
  96                    |                  |        |
  97                    |--> Global-+----->|        |
  98                    |           V      |        V
  99                    +------> Layers -----> MIDI translator ---> MIDI Synth
 100                    |
 101     MIDI keyboard --
 102                    |
 103     (MIDI clock) ---
 104
 105 Gloal, Layers, and MIDI translator are all FRP (Yampa) moduled.
 106
 107   * Global (better name needed!) takes care of system-wide signal
 108     processing, e.g. definition of the system clock, run/stop logic?
 109
 110   * Each Layer is a Reactogon. The core semantics is defined in
 111     BasicSemantics. The intention is to lift (most of) this into
 112     an event-processing signal fnction using "accumBy". Additional
 113     signal functions per layer would be needed to define the
 114     layer clock, layer LFOs, and maybe more.
 115
 116   * The MIDI translator is responsible for translating the collective
 117     output from the layers (high-level MIDI notes, LFO output) into
 118     low level MIDI events. This involves things like ensuring that a
 119     note off event is scheduled for every note on event at the appropriate
 120     time, translating and realising continuous control signals
 121     (from LFOs, slide ornaments) into discrete MIDI messages,
 122     and merging it all into a single sequence of events, taking the
 123     limited capacity of a standard MIDI connection into account
 124     (more corse grained translation of continous control signals
 125     if too busy? dropping notes in case of excessive polyphony per
 126     channel and/or overall?)
 127
 128   * The GUI manipulates a model of the system tailored to the needs of the
 129     GUI. Control signals are derived from this for Global and each
 130     layer (e.g. the configuration of a board, the board transposition).
 131
 132     The GUI also needs to observe the output from Global and Layers
 133     to animate layers as the play heads move around and to display
 134     the system tempo in case this is derived from external MIDI clock.
 135
 136     The GUI also needs to talk to the MIDI translator to send e.g.
 137     configured prgram change, bank, volume and pan messages for each
 138     layer whenever the Reactogon is started.
 139
 140     Muting of layers could also be achived this way by instructing
 141     the translator to temporarily stop listening to a muted layer.
 142     (Muted layers would still run and be animated.)