README

   1 quincer
   2
   3 quincer is a sequencer for live performance of composed works.
   4
   5 Features
   6 ========
   7
   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 - pure JACK (and is a timebase master)
  17
  18 Planned features, more imminent items first:
  19 - Song mode
  20 - Per-pattern swing setting
  21 - Base tempo can be altered at runtime via MIDI CC
  22 - Jump controls - use MIDI input to skip around (song mode)
  23 - prefix/suffix events mask events from main pattern
  24 - optional MIDI clock output for driving hardware synths
  25
  26 Rationale
  27 =========
  28
  29 I want a sequencer for live performance of songs that have been
  30 previously composed, with the sequencing mostly fixed.
  31
  32 But at performance-time I want the ability to make small adjustments
  33 to the song's form to, say, skip a verse or draw out a solo section or
  34 delay a verse slightly because the drummer dropped a stick.  I want
  35 the ability to decide to take the song a little faster or slower than
  36 in rehearsal.
  37
  38 I want the ability to write a song in an unusual meter, with swing and
  39 mid-song tempo changes.  The content of a song pattern should be
  40 allowed to start before beat one of the first bar (e.g. pickups
  41 (anacrusis), or drum fills, or cues on a cue track) and end after the
  42 last beat of the last bar of the pattern.
  43
  44 For compose-time workflow, I want to support multiple use cases for a
  45 song.  That is, I want to run a file that has a sequenced drum track,
  46 or run a different file with a click track instead of drums and maybe
  47 an extra verse.  Among these multiple files, content is re-used where
  48 possible and files can be checked into source control.
  49
  50 Capturing live input is not important, nor is a graphical interface.
  51 Session management isn't on the roadmap currently and probably won't
  52 be.
  53
  54 I've taken inspiration from a few existing sequencers.  The sequencers
  55 in some DAWs are very good for non-standard time signatures and swing
  56 and tempo changes, but I'd never want the risk/overhead of using a DAW
  57 on stage.  The sequencers that are currently for live use have
  58 interesting control capabilities but focus on evolving looped beats in
  59 an improvisatory way, a very specific use case that isn't needed for
  60 all kinds of music.
  61
  62 These features aren't all implemented yet but I've got a solid start.
  63 I hope you'll find quincer useful while it's in progress.
  64
  65
  66 Input file syntax
  67 =================
  68
  69 The quincer executable takes a single argument, a filename containing
  70 the input.  I use files ending with '.qn' as a convention but the
  71 program doesn't care.
  72
  73 An input file looks like this:
  74
  75 voice basskick sampson 1
  76 voice rim sampson 1
  77 voice rhykeys sampson 1
  78 voice suskeys amsynth 1
  79 voice reso amsynth 1
  80
  81 pattern 88 0
  82 $ 38 127
  83 f 41 110
  84 g 43 110
  85 k 90 80
  86 j 69 80
  87 b 66 70
  88 l 62 60
  89 M 81 100
  90 m 81 60
  91
  92 # Reso on the synth
  93 r cc 74 0
  94 R cc 74 127
  95
  96 0.....'.....'.....'.....|.....'.....'.....'.....
  97 $         $-      f  g  |                         basskick
  98                   k     |                         rim
  99 M m m |                                           rhykeys
 100 j---------              l---b-----              | suskeys
 101 r                       R                       | reso
 102
 103 Time spec
 104 ---------
 105 Look at the final section first, since everything else leads up to
 106 this.  There is a meter line "0.....'.....'.....'....." which defines
 107 that a bar has four beats and a beat has six ticks.
 108
 109 The meter line may contain multiple bars if it's easier for human
 110 readers, but the program only looks at the first one.  Also, the first
 111 beat of the first bar defines how many ticks are in a beat.  It
 112 follows from this that within a pattern the ticks-per-beat and
 113 beats-per-bar are constant within a pattern.
 114
 115 The next lines after the meter line are voice lines, starting with
 116 "$         $-      f  g  | basskick".  These show note events and give
 117 the voice a name.  Note events can pretty much be any printable character,
 118 except '-' which prolongs a note and '|' which is used to mark the end
 119 of the events and the start of the voice name.
 120
 121 It is legal to give the same voice name to multiple lines.  This can
 122 be used to send a block chord to a piano instrument, for example.
 123
 124 Notice that the voice lines have their ending '|' at different beats.
 125 The length of the pattern is the length of the longest voice in it
 126 ("suskeys" or "reso" in this example).  Patterns that are shorter are
 127 looped.  It is undefined what happens if your shorter patterns aren't
 128 exactly divisible into the longest one, so be sure you've got that
 129 right.
 130
 131 Pattern declaration and event definitions
 132 -----------------------------------------
 133 Before that section the pattern is declared:
 134
 135 pattern 88 0
 136 $ 38 127
 137 f 41 110
 138 ...
 139
 140 This takes the form:
 141 pattern <bpm> <swing>
 142 <notechar> [cc] <pitch> <velocity>
 143 <notechar> [cc] <pitch> <velocity>
 144 ...
 145
 146 Note that 'bpm' is declared for each pattern, which allows mid-song
 147 tempo changes.
 148
 149 'swing' isn't implemented yet and may be omitted. 'notechar' can be
 150 any printable character except - or | (for reasons explained above) or
 151 # (comment delimiter).  Future releases will support other MIDI event
 152 types such as pitch bend.
 153
 154 Voice declarations
 155 ------------------
 156 At the top are the voice declarations (e.g. "voice basskick sampson
 157 1").  This creates a MIDI output in JACK called "sampson" and sends
 158 events from the "basskick" voice to channel 1 of that port.
 159
 160 This allows you as many output ports as you need, without requiring a
 161 separate view of the note events for each port like in many
 162 sequencers.
 163
 164 Multiple patterns
 165 -----------------
 166 A new pattern declaration can follow the voice lines, as many patterns
 167 as you need.  Until a song mode is implemented, the behavior will be
 168 to play from top to bottom and start again with the first pattern.
 169
 170 Comments
 171 --------
 172 Comments start with a # and go to the end of the line.
 173
 174 Include files
 175 -------------
 176 At any point in the input you can have a line:
 177
 178 include foo.qn
 179
 180 ...which will behave like includes in other languages (PHP or C
 181 preprocessor).
 182
 183 This is powerful because it allows re-use of material from different
 184 top-level input files, or even within the same one.  As explained in
 185 the rationale section above, a single work can have multiple use
 186 cases, slightly different but with common elements.  Traditionally
 187 sequencers have a "one song = one file" idiom, an unnecessary
 188 constraint on your workflow.
 189
 190 Prefixes and Suffixes (affixes)
 191 -------------------------------
 192 quincer supports events that occur before or after the main pattern.
 193 Prefixes are useful for musical pickup beats (anacrusis), drum fills,
 194 or cue tracks.  Suffixes can be used when a note must linger into the
 195 next pattern.
 196
 197 To enter a prefix, just add ticks before the 0 in your meter line
 198
 199 .'.0.'.'.'.
 200 e  A a     | lead
 201
 202 The e in this example is treated as a pick-up.
 203
 204 To enter a suffix, start a bar with S in your timeline.
 205
 206 0.'.'.'.S.
 207   A   aeAA| lead
 208
 209 The final two A's are the suffix.
 210
 211 Affixes (prefixes/suffixes) don't affect when a pattern begins or
 212 ends.  The extra notes will overlap the notes in the previous or next
 213 patterns.
 214
 215 It is not yet implemented for affixes to mask events in the main
 216 pattern, but this is planned.  In other words, if a drum fill is
 217 entered as a prefix, then the events in the main pattern's drum voices
 218 should be omitted.  Today, all the events just play over each other.
 219 When masking is implemented, this will allow for affixes that
 220 represent breaks (silence).
 221
 222 License
 223 =======
 224 Copyright (C) 2016 Erik Mackdanz <erikmack@gmail.com>
 225
 226 This program is free software: you can redistribute it and/or modify
 227 it under the terms of the GNU General Public License as published by
 228 the Free Software Foundation, either version 3 of the License, or
 229 (at your option) any later version.
 230
 231 This program is distributed in the hope that it will be useful,
 232 but WITHOUT ANY WARRANTY; without even the implied warranty of
 233 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 234 GNU General Public License for more details.
 235
 236 You should have received a copy of the GNU General Public License
 237 along with this program.  If not, see <http://www.gnu.org/licenses/>.