# -*- fill-column: 74 -*-
#+SETUPFILE: floating_toc.theme
#+OPTIONS: toc:t
#+TITLE: Harpwise

/Version  6.32.1/

* Introduction

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

  [[../images/harmonica3.png]]
  
  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.

  It runs on the command line of Linux and WSL2/Windows and probably
  MacOS.
  
  Its main operation modes are 'listen', 'jamming', 'quiz' and 'licks';
  these may help to:

  - Learn scales and intervals
  - Jam through a chord progression guided by scales and licks
  - Learn and memorize licks (a few samples included)
  - Train your ear and musical memory and learn related
    music theory by the way of quiz

    
  Some of the other things, that harpwise can do:

  - Help to find the key of a song (with an adjustable pitch)
  - Interactively play intervals or note progressions
  - Help in writing down a sequence of holes (journal)
  - Work on bends or warbles
  - Transpose a sequence of holes from one key of harp to another
  - Provide an overview table of positions and keys of songs and harp
  - Print notes layed out on a harmonica chart
  - Print or play chords or scales
  - Show full help on its usage
  
* A note for Beginners
  
  'richter' is the most common and affordable type of harmonica and the
  default for harpwise.  It has 10 holes but no slider and is also known
  as the 'blues harp'.  A single harmonica (e.g. in the key of c or a) is
  enough to get started.  This program (harpwise) by itself does not teach
  you how to play harmonica; rather it is a tool and meant to be helpful
  and motivating all along your learning-journey.  Start with: 'harpwise
  listen c'.

* Screencasts
    
  The screencast below, shows how harpwise (mode 'listen') reacts on holes
  beeing played and how it can help to write them down. No sound has been
  recorded however, so please imagine some holes beeing played.
  
  [[../images/harpwise-listen.gif]]
  
  The second screencast is from mode 'quiz', showing three of the many
  flavours: hear-key, players and keep-tempo.
  
  [[../images/harpwise-quiz.gif]]

* Installation

  The latest version of harpwise is a available as a snap. This is the
  preferred way of installing harpwise under linux.

  Ubuntu and related distributions make this especially simple:

  #+begin_src
    sudo snap install harpwise
    harpwise
  #+end_src

  this works quite well for WSL2/Windows too.
  
  For Fedora and its derivatives, you first need to install the snapstore itself:

  #+begin_src
    sudo dnf install snapd
    sudo snap install harpwise
    /var/lib/snapd/snap/bin/harpwise
  #+end_src
  
  And you may want to add /var/lib/snapd/snap/bin to your PATH
  permanently.
  
* Invoking harpwise

  Harpwise is a commandline-program, so you need to open a termnal. The
  terminal should have black (or dark) background to match the colors used
  by harpwise. It should use a fixed-width font.
  
  Please note, that harpwise adapts to different screen (terminal)
  sizes. If you resize the terminal-window (assuming that you have a
  grafical desktop), then harpwise will react accordingly and you do not
  need to restart it.

  You will get the best experience with larger font and a terminal of
  modest size, e.g. 90 cloumns and 30 rows.

  Also note, that harpwise uses figlet to display some information
  (e.g. the note beeing played) in large letters. For this, your
  terminal-font needs to include the unicode Box-drawing characters (see
  https://en.wikipedia.org/wiki/Box-drawing_characters#Block_Elements).

  With that, and if harpwise is installed correctly, invoking harpwise is simple:

  #+begin_src
    harpwise
  #+end_src

  this will issue a text on using harpwise, that you may also read in the
  next section of this page.

* Getting started with harpwise

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

- 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.
    #+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


* The Modes of harpwise

  These correspond with the broad use cases of harpwise. On the
  commandline the mode comes as a the second argument, e.g. 'listen' in
  'harpwise listen'.
  
* harpwise listen

  [[../images/harpwise-listen.gif]]
  
** Overview of 'harpwise listen'

  The mode 'listen' shows information on the notes you play; depending
  on settings for display and comment this can be:

    - Hole
    - Note
    - Membership of played note in various scales
    - Interval to previous note
    - Difference to a reference note, e.g. to practice bends
    - Speed of warbles

  When playing, you may switch on journal to get a simple
  transcription of the holes played.


** Usage by Examples:

  The wise listens, while your are playing a richter harp of key c and
  it shows the holes, that you played; green if from the blues-scale,
  blue otherwise:

    #+begin_src 
    harpwise listen richter c blues
    #+end_src

  The same, but relying on the defaults for type (richter) and key (c):

    #+begin_src 
    harpwise listen blues
    #+end_src

  The same, but also showing the notes from the one-chord (chord-i):

    #+begin_src 
    harpwise listen blues --add-scales chord-i --display chart-scales
    #+end_src


  If you want to follow the chord-progression of a 12-bar blues, you may try

    #+begin_src 
    harpwise listen --scale-progression 12bar
    #+end_src

  to switch from one chord to the next, every time you press 's'.

  To use the RETURN-key, which might be easier to hit, you may try:

    #+begin_src 
    harpwise listen --scale-prog 12bar --keyboard-translate RETURN=s
    #+end_src

  or use (shorter) '--kb-tr TAB=s' to employ the TAB key. And you may
  also make this option durable in your config.ini.

  If, in addition to the scale-progression, you want one or more licks
  at hand (e.g. turnarounds), you may give them as an adhoc
  lick-progression:
  
    #+begin_src 
    harpwise listen --scale-prog 12bar --lick-prog simple-turn,wade
    #+end_src


  As an advanced example, assume that you would like to play the minor
  pentatonic scale in fourth position. However, harpwise only knows it
  in second position (i.e. starting on -2).

  How would you move this scale from second to fourth position?

  The first step would be to get the notes of the minor-pentatonic
  scale:

    #+begin_src 
    harpwise print mipe
    #+end_src

  then take those notes and shift them from second to fourth position
  by moving up two fifths up in the circle of fifths.

  And because a fifth is 7 semitones (you may check this via: harpwise
  print intervals), this would be 2 * 7 = 14 semitones.

  In addition one would move one ocatve (= 12 semitones) down to reach
  the lower end of the harp (for more expressiveness): 14 - 12 = 2
  semitones.

  So we would have to shift the notes of the minor pentatonic scale by
  2 semitones to get from second to fourth position:

    #+begin_src 
    harpwise tools shift +2st -2 -3/ +4 -4 -5 +6
    #+end_src

  Using the resulting holes as an adhoc scale for listen, we would be
  able to tell harpwise, that we want to play the minor pentatonic in
  fourth position:

    #+begin_src 
    harpwise listen -3// +4 -4 +5 +6 -6
    #+end_src

  However, you could get the same effect also like this:

    #+begin_src 
    harpwise listen mipe --transpose-scale +2st
    #+end_src

  which uses the fact (as explained above), that moving two positions
  up are just two semitones.


  Finally, as a quite technical note: If you find harpwise sluggish or
  if you get a warning on lagging and lost samples, you may want to
  experiment with --time-slice:

    #+begin_src 
    harpwise listen c --time-slice short
    #+end_src

** Quick Start

    #+begin_src 
    harpwise listen c              
    #+end_src


* harpwise quiz

  [[../images/harpwise-quiz.gif]]
  
** Overview of 'harpwise quiz'

  The mode 'quiz' is a quiz on music theory, ear and memory. It is meant
  as a fun way to increase your musical abilities. Quiz comes in different
  flavours (see below). It issues questions and asks for answers.

  All flavours offer various sorts of help, allowing to view and explore
  the question at hand from a different angle.

  If you invoke mode 'quiz' with the argument 'random' (or 'ran'), a
  flavour is chosen at random. To try another flavour, just restart
  harpwise, e.g. by pressing ctrl-z.  For a chosen flavour, different
  questions of this flavour are asked in an endless loop.
  
  There are 30 flavours of quiz
  listed below; however, you do not need to memorize them, as they will be
  explained on the spot when they appear during the quiz.

  For an overview, here are the available flavours:

    - all, ran, random:
      any and all flavours, one at random

    - scales:
      flavours related with scales

    - mic:
      flavours, that use the microphone; most of them switch to
      listen-perspective

    - no-mic:
      flavours, that do not use the microphone, so that no harp is
      needed; but these flavours are not necessarily silent and may
      still play sounds themselves

    - silent:
      flavours, that can be tried with muted speakers, although some
      of the help might not be as useful

    - inters:
      flavours, that revolve around intervals

    - layout:
      flavours, that deal with the layout (holes to notes) of the harp

    - players:
      harpwise shows details about a famous player and asks for his or
      her name

    - hear-scale:
      harpwise plays the holes of a scale and asks for its name

    - not-in-scale:
      harpwise picks a scale at random and modifies it: holes are
      shuffled and one is replaced with a foreign hole; this modified
      scale is played and you should find the foreign hole. The holes
      are disguised as h1, h2, and so on

    - match-scale:
      plays a random sequence of holes, that are either a subset of one
      or many scales and asks for the name of the single or shortest
      scale containing all these holes

    - play-scale:
      gives the name of a scale and asks to play it

    - hear-inter:
      plays an interval and asks for its name

    - inter-song:
      names an interval and ask for the mnemonic-song that starts with
      this interval. Or the other way around from song to interval

    - add-inter:
      gives a hole and an interval and asks for the resulting hole,
      which is obtained by either adding or subtracting

    - play-inter:
      names a hole and an interval which resolves to a hole; then asks
      to play back both holes

    - tell-inter:
      names two holes and asks for the interval between

    - hear-key:
      picks a random key and its matching note (from octaves 4 or
      5); plays a sequence of notes starting from this note; asks for
      the key

    - hear-hole:
      picks a random key and a named hole-set; then plays a hole from
      this set and asks for its name

    - play-shifted:
      wise computes a sequence of holes, that can be shifted by an
      interval; it plays the original unshifted sequence and names and
      plays the first hole of the shifted sequence; then you should play
      BOTH the unshifted and shifted sequence together

    - key-harp-song:
      gives a key of harmonica and asks for the matching
      key of song (2nd position) or vice versa

    - hole-note:
      the wise picks a harp-key then gives a hole and asks for the note
      or vice versa

    - hole-note-key:
      picks (and hides) a new key for the harp at random; then, for a
      named hole-set (e.g. 'blow'), gives holes and matching notes
      (which depend on the hidden key of harp); then asks for the key

    - hole-hide-note:
      picks a new key at random and a named hole-set; then shows the
      hole-set, but hides one note; then asks for the hidden note

    - hear-hole-set:
      picks a new key at random and a named hole set; then plays it,
      holes hidden; then asks for the key and the hole set

    - keep-tempo:
      plays a number of beats defining a certain tempo; then some
      silence and then some final beats. You are expected to play along
      and keep the given tempo throughout; harpwise records your playing
      and checks, how well you kept the tempo

    - hear-tempo:
      plays a tempo and asks for its bpm

    - replay:
      harpwise plays a sequence of holes and asks you to play it back

    - hear-chord:
      taking the harp key as base, the wise chooses a chord (e.g. IV)
      then it plays the base note as well as the chord. You are expected
      to identify the chord. For difficulty HARD there are additional
      chords and for some chords also variations

    - choose:
      choose flavour interactively
      (only as extra-argument on commandline)

  
** Usage by Examples

  The wise chooses a quiz-flavour at random (key of c):

    #+begin_src 
    harpwise quiz c random
    #+end_src

  this is the preferred way to get used to this mode.

  To switch to a different, random mode, issue signal ctrl-z.


  Some examples that choose a quiz flavour or a collection of flavours
  explicitly:
  

  Wise plays 5 notes from the scale major_pentatonic for a
  chromatic harmonica of key a and then asks you to play them
  back (then repeat):

    #+begin_src 
    harpwise quiz chromatic a blues replay 5
    #+end_src

  In the examples above, the type of harmonica (e.g. richter or
  chromatic), the key (e.g. c or a) or the number of holes may be
  omitted and are then taken from the config or defaults; so

    #+begin_src 
    harpwise q major replay
    #+end_src

  is valid as well (but would choose a richter harp).


  This example chooses the a flavour-collection:

    #+begin_src 
    harpwise quiz no-mic
    #+end_src

  the collection 'no-mic' includes a number of different flavours, which
  have in common, that they do not need your microphone and do not require
  you to play your harp. This can be helpful e.g. when quizzing in public
  transport.


  Wise plays a scale and asks you for its name:

    #+begin_src 
    harpwise quiz hear-scale
    #+end_src

** Quick Start

    #+begin_src 
    harpwise quiz ran
    #+end_src


  And at any time type 'ctrl-z' to try another flavour.


* harpwise jamming

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

    #+begin_src 
    harpwise jam along 12bar
    #+end_src

  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:
  
    #+begin_src 
    harpwise listen --scale-prog 12bar --lick-prog box1 --jamming
    #+end_src

  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:

    #+begin_src 
    harpwise jamming list
    #+end_src

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

    #+begin_src 
    harpwise jam along 2b       
    #+end_src

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

    #+begin_src 
    harpwise jam along 2b r
    #+end_src

  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:

    #+begin_src 
    harpwise jam g along 12bar
    #+end_src

  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

    #+begin_src 
    harpwise jam along 12
    #+end_src


* harpwise licks

** Overview of 'harpwise licks'

  The mode 'licks' helps to learn and memorize licks.  Typically it
  plays a random lick from your collection and asks you to play it
  back, note by note. If successful, the next lick will be asked for.

  For harpwise, a 'lick' is a short musical phrase with a sequence of
  holes and an mp3-recording. It will be transposed as necessary.

  Please Note: This mode relies on a collection of licks, that you need
  to accumulate over time; only a simple starter set will be created at
  first start; typically it will be kept at:
  ~/harpwise/licks/richter/licks_with_holes.txt similar e.g. for
  chromatic.

  When adding licks and you need to adjust start and end of the
  recording, the mode 'play' might help, to check your results.

  You may want to collect licks, that you dig and even pay for some good
  lick collections until you tens or hundreds of licks, that sound good.
  Once having that many licks, you may want to categorize them with tags
  (e.g. for artist or style). Harpwise helps with this by adding some
  automatic tags (see below); in addition there are some tools to select
  licks based on their affinity to a given scale or chord.

  If you get comfortable with a lick and want to explore it beyond its
  written wholes, you may find it useful to switch to mode listen,
  which can be done by typing 'm' without stopping the wise first.
  
** Usage by Examples

  Play licks from your collection; transpose them (i.e. their
  recordings) to the key of c, if necessary:
  
    #+begin_src 
    harpwise licks c
    #+end_src


  Similar, but only choose from licks with tags 'fav' and 'has-rec'

    #+begin_src 
    harpwise licks c --tags-all fav,has-rec
    #+end_src

  this employs the automatic tag 'has-rec', which is added to each
  lick, that has a recording. The opposite is 'no-rec'.


  Another automatic tag is 'shifts-four', which is added to each lick,
  which, when shifted by a major fourth, can still be played on the
  chosen harmonica. Similar tags are 'shifts-five' and 'shifts-eight'.

  So

    #+begin_src 
    harpwise licks a -t shifts-four,shifts-five
    #+end_src

  selects all licks, that can be shifted by four or five notes without
  loosing any hole; these licks may therefore accompany a
  blues-progression alone. The keys used to actually shift those licks,
  are described in the help-screen (type 'h').
  

  Similar, but only choose from licks with tags 'fav' or 'scales'

    #+begin_src 
    harpwise licks c --tags-any fav,scales
    #+end_src


  Show the licks selected by the previous example, employing the
  mode 'print':

    #+begin_src 
    harpwise print licks-list --tags-any fav,scales
    #+end_src


  To find licks, that are mostly (i.e. all holes or all but one)
  contained in the chords chord-i, chord-iv or chord-v, use the
  respective automatic tags, e.g.:

    #+begin_src 
    harpwise licks c -t mostly-chord-v
    #+end_src

  currently there are 5 automatic 'mostly'-tags for scales
  chord-i, chord-iv, chord-v, blues and mipe.
  

  Select licks (if any), that have been starred by pressing '*' while
  it is beeing or has been played played:

    #+begin_src 
    harpwise licks a -t starred
    #+end_src

  and use mode print to see details about starred licks.
  The list of starred licks is kept e.g. in:

    ~/harpwise/licks/richter/starred.yaml


  There are some more options to *filter* the set of available licks
  (see below); see also the lick-file created initially on more
  explanation on the concept of tags.
  
  Here is a more sophisticated example. It helps to memorize licks,
  but not scales and shows the scales for each hole:

    #+begin_src 
    harpwise licks c blues --loop --imm --drop-tags-any scales \
        --add-scales chord-i,chord-iv,chord-v \
        --display chart-scales --comment holes-all
    #+end_src

  However, if you find yourself using these options for mode licks
  over and over again (and if you do not want to set them
  interactively, once the wise is running) you may move them to your
  config.ini and shorten the above command line to:

    #+begin_src 
    harpwise licks blues
    #+end_src


  Alternatively to using the tag-options described above, you may give
  licks as arguments on the commandline (especially for a 12-bar blues):

    #+begin_src 
    harpwise licks box1-i box1-iv box1-i box1-v box1-iv box1-v box1-i simple-turn
    #+end_src

  would start with the lick box1-i and switch from one to the next per your
  request; all other licks that you may have (e.g. wade, st-louis) are ignored.

  Note, that the lick box1-i (e.g.) appears more than once in the
  commandline above, because during a 12-bar blues, this chord appears
  multiple times.


  If you find yourself using such a commandline as given above over
  and over, you may define them as a lick-progression in your
  lick-file (see there for explanation); a predefined example could be
  used like this:

    #+begin_src 
    harpwise licks --lick-progression box1
    #+end_src

  knowing these licks in and out would allow for basic accompaniment
  of e.g. a 12-bar blues.


  This option can fruitfully be combined with a scale-progression:

    #+begin_src 
    harpwise licks --scale-prog 12bar --lick-prog box1
      --kb-tr RIGHT=s+RETURN,LEFT=S+L
    #+end_src

  which employs the key 'RIGHT' to switch both scale-progression and
  lick-progression at once; whereas 'LEFT' resets them to their
  initial values.
  

  If you want to explore a single lick, that is not yet in your
  lick-file (take +1 +2 +3 as a simple example), you may specify it
  adhoc by giving its holes on the commandline:

    #+begin_src 
    harpwise licks +1 +2 +3
    #+end_src

  later, if satisfied, you may add this lick (and maybe a recording)
  to your lickfile.


* harpwise play

** Overview of 'harpwise play'

  The mode 'play' takes its arguments (holes, notes, semitones, licks,
  scales) and plays them.  It also handles some extra keywords.

  Its arguments (which mostly can not be mixed) can be any of these:

    - holes (e.g. '-1') or notes
    - notes (e.g. 'a4')
    - semitones (e.g. '+12st')
    - licks (e.g. 'st-louis')
    - lick progressions
    - scales (e.g. 'chord-i')
    - jams, i.e. its mp3
    - 'l', '2l', for the last lick, 2nd-to-last, etc.

  or one of the known extra arguments (that themselves might require
  additional arguments):

    - licks:
      all licks selected (e.g. by option -t). Add option '--lick-radio'
      to make harpwise play licks without interruption (but repeats);
      as an optional argument you may give the number of repeats

    - pitch:
      play an interactive, adjustable pitch; this may help to find the
      key of a song by ear-comparison; the initial key, e.g. 'a4' can be
      supplied as an optional argument

    - interval, inter:
      interactive, adjustable interval given as arguments

    - progression, prog:
      take a base and some semitone diffs, then play it in a loop,
      allowing e.g. to shift each iteration by some semitones e.g.
      through a chord-progression of i-iv-v. Moreover you may specify
      two or more progressions with a dot (.) between; those can then
      be switched for each iteration.

    - chord:
      play the given holes or notes simultanously as a chord; also
      useful for tongue-splits.

    - user:
      play back (if any), what you (the user) have recorded in mode
      'licks' before



** Usage by Examples

  Play a few holes and notes on a harp of key c:

    #+begin_src 
    harpwise play c +1 -2 c4
    #+end_src

  Play a few semitones:

    #+begin_src 
    harpwise play c +1st -4st
    #+end_src

  Play the lick 'wade'; transpose it to d:
  
    #+begin_src 
    harpwise play d wade
    #+end_src

  Play an earlier lick:

    #+begin_src 
    harpwise play 3l
    #+end_src

  To see a list of earlier licks:

    #+begin_src 
    harpwise print licks-history
    #+end_src


  Various ways to play all licks:

  Shuffled and in random order, without end:

    #+begin_src 
    harpwise play licks
    #+end_src

  or play them one after another as they appear in your lickfile:

    #+begin_src 
    harpwise play licks --iterate cycle
    #+end_src

  or shorter:
  
    #+begin_src 
    harpwise play licks -i c
    #+end_src

  Only play favorite licks (tag 'fav'):

    #+begin_src 
    harpwise play licks --tags-all fav
    #+end_src

  or shorter:

    #+begin_src 
    harpwise play licks -t fav
    #+end_src

  Play licks from a progression:

    #+begin_src 
    harpwise play licks --lick-prog box1
    #+end_src

  Play endless, no questions asked, but various controls available:

    #+begin_src 
    harpwise play licks --lick-radio
    #+end_src


  Play an interactive, adjustable pitch:

    #+begin_src 
    harpwise play pitch
    #+end_src

  this may help to find the key of a song that is playing: change the
  pitch by semitones, fiths or octaves until both match.

    #+begin_src 
    harpwise play pitch c
    #+end_src

  Exactly the same result as above, but with the key of c given
  explicit. This will actually start of playing g, the root note in
  second position (cross-harp).

  Note: As an alternative, you may try to hum the root note (or tonal
  center) of the song to find its key. Which is the preferred method,
  because it does not need a computer; but this command may help to
  get you started anyway.


  Play an interval:

    #+begin_src 
    harpwise play inter c4 d4
    #+end_src

  while this is beeing played you may move it around or widen or
  narrow it by semitones.

  There are multiple ways to specify an interval:
  - Either as two notes or holes
  - Or as one note or hole plus one interval (named or as semitones)

  So these are more ways to play an interval:

    #+begin_src 
    harpwise play inter c4 12st    ## Note c4 and 12 Semitones
    #+end_src

    #+begin_src 
    harpwise play inter +2 pfi     ## Hole +2 and a perfect fifth
    #+end_src

  The error message (if any) will list valid values.


  Play a note progression:

    #+begin_src 
    harpwise play prog e3 7st 10st oct
    #+end_src

  this plays the classic box pattern interactively, you may loop it or
  shift it by semitones. Holes for the harmonica (if any) are printed
  along.

  A similar progression would be:

    #+begin_src 
    harpwise play prog +1 5st 7st 10st
    #+end_src


  Building on the above, you may want to use the box pattern and the
  interactive features of 'harpwise play prog' to play (sort of) a
  full 12-bar blues: Start with the progression above, switch on loop
  and let it repeat 4 times (i.e. for 4 bars); this is the
  i-chord. Then shift by 5 Semitones up or 7 down, to get the
  iv-chord, and let this play another two times; then 5 semitones down
  to get the i-chord again, then 7 etc., etc. until all 12 bars have
  been played.

  If you want to switch between multiple progressions, separate them
  by a dot ('.') like so (using both progressions from above):

    #+begin_src 
    harpwise play prog e3 7st 10st oct . +1 5st 7st 10st
    #+end_src


  Alternatively (and without using the progression feature) you may
  get a similar result by playing predefined licks. As harpwise comes
  with licks of the 'box pattern' for chords i, iv and v, you may ask
  the wise to play the bass-line of a 12-bar blues like this:

    #+begin_src 
    harpwise play box1-i box1-i box1-i box1-i box1-iv
      box1-iv box1-i box1-i box1-v box1-iv box1-i simple-turn
    #+end_src

  which also uses the simple-turn lick at the end; you may also
  replace 'box1' with 'box2' for a variant.


    #+begin_src 
    harpwise play boogie-i boogie-i boogie-iv boogie-v boogie-iv boogie-i simple-turn
    #+end_src

  which might be a starting point for improvisation.


  Another way of playing would be:

    #+begin_src 
    harpwise play chord +1 +2 +3 -3/
    #+end_src

  plays the given holes (notes may be given too) simultanously; the
  given example is (by the way) a flat-seventh-chord, what you may
  find out by using print:

    #+begin_src 
    harpwise print +1 +2 +3 -3/
    #+end_src


  If you record yourself during lick-practice,

    #+begin_src 
    harpwise play user
    #+end_src

  plays what you have recorded before in mode 'licks' (where you need to
  trigger the recording explicitly).


* harpwise tools

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


* harpwise samples

** Overview of 'harpwise samples'

  The wise needs a set of audio-samples; these are the sounds-files
  (recorded or generated) of each of the holes of your harmonica;
  blow, draw, bend.
  
  The samples are used to:
  
  - Play a series of holes, e.g. for modes play or quiz
  - Judge the frequencies of your playing against the frequencies of the
    samples to find out, which note you are actually playing

  You may either record those samples under the guidance of this mode,
  or you may let the wise generate them for you; adding some helper
  functions, this gives the following choice of extra arguments:

    - record:
      harpwise assists while you play the holes for the given type and
      key of harmonica. After each recording you may hear back and trim.
      
      These samples capture your style of playing and the specific sound
      of your harmonica as far as possible and brings them into
      harpwise. This way of creating samples gives more interesting
      results than 'generate' but requires some work from your side;
      consider recording the most important keys (or even holes) first
      and use 'generate' for the others. Even 'generate all', as your
      recordings would not be overwritten.
      
      To redo the recording for a single hole, give it as an argument on
      the commandline.
      
      You may even combine this method of recording hole-samples with
      'generate', as your recorded samples will be kept and preferred
      over generated samples unless you explicitly use the extra-command
      'delete'.

    - generate:
      as a faster alternative to 'record', you may let harpwise generate
      samples for each hole.  This gives fast results, that, however
      lack the typical harmonica sound.  You may try different waveforms
      (e.g. 'sine') with option --wave (with a default of 'pluck').
      
      To generate samples for all keys in one pass, you may give 'all'
      as an additional argument; otherwise samples are created for the
      current key only.
      
      'generate' never overwrites samples that you play during 'record';
      use 'delete' for this, if required.

    - check:
      For the current type and key of harmonica, check out and summarize
      available samples; especially show, which samples have been
      recorded and which ones generated. Use 'all' to get a summary for
      each and every key.

    - delete:
      For the current key, ask for confirmation to delete your recorded
      samples, if any. As these recorded samples had precedence over any
      generated samples, this might be necessary to make harpwise use
      the generated samples (or maybe suggest to use 'generate' first).
      
      This can be useful, if you prefer the (maybe) more precise samples
      that harpwise generates.
      
      By giving the argument 'all' you may delete all samples for all
      keys.



  The samples need to be generated for each key, but only once in the
  lifetime of your harp; you may start with the key of c only.
  After that you are ready to use the other modes of the wise.

  Samples that have been recorded will not be overwritten with
  samples, that the wise generates.  Moreover, recorded samples are
  always preferred over generated samples, when harpwise has to play
  holes; remove recorded samples, if (for the moment) you prefer
  generated samples.
  
  By its nature, this mode only accepts arguments for type and key,
  but not for scale.
  

** Usage by Examples

  Record samples to teach the wise abut the frequencies of the harp
  you are using:

    #+begin_src 
    harpwise samples c record
    #+end_src

  this will ask you to play notes on your harp (key of c). The samples
  will be stored in the folder harpwise within your home
  directory; frequencies will be extracted to the file
  frequencies.yaml.

  You may cancel the process of recording samples after any hole whle
  still keeping the samples recorded so far (but you may 'delete'
  them, if you choose). If later, you want to continue recording from
  where you left, simply give the respective hole as an argument, e.g.

    #+begin_src 
    harpwise samples c record +4
    #+end_src


  If at a later time, you just want to review the samples, you have
  created, simply use play, e.g.:

    #+begin_src 
    harpwise play +4
    #+end_src

  or even:

    #+begin_src 
    harpwise play full
    #+end_src


  Compared with the process of recording samples, the alternative of
  generating samples automatically is the quickest way to get started.
  The wise may create all the audio samples for you (using sox);
  however, this cannot match the characteristics of your own harp and
  your own playing style, but it gives a good quick start.  For
  auto-generation, type:

    #+begin_src 
    harpwise samples a generate
    #+end_src


  Or, to generate everything, all holes, all keys, in a single run:

    #+begin_src 
    harpwise samples generate all
    #+end_src

  With this, only when first changing the type of harmonica, e.g. from
  richter (default) to chromatic, you will need to create samples
  again.


  If later, you want to remove some samples, that you have recorded
  previously, try (for the key of d):

    #+begin_src 
    harpwise samples d delete
    #+end_src

  this applies to recorded samples only; there is no need to delete
  generated samples, as they can allways be generated and overwritten
  or shadowed by recorded samples.

                  
* Command-line options

  The command line of harpwise accepts a broad range of options; many of
  them are specific for one of the modes of harpwise (e.g. 'harpwise
  listen').

  Many of the options appear in the usage-examples for the individual
  modes. However for a comprehensive list, invoke with the option '-o'.
  E.g. for mode 'listen' type:

  #+begin_src
    harpwise listen -o
  #+end_src
  
  this will give you a long colored, list of all options, that 'harpwise
  listen' accepts. The list will contain options, that are specific for
  mode 'listen' (.e.g '--display' or '-d') as well as options, that can be
  applied to many (or all) modes (e.g. '--sharps').

  If you only want to read the description of a specific option
  (e.g. '-d'), you may add it to the command line right away, e.g.:

  #+begin_src
    harpwise listen -o -d
  #+end_src
  
* A closer look at the Screen (mode listen)

  The Screenshot below is from mode listen. This view presents a lot of
  information about the holes you are playing, including their musical
  context. Note the added line-numbers, that will be used in the
  explanations below.
  
  #+begin_src text -n
Play from 4 scales                              SPACE to pause; h for help
listen richter c blues,1,4,5
                                                    4     full bend
                                          -    5    1     half bend
      b4    4   b14  b45   4   b14  b45   4   b14  45     blow

     --1----2----3----4----5----6----7----8----9---10---------

      b5   b14   1   b15  b1   b5    1   b15  b1   b5     draw
       b    5   b4    b         b                         half bend
            b    5                                        full bend
                 -                                         3/2 bend
Hole:    +4, Note:   c5, Ref:   --
Frequency:   531.0 Hz,   26 Cnt  [.........:....I....]
Interval:   +4  to   +1  is 12 st  , Octave

                               ▄▄▄▄▄
                         ▄▄▄   █
                        █▀  ▀  ▀▀▀▀▄▄
                        █           █
                        ▀█▄▄▀  ▀▄▄▄█▀


Featuring Sonny Boy Williamson
  #+end_src
  
  Now if you start harpwise e.g. in mode listen, or licks or some flavours
  of quiz, you get a screen as shown in the screenshots above.

  Its structure is as follows (top to bottom):

  - Header, the first two lines 1 and 2
  - The 'display', lines 3 to 12
  - The middle part of the screen, lines 13 to 15
  - The 'comment', lines 16 to 22
  - Footer, the two bottommost 2 lines, 23 and 24

** The header

   Two topmost two lines, that show e.g.
   
   - The current mission, i.e. what you are supposed to do; in the example
     this is simply 'Play from 4 scales'.
   - As a special case, when mode 'listen' takes part in a jam, this line
     shows your exact position within the scale progression (iteration,
     chord and second)
   - In the top-right corner you get immediate feedback on keys beeing
     pressed or a hint on how to get help
   - A summary of the current settings: mode, harmonica-type, key and
     scales

** The 'display'

   This part of the screen (i.e. most of its upper half) shows different
   versions of a harmonica chart as known from textbooks. In addition, the
   holes, that you are playing are highlighted in colours according
   to the scale.

   To change the display type 'd' repeatedly or type 'D' to get a menu
   with descriptions.

** The middle part of the screen

   The three middle lines of the screen show:

   - The hole and note, that you are playing and the reference hole, if
     set (see [[*The reference hole][The reference hole]])
   - Starting with "Frequency:": The Frequency (in Herz), that you are
     playing; also the deviation in cent and a small frequency gauge; both
     relative to the exact frequency of the hole played
   - Starting with "Interval": The interval of the current hole to the
     reference hole or to the last hole played
        
** The 'comment'

   This part of the screen (i.e. most of its lower half) shows comments.
   E.g. when in mode licks, harpwise expects you to play a sequence of
   holes, the comment-region shows the sequence of holes that you have
   already played or are expected to play.

   In the example-screenshot, the comment shows the note beeing played in
   large letters: c5

   To change the comment type 'c' repeatedly or type 'C' to get a menu
   with one-line descriptions.

** The footer

   Within those two lines at the bottom, harpwise shows hints and issues
   various remarks on its operation.

   For example:
   
   - In mode licks, details about the current lick
   - In mode listen, if idle, notes about famous harp-players

* Getting help

  Within harpwise, you may press 'h' to get help on the keys, that are
  currently accepted.

  This page https://marcihm.github.io/harpwise/ collects all other written
  documentation (overview, background, usage, concepts, etc.).
  
  If you still have problems, questions or just want to give feedback,
  please drop me a note: marc@ihm.name

  If you have a github-account and prefer a more structured approach, you
  may also open a github-issue at https://marcihm.github.io/harpwise/
  
* Configuration

  This is the user-modifyable configuration file, that will be created on
  first invocation:

  #+begin_src
    ~/harpwise/config.ini
  #+end_src

  There you may override many settings and program defaults or store
  options, that you use frequently.  The file is commented extensively, so
  that you read there for details on the various settings. Initially this
  config-file is a copy of harpwise central config-file.

  See also the usage-information of the various modes, which list all of
  the command line options, that (in many cases) mirror the settings from
  your config.ini.

* Some musical concepts
** Scales

   Scales, e.g. 'blues' or 'major pentatonic' or 'chord-i' are central for
   playing the harmonica. E.g. when improvising, you may stick to a
   specific scale.

   Therefore, harpwise shows information about the scales, that a given
   hole belongs to; it can also play scales or print their content or quiz
   you about them.

   For this to work best, you may:

   - Give the name of your favorite scale as an argument when starting
     harpwise. The default is often 'blues', but you may also use
     e.g. 'mape' (for major pentatonic). Use 'harpwise print scales' to
     learn about the available scales.
   - To include other scales beyound the main scale, you may add the
     option --add-scales on the commandline, e.g.  '--add-scales
     chord-i,chord-iv,chord-v' In many modes of harpwise you may rotate
     among scales by pressing 's'.


   So a typical invocation would be:

   harpwise listen c blues --add-scales chord-i,chord-iv,chord-v

   which shows, which of the four given scales the notes you play belong
   to respectively. This command line may be shortend by moving the option
   --add-scale to your configuration.

   
   The wise already comes with a large set of scales; but if you still miss
   something, you may create your own using the tool make-scale.

   You may even use an adhoc-scale by giving its holes on the commandline;
   see mode listen for an example.

** Licks

   Licks help you to grasp the style and ideas of other players. Harpwise
   allows to build and organize a whole collection of licks. For each lick
   there is a recording and the sequence of holes that (mostly) make it
   up.

   Out of the factory, harpwise only has a few older licks with expired
   copyright and amateur recordings; an example would be a lick from the
   St-Louis blues.

   To work fruitfully with licks, you should record your own or buy some
   decent lick collections (me beeing not connected with any of those).
   See your lick-file for pointers and instructions:

    ~/harpwise/licks/richter/licks_with_holes.txt
    
* Some technical concepts
** The reference hole

   The wise can remember a hole that you have played and later refer to
   it; this is useful e.g. to show the interval between the current hole
   and the reference, or to show the deviation from the currently played
   frequency to the nominal frequency of the hole, e.g. when practicing
   bends.

   To set the reference, you simply play the desired note and hit the key
   'r' at the same time. To clear the reference you just hit 'r' when not
   playing anything.

** When multiple holes produce the same note

   Many harps produce identical notes on certain holes; e.g. the diatonic
   harmonica on holes -2 and +3. There are even more cases e.g. for a
   chromatic harmonica.

   Harpwise cannot distinguish between such holes either and treats them
   alike in all aspects (display, quiz, notation).

   For writing down licks however, you are free to use any of those
   multiple holes.

** Tuning

   The harp wise does not make assumptions about the tuning of your
   harmonica; e.g. it works equally well with 'equal temperament' (ET) or
   'just intonation'.  Simply because, it asks you to play your own harp
   to generate samples (whatever its tuning might be). It then computes
   frequency values from these samples. (Remark: for a quick start you may
   have skipped this step using automatic sample generation)
  
   However, sometimes harpwise has to choose one tuning, e.g. when doing
   sample generation or when your samples need to be judged against some
   standard. In such cases it generally uses 'equal temperament' (ET for
   short).
