manulx 1.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,26 @@
1
+ """ManulX: modular SSTV-like protocol for sending images over audio."""
2
+
3
+ from .core import (
4
+ ManulXError,
5
+ decode_samples,
6
+ encode_audio,
7
+ eot_watch,
8
+ load_audio,
9
+ plan,
10
+ read_wav,
11
+ write_wav,
12
+ )
13
+
14
+ __version__ = "1.1.0"
15
+
16
+ __all__ = [
17
+ "ManulXError",
18
+ "decode_samples",
19
+ "encode_audio",
20
+ "eot_watch",
21
+ "load_audio",
22
+ "plan",
23
+ "read_wav",
24
+ "write_wav",
25
+ "__version__",
26
+ ]
manulx/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ main()
manulx/cli.py ADDED
@@ -0,0 +1,91 @@
1
+ """Command-line interface: `manulx encode` / `manulx decode`."""
2
+
3
+ import argparse
4
+ import sys
5
+
6
+ from PIL import Image
7
+
8
+ from . import __version__
9
+ from .core import ManulXError, decode_samples, encode_audio, load_audio, write_wav
10
+
11
+
12
+ def parse_tile(s):
13
+ try:
14
+ w, h = s.lower().split("x")
15
+ return int(w), int(h)
16
+ except ValueError:
17
+ raise argparse.ArgumentTypeError("expected WxH, e.g. 320x240")
18
+
19
+
20
+ def cmd_encode(a):
21
+ audio, rate = encode_audio(
22
+ Image.open(a.input), mode=a.mode, pt_us=a.pt, marker=a.marker, tile=a.tile,
23
+ max_side=a.max_side, call=a.call, image_id=a.image_id, rate=a.rate,
24
+ stream=a.stream, stop_after=a.stop_after,
25
+ log=(lambda s: None) if a.quiet else print,
26
+ )
27
+ write_wav(a.output, audio, rate)
28
+ if not a.quiet:
29
+ print(f"-> {a.output}")
30
+
31
+
32
+ def cmd_decode(a):
33
+ x, rate = load_audio(a.input)
34
+ results = decode_samples(x, rate, log=(lambda s: None) if a.quiet else print)
35
+ incomplete = False
36
+ for i, r in enumerate(results):
37
+ out = a.output
38
+ if len(results) > 1:
39
+ stem, dot, ext = a.output.rpartition(".")
40
+ out = f"{stem}_{i + 1}.{ext}" if dot else f"{a.output}_{i + 1}"
41
+ r["image"].save(out)
42
+ incomplete |= not r["complete"]
43
+ print(f"image #{r['id']} {r['w']}x{r['h']}, tiles {r['tiles']}, "
44
+ f"{'complete' if r['complete'] else 'INCOMPLETE'} -> {out}")
45
+ return 3 if incomplete else 0
46
+
47
+
48
+ def build_parser():
49
+ p = argparse.ArgumentParser(prog="manulx", description="ManulX: send images over audio.")
50
+ p.add_argument("--version", action="version", version=f"manulx {__version__}")
51
+ sp = p.add_subparsers(dest="cmd", required=True)
52
+
53
+ e = sp.add_parser("encode", help="image -> WAV")
54
+ e.add_argument("input", help="input image (PNG, JPEG, ...)")
55
+ e.add_argument("output", help="output WAV file")
56
+ e.add_argument("--mode", choices=["yuv", "rgb", "gray"], default="yuv", help="color mode (default: yuv)")
57
+ e.add_argument("--pt", type=float, default=275, help="time per sample, us, 5..1280 (default: 275)")
58
+ e.add_argument("--marker", type=int, default=64, help="in-line marker every N samples, 0 = none (default: 64)")
59
+ e.add_argument("--tile", type=parse_tile, help="split into tiles WxH, e.g. 320x240")
60
+ e.add_argument("--max-side", type=int, default=0, help="downscale so that the longer side <= N")
61
+ e.add_argument("--call", default="", help="callsign, up to 6 characters")
62
+ e.add_argument("--image-id", type=int, default=1, help="image id 0..255 (default: 1)")
63
+ e.add_argument("--rate", type=int, default=48000, help="sample rate, Hz (default: 48000)")
64
+ e.add_argument("--stream", action="store_true", help="stream mode: height is not sent, end is marked by EOT")
65
+ e.add_argument("--stop-after", type=int, help="stop each tile after N lines (early stop, announced by EOT)")
66
+ e.add_argument("-q", "--quiet", action="store_true", help="no progress output")
67
+ e.set_defaults(func=cmd_encode)
68
+
69
+ d = sp.add_parser("decode", help="audio -> PNG")
70
+ d.add_argument("input", help="recording: WAV; OGG/Opus, FLAC, MP3 via soundfile or ffmpeg")
71
+ d.add_argument("output", help="output PNG (several images get suffixes _1, _2, ...)")
72
+ d.add_argument("-q", "--quiet", action="store_true", help="print only the result")
73
+ d.set_defaults(func=cmd_decode)
74
+ return p
75
+
76
+
77
+ def main(argv=None):
78
+ a = build_parser().parse_args(argv)
79
+ try:
80
+ code = a.func(a)
81
+ except ManulXError as e:
82
+ print(f"manulx: {e}", file=sys.stderr)
83
+ sys.exit(1)
84
+ except FileNotFoundError as e:
85
+ print(f"manulx: {e}", file=sys.stderr)
86
+ sys.exit(1)
87
+ sys.exit(code or 0)
88
+
89
+
90
+ if __name__ == "__main__":
91
+ main()
manulx/core.py ADDED
@@ -0,0 +1,956 @@
1
+ """ManulX core: encoder and decoder.
2
+
3
+ Protocol specification: PROTOCOL.md (English), PROTOCOL.ru.md (Russian).
4
+ """
5
+ import math
6
+ import sys
7
+ import wave
8
+
9
+ import numpy as np
10
+ from PIL import Image
11
+ from scipy.signal import firwin, oaconvolve, resample_poly
12
+
13
+ # ---------------- константы протокола ----------------
14
+ F_BLACK, F_WHITE = 1500.0, 2300.0
15
+ F_LEADER = 1900.0
16
+ F_SYNC = 1200.0
17
+ F_MARK = 1100.0
18
+
19
+ T_LEADER = 0.300
20
+ T_BREAK = 0.010
21
+ T_HSEP = 0.020
22
+ T_HSTART = 0.030
23
+ T_HBIT = 0.005
24
+ N_HCOPIES = 3
25
+ T_POST_HDR = 0.010
26
+ T_TAIL = 0.050
27
+ T_GAP_SILENCE = 0.300
28
+
29
+ T_SYNC = 0.005
30
+ T_PORCH = 0.001
31
+ T_LBIT = 0.001
32
+ N_LBITS = 13 # 12 бит номера + чётность
33
+ T_MARK = 0.001
34
+ T_GUARD = 0.0003 # защитный интервал: соседний пиксель удерживается у меток и краёв строки
35
+
36
+ MAGIC, VERSION = 0xA, 1
37
+ MODES = {"gray": 0, "yuv": 1, "rgb": 2}
38
+ MODE_NAMES = {v: k for k, v in MODES.items()}
39
+ CALL_CHARS = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/-."
40
+ HEADER_FIELDS = [ # (имя, бит)
41
+ ("magic", 4), ("version", 4), ("mode", 2), ("pt_code", 8), ("marker", 8),
42
+ ("tile_w", 12), ("tile_h", 12), ("tile_x", 12), ("tile_y", 12),
43
+ ("full_w", 12), ("full_h", 12), ("image_id", 8), ("call", 36),
44
+ ]
45
+ N_HBITS = sum(b for _, b in HEADER_FIELDS) + 16
46
+ EOT_MAGIC = 0x5
47
+ N_EBITS = 32
48
+ N_ECOPIES = 2
49
+ T_HCOPY = T_HSEP + T_HSTART + N_HBITS * T_HBIT
50
+ T_ECOPY = T_HSEP + T_HSTART + N_EBITS * T_HBIT
51
+ T_EOT = N_ECOPIES * T_ECOPY
52
+
53
+
54
+ def crc16_ccitt(bits):
55
+ crc = 0xFFFF
56
+ for b in bits:
57
+ top = (crc >> 15) & 1
58
+ crc = (crc << 1) & 0xFFFF
59
+ if top ^ b:
60
+ crc ^= 0x1021
61
+ return crc
62
+
63
+
64
+ def crc8(bits):
65
+ crc = 0
66
+ for b in bits:
67
+ top = (crc >> 7) & 1
68
+ crc = (crc << 1) & 0xFF
69
+ if top ^ b:
70
+ crc ^= 0x07
71
+ return crc
72
+
73
+
74
+ def eot_to_bits(image_id, n_lines):
75
+ body = int_to_bits(EOT_MAGIC, 4) + int_to_bits(image_id & 0xFF, 8) + int_to_bits(n_lines, 12)
76
+ return body + int_to_bits(crc8(body), 8)
77
+
78
+
79
+ def bits_to_eot(bits):
80
+ body = list(bits[:24])
81
+ if crc8(body) != bits_to_int(bits[24:32]) or bits_to_int(body[:4]) != EOT_MAGIC:
82
+ return None
83
+ return dict(image_id=bits_to_int(body[4:12]), lines=bits_to_int(body[12:24]))
84
+
85
+
86
+ def int_to_bits(v, n):
87
+ return [(v >> (n - 1 - i)) & 1 for i in range(n)]
88
+
89
+
90
+ def bits_to_int(bits):
91
+ v = 0
92
+ for b in bits:
93
+ v = (v << 1) | int(b)
94
+ return v
95
+
96
+
97
+ def encode_call(call):
98
+ call = (call or "").upper()[:6].ljust(6)
99
+ v = 0
100
+ for ch in call:
101
+ v = (v << 6) | (CALL_CHARS.index(ch) if ch in CALL_CHARS else 0)
102
+ return v
103
+
104
+
105
+ def decode_call(v):
106
+ chars = []
107
+ for i in range(6):
108
+ idx = (v >> (6 * (5 - i))) & 0x3F
109
+ chars.append(CALL_CHARS[idx] if idx < len(CALL_CHARS) else "?")
110
+ return "".join(chars).strip()
111
+
112
+
113
+ def header_to_bits(h):
114
+ bits = []
115
+ for name, n in HEADER_FIELDS:
116
+ bits += int_to_bits(h[name], n)
117
+ return bits + int_to_bits(crc16_ccitt(bits), 16)
118
+
119
+
120
+ def bits_to_header(bits):
121
+ body, crc = bits[:-16], bits_to_int(bits[-16:])
122
+ if crc16_ccitt(body) != crc:
123
+ return None
124
+ h, i = {}, 0
125
+ for name, n in HEADER_FIELDS:
126
+ h[name] = bits_to_int(body[i:i + n])
127
+ i += n
128
+ if h["magic"] != MAGIC or h["version"] != VERSION or h["mode"] not in MODE_NAMES:
129
+ return None
130
+ return h
131
+
132
+
133
+ def pt_seconds(h):
134
+ return (h["pt_code"] + 1) * 5e-6
135
+
136
+
137
+ def payload_len(mode, w):
138
+ cw = (w + 1) // 2
139
+ return {0: w, 1: w + cw, 2: 3 * w}[mode]
140
+
141
+
142
+ def n_markers(mode, w, marker):
143
+ n = payload_len(mode, w)
144
+ return 0 if marker == 0 else (n - 1) // marker
145
+
146
+
147
+ def line_duration(h):
148
+ w, mode, M = h["tile_w"], h["mode"], h["marker"]
149
+ return (T_SYNC + T_PORCH + N_LBITS * T_LBIT + 2 * T_GUARD
150
+ + payload_len(mode, w) * pt_seconds(h) + n_markers(mode, w, M) * (T_MARK + 2 * T_GUARD))
151
+
152
+
153
+ # ---------------- цвет ----------------
154
+ def rgb_to_ycc(rgb):
155
+ r, g, b = [rgb[..., i].astype(np.float64) for i in range(3)]
156
+ y = 0.299 * r + 0.587 * g + 0.114 * b
157
+ cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b
158
+ cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b
159
+ return y, cb, cr
160
+
161
+
162
+ def ycc_to_rgb(y, cb, cr):
163
+ r = y + 1.402 * (cr - 128)
164
+ g = y - 0.344136 * (cb - 128) - 0.714136 * (cr - 128)
165
+ b = y + 1.772 * (cb - 128)
166
+ return np.clip(np.stack([r, g, b], -1), 0, 255).round().astype(np.uint8)
167
+
168
+
169
+ def half_width(c):
170
+ """Усреднение пар пикселей по горизонтали (ceil(w/2))."""
171
+ if c.shape[-1] % 2:
172
+ c = np.concatenate([c, c[..., -1:]], -1)
173
+ return 0.5 * (c[..., 0::2] + c[..., 1::2])
174
+
175
+
176
+ # ---------------- кодер ----------------
177
+ class ToneBuilder:
178
+ def __init__(self):
179
+ self.f, self.d = [], []
180
+
181
+ def tone(self, f, d):
182
+ self.f.append(f)
183
+ self.d.append(d)
184
+
185
+ def tones(self, fs, d):
186
+ fs = np.asarray(fs, dtype=np.float64)
187
+ self.f.append(fs)
188
+ self.d.append(np.full(len(fs), d))
189
+
190
+ def render(self, rate, amp=0.7):
191
+ f = np.concatenate([np.atleast_1d(np.asarray(x, dtype=np.float64)) for x in self.f])
192
+ d = np.concatenate([np.atleast_1d(np.asarray(x, dtype=np.float64)) for x in self.d])
193
+ ends = np.cumsum(d)
194
+ n = int(math.ceil(ends[-1] * rate))
195
+ t = (np.arange(n) + 0.5) / rate
196
+ idx = np.minimum(np.searchsorted(ends, t, side="right"), len(f) - 1)
197
+ freq = f[idx]
198
+ amp_arr = np.where(freq > 0, amp, 0.0) # f=0 -> тишина
199
+ phase = 2 * np.pi * np.cumsum(freq) / rate
200
+ return (amp_arr * np.sin(phase)).astype(np.float32)
201
+
202
+
203
+ def value_to_freq(v):
204
+ return F_BLACK + (np.clip(v, 0, 255) / 255.0) * (F_WHITE - F_BLACK)
205
+
206
+
207
+ def line_payload(mode, r, planes):
208
+ if mode == 0:
209
+ return planes[0][r]
210
+ if mode == 1:
211
+ y, cb_h, cr_h = planes
212
+ pair = r // 2
213
+ c = cr_h[pair] if r % 2 == 0 else cb_h[pair]
214
+ return np.concatenate([y[r], c])
215
+ return np.concatenate([planes[0][r], planes[1][r], planes[2][r]])
216
+
217
+
218
+ def encode_tile(tb, rgb, h, n_send=None):
219
+ mode, pt, M = h["mode"], pt_seconds(h), h["marker"]
220
+ th = rgb.shape[0]
221
+ # лидер
222
+ tb.tone(F_LEADER, T_LEADER)
223
+ tb.tone(F_SYNC, T_BREAK)
224
+ tb.tone(F_LEADER, T_LEADER)
225
+ hb = header_to_bits(h)
226
+ for _ in range(N_HCOPIES):
227
+ tb.tone(F_LEADER, T_HSEP)
228
+ tb.tone(F_SYNC, T_HSTART)
229
+ tb.tones([F_WHITE if b else F_BLACK for b in hb], T_HBIT)
230
+ tb.tone(F_LEADER, T_POST_HDR)
231
+
232
+ if mode == 0:
233
+ y, _, _ = rgb_to_ycc(rgb)
234
+ planes = (y,)
235
+ elif mode == 1:
236
+ y, cb, cr = rgb_to_ycc(rgb)
237
+ if th % 2:
238
+ cb = np.vstack([cb, cb[-1:]])
239
+ cr = np.vstack([cr, cr[-1:]])
240
+ cb_h = half_width(0.5 * (cb[0::2] + cb[1::2]))
241
+ cr_h = half_width(0.5 * (cr[0::2] + cr[1::2]))
242
+ planes = (y, cb_h, cr_h)
243
+ else:
244
+ planes = tuple(rgb[..., i].astype(np.float64) for i in range(3))
245
+
246
+ n_send = th if n_send is None else min(th, n_send)
247
+ for r in range(n_send):
248
+ tb.tone(F_SYNC, T_SYNC)
249
+ tb.tone(F_BLACK, T_PORCH)
250
+ nb = int_to_bits(r, 12)
251
+ nb.append(sum(nb) % 2)
252
+ tb.tones([F_WHITE if b else F_BLACK for b in nb], T_LBIT)
253
+ freqs = value_to_freq(line_payload(mode, r, planes))
254
+ tb.tone(freqs[0], T_GUARD)
255
+ step = M if M else len(freqs)
256
+ for s in range(0, len(freqs), step):
257
+ if s:
258
+ tb.tone(freqs[s - 1], T_GUARD)
259
+ tb.tone(F_MARK, T_MARK)
260
+ tb.tone(freqs[s], T_GUARD)
261
+ tb.tones(freqs[s:s + step], pt)
262
+ tb.tone(freqs[-1], T_GUARD)
263
+ eb = eot_to_bits(h["image_id"], n_send)
264
+ for _ in range(N_ECOPIES):
265
+ tb.tone(F_LEADER, T_HSEP)
266
+ tb.tone(F_SYNC, T_HSTART)
267
+ tb.tones([F_WHITE if b else F_BLACK for b in eb], T_HBIT)
268
+ tb.tone(F_LEADER, T_TAIL)
269
+
270
+
271
+ class ManulXError(Exception):
272
+ pass
273
+
274
+
275
+ def prepare_image(img, max_side=0):
276
+ """PIL.Image -> RGB-массив (с уменьшением, если большая сторона > max_side)."""
277
+ img = img.convert("RGB")
278
+ if max_side and max(img.size) > max_side:
279
+ k = max_side / max(img.size)
280
+ img = img.resize((max(1, round(img.width * k)), max(1, round(img.height * k))), Image.LANCZOS)
281
+ return np.asarray(img)
282
+
283
+
284
+ def plan(W, H, tile, mode, pt_us, marker, call="", image_id=1, stream=False):
285
+ """Список заголовков тайлов и полная длительность передачи (с).
286
+ stream=True — высота не пишется в заголовок (tile_h = full_h = 0), тайлы только по ширине."""
287
+ tw, th = tile if tile else (W, H)
288
+ if stream:
289
+ th = H
290
+ if max(W, H, tw, th) > 4095:
291
+ raise ManulXError("Maximum side is 4095 pixels (downscale the image or use tiles).")
292
+ if min(W, H, tw, th) < 1:
293
+ raise ManulXError("Empty image or tile.")
294
+ pt_code = int(round(pt_us / 5.0)) - 1
295
+ if not 0 <= pt_code <= 255:
296
+ raise ManulXError("Time per sample must be within 5..1280 us.")
297
+ if not 0 <= marker <= 255:
298
+ raise ManulXError("Marker interval must be within 0..255.")
299
+ mode_id = MODES[mode] if isinstance(mode, str) else mode
300
+ headers, total = [], 0.0
301
+ for ty in range(0, H, th):
302
+ for tx in range(0, W, tw):
303
+ h = dict(magic=MAGIC, version=VERSION, mode=mode_id, pt_code=pt_code,
304
+ marker=marker, tile_w=min(tw, W - tx), tile_h=min(th, H - ty),
305
+ tile_x=tx, tile_y=ty, full_w=W, full_h=H,
306
+ image_id=image_id & 0xFF, call=encode_call(call))
307
+ h["_rows"] = h["tile_h"] # реальная высота тайла (для кодера)
308
+ if stream:
309
+ h["tile_h"] = h["full_h"] = 0
310
+ if headers:
311
+ total += T_GAP_SILENCE
312
+ total += tile_duration(h)
313
+ headers.append(h)
314
+ return headers, total
315
+
316
+
317
+ def tile_duration(h):
318
+ return (2 * T_LEADER + T_BREAK + N_HCOPIES * T_HCOPY + T_POST_HDR
319
+ + h.get("_rows", h["tile_h"]) * line_duration(h) + T_EOT + T_TAIL)
320
+
321
+
322
+ def encode_audio(img, mode="yuv", pt_us=275, marker=64, tile=None, max_side=0,
323
+ call="", image_id=1, rate=48000, log=print, progress=None, stream=False, stop_after=None):
324
+ """PIL.Image -> (звук float32 [-1..1], частота дискретизации).
325
+ stream — потоковый режим (высота не указывается); stop_after — досрочно
326
+ остановить каждый тайл после N строк (для проверки сигнала окончания)."""
327
+ rgb = prepare_image(img, max_side)
328
+ H, W = rgb.shape[:2]
329
+ headers, total = plan(W, H, tile, mode, pt_us, marker, call, image_id, stream)
330
+ tb = ToneBuilder()
331
+ for i, h in enumerate(headers):
332
+ if i:
333
+ tb.tone(0.0, T_GAP_SILENCE)
334
+ x, y = h["tile_x"], h["tile_y"]
335
+ hw = {k: v for k, v in h.items() if not k.startswith("_")}
336
+ encode_tile(tb, rgb[y:y + h["_rows"], x:x + h["tile_w"]], hw, stop_after)
337
+ log(f" tile {i + 1}: {h['tile_w']}x{h['_rows']}{' (stream)' if stream else ''} @ ({x},{y}) - {tile_duration(h):.1f} s")
338
+ if progress:
339
+ progress((i + 1) / len(headers) * 0.8)
340
+ audio = tb.render(rate)
341
+ if progress:
342
+ progress(1.0)
343
+ log(f"ManulX: {W}x{H}, mode {MODE_NAMES[headers[0]['mode']]}, {pt_us:.0f} us/sample, "
344
+ f"marker every {marker}, tiles {len(headers)}, duration {len(audio) / rate:.1f} s")
345
+ return audio, rate
346
+
347
+
348
+ def write_wav(path, audio, rate):
349
+ with wave.open(path, "wb") as wf:
350
+ wf.setnchannels(1)
351
+ wf.setsampwidth(2)
352
+ wf.setframerate(int(rate))
353
+ wf.writeframes((np.clip(audio, -1, 1) * 32767).astype("<i2").tobytes())
354
+
355
+
356
+ # ---------------- декодер ----------------
357
+ WORK_RATE = 24000
358
+ F_CENTER = 1700.0
359
+
360
+
361
+ def read_wav(path):
362
+ with wave.open(path, "rb") as wf:
363
+ rate, nch, sw = wf.getframerate(), wf.getnchannels(), wf.getsampwidth()
364
+ raw = wf.readframes(wf.getnframes())
365
+ if sw == 2:
366
+ x = np.frombuffer(raw, "<i2").astype(np.float64) / 32768
367
+ elif sw == 1:
368
+ x = (np.frombuffer(raw, np.uint8).astype(np.float64) - 128) / 128
369
+ elif sw == 4:
370
+ x = np.frombuffer(raw, "<i4").astype(np.float64) / 2 ** 31
371
+ elif sw == 3:
372
+ b = np.frombuffer(raw, np.uint8).reshape(-1, 3)
373
+ v = (b[:, 0].astype(np.int32) | (b[:, 1].astype(np.int32) << 8) | (b[:, 2].astype(np.int32) << 16))
374
+ v = np.where(v >= 1 << 23, v - (1 << 24), v)
375
+ x = v / 2 ** 23
376
+ else:
377
+ raise ValueError("Unsupported WAV sample width")
378
+ if nch > 1:
379
+ x = x.reshape(-1, nch).mean(1)
380
+ return x, rate
381
+
382
+
383
+ def moving_avg(x, n):
384
+ n = max(1, int(n))
385
+ if n == 1:
386
+ return x
387
+ k = np.ones(n) / n
388
+ return np.convolve(x, k, mode="same")
389
+
390
+
391
+ def runs(mask):
392
+ """Список (start, end) непрерывных участков True."""
393
+ m = np.concatenate([[False], mask, [False]]).astype(np.int8)
394
+ d = np.diff(m)
395
+ return list(zip(np.where(d == 1)[0], np.where(d == -1)[0]))
396
+
397
+
398
+ class Demod:
399
+ """FM-демодулятор: перенос на 1700 Гц, ФНЧ, затем частота как угол
400
+ усреднённого комплексного произведения z[n+1]*conj(z[n]).
401
+ Усреднение комплексного произведения (а не уже вычисленной частоты)
402
+ устойчиво к шумовым выбросам — слабые/шумовые участки весят меньше."""
403
+
404
+ def __init__(self, x, rate):
405
+ g = math.gcd(int(rate), WORK_RATE)
406
+ if rate != WORK_RATE:
407
+ x = resample_poly(x, WORK_RATE // g, int(rate) // g)
408
+ self.fs = fs = WORK_RATE
409
+ n = np.arange(len(x))
410
+ z = x * np.exp(-2j * np.pi * F_CENTER * n / fs)
411
+ z = oaconvolve(z, firwin(121, 1500, fs=fs), mode="same")
412
+ d = z[1:] * np.conj(z[:-1]) # d[k] — на интервале [k, k+1)
413
+ d /= np.sqrt(np.abs(d)) + 1e-12 # мягкая нормировка (вес ~ амплитуде)
414
+ self.D = np.concatenate([[0j], np.cumsum(d)])
415
+ self.n = len(d)
416
+ self.dur = self.n / fs
417
+ self.f03 = self._smooth(0.0003)
418
+ self.f1 = self._smooth(0.001)
419
+ self.f4 = self._smooth(0.004)
420
+ self.f10 = self._smooth(0.010)
421
+
422
+ def _to_f(self, c):
423
+ return np.angle(c) * self.fs / (2 * np.pi) + F_CENTER
424
+
425
+ def _smooth(self, t):
426
+ k = max(1, int(round(t * self.fs))) | 1 # нечётная длина: центр окна в (i+0.5)/fs
427
+ c = np.zeros(self.n, complex)
428
+ h = k // 2
429
+ idx = np.arange(self.n)
430
+ lo, hi = np.clip(idx - h, 0, self.n), np.clip(idx - h + k, 0, self.n)
431
+ c = self.D[hi] - self.D[lo]
432
+ return self._to_f(c)
433
+
434
+ def mean(self, a, b):
435
+ """Средняя частота на интервалах времени [a, b] (векторно, дробные границы)."""
436
+ a = np.clip(np.asarray(a, float) * self.fs, 0, self.n)
437
+ b = np.clip(np.asarray(b, float) * self.fs, 0, self.n)
438
+ return self._to_f(self._D_at(b) - self._D_at(a))
439
+
440
+ def _D_at(self, x):
441
+ """Линейная интерполяция накопленной суммы D в дробной позиции x (в отсчётах)."""
442
+ i = np.minimum(np.floor(x).astype(np.int64), self.n - 1)
443
+ fr = x - i
444
+ return self.D[i] + (self.D[i + 1] - self.D[i]) * fr
445
+
446
+ def median(self, a, b):
447
+ """Медиана мгновенной частоты на [a, b] — устойчива к щелчкам (для битов)."""
448
+ i0, i1 = max(0, int(a * self.fs)), min(self.n, int(b * self.fs) + 1)
449
+ return float(np.median(self.f03[i0:i1])) if i1 > i0 else F_CENTER
450
+
451
+ def crossing(self, t_from, t_to, level, rising, src=None):
452
+ """Время первого пересечения уровня (по f03 или src) в окне, с субсемпловой точностью."""
453
+ src = self.f03 if src is None else src
454
+ i0, i1 = max(0, int(t_from * self.fs)), min(len(src) - 1, int(t_to * self.fs))
455
+ s = src[i0:i1 + 1]
456
+ if len(s) < 2:
457
+ return None
458
+ if rising:
459
+ k = np.where((s[:-1] < level) & (s[1:] >= level))[0]
460
+ else:
461
+ k = np.where((s[:-1] > level) & (s[1:] <= level))[0]
462
+ if not len(k):
463
+ return None
464
+ k = k[0]
465
+ frac = (level - s[k]) / (s[k + 1] - s[k])
466
+ return (i0 + k + 0.5 + frac) / self.fs
467
+
468
+ def step_edge(self, t_from, t_to, f_before, f_after, w_before, w_after):
469
+ """Момент перехода f_before -> f_after в окне [t_from, t_to]: минимум квадратичной
470
+ ошибки модели «ступенька» (w_before до, w_after после). Устойчиво к дрожанию частоты."""
471
+ fs = self.fs
472
+ i0 = int(t_from * fs) - int(w_before * fs)
473
+ i1 = int(t_to * fs) + int(w_after * fs) + 1
474
+ if i0 < 0 or i1 > self.n:
475
+ return None
476
+ f = np.clip(self.f03[i0:i1], 800, 2800)
477
+ cb = np.concatenate([[0], np.cumsum((f - f_before) ** 2)])
478
+ ca = np.concatenate([[0], np.cumsum((f - f_after) ** 2)])
479
+ nb, na = int(w_before * fs), int(w_after * fs)
480
+ ts = np.arange(nb, len(f) - na + 1)
481
+ cost = (cb[ts] - cb[ts - nb]) + (ca[ts + na] - ca[ts])
482
+ k = int(np.argmin(cost))
483
+ # параболическая интерполяция минимума
484
+ frac = 0.0
485
+ if 0 < k < len(cost) - 1:
486
+ y0, y1, y2 = cost[k - 1], cost[k], cost[k + 1]
487
+ den = y0 - 2 * y1 + y2
488
+ if den > 0:
489
+ frac = 0.5 * (y0 - y2) / den
490
+ return (i0 + ts[k] + frac) / fs
491
+
492
+
493
+ def read_bits(dm, start, nbits, T, f0=F_BLACK, f1=F_WHITE):
494
+ """Чтение FSK-битов с подстройкой фазы на каждом переходе 0<->1 (как в UART),
495
+ чтобы плавающая скорость не накапливала сдвиг. Возвращает средние частоты бит."""
496
+ thr = (f0 + f1) / 2
497
+ t, prev, out = start, None, []
498
+ for _ in range(nbits):
499
+ v = dm.median(t + 0.2 * T, t + 0.8 * T)
500
+ b = v > thr
501
+ if prev is not None and b != prev:
502
+ fa, fb = (f1, f0) if prev else (f0, f1)
503
+ e = dm.step_edge(t - 0.4 * T, t + 0.4 * T, fa, fb, 0.5 * T, 0.5 * T)
504
+ if e is not None:
505
+ t = t + 0.6 * (e - t)
506
+ v = dm.median(t + 0.2 * T, t + 0.8 * T)
507
+ b = v > thr
508
+ out.append(v)
509
+ prev = b
510
+ t += T
511
+ return np.array(out)
512
+
513
+
514
+ def find_headers(dm, t_start):
515
+ """Ищет лидер, затем читает 3 копии заголовка (каждую по своему фронту).
516
+ Возвращает (header, t_hdr_end) или (None, None)."""
517
+ fs = dm.fs
518
+ i_start = int(t_start * fs)
519
+ thr = (F_BLACK + F_WHITE) / 2
520
+ # ищем стартовый импульс 1200 Гц (~30 мс), перед которым ~100 мс преобладает 1900 Гц.
521
+ # Доля, а не непрерывность — так провалы и щелчки в лидере не мешают.
522
+ start_pulses = np.abs(dm.f10[i_start:] - F_SYNC) < 100
523
+ for a, b in runs(start_pulses):
524
+ if (b - a) / fs < 0.012:
525
+ continue
526
+ ts = (i_start + a) / fs
527
+ pre = dm.f1[max(0, int((ts - 0.12) * fs)): int((ts - 0.01) * fs)]
528
+ if not len(pre) or np.mean(np.abs(pre - F_LEADER) < 100) < 0.6:
529
+ continue
530
+ t0 = dm.step_edge(ts - 0.012, ts + 0.012, F_LEADER, F_SYNC, 0.015, 0.025)
531
+ if t0 is None:
532
+ continue
533
+ # убеждаемся, что дальше действительно 1200 Гц ~30 мс (а не просто конец лидера)
534
+ if abs(dm.mean(t0 + 0.005, t0 + 0.025) - F_SYNC) > 120:
535
+ continue
536
+ copies, last_edge = [], t0
537
+ for k in range(N_HCOPIES):
538
+ exp = t0 + k * T_HCOPY
539
+ e = t0 if k == 0 else dm.step_edge(exp - 0.020, exp + 0.020, F_LEADER, F_SYNC, 0.015, 0.025)
540
+ if e is None or abs(dm.mean(e + 0.005, e + 0.025) - F_SYNC) > 120 \
541
+ or abs(dm.mean(e - 0.015, e - 0.004) - F_LEADER) > 150:
542
+ e = exp
543
+ last_edge = e
544
+ v = read_bits(dm, e + T_HSTART, N_HBITS, T_HBIT)
545
+ copies.append(v)
546
+ h = bits_to_header([int(x > thr) for x in v])
547
+ if h:
548
+ return h, t0 - T_HSEP + N_HCOPIES * T_HCOPY
549
+ # побитовое голосование (среднее частот по копиям)
550
+ v = np.median(copies, axis=0)
551
+ h = bits_to_header([int(x > thr) for x in v])
552
+ if h:
553
+ return h, t0 - T_HSEP + N_HCOPIES * T_HCOPY
554
+ return None, None
555
+
556
+
557
+ def find_eots(dm, t_from, t_to, image_id=None):
558
+ """Все сигналы окончания в [t_from, t_to]: список (eot, t_start, t_end).
559
+ Признак: импульс 1200 Гц ~30 мс, перед которым ~20 мс 1900 Гц; затем 32 бита с CRC-8.
560
+ Две копии; если обе не прошли CRC — побитовое голосование."""
561
+ fs = dm.fs
562
+ i0, i1 = max(0, int(t_from * fs)), min(dm.n, int(t_to * fs))
563
+ if i1 - i0 < int(0.05 * fs):
564
+ return []
565
+ thr = (F_BLACK + F_WHITE) / 2
566
+ found, skip_until = [], -1.0
567
+ for a, b in runs(np.abs(dm.f10[i0:i1] - F_SYNC) < 100):
568
+ if (b - a) / fs < 0.012:
569
+ continue
570
+ ts = (i0 + a) / fs
571
+ if ts < skip_until:
572
+ continue
573
+ pre = dm.f1[max(0, int((ts - 0.022) * fs)): int((ts - 0.003) * fs)]
574
+ if not len(pre) or np.mean(np.abs(pre - F_LEADER) < 120) < 0.5:
575
+ continue
576
+ e0 = dm.step_edge(ts - 0.012, ts + 0.012, F_LEADER, F_SYNC, 0.015, 0.025)
577
+ if e0 is None:
578
+ continue
579
+ copies, res = [], None
580
+ for k in range(N_ECOPIES):
581
+ exp = e0 + k * T_ECOPY
582
+ e = e0 if k == 0 else (dm.step_edge(exp - 0.01, exp + 0.01, F_LEADER, F_SYNC, 0.015, 0.025) or exp)
583
+ v = read_bits(dm, e + T_HSTART, N_EBITS, T_HBIT)
584
+ copies.append(v)
585
+ res = bits_to_eot([int(x > thr) for x in v])
586
+ if res:
587
+ break
588
+ if res is None:
589
+ res = bits_to_eot([int(x > thr) for x in np.median(copies, axis=0)])
590
+ if res is None:
591
+ continue
592
+ if image_id is not None and res["image_id"] != image_id:
593
+ continue
594
+ start = e0 - T_HSEP
595
+ # если это вторая копия — начало EOT на одну копию раньше
596
+ prev = dm.f1[max(0, int((start - T_ECOPY + T_HSEP + 0.005) * fs)): int((start - T_ECOPY + T_HSEP + 0.025) * fs)]
597
+ if len(prev) and np.mean(np.abs(prev - F_SYNC) < 120) > 0.6:
598
+ start -= T_ECOPY
599
+ end = start + T_EOT
600
+ found.append((res, start, end))
601
+ skip_until = end + 0.01
602
+ return found
603
+
604
+
605
+ def find_marker(dm, m_nom, rate, wide=False):
606
+ """Центр метки 1100 Гц около ожидаемого начала m_nom: минимум 1-мс скользящего
607
+ среднего частоты (пиксели >= 1500 Гц, поэтому минимум приходится на метку)."""
608
+ fs = dm.fs
609
+ c_nom = m_nom + 0.5 * T_MARK * rate
610
+ span = 0.015 if wide else 0.0012
611
+ lo, hi = max(1, int((c_nom - span) * fs)), min(dm.n - 1, int((c_nom + span) * fs))
612
+ w = dm.f1[lo:hi]
613
+ if len(w) < 3:
614
+ return None
615
+ k = int(np.argmin(w))
616
+ if w[k] > 1300 or k == 0 or k == len(w) - 1:
617
+ return None
618
+ y0, y1, y2 = w[k - 1], w[k], w[k + 1]
619
+ den = y0 - 2 * y1 + y2
620
+ frac = 0.5 * (y0 - y2) / den if den > 0 else 0.0
621
+ return (lo + k + frac + 0.5) / fs
622
+
623
+
624
+ def decode_lines(dm, h, t_hdr_end, t_search_end=None):
625
+ """Чтение строк тайла. Возвращает (rgb, stats, t_end).
626
+ t_search_end — где начинается следующая передача (или конец записи)."""
627
+ fs = dm.fs
628
+ mode, w, th_hdr, M = h["mode"], h["tile_w"], h["tile_h"], h["marker"]
629
+ stream = th_hdr == 0
630
+ pt = pt_seconds(h)
631
+ L = line_duration(h)
632
+ n_payload = payload_len(mode, w)
633
+ t_lines = t_hdr_end + T_POST_HDR
634
+ edge0_nom = t_lines + T_SYNC
635
+ t_search_end = dm.dur if t_search_end is None else min(t_search_end, dm.dur)
636
+
637
+ # 0. сигнал окончания: где закончились строки и сколько их было
638
+ t_eot_to = t_search_end if stream else min(t_search_end, t_lines + th_hdr * L * 1.05 + 1.5)
639
+ eots = find_eots(dm, t_lines, t_eot_to, h["image_id"])
640
+ eot = eots[0] if eots else None
641
+ if eot:
642
+ th = eot[0]["lines"] if stream else min(th_hdr, eot[0]["lines"])
643
+ t_limit = eot[1] + 0.002
644
+ elif stream:
645
+ th = int(max(1, min(4095, (t_search_end - t_lines) / L + 1)))
646
+ t_limit = t_search_end
647
+ else:
648
+ th = th_hdr
649
+ t_limit = min(t_search_end, t_lines + th * L * 1.03 + 0.1)
650
+ if th <= 0:
651
+ return np.zeros((0, w, 3), np.uint8), dict(lines_found=0, lines_pred=0, lines_total=0, marks_found=0,
652
+ marks_total=0, rate=1.0, eot=bool(eot), eot_lines=0,
653
+ cut_at=None, stream=stream, declared=th_hdr), \
654
+ (eot[2] if eot else t_lines)
655
+
656
+ # 1. кандидаты синхроимпульсов
657
+ i0, i1 = int(t_lines * fs) - int(0.003 * fs), min(len(dm.f4), int(t_limit * fs))
658
+ # 4-мс среднее: пиксели (>=1500) и короткие метки не опускают его ниже ~1400,
659
+ # а 5-мс синхроимпульс 1200 Гц — опускает, даже при дрожании частоты от кодека
660
+ mask = dm.f4[i0:i1] < 1350
661
+ cands = []
662
+ for a, b in runs(mask):
663
+ if (b - a) / fs < 0.0005:
664
+ continue
665
+ te = (i0 + b) / fs
666
+ edge = dm.step_edge(te - 0.003, te + 0.003, F_SYNC, F_BLACK, 0.004, 0.0009)
667
+ if edge is None:
668
+ continue
669
+ v = read_bits(dm, edge + T_PORCH, N_LBITS, T_LBIT)
670
+ bits = [int(x > (F_BLACK + F_WHITE) / 2) for x in v]
671
+ num = bits_to_int(bits[:12]) if sum(bits[:12]) % 2 == bits[12] else None
672
+ cands.append((edge, num))
673
+
674
+ # 2. грубая оценка периода строк (перебор наклона ±1%, медиана сдвига)
675
+ good = [(n, e) for e, n in cands if n is not None and n < th]
676
+ b_fit = L
677
+ if len(good) >= 2:
678
+ n_arr = np.array([g[0] for g in good], float)
679
+ e_arr = np.array([g[1] for g in good])
680
+ best = None
681
+ for b_try in L * np.linspace(0.99, 1.01, 81):
682
+ off = e_arr - b_try * n_arr
683
+ score = np.sum(np.abs(off - np.median(off)) < 0.01)
684
+ if best is None or score > best[0]:
685
+ best = (score, b_try)
686
+ b_fit = best[1]
687
+ off = e_arr - b_fit * n_arr
688
+ inl = np.abs(off - np.median(off)) < 0.01
689
+ if inl.sum() >= 2 and np.ptp(n_arr[inl]) > 0:
690
+ b_fit = float(np.polyfit(n_arr[inl], e_arr[inl], 1)[0])
691
+ rate = float(np.clip(b_fit / L, 0.95, 1.05))
692
+
693
+ # 3. привязка по согласованности последовательности: номер строки принимается,
694
+ # если у соседнего (по времени) синхроимпульса номер отличается ровно на
695
+ # round(dt / период). Скачки времени (мс) на это не влияют, ошибочные номера отсеиваются.
696
+ edges = [None] * th
697
+ seq = sorted((e, n) for e, n in cands if n is not None and n < th)
698
+ for i, (e, n) in enumerate(seq):
699
+ votes = 0
700
+ for j in (i - 2, i - 1, i + 1, i + 2):
701
+ if 0 <= j < len(seq):
702
+ ej, nj = seq[j]
703
+ if nj - n == int(round((ej - e) / b_fit)) and nj != n:
704
+ votes += 1
705
+ if votes >= 1 and edges[n] is None:
706
+ edges[n] = e
707
+ acc = np.array([k for k in range(th) if edges[k] is not None])
708
+
709
+ def predict(k):
710
+ if not len(acc):
711
+ return edge0_nom + L * k
712
+ j = np.searchsorted(acc, k)
713
+ lo_ = acc[j - 1] if j > 0 else None
714
+ hi_ = acc[j] if j < len(acc) else None
715
+ olo = edges[lo_] - b_fit * lo_ if lo_ is not None else None
716
+ ohi = edges[hi_] - b_fit * hi_ if hi_ is not None else None
717
+ o = olo if ohi is None else ohi if olo is None else olo + (ohi - olo) * (k - lo_) / (hi_ - lo_)
718
+ return b_fit * k + o
719
+
720
+ # синхро без валидного номера — по предсказанному времени
721
+ for e, n in cands:
722
+ if n is None or n >= th:
723
+ k = int(round((e - predict(0)) / b_fit))
724
+ for kk in (k - 1, k, k + 1):
725
+ if 0 <= kk < th and edges[kk] is None and abs(e - predict(kk)) < 0.003:
726
+ edges[kk] = e
727
+ break
728
+ found = sum(e is not None for e in edges)
729
+ acc = np.array([k for k in range(th) if edges[k] is not None])
730
+ last_seen = int(acc.max()) if len(acc) else -1
731
+ # без сигнала окончания строки после последней найденной считаем непереданными
732
+ cut_at = None
733
+ if not eot:
734
+ if stream:
735
+ th = max(1, last_seen + 1)
736
+ edges = edges[:th]
737
+ elif last_seen < th - 3:
738
+ cut_at = last_seen + 1
739
+ n_valid = th if cut_at is None else cut_at
740
+ # строки без синхро, но с найденными соседями (±2) — читаем по предсказанию
741
+ predicted = 0
742
+ for k in range(n_valid):
743
+ if edges[k] is None and len(acc) and np.min(np.abs(acc - k)) <= 2:
744
+ edges[k] = predict(k)
745
+ predicted += 1
746
+ for k in range(n_valid, th):
747
+ edges[k] = None
748
+ a_fit = predict(0)
749
+
750
+ # 4. чтение строк
751
+ vals = np.zeros((th, n_payload))
752
+ ok_lines = np.zeros(th, bool)
753
+ marks_found = marks_total = 0
754
+ for r in range(th):
755
+ e = edges[r]
756
+ if e is None:
757
+ continue
758
+ ok_lines[r] = True
759
+ s = e + (T_PORCH + N_LBITS * T_LBIT + T_GUARD) * rate
760
+ idx = 0
761
+ while idx < n_payload:
762
+ n = min(M, n_payload - idx) if M else n_payload
763
+ seg_pt = pt * rate
764
+ resync = None
765
+ last = idx + n >= n_payload
766
+ if not last:
767
+ m_nom = s + n * seg_pt + T_GUARD * rate
768
+ marks_total += 1
769
+ center = find_marker(dm, m_nom, rate)
770
+ jump = None
771
+ if center is None:
772
+ center = find_marker(dm, m_nom, rate, wide=True)
773
+ jump = center
774
+ if center is not None:
775
+ m_start = center - 0.5 * T_MARK * rate
776
+ d = (m_start - T_GUARD * rate - s) / n
777
+ if jump is None and abs(d / seg_pt - 1) < 0.1:
778
+ # мелкие отклонения (< 0.1 мс) — погрешность оценки, не трогаем
779
+ if abs(m_start - m_nom) > 0.0001:
780
+ seg_pt = d
781
+ marks_found += 1
782
+ elif jump is not None:
783
+ marks_found += 1
784
+ resync = m_start # скачок времени: этот сегмент номинально, следующий — от метки
785
+ a_ = s + np.arange(n) * seg_pt
786
+ f = dm.mean(a_ + 0.1 * seg_pt, a_ + 0.9 * seg_pt)
787
+ vals[r, idx:idx + n] = (f - F_BLACK) / (F_WHITE - F_BLACK) * 255
788
+ if resync is not None:
789
+ s = resync + (T_MARK + T_GUARD) * rate
790
+ else:
791
+ s = s + n * seg_pt + (0 if last else (T_MARK + 2 * T_GUARD) * rate)
792
+ idx += n
793
+ vals = np.clip(vals, 0, 255)
794
+
795
+ # 5. потерянные строки — копия ближайшей найденной (кроме непереданного хвоста)
796
+ if found and ok_lines.sum() < n_valid:
797
+ good_idx = np.where(ok_lines)[0]
798
+ for r in np.where(~ok_lines[:n_valid])[0]:
799
+ j = good_idx[np.argmin(np.abs(good_idx - r))]
800
+ vals[r] = vals[j]
801
+
802
+ # 6. сборка цвета
803
+ if mode == 0:
804
+ y = vals[:, :w]
805
+ rgb = np.repeat(np.clip(y, 0, 255).round().astype(np.uint8)[..., None], 3, -1)
806
+ elif mode == 2:
807
+ rgb = np.clip(np.stack([vals[:, :w], vals[:, w:2 * w], vals[:, 2 * w:]], -1), 0, 255).round().astype(np.uint8)
808
+ else:
809
+ y = vals[:, :w]
810
+ c = vals[:, w:]
811
+ cr_rows, cb_rows = c[0::2], c[1::2]
812
+ crok, cbok = ok_lines[0::2], ok_lines[1::2]
813
+ npairs = (th + 1) // 2
814
+
815
+ def pick(rows, okm, k):
816
+ if k < len(rows) and okm[k]:
817
+ return rows[k]
818
+ oks = np.where(okm)[0]
819
+ return rows[oks[np.argmin(np.abs(oks - k))]] if len(oks) else np.full(rows.shape[1], 128.0)
820
+
821
+ cr = np.array([pick(cr_rows, crok, k) for k in range(npairs)])
822
+ cb = np.array([pick(cb_rows, cbok, k) for k in range(npairs)]) if len(cb_rows) else np.full_like(cr, 128.0)
823
+ cr_full = np.repeat(np.repeat(cr, 2, 0)[:th], 2, 1)[:, :w]
824
+ cb_full = np.repeat(np.repeat(cb, 2, 0)[:th], 2, 1)[:, :w]
825
+ rgb = ycc_to_rgb(y, cb_full, cr_full)
826
+ if n_valid < th:
827
+ rgb[n_valid:] = 40 # непереданный хвост — тёмно-серый
828
+
829
+ stats = dict(lines_found=found, lines_pred=predicted, lines_total=th, marks_found=marks_found,
830
+ marks_total=marks_total, rate=rate, eot=bool(eot), eot_lines=eot[0]["lines"] if eot else None,
831
+ cut_at=cut_at, stream=stream, declared=th_hdr)
832
+ if eot:
833
+ t_end = eot[2]
834
+ else:
835
+ last = max((k for k in range(th) if edges[k] is not None), default=None)
836
+ t_end = (edges[last] if last is not None else a_fit) + L
837
+ return rgb, stats, t_end
838
+
839
+
840
+ def load_audio(path):
841
+ """WAV — встроенными средствами; OGG/Opus (голосовые Telegram), FLAC, MP3 и др. —
842
+ через soundfile, а если его нет или он не справился — через ffmpeg."""
843
+ import os
844
+ if not os.path.isfile(path):
845
+ raise ManulXError(f"File not found: {path}")
846
+ if path.lower().endswith(".wav"):
847
+ try:
848
+ return read_wav(path)
849
+ except Exception:
850
+ pass
851
+ try:
852
+ import soundfile as sf
853
+ x, rate = sf.read(path, dtype="float64", always_2d=True)
854
+ return x.mean(1), rate
855
+ except Exception:
856
+ pass
857
+ import shutil, subprocess, tempfile
858
+ ff = shutil.which("ffmpeg")
859
+ if not ff:
860
+ raise ManulXError("Cannot read the file. This format requires the soundfile package or ffmpeg in PATH.")
861
+ fd, tmp = tempfile.mkstemp(suffix=".wav")
862
+ os.close(fd)
863
+ try:
864
+ r = subprocess.run([ff, "-y", "-loglevel", "error", "-i", path, "-ac", "1", "-ar", "48000", tmp],
865
+ capture_output=True, creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
866
+ if r.returncode != 0:
867
+ raise ManulXError(f"Cannot read the file: {path}")
868
+ return read_wav(tmp)
869
+ finally:
870
+ try:
871
+ os.remove(tmp)
872
+ except OSError:
873
+ pass
874
+
875
+
876
+ def tile_status(st):
877
+ """Человекочитаемое состояние тайла по статистике decode_lines."""
878
+ if st["eot"]:
879
+ if st["stream"]:
880
+ return f"complete: stream, {st['lines_total']} lines, end-of-transmission received"
881
+ if st["eot_lines"] is not None and st["eot_lines"] < st["declared"]:
882
+ return f"complete: stopped early at {st['eot_lines']} of {st['declared']} lines (end-of-transmission received)"
883
+ return "complete: end-of-transmission received"
884
+ if st["cut_at"] is not None:
885
+ return f"INTERRUPTED at line {st['cut_at']} of {st['lines_total']}: no end-of-transmission"
886
+ if st["stream"]:
887
+ return f"stream without end-of-transmission: {st['lines_total']} lines received, the end may be lost"
888
+ return "all lines present, but end-of-transmission not detected"
889
+
890
+
891
+ def decode_samples(x, rate, log=print, progress=None):
892
+ """Звук -> список изображений:
893
+ [{'image': PIL.Image, 'id', 'w', 'h', 'tiles', 'call', 'complete', 'notes'}]."""
894
+ if len(x) < rate * 0.5:
895
+ raise ManulXError("Recording is too short.")
896
+ dm = Demod(np.asarray(x, dtype=np.float64), rate)
897
+ images = {}
898
+ nxt = find_headers(dm, 0.0)
899
+ while nxt[0] is not None:
900
+ h, t_hdr = nxt
901
+ t0 = t_hdr - N_HCOPIES * T_HCOPY + T_HSEP
902
+ nxt = find_headers(dm, t_hdr + 0.05)
903
+ # начало следующей передачи (лидер ~0.62 с до её первого заголовка)
904
+ t_next = (nxt[1] - N_HCOPIES * T_HCOPY - 2 * T_LEADER - T_BREAK - 0.05) if nxt[0] is not None else dm.dur
905
+ rgb, st, t_end = decode_lines(dm, h, t_hdr, t_next)
906
+ key = (h["image_id"], h["full_w"], h["full_h"])
907
+ if key not in images:
908
+ images[key] = dict(canvas=np.full((max(h["full_h"], 1), h["full_w"], 3), 40, np.uint8),
909
+ call=decode_call(h["call"]), tiles=0, complete=True, notes=[], grow=h["full_h"] == 0)
910
+ im = images[key]
911
+ y0, x0 = h["tile_y"], h["tile_x"]
912
+ if im["grow"] and y0 + rgb.shape[0] > im["canvas"].shape[0]:
913
+ cv = np.full((y0 + rgb.shape[0], im["canvas"].shape[1], 3), 40, np.uint8)
914
+ cv[:im["canvas"].shape[0]] = im["canvas"]
915
+ im["canvas"] = cv
916
+ cv = im["canvas"]
917
+ hh, ww = min(rgb.shape[0], cv.shape[0] - y0), min(rgb.shape[1], cv.shape[1] - x0)
918
+ if hh > 0 and ww > 0:
919
+ cv[y0:y0 + hh, x0:x0 + ww] = rgb[:hh, :ww]
920
+ im["tiles"] += 1
921
+ status = tile_status(st)
922
+ if not st["eot"]:
923
+ im["complete"] = False
924
+ im["notes"].append(f"tile @({x0},{y0}): {status}")
925
+ hdr_h = "stream" if h["tile_h"] == 0 else h["tile_h"]
926
+ full_h = "?" if h["full_h"] == 0 else h["full_h"]
927
+ log(f"[{t0:7.2f} s] tile {h['tile_w']}x{hdr_h} @ ({x0},{y0}) of {h['full_w']}x{full_h}, "
928
+ f"{MODE_NAMES[h['mode']]}, {pt_seconds(h) * 1e6:.0f} us, callsign '{decode_call(h['call'])}': "
929
+ f"lines {st['lines_found']}/{st['lines_total']} (+{st['lines_pred']} interpolated), "
930
+ f"markers {st['marks_found']}/{st['marks_total']}, time scale {st['rate']:.5f}")
931
+ log(f" {status}")
932
+ if progress:
933
+ progress(min(1.0, t_end / dm.dur))
934
+ if progress:
935
+ progress(1.0)
936
+ if not images:
937
+ raise ManulXError("No ManulX transmissions found.")
938
+ return [dict(image=Image.fromarray(im["canvas"]), id=k[0], w=im["canvas"].shape[1], h=im["canvas"].shape[0],
939
+ tiles=im["tiles"], call=im["call"], complete=im["complete"], notes=im["notes"])
940
+ for k, im in images.items()]
941
+
942
+
943
+ def eot_watch(x, rate):
944
+ """Для автостопа записи: анализирует хвост записи. Возвращает
945
+ (t_конца_последнего_EOT или None, есть_ли_после_него_новый_лидер)."""
946
+ if len(x) < rate * 0.5:
947
+ return None, False
948
+ dm = Demod(np.asarray(x, dtype=np.float64), rate)
949
+ eots = find_eots(dm, 0.0, dm.dur)
950
+ if not eots:
951
+ return None, False
952
+ t_end = eots[-1][2]
953
+ i = int((t_end + T_TAIL + 0.01) * dm.fs)
954
+ after = np.abs(dm.f10[i:] - F_LEADER) < 80
955
+ leader = any((b - a) / dm.fs >= 0.15 for a, b in runs(after))
956
+ return t_end, leader
@@ -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).
@@ -0,0 +1,9 @@
1
+ manulx/__init__.py,sha256=Uj6ggb1Z9nYvkzR_wprUl4xvNf-SA9koiCEbG3Kw3Rc,418
2
+ manulx/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
3
+ manulx/cli.py,sha256=ttmebQr40erXQw_6ewLa0sBYCDQT0TEGDATbWcJ8kM4,3746
4
+ manulx/core.py,sha256=z9t3Od4VpxPBgyCPhFLWcESaPnaMQxFn9HND0YRJs98,40020
5
+ manulx-1.1.0.dist-info/METADATA,sha256=ZLoBoDE0LSd5ZbgHesti61LhiVKWaJF284Q6uTDN13k,5971
6
+ manulx-1.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ manulx-1.1.0.dist-info/entry_points.txt,sha256=MUj1uVL94Qql3GNsSg0DUhaSS2UMt42zH6FKXLv1C3s,43
8
+ manulx-1.1.0.dist-info/licenses/LICENSE,sha256=gvc6K9C3R993Qa8WvOpQnppSkjV6dPKp-mKU7nnDREw,1065
9
+ manulx-1.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ manulx = manulx.cli:main
@@ -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.