Harpwise ('wise' for short) supports the daily practice of scales,
intervals, licks or bends on a diatonic (richter) or chromatic
harmonica for various 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
    many different flavours. This is actually a fun way to start.
  - licks: Learn licks (some included, pointers for more) as a
    starting point for improvisations.
  - jamming: Harpwise helps to jam along a backing-track.

And, less interactive:

  - play: Wise plays scales, holes, licks, intervals, chords, etc.
  - print: Print and annotate the holes of scales or licks given
    on the commandline. Also print various informationo about licks,
    scales and much more
  - tools: Some non-interactive tools related to basic harmonica theory
  - samples: The wise assists in recording your own samples or generates
    them for you; this is a prerequisite for using many 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 'all'; 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.


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:

  <%=types_with_scales%>

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.


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

Commandline 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 sounds or if you see spurious error messages, you may invoke:

     harpwise tools diag

  to execute two basic tests and get some advice.

Quick Start:

  Feedback on what you are playing:
  
    harpwise listen c              

  or:

    harpwise quiz random

  for a fun way to improve your harmonica knowledge

  or:

    harpwise jam along 12

  to jam along a 12bar-blues.


Version <%=$version%>
Copyright (c) 2021-2025 by Marc Ihm (marc@ihm.name) 
This program is subject to the MIT License.
