First draft of the README.MD

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>
+          Kick drum pattern
+  -S, --snare <SNARE>
+          Snare drum pattern
+  -H, --hi-hat <HIHAT>
+          Hi-Hat pattern
+  -C, --crash <CRASH>
+          Crash cymbal pattern
+  -t, --tempo <TEMPO>
+          Tempo value [default: 120]
+  -s, --time-signature <TIME_SIGNATURE>
+          Time signature [default: 4/4]
+  -o, --output-file <OUTPUT>
+          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 <OPTIONS> -o out.mid && open out.mid` or `poly <OPTIONS> -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)
+
+
+