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.:

  ,----
  | harpwise jam along 12bar
  `----

  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:

  ,----
  | harpwise listen --scale-prog 12bar --lick-prog box1 --jamming
  `----

  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:

  ,----
  | harpwise jamming list
  `----

  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.:

  ,----
  | harpwise jam along 2b       
  `----

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

  ,----
  | harpwise jam along 2b r
  `----

  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:

  ,----
  | harpwise jam g along 12bar
  `----

  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
===========

  ,----
  | harpwise jam along 12
  `----
