# yongyizang/singfake architecture

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

- Interactive diagram: https://gitdiagram.com/yongyizang/singfake
- Repository: https://github.com/yongyizang/singfake

## Overview

SingFake is a singing-voice deepfake detection research repository: it prepares audio data, trains and evaluates four baseline model families, and includes a Chrome-based metadata annotation tool backed by Firestore. The README documents the separation/VAD-to-clip preparation sequence and codec simulation; the sampled source confirms clip generation and model inference details. The AASIST training excerpts are partial, so model/data wiring beyond what is explicit in the README is kept at the documented subsystem level.

Main entry points: [`models/feat+resnet/train.py`](https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/train.py) (Feature ResNet), [`models/AASIST/main.py`](https://github.com/yongyizang/singfake/blob/main/models/AASIST/main.py) (AASIST training), [`models/feat+resnet/eval_metrics.py`](https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/eval_metrics.py) (Evaluation metrics), [`dataset/separate.py`](https://github.com/yongyizang/singfake/blob/main/dataset/separate.py) (Vocal separation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Audio preparation"]
  node_separate["Vocal separation<br/>[separate.py]"]
  node_split["Clip generation<br/>[split.py]"]
  node_codec["Codec simulation<br/>[simulate_codec.py]"]
end

subgraph group_models["Detection models"]
  node_train["Feature ResNet<br/>[train.py]"]
  node_featmodel["Feature ResNet model<br/>[model.py]"]
  node_lfccmodel["LFCC ResNet model<br/>[model.py]"]
  node_aasistmain["AASIST training<br/>[main.py]"]
  node_aasistmodel["AASIST network<br/>[AASIST.py]"]
  node_wavmain["Wav2vec AASIST training<br/>[main.py]"]
  node_wavmodel["Wav2vec AASIST network<br/>[wav2vecAASIST.py]"]
  node_evaluation["Evaluation metrics<br/>[eval_metrics.py]"]
end

subgraph group_annotation["Metadata annotation"]
  node_popup["Annotation popup<br/>[popup.js]"]
  node_background["Extension background<br/>[background.js]"]
  node_firestore["Firestore client"]
end

node_researcher(("Researcher"))
node_audio["Downloaded FLAC"]
node_clips["Training clips"]
node_scores["Detection scores"]
node_chrome(("Chrome user"))
node_cloud[("Google Firestore")]
node_records["Annotation records"]

node_audio -->|"separates vocals"| node_separate
node_separate -->|"provides stems and VAD"| node_split
node_split -->|"writes clips"| node_clips
node_audio -.->|"simulates codec"| node_codec
node_clips -->|"trains on"| node_train
node_clips -->|"trains on"| node_aasistmain
node_clips -->|"trains on"| node_wavmain
node_train -->|"uses network"| node_featmodel
node_train -->|"evaluates with"| node_evaluation
node_evaluation -->|"produces scores"| node_scores
node_aasistmain -->|"loads architecture"| node_aasistmodel
node_aasistmain -.->|"evaluates with"| node_evaluation
node_wavmain -->|"loads architecture"| node_wavmodel
node_researcher -->|"supplies"| node_audio
node_chrome -->|"opens extension"| node_popup
node_popup -->|"sends messages"| node_background
node_background -->|"uses client"| node_firestore
node_firestore -->|"reads and writes"| node_cloud
node_cloud -->|"stores"| node_records

click node_separate "https://github.com/yongyizang/singfake/blob/main/dataset/separate.py"
click node_split "https://github.com/yongyizang/singfake/blob/main/dataset/split.py"
click node_codec "https://github.com/yongyizang/singfake/blob/main/dataset/simulate_codec.py"
click node_train "https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/train.py"
click node_featmodel "https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/model.py"
click node_lfccmodel "https://github.com/yongyizang/singfake/blob/main/models/lfcc%2Bresnet/model.py"
click node_aasistmain "https://github.com/yongyizang/singfake/blob/main/models/AASIST/main.py"
click node_aasistmodel "https://github.com/yongyizang/singfake/blob/main/models/AASIST/AASIST.py"
click node_wavmain "https://github.com/yongyizang/singfake/blob/main/models/wav2vec2%2BAASIST/main.py"
click node_wavmodel "https://github.com/yongyizang/singfake/blob/main/models/wav2vec2%2BAASIST/wav2vecAASIST.py"
click node_evaluation "https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/eval_metrics.py"
click node_popup "https://github.com/yongyizang/singfake/blob/main/annotation-tool/popup.js"
click node_background "https://github.com/yongyizang/singfake/blob/main/annotation-tool/background.js"
click node_firestore "https://github.com/yongyizang/singfake/blob/main/annotation-tool/firebase/firebase-firestore.js"

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_separate,node_split,node_codec,node_chrome toneBlue
class node_train,node_featmodel,node_lfccmodel,node_aasistmain,node_aasistmodel,node_wavmain,node_wavmodel,node_evaluation,node_cloud toneAmber
class node_popup,node_background,node_firestore toneMint
class node_researcher,node_audio,node_clips,node_scores,node_records toneIndigo
```

## Components

### Audio preparation

- [Vocal separation](https://github.com/yongyizang/singfake/blob/main/dataset/separate.py): `dataset/separate.py`
- [Clip generation](https://github.com/yongyizang/singfake/blob/main/dataset/split.py): `dataset/split.py`
- [Codec simulation](https://github.com/yongyizang/singfake/blob/main/dataset/simulate_codec.py): `dataset/simulate_codec.py`

### Detection models

- [Feature ResNet](https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/train.py): `models/feat+resnet/train.py`
- [Feature ResNet model](https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/model.py): `models/feat+resnet/model.py`
- [LFCC ResNet model](https://github.com/yongyizang/singfake/blob/main/models/lfcc%2Bresnet/model.py): `models/lfcc+resnet/model.py`
- [AASIST training](https://github.com/yongyizang/singfake/blob/main/models/AASIST/main.py): `models/AASIST/main.py`
- [AASIST network](https://github.com/yongyizang/singfake/blob/main/models/AASIST/AASIST.py): `models/AASIST/AASIST.py`
- [Wav2vec AASIST training](https://github.com/yongyizang/singfake/blob/main/models/wav2vec2%2BAASIST/main.py): `models/wav2vec2+AASIST/main.py`
- [Wav2vec AASIST network](https://github.com/yongyizang/singfake/blob/main/models/wav2vec2%2BAASIST/wav2vecAASIST.py): `models/wav2vec2+AASIST/wav2vecAASIST.py`
- [Evaluation metrics](https://github.com/yongyizang/singfake/blob/main/models/feat%2Bresnet/eval_metrics.py): `models/feat+resnet/eval_metrics.py`

### Metadata annotation

- [Annotation popup](https://github.com/yongyizang/singfake/blob/main/annotation-tool/popup.js): `annotation-tool/popup.js`
- [Extension background](https://github.com/yongyizang/singfake/blob/main/annotation-tool/background.js): `annotation-tool/background.js`
- [Firestore client](https://github.com/yongyizang/singfake/blob/main/annotation-tool/firebase/firebase-firestore.js): `annotation-tool/firebase/firebase-firestore.js`

### Other components

- **Researcher**
- **Downloaded FLAC**
- **Training clips**
- **Detection scores**
- **Chrome user**
- **Google Firestore**
- **Annotation records**

## Connections

- Downloaded FLAC → Vocal separation: separates vocals
- Vocal separation → Clip generation: provides stems and VAD
- Clip generation → Training clips: writes clips
- Downloaded FLAC → Codec simulation: simulates codec
- Training clips → Feature ResNet: trains on
- Training clips → AASIST training: trains on
- Training clips → Wav2vec AASIST training: trains on
- Feature ResNet → Feature ResNet model: uses network
- Feature ResNet → Evaluation metrics: evaluates with
- Evaluation metrics → Detection scores: produces scores
- AASIST training → AASIST network: loads architecture
- AASIST training → Evaluation metrics: evaluates with
- Wav2vec AASIST training → Wav2vec AASIST network: loads architecture
- Researcher → Downloaded FLAC: supplies
- Chrome user → Annotation popup: opens extension
- Annotation popup → Extension background: sends messages
- Extension background → Firestore client: uses client
- Firestore client → Google Firestore: reads and writes
- Google Firestore → Annotation records: stores