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.

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

  ,----
  | 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
  `----


Quick Start
===========

  ,----
  | harpwise quiz ran
  `----


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