ebook2cw - convert ebooks to Morse MP3s/OGGs

ebook2cw version: 0.8.5 - Aug 16^th 2023 - See ChangeLog - Download directory - Updates (Atom Feed format)

ebook2cwgui version: 0.1.2 - January 23^rd 2013 - See ChangeLog-GUI

ebook2cw is a command line program (optional graphical user interface available) which converts a plain text (ASCII, ISO 8859-1 or UTF-8) file (e. g. an ebook) to Morse code MP3 or OGG audio files. It works on several platforms, including Windows, Linux, FreeBSD and Mac OS X.

Contents

• Parameters (Command Line)
• Text Commands
• Usage
• Configuration File
• Code Tables
  • Character encodings: ISO 8859-1 vs. UTF-8
• Graphical User Interface
• Performance, Quality
• Where to get ebooks?
• ebook2cw as a CGI
• Download
• Contact, Feedback

Parameters

A number of CW and audio parameters can be changed from their default values, by command line switches or a config file (see below). These are (default values in brackets):

• -w wpm - CW speed in words per minute [25]
• -e wpm - [Optional] Effective CW speed. If set, the spaces are sent at this speed instead of the character speed set by -w ("Farnsworth").
• -W x - [Optional] Extra Word spacing. Similar to -e, but only affects the inter- word spacing, not the inter-character spacing. Example: -W 0.5 adds half an extra word space.
• -f freq - audio frequency in Hz [600]
• -T waveform - audio wave form; 0 = sine, 1 = sawtooth, 2 = square-wave [0]
• -Q minutes - Increase CW speed (QRQ) by 1wpm in intervals of 'minutes'. Speed will be reset to the initial value at the start of each chapter. Zero means no QRQ. [0]
• -n - Disables resetting the speed when using the -Q option.
• -p - Disables the paragraph separator (<BT>)
• -R risetime - risetime of the CW signal, in samples [50]
• -F falltime - falltime, samples [50]
• -O - Generate an OGG-File instead of MP3
• -X - Test mode, do not generate any files
• -s samplerate - samplerate for the audio file [11025]
• -b bitrate - MP3 bitrate, kbps [16]
• -q quality - MP3 quality, 1 (best) to 9 (worst) [5]
• -c chapter separator - Split chapters at this string [CHAPTER]. In the file, there must be a space after this string to make it work. If the separator string is empty or starts with a dash, chapters will not be split and the output files will not be numbered.
• -d seconds - Split output files after seconds seconds (finishes the current sentence first)
• -l words - Split output files after a limit of words words (finishes the current sentence first)
• -o outfile-name - Output filename (chapter number and .mp3/.ogg will be appended) [Chapter]
• -a author - Author for the ID3 tag. Use quotes for strings with spaces (e.g. "JW Goethe")
• -t title - Title for the ID3 tag. Use quotes for strings with spaces (e.g. "Faust II")
• -k comment - Comment for the ID3 tag. Use quotes for strings with spaces.
• -y year - Year for the ID3 tag.
• -u - Enables UTF-8 support (so far supported: Latin, Cyrillic, Greek, Hebrew and Arabic). Default setting (no -u switch) is ISO 8859-1.
• -g file - Guesses the encoding of a text file (ISO 8859-1 / ASCII or UTF-8).
• -S [UTF|ISO] - Prints a table of the available character sets and CW symbols in HTML format.
• -N snr - Adds a background noise with any SNR from -10 to 10. Negative values must be in quotation marks (e.g. "-3").
• -B bandwidth - Filter bandwidth in Hz for the noise. Available filters: 100, 500, 1000, 2100Hz. [500]
• -C filtercenter - Center freq of the filter in Hz. Only 800Hz implemented.
• -E ebook2cw.conf - Specify a configuration file to be loaded.

Text commands

CW prosigns can be generated by enclosing arbitrary letters in angle brackets (e.g. <AR>, <SK>, ...).

The tone frequency (f), speed (w), effective speed (e), volume (v, 1..100), waveform (T) and SNR (N) can be changed arbitrarily within the text by inserting commands, starting with a pipe symbol, followed by the parameter to change and the value.

Silence/pauses can be inserted by |Snnnn.

Example: |f400 changes the tone frequency to 400Hz, |w60 changes the speed to 60wpm, |S1000 inserts 1000 milliseconds of silence..

Usage

ebook2cw has no graphical user interface itself, but a GUI interface is available as a separate program.

These explanations aim at Windows users since I assume that Linux users can adopt it more easily to their needs than the other way around.

To convert the ebook file "Book.txt", in which the chapters are separated by "Chapter n" to MP3 files, called "Book-n.mp3", at 40wpm, the following command has to be entered in the Windows command prompt (Start → Utilities → Command prompt):

C:\test> ebook2cw.exe -w 40 -c Chapter -o Book- Book.txt
ebook2cw 0.8.0 - (c) 2011 by Fabian Kurz, DJ1YFK

Speed: 40wpm, Freq: 700Hz, Chapter: >Chapter<, Encoding: ISO 8859-1
Effective speed: 40wpm, Extra word spaces: 0.0, QRQ: 0min, reset QRQ: yes

Starting Book-0000.mp3
words: 12, time: 10s
Finishing Book-0000.mp3

Starting Book-0001.mp3
words: 1142, time: 16:12s
Finishing Book-0001.mp3

Total words: 1154, total time: 16:22s

In this example everything takes place in C:\test\. It is assumed that ebook2cw.exe and the text file to convert are in this directory.

If you want to avoid using the command line, a simple batch file for Windows is available. If placed in the same directory, you can comfortably drag & drop a text file to ebook2cw. The new GUI offers an even more comfortable way to convert ebooks.

Configuration File

As of version 0.7.0 (July 2008), ebook2cw can read a configuration file, ebook2cw.conf. In this file you can set all of the parameters which are available as command line parameters, to reduce typing work each time you use ebook2cw.

An example ebook2cw.conf with further explanations is available. Under Windows, place this file in the same directory as ebook2cw. Under Linux, it is also searched for in ~/.ebook2cw/.

Code tables

As of version 0.6.0 (February 2008), ebook2cw supports the full ISO 8859-1 charset (where mappings to CW symbols are applicable) and also UTF-8 (1- and 2-byte sequences). The latter so far includes most of the Latin characters, the Cyrillic, Greek, Hebrew and Arabic alphabets. To maintain backward compability, the default character set is ISO 8859-1. Use the -u command line switch to enable UTF-8.

The available codes can be printed by ebook2cw with the -S command line option (see above), here is the output: UTF-8 - ISO 8859-1. I am grateful for any feedback and additions to the tables.

As of version 0.7.0 (July 2008), character mappings can be defined. For example, you can automatically replace all accented characters or umlauts (e.g. á = .--.-, ä = .-.-) with more common characters (like a = .-).

This is done by map files separately for ISO8859-1 and UTF-8 coded texts. These map files must be specified in ebook2cw.conf, examples are available for ISO8859-1 and UTF-8. Under Windows, place them in the same directory as ebook2cw. Under Linux, these files are also searched for in ~/.ebook2cw/.

Note that native character mapping is only implemented for 1- and 2-byte sequences of UTF-8 characters at the moment. If you need to map other characters, you may use this shell script by Tor, NH7XC which does the job with sed, or the cwzer.py Python script by Gabe/IZ4APU.

Graphical User Interface

A graphical user interface (GUI) for ebook2cw is available as a separate program (screenshots: WinXP, Linux). It is designed to work on Windows (95 through 7), Linux and Mac OS X (not tested). It's a single executable file that you can download here (Windows version - see the download directory for the source code to compile it for other platforms).

ebook2cw.exe itself is not included within the GUI; it must be downloaded separately and saved in the same directory, or anywhere within the executable path.

The GUI uses the same configuration file as ebook2cw, called ebook2cw.conf.

Performance, Quality

The default settings (except for the speed) are probably suitable for most people. A full hour of MP3 takes only 7 MB, OGG even less, so depending on your speed, several books will fit even on cheap 1 GB portable media players.

Some MP3 players do not support all the possible variations of samplerates and bitrates. If you are running into problems with the default configuration, please try the command line options -s22050 -b32 (or make these settings in the GUI) to produce your MP3 files.

The speed of the conversion mainly depends on your CPU speed; for example converting The War of the Worlds to MP3 at 60 WpM, resulting in almost 17 hours of MP3 took about 15 minutes on the author's dated 1.8 GHz Celeron CPU. The OGG encoder is a little slower.

Where to get ebooks?

Books are subject to different copyright laws in every country; there are several online archives with free (copyright expired or public domain in the respective country) ebooks, most notably Project Gutenberg.

Here is a list of books that the author already completed reading in CW.

User feedback indicates, that ebook2cw is also used to prepare Morse courses lessons, generate morse versions of DX newsletters and other purposes (e. g. a CW plugin for the IRC client colloquy., a Telegram bot which converts text messages to CW and a Morse RSS reader).

The author claims no credit for the original idea to convert books to morse. Other hams (like DL2KCD, K7QO, AC4FS, KY8D) have done this before but the distribution as audio files largely limits the flexibility and requires a lot of bandwidth. Therefore, after some discussions on the AGCW mailinglist in October/November the author decided to write a free piece of software with which everyone can create a CW audio book to his or her own liking.

ebook2cw as a CGI

ebook2cw can be compiled to run on a webserver as a CGI (make cgi or make cgibuffered). It then returns a MP3 or OGG file when called with a suitable set of parameters, allowing for integrating dynamically created Morse code into websites.

Example: http://example.com/cgi-bin/cw.cgi?s=25&e=20&f=600&t=%20hello%20world returns a sound file with "hello world" at 25wpm character speed, 20wpm effective speed at a tone frequency of 600 Hz. Add d=123 as the first GET parameter to get the file as a download with filename "lcwo-123.mp3". These are all available HTTP GET parameters but using the text commands, more options are available.

This is extensively used on Learn CW Online (lcwo.net) (but nowadays the main method of generating CW on the website is by using jscwlib). Over there you'll also find an online text to CW converter.

Download, License

Of course ebook2cw is free software (free as in beer and free as in freedom) and published under the GPLv2.

The current versions are: ebook2cw 0.8.5 (Aug 16, 2023), ebook2cwgui 0.1.2 (January 23rd 2013). They can be obtained in several formats:

Many thanks to all the maintainers for their time and efforts to make ebook2cw available on so many platforms!

Previous versions can be found in the download directory; the source code repository is at https://git.fkurz.net/dj1yfk/ebook2cw.

Author, Contact, Feedback

ebook2cw was written by Fabian Kurz, DJ5CW (ex DJ1YFK).

I am always interested in any kind of feedback for my software. If you have any suggestions, questions, feature-requests etc., don't hesitate a minute and contact me via email.