Harpwise

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.

• 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

~/harpwise/config.ini

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

harpwise listen -o

to read options for mode listen.

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.

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

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.

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:

harpwise listen richter c blues

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

harpwise listen blues

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

harpwise listen blues --add-scales chord-i --display chart-scales

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

harpwise listen --scale-progression 12bar

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:

harpwise listen --scale-prog 12bar --keyboard-translate RETURN=s

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:

harpwise listen --scale-prog 12bar --lick-prog simple-turn,wade

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:

harpwise print mipe

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:

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

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:

harpwise listen -3// +4 -4 +5 +6 -6

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

harpwise listen mipe --transpose-scale +2st

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:

harpwise listen c --time-slice short

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.

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)

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

harpwise quiz c random

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

harpwise quiz chromatic a blues replay 5

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

harpwise q major replay

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

This example chooses the a flavour-collection:

harpwise quiz no-mic

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:

harpwise quiz hear-scale

harpwise quiz ran

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

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.

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

harpwise jam along 12bar

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:

harpwise listen --scale-prog 12bar --lick-prog box1 --jamming

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:

harpwise jamming list

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

harpwise jam along 2b       

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

harpwise jam along 2b r

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:

harpwise jam g along 12bar

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.

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_{withholes.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.

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

harpwise licks c

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

harpwise licks c --tags-all fav,has-rec

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

harpwise licks a -t shifts-four,shifts-five

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'

harpwise licks c --tags-any fav,scales

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

harpwise print licks-list --tags-any fav,scales

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

harpwise licks c -t mostly-chord-v

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:

harpwise licks a -t starred

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:

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

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:

harpwise licks blues

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

harpwise licks box1-i box1-iv box1-i box1-v box1-iv box1-v box1-i simple-turn

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:

harpwise licks --lick-progression box1

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:

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

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:

harpwise licks +1 +2 +3

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

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

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

harpwise play c +1 -2 c4

Play a few semitones:

harpwise play c +1st -4st

Play the lick 'wade'; transpose it to d:

harpwise play d wade

Play an earlier lick:

harpwise play 3l

To see a list of earlier licks:

harpwise print licks-history

Various ways to play all licks:

Shuffled and in random order, without end:

harpwise play licks

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

harpwise play licks --iterate cycle

or shorter:

harpwise play licks -i c

Only play favorite licks (tag 'fav'):

harpwise play licks --tags-all fav

or shorter:

harpwise play licks -t fav

Play licks from a progression:

harpwise play licks --lick-prog box1

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

harpwise play licks --lick-radio

Play an interactive, adjustable pitch:

harpwise play pitch

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

harpwise play pitch c

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:

harpwise play inter c4 d4

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:

harpwise play inter c4 12st    ## Note c4 and 12 Semitones

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

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

Play a note progression:

harpwise play prog e3 7st 10st oct

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:

harpwise play prog +1 5st 7st 10st

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

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

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:

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

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

harpwise play boogie-i boogie-i boogie-iv boogie-v boogie-iv boogie-i simple-turn

which might be a starting point for improvisation.

Another way of playing would be:

harpwise play chord +1 +2 +3 -3/

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:

harpwise print +1 +2 +3 -3/

If you record yourself during lick-practice,

harpwise play user

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

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.

Transpose a sequence of notes (some specified as holes) from the key of c to g (keeping the notes/pitches constant):

harpwise tools transpose c g -1 +2 -3

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:

harpwise tools shift 12st -1 +2 -3

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:

harpwise tools keys

Center the semitone-column around a specific key of harp (bf) and mark it in the table:

harpwise tools keys bf

The same and mark a key of song (d) too:

harpwise tools keys bf d

If you have a g-harp and want to know what song-keys and positions are available:

harpwise tools keys g g

Print a harmonica chart for the key of g:

harpwise tools chart g

The same chart, but with arguments rearranged

harpwise tools g chart

Two charts, the second with scale-content (chord-i)

harpwise tools g chord-i chart --add-scales -

Four charts, the third and fourth with intervals of each hole to the given reference:

harpwise tools chord-i chart --ref -4

How to get the holes of the pentatonic scale in an adhoc fashion:

Assuming, that you know its notes g a b d e:

harpwise tools spread-notes g a b d e

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

harpwise tools make-scale +1 +2 +3

The notes of the major scale starting at c:

harpwise tools notes c

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:

harpwise tools prog e3 7st 9st oct

which will give you all the notes starting at e3 and the 7, 9, 12 semitones up.

Print the interval over the base note:

harpwise tools interval c4 oct

harpwise tools interval c4 +12st

print the chords i, iv and v for the current key:

harpwise tools chords

Transcribe and audio-file given on the commandline approximately:

harpwise tools transcribe wade.mp3

for simple harmonica content this will give you sequence of holes played in lick wade.mp3 (from current working dir)

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.

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

harpwise samples c record

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.

harpwise samples c record +4

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

harpwise play +4

or even:

harpwise play full

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:

harpwise samples a generate

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

harpwise samples generate all

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

harpwise samples d delete

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.

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

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

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.

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

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 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_{withholes.txt}

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.

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.

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