==================================================================
txt2mca: TEXT-TO-MORSE-CODE-AUDIO CONVERTER
==================================================================

Developed by DF7TV with assistance from ChatGPT.

Readme file revised November 17, 2026

Author: Thomas MARTIN, DF7TV

Reference:
https://www.qsl.net/df7tv/morse-code-processing.html


==================================================================
PART I - USER GUIDE
Installation, Setup and Basic Operation
==================================================================


1. INTRODUCTION
==================================================================

The txt2mca converter transforms UTF-8 encoded text files,
including large documents and books, into MP3 audio files
containing Morse code.

The conversion parameters can be adjusted through the graphical
user interface (GUI) to produce a pleasant and easily readable
flow of Morse code.

Different edge-shaping functions can be selected to shape the
rising and falling edges of the DITs and DAHs.

txt2mca is available in two versions:

- A standalone Windows executable (txt2mca.exe).
- A Python script (txt2mca.py) for Windows, Linux and macOS.

This README provides installation and operating instructions
as well as additional technical information for interested
users and developers.

If you have any questions, please let me know.
I will be happy to help.


1.1 WINDOWS EXECUTABLE (txt2mca.exe)
------------------------------------

The Windows executable txt2mca.exe is a standalone application
packaged with PyInstaller.

FFmpeg is required for MP3 audio encoding. It must be installed
separately and be accessible through the system PATH.

No separate Python installation or NumPy installation is
required.

The executable is intended for Windows computers.


1.2 PYTHON SCRIPT (txt2mca.py)
------------------------------

The Python script txt2mca.py can be used on Windows, Linux
and macOS.

Thanks to Mark/AJ6CU, Jeff/N0MII, Holger/DL9HDA and Joe/AA8TA
for testing on macOS.

To run the script, you need:

- A working Python 3 installation.
- The NumPy package.
- Tkinter for the graphical user interface (GUI).
- FFmpeg for MP3 audio encoding.

FFmpeg must be installed separately and be accessible through
the system PATH.

Depending on your operating system and Python distribution,
Tkinter may also need to be installed or configured separately.

The required Python packages must be installed for the Python
interpreter used to run txt2mca.py.


------------------------------------------------------------------
2. INSTALLATION AND SETUP
==================================================================


2.1 FFMPEG INSTALLATION
-----------------------

FFmpeg is required for MP3 audio encoding.

Before installing FFmpeg, check whether it is already available
on your system.

1. Open a Terminal window (macOS or Linux) or a Command
   Prompt window (Windows).

2. Enter the following command:

   ffmpeg -version

3. If FFmpeg displays version information, it is already
   available. You do not need to install it again.

4. If the command is not recognized or not found, follow
   the installation instructions below.

The following website provides instructions for installing
FFmpeg on Windows, Linux and macOS:

https://ffmpeg-cookbook.com/en/articles/install-ffmpeg/

The "essentials" version of FFmpeg is sufficient on Windows.

FFmpeg must be accessible through the system PATH so that
txt2mca can find and execute it.


2.2 PYTHON REQUIREMENTS
-----------------------

This section applies only to the Python script txt2mca.py.

The required third-party package is:

   numpy

It can be installed using:

   python -m pip install numpy

Tkinter is part of the Python standard library, but may need
to be installed separately depending on the operating system
and Python distribution.

The other Python modules used by txt2mca are included in
standard Python installations.

No additional third-party Python packages are required.


2.3 STARTING txt2mca
--------------------

WINDOWS EXECUTABLE:

   Double-click txt2mca.exe.

PYTHON SCRIPT:

Open a Terminal or Command Prompt window, navigate to the
directory containing txt2mca.py and enter:

   python txt2mca.py

On some systems, the Python command may instead be:

   python3 txt2mca.py

The graphical user interface will open.


------------------------------------------------------------------
3. BASIC OPERATION
==================================================================


3.1 INPUT AND OUTPUT FILES
--------------------------

INPUT:

UTF-8 encoded text file.

Use the Browse button to select the input text file.

OUTPUT:

MP3 audio file containing Morse code.

OUTPUT FILE NAMING:

When an input file is selected, txt2mca automatically suggests
an output filename based on the input filename, using the .mp3
extension.

For example:

    Input:   example.txt
    Output:  example.mp3

The suggested output filename is set only if the output filename
field is empty. If you have already selected or entered an output
filename, txt2mca preserves your choice.

You can also use the Browse button next to the output field to
select a different output filename and destination.


3.2 CONVERT
-----------

When the Convert button is pressed, the application starts
converting the selected UTF-8 text file into Morse code audio.

The conversion progress is displayed in the progress bar.

Once the conversion is complete, the resulting MP3 file is
saved in the output directory.

When conversion is complete, the total conversion time is
displayed together with the completion message.


3.3 STOP
--------

Pressing the Stop button stops the current conversion and
finalizes an output audio file containing the portion of the
input text processed up to that point.

The resulting partial MP3 file is retained.


3.4 EXIT
--------

Pressing the Exit button has the same effect as Stop:
any current conversion is finalized and the resulting partial
MP3 file is retained.

In addition, the current parameter values are saved in the
configuration file and the application is closed.

If conversion has already been completed, no additional MP3
file is generated.


3.5 CONFIGURATION FILE
----------------------

The configuration file is stored in the user's application
configuration directory. Its location depends on the operating
system:

- Windows: %APPDATA%\txt2mca\txt2mca.cfg
- Linux:   ~/.config/txt2mca/txt2mca.cfg
- macOS:   ~/Library/Application Support/txt2mca/txt2mca.cfg

The configuration directory is created automatically if it
does not already exist.

After restarting either the Python script or the Windows
executable, the previously saved parameter values are restored
from the configuration file and displayed in the GUI.


------------------------------------------------------------------
4. GUI PARAMETER SETTINGS
==================================================================

The available adjustment ranges for each parameter are displayed
in the graphical user interface (GUI).

Choose values that provide the best readability of the generated
Morse code audio at your preferred speed and tone frequency.

The GUI also provides a BPF (Band-Pass Filter) ON/OFF switch.

The filter is enabled by default on fresh installations and can
be switched on or off according to user preference.

The selected BPF state is saved in the configuration file,
along with all other GUI settings, and restored when txt2mca
is started again.

All GUI controls are temporarily disabled during conversion,
except for the Stop and Exit buttons.


4.1 DECIMAL NUMBER INPUT
------------------------

The WPM and tone frequency parameters accept both decimal
points and decimal commas.

For example, both 25.5 and 25,5 are accepted as valid
decimal values.

Values are normalized to decimal points when saved in
the configuration file.


------------------------------------------------------------------
5. SAMPLE INPUT FILE
==================================================================

A sample UTF-8 text file is provided for testing:

   N0HFF-ASRT-2002-PART.txt

This file contains an edited passage from William G. Pierpont,
N0HFF (2002), "The Art and Skill of Radio Telegraphy" (ASRT).

To download a much larger edited part of this book as UTF-8 text,
please visit:

https://www.qsl.net/df7tv/morse-code-training.html

Search in the References for:

William G. Pierpont, N0HFF (2002): ASRT;
Edited Input File (txt) for ebook2cw

Although I originally prepared this file for DJ5CW's tool
ebook2CW, it can also be used as an input file for txt2mca.


==================================================================
PART II - TECHNICAL INFORMATION
Signal Processing, Morse Timing and Developer Features
==================================================================


6. MP3 AUDIO ENCODING
==================================================================

The generated MP3 audio files are encoded using Variable Bitrate
(VBR) encoding.

VBR dynamically adjusts the audio bitrate according to the
characteristics of the audio signal.

This provides efficient file sizes while maintaining good
audio quality.

The MP3 encoding quality is controlled by the internal FFmpeg
configuration.


------------------------------------------------------------------
7. EDGE SHAPING
==================================================================

The edge-shaping functions are taken from my project
"sineCW60", a VST3 plugin.

They are used to shape the rising and falling edges of the
Morse code elements (DITs and DAHs).

For further information, see:

https://www.qsl.net/df7tv/morse-code-processing.html#shapes


------------------------------------------------------------------
8. ADDITIONAL PAUSES FROM CONSECUTIVE SPACES
==================================================================

Consecutive ordinary space characters are interpreted as
additional pauses in the generated audio.

A single ordinary space produces the standard Morse code
word gap.

Each additional consecutive space adds three dits of silence
to that word gap.

These additional pauses are independent of the normal Morse
character and word gaps.

For example, a longer sequence of spaces between two sentences
produces a longer pause than a single space.

This feature can be used to introduce pauses similar to those
found in natural speech.


EXAMPLE OF USE
--------------

Before conversion, you can modify your input text file by
replacing:

- Every period with five spaces.
- Every comma with two spaces.
- Every question mark with two spaces, followed by the
  question mark itself, followed by five spaces.

The resulting audio will sound more like a conversational
radio QSO.

This is just an example. Your preferred replacements may differ.


------------------------------------------------------------------
9. ADDED CODE ELEMENT TIME
==================================================================

The Added Code Element Time parameter extends the tone duration
of each Morse code element (DIT or DAH) by a configurable amount
from 0 to 50 percent of one dit duration.

This feature can improve Morse code readability, particularly
at very high speeds.

To preserve the nominal Morse timing, the additional tone
duration is subtracted from the silence immediately following
each DIT or DAH.

This applies to all Morse code elements, including those at
the end of a character or word.

In other words, this parameter transfers time from the
following silence to the preceding tone.

The overall time allocated to each Morse code element and its
following gap remains unchanged. Only the distribution between
tone and silence is modified.


9.1 EXAMPLE AT 60 WPM
---------------------

One dit lasts 20 milliseconds.

With an Added Code Element Time setting of 20 percent,
the tone is extended by 4 milliseconds.

The following gap is shortened by the same amount.

For example, a normal 20-millisecond intra-character gap
becomes 16 milliseconds, while the preceding tone is extended
by 4 milliseconds.

This timing adjustment is also known from electronic keyers
as keying compensation, key compensation, or simply
compensation.


------------------------------------------------------------------
10. EXTREMELY HIGH SPEEDS (ESPECIALLY ABOVE 100 WPM)
==================================================================

txt2mca also supports extremely high Morse code speeds above
100 WPM.

At these speeds, individual Morse code elements become very
short. For example:

    100 WPM:  12 milliseconds per DIT
    150 WPM:   8 milliseconds per DIT
    200 WPM:   6 milliseconds per DIT


10.1 TIMING ACCURACY
--------------------

The Morse code audio is generated internally as PCM audio.
Cumulative sample counting is used to maintain accurate timing
and to avoid rounding errors when converting Morse durations
into audio samples.

The PCM timing has been verified experimentally by generating
audio at 200 WPM and inspecting the resulting uncompressed
WAV waveform.

The measured DIT duration was 6 milliseconds, matching the
nominal calculated duration. The measured gap between two
consecutive E characters was 18 milliseconds, also matching
the nominal Morse timing.

These measurements confirm that the internal PCM generation
maintains the intended Morse timing, even at extremely high
speeds.

The generated PCM audio therefore provides the reference for
the nominal Morse timing.


10.2 AUDIO FILTERING AND MP3 ENCODING
-------------------------------------
Before MP3 encoding, the generated PCM audio can optionally be
processed through an audio band-pass filter (BPF).

The filter suppresses unwanted frequency components outside
the frequency range surrounding the Morse tone. This is
particularly useful at extremely high speeds, where the rapid
switching of short tone elements produces a broader frequency
spectrum.

Audio filtering and MP3 encoding are handled by a single FFmpeg
process.

If the BPF is enabled, FFmpeg applies the band-pass filter
before encoding the audio as MP3. If the BPF is disabled,
the PCM audio is passed to the MP3 encoder without filtering.

The audio is streamed directly from txt2mca to FFmpeg.
No intermediate PCM file is required for normal conversion.

The FFmpeg process remains active throughout the conversion,
so its internal filter state is maintained across successive
PCM data chunks.

When developer debug mode is enabled together with the BPF,
FFmpeg also produces a separate uncompressed PCM WAV output
from the filtered audio stream. This output is generated in
parallel with MP3 encoding.

The band-pass filter itself affects the waveform around tone
transitions. Consequently, the apparent duration and shape
of very short DITs may differ slightly from the nominal PCM
timing, even before MP3 encoding takes place.

This effect was confirmed experimentally by comparing
unfiltered and filtered audio at 200 WPM.

MP3 is a lossy audio format. Its encoding and decoding process
can introduce additional waveform artifacts around signal
transitions.

In particular, short DITs may exhibit low-level, decreasing
oscillations after the end of the tone. These artifacts can
make the apparent beginning and end of a Morse element less
clearly defined.

Therefore, waveform differences observed in the decoded MP3
audio are not necessarily caused by MP3 encoding alone.
Both the audio band-pass filter and the MP3 encoding process
can contribute to the observed changes.

These effects do not necessarily indicate an error in the
generated Morse timing.


10.3 RECOMMENDATION FOR WAVEFORM INSPECTION
-------------------------------------------

For precise waveform inspection and timing verification,
uncompressed PCM audio (WAV) is recommended.

The optional debug WAV outputs available in the Python script
allow inspection of the audio at different stages of the
processing pipeline:

Original unfiltered PCM WAV: Contains the raw Morse code
PCM audio generated internally by txt2mca, before filtering
and MP3 encoding.

FFmpeg-filtered PCM WAV: When the BPF is enabled, an
additional WAV file contains the audio after the FFmpeg
band-pass filter, but before MP3 encoding.

Comparing these files with the resulting MP3 makes it possible
to distinguish waveform changes caused by filtering from
those introduced by MP3 encoding.

MP3 is intended primarily for convenient listening and
distribution.

When evaluating extremely high-speed Morse timing, distinguish
between the nominal timing of the generated PCM audio and
the waveform changes introduced by audio filtering and
MP3 encoding.

Small differences in the decoded MP3 waveform do not,
by themselves, justify modifying the nominal Morse timing
parameters.

------------------------------------------------------------------
11. DEVELOPER DEBUG WAV OUTPUT
==================================================================

The Python script includes an optional developer-only debug mode
for generating additional uncompressed WAV audio files.

This feature is controlled by the DEBUG_MODE constant near
the beginning of the Python script.

By default:

DEBUG_MODE = False

To enable debug WAV generation, change this value to:

DEBUG_MODE = True

When enabled, txt2mca generates the following original,
unfiltered WAV file:

txt2mca_debug_original_PCM_unfiltered.wav

If the BPF is also enabled, an additional filtered WAV file
is generated:

txt2mca_debug_FFmpeg_filtered.wav

Both files are saved in the same output directory as the MP3.

If files with these names already exist in that directory,
they will be overwritten when the corresponding debug output
is generated.

The two debug WAV files contain audio at different stages
of the processing pipeline:

ORIGINAL UNFILTERED AUDIO:
--------------------------

The file txt2mca_debug_original_PCM_unfiltered.wav contains
the original raw Morse code PCM audio generated internally
by txt2mca, before FFmpeg applies the audio band-pass filter
and MP3 encoding.

This WAV file is written directly by Python from the same
PCM audio data that is streamed to FFmpeg.

FFMPEG-FILTERED AUDIO:
----------------------

The file txt2mca_debug_FFmpeg_filtered.wav contains the audio
after the FFmpeg band-pass filter, but before MP3 encoding.

This file is generated only when both DEBUG_MODE and BPF
are enabled.

The filtered WAV output is produced by the same FFmpeg
process that performs MP3 encoding. The filtered audio is
split into parallel outputs for the WAV file and the MP3
encoder.

This allows direct comparison of the original and filtered
PCM signals, independently of MP3 encoding.


AUDIO FORMAT:
-------------

		Sample rate:  44100 Hz
		Channels:     Mono
		Bit depth:    16-bit PCM

The original unfiltered PCM audio is written directly to
the debug WAV file by Python.

The same PCM data is also streamed to a single FFmpeg
process for audio filtering, when enabled, and MP3 encoding.

When the BPF is enabled and debug mode is active, FFmpeg
simultaneously produces the filtered WAV output and the
MP3 audio.

When the BPF is disabled, the unfiltered PCM audio is passed
to FFmpeg for MP3 encoding without filtering. No filtered
debug WAV file is generated.

If conversion is stopped by the user, the partial debug WAV
outputs are properly finalized and retained.

If conversion fails, the debug WAV and MP3 output files
are removed.

These debug files are intended primarily for developers and
for precise waveform inspection, particularly at extremely
high Morse code speeds.

The debug mode is available in the Python script only and
does not require any additional GUI settings.

==================================================================
12. LICENSE
==================================================================

This work, txt2mca (TEXT-TO-MORSE-CODE-AUDIO CONVERTER),
Copyright 2024-2026 by Thomas MARTIN, DF7TV, is licensed under
the Creative Commons Attribution-ShareAlike 4.0 International
License (CC BY-SA 4.0).

For the full license terms, see:

https://creativecommons.org/licenses/by-sa/4.0/


==================================================================
Thomas MARTIN, DF7TV
==================================================================