///|
/// Deterministic excitation waveforms for offline recording and experiments.
/// Frequencies are in Hz and every duration is measured in samples.
pub(all) enum Excitation {
  Impulse
  Sine(Double)
  LogSweep(Double, Double)
  WhiteNoise(UInt32)
}

///|
pub(all) struct ProbeSpec {
  sample_rate : Int32
  active_frames : Int32
  lead_frames : Int32
  tail_frames : Int32
  fade_frames : Int32
  amplitude : Double
  excitation : Excitation
}

///|
fn valid_audio_rate(sample_rate : Int32) -> Bool {
  sample_rate >= 8000 && sample_rate <= 96000
}

///|
fn valid_tone_frequency(frequency : Double, sample_rate : Int32) -> Bool {
  frequency >= 10.0 && frequency <= 0.45 * sample_rate.to_double()
}

///|
fn probe_envelope(index : Int32, active : Int32, fade : Int32) -> Double {
  if fade == 0 {
    return 1.0
  }
  let from_edge = index.min(active - 1 - index)
  if from_edge >= fade {
    1.0
  } else {
    0.5 * (1.0 - @math.cos(PI * from_edge.to_double() / fade.to_double()))
  }
}

///|
fn next_noise_state(seed : UInt32) -> UInt32 {
  let shifted = seed ^ (seed << 13)
  let shifted = shifted ^ (shifted >> 17)
  shifted ^ (shifted << 5)
}

///|
/// The active sequence starts after lead_frames. Sine/sweep phase starts at
/// zero; the sweep frequency reaches its endpoint one sample beyond the
/// active interval. A raised cosine taper applies only to the active edges.
pub fn generate_probe(spec : ProbeSpec) -> Result[Audio, String] {
  let rate = spec.sample_rate
  let active = spec.active_frames
  let lead = spec.lead_frames
  let tail = spec.tail_frames
  let fade = spec.fade_frames
  let full = active.to_int64() + lead.to_int64() + tail.to_int64()
  if !valid_audio_rate(rate) ||
    active < 1 ||
    lead < 0 ||
    tail < 0 ||
    full > 262144L ||
    fade < 0 ||
    fade > (active - 1) / 2 ||
    !(spec.amplitude > 0.0 && spec.amplitude <= 1.0) {
    return Err("invalid probe rate, frame budget, taper or amplitude")
  }
  let mut noise = 0U
  let mut sweep_ratio = 0.0
  let mut sweep_scale = 0.0
  match spec.excitation {
    Impulse =>
      if active != 1 {
        return Err("an impulse has exactly one active frame")
      }
    Sine(hz) =>
      if !valid_tone_frequency(hz, rate) || active < 4 {
        return Err("invalid sine frequency or active duration")
      }
    LogSweep(start, end) => {
      if !valid_tone_frequency(start, rate) ||
        !valid_tone_frequency(end, rate) ||
        end < 1.01 * start ||
        active < 32 {
        return Err("sweep frequencies must increase within 10 Hz..0.45*rate")
      }
      sweep_ratio = @math.ln(end / start)
      sweep_scale = 2.0 *
        PI *
        start *
        active.to_double() /
        (rate.to_double() * sweep_ratio)
    }
    WhiteNoise(seed) => {
      if seed == 0U {
        return Err("white-noise seed must be nonzero")
      }
      noise = seed
    }
  }
  let samples = Array::make(full.to_int(), 0.0)
  let inverse_rate = 1.0 / rate.to_double()
  for i in 0.. 1.0
      Sine(hz) => @math.sin(2.0 * PI * hz * i.to_double() * inverse_rate)
      LogSweep(_, _) => {
        let progress = i.to_double() / active.to_double()
        @math.sin(sweep_scale * (@math.exp(sweep_ratio * progress) - 1.0))
      }
      WhiteNoise(_) => {
        noise = next_noise_state(noise)
        // The 24-bit fraction is exactly representable on each target.
        (noise >> 8).to_double() / 8388608.0 - 1.0
      }
    }
    samples[lead + i] = spec.amplitude * probe_envelope(i, active, fade) * value
  }
  Ok({ samples: [samples], sample_rate: rate, latency_samples: 0, })
}

///|
/// One-second reference sweep for the local workbench. Its upper frequency is
/// constrained by the selected sample rate so a new scene doesn't need a file.
pub fn default_probe(sample_rate : Int32) -> Result[Audio, String] {
  if !valid_audio_rate(sample_rate) {
    return Err("probe sample rate must be 8000..96000")
  }
  let high_hz = (0.4 * sample_rate.to_double()).min(7200.0)
  generate_probe({
    sample_rate,
    active_frames: sample_rate,
    lead_frames: 0,
    tail_frames: 0,
    fade_frames: sample_rate / 100,
    amplitude: 0.7,
    excitation: LogSweep(60.0, high_hz),
  })
}