Overview
========

  A harmonica tool for the command line, using microphone and speaker.

  Harpwise supports your harmonica practice with scales, chords and
  licks.  It offers various tools, an explorable quiz and may guide your
  jamming.  It can be used with diatonic (richter) or chromatic
  harmonicas in different keys.

  When invoking harpwise, the first argument on the command line
  specifies the mode of operation; it can be one of:

  listen
        The wise listens to your playing (e.g. for scales or bends) and
        helps to steer through a chord progression
  quiz
        Train your ear, memory and knowledge of music theory with more
        than 20 flavours; a fun way to start with harpwise
  jamming
        Scripted jamming along a backing-track
  licks
        Learn licks (some included, pointers for more) as a starting
        point for improvisations

  And, less interactive:

  play
        The wise plays scales, holes, licks, intervals, chords, etc.
  print
        Print and annotate the holes or scales or licks given; in
        general everything, that the wise knows about
  tools
        More then 20 tools for various harmonica needs
  samples
        The wise assists in recording your own samples or generates them
        for you; this is a prerequisite for using some other modes, so
        you will be asked to invoke it, when necessary

  to read more details, usage examples and options for the individual
  modes, invoke them without arguments, e.g.

  ,----
  | harpwise listen
  `----


  After the first argument (which specifies the mode) some additional
  arguments may be given:

  type
        mostly 'richter' or 'chromatic' but other choices might be
        defined. If omitted, this defaults to 'richter'.

  key
        key of harp, e.g. 'c' or 'g' or 'af' (a flat) or 'ds' (d
        sharp). If omitted, this defaults to 'c'.

  scale
        scale on which you want to concentrate, e.g. 'blues',
        'major_pentatonic' or 'full'; defaults to 'blues'.

        Note, that most scales are notated in second position (e.g. key
        of g for a c-harp); you may use the option --transpose-scale to
        change this.

        Also note, that scales can be abbreviated. This is useful for
        harmonica-charts (e.g. in mode listen); a chart shows a
        one-letter abbreviation of the scale, e.g. 'b' for 'blues'; for
        this you may supply your own letter after a colon,
        e.g. 'blues:B', which results in 'B' instead of the default 'b'
        beeing shown in charts.


  Some modes (e.g. listen, licks, play) accept additional arguments on
  the commandline. See their individual usage messages for details (type
  e.g. 'harpwise listen') for details.


  An example using all these arguments would be:

  ,----
  | harpwise listen richter c blues
  `----

  this does listen to your playing, while marking notes from the
  blues-scale.  However, relying on defaults, this could also be written
  shorter as:

  ,----
  | harpwise listen blues
  `----

  or shorter:

  ,----
  | harpwise listen c
  `----

  as 'blues' and 'c' are also the defaults, one might be tempted to
  write even shorter:

  ,----
  | harpwise listen
  `----

  but that would (on purpose) produce the usage-message of mode listen.


  This example would listen especially for the first three notes of the
  blues-scale, which are given as arguments and form an adhoc scale:

  ,----
  | harpwise listen -2 -3 +4
  `----


  The possible scales depend on the chosen type of harmonica:

  scales for chromatic
        blues, blues-middle, chord-i, chord-i7, chord-iv, chord-iv7,
        chord-v, chord-v7, full, mape, one, two
  scales for richter
        blues, blues-middle, chord-i, chord-i7, chord-iv, chord-iv7,
        chord-v, chord-v7, drawbends, full, major, major-full,
        major-pentatonic, mape, mape4, mape5, middle, minor,
        minor-pentatonic, mipe, mixolydian

  Note that advanced users may try to create their own scales. See usage
  of mode tools for an example.


  Besides the arguments for type, key and scale, there are a lot of
  options (introduced by '-' or '--'), some requiring an argument
  themselves. Options are specific for each mode and are described on
  request, i.e. if you give the special option '-o'.

  Also note, that for most modes, the behaviour of the wise (e.g. the
  ways of display or comment) can be changed interactively; type 'h' to
  see help on this.


  A Remark on writing holes: The wise supports different types of
  harmonica (e.g. richter or chromatic), that may have their own way of
  writing holes; however for the most common case of a richter-harp,
  this style and examples apply:

  - Blow-holes are written with a '+', e.g.: +1 +6 +3
  - Draw-holes with a '-', e.g.: -9 -2 -3
  - Bends (both draw and blow) with a '/', e.g.: -2/ -3// +10/
  - Comments in '()' or '[]' or starting with '.' or '~' or a single '|'

  See the initial lickfile (type richter) for more details.


  The wise offers a broad set of features that can support your practice
  for a long time. However, it also has its limitations: The wise
  recognizes single notes and it may play chords for you, but it can not
  identify your chords. It knows a bit about tempo, but has no notion of
  rhythm.


Suggested Reading
=================

  - Usage information for the individual modes, e.g.
    ,----
    | harpwise listen
    `----
  - The top level file README.org, also available at:
    <https://github.com/marcIhm/harpwise/blob/main/README.org>


User Configuration
==================

  ~/harpwise/config.ini


Command-line Options
====================

  Options are specific for each mode; as an example you may type

  ,----
  | harpwise listen -o
  `----

  to read options for mode listen.


Diagnosis
=========

  Harpwise uses the excellent program sox (aka play, aka rec) to
  interact with your sound system. Sox handles all playing and recording
  of sounds.

  However, sometimes, sox might not be configured correctly out of the
  box. If you feel, that sox (and therefore harpwise) has problems with
  sound or if you see spurious error messages, you may invoke:

  ,----
  | harpwise tools diag
  `----

  to execute some basic tests and get advice on how to fix common
  problems.


Quick Start
===========

  Feedback on holes and notes you play:

  ,----
  | harpwise listen c              
  `----

  Improve your harmonica knowledge:

  ,----
  | harpwise quiz random
  `----

  Guided jam along a 12bar-blues:

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