title: Browser-Based Diagnostic Decision Tree

content: Implementation of a status code system (GREEN, YELLOW, ORANGE, RED) to categorize audio stream health. It runs non-intrusively on session start, checking API availability, permissions, device enumeration, and stream validation via AudioContext before passing the stream to the application.


title: Audio Diagnosis Pseudocode Logic

content: Pseudocode for the `diagnoseAudio` function: 1. Check `navigator.mediaDevices` support. 2. Query permission state. 3. Enumerate devices and check for audio input. 4. Request stream (`getUserMedia`). 5. Validate stream using `AudioContext` and `AnalyserNode` to calculate RMS (threshold < 1 for silence). 6. Map errors (NotAllowedError, NotFoundError, NotReadableError) to status codes.


title: Intelligent Device Selection Algorithm

content: Scoring heuristic algorithm for picking the best microphone: User Preference (Weight: 1000), Device Type Priority (Bluetooth: 500, USB: 400, Webcam: 200, Built-in: 100), Windows Default Device (Weight: 50), Active Signal Score (tie-breaker via RMS), and Recency.


title: Mid-Call Device Failure Fallback Chain

content: Ordered sequence of recovery attempts when a device fails mid-call: 1. Attempt Reconnect (same deviceId). 2. Switch to Next Best (re-run selection excluding failed ID). 3. Notify User (non-blocking notification). 4. Degrade to Listen-Only. 5. Terminate session.


title: Bluetooth Audio Profile Management

content: Strategy for handling Bluetooth issues: Detection via label keywords. Latency tracking using `audioContext.outputLatency` (spike from ~50ms to ~250ms indicates profile switch). Dropout detection via silence flag >1s. Signal strength proxy via WebRTC stats (`packetsLost`, `jitter`).


title: Real-Time Audio Health Metrics

content: Metrics and thresholds for continuous monitoring: RMS Amplitude (Normal: 20-80), Clipping Rate (Normal: <0.1%), Silence % (Normal: <70%), Packet Loss (Normal: <1%), Jitter (Normal: <30ms). Includes 3-Level Auto-Recovery: Soft (internal), Moderate (guidance toast), Hard (blocking modal).


title: 3-Level Auto-Recovery System

content: Structure for handling audio issues: Level 1 (Soft Recovery): Internal fixes like adjusting codec bitrate. Level 2 (Moderate Recovery): Non-blocking toast with actionable suggestion. Level 3 (Hard Recovery): Blocking modal, session pause, and guided fix.


title: Cross-Platform Diagnostic Engine

content: Abstraction layer `PlatformAdapter` to handle OS-specific quirks: iOS (enumerateDevices requires active stream), Android (battery optimization checks), Windows (handling 3-level default devices), macOS (Safari sticky permissions), Linux (de-prioritizing Monitor/Loopback devices).


title: Graceful Degradation Hierarchy

content: 5-level degradation of service based on failure severity: Level 5 (Full Duplex), Level 4 (Half Duplex/Push-to-Talk), Level 3 (Playback Only), Level 2 (Text Only), Level 1 (Session End).


title: Progressive Disclosure UX

content: UI/UX principle of showing only necessary information: Level 1 (Silent Auto-Fix - 70-80% of cases), Level 2 (Gentle Toast), Level 3 (Blocking Modal with Checklist), Level 4 (Guided Walkthrough with screenshots), Level 5 (Human Escalation).


title: Embeddable Widget Architecture

content: Technical design for the widget: TypeScript/Preact, Shadow DOM for CSS isolation, tree-shakeable modular packages (@genesis/audio-doctor/core, analyzer, ui, recovery, reporter). API includes `AudioDoctor` class with `runPreflightCheck()` and `onComplete` callback.


title: Audio Doctor NPM Packages

content: Modular package specifications: @genesis/audio-doctor/core (~8KB), @genesis/audio-doctor/analyzer (~12KB), @genesis/audio-doctor/ui (~15KB), @genesis/audio-doctor/recovery (~10KB), @genesis/audio-doctor/reporter (~5KB).


title: Data Collection Pipeline Schema

content: JSON schema for analytics: Captures sessionId, platform (OS, Browser), initialState (permissions, devices), diagnosticTrace (steps, status, duration), userActions, and finalResolution (status, code, timeToResolve).


title: Talking Widget Integration

content: Policy for Customer-facing chat: Zero-tolerance, aggressive recovery. Runs silent `diagnose()` on page load. Disables 'voice' button if not GREEN. Immediately switches devices on failure.


title: AIVA Integration

content: Policy for Internal agent assistant: Conservative recovery. Persistent 'Audio Health' icon (Green/Yellow/Red). Shows detailed metrics (latency, jitter). Prefers user notification over auto-switching.


title: ReceptionistAI Integration

content: Policy for B2B phone system: Mandatory pre-flight check before going 'on duty'. Logs pass/fail and device used. Alerts business owner/admin for recurring issues.


title: Data-Driven Competitive Advantage

content: The system creates a learning flywheel by collecting diagnostic data (most problematic devices, common errors per platform). This data is used to improve the product, reduce support load, and address the #1 friction point in voice applications.