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