CINXE.COM

<!DOCTYPE html> <html> <head> <base href="//fkurz.net/ham/ebook2cw.html"> <meta charset="utf-8"> <title>ebook2cw - convert ebooks to Morse MP3s / OGGs</title> <meta name="author" content="Fabian Kurz"> <meta name="keywords" lang="en" content="ebook2cw, Hamradio, ham radio, text to morse, text to mp3, ebook, morse, mp3, cw book, ogg, vorbis"> <link href="/dj1yfk.xml?filter=ebook2cw" type="application/atom+xml" rel="alternate" title="ebook2cw newsfeed"> <link rel="stylesheet" type="text/css" href="/fkurz.css"> </head> <body> <h1>ebook2cw - convert ebooks to Morse MP3s/OGGs</h1> <hr> <nav> <a href="//fkurz.net/">Fabian Kurz</a> → <a href="/ham/">Ham Radio</a> → <a class="navself" href="/ham/ebook2cw.html">ebook2cw</a> </nav> <hr> <p><a href="">ebook2cw</a> version: 0.8.5 - <time datetime="2023-08-16">Aug 16<sup>th</sup> 2023</time> - See <a href="ebook2cw/ChangeLog">ChangeLog</a> - <a href="ebook2cw/">Download directory</a> - <a href="/dj1yfk.xml?filter=ebook2cw">Updates (Atom Feed format) <img src="/feed.png" alt="[Atom Feed]"></a> </p> <p><a href="#gui">ebook2cwgui</a> version: 0.1.2 - <time datetime="2013-01-23">January 23<sup>rd</sup> 2013</time> - See <a href="ebook2cw/ChangeLog-GUI">ChangeLog-GUI</a></p> <hr> <p><em>ebook2cw</em> is a command line program (optional <a href="#gui">graphical user interface</a> 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.</p> <h2>Contents</h2> <ul> <li><a href="#parameters">Parameters (Command Line)</a></li> <li><a href="#textcommands">Text Commands</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#configurationfile">Configuration File</a></li> <li><a href="#codetables">Code Tables</a> <ul> <li><a href="#encodings">Character encodings: ISO 8859-1 vs. UTF-8</a></li> </ul></li> <li><a href="#graphicaluserinterface">Graphical User Interface</a></li> <li><a href="#performance">Performance, Quality</a></li> <li><a href="#where">Where to get ebooks?</a></li> <li><a href="#cgi">ebook2cw as a CGI</a></li> <li><a href="#download">Download</a></li> <li><a href="#author">Contact, Feedback</a></li> </ul> <hr> <h2 id="parameters">Parameters</h2> <p>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):</p> <ul> <li><strong>-w wpm</strong> - CW speed in words per minute [25]</li> <li><strong>-e wpm</strong> - [Optional] Effective CW speed. If set, the spaces are sent at this speed instead of the character speed set by -w ("Farnsworth").</li> <li><strong>-W x</strong> - [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.</li> <li><strong>-f freq</strong> - audio frequency in Hz [600]</li> <li><strong>-T waveform</strong> - audio wave form; 0 = sine, 1 = sawtooth, 2 = square-wave [0] <li><strong>-Q minutes</strong> - 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]</li> <li><strong>-n </strong> - Disables resetting the speed when using the -Q option.</li> <li><strong>-p </strong> - Disables the paragraph separator (<BT>)</li> <li><strong>-R risetime</strong> - risetime of the CW signal, in samples [50]</li> <li><strong>-F falltime</strong> - falltime, samples [50]</li> <li><strong>-O</strong> - Generate an OGG-File instead of MP3</li> <li><strong>-X</strong> - Test mode, do not generate any files</li> <li><strong>-s samplerate</strong> - samplerate for the audio file [11025]</li> <li><strong>-b bitrate</strong> - MP3 bitrate, kbps [16]</li> <li><strong>-q quality</strong> - MP3 quality, 1 (best) to 9 (worst) [5]</li> <li><strong>-c chapter separator</strong> - 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.</li> <li><strong>-d seconds</strong> - Split output files after <em>seconds</em> seconds (finishes the current sentence first)</li> <li><strong>-l words</strong> - Split output files after a limit of <em>words</em> words (finishes the current sentence first)</li> <li><strong>-o outfile-name</strong> - Output filename (chapter number and .mp3/.ogg will be appended) [Chapter]</li> <li><strong>-a author</strong> - Author for the <a href="http://en.wikipedia.org/wiki/ID3">ID3 tag</a>. Use quotes for strings with spaces (e.g. "JW Goethe")</li> <li><strong>-t title</strong> - Title for the ID3 tag. Use quotes for strings with spaces (e.g. "Faust II")</li> <li><strong>-k comment</strong> - Comment for the ID3 tag. Use quotes for strings with spaces.</li> <li><strong>-y year</strong> - Year for the ID3 tag.</li> <li><strong>-u</strong> - Enables UTF-8 support (so far supported: Latin, Cyrillic, Greek, Hebrew and Arabic). Default setting (no -u switch) is ISO 8859-1.</li> <li><strong>-g file</strong> - Guesses the encoding of a text file (ISO 8859-1 / ASCII or UTF-8).</li> <li><strong>-S</strong> [UTF|ISO] - Prints a table of the available <a href="#codes">character sets</a> and CW symbols in HTML format.</li> <li><strong>-N snr</strong> - Adds a background noise with any SNR from -10 to 10. Negative values must be in quotation marks (e.g. "-3").</li> <li><strong>-B bandwidth</strong> - Filter bandwidth in Hz for the noise. Available filters: 100, 500, 1000, 2100Hz. [500]</li> <li><strong>-C filtercenter</strong> - Center freq of the filter in Hz. Only 800Hz implemented.</li> <li><strong>-E ebook2cw.conf</strong> - Specify a configuration file to be loaded.</li> </ul> <h2 id="textcommands">Text commands</h2> <p>CW prosigns can be generated by enclosing arbitrary letters in angle brackets (e.g. <AR>, <SK>, ...).</p> <p>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.</p> <p>Silence/pauses can be inserted by <code>|Snnnn</code>.</p> <p>Example: <code>|f400</code> changes the tone frequency to 400Hz, <code>|w60</code> changes the speed to 60wpm, <code>|S1000</code> inserts 1000 milliseconds of silence..</p> <h2 id="usage">Usage</h2> <p>ebook2cw has no graphical user interface itself, but a <a href="#gui">GUI interface is available as a separate program</a>.</p> <p>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.</p> <p>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):</p> <div style="color:white;background-color:black;border:5px solid #000000;"> <pre>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 </pre></div> <p>In this example everything takes place in <code>C:\test\</code>. It is assumed that ebook2cw.exe and the text file to convert are in this directory.</p> <p>If you want to avoid using the command line, a <a href="ebook2cw/example/ebook2cw.bat">simple batch file</a> for Windows is available. If placed in the same directory, you can comfortably drag & drop a text file to ebook2cw. The <a href="#gui">new GUI</a> offers an even more comfortable way to convert ebooks.</p> <h2 id="configurationfile">Configuration File</h2> <p>As of version 0.7.0 (July 2008), ebook2cw can read a configuration file, <code>ebook2cw.conf</code>. 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.<p> <p>An <a href="ebook2cw/example/ebook2cw.conf">example ebook2cw.conf</a> with further explanations is available. Under Windows, place this file in the same directory as ebook2cw. Under Linux, it is also searched for in <code>~/.ebook2cw/</code>.</p> <aside> <div style="float:right;width:300px;background-color:#ccffff;border:3px"> <h3 id="encodings" style="text-align:center">What is "ISO 8859-1" and "UTF-8"?</h3> <p>ISO 8859-1 and UTF-8 are different enconding formats for texts. <a href="http://en.wikipedia.org/wiki/ISO_8859-1">ISO 8859-1</a> is a standard encoding of the Latin alphabet (limited to 256 different symbols), while <a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a> can encode all <a href="http://en.wikipedia.org/wiki/Unicode">Unicode</a> characters, which includes the Cyrillic, Greek, Arabic alphabets, and a lot more.</p> <p>If you are not sure about the encoding of your text, invoke ebook2cw with the <code>-g</code> command line option, and it will guess the encoding. Most programs (text editors, browsers, etc.) nowadays default to UTF-8. If you try to convert a text with the wrong encoding, ebook2cw may produce some warnings about unknown characters.</p> </div> </aside> <h2 id="codetables"><a id="codes">Code tables</a></h2> <p> 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 <strong>Latin</strong> characters, the <strong>Cyrillic</strong>, <strong>Greek</strong>, <strong>Hebrew</strong> and <strong>Arabic</strong> alphabets. To maintain backward compability, the default character set is ISO 8859-1. Use the -u command line switch to enable UTF-8.</p> <p>The available codes can be printed by ebook2cw with the -S command line option (see above), here is the output: <a href="codes.html">UTF-8</a> - <a href="codes2.html">ISO 8859-1</a>. I am grateful for any feedback and additions to the tables.</p> <p>As of version 0.7.0 (July 2008), <em>character mappings</em> can be defined. For example, you can automatically replace all accented characters or umlauts (e.g. á = .--.-, ä = .-.-) with more common characters (like a = .-).</p> <p>This is done by <em>map files</em> separately for ISO8859-1 and UTF-8 coded texts. These map files must be specified in <em>ebook2cw.conf</em>, examples are available for <a href="ebook2cw/example/isomap.txt">ISO8859-1</a> and <a href="ebook2cw/example/utf8map.txt">UTF-8</a>. Under Windows, place them in the same directory as ebook2cw. Under Linux, these files are also searched for in <code>~/.ebook2cw/</code>.</p> <p>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 <a href="/ham/ebook2cw/ebk2cw">shell script</a> by Tor, NH7XC which does the job with sed, or the <a href="/ham/ebook2cw/cwzer.py">cwzer.py</a> Python script by Gabe/IZ4APU.</p> <h2 id="graphicaluserinterface"><a id="gui">Graphical User Interface</a></h2> <p>A graphical user interface (GUI) for ebook2cw is available as a separate program (screenshots: <a href="ebook2cwgui-0.1.0.png">WinXP</a>, <a href="ebook2cwgui-0.1.0-gtk.png">Linux</a>). 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 <a href="ebook2cw/ebook2cwgui.exe">download here</a> (Windows version - see the <a href="ebook2cw/">download directory</a> for the source code to compile it for other platforms).</p> <p><code>ebook2cw.exe</code> itself is not included within the GUI; it must be downloaded separately and saved in the same directory, or anywhere within the <a href="http://en.wikipedia.org/wiki/PATH_%28variable%29">executable path</a>. </p> <p>The GUI uses the same configuration file as ebook2cw, called <code>ebook2cw.conf</code>.</p> <h2 id="performance">Performance, Quality</h2> <p>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.</p> <p>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 <code>-s22050 -b32</code> (or make these settings in the GUI) to produce your MP3 files.</p> <p>The speed of the conversion mainly depends on your CPU speed; for example converting <a href="http://www.gutenberg.org/ebooks/36">The War of the Worlds</a> 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.</p> <h2 id="where">Where to get ebooks?</h2> <p>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 <a href="http://www.gutenberg.org/">Project Gutenberg</a>.</p> <p>Here is a <a href="read-books.txt">list of books</a> that the author already completed reading in CW.</p> <p>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 href="https://github.com/jeremy-w/colloquy-cw-plugin">a CW plugin for the IRC client colloquy.</a>, a <a href="https://github.com/iz3gme/text2cw_bot">Telegram bot which converts text messages to CW</a> and a <a href="https://rss2cw.herokuapp.com/">Morse RSS reader</a>).</p> <p>The author claims no credit for the original idea to convert books to morse. Other hams (like <a href="http://www.schlaupelz.de/Alice_in_Wonderland.html">DL2KCD</a>, <a href="https://www.k7qo.com/">K7QO</a>, <a href="http://www.hotpeppersoftware.com/downloads/pom_downloads.html">AC4FS</a>, <a href="http://ky8d.net/">KY8D</a>) 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 <a href="http://www.agcw.org/">AGCW</a> mailinglist in <a href="http://mailman.qth.net/pipermail/agcw/2007-October/thread.html">October</a>/<a href="http://mailman.qth.net/pipermail/agcw/2007-November/thread.html">November</a> 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.</p> <h2 id="cgi">ebook2cw as a CGI</h2> <p>ebook2cw can be compiled to run on a webserver as a CGI (<code>make cgi</code> or <code>make cgibuffered</code>). 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.</p> <p>Example: <code>http://example.com/cgi-bin/cw.cgi?s=25&e=20&f=600&t=%20hello%20world</code> returns a sound file with "hello world" at 25wpm character speed, 20wpm effective speed at a tone frequency of 600 Hz. Add <code>d=123</code> 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 <a href="#textcommands">text commands</a>, more options are available.</p> <p>This is extensively used on <a href="https://lcwo.net/">Learn CW Online (lcwo.net)</a> (but nowadays the main method of generating CW on the website is by using <a href="/ham/jscwlib.html">jscwlib</a>). Over there you'll also find an online <a href="https://lcwo.net/text2cw">text to CW</a> converter.</p> <hr> <h2 id="download">Download, License</h2> <p>Of course <em>ebook2cw</em> is <a href="https://www.fsf.org/licensing/essays/free-sw.html">free software</a> (<a href="http://en.wikipedia.org/wiki/Free_as_in_beer">free as in beer</a> and <a href="http://en.wikipedia.org/wiki/Freedom_of_speech">free as in freedom</a>) and published under the GPLv2.</p> <p>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:</p> <table class="fancy"> <tr><th colspan="3">Official files</th></tr> <tr><th>Format</th><th>Link</th><th>Remarks</th></tr> <tr><td>Windows EXE</td><td> <a href="ebook2cw/ebook2cw.exe">ebook2cw.exe</a></td><td>OGG/MP3 support (510 KB)</td></tr> <tr class="grey"><td>Windows EXE</td><td> <a href="ebook2cw/ebook2cw-mp3.exe">ebook2cw-mp3.exe</a></td><td>MP3 only (186 KB)</td></tr> <tr><td>Windows EXE</td><td> <a href="ebook2cw/ebook2cw-ogg.exe">ebook2cw-ogg.exe</a></td><td>OGG only (375 KB)</td></tr> <tr class="grey"><td>Windows EXE</td><td><a href="ebook2cw/ebook2cwgui.exe">ebook2cwgui.exe</a></td><td>(GUI only. Requires ebook2cw.exe)</td></tr> <tr><td>Linux Binary</td><td> <a href="ebook2cw/ebook2cw">ebook2cw</a></td><td>static, use if you can't compile it yourself</td></tr> <tr class="grey"><td>Source Code</td><td> <a href="ebook2cw/ebook2cw-0.8.5.tar.gz">ebook2cw-0.8.5.tar.gz</a></td><td> </td></tr> <tr><td>Source Code</td><td> <a href="ebook2cw/ebook2cwgui-0.1.2.tar.gz">ebook2cwgui-0.1.2.tar.gz</a></td><td> </td></tr> <tr><th colspan="3">Packages for various systems (Linux, FreeBSD, OS X)</th></tr> <tr><th>OS</th><th>Link</th><th>Maintainer</th></tr> <tr><td>Debian</td><td> <a href="http://packages.qa.debian.org/e/ebook2cw.html">ebook2cw-0.8.5-1</a><br><a href="http://packages.qa.debian.org/e/ebook2cwgui.html">ebook2cwgui_0.1.2-1</a></td><td><a href="http://www.qrz.com/db/dk5cf">Christoph, DK5CF</a></td></tr> <tr class="grey"><td>Ubuntu</td><td><a href="https://launchpad.net/~kamalmostafa/+archive/ebook2cw">ppa:kamalmostafa/ebook2cw</a></td><td><a href="https://wiki.ubuntu.com/KamalMostafa">Kamal, KA6MAL</a> (incl. GUI, based on Debian package)</td></tr> <tr><td>FreeBSD port</td><td><a href="http://www.freshports.org/comms/ebook2cw">ebook2cw</a></td><td><a href="http://www.db.net/~db/">Diane, VA3DB (db)</a></td></tr> <tr class="grey"><td>FreeBSD port</td><td><a href="http://www.freshports.org/comms/ebook2cwgui">ebook2cwgui</a></td><td><a href="http://www.db.net/~db/">Diane, VA3DB</a> / <a href="http://www.cpetservices.com/">Chris Petrik (cpet)</a></td></tr> <tr><td>ArchLinux</td><td><a href="https://aur.archlinux.org/packages/ebook2cw/">ebook2cw</a></td><td><a href="http://www.sportscliche.com/wb2fko/">Mike, WB2FKO (sportscliche)</a></td></tr> <tr class="grey"><td>Mac OS X</td><td><a href="ebook2cw/ebook2cw-osx-build-instructions.txt">build instructions</a></td><td>provided by <a href="http://www.turbidplaque.com/">Alan, N3IMU</a></td></tr> </table> <p>Many thanks to all the maintainers for their time and efforts to make ebook2cw available on so many platforms!</p> <p>Previous versions can be found in the <a href="ebook2cw/">download directory</a>; the source code repository is at <a href="https://git.fkurz.net/dj1yfk/ebook2cw">https://git.fkurz.net/dj1yfk/ebook2cw</a>.</p> <hr> <h2 id="author">Author, Contact, Feedback</h2> <p><em>ebook2cw</em> was written by Fabian Kurz, DJ5CW (ex DJ1YFK).</p> <p>I am always interested in <strong>any kind</strong> of feedback for my software. If you have any suggestions, questions, feature-requests etc., don't hesitate a minute and contact me via <a href="mailto:fabian@fkurz.net" title="my email address">email</a>.</p> <hr> <nav> <a href="//fkurz.net/">Fabian Kurz</a> → <a href="/ham/">Ham Radio</a> → <a class="navself" href="/ham/ebook2cw.html">ebook2cw</a> </nav> <hr> Last modified: Sunday, 21-Apr-2024 15:20:02 CEST <br> </body> </html>