README

An OpenBSD implementation of Ward Cunningham's automatic morse teacher
pesco DC4HK 2021-2023


How to build:

 $ make

Designed to compile and run on OpenBSD.
This is the 'portable' version including Linux and FreeBSD support.


Dependencies:

 OpenBSD:	none
 FreeBSD:	sndio
 Linux:		libsndio, sndiod

Make sure that sndiod is running and can access the audio device. You may have
to reboot after installing it.


How to use:

 $ ./morse -t
 ... follow the on-screen instructions ...


Useful environment variables:

 MORSE_SPEED	set output speed in words per minute [24]
 MORSE_PITCH	set sidetone frequency in Hz [550]
 MORSE_LEVEL	set number of starting characters [4]


Tips for learning:

 - Do not try to go fast!
   Give yourself time to process each symbol. Speed comes after accuracy.
 - Consider the sound of each symbol as a whole.
   Do not try to count individual beeps.
 - Think of each character while you type it.
   Avoid training only your fingers' muscle memory.
 - Look away from the screen if it helps you concentrate on the sounds.
 - Resound a new symbol a few times (press Space) when you first hear it.
   You are encouraged to use this function whenever you want.
 - Experiment with raising the output speed (MORSE_SPEED).
   Shorter sounds help your ear consider them as a whole, but be sure to keep
   the speed low enough to clearly distinguish hard cases like 5 vs. H.
 - Trust your intuition.
   For example, when you have trouble distinguishing 6 from B, 4 from V, or
   5 from H, ask your ear: "Did that sound like a digit or not?"
 - Rest after each session.
   Your subconcious needs time to commit its experiences to memory. You don't
   have to sit in meditation, just do something benign for about 15 minutes to
   give it some room.
 - Begin every session with only the first few characters.
   It reinforces learning to reiterate old material. You may later increase
   MORSE_LEVEL *conservatively* if and when the "recap" part of each session
   takes so long that it impedes progress.
 - Aim to train once every day.
   More than one session per day is said to be unhelpful. Persistence is key.
 - Leaves of absence are fine.
   Life likes to interfere. Even months-long breaks are not very damaging to
   your progress. Restart at the beginning and you will recover quickly.
 - Find what works for you.
   Like learning a language, learning Morse code is an individual process.
   Experiment, try different approaches, mix and match, hack up this program.
   Whatever suits your needs.


Detailed table of contents:

 morse.c
	An extended version of classic /usr/games/morse that supports
	audio output (-a) through sndio and integrates an interactive
	teacher mode (-t) modeled after Cunningham's 1977 algorithm.
 morseteach.c
	Stand-alone teacher program that forks and uses 'morse -a' in the
	background for its audio output.
 morseplay.c
	Stand-alone audio component to play morse code. Accepts dots and
	dashes as 'morse -s' produces them.

 teach.c
	Implements the teacher algorithm. Used by morse and morseteach.
 cw.c
	Audio output routines for "continuous wave" tones of a given
	frequency and length. Applies envelope functions for clean sound
	without unwanted clicks. Used by morse and morseplay.

 platform.h
	Compatibility code to adapt to other platforms.

 NOTES
	Background research, plans, and history for the teacher algorithm,
	other implementations, and the UNIX/BSD morse program.