manulx 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- manulx-1.1.0/.gitignore +7 -0
- manulx-1.1.0/LICENSE +21 -0
- manulx-1.1.0/PKG-INFO +142 -0
- manulx-1.1.0/PROTOCOL.md +209 -0
- manulx-1.1.0/PROTOCOL.ru.md +209 -0
- manulx-1.1.0/README.md +119 -0
- manulx-1.1.0/README.ru.md +119 -0
- manulx-1.1.0/pyproject.toml +38 -0
- manulx-1.1.0/src/manulx/__init__.py +26 -0
- manulx-1.1.0/src/manulx/__main__.py +3 -0
- manulx-1.1.0/src/manulx/cli.py +91 -0
- manulx-1.1.0/src/manulx/core.py +956 -0
manulx-1.1.0/.gitignore
ADDED
manulx-1.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 smrplugg
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
manulx-1.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: manulx
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Modular SSTV-like protocol for sending images over audio
|
|
5
|
+
Project-URL: Homepage, https://github.com/smrplugg/manulx
|
|
6
|
+
Project-URL: Repository, https://github.com/smrplugg/manulx
|
|
7
|
+
Project-URL: Issues, https://github.com/smrplugg/manulx/issues
|
|
8
|
+
Author: smrplugg
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: audio,ham radio,image,modem,sstv
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Communications :: Ham Radio
|
|
15
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Requires-Dist: numpy
|
|
18
|
+
Requires-Dist: pillow
|
|
19
|
+
Requires-Dist: scipy
|
|
20
|
+
Provides-Extra: formats
|
|
21
|
+
Requires-Dist: soundfile; extra == 'formats'
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# ManulX
|
|
25
|
+
|
|
26
|
+
[Русская версия](README.ru.md)
|
|
27
|
+
|
|
28
|
+
ManulX is a modular SSTV-like protocol for sending images over audio. Image size, color mode, timing and tiling are described in the header of every transmission, and the end of every transmission is marked by an end-of-transmission signal.
|
|
29
|
+
|
|
30
|
+
Protocol specification: [PROTOCOL.md](PROTOCOL.md).
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
pip install manulx
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
From the source directory:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
pip install .
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Requirements: Python 3.10+, numpy, scipy, pillow.
|
|
45
|
+
|
|
46
|
+
WAV files are read without extra packages. To decode OGG/Opus, FLAC, MP3 and other formats, install the `formats` extra (soundfile) or have `ffmpeg` in `PATH`:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
pip install "manulx[formats]"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Usage
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
manulx encode image.png signal.wav
|
|
56
|
+
manulx decode signal.wav image.png
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The same commands are available as `python -m manulx`.
|
|
60
|
+
|
|
61
|
+
### encode
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
manulx encode INPUT OUTPUT [options]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| Option | Default | Description |
|
|
68
|
+
|--------|---------|-------------|
|
|
69
|
+
| `--mode {yuv,rgb,gray}` | `yuv` | color mode |
|
|
70
|
+
| `--pt US` | `275` | time per sample, µs (5…1280) |
|
|
71
|
+
| `--marker N` | `64` | in-line marker every N samples; 0 = no markers |
|
|
72
|
+
| `--tile WxH` | — | split into tiles, e.g. `320x240` |
|
|
73
|
+
| `--max-side N` | — | downscale so that the longer side is at most N pixels |
|
|
74
|
+
| `--call CALL` | — | callsign, up to 6 characters |
|
|
75
|
+
| `--image-id N` | `1` | image number, 0…255 |
|
|
76
|
+
| `--rate HZ` | `48000` | sample rate of the WAV file |
|
|
77
|
+
| `--stream` | — | stream mode: the height is not sent, the end is marked by the end-of-transmission signal |
|
|
78
|
+
| `--stop-after N` | — | stop each tile after N lines (early stop announced by the end-of-transmission signal) |
|
|
79
|
+
| `-q`, `--quiet` | — | no progress output |
|
|
80
|
+
|
|
81
|
+
The maximum image or tile side is 4095 pixels.
|
|
82
|
+
|
|
83
|
+
### decode
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
manulx decode INPUT OUTPUT [-q]
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`INPUT` is a recording; it may contain several transmissions. Tiles of one image are assembled into one picture. If the recording contains several images, they are saved as `OUTPUT_1.png`, `OUTPUT_2.png`, …
|
|
90
|
+
|
|
91
|
+
Exit codes:
|
|
92
|
+
|
|
93
|
+
| Code | Meaning |
|
|
94
|
+
|-----:|---------|
|
|
95
|
+
| 0 | all images received completely |
|
|
96
|
+
| 1 | error (file not found or unreadable, no transmissions found) |
|
|
97
|
+
| 2 | invalid command-line arguments |
|
|
98
|
+
| 3 | images decoded, but at least one transmission has no end-of-transmission signal |
|
|
99
|
+
|
|
100
|
+
## Python API
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from PIL import Image
|
|
104
|
+
import manulx
|
|
105
|
+
|
|
106
|
+
audio, rate = manulx.encode_audio(Image.open("test_card.png"), mode="yuv", pt_us=275,
|
|
107
|
+
marker=64, tile=None, rate=11025)
|
|
108
|
+
manulx.write_wav("signal.wav", audio, rate)
|
|
109
|
+
|
|
110
|
+
samples, rate = manulx.load_audio("signal.wav")
|
|
111
|
+
for result in manulx.decode_samples(samples, rate):
|
|
112
|
+
result["image"].save("decoded.png")
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
| Function | Description |
|
|
116
|
+
|----------|-------------|
|
|
117
|
+
| `encode_audio(img, mode, pt_us, marker, tile, max_side, call, image_id, rate, log, progress, stream, stop_after)` | PIL image → `(samples float32, sample_rate)` |
|
|
118
|
+
| `write_wav(path, samples, rate)` | write 16-bit mono WAV |
|
|
119
|
+
| `load_audio(path)` | read a recording → `(samples, sample_rate)` |
|
|
120
|
+
| `read_wav(path)` | read WAV without extra packages |
|
|
121
|
+
| `decode_samples(samples, rate, log, progress)` | list of dicts: `image` (PIL), `id`, `w`, `h`, `tiles`, `call`, `complete`, `notes` |
|
|
122
|
+
| `plan(W, H, tile, mode, pt_us, marker, call, image_id, stream)` | tile headers and total duration in seconds, without encoding |
|
|
123
|
+
| `eot_watch(samples, rate)` | for live recording: time of the last end-of-transmission signal and whether a new transmission started after it |
|
|
124
|
+
| `ManulXError` | exception for invalid parameters and undecodable input |
|
|
125
|
+
|
|
126
|
+
## Examples
|
|
127
|
+
|
|
128
|
+
The [examples](examples) directory contains source images, encoded signals (11025 Hz) and the results of decoding them.
|
|
129
|
+
|
|
130
|
+
| Source | Command | Signal | Duration | Decoded |
|
|
131
|
+
|--------|---------|--------|---------:|---------|
|
|
132
|
+
| [test_card.png](examples/test_card.png) | `manulx encode test_card.png test_card_yuv.wav --rate 11025` | [test_card_yuv.wav](examples/test_card_yuv.wav) | 42.7 s | [test_card_yuv_decoded.png](examples/test_card_yuv_decoded.png) |
|
|
133
|
+
| [test_card.png](examples/test_card.png) | `manulx encode test_card.png test_card_rgb.wav --mode rgb --rate 11025` | [test_card_rgb.wav](examples/test_card_rgb.wav) | 77.1 s | [test_card_rgb_decoded.png](examples/test_card_rgb_decoded.png) |
|
|
134
|
+
| [test_card.png](examples/test_card.png) | `manulx encode test_card.png test_card_gray.wav --mode gray --rate 11025` | [test_card_gray.wav](examples/test_card_gray.wav) | 31.0 s | [test_card_gray_decoded.png](examples/test_card_gray_decoded.png) |
|
|
135
|
+
| [test_card.png](examples/test_card.png) | `manulx encode test_card.png test_card_stream.wav --stream --rate 11025` | [test_card_stream.wav](examples/test_card_stream.wav) | 42.7 s | [test_card_stream_decoded.png](examples/test_card_stream_decoded.png) |
|
|
136
|
+
| [tiles_source.png](examples/tiles_source.png) | `manulx encode tiles_source.png tiles.wav --tile 160x100 --rate 11025` | [tiles.wav](examples/tiles.wav) | 51.5 s | [tiles_decoded.png](examples/tiles_decoded.png) |
|
|
137
|
+
|
|
138
|
+
[examples/encode_decode.py](examples/encode_decode.py) is the Python API example.
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
MIT, see [LICENSE](LICENSE).
|
manulx-1.1.0/PROTOCOL.md
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# ManulX protocol, version 1.1
|
|
2
|
+
|
|
3
|
+
[Русская версия](PROTOCOL.ru.md)
|
|
4
|
+
|
|
5
|
+
ManulX transmits an image as an audio signal. Image size, color mode, timing and tiling are described in the header of every transmission, so the receiver does not need to know the mode in advance.
|
|
6
|
+
|
|
7
|
+
## 1. Signal
|
|
8
|
+
|
|
9
|
+
The signal is a single sine tone with varying frequency (frequency modulation). The phase is continuous: when the frequency changes, the phase is carried over, so the signal has no discontinuities. Amplitude carries no information.
|
|
10
|
+
|
|
11
|
+
A sample value `v` (0…255) is sent as the frequency
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
f = 1500 Hz + v / 255 × 800 Hz
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
| Value | Frequency |
|
|
18
|
+
|------:|----------:|
|
|
19
|
+
| 0 (black) | 1500.0 Hz |
|
|
20
|
+
| 64 | 1700.8 Hz |
|
|
21
|
+
| 128 | 1901.6 Hz |
|
|
22
|
+
| 192 | 2102.4 Hz |
|
|
23
|
+
| 255 (white) | 2300.0 Hz |
|
|
24
|
+
|
|
25
|
+
Every sample lasts the same time `pt` (time per sample), 5…1280 µs, default 275 µs.
|
|
26
|
+
|
|
27
|
+
Service tones lie outside the image band:
|
|
28
|
+
|
|
29
|
+
| Frequency | Purpose |
|
|
30
|
+
|----------:|---------|
|
|
31
|
+
| 1900 Hz | leader, separators |
|
|
32
|
+
| 1200 Hz | sync pulses (header, line, end of transmission) |
|
|
33
|
+
| 1100 Hz | in-line markers |
|
|
34
|
+
|
|
35
|
+
Digital data (header, line numbers, end of transmission) use the image band frequencies: bit `0` = 1500 Hz, bit `1` = 2300 Hz. Bits are sent most significant first.
|
|
36
|
+
|
|
37
|
+
## 2. Transmission structure
|
|
38
|
+
|
|
39
|
+
One transmission carries one image or one tile.
|
|
40
|
+
|
|
41
|
+
| Part | Content | Duration |
|
|
42
|
+
|------|---------|---------:|
|
|
43
|
+
| Leader | 1900 Hz 300 ms, 1200 Hz 10 ms, 1900 Hz 300 ms | 610 ms |
|
|
44
|
+
| Header, 3 copies | each: 1900 Hz 20 ms, 1200 Hz 30 ms, 158 bits × 5 ms | 3 × 840 ms |
|
|
45
|
+
| Separator | 1900 Hz | 10 ms |
|
|
46
|
+
| Lines | lines 0 … n−1 (section 5) | n × line time |
|
|
47
|
+
| End of transmission, 2 copies | each: 1900 Hz 20 ms, 1200 Hz 30 ms, 32 bits × 5 ms | 2 × 210 ms |
|
|
48
|
+
| Tail | 1900 Hz | 50 ms |
|
|
49
|
+
|
|
50
|
+
Consecutive transmissions (tiles) are separated by 300 ms of silence.
|
|
51
|
+
|
|
52
|
+
## 3. Header (158 bits)
|
|
53
|
+
|
|
54
|
+
| Field | Bits | Meaning |
|
|
55
|
+
|-------|-----:|---------|
|
|
56
|
+
| magic | 4 | `1010` (0xA) |
|
|
57
|
+
| version | 4 | `1` |
|
|
58
|
+
| mode | 2 | 0 = grayscale, 1 = YUV 4:2:0, 2 = RGB |
|
|
59
|
+
| pt_code | 8 | time per sample = (pt_code + 1) × 5 µs |
|
|
60
|
+
| marker | 8 | in-line marker every N samples; 0 = no markers |
|
|
61
|
+
| tile_w | 12 | tile width |
|
|
62
|
+
| tile_h | 12 | tile height; 0 = stream mode |
|
|
63
|
+
| tile_x | 12 | tile position in the image, X |
|
|
64
|
+
| tile_y | 12 | tile position in the image, Y |
|
|
65
|
+
| full_w | 12 | image width |
|
|
66
|
+
| full_h | 12 | image height; 0 = stream mode |
|
|
67
|
+
| image_id | 8 | image number; tiles with the same id form one image |
|
|
68
|
+
| callsign | 36 | 6 characters × 6 bits |
|
|
69
|
+
| CRC | 16 | CRC-16/CCITT of all preceding bits |
|
|
70
|
+
|
|
71
|
+
CRC-16/CCITT: polynomial 0x1021, initial value 0xFFFF, no reflection, no final XOR.
|
|
72
|
+
|
|
73
|
+
Callsign: each character is its index in the alphabet `" ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/-."` (space = 0, A = 1 … Z = 26, 0 = 27 …), written as 6 bits. The callsign is padded with spaces to 6 characters.
|
|
74
|
+
|
|
75
|
+
The header is sent three times. Each copy starts with its own 1900 → 1200 Hz edge, which the receiver uses to align that copy in time. If no copy passes the CRC check, the receiver takes the majority value of each bit across the copies and checks the CRC again.
|
|
76
|
+
|
|
77
|
+
Example: 320×240, YUV, 275 µs, marker every 64, image_id 1, callsign `R0ABC`:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
magic 1010
|
|
81
|
+
version 0001
|
|
82
|
+
mode 01 YUV
|
|
83
|
+
pt_code 00110110 54 -> (54 + 1) × 5 = 275 µs
|
|
84
|
+
marker 01000000 64
|
|
85
|
+
tile_w 000101000000 320
|
|
86
|
+
tile_h 000011110000 240
|
|
87
|
+
tile_x 000000000000 0
|
|
88
|
+
tile_y 000000000000 0
|
|
89
|
+
full_w 000101000000 320
|
|
90
|
+
full_h 000011110000 240
|
|
91
|
+
image_id 00000001 1
|
|
92
|
+
callsign 010010 011011 000001 000010 000011 000000
|
|
93
|
+
R=18 0=27 A=1 B=2 C=3 space
|
|
94
|
+
CRC 0100000110110010
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## 4. Color modes
|
|
98
|
+
|
|
99
|
+
**Grayscale (mode 0).** Each line carries luminance:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
Y = 0.299 R + 0.587 G + 0.114 B
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
**RGB (mode 2).** Each line carries all R samples, then all G samples, then all B samples.
|
|
106
|
+
|
|
107
|
+
**YUV 4:2:0 (mode 1).**
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Y = 0.299 R + 0.587 G + 0.114 B
|
|
111
|
+
Cb = 128 − 0.168736 R − 0.331264 G + 0.5 B
|
|
112
|
+
Cr = 128 + 0.5 R − 0.418688 G − 0.081312 B
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Luminance is sent in every line at full resolution. Chroma is averaged over 2×2 pixel blocks (chroma width = ⌈w / 2⌉; for an odd width the last column and for an odd height the last row are duplicated for averaging). Each pair of lines shares the chroma:
|
|
116
|
+
|
|
117
|
+
| Line | Payload |
|
|
118
|
+
|------|---------|
|
|
119
|
+
| even (0, 2, 4 …) | Y[w] + Cr[⌈w/2⌉] |
|
|
120
|
+
| odd (1, 3, 5 …) | Y[w] + Cb[⌈w/2⌉] |
|
|
121
|
+
|
|
122
|
+
The receiver combines Cr of the even line and Cb of the odd line and converts back to RGB.
|
|
123
|
+
|
|
124
|
+
## 5. Line
|
|
125
|
+
|
|
126
|
+
| Part | Content | Duration |
|
|
127
|
+
|------|---------|---------:|
|
|
128
|
+
| Sync | 1200 Hz | 5 ms |
|
|
129
|
+
| Porch | 1500 Hz | 1 ms |
|
|
130
|
+
| Line number | 12 bits of the number + 1 parity bit, 1 ms each | 13 ms |
|
|
131
|
+
| Guard | first sample of the payload | 0.3 ms |
|
|
132
|
+
| Payload | samples of `pt` each, with markers | see below |
|
|
133
|
+
| Guard | last sample of the payload | 0.3 ms |
|
|
134
|
+
|
|
135
|
+
Parity bit = sum of the 12 number bits mod 2. Example: line 5 → `000000000101`, parity `0`.
|
|
136
|
+
|
|
137
|
+
The payload is the sample sequence of the line (section 4). If `marker` > 0, after every `marker` samples (except at the end of the line) a marker is inserted:
|
|
138
|
+
|
|
139
|
+
| Part | Content | Duration |
|
|
140
|
+
|------|---------|---------:|
|
|
141
|
+
| Guard | previous sample | 0.3 ms |
|
|
142
|
+
| Marker | 1100 Hz | 1 ms |
|
|
143
|
+
| Guard | next sample | 0.3 ms |
|
|
144
|
+
|
|
145
|
+
A guard repeats the neighbouring sample value; it keeps the receiver's filter from smearing service tones into the image.
|
|
146
|
+
|
|
147
|
+
Line time:
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
T_line = 5 + 1 + 13 + 2 × 0.3 + N × pt + M × (1 + 2 × 0.3) [ms]
|
|
151
|
+
N = payload length: w (grayscale), w + ⌈w/2⌉ (YUV), 3w (RGB)
|
|
152
|
+
M = ⌊(N − 1) / marker⌋ if marker > 0, otherwise 0
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## 6. End of transmission (32 bits)
|
|
156
|
+
|
|
157
|
+
| Field | Bits | Meaning |
|
|
158
|
+
|-------|-----:|---------|
|
|
159
|
+
| magic | 4 | `0101` (0x5) |
|
|
160
|
+
| image_id | 8 | image number |
|
|
161
|
+
| lines | 12 | number of lines actually sent |
|
|
162
|
+
| CRC | 8 | CRC-8 of the preceding 24 bits |
|
|
163
|
+
|
|
164
|
+
CRC-8: polynomial 0x07, initial value 0x00, no reflection, no final XOR.
|
|
165
|
+
|
|
166
|
+
Example, image 1, 240 lines: `0101 00000001 000011110000 10101101`.
|
|
167
|
+
|
|
168
|
+
Sent twice, each copy as in section 2. The receiver interprets it as follows:
|
|
169
|
+
|
|
170
|
+
| Situation | Meaning |
|
|
171
|
+
|-----------|---------|
|
|
172
|
+
| received, lines = tile_h | the tile was received completely |
|
|
173
|
+
| received, lines < tile_h | the transmission was stopped early; there are no further lines |
|
|
174
|
+
| received, tile_h = 0 | stream mode; the number of lines is the image height |
|
|
175
|
+
| not received | the transmission was interrupted; lines after the last received line are missing |
|
|
176
|
+
|
|
177
|
+
## 7. Tiles and stream mode
|
|
178
|
+
|
|
179
|
+
**Tiles.** The image is split into rectangles of `tile_w × tile_h`, row by row starting at the top-left corner; edge tiles may be smaller. Each tile is a separate transmission with its own header containing `tile_x`, `tile_y`, `full_w`, `full_h`. The receiver assembles tiles with the same `image_id` and image size into one image.
|
|
180
|
+
|
|
181
|
+
**Stream mode.** `tile_h` = `full_h` = 0. Lines are sent until the end of transmission; the height comes from it. Tiling is possible only by width.
|
|
182
|
+
|
|
183
|
+
## 8. Duration
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
T_tile = 0.610 + 3 × 0.840 + 0.010 + h × T_line + 2 × 0.210 + 0.050 [s]
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Example: 320×240, 275 µs, marker 64.
|
|
190
|
+
|
|
191
|
+
| Mode | Line | Transmission |
|
|
192
|
+
|------|-----:|-------------:|
|
|
193
|
+
| YUV 4:2:0 | 162.8 ms | 42.7 s |
|
|
194
|
+
| Grayscale | 114.0 ms | 31.0 s |
|
|
195
|
+
| RGB | 306.0 ms | 77.1 s |
|
|
196
|
+
|
|
197
|
+
YUV line: 5 + 1 + 13 + 0.6 + 480 × 0.275 + 7 × 1.6 = 162.8 ms.
|
|
198
|
+
|
|
199
|
+
## 9. Reference decoder
|
|
200
|
+
|
|
201
|
+
The decoder in this repository works as follows:
|
|
202
|
+
|
|
203
|
+
1. Resamples the audio to 24 kHz, shifts it down by 1700 Hz and low-pass filters it (passband about 200–3200 Hz).
|
|
204
|
+
2. Estimates the frequency from the phase rotation between neighbouring samples. Averaging is done on the complex product of neighbouring samples, not on the frequency; bits are decided by the median frequency of the bit interval.
|
|
205
|
+
3. Finds the header: a 1200 Hz pulse of about 30 ms preceded by the 1900 Hz leader. Reads the three copies and checks the CRC.
|
|
206
|
+
4. Finds line sync pulses, reads line numbers and places lines by number. A line number is accepted if it agrees with the number of a neighbouring sync pulse and the time between them. The line period is adjusted to the actual playback speed.
|
|
207
|
+
5. Inside a line, finds the markers and adjusts the timing of each segment between them. The mean frequency of each sample interval is converted back to a value: `v = (f − 1500) / 800 × 255`.
|
|
208
|
+
6. Finds the end of transmission. Lines missing inside the image are filled from neighbouring lines; missing lines at the end of an interrupted transmission are left empty.
|
|
209
|
+
7. Converts color back to RGB and assembles tiles.
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# Протокол ManulX, версия 1.1
|
|
2
|
+
|
|
3
|
+
[English version](PROTOCOL.md)
|
|
4
|
+
|
|
5
|
+
ManulX передаёт изображение звуковым сигналом. Размер изображения, цветовой режим, временные параметры и разбиение на тайлы описываются в заголовке каждой передачи, поэтому приёмнику не нужно заранее знать режим.
|
|
6
|
+
|
|
7
|
+
## 1. Сигнал
|
|
8
|
+
|
|
9
|
+
Сигнал — один синусоидальный тон с изменяющейся частотой (частотная модуляция). Фаза непрерывна: при смене частоты фаза сохраняется, поэтому в сигнале нет разрывов. Амплитуда информации не несёт.
|
|
10
|
+
|
|
11
|
+
Значение отсчёта `v` (0…255) передаётся частотой
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
f = 1500 Гц + v / 255 × 800 Гц
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
| Значение | Частота |
|
|
18
|
+
|---------:|--------:|
|
|
19
|
+
| 0 (чёрный) | 1500,0 Гц |
|
|
20
|
+
| 64 | 1700,8 Гц |
|
|
21
|
+
| 128 | 1901,6 Гц |
|
|
22
|
+
| 192 | 2102,4 Гц |
|
|
23
|
+
| 255 (белый) | 2300,0 Гц |
|
|
24
|
+
|
|
25
|
+
Каждый отсчёт длится одинаковое время `pt` (время на отсчёт), 5…1280 мкс, по умолчанию 275 мкс.
|
|
26
|
+
|
|
27
|
+
Служебные тоны лежат вне полосы изображения:
|
|
28
|
+
|
|
29
|
+
| Частота | Назначение |
|
|
30
|
+
|--------:|------------|
|
|
31
|
+
| 1900 Гц | лидер, разделители |
|
|
32
|
+
| 1200 Гц | синхроимпульсы (заголовок, строка, сигнал окончания) |
|
|
33
|
+
| 1100 Гц | метки внутри строки |
|
|
34
|
+
|
|
35
|
+
Цифровые данные (заголовок, номера строк, сигнал окончания) передаются частотами полосы изображения: бит `0` = 1500 Гц, бит `1` = 2300 Гц. Биты передаются старшим вперёд.
|
|
36
|
+
|
|
37
|
+
## 2. Структура передачи
|
|
38
|
+
|
|
39
|
+
Одна передача содержит одно изображение или один тайл.
|
|
40
|
+
|
|
41
|
+
| Часть | Содержимое | Длительность |
|
|
42
|
+
|-------|------------|-------------:|
|
|
43
|
+
| Лидер | 1900 Гц 300 мс, 1200 Гц 10 мс, 1900 Гц 300 мс | 610 мс |
|
|
44
|
+
| Заголовок, 3 копии | каждая: 1900 Гц 20 мс, 1200 Гц 30 мс, 158 бит × 5 мс | 3 × 840 мс |
|
|
45
|
+
| Разделитель | 1900 Гц | 10 мс |
|
|
46
|
+
| Строки | строки 0 … n−1 (раздел 5) | n × время строки |
|
|
47
|
+
| Сигнал окончания, 2 копии | каждая: 1900 Гц 20 мс, 1200 Гц 30 мс, 32 бита × 5 мс | 2 × 210 мс |
|
|
48
|
+
| Хвост | 1900 Гц | 50 мс |
|
|
49
|
+
|
|
50
|
+
Последовательные передачи (тайлы) разделяются 300 мс тишины.
|
|
51
|
+
|
|
52
|
+
## 3. Заголовок (158 бит)
|
|
53
|
+
|
|
54
|
+
| Поле | Бит | Значение |
|
|
55
|
+
|------|----:|----------|
|
|
56
|
+
| magic | 4 | `1010` (0xA) |
|
|
57
|
+
| version | 4 | `1` |
|
|
58
|
+
| mode | 2 | 0 = оттенки серого, 1 = YUV 4:2:0, 2 = RGB |
|
|
59
|
+
| pt_code | 8 | время на отсчёт = (pt_code + 1) × 5 мкс |
|
|
60
|
+
| marker | 8 | метка через каждые N отсчётов; 0 = без меток |
|
|
61
|
+
| tile_w | 12 | ширина тайла |
|
|
62
|
+
| tile_h | 12 | высота тайла; 0 = потоковый режим |
|
|
63
|
+
| tile_x | 12 | положение тайла в изображении по X |
|
|
64
|
+
| tile_y | 12 | положение тайла в изображении по Y |
|
|
65
|
+
| full_w | 12 | ширина изображения |
|
|
66
|
+
| full_h | 12 | высота изображения; 0 = потоковый режим |
|
|
67
|
+
| image_id | 8 | номер изображения; тайлы с одинаковым номером образуют одно изображение |
|
|
68
|
+
| callsign | 36 | позывной: 6 символов × 6 бит |
|
|
69
|
+
| CRC | 16 | CRC-16/CCITT всех предыдущих битов |
|
|
70
|
+
|
|
71
|
+
CRC-16/CCITT: полином 0x1021, начальное значение 0xFFFF, без отражения, без финального XOR.
|
|
72
|
+
|
|
73
|
+
Позывной: каждый символ — его номер в алфавите `" ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/-."` (пробел = 0, A = 1 … Z = 26, 0 = 27 …), записанный 6 битами. Позывной дополняется пробелами до 6 символов.
|
|
74
|
+
|
|
75
|
+
Заголовок передаётся трижды. Каждая копия начинается со своего фронта 1900 → 1200 Гц, по которому приёмник выравнивает эту копию во времени. Если ни одна копия не прошла проверку CRC, приёмник берёт для каждого бита значение большинства копий и проверяет CRC повторно.
|
|
76
|
+
|
|
77
|
+
Пример: 320×240, YUV, 275 мкс, метка через 64, image_id 1, позывной `R0ABC`:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
magic 1010
|
|
81
|
+
version 0001
|
|
82
|
+
mode 01 YUV
|
|
83
|
+
pt_code 00110110 54 -> (54 + 1) × 5 = 275 мкс
|
|
84
|
+
marker 01000000 64
|
|
85
|
+
tile_w 000101000000 320
|
|
86
|
+
tile_h 000011110000 240
|
|
87
|
+
tile_x 000000000000 0
|
|
88
|
+
tile_y 000000000000 0
|
|
89
|
+
full_w 000101000000 320
|
|
90
|
+
full_h 000011110000 240
|
|
91
|
+
image_id 00000001 1
|
|
92
|
+
callsign 010010 011011 000001 000010 000011 000000
|
|
93
|
+
R=18 0=27 A=1 B=2 C=3 пробел
|
|
94
|
+
CRC 0100000110110010
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## 4. Цветовые режимы
|
|
98
|
+
|
|
99
|
+
**Оттенки серого (mode 0).** Каждая строка содержит яркость:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
Y = 0.299 R + 0.587 G + 0.114 B
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
**RGB (mode 2).** Каждая строка содержит все отсчёты R, затем все G, затем все B.
|
|
106
|
+
|
|
107
|
+
**YUV 4:2:0 (mode 1).**
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Y = 0.299 R + 0.587 G + 0.114 B
|
|
111
|
+
Cb = 128 − 0.168736 R − 0.331264 G + 0.5 B
|
|
112
|
+
Cr = 128 + 0.5 R − 0.418688 G − 0.081312 B
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Яркость передаётся в каждой строке с полным разрешением. Цветность усредняется по блокам 2×2 пикселя (ширина цветности = ⌈w / 2⌉; при нечётной ширине для усреднения дублируется последний столбец, при нечётной высоте — последняя строка). Каждая пара строк делит цветность:
|
|
116
|
+
|
|
117
|
+
| Строка | Полезная нагрузка |
|
|
118
|
+
|--------|-------------------|
|
|
119
|
+
| чётная (0, 2, 4 …) | Y[w] + Cr[⌈w/2⌉] |
|
|
120
|
+
| нечётная (1, 3, 5 …) | Y[w] + Cb[⌈w/2⌉] |
|
|
121
|
+
|
|
122
|
+
Приёмник объединяет Cr чётной строки и Cb нечётной и переводит обратно в RGB.
|
|
123
|
+
|
|
124
|
+
## 5. Строка
|
|
125
|
+
|
|
126
|
+
| Часть | Содержимое | Длительность |
|
|
127
|
+
|-------|------------|-------------:|
|
|
128
|
+
| Синхроимпульс | 1200 Гц | 5 мс |
|
|
129
|
+
| Порог | 1500 Гц | 1 мс |
|
|
130
|
+
| Номер строки | 12 бит номера + 1 бит чётности, по 1 мс | 13 мс |
|
|
131
|
+
| Защита | первый отсчёт полезной нагрузки | 0,3 мс |
|
|
132
|
+
| Полезная нагрузка | отсчёты по `pt`, с метками | см. ниже |
|
|
133
|
+
| Защита | последний отсчёт полезной нагрузки | 0,3 мс |
|
|
134
|
+
|
|
135
|
+
Бит чётности = сумма 12 битов номера по модулю 2. Пример: строка 5 → `000000000101`, чётность `0`.
|
|
136
|
+
|
|
137
|
+
Полезная нагрузка — последовательность отсчётов строки (раздел 4). Если `marker` > 0, после каждых `marker` отсчётов (кроме конца строки) вставляется метка:
|
|
138
|
+
|
|
139
|
+
| Часть | Содержимое | Длительность |
|
|
140
|
+
|-------|------------|-------------:|
|
|
141
|
+
| Защита | предыдущий отсчёт | 0,3 мс |
|
|
142
|
+
| Метка | 1100 Гц | 1 мс |
|
|
143
|
+
| Защита | следующий отсчёт | 0,3 мс |
|
|
144
|
+
|
|
145
|
+
Защита повторяет значение соседнего отсчёта; она не даёт фильтру приёмника размазывать служебные тоны по изображению.
|
|
146
|
+
|
|
147
|
+
Время строки:
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
T_строки = 5 + 1 + 13 + 2 × 0,3 + N × pt + M × (1 + 2 × 0,3) [мс]
|
|
151
|
+
N = длина полезной нагрузки: w (серый), w + ⌈w/2⌉ (YUV), 3w (RGB)
|
|
152
|
+
M = ⌊(N − 1) / marker⌋ при marker > 0, иначе 0
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## 6. Сигнал окончания (32 бита)
|
|
156
|
+
|
|
157
|
+
| Поле | Бит | Значение |
|
|
158
|
+
|------|----:|----------|
|
|
159
|
+
| magic | 4 | `0101` (0x5) |
|
|
160
|
+
| image_id | 8 | номер изображения |
|
|
161
|
+
| lines | 12 | число фактически переданных строк |
|
|
162
|
+
| CRC | 8 | CRC-8 предыдущих 24 битов |
|
|
163
|
+
|
|
164
|
+
CRC-8: полином 0x07, начальное значение 0x00, без отражения, без финального XOR.
|
|
165
|
+
|
|
166
|
+
Пример, изображение 1, 240 строк: `0101 00000001 000011110000 10101101`.
|
|
167
|
+
|
|
168
|
+
Передаётся дважды, каждая копия — как в разделе 2. Приёмник понимает его так:
|
|
169
|
+
|
|
170
|
+
| Ситуация | Значение |
|
|
171
|
+
|----------|----------|
|
|
172
|
+
| принят, lines = tile_h | тайл принят полностью |
|
|
173
|
+
| принят, lines < tile_h | передача остановлена досрочно; дальнейших строк нет |
|
|
174
|
+
| принят, tile_h = 0 | потоковый режим; число строк — высота изображения |
|
|
175
|
+
| не принят | передача оборвана; строк после последней принятой нет |
|
|
176
|
+
|
|
177
|
+
## 7. Тайлы и потоковый режим
|
|
178
|
+
|
|
179
|
+
**Тайлы.** Изображение делится на прямоугольники `tile_w × tile_h` построчно, начиная с левого верхнего угла; крайние тайлы могут быть меньше. Каждый тайл — отдельная передача со своим заголовком, содержащим `tile_x`, `tile_y`, `full_w`, `full_h`. Приёмник собирает тайлы с одинаковыми `image_id` и размером изображения в одно изображение.
|
|
180
|
+
|
|
181
|
+
**Потоковый режим.** `tile_h` = `full_h` = 0. Строки передаются до сигнала окончания; высота берётся из него. Разбиение на тайлы возможно только по ширине.
|
|
182
|
+
|
|
183
|
+
## 8. Длительность
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
T_тайла = 0,610 + 3 × 0,840 + 0,010 + h × T_строки + 2 × 0,210 + 0,050 [с]
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Пример: 320×240, 275 мкс, метка 64.
|
|
190
|
+
|
|
191
|
+
| Режим | Строка | Передача |
|
|
192
|
+
|-------|-------:|---------:|
|
|
193
|
+
| YUV 4:2:0 | 162,8 мс | 42,7 с |
|
|
194
|
+
| Оттенки серого | 114,0 мс | 31,0 с |
|
|
195
|
+
| RGB | 306,0 мс | 77,1 с |
|
|
196
|
+
|
|
197
|
+
Строка YUV: 5 + 1 + 13 + 0,6 + 480 × 0,275 + 7 × 1,6 = 162,8 мс.
|
|
198
|
+
|
|
199
|
+
## 9. Эталонный декодер
|
|
200
|
+
|
|
201
|
+
Декодер в этом репозитории работает так:
|
|
202
|
+
|
|
203
|
+
1. Приводит звук к 24 кГц, сдвигает вниз на 1700 Гц и фильтрует фильтром нижних частот (полоса пропускания около 200–3200 Гц).
|
|
204
|
+
2. Оценивает частоту по повороту фазы между соседними отсчётами. Усредняется комплексное произведение соседних отсчётов, а не частота; биты определяются по медиане частоты на интервале бита.
|
|
205
|
+
3. Находит заголовок: импульс 1200 Гц длительностью около 30 мс, которому предшествует лидер 1900 Гц. Читает три копии и проверяет CRC.
|
|
206
|
+
4. Находит синхроимпульсы строк, читает номера строк и расставляет строки по номерам. Номер строки принимается, если он согласуется с номером соседнего синхроимпульса и временем между ними. Период строк подстраивается под фактическую скорость воспроизведения.
|
|
207
|
+
5. Внутри строки находит метки и уточняет время каждого участка между ними. Средняя частота на интервале каждого отсчёта переводится обратно в значение: `v = (f − 1500) / 800 × 255`.
|
|
208
|
+
6. Находит сигнал окончания. Строки, пропущенные внутри изображения, восполняются соседними; недостающие строки в конце оборванной передачи остаются пустыми.
|
|
209
|
+
7. Переводит цвет обратно в RGB и собирает тайлы.
|