README.md

   1 Arpeggigon
   2 ===
   3
   4 The arpeggigon is a music instrument inspired by Mark
   5 Burton's [reacTogon][].
   6
   7 It is written in Haskell using the FRP
   8 library [Yampa](http://hackage.haskell.org/package/Yampa-0.10.4) for
   9 the music
  10 generation, [Gtk2Hs](https://hackage.haskell.org/package/gtk-0.14.5)
  11 for the Graphical User Interface (GUI)
  12 and [jack](http://hackage.haskell.org/package/jack-0.7.1) for handling
  13 MIDI I/O. The code to interface with the exterior world is structured
  14 using reactive values and relations
  15 (see
  16 [this paper](http://www.cs.nott.ac.uk/~psxip1/papers/2015-HaskellSymposium-Perez-Nilsson-BridingGUIGapReactiveValues.pdf) and
  17 the
  18 libraries
  19 [here](https://hackage.haskell.org/package/keera-hails-reactivevalues-0.2.2.0) and
  20 [here](https://hackage.haskell.org/package/keera-hails-reactive-gtk-0.3)).
  21
  22 Install guide
  23 ---
  24
  25 The arpeggigon needs the [GTK+ 2.0 C API](http://www.gtk.org/) and
  26 the [JACK C API](http://jackaudio.org/) to be built. It is known to
  27 work with GHC 7.10.3 and GHC 8.0.1.
  28
  29 Running the arpeggigon is then possible with:
  30
  31         cabal sandbox init
  32         cabal install --only-dependencies
  33     cabal run arpeggigon
  34
  35 To install the arpeggigon globally, one can call:
  36
  37         cabal install
  38
  39 This will create an executable located in
  40 `<path_to_repo>/.cabal-sandbox/bin/` from where it is possible to create a
  41 symbolic link to an object in the `PATH`.
  42
  43         ln -s <path_to_repo>/.cabal-sandbox/bin/arpeggigon <somewhere_in_PATH>/arpeggigon
  44
  45 Description
  46 ---
  47
  48 ### The reacTogon
  49
  50 The [reacTogon][] is a musical instrument invented based upon
  51 the
  52 [harmonic table](https://en.wikipedia.org/wiki/Harmonic_table_note_layout),
  53 a way of arranging notes where the various directions correspond to
  54 meaningful musical intervals. From that layout, the reacTogon defines
  55 an automaton: tokens of different kinds interact with *play heads*
  56 moving around on the board, altering their directions and eventually
  57 playing a note.
  58
  59 The arpeggigon is an extended reacTogon. It is for instance possible
  60 to have multiple layers with different characteristics running in
  61 parallel, or to modify the way individual notes should be played, etc.
  62
  63 ### Music generation
  64
  65 The arpeggigon doesn't directly produce music, but is
  66 a
  67 [MIDI](https://en.wikipedia.org/wiki/MIDI) [JACK](http://jackaudio.org/) client. It
  68 then requires a JACK server to run when it is launched and to be
  69 connected to a MIDI synthetizer to produce music.
  70
  71 ### Tokens
  72
  73 There are five kinds of tokens currently supported, that appear in the
  74 following order in the arpeggigon's GUI:
  75 * ricochet token: plays a note and reorients the play head toward the
  76   direction it's pointing to,
  77 * start token: like the ricochet token but generated an impulsion when
  78   the machine starts,
  79 * stop token: plays a note and makes the play head disappear,
  80 * absorb token: like the stop token but doesn't play any note,
  81 * split token: splits the impulsion into five.
  82
  83 ### Multiple layers
  84
  85 It is possible to have multiple layers running in parallel, each one
  86 having it's own control settings. Adjustable parameters include:
  87 * the layer beat,
  88 * the strength at which notes should be played,
  89 * the volume,
  90 * the instrument,
  91 * the beats per bar for the given layer,
  92 * the possibility to make the layer restart automatically after a
  93   certain number of bars, specifying if the layer should completly
  94   restart or not.
  95
  96 ### Note attributes
  97
  98 Each tile, whether it's inhabited by a token or note is attributed a
  99 repeat counter, telling how long a play head should stay on it.
 100
 101 For tiles inhabited by a token giving the possibility of a note being
 102 played, it is possible to adjust some parameters, including:
 103 * the note duration,
 104 * an articulation, allowing the note to be played stronger depending
 105   on its position in the bar,
 106
 107 **Warning:** *Though it appears a slide can be specified, it is for
 108 now a missing feature.*
 109
 110 ### Button semantics
 111
 112 The start/restart button has a particular semantic. Pressing the start
 113 button makes the machine start and turns the button into a restart
 114 button. When pressed it will restart all the layers but take into
 115 account the layer restart policy to know if it should completely
 116 restart the layer or simply add the start heads to the already running
 117 ones.
 118
 119 The stop button simply stops all the layers.
 120
 121 ### Missing features
 122
 123 This lists the buttons that have no effect but are yet present at the
 124 moment in the GUI. This features are being worked on in priority.
 125 * Recording a performance is not yet possible.
 126 * Configuration saving and loading is unavailable.
 127 * Slides are not implemented.
 128 * Tabs are not really named.
 129
 130 ### Future features
 131
 132 This lists the features that would be nice to add to the arpeggigon at
 133 some point:
 134 * a nicer GUI, with the possibility to display note names on the
 135   board, and see which note is being focused on.
 136 * a new “random split token”, that would redirect a play head in a
 137   random direction, or more generally split it in a random way.
 138 * an ALSA backend for Linux.
 139
 140 [reacTogon]:https://www.youtube.com/watch?v=AklKy2NDpqs
 141
 142 Copyright and license
 143 ---
 144
 145 Copyright 2016, Guerric Chupin and Henrik Nilsson.
 146
 147 The arpeggigon is licensed under the BSD 3-Clause License. A copy of
 148 the license is included in the [LICENSE](LICENSE) file.