# whenkey2007/true-tone architecture

> Architecture diagram of the GitHub repository whenkey2007/true-tone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whenkey2007/true-tone
- Repository: https://github.com/whenkey2007/true-tone

## Overview

TrueTone detects AI-generated speech from live microphone or system audio, WAV uploads, and replayed files. Its principal workflow captures audio, prepares it for speech gating and model/feature scoring, stabilizes scores over time, then presents live results and alerts in the dashboard. The graph preserves the documented capture, analysis, and evaluation capabilities; unsampled feature and preprocessing connections are based on README descriptions, while code-level edges cite the excerpts or SOURCE INDEX relationships available here.

Main entry points: [`pipeline/orchestrator.py`](https://github.com/whenkey2007/true-tone/blob/main/pipeline/orchestrator.py) (Threaded Orchestrator), [`app.py`](https://github.com/whenkey2007/true-tone/blob/main/app.py) (Application Modes), [`inference/detector.py`](https://github.com/whenkey2007/true-tone/blob/main/inference/detector.py) (AI Detector), [`live_pipeline.py`](https://github.com/whenkey2007/true-tone/blob/main/live_pipeline.py) (Standalone Live Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Audio Sources"]
  node_mic["Microphone Capture<br/>[mic_capture.py]"]
  node_loopback["System Loopback<br/>[system_capture.py]"]
  node_wav_replay["WAV Replay<br/>[wav_loader.py]"]
  node_audio_utils["Audio Loading and Chunks<br/>[wav_utils.py]"]
  node_audio_buffer["Sliding Audio Buffer<br/>[buffer.py]"]
end

subgraph group_signal["Signal Analysis"]
  node_preprocessor["Audio Preprocessing<br/>[preprocessor.py]"]
  node_vad["Speech Gates<br/>[vad.py]"]
  node_features["DSP Features<br/>[features.py]"]
  node_detector["AI Detector<br/>[detector.py]"]
end

subgraph group_runtime["Pipeline Runtime"]
  node_app["Application Modes<br/>[app.py]"]
  node_orchestrator["Threaded Orchestrator<br/>[orchestrator.py]"]
  node_live_pipeline["Standalone Live Pipeline<br/>[live_pipeline.py]"]
  node_temporal["Temporal Aggregation<br/>[temporal.py]"]
end

subgraph group_interface["User Experience"]
  node_dashboard["Dashboard and Alerts<br/>[dashboard.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_stream_eval["Streaming Evaluation"]
end

node_user(("User"))

node_user -->|"selects mode"| node_app
node_app -->|"configures capture"| node_mic
node_app -->|"configures capture"| node_loopback
node_app -->|"configures replay"| node_wav_replay
node_app -->|"creates detector"| node_detector
node_app -->|"creates gate"| node_vad
node_app -->|"starts pipeline"| node_orchestrator
node_mic -.->|"supplies chunks"| node_orchestrator
node_loopback -.->|"supplies chunks"| node_orchestrator
node_wav_replay -.->|"supplies chunks"| node_orchestrator
node_wav_replay -->|"loads and chunks"| node_audio_utils
node_orchestrator -->|"prepares audio"| node_preprocessor
node_orchestrator -->|"gates speech"| node_vad
node_orchestrator -->|"requests scores"| node_detector
node_detector -->|"extracts features"| node_features
node_detector -->|"uses audio helpers"| node_audio_utils
node_orchestrator -->|"stabilizes scores"| node_temporal
node_dashboard -->|"reads state"| node_orchestrator
node_dashboard -->|"offers file replay"| node_wav_replay
node_dashboard -->|"offers live capture"| node_mic
node_dashboard -->|"offers loopback"| node_loopback
node_orchestrator -->|"provides scores"| node_dashboard
node_live_pipeline -->|"starts capture"| node_mic
node_live_pipeline -->|"supports capture"| node_loopback
node_live_pipeline -->|"gates speech"| node_vad
node_live_pipeline -->|"requests scores"| node_detector
node_live_pipeline -->|"aggregates scores"| node_temporal
node_stream_eval -->|"gates speech"| node_vad
node_stream_eval -->|"requests scores"| node_detector
node_stream_eval -->|"evaluates aggregation"| node_temporal
node_stream_eval -->|"loads audio"| node_audio_utils

click node_app "https://github.com/whenkey2007/true-tone/blob/main/app.py"
click node_mic "https://github.com/whenkey2007/true-tone/blob/main/audio/mic_capture.py"
click node_loopback "https://github.com/whenkey2007/true-tone/blob/main/audio/system_capture.py"
click node_wav_replay "https://github.com/whenkey2007/true-tone/blob/main/audio/wav_loader.py"
click node_audio_utils "https://github.com/whenkey2007/true-tone/blob/main/audio/wav_utils.py"
click node_audio_buffer "https://github.com/whenkey2007/true-tone/blob/main/audio/buffer.py"
click node_preprocessor "https://github.com/whenkey2007/true-tone/blob/main/processing/preprocessor.py"
click node_vad "https://github.com/whenkey2007/true-tone/blob/main/audio/vad.py"
click node_features "https://github.com/whenkey2007/true-tone/blob/main/processing/features.py"
click node_detector "https://github.com/whenkey2007/true-tone/blob/main/inference/detector.py"
click node_orchestrator "https://github.com/whenkey2007/true-tone/blob/main/pipeline/orchestrator.py"
click node_live_pipeline "https://github.com/whenkey2007/true-tone/blob/main/live_pipeline.py"
click node_temporal "https://github.com/whenkey2007/true-tone/blob/main/pipeline/temporal.py"
click node_dashboard "https://github.com/whenkey2007/true-tone/blob/main/ui/dashboard.py"
click node_stream_eval "https://github.com/whenkey2007/true-tone/blob/main/tools/evaluate_streaming.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mic,node_loopback,node_wav_replay,node_audio_utils,node_audio_buffer,node_user toneBlue
class node_preprocessor,node_vad,node_features,node_detector toneAmber
class node_app,node_orchestrator,node_live_pipeline,node_temporal toneMint
class node_dashboard toneRose
class node_stream_eval toneIndigo
```

## Components

### Audio Sources

- [Microphone Capture](https://github.com/whenkey2007/true-tone/blob/main/audio/mic_capture.py): `audio/mic_capture.py`
- [System Loopback](https://github.com/whenkey2007/true-tone/blob/main/audio/system_capture.py): `audio/system_capture.py`
- [WAV Replay](https://github.com/whenkey2007/true-tone/blob/main/audio/wav_loader.py): `audio/wav_loader.py`
- [Audio Loading and Chunks](https://github.com/whenkey2007/true-tone/blob/main/audio/wav_utils.py): `audio/wav_utils.py`
- [Sliding Audio Buffer](https://github.com/whenkey2007/true-tone/blob/main/audio/buffer.py): `audio/buffer.py`

### Signal Analysis

- [Audio Preprocessing](https://github.com/whenkey2007/true-tone/blob/main/processing/preprocessor.py): `processing/preprocessor.py`
- [Speech Gates](https://github.com/whenkey2007/true-tone/blob/main/audio/vad.py): `audio/vad.py`
- [DSP Features](https://github.com/whenkey2007/true-tone/blob/main/processing/features.py): `processing/features.py`
- [AI Detector](https://github.com/whenkey2007/true-tone/blob/main/inference/detector.py): `inference/detector.py`

### Pipeline Runtime

- [Application Modes](https://github.com/whenkey2007/true-tone/blob/main/app.py): `app.py`
- [Threaded Orchestrator](https://github.com/whenkey2007/true-tone/blob/main/pipeline/orchestrator.py): `pipeline/orchestrator.py`
- [Standalone Live Pipeline](https://github.com/whenkey2007/true-tone/blob/main/live_pipeline.py): `live_pipeline.py`
- [Temporal Aggregation](https://github.com/whenkey2007/true-tone/blob/main/pipeline/temporal.py): `pipeline/temporal.py`

### User Experience

- [Dashboard and Alerts](https://github.com/whenkey2007/true-tone/blob/main/ui/dashboard.py): `ui/dashboard.py`

### Evaluation

- [Streaming Evaluation](https://github.com/whenkey2007/true-tone/blob/main/tools/evaluate_streaming.py): `tools/evaluate_streaming.py`

### Other components

- **User**

## Connections

- User → Application Modes: selects mode (evidence: `README.md`)
- Application Modes → Microphone Capture: configures capture (evidence: `app.py`)
- Application Modes → System Loopback: configures capture (evidence: `app.py`)
- Application Modes → WAV Replay: configures replay (evidence: `app.py`)
- Application Modes → AI Detector: creates detector (evidence: `app.py`)
- Application Modes → Speech Gates: creates gate (evidence: `app.py`)
- Application Modes → Threaded Orchestrator: starts pipeline (evidence: `app.py`)
- Microphone Capture → Threaded Orchestrator: supplies chunks
- System Loopback → Threaded Orchestrator: supplies chunks
- WAV Replay → Threaded Orchestrator: supplies chunks
- WAV Replay → Audio Loading and Chunks: loads and chunks (evidence: `audio/wav_loader.py`)
- Threaded Orchestrator → Audio Preprocessing: prepares audio (evidence: `README.md`)
- Threaded Orchestrator → Speech Gates: gates speech (evidence: `pipeline/orchestrator.py`)
- Threaded Orchestrator → AI Detector: requests scores (evidence: `pipeline/orchestrator.py`)
- AI Detector → DSP Features: extracts features (evidence: `inference/detector.py`)
- AI Detector → Audio Loading and Chunks: uses audio helpers (evidence: `inference/detector.py`)
- Threaded Orchestrator → Temporal Aggregation: stabilizes scores (evidence: `pipeline/orchestrator.py`)
- Dashboard and Alerts → Threaded Orchestrator: reads state (evidence: `ui/dashboard.py`)
- Dashboard and Alerts → WAV Replay: offers file replay (evidence: `ui/dashboard.py`)
- Dashboard and Alerts → Microphone Capture: offers live capture (evidence: `ui/dashboard.py`)
- Dashboard and Alerts → System Loopback: offers loopback (evidence: `ui/dashboard.py`)
- Threaded Orchestrator → Dashboard and Alerts: provides scores (evidence: `README.md`)
- Standalone Live Pipeline → Microphone Capture: starts capture (evidence: `live_pipeline.py`)
- Standalone Live Pipeline → System Loopback: supports capture (evidence: `live_pipeline.py`)
- Standalone Live Pipeline → Speech Gates: gates speech (evidence: `live_pipeline.py`)
- Standalone Live Pipeline → AI Detector: requests scores (evidence: `live_pipeline.py`)
- Standalone Live Pipeline → Temporal Aggregation: aggregates scores (evidence: `live_pipeline.py`)
- Streaming Evaluation → Speech Gates: gates speech (evidence: `tools/evaluate_streaming.py`)
- Streaming Evaluation → AI Detector: requests scores (evidence: `tools/evaluate_streaming.py`)
- Streaming Evaluation → Temporal Aggregation: evaluates aggregation (evidence: `tools/evaluate_streaming.py`)
- Streaming Evaluation → Audio Loading and Chunks: loads audio (evidence: `tools/evaluate_streaming.py`)
