.Dd CWSND 1
.Os
.Sh NAME
.Nm cwsnd
.Nd cw sounder
.Sh SYNOPSIS
.Nm cwsnd
.Op Fl h
.Op Fl E
.Op Fl P
.Op Fl f Ar effwpm
.Op Fl s Ar suffix
.Op Fl t Ar tonefrq
.Op Fl w Ar wpm
.Op Ar file
.Sh DESCRIPTION
.Nm
is a CW/Morse code sounder written for OpenBSD using the sndio API.
The primary use case for this program is for CW ham study purposes,
although it can be used for computer keying with suitable hardware,
similar to FLDigi Tx using sound card audio output.
.Pp
Input is taken from the standard input by default, unless specified
in the
.Ar file
argument.
Prosigns are prefixed with the dollar sign ($), for example $AR, $SK.
.Pp
The input is translated into code, and then into sinusoidal
audio-frequency tones outputted by the sound card,
which can be used as-is for ear training,
or further modulated by external hardware for transmission.
The output device can be selected with the
.Ev AUDIODEVICE
environment variable (see
.Xr sndio 7
for details).
.Pp
There are three modes of operation: Default,
Echo (see the
.Fl E
option) and Prompt (see the
.Fl P
option).
In the Default mode, lines of text to be transmitted can be entered
into the standard input.
Lines are processed in a line-by-line basis, i.e. nothing gets sent
unless Enter/Return is inputted.
There will be no outputs on the standard output,
except one single newline upon the input EOF.
.Pp
If running interactively in a terminal,
Ctrl+D (end-of-file) ends the session.
.Pp
The options are:
.Bl -tag -width Ds
.It Fl h
Show help message.
.It Fl E
Starts a session in the Echo mode.
In this mode, the input will be obtained from the standard input (or
.Ar file
if supplied).
Characters are echoed into the standard output as they are sent.
Useful for making a transcript of what is actually sent.
Not recommended for interactive use.
.It Fl P
Starts a session in the Prompt mode.
The user types into an asterisk prompt before sending the entire line
by inputting Enter/Return.
The sent characters will be echoed into the standard output,
and the prompt will appear again after the transmission is finished.
.It Fl f Ar effwpm
Sets the Farnsworth speed (effective wpm) to
.Ar effwpm
words per minute.
When not specified,
.Ar effwpm
is assumed to be equal to the actual
.Ar wpm .
.It Fl s Ar suffix
To send
.Ar suffix
when end-of-file is reached.
Default empty.
.It Fl t Ar tonefrq
Sets the output tone frequency to
.Ar tonefrq
cycles per second.
Defaults to 600 cycles/sec.
.It Fl w Ar wpm
Sets the character speed (wpm) to
.Ar wpm
words per minute, using the PARIS standard word.
Defaults to 20 words/min.
.Sh ENVIRONMENT
.Bl -tag -width "AUDIODEVICEXXX" -compact
.It Ev AUDIODEVICE
Name of audio device to use.
.Sh EXAMPLES
Start a Prompt session.
.Pp
.Dl "$ cwsnd -P"
.Dl "* TEST TEST"
.Dl "TEST TEST"
.Pp
Press Ctrl+D to end the session.
.Pp
The Default mode works better for real-time conversations
since it allows the operator to buffer the input
while transmitting at the same time.
.Pp
.Dl "$ cwsnd"
.Dl "s2yz de s1abc"
.Dl "gm dr om            [ these lines can be typed while    ]"
.Dl "ur rst 5nn 5nn =    [ the prev. lines are still sending ]"
.Dl "op is john john ="
.Dl "qth andalusia ="
.Dl "hw?"
.Dl "s2yz de s1abc"
.Dl "$kn"
.Pp
Sending an automatic report in a text file at 30 words per minute.
The transmission ends with the specified suffix.
.Pp
.Dl "$ cwsnd -w 30 -s '= 73 de s2yz $sk' report.txt"
.Pp
Random
.Xr fortune 1
cookie with transcript via Echo mode.
.Pp
.Dl "$ fortune -s | cwsnd -E"
.Pp
Koch--Farnsworth traning practice, 25 wpm code
spaced out to 15 effective words per minute (requires
.Xr kochgen 1 )
.Pp
.Dl "$ kochgen -n 30 KMRSUAPTLO | cwsnd -w 25 -f 15"
.Sh SEE ALSO
.Xr kochgen 1 ,
.Xr morse 6 ,
.Xr sndio 7
.Sh AUTHORS
.An Samuel Wirajaya