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. Note that Gtk2Hs
  27 depends on external program such
  28 as [alex](http://hackage.haskell.org/package/alex)
  29 or [happy](http://hackage.haskell.org/package/happy). It is known to
  30 work with GHC 7.10.3 and GHC 8.0.1.
  31
  32 Running the arpeggigon is then possible with:
  33
  34         cabal sandbox init
  35         cabal install --only-dependencies
  36     cabal run arpeggigon
  37
  38 **WARNING:** to run, the Arpeggigon needs a running Jack server. If it cannot
  39 find one on startup it will crash. Experience has shown that it can be quite
  40 difficult to set up such a server, however there are good tools and tutorials
  41 online to help you with that task, in particular
  42 [qjackctl](https://qjackctl.sourceforge.io/) often does a good job at easing
  43 it.
  44
  45 **WARNING (bis):** as will be stated after, the Arpeggigon is a MIDI event
  46 producer, therefore it needs to be connected to a synthetizer to produce music.
  47 Again, [qjackctl](https://qjackctl.sourceforge.io/) makes this task quite easy,
  48 but it is also possible to do it via the command line.
  49
  50 Description
  51 ---
  52
  53 ### The reacTogon
  54
  55 The [reacTogon][] is a musical instrument invented based upon
  56 the
  57 [harmonic table](https://en.wikipedia.org/wiki/Harmonic_table_note_layout),
  58 a way of arranging notes where the various directions correspond to
  59 meaningful musical intervals. From that layout, the reacTogon defines
  60 an automaton: tokens of different kinds interact with *play heads*
  61 moving around on the board, altering their directions and eventually
  62 playing a note.
  63
  64 The arpeggigon is an extended reacTogon. It is for instance possible
  65 to have multiple layers with different characteristics running in
  66 parallel, or to modify the way individual notes should be played, etc.
  67
  68 ### Music generation
  69
  70 The arpeggigon doesn't directly produce music, but is
  71 a
  72 [MIDI](https://en.wikipedia.org/wiki/MIDI) [JACK](http://jackaudio.org/) client. It
  73 then requires a JACK server to run when it is launched and to be
  74 connected to a MIDI synthetizer to produce music.
  75
  76 ### Tokens
  77
  78 There are five kinds of tokens currently supported, that appear in the
  79 following order in the arpeggigon's GUI:
  80 * ricochet token: plays a note and reorients the play head toward the
  81   direction it's pointing to,
  82 * start token: like the ricochet token but generated an impulsion when
  83   the machine starts,
  84 * stop token: plays a note and makes the play head disappear,
  85 * absorb token: like the stop token but doesn't play any note,
  86 * split token: splits the impulsion into five.
  87
  88 ### Multiple layers
  89
  90 It is possible to have multiple layers running in parallel, each one
  91 having it's own control settings. Adjustable parameters include:
  92 * the layer beat,
  93 * the strength at which notes should be played,
  94 * the volume,
  95 * the instrument,
  96 * the beats per bar for the given layer,
  97 * the possibility to make the layer restart automatically after a
  98   certain number of bars, specifying if the layer should completly
  99   restart or not.
 100
 101 ### Note attributes
 102
 103 Each tile, whether it's inhabited by a token or note is attributed a
 104 repeat counter, telling how long a play head should stay on it.
 105
 106 For tiles inhabited by a token giving the possibility of a note being
 107 played, it is possible to adjust some parameters, including:
 108 * the note duration,
 109 * an articulation, allowing the note to be played stronger depending
 110   on its position in the bar,
 111
 112 **Warning:** *Though it appears a slide can be specified, it is for
 113 now a missing feature.*
 114
 115 ### Button semantics
 116
 117 The start/restart button has a particular semantic. Pressing the start
 118 button makes the machine start and turns the button into a restart
 119 button. When pressed it will restart all the layers but take into
 120 account the layer restart policy to know if it should completely
 121 restart the layer or simply add the start heads to the already running
 122 ones.
 123
 124 The stop button simply stops all the layers.
 125
 126 ### Missing features
 127
 128 This lists the buttons that have no effect but are yet present at the
 129 moment in the GUI. This features are being worked on in priority.
 130 * Recording a performance is not yet possible.
 131 * Configuration saving and loading is unavailable (soon to be fixed).
 132 * Slides are not implemented.
 133 * Tabs are not really named.
 134
 135 ### Future features
 136
 137 This lists the features that would be nice to add to the arpeggigon at
 138 some point:
 139 * a nicer GUI, with the possibility to display note names on the
 140   board, and see which note is being focused on.
 141 * a new “random split token”, that would redirect a play head in a
 142   random direction, or more generally split it in a random way.
 143 * an ALSA backend for Linux.
 144
 145 [reacTogon]:https://www.youtube.com/watch?v=AklKy2NDpqs
 146
 147 Copyright and license
 148 ---
 149
 150 Copyright 2016, Guerric Chupin and Henrik Nilsson.
 151
 152 The arpeggigon is licensed under the BSD 3-Clause License. A copy of
 153 the license is included in the [LICENSE](LICENSE) file.
 154
 155 Credits
 156 ---
 157
 158 We would like to thank the following people for their help, support
 159 and feedback on the arpeggigon:
 160 * Ivan Perez
 161 * Henning Thielemann
 162 * Michel Mauny
 163 * François Pessaux