Comprehensive overhaul: Add constants to replace event keys; tidy up examples; remove some cruft; improve naming

Author: ideoforms

README.md

@@ -13,53 +13,56 @@ Most of the major parts of isobar are subclasses of `Pattern`, which implement's
 # Usage
 
 ```python
-from isobar import *
-
-# create a repeating sequence with scalar transposition:
-# [ 36, 38, 43, 39, ... ]
-a = PSeq([ 0, 2, 7, 3 ]) + 36
-
-# apply pattern-wise transposition
-# [ 36, 50, 43, 51, ... ]
-a = a + PSeq([ 0, 12 ])
-
-# create a geometric chromatic series, repeated back and forth
-b = PSeries(0, 1, 12) + 72
-b = PPingPong(b)
-b = PLoop(b)
-
-# create an velocity series, with emphasis every 4th note,
-# plus a random walk to create gradual dynamic changes
-amp = PSeq([ 50, 35, 25, 35 ]) + PBrown(0, 1, -20, 20)
-
-# a Timeline schedules events at a given BPM.
-# by default, send these over the first MIDI output.
-timeline = Timeline(120)
-
-# assign each of our Patterns to particular properties
-timeline.sched({ 'note': a, 'dur': 1, 'gate': 2 })
-timeline.sched({ 'note': b, 'dur': 0.25, 'amp': amp })
-
-timeline.run()
-
+import isobar as iso
+
+#------------------------------------------------------------------------
+# Create a geometric series on a minor scale.
+# PingPong plays the series forward then backward. PLoop loops forever.
+#------------------------------------------------------------------------
+arpeggio = iso.PSeries(0, 2, 6)
+arpeggio = iso.PDegree(arpeggio, iso.Scale.minor) + 72
+arpeggio = iso.PPingPong(arpeggio)
+arpeggio = iso.PLoop(arpeggio)
+
+#------------------------------------------------------------------------
+# Create a velocity sequence, with emphasis every 4th note,
+# plus a random walk to create gradual dynamic changes.
+# Amplitudes are in the MIDI velocity range (0..127).
+#------------------------------------------------------------------------
+amplitude = iso.PSequence([50, 35, 25, 35]) + iso.PBrown(0, 1, -20, 20)
+
+#------------------------------------------------------------------------
+# A Timeline schedules events at a given BPM.
+#------------------------------------------------------------------------
+timeline = iso.Timeline(120)
+
+#------------------------------------------------------------------------
+# Schedule events, with properties mapped to the Pattern objects.
+#------------------------------------------------------------------------
+timeline.schedule({
+    iso.EVENT_NOTE: arpeggio,
+    iso.EVENT_DURATION: 0.25,
+    iso.EVENT_AMPLITUDE: amplitude
+})
 ```
 
 ## Examples
 
-More examples are available in the 'examples' directory with this
+More examples are available in the [examples](examples) directory with this
 distribution:
 
-* [ex-basics.py](examples/ex-basics.py)
-* [ex-lsystem-grapher.py](examples/ex-lsystem-grapher.py)
-* [ex-lsystem-rhythm.py](examples/ex-lsystem-rhythm.py)
-* [ex-lsystem-stochastic.py](examples/ex-lsystem-stochastic.py)
-* [ex-markov-learner.py](examples/ex-markov-learner.py)
-* [ex-permut-degree.py](examples/ex-permut-degree.py)
-* [ex-piano-phase.py](examples/ex-piano-phase.py)
-* [ex-prime-composition.py](examples/ex-prime-composition.py)
-* [ex-subsequence.py](examples/ex-subsequence.py)
-* [ex-walk.py](examples/ex-walk.py)
-
+* [00.ex-hello-world.py](examples/00.ex-hello-world.py)
+* [01.ex-basics.py](examples/01.ex-basics.py)
+* [02.ex-subsequence.py](examples/02.ex-subsequence.py)
+* [03.ex-euclidean.py](examples/03.ex-euclidean.py)
+* [04.ex-permutations.py](examples/04.ex-permutations.py)
+* [05.ex-piano-phase.py](examples/05.ex-piano-phase.py)
+* [06.ex-walk.py](examples/06.ex-walk.py)
+* [10.ex-lsystem-stochastic.py](examples/10.ex-lsystem-stochastic.py)
+* [11.ex-lsystem-rhythm.py](examples/11.ex-lsystem-rhythm.py)
+* [12.ex-lsystem-grapher.py](examples/12.ex-lsystem-grapher.py)
+* [20.ex-markov-learner.py](examples/20.ex-markov-learner.py)
+* [30.ex-midifile-write.py](examples/30.ex-midifile-write.py)
 
 ## Classes
 
@@ -82,11 +85,11 @@ Pattern classes:
 
     CORE (core.py)
     Pattern          - Abstract superclass of all pattern generators.
-    PConst           - Pattern returning a fixed value
+    PConstant        - Pattern returning a fixed value
     PRef             - Pattern containing a reference to another pattern
     PDict            - Dict of patterns
+    PDictKey         - Request a specified key from a dictionary.
     PIndex           - Request a specified index from an array.
-    PKey             - Request a specified key from a dictionary.
     PConcat          - Concatenate the output of multiple sequences.
     PAdd             - Add elements of two patterns (shorthand: patternA + patternB)
     PSub             - Subtract elements of two patterns (shorthand: patternA - patternB)
@@ -99,12 +102,12 @@ Pattern classes:
     PRShift          - Binary right-shift (shorthand: patternA << patternB)
 
     SEQUENCE (sequence.py)
-    PSeq             - Sequence of values based on an array
+    PSequence        - Sequence of values based on an array
     PSeries          - Arithmetic series, beginning at <start>, increment by <step>
     PRange           - Similar to PSeries, but specify a max/step value.
     PGeom            - Geometric series, beginning at <start>, multiplied by <step>
     PLoop            - Repeats a finite <pattern> for <n> repeats.
-    PConcat          - Concatenate the output of multiple finite sequences
+    PConcatenate     - Concatenate the output of multiple finite sequences
     PPingPong        - Ping-pong input pattern back and forth N times.
     PCreep           - Loop <length>-note segment, progressing <creep> notes after <count> repeats.
     PStutter         - Play each note of <pattern> <count> times.
@@ -159,7 +162,7 @@ Pattern classes:
     PMarkov          - First-order Markov chain.
 
     LSYSTEM (lsystem.py)
-    PLSys            - integer sequence derived from Lindenmayer systems
+    PLSystem         - integer sequence derived from Lindenmayer systems
 
     WARP (warp.py)
     PWInterpolate    - Requests a new target warp value from <pattern> every <length> beats

examples/00.ex-hello-world.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+
+#------------------------------------------------------------------------
+# isobar: ex-hello-world
+# 
+# Introductory example. Plays a one-octave chromatic scale.
+# Make sure you have a MIDI device connected.
+#------------------------------------------------------------------------
+
+import isobar as iso
+
+import logging
+logging.basicConfig(level=logging.INFO, format="[%(asctime)s] %(message)s")
+
+series = iso.PRange(0, 73, 1)
+timeline = iso.Timeline(120)
+
+timeline.schedule({
+    iso.EVENT_NOTE: series,
+    iso.EVENT_DURATION: 1
+})
+
+timeline.run()

examples/ex-basics.py examples/01.ex-basics.pyexamples/ex-basics.py renamed to examples/01.ex-basics.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 #------------------------------------------------------------------------
 # isobar: ex-basics
@@ -7,48 +7,58 @@
 # sequences, randomness, scheduling and parameter mapping.
 #------------------------------------------------------------------------
 
-from isobar import *
-from isobar.io.midi import MidiOut
+import isobar as iso
 
 import logging
+
 logging.basicConfig(level=logging.INFO, format="[%(asctime)s] %(message)s")
 
 #------------------------------------------------------------------------
-# Create a repeating sequence with scalar transposition:
-# [ 36, 38, 43, 39, 36, 38, 43, 39, ... ]
+# Create a geometric series on a minor scale.
+# PingPong plays the series forward then backward. PLoop loops forever.
 #------------------------------------------------------------------------
-a = PSeq([ 0, 2, 7, 3 ]) + 36
+arpeggio = iso.PSeries(0, 2, 6)
+arpeggio = iso.PDegree(arpeggio, iso.Scale.minor) + 72
+arpeggio = iso.PPingPong(arpeggio)
+arpeggio = iso.PLoop(arpeggio)
 
 #------------------------------------------------------------------------
-# Apply pattern-wise transposition
-# [ 36, 50, 43, 51, ... ]
+# Create a velocity sequence, with emphasis every 4th note,
+# plus a random walk to create gradual dynamic changes.
+# Amplitudes are in the MIDI velocity range (0..127).
 #------------------------------------------------------------------------
-a = a + PSeq([ 0, 12, 24 ])
+amplitude = iso.PSequence([50, 35, 25, 35]) + iso.PBrown(0, 1, -20, 20)
 
 #------------------------------------------------------------------------
-# Create a geometric chromatic series, repeated back and forth
+# Create a repeating sequence with scalar transposition:
+# [ 36, 38, 43, 39, 36, 38, 43, 39, ... ]
 #------------------------------------------------------------------------
-b = PSeries(0, 2, 6) + 72
-b = PPingPong(b)
-b = PLoop(b)
+bassline = iso.PSequence([0, 2, 7, 3]) + 36
 
 #------------------------------------------------------------------------
-# Create an velocity series, with emphasis every 4th note,
-# plus a random walk to create gradual dynamic changes
+# Repeat each note 3 times, and transpose each into a different octave
+# [ 36, 48, 60, 38, 50, 62, ... ]
 #------------------------------------------------------------------------
-amp = PSeq([ 50, 35, 25, 35 ]) + PBrown(0, 1, -20, 20)
+bassline = iso.PStutter(bassline, 3) + iso.PSequence([0, 12, 24])
 
 #------------------------------------------------------------------------
 # A Timeline schedules events at a given BPM.
 # by default, send these over the first MIDI output.
 #------------------------------------------------------------------------
-output = MidiOut()
-timeline = Timeline(120, output)
+output = iso.io.midi.MidiOut()
+timeline = iso.Timeline(120, output)
 
 #------------------------------------------------------------------------
 # Schedule events, with properties mapped to the Pattern objects.
 #------------------------------------------------------------------------
-timeline.sched({ 'note': a, 'dur': 1, 'gate': 2 })
-timeline.sched({ 'note': b, 'dur': 0.25, 'amp': amp })
+timeline.schedule({
+    iso.EVENT_NOTE: arpeggio,
+    iso.EVENT_DURATION: 0.25,
+    iso.EVENT_AMPLITUDE: amplitude
+})
+timeline.schedule({
+    iso.EVENT_NOTE: bassline,
+    iso.EVENT_DURATION: 1
+})
 
 timeline.run()

examples/02.ex-subsequence.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+
+#------------------------------------------------------------------------
+# isobar: ex-subsequence
+#------------------------------------------------------------------------
+
+import isobar as iso
+
+import logging
+
+logging.basicConfig(level=logging.DEBUG, format="[%(asctime)s] %(message)s")
+
+scale = iso.Scale.pelog
+sequence = iso.PDegree(iso.PBrown(0, 3, -12, 12, repeats=False), scale)
+
+offset = iso.PStutter(iso.pattern.PWhite(0, 4), 2)
+sequence = iso.PSubsequence(sequence, offset, 4)
+sequence = iso.PPermut(sequence)
+sequence = sequence + 64
+sequence = iso.PReset(sequence, iso.PImpulse(24))
+
+amp = iso.pattern.PSequence([45, 35, 25, 40]) + iso.PBrown(0, 1, -15, 10)
+
+gate = iso.pattern.PBrown(1.5, 0.01, 0.6, 2.5)
+
+timeline = iso.Timeline(120)
+timeline.schedule({
+    iso.EVENT_NOTE: sequence.copy(),
+    iso.EVENT_AMPLITUDE: amp,
+    iso.EVENT_DURATION: 0.25,
+    iso.EVENT_GATE: gate
+})
+timeline.schedule({
+    iso.EVENT_NOTE: sequence.copy() + 24,
+    iso.EVENT_AMPLITUDE: amp.copy(),
+    iso.EVENT_DURATION: 0.5,
+    iso.EVENT_GATE: gate.copy()
+})
+timeline.schedule({
+    iso.EVENT_NOTE: sequence.copy() - 24,
+    iso.EVENT_AMPLITUDE: 10 + amp.copy() * 0.5,
+    iso.EVENT_DURATION: iso.PChoice([4, 4, 6, 8]),
+    iso.EVENT_GATE: gate.copy()
+})
+
+timeline.run()

examples/03.ex-euclidean.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+#------------------------------------------------------------------------
+# isobar: ex-euclidean
+#
+# Uses Euclidean rhythms to generate multiple polyrhythmic voices.
+#------------------------------------------------------------------------
+
+import isobar as iso
+
+import logging
+logging.basicConfig(level=logging.INFO, format="[%(asctime)s] %(message)s")
+
+timeline = iso.Timeline(100)
+
+timeline.schedule({
+    iso.EVENT_NOTE: 60 * iso.PEuclidean(5, 8),
+    iso.EVENT_DURATION: 0.25
+}, delay=0.0)
+timeline.schedule({
+    iso.EVENT_NOTE: 62 * iso.PEuclidean(5, 13),
+    iso.EVENT_DURATION: 0.5
+}, delay=0.25)
+timeline.schedule({
+    iso.EVENT_NOTE: 64 * iso.PEuclidean(7, 15),
+    iso.EVENT_DURATION: 0.5
+}, delay=0.5)
+timeline.schedule({
+    iso.EVENT_NOTE: 67 * iso.PEuclidean(6, 19),
+    iso.EVENT_DURATION: 0.25
+}, delay=0.75)
+timeline.schedule({
+    iso.EVENT_NOTE: 71 * iso.PEuclidean(7, 23),
+    iso.EVENT_DURATION: 0.5
+}, delay=1.0)
+
+timeline.run()