feat: audio latency

apps/common-app/src/demos/index.ts

@@ -37,9 +37,8 @@ export const demos: DemoScreen[] = [
   {
     key: 'Crossfade',
     title: 'Crossfade',
-    subtitle:
-      'Demonstrates crossfading between two audio files.',
+    subtitle: 'Demonstrates crossfading between two audio files.',
     icon: icons.ArrowLeftRight,
     screen: Crossfade,
-  }
+  },
 ] as const;

apps/common-app/src/examples/index.ts

@@ -31,6 +31,7 @@ type NavigationParamList = {
   ConvolverIR: undefined;
   AudioParamPipeline: undefined;
   TestScreen: undefined;
+  LatencyValidation: undefined;
 };
 
 export type ExampleKey = keyof NavigationParamList;

apps/common-app/src/other/LatencyValidation/CorrelationPlot.tsx

@@ -0,0 +1,149 @@
+import React, { FC, useMemo } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import Svg, { Circle, Line, Path, Rect } from 'react-native-svg';
+
+import { colors } from '../../styles';
+import type { CorrelationPoint } from './types';
+
+interface CorrelationPlotProps {
+  title: string;
+  caption?: string;
+  width: number;
+  height?: number;
+  points: CorrelationPoint[];
+  bestLagMs: number | null;
+  expectedLagMs: number;
+}
+
+const CorrelationPlot: FC<CorrelationPlotProps> = ({
+  title,
+  caption,
+  width,
+  height = 120,
+  points,
+  bestLagMs,
+  expectedLagMs,
+}) => {
+  const { path, bestX, expectedX, maxScore } = useMemo(() => {
+    if (points.length === 0) {
+      return { path: '', bestX: null, expectedX: null, maxScore: 1 };
+    }
+
+    const minLag = points[0].lagMs;
+    const maxLag = points[points.length - 1].lagMs;
+    const lagSpan = Math.max(maxLag - minLag, 1);
+    const maxScoreValue = Math.max(...points.map((point) => point.score), 0.001);
+
+    const builtPath = points
+      .map((point, index) => {
+        const x = ((point.lagMs - minLag) / lagSpan) * width;
+        const y = height - (point.score / maxScoreValue) * (height * 0.82) - 8;
+        return `${index === 0 ? 'M' : 'L'}${x.toFixed(2)},${y.toFixed(2)}`;
+      })
+      .join(' ');
+
+    return {
+      path: builtPath,
+      bestX:
+        bestLagMs !== null
+          ? ((bestLagMs - minLag) / lagSpan) * width
+          : null,
+      expectedX: ((expectedLagMs - minLag) / lagSpan) * width,
+      maxScore: maxScoreValue,
+    };
+  }, [bestLagMs, expectedLagMs, height, points, width]);
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>{title}</Text>
+      {caption ? <Text style={styles.caption}>{caption}</Text> : null}
+
+      <View style={[styles.plotFrame, { width, height }]}>
+        <Svg width={width} height={height}>
+          <Rect
+            x={0}
+            y={0}
+            width={width}
+            height={height}
+            fill={colors.backgroundDark}
+            rx={4}
+          />
+
+          {expectedX !== null ? (
+            <Line
+              x1={expectedX}
+              y1={0}
+              x2={expectedX}
+              y2={height}
+              stroke={colors.yellow}
+              strokeDasharray="4 4"
+              strokeWidth={1}
+            />
+          ) : null}
+
+          {bestX !== null ? (
+            <Line
+              x1={bestX}
+              y1={0}
+              x2={bestX}
+              y2={height}
+              stroke={colors.main}
+              strokeWidth={1.5}
+            />
+          ) : null}
+
+          <Path d={path} stroke={colors.main} strokeWidth={2} fill="none" />
+
+          {bestX !== null ? (
+            <Circle cx={bestX} cy={12} r={4} fill={colors.main} />
+          ) : null}
+        </Svg>
+      </View>
+
+      <View style={styles.legendRow}>
+        <Text style={styles.legendText}>Peak score max={maxScore.toFixed(3)}</Text>
+        <Text style={[styles.legendText, { color: colors.main }]}>
+          Best lag {bestLagMs !== null ? `${bestLagMs.toFixed(1)} ms` : '—'}
+        </Text>
+        <Text style={[styles.legendText, { color: colors.yellow }]}>
+          Expected {expectedLagMs.toFixed(1)} ms
+        </Text>
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  caption: {
+    color: colors.gray,
+    fontSize: 12,
+    lineHeight: 17,
+    marginBottom: 8,
+  },
+  container: {
+    backgroundColor: colors.backgroundLight,
+    borderRadius: 8,
+    gap: 8,
+    padding: 12,
+  },
+  legendRow: {
+    gap: 4,
+  },
+  legendText: {
+    color: colors.gray,
+    fontSize: 11,
+  },
+  plotFrame: {
+    borderColor: colors.separator,
+    borderRadius: 4,
+    borderWidth: StyleSheet.hairlineWidth,
+    overflow: 'hidden',
+  },
+  title: {
+    color: colors.white,
+    fontSize: 15,
+    fontWeight: '700',
+  },
+});
+
+export default CorrelationPlot;

apps/common-app/src/other/LatencyValidation/LatencyValidation.tsx

@@ -0,0 +1,198 @@
+import React, { FC, useEffect, useRef, useState } from 'react';
+import { Platform, ScrollView, StyleSheet } from 'react-native';
+import { AudioManager } from 'react-native-audio-api';
+
+import { Container } from '../../components';
+import { audioContext, audioRecorder } from '../../singletons';
+import { TestUI, type ControlAction } from '../../testComponents';
+import { formatTimestamp } from './helpers';
+import {
+  cleanupLatencyValidation,
+  runLatencyValidationSuite,
+} from './latencyTests';
+import LoopbackAnalysisPanel from './LoopbackAnalysisPanel';
+import type { LoopbackAnalysis } from './types';
+
+type RunnerState = 'idle' | 'running';
+
+const LatencyValidation: FC = () => {
+  const isMountedRef = useRef(true);
+  const [runnerState, setRunnerState] = useState<RunnerState>('idle');
+  const [currentStep, setCurrentStep] = useState(
+    'Ready to run the speaker-to-mic loopback latency check.'
+  );
+  const [analysis, setAnalysis] = useState<LoopbackAnalysis | null>(null);
+  const [liveLog, setLiveLog] = useState<string[]>([]);
+
+  const appendLog = (message: string) => {
+    if (!isMountedRef.current) {
+      return;
+    }
+
+    setLiveLog((previous) => [
+      ...previous,
+      `${formatTimestamp(Date.now())} ${message}`,
+    ]);
+  };
+
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+      cleanupLatencyValidation({ audioContext, audioRecorder }).catch((error) => {
+        console.warn('LatencyValidation cleanup failed', error);
+      });
+    };
+  }, []);
+
+  const runTest = async () => {
+    if (runnerState === 'running') {
+      return;
+    }
+
+    setRunnerState('running');
+    setAnalysis(null);
+    setLiveLog([]);
+    setCurrentStep('Preparing audio session...');
+    appendLog('Starting speaker-to-mic loopback check.');
+
+    try {
+      const permission = await AudioManager.requestRecordingPermissions();
+      if (permission !== 'Granted') {
+        throw new Error('Recording permission was not granted.');
+      }
+
+      if (Platform.OS !== 'web') {
+        AudioManager.setAudioSessionOptions({
+          iosCategory: 'playAndRecord',
+          // 'measurement' keeps the signal path raw (no AGC/EQ) so the loopback
+          // delay is accurate, while running the mic+speaker for the shortest
+          // possible window to keep the idle full-duplex buzz to a minimum.
+          iosMode: 'measurement',
+          iosOptions: ['defaultToSpeaker'],
+        });
+        await AudioManager.setAudioSessionActivity(true);
+      }
+
+      setCurrentStep('Playing beep pattern and analyzing microphone capture...');
+      appendLog('Reference pattern scheduled. Recording microphone input.');
+
+      const result = await runLatencyValidationSuite({
+        audioContext,
+        audioRecorder,
+      });
+
+      if (!isMountedRef.current) {
+        return;
+      }
+
+      setAnalysis(result);
+      appendLog(
+        `Captured ${result.recordedWindowPlot.points.length > 0 ? 'microphone' : 'no'} waveform points for visualization.`
+      );
+
+      if (result.scenario.status === 'pass') {
+        setCurrentStep(
+          'Analysis complete: aligned waveform matches the reported latencies.'
+        );
+      } else if (result.scenario.status === 'skipped') {
+        setCurrentStep(
+          'Analysis complete: microphone capture did not contain a matchable beep pattern.'
+        );
+      } else {
+        setCurrentStep(
+          'Analysis complete: waveform alignment exists but latency delta is outside tolerance.'
+        );
+      }
+
+      appendLog(`Test finished with status=${result.scenario.status}.`);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'Unknown validation error';
+      setCurrentStep(`Loopback check failed: ${message}`);
+      appendLog(`Test failed: ${message}`);
+    } finally {
+      await cleanupLatencyValidation({ audioContext, audioRecorder });
+
+      if (isMountedRef.current) {
+        setRunnerState('idle');
+      }
+    }
+  };
+
+  const resetTest = async () => {
+    if (runnerState === 'running') {
+      return;
+    }
+
+    setAnalysis(null);
+    setLiveLog([]);
+    setCurrentStep('Ready to run the speaker-to-mic loopback latency check.');
+    await cleanupLatencyValidation({ audioContext, audioRecorder });
+  };
+
+  if (Platform.OS === 'web') {
+    return (
+      <Container centered>
+        <TestUI.UnsupportedNotice
+          title="Latency Validation"
+          message="The speaker-to-mic loopback check requires native audio I/O and is not available on web."
+        />
+      </Container>
+    );
+  }
+
+  const controlActions: ControlAction[] = [
+    {
+      title: 'Run Test',
+      onPress: () => {
+        runTest();
+      },
+      disabled: runnerState === 'running',
+      width: 120,
+    },
+    {
+      title: 'Reset',
+      onPress: () => {
+        resetTest();
+      },
+      disabled: runnerState === 'running',
+      width: 90,
+    },
+  ];
+
+  return (
+    <Container disablePadding>
+      <TestUI.Header
+        title="Latency Validation"
+        subtitle="Visual loopback analysis: generated beep pattern, microphone capture, aligned overlay, and correlation search."
+      />
+      <TestUI.CurrentStepCard message={currentStep} />
+      <TestUI.ControlBar actions={controlActions} />
+
+      <ScrollView
+        style={styles.scrollView}
+        contentContainerStyle={styles.scrollContent}
+      >
+        <LoopbackAnalysisPanel analysis={analysis} />
+        <TestUI.LiveLog
+          entries={liveLog}
+          emptyMessage="Live log will appear here while the test runs."
+        />
+      </ScrollView>
+    </Container>
+  );
+};
+
+const styles = StyleSheet.create({
+  scrollContent: {
+    gap: 12,
+    paddingBottom: 32,
+    paddingHorizontal: 18,
+    paddingTop: 18,
+  },
+  scrollView: {
+    flex: 1,
+  },
+});
+
+export default LatencyValidation;