rasterwave 0.6.0

High-performance streaming SSTV, radiofax and RTTY encoders/decoders
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
# Rasterwave.rs

High-performance streaming SSTV and radiofax codecs for Rust, plus a streaming
RTTY (ITA2 FSK) modem.

Rasterwave turns raster images into phase-continuous audio and turns a live
audio stream back into image rows. The same state machines power streaming and
one-shot APIs, so a WAV file, a sound-card callback, and a future Node.js worker
all observe the same protocol behavior.

![Rasterwave SSTV and radiofax codec preview](docs/preview.jpg)

The crate is library-first: it does not open audio devices, key a transmitter,
spawn threads, or depend on an async runtime.

## Highlights

- Streaming SSTV encoder that fills caller-owned PCM buffers without building
  a complete WAV in memory.
- Streaming SSTV decoder with automatic VIS detection, sync-timing candidates,
  frequency-offset tracking, bounded acquisition history, and immediate row
  events.
- Optional immediate decoding starts any caller-selected SSTV mode or fixed
  radiofax profile with the first PCM sample. Later SSTV sync pulses still
  correct timing and frequency, while missing headers or weak signals do not
  block row output.
- Dedicated continuous-paper decoders print fallback snow immediately, detect
  protocol boundaries in parallel, and keep emitting rows after a trusted
  SSTV image or APT-delimited fax page completes.
- VIS candidates are checked against subsequent sync timing before an image is
  started. Ambiguous no-VIS timing reports candidates instead of inventing an
  exact mode.
- Provisional and revised rows for formats such as Robot 36, where chroma spans
  adjacent radio lines.
- WMO-style radiofax framing with IOC 288/576, configurable LPM, APT
  selection, phasing, confirmed stop pattern, and black tail.
- Parameterized FM and AM radiofax subcarriers. Clean PCM encode/decode loops
  cover both; over-air and third-party interoperability are separate checks.
- `f32` and `i16` streaming decode inputs plus one-shot convenience functions.
- No mutable global codec state and no `unsafe` code. Independent sessions are
  `Send + Sync`; mutation requires `&mut self` and therefore remains ordered.
- Objective image comparison helpers (MSE, PSNR, block SSIM) and Criterion
  throughput benchmarks.

## Status

Rasterwave is an early `0.5` API intended for integration and interoperability
work. The encoder and decoder share one immutable mode catalog.

The primary built-in profiles currently include:

- Robot BW 8/12/24/36, Robot Color 24/36/72
- Martin M1/M2/M3/M4
- Scottie S1/S2/S3/S4/DX
- PD50/90/120/160/180/240/290
- Pasokon P3/P5/P7
- Wraase SC2-180

Compatibility profiles with conflicting or incomplete historical definitions
are marked by `ModeStatus::Compatibility`: Robot Color 12 and Wraase
SC2-30/60/120.

The public `ModeStatus::Canonical` name means Rasterwave's preferred,
source-backed profile rather than formal standardization or interoperability
certification. See the per-family provenance matrix before relying on an exact
wire timing.

Legacy SSTV FAX480 is deliberately not advertised yet. Its original framing is
APT plus phasing without VIS; treating later VIS code 85 as an ordinary SSTV
header is not interoperable. Meteorological radiofax is implemented separately
under `rasterwave::fax`.

## Install

Add the published crate with Cargo:

```bash
cargo add rasterwave
```

Or declare the dependency directly:

```toml
[dependencies]
rasterwave = "0.5"
```

The minimum supported Rust version is 1.85.

## Streaming SSTV Encode

```rust
use rasterwave::{EncodeOptions, Rgb, RgbImage, SstvEncoder, SstvMode};

fn encode(mut write_audio: impl FnMut(&[f32])) -> rasterwave::Result<()> {
    let mode = SstvMode::Robot36;
    let spec = mode.spec();
    let image = RgbImage::filled(spec.width, spec.height, Rgb::new(32, 128, 224));
    let mut encoder = SstvEncoder::new(
        image,
        mode,
        48_000,
        EncodeOptions::default(),
    )?;

    let mut pcm = [0.0_f32; 1024];
    while !encoder.is_finished() {
        let written = encoder.read_samples(&mut pcm);
        write_audio(&pcm[..written]);
    }
    Ok(())
}
```

Segment deadlines accumulate on one continuous sample timeline. Rounding error
is bounded to one sample over a complete transmission, including at 44.1 kHz.

### Optional transmission envelope

`SstvEncoder::new()` always keeps the interoperable 910 ms VIS header enabled
by default and ends at the last raster sample. Applications that key a radio can
opt into an enhanced calibration preamble, FSK or CW station identification,
and a final keyed-transmitter guard without assembling PCM in another thread:

```rust
use rasterwave::{
    EncodeOptions, Rgb, RgbImage, SstvEncoder, SstvMode, SstvStationId,
    SstvTransmissionEnvelope,
};

let mode = SstvMode::Robot36;
let spec = mode.spec();
let image = RgbImage::filled(spec.width, spec.height, Rgb::new(32, 128, 224));
let mut encoder = SstvEncoder::new_with_envelope(
    image,
    mode,
    48_000,
    EncodeOptions::default(),
    SstvTransmissionEnvelope {
        enhanced_preamble: true,
        station_id: SstvStationId::Fsk { callsign: "N0CALL".into() },
        post_image_gap_seconds: 0.5,
        end_guard_seconds: 0.3,
    },
)?;

let raster_end = encoder.progress().raster_end_sample;
```

The enhanced preamble is the eight 100 ms calibration tones used by QSSTV,
followed by the ordinary VIS header. FSK ID uses the interoperable DL3YAP
6-bit callsign framing. CW accepts 5-60 WPM and 400-2300 Hz. Callsigns are
uppercase `A-Z`, `0-9`, or `/`, up to 16 characters. `raster_start_sample` and
`raster_end_sample` are exact positions in the emitted stream, so monitoring
applications can decode the image without treating the station ID as pixels.

## Streaming SSTV Decode

The hot API borrows row pixels for the duration of a synchronous callback. It
does not allocate an owned event for every line.

```rust
use rasterwave::{
    DecodeEventRef, DecodeSink, DecoderConfig, SstvDecoder,
};

struct Display;

impl DecodeSink for Display {
    fn on_event(&mut self, event: DecodeEventRef<'_>) {
        match event {
            DecodeEventRef::ModeCandidate { candidates, confidence } => {
                println!("candidate modes: {candidates:?} ({confidence:.2})");
            }
            DecodeEventRef::LineReady {
                line_index,
                revision,
                pixels,
                ..
            } => {
                // Copy or render this row before returning.
                println!("row {line_index}, revision {revision}: {} px", pixels.len());
            }
            _ => {}
        }
    }
}

fn decode(audio_chunks: &[&[f32]]) -> rasterwave::Result<()> {
    let mut decoder = SstvDecoder::new(48_000, DecoderConfig::default())?;
    let mut display = Display;
    for chunk in audio_chunks {
        decoder.push_f32(chunk, &mut display)?;
    }

    // Empty input is a no-op. EOF is explicit:
    decoder.finish(&mut display)?;
    Ok(())
}
```

Call `mark_discontinuity()` when PCM was dropped. Concatenating discontinuous
audio silently would corrupt line timing.

For queues and language bindings, use `DecodeEventRef::to_owned()` or
`SstvDecoder::process_into()`. `encode_sstv()` and `decode_sstv()` provide
one-shot helpers built on the same streaming engines.

## Continuous Receiver Paper

`SstvPaperDecoder` and `FaxPaperDecoder` are presentation-neutral orchestration
layers over the framed protocol decoders. They separate three concerns:
continuous fallback raster output, protocol acquisition, and trusted capture
ranges. Automatic SSTV starts as Robot 36 Color; automatic fax starts as
IOC576/120 LPM/FM and evaluates FM and AM acquisition paths in parallel.

```rust
use rasterwave::{SstvPaperConfig, SstvPaperDecoder, SstvPaperEventRef};

fn receive(chunks: &[&[f32]]) -> rasterwave::Result<()> {
    let mut decoder = SstvPaperDecoder::new(48_000, SstvPaperConfig::default())?;
    for chunk in chunks {
        decoder.push_f32(chunk, &mut |event: SstvPaperEventRef<'_>| {
            match event {
                SstvPaperEventRef::Boundary { kind, line_index, .. } => {
                    println!("divider {kind:?} before row {line_index}");
                }
                SstvPaperEventRef::LineReady { line_index, pixels, .. } => {
                    println!("paper row {line_index}: {} px", pixels.len());
                }
                _ => {}
            }
        })?;
    }
    Ok(())
}
```

Paper row indices never reset at nominal image height. A trusted VIS/sync or
APT/phasing boundary opens a capture range; completion closes only that range
while fallback paper output continues. Signal loss and discontinuity emit a
divider but never masquerade as successful protocol completion.

Fallback fax paper rows use the `NominalPaper` basis so an indefinitely growing
receiver never silently changes its coordinate clock. Once trusted phasing is
available, the capture segment is cut directly with the recovered line period
and its rows use the `Calibrated` basis. Image-only reception may publish sparse
`ImageContent` calibration points only after a stable margin persists across
multiple windows; otherwise it stays nominal. Apply nominal-paper points with
`fax::correct_fax_paper` when rendering or saving a paper range. Never apply
them again to `Calibrated` rows.

## Radiofax

```rust
use rasterwave::GrayImage;
use rasterwave::fax::{FaxEncoder, FaxEncodeOptions, FaxIoc, FaxLpm, FaxSpec};

fn fax_encoder() -> rasterwave::Result<FaxEncoder> {
    let spec = FaxSpec::standard(FaxIoc::Ioc576, FaxLpm::LPM_120);
    let page = GrayImage::new(
        spec.width(),
        800,
        vec![255; spec.width() as usize * 800],
    )?;
    FaxEncoder::new(page, spec, 48_000, FaxEncodeOptions::default())
}
```

IOC is a geometric invariant, not a pixel width. Rasterwave's square-sampling
policy uses full image-line widths of 905/1810 for IOC 288/576. The 5% white
interval is part of the phasing pattern, not a reserved interval inserted into
every image line. The encoder therefore accepts and emits the full IOC width.
Radiofax height remains open until APT stop, EOF, signal loss, or a
caller-supplied bound.

WMO-listed rates are 60, 90, 120, and 240 LPM; those are also the decoder's
automatic inference set. 180 LPM is available as an explicit interoperability
extension and must be configured on receive. Default acquisition detects IOC
from APT and timing from phasing. Phasing-only input is supported when IOC is
preconfigured. Image-only continuous paper starts immediately at nominal timing
and only adopts a conservative content-derived model when the evidence remains
stable; this heuristic is not a protocol lock. A
confirmed 450 Hz stop closes a page, while configured target-carrier
level/coherence loss closes it as partial without generating rows from silence
or broadband noise. An upstream squelch can disable the coherence threshold and
apply a stricter receiver-specific policy.

## RTTY

The `rtty` module is an audio FSK modem for interactive keyboard RTTY.
`RttyTones` are audio frequencies; the caller decides which tone is mark for
its sideband so the RF mark stays above the RF space.

```rust
use rasterwave::rtty::{RttyDecoder, RttyDecoderConfig, RttyDecodeEvent, RttyEncoder, RttyEncoderConfig};

let mut encoder = RttyEncoder::new(12_000, RttyEncoderConfig::default())?;
let mut decoder = RttyDecoder::new(12_000, RttyDecoderConfig::default())?;
encoder.push_text("CQ CQ DE N0CALL K")?; // more text may follow while transmitting
encoder.finish();
let mut pcm = vec![0.0; 1_024];
while !encoder.is_finished() {
    let n = encoder.read_samples(&mut pcm);
    decoder.push_f32(&pcm[..n], &mut |event| {
        if let RttyDecodeEvent::Character(c) = event {
            print!("{}", c.ch);
        }
    })?;
}
# Ok::<(), rasterwave::Error>(())
```

The encoder sends LTRS diddles while its buffer is empty and never stops on its
own; `retract_unsent` removes text that has not been committed yet and
`drain_rendered` reports committed characters with sample positions. The
decoder reports characters with a 0..1 confidence and periodic `RttySignal`
tuning data: `snr_db` in a 3 kHz bandwidth measured at the bit centres of
decoded characters (within about 1 dB of the true value from −12 to +40 dB on
white noise), fast per-tone `mark_db` / `space_db` levels, AFC offset, lock and
polarity. Digital silence, such as a receiver muted while transmitting, freezes
the level estimates so noise afterwards is not mistaken for a signal.

`RttyChannelScanner` is a signal browser: it searches a whole audio passband
(default 300 to 2900 Hz) for tone pairs one shift apart whose energy alternates
between the two tones, which separates RTTY from pairs of carriers and from
voice. Every 500 ms it reports the tracked channels (stable id, centre, shift,
score, SNR, lock and polarity), and each channel runs its own `RttyDecoder`
primed with the last two seconds of audio, so a preview of the decoded text
arrives as `Text` events.

```rust
use rasterwave::rtty::{RttyChannelScanner, RttyScanEvent, RttyScannerConfig};

let mut scanner = RttyChannelScanner::new(12_000, RttyScannerConfig {
    shifts_hz: vec![170.0, 425.0],
    ..RttyScannerConfig::default()
})?;
# let pcm = vec![0.0_f32; 12_000];
scanner.push_f32(&pcm, &mut |event| match event {
    RttyScanEvent::Channels { channels, .. } => {
        for channel in channels {
            println!("#{} {:.0} Hz score {:.2}", channel.id, channel.center_hz, channel.score);
        }
    }
    RttyScanEvent::Text { channel_id, characters, .. } => {
        let text: String = characters.iter().map(|c| c.ch).collect();
        println!("#{channel_id}: {text}");
    }
    _ => {}
})?;
# Ok::<(), rasterwave::Error>(())
```

Scanning with eight active channels costs about eight decoders: on one Apple
M1 Max core the scanner runs at about 2.9 million samples per second at 12 kHz
(240 times real time; a single decoder runs at about 26 million), and spectral
detection alone at about 23 million samples per second.

## Threading Contract

- Each encoder or decoder owns all oscillator, detector, ring-buffer, plane,
  and scratch state.
- A session can move to any worker thread (`Send`).
- Independent sessions can run concurrently.
- One stream remains a single ordered writer because processing takes
  `&mut self`.
- The core intentionally has no Tokio, Promise, thread pool, mutex, or Node-API
  dependency. A binding should serialize work per handle and parallelize across
  handles.

See [Architecture](docs/ARCHITECTURE.md) for the intended Node.js boundary.
See [Building Rasterwave](docs/BUILDING.md) for toolchain and platform details.
The complete, Cargo-compiled SSTV example is
[examples/streaming.rs](examples/streaming.rs).

## Build And Verify

```bash
cargo build --release
cargo test --all-targets
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo bench --bench codec
cargo doc --no-deps
```

Focused integration tests cover chunk-boundary invariance, VIS offsets to
`+/-250 Hz`, no-VIS mode detection, ambiguity handling, line-before-EOF
delivery, radiofax APT/phasing and phasing-only acquisition, clean FM/AM
self-loops, stop/signal-loss behavior, and multi-threaded independent sessions.

## Performance Snapshot

Apple M1 Max, macOS 26.5.2, Rust 1.87, release profile with thin LTO:

| Benchmark | Time | Throughput |
| --- | ---: | ---: |
| Robot 36 encode at 12 kHz | 4.03 ms | 110 M samples/s |
| Martin M1 encode at 12 kHz | 6.70 ms | 206 M samples/s |
| PD290 encode at 12 kHz | 25.0 ms | 139 M samples/s |
| Robot 8 decode at 12 kHz | 8.07 ms | 13.1 M samples/s |
| IOC576/120 LPM fax encode | 262 us | 183 M samples/s |

These numbers are development snapshots, not cross-platform guarantees.

## Specifications And Provenance

SSTV has no single formal standards body. Rasterwave records which source wins
when historical tables disagree. Meteorological radiofax framing is based on
WMO-No. 386 and CCIR Recommendation 343-1; the documentation separates that
source basis from the narrower behavior exercised by the crate's tests.

Read [Protocol Sources And Decisions](docs/PROTOCOL-SOURCES.md) and
[Third-Party Notices](THIRD_PARTY_NOTICES.md) before adding a mode.

## License

MIT. See [LICENSE](LICENSE).