# -*- fill-column: 74 -*-
#+SETUPFILE: <%= $org_theme_file %>
#+OPTIONS: toc:t
#+TITLE: Harpwise

/Version  <%=$version%>/

* 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

<%= IO.read("../_org/usage.org") %>

* 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]]
  
<%= IO.read("../_org/usage_listen.org") %>

* harpwise quiz

  [[../images/harpwise-quiz.gif]]
  
<%= IO.read("../_org/usage_quiz.org") %>

* harpwise jamming

<%= IO.read("../_org/usage_jamming.org") %>

* harpwise licks

<%= IO.read("../_org/usage_licks.org") %>

* harpwise play

<%= IO.read("../_org/usage_play.org") %>

* harpwise tools

<%= IO.read("../_org/usage_tools.org") %>

* harpwise samples

<%= IO.read("../_org/usage_samples.org") %>
                  
* 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).

