# hyeminss11/true-voice-gemma4 architecture

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

- Interactive diagram: https://gitdiagram.com/hyeminss11/true-voice-gemma4
- Repository: https://github.com/hyeminss11/true-voice-gemma4

## Overview

TrueVoice is a browser-accessible voice deepfake detector, with a separate notebook-based training and evaluation workflow. The documented user flow accepts uploaded or recorded audio, optionally simulates phone-call codec conditions, and returns a real/fake verdict using Gemma’s frozen audio tower and a trained classifier head. The README describes these relationships, but no notebook source was provided, so implementation details beyond that documentation are not verified.

Main entry points: [`notebooks/truevoice_demo.ipynb`](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb) (Gradio demo), [`notebooks/truevoice_finetune.ipynb`](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb) (Head training), [`saved_model/classifier_head.pt`](https://github.com/hyeminss11/true-voice-gemma4/blob/main/saved_model/classifier_head.pt) (Classifier weights), [`notebooks/truevoice_data_preprocess_pipeline.ipynb`](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_data_preprocess_pipeline.ipynb) (Data preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Detection demo"]
  node_demo_app["Gradio demo"]
  node_audio_input["Audio input"]
  node_phone_mode["Phone simulation"]
  node_verdict["Real / fake verdict"]
end

subgraph group_inference["Audio inference"]
  node_processor["Gemma audio processor"]
  node_audio_tower["Frozen audio tower"]
  node_pooling["Mean pooling"]
  node_classifier["Classification head"]
  node_model_weights["Classifier weights<br/>[classifier_head.pt]"]
end

subgraph group_training["Training pipeline"]
  node_metadata["Training metadata<br/>[metadata.json]"]
  node_preprocessing["Data preprocessing"]
  node_dataset["Audio dataset"]
  node_collator["On-the-fly collator"]
  node_head_training["Head training"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["EER evaluation"]
end

node_user(("User"))
node_gemma["Gemma 4 E4B"]
node_asvspoof[("ASVspoof data")]

node_user -->|"uses"| node_demo_app
node_demo_app -->|"accepts"| node_audio_input
node_demo_app -->|"offers"| node_phone_mode
node_demo_app -->|"processes audio"| node_processor
node_processor -->|"extracts features"| node_audio_tower
node_audio_tower -->|"provides features"| node_pooling
node_pooling -->|"supplies features"| node_classifier
node_classifier -->|"predicts"| node_verdict
node_gemma -->|"provides"| node_processor
node_gemma -->|"provides"| node_audio_tower
node_model_weights -->|"loads into"| node_classifier
node_asvspoof -->|"supplies audio"| node_preprocessing
node_preprocessing -->|"prepares data"| node_dataset
node_dataset -->|"loads batches"| node_collator
node_collator -->|"provides batches"| node_head_training
node_gemma -->|"provides frozen features"| node_head_training
node_head_training -->|"saves head"| node_model_weights
node_head_training -->|"records metadata"| node_metadata
node_asvspoof -->|"supplies eval set"| node_evaluation

click node_demo_app "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_audio_input "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_phone_mode "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_verdict "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_processor "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_audio_tower "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_pooling "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_classifier "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb"
click node_model_weights "https://github.com/hyeminss11/true-voice-gemma4/blob/main/saved_model/classifier_head.pt"
click node_metadata "https://github.com/hyeminss11/true-voice-gemma4/blob/main/saved_model/metadata.json"
click node_preprocessing "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_data_preprocess_pipeline.ipynb"
click node_dataset "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb"
click node_collator "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb"
click node_head_training "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb"
click node_evaluation "https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_test.ipynb"

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_demo_app,node_audio_input,node_phone_mode,node_verdict,node_user toneBlue
class node_processor,node_audio_tower,node_pooling,node_classifier,node_model_weights,node_asvspoof toneAmber
class node_metadata,node_preprocessing,node_dataset,node_collator,node_head_training toneMint
class node_evaluation toneRose
class node_gemma toneIndigo
```

## Components

### Detection demo

- [Gradio demo](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Audio input](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Phone simulation](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Real / fake verdict](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`

### Audio inference

- [Gemma audio processor](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Frozen audio tower](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Mean pooling](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Classification head](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_demo.ipynb): `notebooks/truevoice_demo.ipynb`
- [Classifier weights](https://github.com/hyeminss11/true-voice-gemma4/blob/main/saved_model/classifier_head.pt): `saved_model/classifier_head.pt`

### Training pipeline

- [Training metadata](https://github.com/hyeminss11/true-voice-gemma4/blob/main/saved_model/metadata.json): `saved_model/metadata.json`
- [Data preprocessing](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_data_preprocess_pipeline.ipynb): `notebooks/truevoice_data_preprocess_pipeline.ipynb`
- [Audio dataset](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb): `notebooks/truevoice_finetune.ipynb`
- [On-the-fly collator](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb): `notebooks/truevoice_finetune.ipynb`
- [Head training](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_finetune.ipynb): `notebooks/truevoice_finetune.ipynb`

### Evaluation

- [EER evaluation](https://github.com/hyeminss11/true-voice-gemma4/blob/main/notebooks/truevoice_test.ipynb): `notebooks/truevoice_test.ipynb`

### Other components

- **User**
- **Gemma 4 E4B**
- **ASVspoof data**

## Connections

- User → Gradio demo: uses (evidence: `README.md`)
- Gradio demo → Audio input: accepts (evidence: `README.md`)
- Gradio demo → Phone simulation: offers (evidence: `README.md`)
- Gradio demo → Gemma audio processor: processes audio (evidence: `README.md`)
- Gemma audio processor → Frozen audio tower: extracts features (evidence: `README.md`)
- Frozen audio tower → Mean pooling: provides features (evidence: `README.md`)
- Mean pooling → Classification head: supplies features (evidence: `README.md`)
- Classification head → Real / fake verdict: predicts (evidence: `README.md`)
- Gemma 4 E4B → Gemma audio processor: provides (evidence: `README.md`)
- Gemma 4 E4B → Frozen audio tower: provides (evidence: `README.md`)
- Classifier weights → Classification head: loads into (evidence: `README.md`)
- ASVspoof data → Data preprocessing: supplies audio (evidence: `README.md`)
- Data preprocessing → Audio dataset: prepares data (evidence: `README.md`)
- Audio dataset → On-the-fly collator: loads batches (evidence: `README.md`)
- On-the-fly collator → Head training: provides batches (evidence: `README.md`)
- Gemma 4 E4B → Head training: provides frozen features (evidence: `README.md`)
- Head training → Classifier weights: saves head (evidence: `README.md`)
- Head training → Training metadata: records metadata (evidence: `README.md`)
- ASVspoof data → EER evaluation: supplies eval set (evidence: `README.md`)
