ebook2cw - convert ebooks to Morse MP3s/OGGs

ebook2cw version: 0.8.5 - - See ChangeLog - Download directory - Updates (Atom Feed format) [Atom Feed]

ebook2cwgui version: 0.1.2 - - 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.



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):

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..


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:

Official files
Windows EXE ebook2cw.exeOGG/MP3 support (510 KB)
Windows EXE ebook2cw-mp3.exeMP3 only (186 KB)
Windows EXE ebook2cw-ogg.exeOGG only (375 KB)
Windows EXEebook2cwgui.exe(GUI only. Requires ebook2cw.exe)
Linux Binary ebook2cwstatic, use if you can't compile it yourself
Source Code ebook2cw-0.8.5.tar.gz 
Source Code ebook2cwgui-0.1.2.tar.gz 
Packages for various systems (Linux, FreeBSD, OS X)
Debian ebook2cw-0.8.4-1
Christoph, DK5CF
Ubuntuppa:kamalmostafa/ebook2cwKamal, KA6MAL (incl. GUI, based on Debian package)
FreeBSD portebook2cwDiane, VA3DB (db)
FreeBSD portebook2cwguiDiane, VA3DB / Chris Petrik (cpet)
ArchLinuxebook2cwMike, WB2FKO (sportscliche)
Mac OS Xbuild instructionsprovided by Alan, N3IMU

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.

Last modified: Sunday, 20-Aug-2023 20:27:03 CEST