Metadata-Version: 2.4
Name: morse-transceiver
Version: 2.0.2
Summary: Ultrasonic Audio Steganography for Cross-Modal Information Embedding
Author: Morse Transceiver Contributors
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/cycleuser/Morse-Transceiver
Project-URL: Repository, https://github.com/cycleuser/Morse-Transceiver
Project-URL: Issues, https://github.com/cycleuser/Morse-Transceiver/issues
Keywords: morse,steganography,ultrasonic,audio,video,embedding,watermark
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: soundfile>=0.12
Requires-Dist: moviepy>=2.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.5; extra == "gui"
Requires-Dist: matplotlib>=3.7; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# Morse Transceiver - Ultrasonic Audio Steganography

##### Version: 2.0.0

## Overview

**Morse Transceiver** is a cross-modal information embedding framework that leverages ultrasonic frequency carriers (17.5–19.5 kHz) to embed hidden data into audio/video files. The embedded signals are:

- **Inaudible to humans**: Above the adult hearing threshold (~16 kHz for ages 30+)
- **Recordable by computers**: Below the Nyquist frequency (22.05 kHz at 44.1 kHz sampling)
- **Compression-resilient**: Survives AAC/MP3 encoding at ≥64 kbps bitrates

This enables persistent metadata embedding, copyright watermarking, and secure cross-modal communication.

## Key Features

### Ultrasonic Steganography
- **Dual-Tone FSK Modulation**: Encodes Morse dots and dashes at distinct ultrasonic frequencies
- **Adaptive Frequency Selection**: Optimizes carriers based on sample rate, target bitrate, and age demographic
- **Protocol Framing**: KA/AR preamble/postamble with MD5 checksum verification
- **Redundancy**: Configurable repetition (3–5×) for compression resilience

### Cross-Modal Embedding
- **Audio Files**: WAV, FLAC, OGG, MP3
- **Video Files**: MP4, MOV, AVI, MKV (with audio track)
- **High-Bitrate Preservation**: Uses 320 kbps AAC to maintain ultrasonic fidelity

### CLI Interface
```bash
# Embed message into video
morse-embed sample.mp4 -m "SECRET MESSAGE" -o output.mp4

# Extract message from video
morse-extract output.mp4 -f 17500

# Verify frequency inaudibility
morse-verify --age 40
```

## The Science

### The Perceptual-Technical Boundary

Human hearing follows an age-dependent decline (presbycusis):
- **Young (<25)**: ~19–20 kHz upper limit
- **Adult (30–40)**: ~16–18 kHz upper limit
- **Adult (40–50)**: ~14–16 kHz upper limit
- **Senior (50+)**: ~12–14 kHz upper limit

Standard audio sampling (44.1 kHz) supports frequencies up to 22.05 kHz (Nyquist limit).

This creates an optimal embedding window of **17.5–19.5 kHz**—inaudible to most adults yet fully representable digitally.

### Frequency Modes

| Mode | Dot (Hz) | Dash (Hz) | Use Case |
|------|----------|-----------|----------|
| Conservative | 17,000 | 18,000 | Maximum compatibility |
| Standard | 17,500 | 18,500 | Default (recommended) |
| Aggressive | 18,000 | 19,000 | Enhanced stealth |
| Maximum | 18,500 | 19,500 | Maximum inaudibility |

## Installation

### From PyPI (Recommended)
```bash
pip install morse-transceiver
```

### From Source
```bash
git clone https://github.com/cycleuser/Morse-Transceiver.git
cd Morse-Transceiver
pip install -r requirements.txt
```

### Optional GUI Dependencies
```bash
pip install morse-transceiver[gui]
```

## Quick Start

### Embed Message
```python
from stego_engine import UltrasonicStegoEngine

# Embed into video
UltrasonicStegoEngine.embed_signal(
    "sample.mp4", "output.mp4",
    text="SECRET MESSAGE",
    wpm=15, freq=17500, volume=0.1,
    redundancy=5, use_dual_tone=True
)
```

### Extract Message
```python
morse, status = UltrasonicStegoEngine.extract_signal(
    "output.mp4", freq=17500, wpm=15, use_dual_tone=True
)

from morse_transceiver.morse_logic import MorseLogic
decoded = MorseLogic.morse_to_text(morse)
payload, proto_status = MorseLogic.parse_packet(decoded)
print(f"Extracted: {payload}")
```

### CLI Usage
```bash
# Embed
morse-embed sample.mp4 -m "HELLO WORLD" -o output.mp4 --wpm 15 --redundancy 5

# Extract
morse-extract output.mp4 --freq 17500 --wpm 15

# Verify inaudibility for age group
morse-verify --age 40 --mode standard
```

## Testing

Run the full test suite:
```bash
python test_ultrasonic.py
```

Or with pytest:
```bash
pip install pytest
pytest tests/ -v
```

## Transcoding Resilience

| Profile | Bitrate | Result |
|---------|---------|--------|
| High Quality | 320 kbps | ✓ 100% Recovery |
| Standard | 192 kbps | ✓ 100% Recovery |
| Social Media | 128 kbps | ⚠ Partial Recovery |
| Low Bandwidth | 64 kbps | ✓ With Lower Frequencies |
| Ultra Low | 32 kbps | ✗ Failure |

## Project Structure

```
Morse-Transceiver/
├── morse_transceiver/          # Python package
│   ├── __init__.py             # Package metadata
│   ├── morse_logic.py          # Morse encoding/decoding
│   └── cli.py                  # Command-line interface
├── stego_engine.py             # Ultrasonic steganography engine
├── test_ultrasonic.py          # Full test suite
├── tests/                      # pytest tests
│   ├── __init__.py
│   └── test_stego.py
├── Article.md                  # English paper
├── Article_CN.md               # Chinese paper
├── pyproject.toml              # Package configuration
├── requirements.txt            # Dependencies
├── publish.py                  # PyPI publishing script
├── upload_pypi.sh              # Bash upload script
├── upload_pypi.bat             # Windows upload script
├── build.sh                    # Bash build script
└── build.bat                   # Windows build script
```

## Development

### Build Package
```bash
# Linux/macOS
chmod +x build.sh
./build.sh

# Windows
build.bat

# Or using publish.py
python publish.py build
```

### Publish to PyPI
```bash
# Linux/macOS
chmod +x upload_pypi.sh
./upload_pypi.sh

# Windows
upload_pypi.bat

# Or using publish.py
python publish.py test     # TestPyPI
python publish.py release  # PyPI
```

## License

**GNU General Public License v3.0 (GPLv3)**

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

## Citation

If you use this work in your research, please cite:

```bibtex
@misc{morse-transceiver-2026,
  title={Cross-Modal Information Embedding via Ultrasonic Audio Steganography},
  author={Morse Transceiver Contributors},
  year={2026},
  url={https://github.com/cycleuser/Morse-Transceiver}
}
```

## References

See [Article.md](Article.md) and [Article_CN.md](Article_CN.md) for full academic paper with 20 references.
