What to Check When Your Meeting App Cannot Hear You

a(constraints); result.permissionGranted = true;

  // Analyze signal flow
  this.audioContext = new AudioContext();
  this.analyser = this.audioContext.createAnalyser();
  this.analyser.fftSize = 256;

  const source = this.audioContext.createMediaStreamSource(this.stream);
  source.connect(this.analyser);

  const volume = this.getAverageVolume();
  result.volumeLevel = volume;
  result.signalDetected = volume > 0.02; // Threshold for silence detection

  if (!result.signalDetected) {
    // Differentiate between hardware mute and OS routing
    result.layerFailure = this.inferHardwareFailure() ? 'hardware' : 'os';
    result.errorMessage = 'Signal absent. Check physical mute switch or OS input routing.';
  }

} catch (error) {
  result.layerFailure = this.classifyError(error);
  result.errorMessage = error instanceof Error ? error.message : 'Unknown diagnostic error.';
} finally {
  this.cleanup();
}

return result;

}

private getAverageVolume(): number { if (!this.analyser) return 0; const dataArray = new Uint8Array(this.analyser.frequencyBinCount); this.analyser.getByteFrequencyData(dataArray); const sum = dataArray.reduce((acc, val) => acc + val, 0); return sum / dataArray.length / 255; // Normalize to 0-1 }

private inferHardwareFailure(): boolean { // Heuristic: If stream exists but volume is zero, check for common hardware indicators. // In production, this could query device capabilities or check system APIs. return true; // Simplified for example; real impl would check device metadata }

private classifyError(error: unknown): DiagnosticResult['layerFailure'] { if (error instanceof DOMException && error.name === 'NotAllowedError') { return 'browser'; } if (error instanceof DOMException && error.name === 'NotFoundError') { return 'os'; } return 'app'; }

private cleanup() { this.stream?.getTracks().forEach(track => track.stop()); this.audioContext?.close(); this.stream = null; this.audioContext = null; this.analyser = null; } }

**Rationale:**
*   **Echo Cancellation Disabled:** Processing algorithms can mask silence or introduce latency. Disabling them ensures the diagnostic measures raw input capability.
*   **Volume Threshold:** A threshold of `0.02` filters out background noise floor while detecting speech. This prevents false positives from ambient room tone.
*   **Cleanup:** `track.stop()` is critical to release the microphone resource immediately, preventing "device in use" errors in subsequent checks.

### Pitfall Guide

1.  **The Shotgun Approach**
    *   *Explanation:* Changing OS settings, app settings, and browser permissions simultaneously.
    *   *Fix:* Isolate one layer at a time. Verify browser access first; if successful, move to app configuration. If browser access fails, inspect OS and hardware.

2.  **Exclusive Mode Blindspot**
    *   *Explanation:* Some operating systems allow an application to claim exclusive control of the microphone, blocking other apps even if permissions are granted.
    *   *Fix:* Check the OS audio mixer for exclusive mode flags. If the diagnostic fails while another app is active, advise the user to close the competing application or disable exclusive mode in system settings.

3.  **Bluetooth Handshake Latency**
    *   *Explanation:* Bluetooth microphones may report as connected but fail to establish the audio profile (HFP/HSP) immediately. The device appears available but produces no signal.
    *   *Fix:* Verify the connection state includes an active audio profile. Implement a retry mechanism with a short delay for Bluetooth devices, or prompt the user to toggle Bluetooth to force a profile renegotiation.

4.  **Permission State Staleness**
    *   *Explanation:* Browsers may cache permission states. A user might have previously denied access, and the app fails to re-prompt or detect the denial correctly.
    *   *Fix:* Use `navigator.permissions.query` to check the current state. If the state is `prompt`, the app should trigger a user gesture to request access. Clear site data if the state is stuck.

5.  **Default Device Drift**
    *   *Explanation:* The OS default input device may change due to driver updates or peripheral connections, causing the app to use an unintended microphone (e.g., a webcam mic instead of a headset).
    *   *Fix:* Never rely on the default device. Explicitly enumerate devices and allow the user to select the desired input. Validate that the selected device ID matches the expected hardware.

6.  **Assuming `getUserMedia` Success Equals Audio**
    *   *Explanation:* A successful stream acquisition only confirms permission and device availability. It does not guarantee audio is flowing.
    *   *Fix:* Always attach an `AnalyserNode` and monitor volume levels. If the stream is active but volume is zero, the issue is likely hardware mute or OS routing.

7.  **Ignoring Sample Rate Mismatches**
    *   *Explanation:* Rarely, a device may support a sample rate that the browser or app does not handle correctly, resulting in silence or distortion.
    *   *Fix:* Specify explicit sample rate constraints in `getUserMedia` if the device is known to have compatibility issues. Validate the `AudioContext` sample rate matches the stream.

### Production Bundle

#### Action Checklist

- [ ] **Verify Hardware Mute:** Inspect physical mute switches on headsets, webcams, and laptops.
- [ ] **Run Browser Signal Test:** Execute `AudioChainAnalyzer` to confirm browser-level access and signal detection.
- [ ] **Confirm OS Input Routing:** Check system audio settings to ensure the correct device is selected and not muted.
- [ ] **Check App Device Selection:** Validate the application's input selector matches the intended hardware device ID.
- [ ] **Validate Exclusive Access:** Ensure no other application is holding exclusive control of the microphone.
- [ ] **Review Permission State:** Confirm the browser permission status is `granted` and not `denied` or `prompt`.
- [ ] **Test with External Tool:** Use a generic browser microphone test to isolate app-specific issues from general browser issues.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Enterprise Managed Device** | Layered Isolation with IT Policy Check | MDM policies may block microphone access or enforce specific devices. | Low (Automated policy validation) |
| **Personal Device / BYOD** | User-Guided Diagnostic UI | Users need clear instructions to check physical switches and OS settings. | Medium (Support interaction) |
| **Web App vs Native App** | Browser API Diagnostics | Web apps are constrained by browser security models; native apps have broader OS access. | Low (Standardized web APIs) |
| **High-Volume Support** | Automated Telemetry Integration | Embed `AudioChainAnalyzer` results in crash reports to triage issues without user interaction. | High (Initial dev effort, long-term savings) |

#### Configuration Template

Use this JSON configuration to tune the diagnostic thresholds and behavior for your environment.

```json
{
  "audioDiagnostics": {
    "volumeThreshold": 0.02,
    "sampleDurationMs": 2000,
    "disableProcessing": true,
    "checkExclusiveAccess": true,
    "retryBluetoothDelayMs": 1500,
    "allowedLayers": ["hardware", "os", "browser", "app"],
    "telemetry": {
      "enabled": true,
      "endpoint": "/api/diagnostics/audio"
    }
  }
}

Quick Start Guide

1. Import the Analyzer: Add AudioChainAnalyzer to your diagnostic module.
2. Initialize Diagnostics: Call analyzer.runDiagnostics() triggered by a user gesture (e.g., "Test Microphone" button).
3. Parse Results: Inspect layerFailure and signalDetected from the returned DiagnosticResult.
4. Display Feedback: Show user-friendly messages based on the failure layer. For example, if layerFailure === 'hardware', display "Check your microphone mute switch."
5. Integrate Telemetry: Send diagnostic results to your analytics endpoint to monitor audio health across your user base.