# Truth Detector (Are You A Liar?)

Truth Detector is a real-time, browser-based voice stress and vocal pitch analysis web application. It analyzes subtle vocal micro-tremors, fundamental frequency ($F_0$) variations, and amplitude fluctuations from microphone audio streams to calculate a vocal truth-or-lie score.

The entire application runs client-side in the browser using the Web Audio API and React. No audio data, recordings, or telemetry are ever uploaded or transmitted across the network, ensuring 100% privacy.

---

## Core Functionality

- **Real-Time Audio Capture:** Captures audio input directly from the user's microphone using the browser's `navigator.mediaDevices.getUserMedia` and Web Audio API `AudioContext`.
- **Dual-Phase Evaluation:**
  1. **Calibration Phase:** Measures the speaker's baseline vocal characteristics while answering a known truthful control question.
  2. **Test Phase:** Records and compares the subject's vocal response to a critical target question against their personal baseline.
- **Immediate Stress & Truth Scoring:** Calculates an overall stress score (0% to 100%) and categorizes the result into Truth, Inconclusive, or Lie states.
- **Detailed Metric Breakdown:** Provides granular metrics for fundamental pitch, pitch deviation, jitter, shimmer, hesitation pause count, and volume consistency.
- **Shareable Result Generation:** Allows users to export and share a visual result card generated on-the-fly via canvas rendering.
- **Zero Server Footprint:** Completely client-side execution; all audio buffers and calculations stay strictly in browser memory.

---

## Audio Analysis Parameters & Metrics

All signal processing takes place inside `audioAnalyzer.js`, operating on raw 32-bit floating-point PCM audio buffers extracted from an `AnalyserNode` with an FFT size of 2048:

| Parameter | Metric Name | Description & Interpretation |
| :--- | :--- | :--- |
| **Fundamental Pitch ($F_0$)** | `meanPitch` (Hz) | Average fundamental frequency of the voice during voiced frames (filtered between 50 Hz and 500 Hz). |
| **Pitch Deviation** | `pitchDev` (Hz) & `pitchDevPercent` (%) | Relative shift in mean pitch compared to the calibration baseline. Elevated pitch deviation is an indicator of psychological or autonomic arousal. |
| **Pitch Variability** | `pitchVar` (Hz) | Standard deviation of pitch across voiced segments, measuring intonation range and monotonic vs. dynamic speech patterns. |
| **Vocal Jitter** | `jitter` (ms) | Cycle-to-cycle frequency perturbations (micro-tremors) between consecutive pitch periods. High jitter indicates involuntary vocal cord tension. |
| **Vocal Shimmer** | `shimmer` (%) | Cycle-to-cycle amplitude perturbations measuring short-term variation in vocal energy and volume control. |
| **RMS Energy & Variance** | `rmsVar` (%) | Root-mean-square amplitude variance across audio frames, measuring volume stability. |
| **Hesitations & Pauses** | `pauseCount` | Count of silent frames (RMS below 0.02 for sustained intervals), detecting cognitive load, hesitations, and unnatural speech breaks. |
| **Stress Score** | `stressScore` (0–100%) | Composite index synthesized from pitch deviation, micro-tremor jitter, shimmer, and pause counts calibrated against the baseline. |

### Audio Quality Validation

Before computing metrics, the analyzer runs validation checks:
1. **Duration Check:** Rejects samples under ~30 frames (minimum ~1–2 seconds of continuous speech).
2. **Signal Level Check:** Rejects recordings where mean RMS is below 0.005 (speech too quiet or microphone muted).
3. **Noise Floor Check:** Analyzes the bottom 10th percentile of RMS values. If the ambient silence level exceeds 0.08, the system flags excessive background noise.

---

## Usage Guide

1. **Grant Microphone Access:** Launch the application in any modern web browser and grant microphone permissions when prompted.
2. **Step 1 — Calibrate Baseline:**
   - Press and hold the microphone button.
   - Speak a known truthful statement (e.g., "My name is [Name], and I am sitting in my room.").
   - Release the button after speaking clearly for at least 2 to 3 seconds.
3. **Step 2 — Conduct the Test:**
   - Ask the target question to the subject.
   - Press and hold the microphone button while they respond.
   - Release the button when their answer is complete.
4. **Step 3 — Review Results:**
   - The application computes comparative metrics against the calibration baseline.
   - View the overall Truth vs. Lie verdict, the stress percentage meter, and toggle the detailed metrics drawer for individual acoustic measurements.
5. **Step 4 — Retest, Download Result Image, or Share:**
   - Download a high-resolution results card image (PNG) formatted for social sharing, copy/share the score link, or reset the application to test another subject or question.

---

## Technical Stack

- **Frontend Framework:** [React 19](https://react.dev/) (Component-based UI, reactive state management)
- **Styling:** [Tailwind CSS v4](https://tailwindcss.com/) with custom dark neon aesthetic
- **Build System:** [Vite 8](https://vitejs.dev/) with `@vitejs/plugin-react` and `@tailwindcss/vite`
- **Audio Processing:** Native HTML5 [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) (`AudioContext`, `AnalyserNode`, `getFloatTimeDomainData`)
- **Signal Processing Algorithms:** Custom client-side autocorrelation, parabolic interpolation peak refinement, and voice stress heuristics in `audioAnalyzer.js`
- **Icons & Graphics:** [FontAwesome React Icons](https://fontawesome.com/)
- **Canvas Generation:** [html2canvas](https://html2canvas.hertzen.com/) for generating dynamic, shareable social image cards
- **Metadata & LLM Specifications:** `/llms.txt` v2 specification, discovery link tags (`describedby`, `alternate`), standard `robots.txt`, and XML sitemaps

---

## Privacy & Security

Truth Detector operates under a zero-data-collection philosophy:
- **No Remote Streaming:** Audio captured by `getUserMedia` is directly piped to an in-memory `AudioContext` within the browser tab.
- **No Cloud Storage:** No audio files, transcripts, or personal identifiers are stored on servers or transmitted to third-party APIs.
- **Ephemeral Buffers:** Audio buffers exist only in temporary JavaScript memory for the duration of the analysis session and are cleared upon reset or page refresh.