///|
/// All frame positions in this report are absolute positions in the input
/// WAVs. A positive lag means the observed waveform occurred later.
pub(all) struct ResponseDifference {
status : String
reference_start : Int32
requested_observed_start : Int32
observed_start : Int32
observed_lag_frames : Int32
lag_trials : Int32
signed_correlation : Double?
reference_to_observed_gain : Double?
observed_energy_delta_db : Double?
raw_error_ratio : Double?
adjusted_error_ratio : Double?
}
///|
pub(all) struct ResponseComparison {
sample_rate : Int32
reference_frames : Int32
observed_frames : Int32
compared_frames : Int32
channels : Array[ResponseDifference]
}
///|
priv struct ComparisonWindow {
reference_start : Int32
observed_start : Int32
minimum_lag : Int32
maximum_lag : Int32
}
///|
priv struct WindowEnergy {
cross : Double
x_power : Double
y_power : Double
x_peak : Double
y_peak : Double
raw_residual : Double
}
///|
fn comparison_peak(
signal : Array[Double],
start : Int32,
length : Int32,
) -> Double {
let mut peak = 0.0
for i in start..<(start + length) {
peak = peak.max(signal[i].abs())
}
peak
}
///|
fn comparison_energy(
x : Array[Double],
y : Array[Double],
x_origin : Int32,
y_origin : Int32,
frames : Int32,
x_peak : Double,
) -> WindowEnergy {
let y_peak = comparison_peak(y, y_origin, frames)
let scale_x = if x_peak > 0.0 { x_peak } else { 1.0 }
let scale_y = if y_peak > 0.0 { y_peak } else { 1.0 }
let peak = x_peak.max(y_peak)
let joint_scale = if peak > 0.0 { peak } else { 1.0 }
let joint_x = x_peak / joint_scale
let joint_y = y_peak / joint_scale
let mut cross = 0.0
let mut x_power = 0.0
let mut y_power = 0.0
let mut raw_residual = 0.0
for i in 0.. ResponseDifference {
let x_peak = comparison_peak(x, window.reference_start, frames)
let mut offset = 0
let mut best = comparison_energy(
x,
y,
window.reference_start,
window.observed_start,
frames,
x_peak,
)
let mut score = if best.y_power > 0.0 {
best.cross.abs() / best.y_power.sqrt()
} else {
-1.0
}
let mut lag_trials = 1
if x_peak > 0.0 {
for lag in window.minimum_lag..<(window.maximum_lag + 1) {
if lag == 0 {
continue
}
lag_trials += 1
let candidate = comparison_energy(
x,
y,
window.reference_start,
window.observed_start + lag,
frames,
x_peak,
)
if candidate.y_power == 0.0 {
continue
}
let candidate_score = candidate.cross.abs() / candidate.y_power.sqrt()
let tolerance = 1.0e-12 * candidate_score.max(score).max(1.0)
let tie = (candidate_score - score).abs() <= tolerance
if candidate_score > score + tolerance ||
(
tie &&
(
lag.abs() < offset.abs() ||
(lag.abs() == offset.abs() && lag < offset)
)
) {
score = candidate_score
best = candidate
offset = lag
}
}
}
let valid = best.x_power > 0.0 && best.y_power > 0.0
let relative_energy_db = if valid {
Some(
2.0 * decay_energy_db(best.y_peak, best.x_peak) +
decay_energy_db(best.y_power, best.x_power),
)
} else {
None
}
let rho = if valid {
(best.cross / (best.x_power * best.y_power).sqrt()).max(-1.0).min(1.0)
} else {
0.0
}
let ratio = if valid {
best.cross / best.x_power * (best.y_peak / best.x_peak)
} else {
0.0
}
{
status: if valid {
"compared"
} else if best.x_power == 0.0 && best.y_power == 0.0 {
"both_silent"
} else if best.x_power == 0.0 {
"reference_silent"
} else {
"observed_silent"
},
reference_start: window.reference_start,
requested_observed_start: window.observed_start,
observed_start: window.observed_start + offset,
observed_lag_frames: offset,
lag_trials,
signed_correlation: if valid {
Some(rho)
} else {
None
},
reference_to_observed_gain: if valid &&
ratio >= -1.0e300 &&
ratio <= 1.0e300 {
Some(ratio)
} else {
None
},
observed_energy_delta_db: relative_energy_db,
raw_error_ratio: if best.y_power > 0.0 && best.raw_residual >= 0.0 {
Some(best.raw_residual)
} else {
None
},
adjusted_error_ratio: if valid {
Some((1.0 - rho * rho).max(0.0).sqrt())
} else {
None
},
}
}
///|
fn checked_starts(starts : Array[Int32], count : Int32, frames : Int32) -> Bool {
starts.is_empty() ||
(
starts.length() == count &&
starts.all(frame => frame >= 0 && frame < frames)
)
}
///|
/// Compare corresponding microphones over a common fixed-length window.
/// No alignment is applied by default. A nonzero lag search is opt-in and
/// requires an explicit window to keep every trial's length identical.
pub fn compare_responses(
reference : Array[Array[Double]],
observed : Array[Array[Double]],
sample_rate : Int32,
frames~ : Int32? = None,
reference_starts~ : Array[Int32] = [],
observed_starts~ : Array[Int32] = [],
lag_radius~ : Int32 = 0,
) -> Result[ResponseComparison, String] {
let reference_frames = match
checked_audio_frames(reference, sample_rate, 262144, 2000000, 1.0e20) {
Err(reason) => return Err("reference: " + reason)
Ok(value) => value
}
let observed_frames = match
checked_audio_frames(observed, sample_rate, 262144, 2000000, 1.0e20) {
Err(reason) => return Err("observed: " + reason)
Ok(value) => value
}
let count = reference.length()
if count != observed.length() ||
!checked_starts(reference_starts, count, reference_frames) ||
!checked_starts(observed_starts, count, observed_frames) {
return Err("comparison requires matching channels and valid starts")
}
if lag_radius < 0 || lag_radius > 2048 || (lag_radius > 0 && frames is None) {
return Err(
"lag radius must be 0..2048 with an explicit window for alignment",
)
}
let start_ref = if reference_starts.is_empty() {
Array::make(count, 0)
} else {
reference_starts
}
let start_obs = if observed_starts.is_empty() {
Array::make(count, 0)
} else {
observed_starts
}
let mut available = reference_frames.min(observed_frames)
for i in 0.. available {
return Err("comparison window exceeds at least one recording")
}
let windows : Array[ComparisonWindow] = []
let mut work = 0L
for i in 0.. 4000000L {
return Err("comparison budget exceeded: 4000000 sample pairs")
}
windows.push({
reference_start: start_ref[i],
observed_start: start_obs[i],
minimum_lag,
maximum_lag,
})
}
Ok({
sample_rate,
reference_frames,
observed_frames,
compared_frames,
channels: Array::makei(count, fn(i) {
compare_channel(reference[i], observed[i], compared_frames, windows[i])
}),
})
}