** Overview of 'harpwise tools'

  The mode 'tools' offers some non-interactive but useful utilities,
  which are mostly related to basic harmonica theory; they do not use
  microphone or speaker.

  The required additional argument specifies the tool to run;
  it can be one of:

    - transpose:
      transpose a sequence of holes between keys

    - shift:
      shift a sequence of holes or notes or a single lick by the given
      number of semitones (first argument)

    - shift-to-groups:
      Starts off like 'shift' (see there), but also shows groups of
      alternative holes, that give the same note only in different
      octaves. This can be useful to find variations of a
      hole-sequences, e.g. for improvisation

    - keys:
      For a diatonic harmonica: print a chart with keys and positions
      centered around current key; this tool accepts two optional extra
      arguments, which control coloured emphasis in the otherwise fixed
      chart.  The first argument is the key of the song, the second the
      key of the harp; use '.' to skip emphasising the song.
      
      Use option --brief to print a version shortend to the most common
      keys and position.

    - spread-notes:
      take a list of notes (e.g. a, a4, b, cs) as arguments and turn
      them into a list of holes that produce them. As the octave is
      deliberately not taken into account, you may give "a" as an
      argument just as well as "a4". Also shows these holes in the
      harmonica chart. When invoked with option --brief, this tool can
      be used as a subcommand on the commandline, in which case it just
      returns the list of holes, to be used e.g. as an adhoc-scale.

    - make-scale:
      accepts a list of holes on the commandline, asks some additional
      questions and writes a new user-defined scale.

    - chart:
      various harmonica charts for current key; add option --ref for
      more charts. If you supply holes or notes as arguments (optional),
      only these are printed in the chart of holes and the other charts
      are skipped.

    - notes-major, notes:
      print notes of major scale for given key

    - progression, prog:
      take a base and some semitone diffs, then spell them out

    - interval, inter:
      calculate and print interval between two notes

    - chords:
      print chords i, iv and v for current key

    - transcribe:
      transcribe given audio-file approximately

    - search-holes-in-licks:
      search given sequence of holes (or equiv) in all licks; the same
      ordering of holes is required; this can help to find licks that
      expand on a given sequence of holes

    - search-lick-in-scales:
      search given lick or sequence of holes (or equiv) in all scales;
      ordering of holes is not important; this may give an idea, to which
      of all scales a given lick can be played. See also the somewhat
      inverse tool search-scale-in-licks.

    - search-scale-in-licks:
      search given scale in all licks; this computes the uniq holes of a
      lick and, taking away 0,1,2 ... holes, checks if the remaining holes
      are contained in the scale.  This can give an idea, which licks can
      be played over the given scale (e.g. chord-iv). See also the very
      similar tool licks-from-scale and the somewhat inverse
      search-lick-in-scales.

    - licks-from-scale:
      For all licks, find percentage of holes, that are taken from the
      given scale and group and sort them accordingly.  This may give an
      idea, which of all licks can be played over the given scale
      (e.g. chord-i or blues). See also the very similar tool
      seach-scale-in-licks.

    - translate:
      Recognize and translate alternate harmonica notations into the
      format required for harpwise; e.g. turn "2 (2) 3" into "+2 -2 +3";
      Currently this is optimized for diatonic harmonicas.

    - utils, utilities:
      Describe some utilities, that come with harpwise and need
      to be invoked seperately.

    - edit, edit-licks:
      invoke editor on your lickfile
      optionally add name of lick or lick-progression to land on

    - edit-config:
      invoke editor on your personal config file ~/harpwise/config.ini

    - edit-jam:
      edit given jamming-file. This is much like "harpwise jam edit",
      which however has a more relaxed way of specifying the jam.
      See there for details.

    - diag, diag1:
      help to diagnose problems with your sound system; i.e.
      check that recording and replay work properly.

    - diag2:
      check that mp3 can be played without problems.

    - diag3:
      check that frequencies picked up by your microphone can be
      recognized properly; for this the check 'diag1' should have
      been performed sucessfully first.

    - diag-hints:
      read technical hints on how to fix some of the problems, that
      might have come up with the other diag-tools.

  

** Usage by Examples

  Transpose a sequence of notes (some specified as holes) from
  the key of c to g (keeping the notes/pitches constant):

    #+begin_src 
    harpwise tools transpose c g -1 +2 -3
    #+end_src

  when playing the result on the g-harp you will have the exact same
  pitches as on the original c-harp.


  Shift a sequence of holes up 12 semitones:

    #+begin_src 
    harpwise tools shift 12st -1 +2 -3
    #+end_src

  This is different from transposing the notes/pitches as given
  before, as it changes the pitches of the notes.

  You may then let harpwise play the resulting notes, even if they
  have no hole on the harp (with mode play)


  Print a simple table of keys and positions:
  
    #+begin_src 
    harpwise tools keys
    #+end_src

  Center the semitone-column around a specific key of harp (bf) and
  mark it in the table:

    #+begin_src 
    harpwise tools keys bf
    #+end_src

  The same and mark a key of song (d) too:

    #+begin_src 
    harpwise tools keys bf d
    #+end_src

  If you have a g-harp and want to know what song-keys and positions
  are available:

    #+begin_src 
    harpwise tools keys g g
    #+end_src
    

  Print a harmonica chart for the key of g:

    #+begin_src 
    harpwise tools chart g
    #+end_src

  The same chart, but with arguments rearranged

    #+begin_src 
    harpwise tools g chart
    #+end_src
    
  Two charts, the second with scale-content (chord-i)

    #+begin_src 
    harpwise tools g chord-i chart --add-scales -
    #+end_src

  Four charts, the third and fourth with intervals of each hole to the
  given reference:

    #+begin_src 
    harpwise tools chord-i chart --ref -4
    #+end_src


  How to get the holes of the pentatonic scale in an adhoc fashion:

  Assuming, that you know its notes  g a b d e:

    #+begin_src 
    harpwise tools spread-notes g a b d e
    #+end_src

  the resulting long list of 16 holes may then be used as an adhoc
  scale for mode listen.


  Advanced users, that are not satisfied with the builtin set of
  scales, may want to create their own from a list of holes, e.g.:

    #+begin_src 
    harpwise tools make-scale +1 +2 +3
    #+end_src


  The notes of the major scale starting at c:

    #+begin_src 
    harpwise tools notes c
    #+end_src

  this also gives the notes of the major scale one fifth down,
  i.e. starting at f, so that you may follow the circle of fifths in
  both directions if you wish.


  Print a note progression:

    #+begin_src 
    harpwise tools prog e3 7st 9st oct
    #+end_src

  which will give you all the notes starting at e3 and the 7, 9, 12
  semitones up.
    

  Print the interval over the base note:

    #+begin_src 
    harpwise tools interval c4 oct
    #+end_src

    #+begin_src 
    harpwise tools interval c4 +12st
    #+end_src


  print the chords i, iv and v for the current key:

    #+begin_src 
    harpwise tools chords
    #+end_src


  Transcribe and audio-file given on the commandline approximately:

    #+begin_src 
    harpwise tools transcribe wade.mp3
    #+end_src

  for simple harmonica content this will give you sequence of holes
  played in lick wade.mp3 (from current working dir)
