use std::collections::VecDeque;
use std::f64::consts::{PI, TAU};
use super::ita2::{self, Encoded, Shift};
use super::profile::{CharacterSet, RttyProfile, RttyTones, validate_sample_rate};
use crate::{Error, Result};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum RttyIdle {
#[default]
Diddle,
Mark,
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct RttyEncoderConfig {
pub profile: RttyProfile,
pub tones: RttyTones,
pub character_set: CharacterSet,
pub amplitude: f32,
pub preamble_mark_seconds: f64,
pub preamble_ltrs: u8,
pub idle: RttyIdle,
pub tail_ltrs: u8,
pub tail_mark_seconds: f64,
pub transition_seconds: f64,
pub envelope_seconds: f64,
pub expand_newline: bool,
}
impl Default for RttyEncoderConfig {
fn default() -> Self {
Self {
profile: RttyProfile::default(),
tones: RttyTones::default(),
character_set: CharacterSet::default(),
amplitude: 0.7,
preamble_mark_seconds: 0.2,
preamble_ltrs: 2,
idle: RttyIdle::Diddle,
tail_ltrs: 1,
tail_mark_seconds: 0.1,
transition_seconds: 0.002,
envelope_seconds: 0.005,
expand_newline: true,
}
}
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct RttyPushReport {
pub accepted: usize,
pub first_seq: Option<u64>,
pub rejected: Vec<char>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RttyCharRendered {
pub seq: u64,
pub ch: char,
pub start_sample: u64,
pub end_sample: u64,
}
const MAX_PENDING: usize = 4_096;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Stage {
Start,
Running,
Tail,
Done,
}
#[derive(Clone, Copy, Debug)]
struct BitSpan {
mark: bool,
end_sample: u64,
}
#[derive(Clone, Copy, Debug)]
struct Pending {
seq: u64,
ch: char,
encoded: Encoded,
}
#[derive(Debug)]
pub struct RttyEncoder {
config: RttyEncoderConfig,
sample_rate: u32,
samples_per_bit: f64,
transition_samples: f64,
envelope_samples: f64,
stage: Stage,
finish_requested: bool,
pending: VecDeque<Pending>,
bits: VecDeque<BitSpan>,
scheduled_until: f64,
shift: Option<Shift>,
last_code: Option<u8>,
next_seq: u64,
rendered: Vec<RttyCharRendered>,
position: u64,
end_sample: Option<u64>,
phase: f64,
target_hz: f64,
from_hz: f64,
transition_pos: f64,
}
impl RttyEncoder {
pub fn new(sample_rate: u32, config: RttyEncoderConfig) -> Result<Self> {
validate_sample_rate(sample_rate)?;
config.profile.validate()?;
config.tones.validate(sample_rate)?;
config.profile.check_tones(&config.tones)?;
if !config.amplitude.is_finite() || !(0.0..=1.0).contains(&config.amplitude) {
return Err(Error::InvalidConfiguration(
"RTTY amplitude must be between 0 and 1",
));
}
for seconds in [
config.preamble_mark_seconds,
config.tail_mark_seconds,
config.transition_seconds,
config.envelope_seconds,
] {
if !seconds.is_finite() || !(0.0..=10.0).contains(&seconds) {
return Err(Error::InvalidConfiguration(
"RTTY encoder durations must be between 0 and 10 seconds",
));
}
}
let rate = f64::from(sample_rate);
let samples_per_bit = rate / config.profile.baud;
let transition_samples = (config.transition_seconds * rate).min(samples_per_bit / 2.0);
Ok(Self {
config,
sample_rate,
samples_per_bit,
transition_samples,
envelope_samples: config.envelope_seconds * rate,
stage: Stage::Start,
finish_requested: false,
pending: VecDeque::new(),
bits: VecDeque::new(),
scheduled_until: 0.0,
shift: None,
last_code: None,
next_seq: 0,
rendered: Vec::new(),
position: 0,
end_sample: None,
phase: 0.0,
target_hz: config.tones.mark_hz,
from_hz: config.tones.mark_hz,
transition_pos: f64::INFINITY,
})
}
#[must_use]
pub fn sample_rate(&self) -> u32 {
self.sample_rate
}
pub fn push_text(&mut self, text: &str) -> Result<RttyPushReport> {
if matches!(self.stage, Stage::Tail | Stage::Done) || self.end_sample.is_some() {
return Err(Error::EncoderFinished);
}
let mut report = RttyPushReport::default();
for ch in text.chars() {
if self.pending.len() >= MAX_PENDING {
report.rejected.push(ch);
continue;
}
match ita2::encode(ch, self.config.character_set) {
Some(encoded) => {
let seq = self.next_seq;
self.next_seq += 1;
report.first_seq.get_or_insert(seq);
report.accepted += 1;
self.pending.push_back(Pending {
seq,
ch: ch.to_ascii_uppercase(),
encoded,
});
}
None => report.rejected.push(ch),
}
}
Ok(report)
}
#[must_use]
pub fn pending_len(&self) -> usize {
self.pending.len()
}
#[must_use]
pub fn pending_text(&self) -> String {
self.pending.iter().map(|pending| pending.ch).collect()
}
pub fn retract_unsent(&mut self, count: usize) -> usize {
let removed = count.min(self.pending.len());
self.pending.truncate(self.pending.len() - removed);
removed
}
pub fn clear_unsent(&mut self) -> usize {
let removed = self.pending.len();
self.pending.clear();
removed
}
pub fn finish(&mut self) {
self.finish_requested = true;
}
pub fn abort(&mut self) {
self.pending.clear();
self.finish_requested = true;
if self.stage == Stage::Done {
return;
}
let ramp = self.envelope_samples.ceil() as u64;
let end = self.position + ramp;
if self.end_sample.is_some_and(|scheduled| scheduled <= end) {
return;
}
self.end_sample = Some(end);
if ramp == 0 {
self.stage = Stage::Done;
}
}
#[must_use]
pub fn is_finished(&self) -> bool {
self.stage == Stage::Done
}
#[must_use]
pub fn is_finishing(&self) -> bool {
self.finish_requested
}
#[must_use]
pub fn samples_rendered(&self) -> u64 {
self.position
}
pub fn drain_rendered(&mut self, out: &mut Vec<RttyCharRendered>) {
out.append(&mut self.rendered);
}
pub fn read_samples(&mut self, output: &mut [f32]) -> usize {
let rate = f64::from(self.sample_rate);
let mut written = 0;
while written < output.len() {
if self.stage == Stage::Done {
break;
}
if self.end_sample.is_some_and(|end| self.position >= end) {
self.stage = Stage::Done;
break;
}
let Some(bit) = self.current_bit() else {
self.stage = Stage::Done;
break;
};
let tone = if bit.mark {
self.config.tones.mark_hz
} else {
self.config.tones.space_hz
};
if tone != self.target_hz {
self.from_hz = self.instantaneous_hz();
self.target_hz = tone;
self.transition_pos = 0.0;
}
let mut span_end = bit.end_sample;
if let Some(end) = self.end_sample {
span_end = span_end.min(end);
}
let available = (span_end - self.position) as usize;
let count = available.min(output.len() - written);
let amplitude = f64::from(self.config.amplitude);
for sample in &mut output[written..written + count] {
let hz = self.instantaneous_hz();
self.transition_pos += 1.0;
*sample = (self.phase.sin() * amplitude * self.envelope_at(self.position)) as f32;
self.phase += TAU * hz / rate;
if self.phase >= TAU {
self.phase -= TAU;
}
self.position += 1;
}
written += count;
if self.position >= bit.end_sample {
self.bits.pop_front();
}
}
written
}
fn instantaneous_hz(&self) -> f64 {
if self.transition_pos >= self.transition_samples {
return self.target_hz;
}
let progress = 0.5 * (1.0 - (PI * self.transition_pos / self.transition_samples).cos());
self.from_hz + (self.target_hz - self.from_hz) * progress
}
fn envelope_at(&self, position: u64) -> f64 {
if self.envelope_samples <= 0.0 {
return 1.0;
}
let attack = (position as f64 / self.envelope_samples).min(1.0);
let release = self.end_sample.map_or(1.0, |end| {
(end.saturating_sub(position) as f64 / self.envelope_samples).min(1.0)
});
let level = attack.min(release);
0.5 * (1.0 - (PI * level).cos())
}
fn current_bit(&mut self) -> Option<BitSpan> {
while self
.bits
.front()
.is_some_and(|bit| bit.end_sample <= self.position)
{
self.bits.pop_front();
}
if self.bits.is_empty() {
self.schedule();
}
self.bits.front().copied()
}
fn schedule(&mut self) {
if self.end_sample.is_some() {
self.push_bits(true, 1.0);
return;
}
match self.stage {
Stage::Start => {
let preamble_bits = self.config.preamble_mark_seconds * self.config.profile.baud;
if preamble_bits > 0.0 {
self.push_bits(true, preamble_bits);
}
for _ in 0..self.config.preamble_ltrs {
self.push_code(ita2::LTRS);
self.shift = Some(Shift::Letters);
}
self.stage = Stage::Running;
if self.bits.is_empty() {
self.schedule();
}
}
Stage::Running => {
if let Some(next) = self.pending.pop_front() {
self.schedule_character(next);
} else if self.finish_requested {
for _ in 0..self.config.tail_ltrs {
self.push_code(ita2::LTRS);
}
let tail_bits = self.config.tail_mark_seconds * self.config.profile.baud;
if tail_bits > 0.0 {
self.push_bits(true, tail_bits);
}
let release = self.envelope_samples.ceil() as u64;
if release > 0 {
self.push_bits(true, release as f64 / self.samples_per_bit);
}
self.end_sample = Some(self.scheduled_until.round() as u64);
self.stage = Stage::Tail;
} else {
match self.config.idle {
RttyIdle::Diddle if self.shift == Some(Shift::Figures) => {
self.push_code(ita2::FIGS);
}
RttyIdle::Diddle => {
self.push_code(ita2::LTRS);
self.shift = Some(Shift::Letters);
}
RttyIdle::Mark => self.push_bits(true, 1.0),
}
}
}
Stage::Tail | Stage::Done => {}
}
}
fn schedule_character(&mut self, next: Pending) {
let Encoded { code, shift } = next.encoded;
if let Some(required) = shift.filter(|&required| self.shift != Some(required)) {
self.push_code(match required {
Shift::Letters => ita2::LTRS,
Shift::Figures => ita2::FIGS,
});
self.shift = Some(required);
}
let start_sample = self.scheduled_until.round() as u64;
if next.ch == '\n' && self.config.expand_newline && self.last_code != Some(ita2::CR) {
self.push_code(ita2::CR);
}
self.push_code(code);
if code == ita2::SPACE && self.shift == Some(Shift::Figures) {
self.shift = None;
}
self.rendered.push(RttyCharRendered {
seq: next.seq,
ch: next.ch,
start_sample,
end_sample: self.scheduled_until.round() as u64,
});
}
fn push_code(&mut self, code: u8) {
self.last_code = Some(code);
self.push_bits(false, 1.0);
for bit in 0..5 {
self.push_bits((code >> bit) & 1 == 1, 1.0);
}
self.push_bits(true, self.config.profile.stop_bits.bits());
}
fn push_bits(&mut self, mark: bool, bits: f64) {
self.scheduled_until += bits * self.samples_per_bit;
let end_sample = self.scheduled_until.round() as u64;
if let Some(last) = self.bits.back_mut().filter(|last| last.mark == mark) {
last.end_sample = end_sample;
return;
}
self.bits.push_back(BitSpan { mark, end_sample });
}
}
#[cfg(test)]
mod tests {
use super::*;
fn read_all(encoder: &mut RttyEncoder, chunk: usize) -> Vec<f32> {
let mut out = Vec::new();
let mut buffer = vec![0.0; chunk];
while !encoder.is_finished() {
let n = encoder.read_samples(&mut buffer);
out.extend_from_slice(&buffer[..n]);
assert!(out.len() < 10_000_000, "encoder did not finish");
}
out
}
#[test]
fn finished_transmission_has_expected_length() {
let config = RttyEncoderConfig {
preamble_mark_seconds: 0.0,
preamble_ltrs: 0,
tail_ltrs: 0,
tail_mark_seconds: 0.0,
envelope_seconds: 0.0,
..RttyEncoderConfig::default()
};
let mut encoder = RttyEncoder::new(12_000, config).unwrap();
encoder.push_text("RY").unwrap();
encoder.finish();
let pcm = read_all(&mut encoder, 333);
let expected = 3.0 * 7.5 * 12_000.0 / 45.45;
assert!((pcm.len() as f64 - expected).abs() <= 1.0, "{}", pcm.len());
let mut rendered = Vec::new();
encoder.drain_rendered(&mut rendered);
assert_eq!(rendered.len(), 2);
assert_eq!(rendered[0].ch, 'R');
assert_eq!(rendered[1].start_sample, rendered[0].end_sample);
}
#[test]
fn idle_never_finishes_and_retract_removes_uncommitted_text() {
let mut encoder = RttyEncoder::new(12_000, RttyEncoderConfig::default()).unwrap();
let mut buffer = vec![0.0; 1024];
assert_eq!(encoder.read_samples(&mut buffer), 1024);
let report = encoder.push_text("CQ test%").unwrap();
assert_eq!(report.accepted, 7);
assert_eq!(report.rejected, vec!['%']);
assert_eq!(encoder.retract_unsent(3), 3);
assert_eq!(encoder.pending_len(), 4);
for _ in 0..200 {
assert_eq!(encoder.read_samples(&mut buffer), 1024);
}
let mut rendered = Vec::new();
encoder.drain_rendered(&mut rendered);
let text: String = rendered.iter().map(|r| r.ch).collect();
assert_eq!(text, "CQ T");
assert!(!encoder.is_finished());
}
#[test]
fn abort_ramps_down_quickly() {
let mut encoder = RttyEncoder::new(48_000, RttyEncoderConfig::default()).unwrap();
encoder.push_text("RYRYRYRYRY").unwrap();
let mut buffer = vec![0.0; 4800];
encoder.read_samples(&mut buffer);
encoder.abort();
let rest = read_all(&mut encoder, 4800);
assert!(rest.len() <= 241, "{}", rest.len());
assert!(encoder.is_finished());
assert!(encoder.push_text("X").is_err());
}
#[test]
fn abort_during_the_finish_tail_ramps_down_quickly() {
let config = RttyEncoderConfig {
tail_mark_seconds: 5.0,
..RttyEncoderConfig::default()
};
let mut encoder = RttyEncoder::new(12_000, config).unwrap();
encoder.push_text("CQ").unwrap();
encoder.finish();
let mut buffer = vec![0.0; 1200];
for _ in 0..20 {
assert_eq!(encoder.read_samples(&mut buffer), 1200);
}
assert!(encoder.pending_len() == 0 && !encoder.is_finished());
encoder.abort();
let rest = read_all(&mut encoder, 1200);
assert!(rest.len() <= 61, "{}", rest.len());
assert!(encoder.is_finished());
let mut encoder = RttyEncoder::new(12_000, RttyEncoderConfig::default()).unwrap();
encoder.push_text("CQ").unwrap();
encoder.abort();
let mut short = vec![0.0; 30];
assert_eq!(encoder.read_samples(&mut short), 30);
encoder.abort();
assert_eq!(read_all(&mut encoder, 1200).len(), 30);
}
#[test]
fn output_is_chunk_size_invariant() {
let make = |chunk| {
let mut encoder = RttyEncoder::new(12_000, RttyEncoderConfig::default()).unwrap();
encoder.push_text("CQ CQ DE BG5DRB 599 73\n").unwrap();
encoder.finish();
read_all(&mut encoder, chunk)
};
let reference = make(4096);
for chunk in [1, 7, 127, 1000] {
assert_eq!(make(chunk), reference);
}
}
}