** Overview of 'harpwise jamming'

  Scripted jamming along a backing track. For this harpwise includes a
  backing-track with timestamps as well as a matching set of licks and
  chords. Two instances of harpwise then work together to display licks
  and chords in sync with the track.


** Usage by Examples

  The mode jamming is a remote control and helper for harpwise in mode
  listen; jamming plays a backing-track while making listen switch licks
  and chords (scales). This happens in time with the chord-changes of the
  track by means of a time-table (see below).

  The screen of listen, shows iteration, current chord and seconds left in the first line,
  making orientation easy.


  To use harpwise jamming, you need *two* terminals. In the first one
  start e.g.:

    #+begin_src 
    harpwise jam along 12bar
    #+end_src

  this will give you the command for the second terminal, and will stand by
  until you have started it. For 'jam along 12bar' it will be like this:
  
    #+begin_src 
    harpwise listen --scale-prog 12bar --lick-prog box1 --jamming
    #+end_src

  note, that advanced users may vary this command, e.g. by choosing
  a different lick-progression.
  
  As soon as both instances of harpwise are running, grab your harp and
  get into the flow.


  Once started, 'harpwise listen' (as usual) shows your playing on the
  harmonica-chart and indicates, how it matches the current chord; all
  with respect to the backing track beeing played. The scale-progression
  '12bar' is really a chord-progression (I,IV,V) and is switched along by
  mode jamming. This mode uses the timestamps from the file 12bar.json to
  trigger harpwise at the right moments.

  With the scripted chord-progression '12bar' you always see, which are
  the notes (holes) from the chord and may check easily, if you play
  within the current chord or not. In addition you have the licks of the
  lick-progression 'box1' (whose name comes from the box-pattern on
  guitar). These licks are switched along as the backing-track progresses
  (just like the chords). Start by playing the licks unil you feel in the
  mood for some improvisation, e.g. over the chords.

  Note, that in this accustic setup you may either need headphones or a
  hand-held microphone to keep apart your playing from the backing track
  beeing played.


  The argument '12bar' above is treated as a filename; it is expandeded to
  '12bar.json' and searched in two directories: ~/harpwise/jamming and
  the installation-dir of harpwise.

  The file '12bar.json' contains the required settings (e.g. location of
  the backing track) and has many comments (lots of them!), that can help
  to understand its content. This is not needed initially but becomes
  essential, if you want to jam along with your own backing-tracks; for
  this you will need to create your own json-file.


  If, over time, you have created multiple json-files with settings
  (e.g. different backing-tracks), you may use:

    #+begin_src 
    harpwise jamming list
    #+end_src

  to list them; if you have many files, you may create subdirectories.
  

  With all subcommands of 'harpwise jam' (e.g. 'along'), you may abbreviate
  the name of the json-file and supply one or many strings that appear in
  the filename (in the given sequence); e.g.:

    #+begin_src 
    harpwise jam along 2b       
    #+end_src

  which saves us some typing, compared to '12bar'. Or even

    #+begin_src 
    harpwise jam along 2b r
    #+end_src

  which is too wordy, if you have one json-file only. However, if you
  create your own jamming-files and have multiple of them, this may help
  to distinguish among files with similar names.
  

  The key for jamming comes (as usual) either from your configuration or
  is given explicitly on the commandline:

    #+begin_src 
    harpwise jam g along 12bar
    #+end_src

  in response the wise will shift the backing-track accordingly and tell
  'harpwise listen' to use this key too. However, if you do not specify a
  key on the commandline, the key from the json-file prevails.
  

  Finally, here are all the extra-functions for 'harpwise jamming':

    - along:
      Start the jamming; this matches its arguments
      against known files and starts the jamming; an example would be:
      
      harpwise jam along 12
      
      which would pick the pre-installed file '12bar'. If you have many
      jamming-files of your own, you may give longer or more words to make
      selection uniq.
      
      Please note, that this kind of fuzzy selection applies to other
      extra-commands within mode jamming too.

    - list, ls:
      list available jamming-files with date of last usage and any stored
      processing notes.
      
      You may also add arguments to name a single file, in which case the
      comment and additional details will be shown too.
      
      If you give the argument 'all' alone, details for all files will
      be printed.

    - play:
      Play the given backing-track; can be useful if you want to search
      for a matching lick-progression before starting to jam.
      
      Also useful when creating a new json for jamming, because it
      allows to create a list of timestamps.
      
      For this purpose you may even give the path to a simple .mp3-file
      which will be played, thus allowing you to mark timestamps; so
      no need to create a json-file up front.

    - edit:
      edit given jamming-file (fuzzy selection)

    - notes, note:
      For the given jamming-file Invoke your editor to enter or edit the
      notes, that will be shown in "harpwise jam list".
      
      An empty (or whitespace only) note will be removed altogether.


** Quick Start

    #+begin_src 
    harpwise jam along 12
    #+end_src
