cwwav
=====

Copyright (C) 2011-2014 by Thomas Horsten

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


What and why
============

This program takes one or more text files (or text read from standard
input) and converts it into a WAV (audio), or, if you have the "LAME"
MP3 encoder library installed, optionally an MP3 file containing CW
(Morse code).

It's useful for generating practice files if you are learning CW and
want to practice by listening to text on your iPod, phone, laptop or
whatever.

It's a very simple program but it is designed to do what it does
well. That is, it is designed to produce good sounding CW output
files, with proper timing and comfortable envelope to avoid keyclicks
and make the CW softer.

This is a beta version and I still plan to add more features. Requests
are welcome.

But as it is, it does generate nice practice files!


Installation
============

Make sure you have libsndfile-dev installed. On Ubuntu this is easy:

  $ sudo apt-get install libsndfile-dev

Then compile the program:

  $ make

If you want to enable the built-in MP3 encoder support, you need to
install the LAME development files and append "LAME=1" to the make
command. For Ubuntu, you do it like this - but it only works if you
have "Universe" ticked under Software Center->Edit->Software Sources.

  $ sudo apt-get install libmp3lame-dev
  $ make clean   (to remove the previous copy without MP3 support)
  $ make LAME=1

If that works out, you can run it directly from the current directory, or
install it system-wide by doing:

  $ sudo make install

However, I haven't added a ton of LAME encoder options and I find that
using the "lame" command line tool to convert the WAV files to MP3 is
more flexible. See the script in examples/huckleberry-finn for an
example on how to batch convert a bunch of text files into MP3.


How to use
==========

Usage: ./cwwav OPTIONS [FILENAME...]
Convert text into an audio file with morse code.

Mandatory arguments to long options are mandatory for short options too.
  -s, --stereo        generate stereo output (by default 2 identical channels)
  -p, --phaseshift N  shift phase of right channel by N radians (stereo effect)
  -o, --output        specify output file (must be supplied for WAV output)
  -O, --output-format specify output file format (wav or mp3, default: wav)
  -f, --frequency=N   use sidetone frequency N Hz (default: 660)
  -r, --rate=N        sample rate N (default 16000)
  -w, --wpm=N         use N words per minute (default: 25)
  -F, --farnsworth=N  use N WPM Farnsworth speed (default: same as WPM)
  -e, --envelope=N    envelope N ms raised cosine (default=10.0)
  -h, --help          display this help and exit
Convert text into an audio file with morse code.


Example
=======

1. I took the "printable" version of the James Clerk Maxwell article
on Wikipedia and covnerted into text (examples/maxwell.txt).

2a. New method: Convert it directly to an MP3 file:

 $ ./cwwav --output maxwell.mp3 --frequency=650 --wpm=20 examples/maxwell.txt

2b. Old method, or if you don't have the LAME library installed, or if
you prefer to add options to lame:

Then I converted it to a 20-WPM CW file like this:

 $ ./cwwav --output maxwell.wav --frequency=650 --rate=16000 --wpm=20 examples/maxwell.txt

3. Then I converted the resulting WAV file into an MP3 file using
lame:

 $ lame --preset phone maxwell.wav maxwell.mp3

Finally I deleted the intermediate maxwell.wav file and copied the
resulting maxwell.mp3 file to my phone.

I hope you enjoy this program and find it useful for generating
practice files. Any commends, suggestions etc. are very welcome, my
email address is thomas at horsten dot com.


Releases
========

0.4 - Add UTF-8 text file support, and support for a number of
European accented letters, should be good to transcribe
Danish/Norwegian/Swedish/German files and possibly French. Also
changed paragraph breaks (an empty line in the input) to produce a
short pause instead of " = ". Added "A Journey to the Interior of the
Earth" by Jules Verne (from Project Gutenberg) to the examples, along
with a conversion script with some nice settings.

0.3 - Add stereo effect (phase shifting 1 channel) and more examples

0.2.1 - First release with MP3 support

0.1 - First public alpha


TODO
====

Still a lot to be done, but it works for me :) So it might take some
time to add more features. If you have anything specific you want I
will probably be able to help, just email me!


Homepage
========

You can find the latest sources on:

  http://home.horsten.com/cgit/cgit.cgi/cwwav/

VY 73 de Thomas, M0TRN