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

  #+begin_src 
  harpwise listen
  #+end_src

  
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:

  #+begin_src 
  harpwise listen richter c blues
  #+end_src

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

  #+begin_src 
  harpwise listen blues
  #+end_src

or shorter:

  #+begin_src 
  harpwise listen c
  #+end_src

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

  #+begin_src 
  harpwise listen
  #+end_src

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:

  #+begin_src 
  harpwise listen -2 -3 +4
  #+end_src


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.


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.
    #+begin_src 
    harpwise listen
    #+end_src
  - 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

    #+begin_src 
    harpwise listen -o
    #+end_src

  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:

    #+begin_src 
    harpwise tools diag
    #+end_src

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

** Quick Start

  Feedback on holes and notes you play:
  
    #+begin_src 
    harpwise listen c              
    #+end_src

  Improve your harmonica knowledge:

    #+begin_src 
    harpwise quiz random
    #+end_src

  Guided jam along a 12bar-blues:

    #+begin_src 
    harpwise jam along 12
    #+end_src
