morse2sound 1.0.1__tar.gz

morse2sound-1.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2024 Dr. Andreas Krüger, DJ3EI, dj3ei@famsik.de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

morse2sound-1.0.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.1
+Name: morse2sound
+Version: 1.0.1
+Summary: Software to convert text into Morse code sound files.
+Author-email: "Dr. Andreas Krüger, DJ3EI" <dj3ei@famsik.de>
+Project-URL: Homepage, https://gitlab.com/4ham/morse2sound
+Project-URL: Repository, https://gitlab.com/4ham/morse2sound
+Project-URL: Issues, https://gitlab.com/4ham/morse2sound/-/issues
+Keywords: Morse,Morsecode,ham,amateur radio,cw
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Communications :: Ham Radio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Morse2sound
+
+## What can I do with this?
+
+From some text, produce a sound file that contains that text, encoded
+in Morse code.
+
+## Background
+
+### What's this Morse code thing?
+
+Fast message transport via telegraphy was one of the first practical
+uses of electricity, dating back to the middle of the 18th century.
+
+[Samuel F. B. Morse](https://en.wikipedia.org/wiki/Samuel_Morse)
+originally devised a scheme to transmit numbers via electric pulses,
+with a code book that allowed translation of words to those numbers
+and back.  Later, his assistant [Alfred
+L. Vail](https://en.wikipedia.org/wiki/Alfred_Vail) improved on this
+by coding single letters, so the code book became obsolete.  He used
+short, long, longer, and extra long impulses.  His original method is
+still remembered as [American Morse
+Code](https://en.wikipedia.org/wiki/American_Morse_code), although it
+sees little use.  This was again improved by [Friedrich
+C. Gerke](https://en.wikipedia.org/wiki/Friedrich_Clemens_Gerke), who
+simplified from four different impulse lengths to just two.  Gerke's
+code is virtually identical to what is nowadays known as International
+Morse Code.  In 1865, an international treaty established the
+[ITU](https://www.itu.int/en/Pages/default.aspx) as the first
+multinational standards organization, with the purpose of facilitating
+cross-border transport of messages.  That same [1865
+treaty](http://handle.itu.int/11.1004/020.1000/5.1.61.fr.200) also
+formalized Gerke's version of the Morse code.  The coding of the
+letters a-z and the digits 0-9 have remained unchanged since then, but
+other things like punctuation indeed have seen some changes.  The ITU
+still exists and to this day standardizes the [international Morse
+code](https://www.itu.int/dms_pubrec/itu-r/rec/m/R-REC-M.1677-1-200910-I!!PDF-E.pdf),
+among many other things.
+
+### Is anybody still using Morse telegraphy?
+
+Morse telegraphy is still extensively used by certain sections of the
+HAM [amateur radio](https://en.wikipedia.org/wiki/Amateur_radio)
+community. For obscure historical/technical reasons, Morse telegraphy
+is generally designated as "CW".
+
+CW is ubiquitous.  On an everyday basis, any CW-capable short wave
+receiver (such as [Twente Web-SDR](http://websdr.ewi.utwente.nl:8901/)
+available on the internet) is likely to pick up CW signals if tuned
+through the designated telegraphy ranges, e.g., 7000-7040 kHz.  CW
+sees extensive use among DXers (radio amateurs trying to reach rare
+far-away places), in contests (radio amateur competitions), and by the
+"home-brew" community (radio amateurs constructing their own
+equipment).  By its supporters, CW is considered an enjoyable mode of
+operation.
+
+## Usage
+
+### What does this software do?
+
+It takes text and produces, as a sound file or stream, a Morse encoded
+version of that text.
+
+The output format is that of
+[`.wav`](https://en.wikipedia.org/wiki/WAV) files.
+
+### Basic usage
+
+```shell
+morse2sound --in message.txt --wpm 12 --out message.wav
+```
+
+### Character set
+
+The international Morse code.
+
+## Remarks
+
+### Compression
+
+The `.wav` files generated compress quite well, with the compression
+algorithm of your choice.
+
+## Installation
+
+Make sure when you say `python`, then a version 3 Python comes up.
+E.g., `python --version` should give a 3.8 or better version.
+
+I suggest you create and activate a `venv`.  On Linux:
+
+    python3 -m venv venv
+    . venv/bin/activate
+
+
+### Install
+
+    pip install morse2sound
+
+## Contributing
+
+Have `git` installed.
+
+```shell
+git clone https://gitlab.com/4ham/morse2sound.git
+```
+
+Change to the directory `morse2sound` that was created by the above.
+
+Create and activate a virtual environment as per the
+[documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments)
+pertaining to your OS.
+
+Then:
+
+```shell
+pip install -r requirements_test.frozen
+./lint.py
+```
+
+Do your changes and repeat that `python ./lint.py` part in your branch
+before starting a pull request as usual towards the
+[repository](https://gitlab.com/4ham/morse2sound).
+
+## To run locally
+
+```shell
+PYTHONPATH=$(pwd)/src python src/cw_enc/driver.py -h
+```
+
+## To build locally
+
+In an activated
+[virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments):
+
+```shell
+pip install --upgrade build
+rm -rf dist build morse2sound.egg-info
+python -m build
+```
+
+To install what you built:
+
+```shell
+pip install dist/morse2sound-*-py3-none-any.whl
+```
+
+## To upload
+
+This is useful only for the maintainer:
+
+* Edit the version in `pyproject.toml`
+* `git tag -s vx.y.z`
+* `git push origin --tags`
+
+```shell
+pip install --upgrade build twine
+rm -rf dist build src/morse2sound.egg-info
+python -m build
+python -m twine upload dist/*
+```

morse2sound-1.0.1/README.md

@@ -0,0 +1,160 @@
+# Morse2sound
+
+## What can I do with this?
+
+From some text, produce a sound file that contains that text, encoded
+in Morse code.
+
+## Background
+
+### What's this Morse code thing?
+
+Fast message transport via telegraphy was one of the first practical
+uses of electricity, dating back to the middle of the 18th century.
+
+[Samuel F. B. Morse](https://en.wikipedia.org/wiki/Samuel_Morse)
+originally devised a scheme to transmit numbers via electric pulses,
+with a code book that allowed translation of words to those numbers
+and back.  Later, his assistant [Alfred
+L. Vail](https://en.wikipedia.org/wiki/Alfred_Vail) improved on this
+by coding single letters, so the code book became obsolete.  He used
+short, long, longer, and extra long impulses.  His original method is
+still remembered as [American Morse
+Code](https://en.wikipedia.org/wiki/American_Morse_code), although it
+sees little use.  This was again improved by [Friedrich
+C. Gerke](https://en.wikipedia.org/wiki/Friedrich_Clemens_Gerke), who
+simplified from four different impulse lengths to just two.  Gerke's
+code is virtually identical to what is nowadays known as International
+Morse Code.  In 1865, an international treaty established the
+[ITU](https://www.itu.int/en/Pages/default.aspx) as the first
+multinational standards organization, with the purpose of facilitating
+cross-border transport of messages.  That same [1865
+treaty](http://handle.itu.int/11.1004/020.1000/5.1.61.fr.200) also
+formalized Gerke's version of the Morse code.  The coding of the
+letters a-z and the digits 0-9 have remained unchanged since then, but
+other things like punctuation indeed have seen some changes.  The ITU
+still exists and to this day standardizes the [international Morse
+code](https://www.itu.int/dms_pubrec/itu-r/rec/m/R-REC-M.1677-1-200910-I!!PDF-E.pdf),
+among many other things.
+
+### Is anybody still using Morse telegraphy?
+
+Morse telegraphy is still extensively used by certain sections of the
+HAM [amateur radio](https://en.wikipedia.org/wiki/Amateur_radio)
+community. For obscure historical/technical reasons, Morse telegraphy
+is generally designated as "CW".
+
+CW is ubiquitous.  On an everyday basis, any CW-capable short wave
+receiver (such as [Twente Web-SDR](http://websdr.ewi.utwente.nl:8901/)
+available on the internet) is likely to pick up CW signals if tuned
+through the designated telegraphy ranges, e.g., 7000-7040 kHz.  CW
+sees extensive use among DXers (radio amateurs trying to reach rare
+far-away places), in contests (radio amateur competitions), and by the
+"home-brew" community (radio amateurs constructing their own
+equipment).  By its supporters, CW is considered an enjoyable mode of
+operation.
+
+## Usage
+
+### What does this software do?
+
+It takes text and produces, as a sound file or stream, a Morse encoded
+version of that text.
+
+The output format is that of
+[`.wav`](https://en.wikipedia.org/wiki/WAV) files.
+
+### Basic usage
+
+```shell
+morse2sound --in message.txt --wpm 12 --out message.wav
+```
+
+### Character set
+
+The international Morse code.
+
+## Remarks
+
+### Compression
+
+The `.wav` files generated compress quite well, with the compression
+algorithm of your choice.
+
+## Installation
+
+Make sure when you say `python`, then a version 3 Python comes up.
+E.g., `python --version` should give a 3.8 or better version.
+
+I suggest you create and activate a `venv`.  On Linux:
+
+    python3 -m venv venv
+    . venv/bin/activate
+
+
+### Install
+
+    pip install morse2sound
+
+## Contributing
+
+Have `git` installed.
+
+```shell
+git clone https://gitlab.com/4ham/morse2sound.git
+```
+
+Change to the directory `morse2sound` that was created by the above.
+
+Create and activate a virtual environment as per the
+[documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments)
+pertaining to your OS.
+
+Then:
+
+```shell
+pip install -r requirements_test.frozen
+./lint.py
+```
+
+Do your changes and repeat that `python ./lint.py` part in your branch
+before starting a pull request as usual towards the
+[repository](https://gitlab.com/4ham/morse2sound).
+
+## To run locally
+
+```shell
+PYTHONPATH=$(pwd)/src python src/cw_enc/driver.py -h
+```
+
+## To build locally
+
+In an activated
+[virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments):
+
+```shell
+pip install --upgrade build
+rm -rf dist build morse2sound.egg-info
+python -m build
+```
+
+To install what you built:
+
+```shell
+pip install dist/morse2sound-*-py3-none-any.whl
+```
+
+## To upload
+
+This is useful only for the maintainer:
+
+* Edit the version in `pyproject.toml`
+* `git tag -s vx.y.z`
+* `git push origin --tags`
+
+```shell
+pip install --upgrade build twine
+rm -rf dist build src/morse2sound.egg-info
+python -m build
+python -m twine upload dist/*
+```

morse2sound-1.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+authors = [
+    {name = "Dr. Andreas Krüger, DJ3EI", email = "dj3ei@famsik.de"},
+]
+name = "morse2sound"
+description = "Software to convert text into Morse code sound files."
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["Morse", "Morsecode", "ham", "amateur radio", "cw"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Education",
+    "Topic :: Communications :: Ham Radio",
+    "Topic :: Multimedia :: Sound/Audio :: Sound Synthesis"
+]
+version = "1.0.1"
+dependencies = []
+
+[project.urls]
+Homepage = "https://gitlab.com/4ham/morse2sound"
+Repository = "https://gitlab.com/4ham/morse2sound"
+Issues = "https://gitlab.com/4ham/morse2sound/-/issues"
+
+[project.scripts]
+morse2sound = "cw_enc.driver:drive"
+
+[tool.isort]
+profile = "black"
+

morse2sound-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

morse2sound-1.0.1/src/cw_enc/__init__.py

@@ -0,0 +1,131 @@
+import sys
+import wave
+from types import TracebackType
+from typing import IO, Literal, Optional, Type
+
+from cw_enc.cw_coder import (
+    CWCoder,
+    ignore_char,
+    raise_on_notmorseable_char,
+    replace_char_with_questionmark,
+)
+from cw_enc.paddle_cache import PaddleCache
+from cw_enc.paddle_mksnd import PaddleMksnd
+from cw_enc.paddle_samplecount import PaddleSampleCount
+from cw_enc.parameters import ParameterError, Parameters
+from cw_enc.wave_blocks import make_wave_blocks
+
+
+def cw_enc(
+    intext: str = "Hello, world!",
+    infile: Optional[str] = None,
+    on_unmorseable: str = "?",
+    out: str = "cwenc_out.wav",
+    samples_per_second: int = 8000,
+    amplitude: float | int = 2**15 - 2,
+    channels: Literal[1] | Literal[2] = 1,
+    wpm: int | float = 12.0,
+    farnsworth_wpm: None | int | float = None,
+    f: int | float = 700,
+    f_delta: int | float = 1,
+    skirt_time: float = 5e-3,
+    skirt_shape: Literal["RC", "L"] = "RC",
+) -> None:
+    """The main driver program to produce Morse code .wav - files from characters."""
+
+    if infile is not None and intext is not None:
+        raise ParameterError("intext (when infile is also set)", intext)
+    elif intext is not None:
+        text = intext
+    elif infile is not None:
+        with open(infile) as inf:
+            text = inf.read()
+    else:
+        raise FileNotFoundError(
+            f"No text specified to convert to sound. Try {sys.argv[0]} -h"
+        )
+
+    pms = Parameters(
+        samples_per_second=samples_per_second,
+        amplitude=amplitude,
+        channels=channels,
+        wpm=wpm,
+        farnsworth_wpm=farnsworth_wpm,
+        f=f,
+        f_delta=f_delta,
+        skirt_time=skirt_time,
+        skirt_shape=skirt_shape,
+    )
+
+    binout: str | IO[bytes]
+    if out == "-":
+        binout = sys.stdout.buffer
+    else:
+        binout = out
+
+    with wave.open(binout, mode="wb") as wavout:
+        wavout.setnchannels(pms.channels)
+        wavout.setsampwidth(2)
+        wavout.setframerate(pms.samples_per_second)
+
+        # We will have a "paddle" that is given dits, dahs, between-character spaces, and between-words spaces.
+
+        # Waveblock, containing pre-canned byte sequence for those four.
+        wb = make_wave_blocks(pms)
+
+        class WriteWavData:
+            """Glue code: A simple object that has a write() method expecting bytes."""
+
+            def write(self, b: bytes) -> None:
+                wavout.writeframesraw(b)
+
+        # The paddle that actually does the "heavy lifting", writing the data to the file.
+        paddle_write_data = PaddleMksnd(what_to_write=wb, consumer=WriteWavData())
+
+        # But first, deal with a complication: .wav files want to know how long they're going to be.
+        class WriteWavHeader(PaddleSampleCount):
+            """A subclass of Paddle that can count how many samples will be written."""
+
+            def __exit__(
+                self,
+                exc_type: Optional[Type[BaseException]],
+                exc_val: Optional[BaseException],
+                exc_tb: Optional[TracebackType],
+            ) -> Literal[False]:
+                # On close, write the number of samples to the wav file:
+                wavout.setnframes(self._count)
+                return super().__exit__(exc_type, exc_val, exc_tb)
+
+        paddle_write_header = WriteWavHeader(
+            dit_samples=int(len(wb.dit) / pms.channels / 2),
+            dah_samples=int(len(wb.dah) / pms.channels / 2),
+            ci_silence_samples=int(len(wb.csilence) / pms.channels / 2),
+            iw_silence_samples=int(len(wb.iwsilence) / pms.channels / 2),
+        )
+
+        # We go through the entire message twice:
+        # First time for sample counting, secondly for real writing of the data.
+        #
+        # This is what a PaddleCache can do for us:
+        # It patiently stores all the information given to it, until it is closed.
+        # When it is closed (as a context manager), it will replay that information
+        # on each of the paddles handed in, in order, one after the other.
+        with PaddleCache([paddle_write_header, paddle_write_data]) as paddle:
+            # Someone needs to convert the morse code to strings of dits and dahs
+            # and hand those over to the paddle.
+            # That is what a CWCoder does.
+            if on_unmorseable == "False":
+                unmorseable_character_strategy = raise_on_notmorseable_char
+            elif on_unmorseable == "?":
+                unmorseable_character_strategy = replace_char_with_questionmark
+            elif on_unmorseable == "x":
+                unmorseable_character_strategy = ignore_char
+            else:
+                raise ParameterError("on_unmorseable", on_unmorseable)
+            coder = CWCoder(paddle=paddle, on_missing=unmorseable_character_strategy)
+            for c in text:
+                coder.code(c)
+
+    # For good luck and stability:
+    if out == "-":
+        sys.stdout.buffer.flush()

morse2sound-1.0.1/src/cw_enc/cw_coder.py

@@ -0,0 +1,103 @@
+from typing import Callable
+
+from cw_enc.paddle import Paddle
+
+
+def raise_on_notmorseable_char(char: str) -> str:
+    raise KeyError('Character "{}" not representable in Morse code.'.format(char))
+
+
+def ignore_char(char: str) -> str:
+    return "x"
+
+
+def replace_char_with_questionmark(char: str) -> str:
+    return "..--.."
+
+
+class CWCoder:
+    """Internal class that knows how to call dit and dah and so on, given a message character."""
+
+    codelist = {
+        "a": ".-",
+        "b": "-...",
+        "c": "-.-.",
+        "d": "-..",
+        "e": ".",
+        "f": "..-.",
+        "g": "--.",
+        "h": "....",
+        "i": "..",
+        "j": ".---",
+        "k": "-.-",
+        "l": ".-..",
+        "m": "--",
+        "n": "-.",
+        "o": "---",
+        "p": ".--.",
+        "q": "--.-",
+        "r": ".-.",
+        "s": "...",
+        "t": "-",
+        "u": "..-",
+        "v": "...-",
+        "w": ".--",
+        "x": "-..-",
+        "y": "-.--",
+        "z": "--..",
+        "0": "-----",
+        "1": ".----",
+        "2": "..---",
+        "3": "...--",
+        "4": "....-",
+        "5": ".....",
+        "6": "-....",
+        "7": "--...",
+        "8": "---..",
+        "9": "----.",
+        ":": "---...",
+        "=": "-...-",
+        "-": "-....-",
+        "?": "..--..",
+        ".": ".-.-.-",
+        ",": "--..--",
+        "(": "-.--.",
+        ")": "-.--.-",
+        "+": ".-.-.",
+        "/": "-..-.",
+        "@": ".--.-.",
+    }
+
+    def __init__(
+        self,
+        paddle: Paddle,
+        on_missing: Callable[[str], str] = raise_on_notmorseable_char,
+        codelist: dict[str, str] = codelist,
+    ) -> None:
+        self.paddle = paddle
+
+        class Codelist(dict[str, str]):
+            def __missing__(self, char: str) -> str:
+                return on_missing(char)
+
+        self.codelist = Codelist(codelist)
+
+    def code(self, char: str, csilence: bool = True) -> None:
+        if char == " " or char == "\n" or char == "\t":
+            self.paddle.iwsilence()
+        else:
+            code = self.codelist[char.lower()]
+            if code == "x":
+                pass
+            else:
+                for dida in self.codelist[char.lower()]:
+                    if dida == ".":
+                        self.paddle.dit()
+                    elif dida == "-":
+                        self.paddle.dah()
+                    else:
+                        raise RuntimeError(
+                            'Morse symbol "{}" is neither "." nor "-".'.format(dida)
+                        )
+                if csilence:
+                    self.paddle.csilence()