README.ssb

TLF provides a voice keyer facility using the PC's sound card. This readme
provides additional information to help the user configure SSB operation.

-----------------
Radio Interfacing
-----------------
For the purposes of CW and PTT control, TLF interfaces to the radio via
cwdaemon, not hamlib. Therefore if you want voice keyer facilities cwdaemon must
be running before starting TLF.

cwdaemon can be invoked for a serial port or a parallel port. The most likely
modern scenario is to use a USB<->serial adaptor, in which case an example of
starting cwdaemon (as root) might be:

cwdaemon -d ttyUSB0

You can figure out which tty the adaptor is on by running 'dmesg' before and
after plugging-in the USB.

Check 'man cwdaemon' for circuit suggestions on interfacing DTR/RTS to CW/PTT
ports on your radio.

One option for mic interfacing is to use PTT to control a relay that connects
the radio's mic input either to the mic or to the soundcard. An alternative
solution, that is recommended by many other contest loggers, is instead to
connect the mic to the soundcard's mic input and the soundcard's output to the
radio's mic input. Most soundcards will loop-back the mic audio to the output,
which is easily checked. The only issue here is that the mic is also live when
playing voice keyer messages, but this can be avoided (see next section).

Note that some radios (e.g. TenTec Orion) have only one port that becomes PTT in
SSB mode and Key in CW mode. Wire-OR-ing the CW and PTT outputs from cwdaemon is
not an ideal solution because in CW mode PTT is still asserted and results in
key-down for the duration of the message. At present there is no satisfactory
solution to this problem.

-------------------
Configuration Files
-------------------
Normal practice is to create a new directory for each contest. Then a logcfg.dat
file in that directory overrides the default. If you are using SSB only in a
contest you can force TLF to start in SSB mode by uncommenting the SSBMODE
keyword in logcfg.dat.

If you have adopted the method that loops back the mic audio and you want to
automatically mute the mic when voice keyer messages are played, copy the
'play_vk' shell script found in the 'scripts' directory of your TLF release to
the same directory. This will then be used in preference to the default.
Uncomment the lines begining with 'amixer'.

Since tlf-1.1.0, (un)muting and playing voice messages has been devolved to this
external script file, because not all soundcards offer the same interface. 'Mic'
could be called something else. One way of finding this out is to run 'amixer'
from a terminal whch returns its capabilities. An alternative method is to
install your distro's version of the 'alsamixergui' package and simply see
what's available on the faders. This is probably a good idea anyway because it's
likely sound won't work without some manual intervention.

If you have something other than a 'Mic' source you could try replacing 'Mic'
with what you think it should be in the local 'play_vk' file. The process of
muting and unmuting the mic is displayed in alsamixergui, which is useful for
debug purposes. Please share any information you discover with the TLF
community.

Similarly, a 'rules' sub-directory can contain a contest specific rule file.
This rule file must contain the paths to the audio files corresponding to each
F-key to be used. An example might be:

VKM1=/home/aham/tlf/audio/f1.wav
VKM2=/home/aham/tlf/audio/f2.wav
VKM3=/home/aham/tlf/audio/f3.wav
VKM4=/home/aham/tlf/audio/f4.wav
VKM5=/home/aham/tlf/audio/f5.wav
VKM6=/home/aham/tlf/audio/f6.wav
VKM7=/home/aham/tlf/audio/f7.wav
VKM8=/home/aham/tlf/audio/f8.wav
VKM9=/home/aham/tlf/audio/f9.wav
VKM10=/home/aham/tlf/audio/f10.wav
VKM11=/home/aham/tlf/audio/f11.wav
VKM12=/home/aham/tlf/audio/f12.wav
VKSPM=/home/aham/tlf/audio/vkspm.wav
VKCQM=/home/aham/tlf/audio/vkcqm.wav

Thus a common set of voice messages can be pointed to from different rule files.
The VKCQM message is the auto-repeated CQ message for when the rate is low! The
VKSPM and VKCQM messages are sent after a contact is logged, in S+P and CQ modes
respectively.

Paths that are not defined cannot be recorded to from within TLF.

------------
Distro Notes
------------
TLF uses 'sox' to record and play audio, so you must have it installed. You can
use the sox commands 'rec' and 'play' on the command line in case you need to
debug any TLF issues.

Modern distros often use the 'pulseaudio' sound server, but this can cause
unacceptably long delays at the beginning and end of recordings, and at the
beginning and end of voice message playback. If you experience these problems
try uninstalling just the pulseaudio alsa plugin. You lose the ability for alsa
applications to play and record across a network, but for most TLF users this
isn't a problem.

---------
Recording
---------
To record messages from within TLF, enter ':sou' at the call entry field to take
you to the TLF Sound Recorder Utility page. Recording starts by hitting the
relevant F-key for that message ('s' or 'c' for the VKSPM and VKCQM messages).
Recording is terminated by hitting the <ESC> key.

Currently, recording messages does not key PTT. If you want to hear yourself via
the radio's monitor function whilst recording, you will need to manually assert
PTT, e.g. press your footswitch throughout. Obviously, this means your recording
also goes out on-air, so you might want to minimise your transmitted power
whilst setting up recordings.

It takes a bit of practice to time your speech within the starting and ending
key presses. It's also quite easy to set the alsa Mic gain too high and end up
with clipped audio. This will show up during playback as some black and white
writing appearing over the top of the display colours. It's actually sox
reporting warnings. You can fix this by adjusting the mic level using the alsa
mixer.

If you have the time, you can trim the audio clip and normalise the levels in an
audio editor, like audacity. That way you can avoid worrying too much about
getting the recording perfect from TLF. Of course, you could initially record
the messages using such an editor if preferred.

Andy, G4KNO

