Replace busy-wait with proper signal handling.
[quincer.git] / README
1 quincer
3 quincer will be a sequencer for live performance of composed works.
5 Features
6 ========
8 Currently implemented:
9 - Send events to multiple output ports
10 - Send MIDI control change events
11 - Per-pattern tempo setting
12 - Prefixes/suffixes
13 - Input files can include other input files
14 - Ticks-per-beat and beats-per-bar are not constrained
15   (though they must be constant within a pattern)
16 - can emit MIDI clock to drive external sequencers/effects
17 - MIDI clock specified at flexible multiples/divisions
18   of the JACK clock
19 - MIDI clock multiples/divisions are unique per output
20 - run looped or once through
21 - pure JACK (and is a timebase master)
23 Planned features, more imminent items first:
24 - Per-pattern swing setting
25 - Base tempo can be altered at runtime via MIDI CC
26 - Jump controls - use MIDI input to skip around (song mode)
27 - prefix/suffix events mask events from main pattern
29 Rationale
30 =========
32 I want a sequencer for live performance of songs that have been
33 previously composed, with the sequencing mostly fixed.
35 But at performance-time I want the ability to make small adjustments
36 to the song's form to, say, skip a verse or draw out a solo section or
37 delay a verse slightly because the drummer dropped a stick.  I want
38 the ability to decide to take the song a little faster or slower than
39 in rehearsal.
41 I want the ability to write a song in an unusual meter, with swing and
42 mid-song tempo changes.  The content of a song pattern should be
43 allowed to start before beat one of the first bar (e.g. pickups
44 (anacrusis), or drum fills, or cues on a cue track) and end after the
45 last beat of the last bar of the pattern.
47 For compose-time workflow, I want to support multiple use cases for a
48 song.  That is, I want to run a file that has a sequenced drum track,
49 or run a different file with a click track instead of drums and maybe
50 an extra verse.  Among these multiple files, content is re-used where
51 possible and files can be checked into source control.
53 Capturing live input is not important, nor is a graphical interface.
54 Session management isn't on the roadmap currently and probably won't
55 be.
57 I've taken inspiration from a few existing sequencers.  The sequencers
58 in some DAWs are very good for non-standard time signatures and swing
59 and tempo changes, but I'd never want the risk/overhead of using a DAW
60 on stage.  The sequencers that are currently for live use have
61 interesting control capabilities but focus on evolving looped beats in
62 an improvisatory way, a very specific use case that isn't needed for
63 all kinds of music.
65 These features aren't all implemented yet but I've got a solid start.
66 I hope you'll find quincer useful while it's in progress.
69 Input file syntax
70 =================
72 The quincer executable takes a single argument, a filename containing
73 the input.  I use files ending with '.qn' as a convention but the
74 program doesn't care.
76 An input file looks like this:
78 voice basskick sampson 1
79 voice rim sampson 1
80 voice rhykeys sampson 1
81 voice suskeys amsynth 1
82 voice reso amsynth 1
84 pattern 88 0
85 $ d2 127
86 f f 110
87 g g 110
88 k 90 80
89 j a4 80
90 b f# 70
91 l d 60
93 M a5 100
94 m a5 60
96 # Send program change (program 3) to rhykeys instrument
97 P pc 3
99 # Reso on the synth
100 r cc 74 0
101 R cc 74 127
103 0.....'.....'.....'.....|.....'.....'.....'.....
104 $         $-      f  g  |                         basskick
105                   k     |                         rim
106 P     |                                           rhykeys
107 M m m |                                           rhykeys
108 j---------              l---b-----              | suskeys
109 r                       R                       | reso
111 Time spec
112 ---------
113 Look at the final section first, since everything else leads up to
114 this.  There is a meter line "0.....'.....'.....'....." which defines
115 that a bar has four beats and a beat has six ticks.
117 The meter line must contain a 0 for the first tick. It is allowed to
118 contain bars if it's easier for human readers, the program doesn't
119 care as only the first beat after the 0 defines how many ticks are in
120 a beat. It follows from this that within a pattern the ticks-per-beat
121 and beats-per-bar are constant within a pattern.
123 The next lines after the meter line are voice lines, starting with
124 "$         $-      f  g  | basskick".  These show note events and give
125 the voice a name.  Note events can pretty much be any printable character,
126 except '-' which prolongs a note and '|' which is used to mark the end
127 of the events and the start of the voice name.
129 It is legal to give the same voice name to multiple lines.  This can
130 be used to send a block chord to a piano instrument, for example.
132 Notice that the voice lines have their ending '|' at different beats.
133 The length of the pattern is the length of the longest voice in it
134 ("suskeys" or "reso" in this example).  Patterns that are shorter are
135 looped.  It is undefined what happens if your shorter patterns aren't
136 exactly divisible into the longest one, so be sure you've got that
137 right.
139 Pattern declaration and event definitions
140 -----------------------------------------
141 Before that section the pattern is declared:
143 pattern 88 0
144 $ d2 127
145 f f 110
146 g g 110
147 k 90 80
150 This takes the form:
151 pattern <bpm> <swing>
152 <notechar> [cc|pc] <pitch> <velocity>
153 <notechar> [cc|pc] <pitch> <velocity>
156 Note that 'bpm' is declared for each pattern, which allows mid-song
157 tempo changes.
159 'swing' isn't implemented yet and may be omitted. 'notechar' can be
160 any printable character except - or | (for reasons explained above) or
161 # (comment delimiter).  Future releases will support other MIDI event
162 types such as pitch bend.
164 The pitch value may be entered a couple of different ways:
165 - midi pitch integer 0-127 (e.g. 80)
167 - named note, absolute (e.g. a4 or A4 f#2 or Bb3).  Case is ignored
168   for the first character ('c' is the same as 'C').  Any pitch can be
169   modified by '#' sharp or 'b' flat.  The final integer is the octave
170   per  In
171   this notation notes range from c-1 to g9.
173 - named note, relative (e.g. Db or a#).  This is like the absolute
174   named note but omits the octave as a convenience.  It will find the
175   pitch closest to the previously specified one.  This is inspired by
176   Lilypond's "Relative Octave Entry".  Some caveats:
178   - When the higher pitch and the lower pitch from the named note are
179     the same distance (6 semitones = tritone), the higher pitch is
180     chosen.
182   - When there is no previous note, the specified pitch is placed in
183     octave 4.
185   - The closest legal pitch is chosen.  Specifying 'g9' (MIDI pitch
186     127, the highest allowed) followed by 'a' would select MIDI pitch
187     117 (the 'a' below g9).
189 Voice declarations
190 ------------------
191 At the top are the voice declarations (e.g. "voice basskick sampson
192 1").  This creates a MIDI output in JACK called "sampson" and sends
193 events from the "basskick" voice to channel 1 of that port.
195 This allows you as many output ports as you need, without requiring a
196 separate view of the note events for each port like in many
197 sequencers.
199 This is also good for a device like the Korg Volca Sample.  To play
200 samples 1-10 on that device, notes must be sent to channels 1-10.
201 This isn't difficult in MIDI but almost no sequencers support that
202 kind of multi-channel output, to the point that a custom
203 channel-splitting cable was devised just for the Sample!  No need
204 custom cables if you use quincer.
206 Multiple patterns
207 -----------------
208 A new pattern declaration can follow the voice lines, as many patterns
209 as you need.  
211 A directive at the top 'run once' will cause the sequencer to play
212 top-to-bottom then stop.
214 You could otherwise specify 'run loop' at the top to cause the
215 sequencer to start over after it has reached the bottom.  This is the
216 default behavior if no 'run ...' directive was specified.
219 --------
220 Comments start with a # and go to the end of the line.
222 Include files
223 -------------
224 At any point in the input you can have a line:
226 include foo.qn
228 ...which will behave like includes in other languages (PHP or C
229 preprocessor).
231 This is powerful because it allows re-use of material from different
232 top-level input files, or even within the same one.  As explained in
233 the rationale section above, a single work can have multiple use
234 cases, slightly different but with common elements.  Traditionally
235 sequencers have a "one song = one file" idiom, an unnecessary
236 constraint on your workflow.
238 Prefixes and Suffixes (affixes)
239 -------------------------------
240 quincer supports events that occur before or after the main pattern.
241 Prefixes are useful for musical pickup beats (anacrusis), drum fills,
242 or cue tracks.  Suffixes can be used when a note must linger into the
243 next pattern.
245 To enter a prefix, just add ticks before the 0 in your meter line
247 .'.0.'.'.'.
248 e  A a     | lead
250 The e in this example is treated as a pick-up.
252 To enter a suffix, start a bar with S in your timeline.
254 0.'.'.'.S.
255   A   aeAA| lead
257 The final two A's are the suffix.
259 Affixes (prefixes/suffixes) don't affect when a pattern begins or
260 ends.  The extra notes will overlap the notes in the previous or next
261 patterns.
263 It is not yet implemented for affixes to mask events in the main
264 pattern, but this is planned.  In other words, if a drum fill is
265 entered as a prefix, then the events in the main pattern's drum voices
266 should be omitted.  Today, all the events just play over each other.
267 When masking is implemented, this will allow for affixes that
268 represent breaks (silence).
270 MIDI clock
271 ----------
272 If a line is specified at the beginning like:
274 clock vsamp 1 1
276 ...then MIDI clock messages (including start & stop) will be emitted
277 to the output 'vsamp'.  This allows you to use external sequencers,
278 whose clocks will be synced to quincer's tempo.  In addition to
279 sequencers, some other kinds of devices can use this information
280 (synths can set LFO, or delay effects like Eventide Timefactor can set
281 tap tempo).
283 The '1 1' is the numerator and denominator, which allow you to stretch
284 or compress the emitted clock signals in a flexible way.  Specifying
285 '2 1' with quincer's BPM set at 120 will cause clock to be emitted at
286 60 BPM.  '4 1' would emit clock at 30 BPM, and '1 2' would emit clock
287 at 240 BPM.  It is supported to specify strange (integer) values such
288 as '3 2', which would emit clock at 80 BPM against quincer's internal
289 120 BPM.
291 Notice that clock is specified per output.  I could emit clock to a
292 Volca Sample device at '1 1' (matching quincer's tempo) but also emit
293 at '2 1' to a Volca Keys device which would run its sequence at half
294 the tempo.
296 License
297 =======
298 Copyright (C) 2016 Erik Mackdanz <>
300 This program is free software: you can redistribute it and/or modify
301 it under the terms of the GNU General Public License as published by
302 the Free Software Foundation, either version 3 of the License, or
303 (at your option) any later version.
305 This program is distributed in the hope that it will be useful,
306 but WITHOUT ANY WARRANTY; without even the implied warranty of
308 GNU General Public License for more details.
310 You should have received a copy of the GNU General Public License
311 along with this program.  If not, see <>.