Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
//! Audio latency correction module for Cap.
//!
//! This module provides comprehensive audio latency detection and correction to maintain
//! proper audio-video synchronization. It handles measuring hardware buffer delays and
//! compensating for transmission latency in wireless audio devices.
//!
//! # Quick Start
//!
//! ```rust,no_run
//! use cap_audio::{LatencyCorrector, LatencyCorrectionConfig, default_output_latency_hint};
//!
//! // Get initial latency hint from hardware
//! let hint = default_output_latency_hint(48000, 512);
//!
//! // Create corrector with default settings
//! let mut corrector = LatencyCorrector::new(hint, LatencyCorrectionConfig::default());
//!
//! // Apply initial output latency to audio playhead
//! let base_playhead = 5.0; // Current playback position in seconds
//! let compensated_playhead = base_playhead + corrector.initial_output_latency_secs();
//! // audio_renderer.set_playhead(compensated_playhead);
//!
//! // In audio callback, update latency estimate
//! // let current_latency = corrector.update_from_callback(&callback_info);
//! ```
//!
//! # Transport Types
//!
//! The system automatically detects and handles different audio transports:
//! - **Wired**: Standard audio interfaces (20-50ms typical)
//! - **Bluetooth**: Wireless audio with encoding delays (120ms+ minimum)
//! - **AirPlay**: Network streaming with substantial buffering (1.8s+ minimum)
//!
//! # Platform Support
//!
//! - **macOS**: Full Core Audio integration with precise device inspection
//! - **Other platforms**: Buffer-based estimation with conservative defaults
use std::time::{Duration, Instant};
use cpal::OutputCallbackInfo;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OutputTransportKind {
Wired,
Wireless,
Airplay,
ContinuityWireless,
Unknown,
}
impl OutputTransportKind {
pub const fn is_wireless(self) -> bool {
matches!(
self,
Self::Wireless | Self::Airplay | Self::ContinuityWireless
)
}
}
#[derive(Debug, Clone, Copy)]
pub struct OutputLatencyHint {
pub latency_secs: f64,
pub transport: OutputTransportKind,
}
impl OutputLatencyHint {
pub fn new(latency_secs: f64, transport: OutputTransportKind) -> Self {
Self {
latency_secs,
transport,
}
}
pub fn is_probably_wireless(&self) -> bool {
self.transport.is_wireless()
}
}
/// Configuration for dynamic latency correction during playback
#[derive(Debug, Clone, Copy)]
pub struct LatencyCorrectionConfig {
/// Minimum change in latency (seconds) before applying correction
pub min_apply_delta_secs: f64,
/// Minimum number of latency updates before enabling dynamic correction
pub min_updates_for_dynamic: u64,
/// Maximum latency change per second to prevent artifacts
pub max_change_per_sec: f64,
/// Initial freeze duration to let the system stabilize
pub initial_freeze_duration_secs: f64,
/// Threshold for logging latency changes (milliseconds)
pub log_change_threshold_ms: i32,
/// Safety multiplier for initial latency compensation
pub initial_safety_multiplier: f64,
}
impl Default for LatencyCorrectionConfig {
fn default() -> Self {
Self {
min_apply_delta_secs: 0.005,
min_updates_for_dynamic: 4,
max_change_per_sec: 0.15,
initial_freeze_duration_secs: 0.35,
log_change_threshold_ms: 5,
initial_safety_multiplier: 2.0,
}
}
}
/// Manages latency correction for audio playback
#[derive(Debug)]
pub struct LatencyCorrector {
estimator: OutputLatencyEstimator,
config: LatencyCorrectionConfig,
last_latency_used: Option<f64>,
last_logged_latency_ms: Option<i32>,
last_latency_update_at: Instant,
latency_freeze_until: Instant,
}
impl LatencyCorrector {
pub fn new(hint: Option<OutputLatencyHint>, config: LatencyCorrectionConfig) -> Self {
let estimator = match hint {
Some(h) => OutputLatencyEstimator::from_hint(h),
None => OutputLatencyEstimator::new(),
};
let now = Instant::now();
Self {
estimator,
config,
last_latency_used: None,
last_logged_latency_ms: None,
last_latency_update_at: now,
latency_freeze_until: now
+ Duration::from_secs_f64(config.initial_freeze_duration_secs),
}
}
/// Get the initial latency compensation value (with safety multiplier applied)
pub fn initial_compensation_secs(&self) -> f64 {
self.estimator.current_secs().unwrap_or_default() * self.config.initial_safety_multiplier
}
pub fn initial_output_latency_secs(&self) -> f64 {
self.estimator.current_secs().unwrap_or_default()
}
/// Update latency estimate from audio callback and return corrected latency
pub fn update_from_callback(&mut self, info: &OutputCallbackInfo) -> f64 {
let previous_update_count = self.estimator.update_count();
let estimated_latency_secs = self
.estimator
.observe_callback(info)
.or(self.last_latency_used)
.unwrap_or_default();
let now = Instant::now();
let latency_secs = if let Some(previous) = self.last_latency_used {
if now < self.latency_freeze_until {
previous
} else if self.estimator.update_count() >= self.config.min_updates_for_dynamic {
let dt_secs = now
.checked_duration_since(self.last_latency_update_at)
.map(|d| d.as_secs_f64())
.unwrap_or(0.0);
let max_delta = (self.config.max_change_per_sec * dt_secs)
.max(self.config.min_apply_delta_secs);
let delta = estimated_latency_secs - previous;
if delta.abs() <= max_delta {
self.last_latency_update_at = now;
estimated_latency_secs
} else {
self.last_latency_update_at = now;
previous + delta.signum() * max_delta
}
} else if (estimated_latency_secs - previous).abs() < self.config.min_apply_delta_secs {
previous
} else {
self.last_latency_update_at = now;
estimated_latency_secs
}
} else {
self.last_latency_update_at = now;
estimated_latency_secs
};
self.last_latency_used = Some(latency_secs);
// Log significant latency changes
if self.estimator.update_count() != previous_update_count {
let latency_ms = (latency_secs * 1_000.0).round() as i32;
let should_log = match self.last_logged_latency_ms {
Some(prev) => (prev - latency_ms).abs() >= self.config.log_change_threshold_ms,
None => latency_ms >= 0,
};
if should_log {
tracing::info!(
"Estimated audio output latency: {:.1} ms",
latency_secs * 1_000.0
);
self.last_logged_latency_ms = Some(latency_ms);
}
}
latency_secs
}
/// Get the current latency estimate without updating
pub fn current_latency_secs(&self) -> Option<f64> {
self.last_latency_used
}
/// Get the underlying latency estimator for advanced use cases
pub fn estimator(&self) -> &OutputLatencyEstimator {
&self.estimator
}
/// Get the underlying latency estimator mutably for advanced use cases
pub fn estimator_mut(&mut self) -> &mut OutputLatencyEstimator {
&mut self.estimator
}
}
const MAX_LATENCY_SECS: f64 = 3.0;
const MIN_VALID_LATENCY_SECS: f64 = 0.000_1;
const INCREASE_TAU_SECS: f64 = 0.25;
const DECREASE_TAU_SECS: f64 = 1.0;
const MAX_RISE_PER_SEC: f64 = 0.75;
const WARMUP_GUARD_SAMPLES: u32 = 3;
const WARMUP_SPIKE_RATIO: f64 = 50.0;
#[cfg(not(target_os = "macos"))]
const FALLBACK_WIRED_LATENCY_SECS: f64 = 0.03;
#[cfg(target_os = "macos")]
const WIRELESS_FALLBACK_LATENCY_SECS: f64 = 0.20;
const WIRELESS_MIN_LATENCY_SECS: f64 = 0.12;
#[cfg(target_os = "macos")]
const AIRPLAY_MIN_LATENCY_SECS: f64 = 1.8;
/// Tracks the measured output latency reported by the active audio device.
///
/// The estimator smooths reported values so that sudden increases are applied quickly while
/// decreases are adopted more conservatively. This keeps the playhead ahead of the hardware
/// buffer without reacting to transient spikes that would otherwise cause unnecessary seeks.
#[derive(Debug, Clone)]
pub struct OutputLatencyEstimator {
smoothed_latency_secs: Option<f64>,
last_raw_latency_secs: Option<f64>,
update_count: u64,
bias_secs: f64,
last_update_at: Option<Instant>,
min_floor_secs: f64,
max_ceiling_secs: f64,
}
impl OutputLatencyEstimator {
pub fn new() -> Self {
Self::with_bias(0.0)
}
pub fn with_bias(bias_secs: f64) -> Self {
let bias_secs = bias_secs.clamp(0.0, MAX_LATENCY_SECS);
Self {
smoothed_latency_secs: if bias_secs > 0.0 {
Some(bias_secs)
} else {
None
},
last_raw_latency_secs: None,
update_count: 0,
bias_secs,
last_update_at: None,
min_floor_secs: 0.0,
max_ceiling_secs: MAX_LATENCY_SECS,
}
}
pub fn from_hint(hint: OutputLatencyHint) -> Self {
let mut estimator = Self::with_bias(0.0);
let (floor, ceiling) = transport_constraints(hint.transport);
estimator.set_floor_and_ceiling(floor, ceiling);
if hint.latency_secs > 0.0 {
let seeded = hint
.latency_secs
.max(estimator.min_floor_secs)
.min(estimator.max_ceiling_secs);
estimator.smoothed_latency_secs = Some(seeded);
estimator.last_update_at = Some(Instant::now());
}
estimator
}
pub fn set_bias_secs(&mut self, bias_secs: f64) {
self.bias_secs = bias_secs.clamp(0.0, MAX_LATENCY_SECS);
}
pub fn set_floor_and_ceiling(&mut self, min_floor_secs: f64, max_ceiling_secs: f64) {
self.min_floor_secs = min_floor_secs.clamp(0.0, MAX_LATENCY_SECS);
self.max_ceiling_secs = max_ceiling_secs
.max(self.min_floor_secs)
.min(MAX_LATENCY_SECS);
if let Some(current) = self.smoothed_latency_secs {
self.smoothed_latency_secs =
Some(current.max(self.min_floor_secs).min(self.max_ceiling_secs));
}
}
pub fn reset(&mut self) {
let bias = self.bias_secs;
let floor = self.min_floor_secs;
let ceiling = self.max_ceiling_secs;
*self = Self::with_bias(bias);
self.set_floor_and_ceiling(floor, ceiling);
}
/// Observes a callback invocation and updates the latency estimate when the backend reports a
/// playback timestamp.
pub fn observe_callback(&mut self, info: &OutputCallbackInfo) -> Option<f64> {
let timestamp = info.timestamp();
let latency = timestamp.playback.duration_since(×tamp.callback);
self.observe_latency(latency)
}
/// Observes a latency duration directly. Exposed for tests.
pub fn observe_latency(&mut self, latency: Option<Duration>) -> Option<f64> {
if let Some(duration) = latency {
let secs = duration.as_secs_f64();
if secs.is_finite() {
self.record_latency(secs);
}
}
self.smoothed_latency_secs
}
/// Returns the current smoothed latency estimate in seconds, if available.
pub fn current_secs(&self) -> Option<f64> {
self.smoothed_latency_secs
}
pub fn current_duration(&self) -> Option<Duration> {
self.smoothed_latency_secs
.map(|secs| Duration::from_secs_f64(secs.max(0.0)))
}
pub fn bias_secs(&self) -> f64 {
self.bias_secs
}
pub fn last_raw_secs(&self) -> Option<f64> {
self.last_raw_latency_secs
}
pub fn update_count(&self) -> u64 {
self.update_count
}
fn record_latency(&mut self, secs: f64) {
if secs < 0.0 {
return;
}
let clamped = secs.min(self.max_ceiling_secs);
if clamped < MIN_VALID_LATENCY_SECS {
return;
}
if let Some(prev_raw) = self.last_raw_latency_secs
&& self.update_count < WARMUP_GUARD_SAMPLES as u64
&& clamped > prev_raw * WARMUP_SPIKE_RATIO
{
self.last_raw_latency_secs = Some(clamped);
self.update_count = self.update_count.saturating_add(1);
return;
}
let now = Instant::now();
let dt_secs = self
.last_update_at
.map(|t| (now - t).as_secs_f64())
.unwrap_or(0.0);
self.last_update_at = Some(now);
self.last_raw_latency_secs = Some(clamped);
self.update_count = self.update_count.saturating_add(1);
let mut target_latency = clamped + self.bias_secs;
if target_latency < self.min_floor_secs {
target_latency = self.min_floor_secs;
}
if target_latency > self.max_ceiling_secs {
target_latency = self.max_ceiling_secs;
}
self.smoothed_latency_secs = Some(match self.smoothed_latency_secs {
Some(current) => {
let rising = target_latency > current;
let tau = if rising {
INCREASE_TAU_SECS
} else {
DECREASE_TAU_SECS
};
let alpha = time_based_alpha(dt_secs, tau);
let mut next = current + (target_latency - current) * alpha;
if rising && dt_secs > 0.0 {
let max_allowed = current + MAX_RISE_PER_SEC * dt_secs;
next = next.min(max_allowed);
}
next
}
None => target_latency,
});
}
}
impl Default for OutputLatencyEstimator {
fn default() -> Self {
Self::new()
}
}
pub fn default_output_latency_hint(
sample_rate: u32,
buffer_size_frames: u32,
) -> Option<OutputLatencyHint> {
if sample_rate == 0 {
return None;
}
#[cfg(target_os = "macos")]
{
macos::default_output_latency_hint(sample_rate, buffer_size_frames)
}
#[cfg(not(target_os = "macos"))]
{
let fallback = (buffer_size_frames as f64 / sample_rate as f64)
.clamp(FALLBACK_WIRED_LATENCY_SECS, MAX_LATENCY_SECS);
Some(OutputLatencyHint::new(
fallback,
OutputTransportKind::Unknown,
))
}
}
/// Whether the default output device is the built-in output, whose stream can
/// be stopped while idle and restarted within a callback period or two.
/// External, wireless, AirPlay and display outputs keep running because some
/// drop the start of audio or take seconds to wake after their stream stops.
pub fn default_output_supports_idle_pause() -> bool {
#[cfg(target_os = "macos")]
{
macos::default_output_supports_idle_pause()
}
#[cfg(not(target_os = "macos"))]
{
false
}
}
#[derive(Debug, Clone, Copy)]
pub struct InputLatencyInfo {
pub device_latency_secs: f64,
pub buffer_latency_secs: f64,
pub total_latency_secs: f64,
pub transport: OutputTransportKind,
}
impl InputLatencyInfo {
pub fn new(
device_latency_secs: f64,
buffer_latency_secs: f64,
transport: OutputTransportKind,
) -> Self {
Self {
device_latency_secs,
buffer_latency_secs,
total_latency_secs: device_latency_secs + buffer_latency_secs,
transport,
}
}
pub fn from_buffer_only(sample_rate: u32, buffer_size_frames: u32) -> Self {
let buffer_latency = if sample_rate > 0 {
buffer_size_frames as f64 / sample_rate as f64
} else {
0.0
};
Self::new(0.0, buffer_latency, OutputTransportKind::Unknown)
}
}
pub fn estimate_input_latency(
sample_rate: u32,
buffer_size_frames: u32,
device_name: Option<&str>,
) -> InputLatencyInfo {
if sample_rate == 0 {
return InputLatencyInfo::new(0.0, 0.0, OutputTransportKind::Unknown);
}
#[cfg(target_os = "macos")]
{
macos::estimate_input_latency(sample_rate, buffer_size_frames, device_name)
.unwrap_or_else(|| InputLatencyInfo::from_buffer_only(sample_rate, buffer_size_frames))
}
#[cfg(windows)]
{
windows::estimate_input_latency(sample_rate, buffer_size_frames, device_name)
}
#[cfg(not(any(target_os = "macos", windows)))]
{
let _ = device_name;
InputLatencyInfo::from_buffer_only(sample_rate, buffer_size_frames)
}
}
fn time_based_alpha(dt_secs: f64, tau_secs: f64) -> f64 {
if tau_secs <= 0.0 {
return 1.0;
}
if dt_secs <= 0.0 {
1.0
} else {
let alpha = 1.0 - (-dt_secs / tau_secs).exp();
alpha.clamp(0.0, 1.0)
}
}
fn transport_constraints(transport: OutputTransportKind) -> (f64, f64) {
#[cfg(target_os = "macos")]
{
match transport {
OutputTransportKind::Airplay => (AIRPLAY_MIN_LATENCY_SECS, MAX_LATENCY_SECS),
OutputTransportKind::Wireless | OutputTransportKind::ContinuityWireless => {
(WIRELESS_MIN_LATENCY_SECS, MAX_LATENCY_SECS)
}
_ => (0.0, MAX_LATENCY_SECS),
}
}
#[cfg(not(target_os = "macos"))]
{
match transport {
OutputTransportKind::Wireless | OutputTransportKind::ContinuityWireless => {
(WIRELESS_MIN_LATENCY_SECS, MAX_LATENCY_SECS)
}
_ => (0.0, MAX_LATENCY_SECS),
}
}
}
#[cfg(target_os = "macos")]
mod macos {
#[cfg(target_os = "macos")]
use super::AIRPLAY_MIN_LATENCY_SECS;
use super::{
InputLatencyInfo, MAX_LATENCY_SECS, OutputLatencyHint, OutputTransportKind,
WIRELESS_FALLBACK_LATENCY_SECS, WIRELESS_MIN_LATENCY_SECS, transport_constraints,
};
use cidre::{
core_audio::{
DeviceTransportType, PropElement, PropScope, PropSelector,
hardware::{Device, Stream, System},
},
os,
};
pub(super) fn default_output_latency_hint(
sample_rate: u32,
fallback_buffer_frames: u32,
) -> Option<OutputLatencyHint> {
let device = System::default_output_device().ok()?;
compute_latency_hint(&device, sample_rate, fallback_buffer_frames).ok()
}
pub(super) fn default_output_supports_idle_pause() -> bool {
System::default_output_device()
.ok()
.and_then(|device| device.transport_type().ok())
.is_some_and(|transport| transport == DeviceTransportType::BUILT_IN)
}
pub(super) fn estimate_input_latency(
sample_rate: u32,
buffer_size_frames: u32,
device_name: Option<&str>,
) -> Option<InputLatencyInfo> {
// Resolve the actual device being recorded from; the system-default
// input may be a different device with very different latency
// characteristics (e.g. a Bluetooth headset while recording from a
// wired interface).
let device =
input_device_by_name(device_name).or_else(|| System::default_input_device().ok())?;
compute_input_latency(&device, sample_rate, buffer_size_frames).ok()
}
fn input_device_by_name(device_name: Option<&str>) -> Option<Device> {
let target = device_name?;
System::devices().ok()?.into_iter().find(|device| {
has_input_streams(device) && device.name().is_ok_and(|name| name.to_string() == target)
})
}
fn has_input_streams(device: &Device) -> bool {
device.streams().is_ok_and(|streams| {
streams
.iter()
.any(|stream| is_input_stream(stream).unwrap_or(false))
})
}
fn compute_input_latency(
device: &Device,
sample_rate: u32,
fallback_buffer_frames: u32,
) -> os::Result<InputLatencyInfo> {
let transport = device
.transport_type()
.unwrap_or(DeviceTransportType::UNKNOWN);
let transport_kind = transport_kind(transport);
let device_latency_frames =
scoped_u32(device, PropSelector::DEVICE_LATENCY, PropScope::INPUT).unwrap_or(0);
let safety_offset_frames =
scoped_u32(device, PropSelector::DEVICE_SAFETY_OFFSET, PropScope::INPUT).unwrap_or(0);
let buffer_frames = device
.prop(&PropSelector::DEVICE_BUF_FRAME_SIZE.global_addr())
.unwrap_or(fallback_buffer_frames);
let stream_latency_frames = max_input_stream_latency(device).unwrap_or(0);
let device_sample_rate = device.nominal_sample_rate().unwrap_or(sample_rate as f64);
let effective_rate = if device_sample_rate > 0.0 {
device_sample_rate
} else {
sample_rate as f64
};
let device_latency_total_frames = device_latency_frames as u64
+ safety_offset_frames as u64
+ stream_latency_frames as u64;
let device_latency_secs = device_latency_total_frames as f64 / effective_rate;
let buffer_latency_secs = buffer_frames as f64 / effective_rate;
Ok(InputLatencyInfo::new(
device_latency_secs,
buffer_latency_secs,
transport_kind,
))
}
fn max_input_stream_latency(device: &Device) -> os::Result<u32> {
let streams = device.streams()?;
let mut max_latency = 0u32;
for stream in streams {
if is_input_stream(&stream)?
&& let Ok(latency) = stream.latency()
{
max_latency = max_latency.max(latency);
}
}
Ok(max_latency)
}
fn is_input_stream(stream: &Stream) -> os::Result<bool> {
stream.direction().map(|dir| dir == 1)
}
fn compute_latency_hint(
device: &Device,
sample_rate: u32,
fallback_buffer_frames: u32,
) -> os::Result<OutputLatencyHint> {
let transport = device
.transport_type()
.unwrap_or(DeviceTransportType::UNKNOWN);
let transport_kind = transport_kind(transport);
let device_latency_frames =
scoped_u32(device, PropSelector::DEVICE_LATENCY, PropScope::OUTPUT).unwrap_or(0);
let safety_offset_frames = scoped_u32(
device,
PropSelector::DEVICE_SAFETY_OFFSET,
PropScope::OUTPUT,
)
.unwrap_or(0);
let buffer_frames = device
.prop(&PropSelector::DEVICE_BUF_FRAME_SIZE.global_addr())
.unwrap_or(fallback_buffer_frames);
let stream_latency_frames = max_output_stream_latency(device).unwrap_or(0);
let device_sample_rate = device.nominal_sample_rate().unwrap_or(sample_rate as f64);
let effective_rate = if device_sample_rate > 0.0 {
device_sample_rate
} else {
sample_rate as f64
};
let total_frames = device_latency_frames as u64
+ safety_offset_frames as u64
+ buffer_frames as u64
+ stream_latency_frames as u64;
if total_frames == 0 {
let (floor, ceiling) = transport_constraints(transport_kind);
let base_latency = (buffer_frames as f64 / effective_rate).min(ceiling);
let fallback = if transport_kind.is_wireless() {
base_latency.max(WIRELESS_FALLBACK_LATENCY_SECS).max(floor)
} else {
base_latency.max(floor)
}
.min(MAX_LATENCY_SECS);
return Ok(OutputLatencyHint::new(fallback, transport_kind));
}
let mut latency_secs = total_frames as f64 / effective_rate;
match transport_kind {
OutputTransportKind::Airplay => {
latency_secs = latency_secs.max(AIRPLAY_MIN_LATENCY_SECS);
}
OutputTransportKind::Wireless | OutputTransportKind::ContinuityWireless => {
latency_secs = latency_secs.max(WIRELESS_MIN_LATENCY_SECS);
}
_ => {}
}
latency_secs = latency_secs.min(MAX_LATENCY_SECS);
Ok(OutputLatencyHint::new(latency_secs, transport_kind))
}
fn scoped_u32(device: &Device, selector: PropSelector, scope: PropScope) -> os::Result<u32> {
device.prop(&selector.addr(scope, PropElement::MAIN))
}
fn max_output_stream_latency(device: &Device) -> os::Result<u32> {
let streams = device.streams()?;
let mut max_latency = 0u32;
for stream in streams {
if is_output_stream(&stream)?
&& let Ok(latency) = stream.latency()
{
max_latency = max_latency.max(latency);
}
}
Ok(max_latency)
}
fn is_output_stream(stream: &Stream) -> os::Result<bool> {
stream.direction().map(|dir| dir == 0)
}
fn transport_kind(transport: DeviceTransportType) -> OutputTransportKind {
match transport {
DeviceTransportType::AIR_PLAY => OutputTransportKind::Airplay,
DeviceTransportType::BLUETOOTH | DeviceTransportType::BLUETOOTH_LE => {
OutputTransportKind::Wireless
}
DeviceTransportType::CONTINUITY_CAPTURE_WIRELESS => {
OutputTransportKind::ContinuityWireless
}
DeviceTransportType::UNKNOWN => OutputTransportKind::Unknown,
_ => OutputTransportKind::Wired,
}
}
}
#[cfg(windows)]
mod windows {
use super::{InputLatencyInfo, OutputTransportKind, WIRELESS_MIN_LATENCY_SECS};
use tracing::{debug, trace};
use windows::{
Win32::Devices::FunctionDiscovery::PKEY_Device_EnumeratorName,
Win32::Media::Audio::{
DEVICE_STATE, IMMDevice, IMMDeviceEnumerator, MMDeviceEnumerator, eCapture,
},
Win32::System::Com::{
CLSCTX_ALL, COINIT_MULTITHREADED, CoCreateInstance, CoInitializeEx, STGM_READ,
},
core::PCWSTR,
};
const BLUETOOTH_DEVICE_PATTERNS: &[&str] = &[
"airpod",
"bluetooth",
"bt ",
"wireless",
"bose",
"sony wh",
"sony wf",
"jabra",
"beats",
"galaxy buds",
"pixel buds",
"anker",
"jbl ",
"soundcore",
"tozo",
"raycon",
"skullcandy",
"sennheiser momentum",
"audio-technica ath-m50xbt",
"marshall",
"b&o",
"bang & olufsen",
"shokz",
"aftershokz",
];
fn is_likely_bluetooth_device(device_name: &str) -> bool {
let lower = device_name.to_lowercase();
BLUETOOTH_DEVICE_PATTERNS
.iter()
.any(|pattern| lower.contains(pattern))
}
fn detect_transport_via_mmdevice(device_name: &str) -> Option<OutputTransportKind> {
unsafe {
let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
let enumerator: IMMDeviceEnumerator =
CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL).ok()?;
let collection = enumerator
.EnumAudioEndpoints(eCapture, DEVICE_STATE(1))
.ok()?;
let count = collection.GetCount().ok()?;
for i in 0..count {
let device: IMMDevice = match collection.Item(i) {
Ok(d) => d,
Err(_) => continue,
};
let props = match device.OpenPropertyStore(STGM_READ) {
Ok(p) => p,
Err(_) => continue,
};
let friendly_name = get_device_friendly_name(&device);
let matches_name = friendly_name
.as_ref()
.map(|n| n.to_lowercase().contains(&device_name.to_lowercase()))
.unwrap_or(false);
if !matches_name {
continue;
}
if let Ok(bus_enum) = props.GetValue(&PKEY_Device_EnumeratorName) {
let bus_name = bus_enum.Anonymous.Anonymous.Anonymous.pwszVal;
if !bus_name.0.is_null() {
let bus_str = PCWSTR(bus_name.0).to_string().ok()?;
trace!(
device = ?friendly_name,
bus = %bus_str,
"Windows audio device bus enumerator"
);
let bus_lower = bus_str.to_lowercase();
if bus_lower.contains("bthenum") || bus_lower.contains("bluetooth") {
debug!(
device = ?friendly_name,
"Detected Bluetooth audio device via Windows API"
);
return Some(OutputTransportKind::Wireless);
}
}
}
return Some(OutputTransportKind::Wired);
}
None
}
}
fn get_device_friendly_name(device: &IMMDevice) -> Option<String> {
use windows::Win32::Devices::FunctionDiscovery::PKEY_Device_FriendlyName;
unsafe {
let props = device.OpenPropertyStore(STGM_READ).ok()?;
let name_val = props.GetValue(&PKEY_Device_FriendlyName).ok()?;
let name_ptr = name_val.Anonymous.Anonymous.Anonymous.pwszVal;
if name_ptr.0.is_null() {
return None;
}
PCWSTR(name_ptr.0).to_string().ok()
}
}
pub fn estimate_input_latency(
sample_rate: u32,
buffer_size_frames: u32,
device_name: Option<&str>,
) -> InputLatencyInfo {
if sample_rate == 0 {
return InputLatencyInfo::new(0.0, 0.0, OutputTransportKind::Unknown);
}
let buffer_latency_secs = buffer_size_frames as f64 / sample_rate as f64;
let transport_kind = device_name
.and_then(|name| {
if let Some(transport) = detect_transport_via_mmdevice(name) {
return Some(transport);
}
if is_likely_bluetooth_device(name) {
debug!(
device = %name,
"Detected likely Bluetooth device via name pattern matching"
);
return Some(OutputTransportKind::Wireless);
}
None
})
.unwrap_or(OutputTransportKind::Unknown);
let device_latency_secs = match transport_kind {
OutputTransportKind::Wireless => {
debug!(
device = ?device_name,
latency_ms = WIRELESS_MIN_LATENCY_SECS * 1000.0,
"Using wireless latency for audio device"
);
WIRELESS_MIN_LATENCY_SECS
}
_ => 0.01,
};
InputLatencyInfo::new(device_latency_secs, buffer_latency_secs, transport_kind)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn detects_airpods() {
assert!(is_likely_bluetooth_device("AirPods Pro"));
assert!(is_likely_bluetooth_device("airpods"));
}
#[test]
fn detects_generic_bluetooth() {
assert!(is_likely_bluetooth_device("Bluetooth Headset"));
assert!(is_likely_bluetooth_device("BT Audio"));
}
#[test]
fn does_not_detect_wired() {
assert!(!is_likely_bluetooth_device("Realtek HD Audio"));
assert!(!is_likely_bluetooth_device("USB Microphone"));
assert!(!is_likely_bluetooth_device("Blue Yeti"));
}
#[test]
fn wireless_mic_gets_higher_latency() {
let wireless = estimate_input_latency(48000, 1024, Some("AirPods Pro"));
let wired = estimate_input_latency(48000, 1024, Some("USB Microphone"));
assert!(wireless.device_latency_secs >= WIRELESS_MIN_LATENCY_SECS);
assert!(wired.device_latency_secs < WIRELESS_MIN_LATENCY_SECS);
assert!(wireless.total_latency_secs > wired.total_latency_secs);
}
}
}
#[cfg(test)]
#[allow(clippy::unchecked_duration_subtraction)]
mod tests {
use super::*;
use std::time::Instant;
#[test]
fn latency_estimator_increases_quickly() {
let mut estimator = OutputLatencyEstimator::new();
estimator.observe_latency(Some(Duration::from_millis(5)));
estimator.last_update_at = Some(Instant::now() - Duration::from_millis(300));
estimator.observe_latency(Some(Duration::from_millis(120)));
let latency = estimator.current_secs().unwrap();
assert!(latency > 0.05);
}
#[test]
fn latency_estimator_decreases_slowly() {
let mut estimator = OutputLatencyEstimator::new();
estimator.observe_latency(Some(Duration::from_millis(150)));
let first = estimator.current_secs().unwrap();
estimator.last_update_at = Some(Instant::now() - Duration::from_millis(60));
estimator.observe_latency(Some(Duration::from_millis(10)));
let second = estimator.current_secs().unwrap();
assert!(second > 0.02);
assert!(second > 0.5 * first);
}
#[test]
fn latency_estimator_ignores_initial_zero() {
let mut estimator = OutputLatencyEstimator::new();
estimator.observe_latency(Some(Duration::from_millis(0)));
assert!(estimator.current_secs().is_none());
estimator.last_update_at = Some(Instant::now() - Duration::from_millis(60));
estimator.observe_latency(Some(Duration::from_millis(120)));
assert!(estimator.current_secs().unwrap() > 0.1);
}
#[test]
fn wireless_floor_is_enforced() {
let hint = OutputLatencyHint::new(0.05, OutputTransportKind::Wireless);
let mut estimator = OutputLatencyEstimator::from_hint(hint);
assert!(estimator.current_secs().unwrap() >= WIRELESS_MIN_LATENCY_SECS);
estimator.last_update_at = Some(Instant::now() - Duration::from_millis(60));
estimator.observe_latency(Some(Duration::from_millis(20)));
assert!(estimator.current_secs().unwrap() >= WIRELESS_MIN_LATENCY_SECS);
}
#[test]
fn latency_corrector_applies_initial_multiplier() {
let hint = OutputLatencyHint::new(0.05, OutputTransportKind::Wired);
let config = LatencyCorrectionConfig::default();
let corrector = LatencyCorrector::new(Some(hint), config);
let initial = corrector.initial_compensation_secs();
assert_eq!(initial, 0.05 * 2.0);
assert_eq!(corrector.initial_output_latency_secs(), 0.05);
}
#[test]
fn latency_corrector_reports_floor_constrained_initial_latency() {
let hint = OutputLatencyHint::new(0.05, OutputTransportKind::Wireless);
let config = LatencyCorrectionConfig {
initial_safety_multiplier: 3.0,
..Default::default()
};
let corrector = LatencyCorrector::new(Some(hint), config);
assert_eq!(
corrector.initial_output_latency_secs(),
WIRELESS_MIN_LATENCY_SECS
);
assert_eq!(
corrector.initial_compensation_secs(),
WIRELESS_MIN_LATENCY_SECS * 3.0
);
}
#[test]
fn latency_corrector_freezes_initially() {
let hint = OutputLatencyHint::new(0.05, OutputTransportKind::Wired);
let config = LatencyCorrectionConfig::default();
let corrector = LatencyCorrector::new(Some(hint), config);
// Initially no latency used in callbacks
assert!(corrector.current_latency_secs().is_none());
// But initial compensation should be available with safety multiplier
let initial_compensation = corrector.initial_compensation_secs();
assert_eq!(initial_compensation, 0.05 * 2.0);
}
#[test]
fn latency_corrector_with_custom_config() {
let hint = OutputLatencyHint::new(0.1, OutputTransportKind::Wireless);
let config = LatencyCorrectionConfig {
initial_safety_multiplier: 3.0,
min_apply_delta_secs: 0.01,
..Default::default()
};
let corrector = LatencyCorrector::new(Some(hint), config);
// Should apply custom multiplier, but 0.1 gets constrained to WIRELESS_MIN_LATENCY_SECS (0.12)
// So: 0.12 * 3.0 = 0.36
assert!((corrector.initial_compensation_secs() - 0.36).abs() < f64::EPSILON);
}
#[test]
fn default_latency_hint_fallback() {
// Test fallback calculation for unknown sample rate
let hint = default_output_latency_hint(0, 512);
assert!(hint.is_none());
// Test with valid parameters
let hint = default_output_latency_hint(48000, 512);
assert!(hint.is_some());
if let Some(h) = hint {
// Should have some reasonable latency value
assert!(h.latency_secs > 0.0);
assert!(h.latency_secs < 1.0); // Should be reasonable for most cases
}
}
#[test]
fn transport_kind_wireless_constraints() {
let wireless_hint = OutputLatencyHint::new(0.01, OutputTransportKind::Wireless);
let estimator = OutputLatencyEstimator::from_hint(wireless_hint);
// Should enforce minimum wireless latency
assert!(estimator.current_secs().unwrap() >= WIRELESS_MIN_LATENCY_SECS);
}
#[test]
fn latency_estimator_bias() {
let mut estimator = OutputLatencyEstimator::with_bias(0.05);
assert_eq!(estimator.bias_secs(), 0.05);
// Should start with bias value
assert_eq!(estimator.current_secs(), Some(0.05));
// Test bias modification
estimator.set_bias_secs(0.1);
assert_eq!(estimator.bias_secs(), 0.1);
}
#[test]
fn integration_latency_correction_workflow() {
// Simulate realistic audio playback scenario
let sample_rate = 48000;
let buffer_size = 512;
// 1. Get initial hardware hint
let hint = default_output_latency_hint(sample_rate, buffer_size);
assert!(hint.is_some());
let hint = hint.unwrap();
assert!(hint.latency_secs > 0.0);
assert!(hint.latency_secs < 1.0); // Reasonable for most hardware
// 2. Create corrector with custom config
let config = LatencyCorrectionConfig {
initial_safety_multiplier: 2.0,
min_apply_delta_secs: 0.001,
min_updates_for_dynamic: 3,
max_change_per_sec: 0.1,
initial_freeze_duration_secs: 0.1,
log_change_threshold_ms: 10,
};
let corrector = LatencyCorrector::new(Some(hint), config);
// 3. Verify initial compensation
let initial_compensation = corrector.initial_compensation_secs();
assert!(initial_compensation >= hint.latency_secs * 1.5); // At least 1.5x due to constraints
assert!(initial_compensation <= hint.latency_secs * 2.5); // But not more than 2.5x
// 4. Simulate audio rendering setup
let base_playhead = 5.0; // 5 seconds into the track
let compensated_playhead = base_playhead + initial_compensation;
assert!(compensated_playhead > base_playhead);
// 5. Verify corrector state
assert!(corrector.current_latency_secs().is_none()); // No callback updates yet
assert_eq!(corrector.estimator().update_count(), 0);
// This test demonstrates the complete workflow for integrating
// latency correction into audio playback systems
}
#[test]
fn output_transport_kind_wireless_detection() {
assert!(OutputTransportKind::Wireless.is_wireless());
assert!(OutputTransportKind::Airplay.is_wireless());
assert!(OutputTransportKind::ContinuityWireless.is_wireless());
assert!(!OutputTransportKind::Wired.is_wireless());
assert!(!OutputTransportKind::Unknown.is_wireless());
}
#[test]
fn output_latency_hint_creation() {
let hint = OutputLatencyHint::new(0.05, OutputTransportKind::Wired);
assert_eq!(hint.latency_secs, 0.05);
assert_eq!(hint.transport, OutputTransportKind::Wired);
assert!(!hint.is_probably_wireless());
}
#[test]
fn wireless_hint_detection() {
let wireless_hint = OutputLatencyHint::new(0.12, OutputTransportKind::Wireless);
assert!(wireless_hint.is_probably_wireless());
let wired_hint = OutputLatencyHint::new(0.03, OutputTransportKind::Wired);
assert!(!wired_hint.is_probably_wireless());
}
}