diff --git a/README.MD b/README.MD new file mode 100644 index 0000000..5b54ec7 --- /dev/null +++ b/README.MD @@ -0,0 +1,119 @@ +# Poly + +Polyrhythmically-inclinded drum generator. + +# Motivation + +I'm a guitar player, and I use tablature notation editors such as Guitar Pro a lot. However, it gets complicated fast to write a polyrhythmic/polymetric drum parts as shifts tend to go over the bar lines. The other property of such parts is: it tend to unfold in a simple way from simple ideas such as "I want to create a drum part that will have a 3 against 4 feel with a kick drum against a snare drum". The other way to think about it is that it has a simple blueprint, but it's tricky to express in the western musical notation. This is why `Poly` exists. I wanted to have a simple tool to workshop/brainstorm rhythmic ideas and evaluate them by having a MIDI playback. I'm into modern progressive rock/metal music, fusion, so it all applies very well. I have an impression it may be useful for indian carnatic music as well, but I would like to get some insightful confirmation on that. + +# Usage + +Poly runs as an executable with the desired command line options. The available options are as follows: + +``` +Usage: poly [OPTIONS] + +Options: + -K, --kick + Kick drum pattern + -S, --snare + Snare drum pattern + -H, --hi-hat + Hi-Hat pattern + -C, --crash + Crash cymbal pattern + -t, --tempo + Tempo value [default: 120] + -s, --time-signature + Time signature [default: 4/4] + -o, --output-file + Output file path, make a dry run if omitted + -B, --follow-kick-drum-with-bass + Generate a second MIDI track for the bass following the kick drum + -h, --help + Print help + -V, --version + Print version +``` + +Poly uses a simple DSL (Domain-specific language) for drum patterns. For a more detailed explanation, go to [DSL Overview](#dsl-overview). + +Let's say you want to tell if two patterns will converge and how soon. We'll start with a 3 against 4. The first pattern would be a series of 8th notes on the kick drum + +``` +poly --kick '8x--x--' --snare '4-x' +``` +Output +``` +No output file path was supplied, running a dry run... +Converges over 3 bars +``` + +We haven't provided an `--output-file` / `-o` parameter, so `poly` made a dry run. It tells us it will converge in 3 bars. Let's see how it will look in the MIDI file by adding an output. + +``` +poly --kick '8x--x--' --snare '4-x' -o out.mid +``` +Output +``` +Converges over 3 bars +out.mid was written successfully +``` + +Poly operates under an assumption, that it's easy to replicate a pattern that converges over a finite number of bars in the DAW or tablature editor, so it only generates 3 bars of drums in this case. On Mac OS, I usually do something in lines of `poly -o out.mid && open out.mid` or `poly -o out.mid && open -a 'Guitar Pro 7' out.mid`. + +This way it defaults to 4/4 as a time signature, but we may want to interpret this rhythmic pattern in 3/4 for example. Let's try it: + +``` +poly --time-signature '3/4' --kick '8x--x--' --snare '4-x' -o out.mid && open -a 'Guitar Pro 7' out.mid +``` +Output: +``` +Converges over 2 bars +out.mid was written successfully +``` + +Now we can see it converges in 2 bars, not 3. Honestly, I like the 4/4 host time signature better. Let's get back to it. Also, we can add a crash cymbal and hi-hat patterns too, also we can make it just a bit livelier by increasing the tempo: + +``` +poly --time-signature '4/4' --tempo 138 --crash '4x---' --hi-hat '8-xxx' --kick '8x--x--' --snare '4-x' -o out.mid +``` + +That's cool, but let's make it even more useful by adding a blueprint for the bass track. Simple way of doing that is to make bass follow the kick drum. `Poly` has an option to do this called `-B`/`--follow-kick-drum-with-bass`. Let's add it to the previous command to add the bass track to the output file: + +``` +poly --time-signature '4/4' --tempo 138 --crash '4x---' --hi-hat '8.t-xxx' --kick '8x--x--' --snare '4-x' -o out.mid -B +``` + +Now we have two tracks in the output file and you can change the bass notes to create an expected harmonic context. + +# DSL overview + +Any pattern can be described by a series of note groups. All note in the note group have the same length. Possible lengths are: +* `1` - Whole note +* `2` - Half note +* `4` - Fourth note +* `8` - Eighth note +* `16` - Sixteenth note +* `32` - Thirty secondth note +* `64` - Sixty Fourth note +* `.` - dotted note (meaning it has 1.5 length of the unmodified duration). Dot should be applied after the basic length like this: `8.` +* `t` - Triplet notes, should be applied after basic lengths and dots. e.g. `4.t` means triplets of dotted fourth notes. + +Now let's talk about the drums. `Poly` has a logic similar to a drum machine, so we only concern ourselves with drum hits and rests: +* `x` - Hit +* `-` - Rest + +Let's compose a few simple note groups: +* `4x` - a group of one fourth note. +* `8.-x` a group of a rest and a drum hit. Both rest and hit have a length of 8th dotted note each. + +... + +## Guitar pro remarks + +Don't forget to quantize MIDI imports to 64th notes as it gets increasingly crazier as we get into the wilder note groupings: +![Guitar Pro Import](doc/Guitar-Pro-Import.png) + + +