fixes: arp, script, started: test synth, tutorial

Author: flipcoder

.pylintrc

@@ -1,2 +1,2 @@
 [MESSAGES CONTROL]
-disable=C0326,C0303
+disable=C0326,C0303,R1714

README.md

@@ -29,8 +29,8 @@ Textbeat is a new project, but you can already do lots of cool things:
 - Strumming
 - Arpeggiation
 - Tuplets and polyrhythms
-- CC automation
-- Vibrato, pitch, and mod wheels
+- MIDI CC automation
+- Vibrato, pitch, and mod wheel control
 - Dynamics
 - Accents
 - Velocity
@@ -46,6 +46,8 @@ Textbeat is a new project, but you can already do lots of cool things:
 You can use the shell with General Midi out-of-the-box on windows, which is great for learning,
 but sounds bad without a decent soundfont.
 
+I'm currently working on headless VST rack generation.
+
 If you want to use VST instruments, you'll need to route the MIDI out to something that hosts them, like a DAW.
 
 For windows, you can use a virtual midi driver, such as [loopMIDI](http://www.tobias-erichsen.de/software/loopmidi.html) for usage with a VST host or DAW.
@@ -321,9 +323,9 @@ Unlike accents, volume changes persist.
 
 Interpolation is not yet impl
 
-## Articulation
+## Vibrato, Pitch, and Mod Wheel
 
-The vibrato symbol is a tilda (~).
+To add vibrato to a note, suffix it with a tilda (~).
 
 Vibrato uses the mod wheel right now, but will eventually use pitch wheel oscillation.
 
@@ -332,7 +334,7 @@ In the future, articulation will be programmable, per-track or per-song.
 ## Arpeggio Modulation
 
 Notes of arpeggios can be modified as they're running,
-by having effects in a grid space, for example:
+by having effects in the grid space they occur, for example:
 
 ```
 maj7&
@@ -347,7 +349,7 @@ maj7&
 
 maj7& starts a repeating 4-note arpeggio, and we indent to show this.
 
-Certain notes of the sequence are modulated with short/staccato '.', soft '?' and accent '!'
+Certain notes of the sequence are modulated with short/staccato '.', soft '?', and accent '!'
 
 For staccato usage w/o a note name, an extra dot is required since '.' is simply a placeholder.
 
@@ -367,7 +369,7 @@ The dots are placeholders.
 .    1''
 ```
 
-Columns can be detected in some cases, but you'll probably want to 
+Columns can be detected (in some cases), but you'll probably want to 
 specify the column width manually at the top,
 which allows vim to mark the columns.
 
@@ -386,7 +388,8 @@ For best view in an editor, it is recommended that you offset the first column b
 ## Patches
 
 Another useful global var is 'p', which sets midi patches by name or number
-across the tracks.  The midi names support partial case-insensitive matches.
+across the tracks.  The midi names support both patch numbers and partial case-insensitive
+matches of GM instruments.
 
 ```
 %t120 x2 p=piano,guitar,bass,drums c8,-2
@@ -396,17 +399,18 @@ For a full list of GM names, see [def/gm.yaml](https://github.com/flipcoder/text
 
 ## Tuplets
 
-Very early support for this. See tuplet example.
-The 't' command spreads a set of notes across a tuplet grid,
-starting at the first occurence of t in that group.
+The 'T' (tuplet) gives us access to the musical concept of tuplets (called triplets in cases of 3).
+which allows note timing and durations to fall along a ratio instead of the usual note subdivisions.
+
+Tuplets are marked by 'T' and have an optional value at the first occurence in that group.
 Ratios provided will control expansion.  Default is 3:4.
 If no denominator is given, it will default to the next power of two
 (so 3:4, 5:8, 7:8, 11:16).
-So in other words if you need a 5:6, you'll need to write t5:6. :)
-The ratio of the beat saves.  You only need to specify it once per group.
+So in other words, T5 is the same as T5:8, but if you need a 5:6, you'll need to write T5:6.
+The ratio of the tuplet persists for the rest of the grouping.
 For nested tripets, group those by adding an extra 'T'.
 
-Consider the 2 tracks:
+The two tracks below are a basic usage of triplets:
 
 ```
 1     1T
@@ -419,8 +423,14 @@ Consider the 2 tracks:
 4
 ```
 
-The spacing is not even between the sets, but the 'T' value stretches them
-to make them line up in a default ratio of 3:4.
+The first column is playing notes along the grid normally, while the
+2nd column is playing 3 notes in the space of the others' 4 notes.
+
+Even though there is visual spacing between the triplet groups, the 'T' value effective
+stretches the notes so they occur along a slower grid according to that ratio.
+
+The spaces that occur after (and between) tuplet groupings should remain empty,
+since they are spacers to make the expansion line up.
 
 ## Picking
 
@@ -435,7 +445,7 @@ to make them line up in a default ratio of 3:4.
 # to set a relative key, this will go from a major scale to relative minor scale
 %k+6
 
-# you can also go down to relative minor below
+# you can also go downwards
 %k-6
 
 # scale names are supported, this changes the scale shape to dorian
@@ -447,10 +457,10 @@ to make them line up in a default ratio of 3:4.
 
 ## Chords (Advanced)
 
-Slash chords do not imply inversions,
-but are for stacking across octaves.  Additionally, note names alone do no imply chords.
+In textbeat, slash (/) chords do not imply inversions,
+but are for spanning chord voicings across octaves.  Additionally, note names alone do no imply chords.
 For example, C/E means play a C note with an E in a lower octave, whereas a musician might
-interpret this as a specific chord voicing.  (Inversions use shift operator (maj> for first inversion))
+interpret this as a specific chord voicing.  Inversions in textbeat uses shift operator (>) instead (maj> for maj first inversion))
 
 ```
 b7maj7#4/sus2/1
@@ -468,7 +478,7 @@ Check out the examples/ folder.  Play them with textbeat from the
 command line:
 
 ```
-./textbeat.py examples/jazz
+./txbt examples/jazz.txbt
 ``` 
 
 # Advanced
@@ -635,7 +645,7 @@ Example: 1~ is fine, but 1v is not. Use 1@v You only need one to combine: 1@v5e5
 Note: Fractional values specified are formated like numbers after a decimal point:
 Example: 3, 30, and 300 all mean 30% (read like .3, .30, etc.)
 
-CC mapping is customizable inside [def/cc.yaml](https://github.com/flipcoder/textbeat/blob/master/def/default.yaml).
+CC mapping is customizable inside [def/cc.yaml](https://github.com/flipcoder/textbeat/blob/master/textbeat/def/default.yaml).
 
 ```
 
@@ -659,9 +669,9 @@ CC mapping is customizable inside [def/cc.yaml](https://github.com/flipcoder/tex
 
 A majority of the music index is contained in inside these files:
 
-- Default: [def/default.yaml](https://github.com/flipcoder/textbeat/blob/master/def/default.yaml).
-- Informal: [def/informal.yaml](https://github.com/flipcoder/textbeat/blob/master/def/informal.yaml).
-- Experimental: [def/exp.yaml](https://github.com/flipcoder/textbeat/blob/master/def/exp.yaml).
+- Default: [def/default.yaml](https://github.com/flipcoder/textbeat/blob/master/textbeatdef/default.yaml).
+- Informal: [def/informal.yaml](https://github.com/flipcoder/textbeat/blob/master/textbeat/def/informal.yaml).
+- Experimental: [def/exp.yaml](https://github.com/flipcoder/textbeat/blob/master/textbeat/def/exp.yaml).
 
 These lists does not include certain chord modifications (add, no, drop, etc.).
 

examples/drums1.txbt

@@ -0,0 +1,7 @@
+%t120 x2 c20,-2 p=drums f=loop
+1
+b5$?
+b5?
+3
+b5$?
+b5?

setup.py

@@ -4,18 +4,19 @@
 Open-source under MIT License
 
 Examples:
-    textbeat.py            shell
-    textbeat.py song.txbt  play song
+    textbeat                  shell
+    textbeat song.txbt        play song
 
 Usage:
-    textbeat.py [--dev=<device> | --verbose | --midi=<fn> | --ring | --follow | --loop] [-eftnpsrxhv] [SONGNAME]
-    textbeat.py [+RANGE] [--dev=<device> | --midi=<fn> | --ring | --follow | --loop] [-eftnpsrxhv] [SONGNAME]
-    textbeat.py -c [COMMANDS ...]
-    textbeat.py -l [LINE_CONTENT ...]
+    textbeat [--dev=<device> | --midi=<fn> | --ring | --follow --stdin] [-aeftnpsrxhvL] [SONGNAME]
+    textbeat [+RANGE] [--dev=<device> | --midi=<fn> | --ring | --follow | --stdin] [-aeftnpsrxhvL] [SONGNAME]
+    textbeat -c [COMMANDS ...]
+    textbeat -l [LINE_CONTENT ...]
 
 Options:
     -h --help             show this
     -v --verbose          verbose
+    -T --tutorial         (STUB) tutorial
     -t --tempo=<bpm>      (STUB) set tempo [default: 120]
     -x --grid=<g>         (STUB) set grid [default: 4]
     -n --note=<n>         (STUB) set grid using note value [default: 1]
@@ -25,9 +26,10 @@
     -f --flags            comma-separated global flags
     -c                    execute commands sequentially
     -l                    execute commands simultaenously
+    --stdin             read from stdin instead of file
     -r --remote           (STUB) remote/daemon mode, keep alive
     --ring                don't mute midi on end
-    --loop                loop song
+    -L --loop             loop song
     --midi=<fn>           generate midi file
     +<range>              play from line or maker, for range use start:end
     -e --edit             (STUB) open file in editor
@@ -41,7 +43,7 @@
     --lint                (STUB) analyze file
     --follow              (old) print newlines every line, no output
     --quiet               no output
-    --input               (STUB) midi input chord analyzer
+    -a --analyze          (STUB) midi input chord analyzer
 """
 from __future__ import absolute_import, unicode_literals, print_function, generators
 # try:
@@ -51,7 +53,7 @@
 def main():
 # if __name__!='__main__':
 #     sys.exit(0)
-    ARGS = docopt(__doc__)
+    ARGS = docopt(__doc__.replace('TEXTBEAT',os.path.basename(sys.argv[0]).lower()))
     set_args(ARGS)
 
     from . import support
@@ -110,11 +112,13 @@ def main():
             elif arg == '--edit': pass
             elif arg == '-l': player.cmdmode = 'l'
             elif arg == '-c': player.cmdmode = 'c'
+            elif arg == '-T':
+                player.tutorial = Tutorial(player)
             elif arg =='--flags':
                 vals = val.split(',')
                 player.add_flags(map(player.FLAGS.index, vals))
             elif arg == '--loop': player.add_flags(Player.Flag.LOOP)
-            elif arg == '--renderman': player.renderman = True
+            # elif arg == '--renderman': player.renderman = True
 
     if player.cmdmode=='l':
         player.buf = ' '.join(ARGS['LINE_CONTENT']).split(';') # ;
@@ -123,8 +127,14 @@ def main():
     else: # mode n
         # if len(sys.argv)>=2:
         #     FN = sys.argv[-1]
-        if ARGS['SONGNAME']:
-            FN = ARGS['SONGNAME']
+        FN = ARGS['SONGNAME']
+        from_stdin = False
+        if FN=='-' or ARGS['--stdin']:
+            FN = 0 # TEMP: doesnt work with py2
+            from_stdin = True
+        else:
+            from_stdin = False
+        if FN or from_stdin:
             # player.markers[''] = 0 # start marker
             with open(FN) as f:
                 lc = 0
@@ -161,7 +171,7 @@ def main():
                 player.cmdmode = ''
             player.shell = True
 
-    player.interactive = player.shell or player.remote
+    player.interactive = player.shell or player.remote or player.tutorial
 
     pygame.midi.init()
     if pygame.midi.get_count()==0:
@@ -258,28 +268,28 @@ def main():
         active = support.SUPPORT_ALL & support.SUPPORT
         inactive = support.SUPPORT_ALL - support.SUPPORT
         if active:
-            log(FG.GREEN + 'Active Modules: ' + FG.WHITE +  ', '.join(active) + FG.WHITE)
+            log(FG.GREEN + 'Active Modules: ' + STYLE.RESET_ALL +  ', '.join(active) + STYLE.RESET_ALL)
         if inactive:
-            log(FG.RED + 'Inactive Modules: ' +  FG.WHITE + ', '.join(inactive))
+            log(FG.RED + 'Inactive Modules: ' +  STYLE.RESET_ALL + ', '.join(inactive))
         if player.portname:
-            log(FG.GREEN + 'Device: ' + FG.WHITE + '%s' % (player.portname if player.portname else 'Unknown',))
-        log(FG.RED + 'Other Devices: ' + FG.WHITE + '%s' % (', '.join(portnames)))
+            log(FG.GREEN + 'Device: ' + STYLE.RESET_ALL + '%s' % (player.portname if player.portname else 'Unknown',))
+        log(FG.RED + 'Other Devices: ' + STYLE.RESET_ALL + '%s' % (', '.join(portnames)))
         if player.portname:
             if player.tracks[0].midich == DRUM_CHANNEL:
                 log(FG.GREEN + 'GM Percussion')
             else:
-                log(FG.GREEN + 'GM Patch: '+ FG.WHITE +'%s' % GM[player.tracks[0].patch_num]) 
+                log(FG.GREEN + 'GM Patch: '+ STYLE.RESET_ALL +'%s' % GM[player.tracks[0].patch_num]) 
 
-        log('Use -h for command line options.')
-        log('Read the manual and look at examples. Have fun!')
+        # log('')
+        # log(FG.BLUE + 'New? Type help and press enter to start the tutorial.')
         log('')
 
     player.run()
 
     if player.midifile:
         player.midifile.save(midifn)
 
-# TODO: turn all midi note off
+    # TODO: turn all midi note off
     i = 0
     for ch in player.tracks:
         if not player.ring: