# allen23antony/audioshield-forensics architecture

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

- Interactive diagram: https://gitdiagram.com/allen23antony/audioshield-forensics
- Repository: https://github.com/allen23antony/audioshield-forensics

## Overview

AudioShield is an audio deepfake detection and forensic application. A browser or API client submits audio; the pipeline runs three model predictions plus metadata, signal, and supplementary segment analysis, then fuses findings and produces JSON artifacts and a PDF. The graph also preserves the AASIST research/training layer and the signal-analysis substeps. Relationships reflect the README and shown imports/calls; several subsystems are represented by their exact directory because their implementation was not sampled.

Main entry points: [`src/inference/pipeline.py`](https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/pipeline.py) (Analysis pipeline), [`src/inference/predict.py`](https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/predict.py) (Ensemble predictions), [`src/metadata/extractor.py`](https://github.com/allen23antony/audioshield-forensics/blob/main/src/metadata/extractor.py) (Metadata extraction), [`src/forensics/signal.py`](https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/signal.py) (Signal analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application flow"]
  node_api["Upload API<br/>[main.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
end

subgraph group_models["Model inference"]
  node_audio["Audio preprocessing"]
  node_features["Feature extraction"]
  node_predict["Ensemble predictions<br/>[predict.py]"]
  node_cnn["CNN training/model<br/>[train_cnn_final.py]"]
end

subgraph group_forensics["Forensic analysis"]
  node_metadataextract["Metadata extraction<br/>[extractor.py]"]
  node_metadataanalysis["Metadata checks<br/>[analyzer.py]"]
  node_signal["Signal analysis<br/>[signal.py]"]
  node_temporal["Temporal analysis<br/>[temporal.py]"]
  node_visualize["Signal visualizations<br/>[visualize.py]"]
  node_segments["Segment scoring<br/>[segment.py]"]
  node_hashing["Integrity hashes<br/>[hashing.py]"]
end

subgraph group_evidence["Evidence and reporting"]
  node_fusion["Evidence fusion<br/>[combine.py]"]
  node_fusionreport["Fusion reports<br/>[report.py]"]
  node_save["Prediction artifacts<br/>[save.py]"]
  node_pdf["Forensic PDF<br/>[generator.py]"]
end

subgraph group_research["AASIST research"]
  node_aasistmodel["AASIST model<br/>[model.py]"]
  node_dataset["AASIST dataset<br/>[dataset.py]"]
  node_config["AASIST configuration<br/>[config.py]"]
  node_aasisttrain["AASIST training<br/>[train_balanced.py]"]
end

node_browser(("Browser user"))
node_ffmpeg["FFmpeg"]
node_probe["FFprobe / ExifTool"]

node_browser -->|"uploads audio"| node_api
node_api -->|"invokes"| node_pipeline
node_pipeline -->|"requests predictions"| node_predict
node_predict -->|"preprocesses audio"| node_audio
node_predict -->|"extracts features"| node_features
node_predict -->|"loads CNN"| node_cnn
node_predict -->|"runs AASIST"| node_aasistmodel
node_pipeline -->|"saves predictions"| node_save
node_pipeline -->|"extracts metadata"| node_metadataextract
node_pipeline -->|"checks metadata"| node_metadataanalysis
node_metadataextract -->|"computes hashes"| node_hashing
node_metadataextract -.->|"queries metadata"| node_probe
node_pipeline -->|"analyzes signal"| node_signal
node_pipeline -->|"scores segments"| node_segments
node_segments -->|"preprocesses audio"| node_audio
node_segments -->|"reuses model inference"| node_predict
node_signal -->|"uses temporal checks"| node_temporal
node_signal -->|"produces plots"| node_visualize
node_pipeline -->|"combines evidence"| node_fusion
node_pipeline -->|"writes fusion report"| node_fusionreport
node_pipeline -->|"generates PDF"| node_pdf
node_audio -.->|"decodes audio"| node_ffmpeg
node_aasisttrain -->|"loads examples"| node_dataset
node_aasisttrain -->|"trains model"| node_aasistmodel
node_dataset -->|"uses split settings"| node_config

click node_api "https://github.com/allen23antony/audioshield-forensics/blob/main/src/api/main.py"
click node_pipeline "https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/pipeline.py"
click node_audio "https://github.com/allen23antony/audioshield-forensics/blob/main/src/audio_preprocessing.py"
click node_features "https://github.com/allen23antony/audioshield-forensics/blob/main/src/feature_extraction.py"
click node_predict "https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/predict.py"
click node_cnn "https://github.com/allen23antony/audioshield-forensics/blob/main/src/train_cnn_final.py"
click node_aasistmodel "https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/model.py"
click node_dataset "https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/dataset.py"
click node_config "https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/config.py"
click node_aasisttrain "https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/train_balanced.py"
click node_metadataextract "https://github.com/allen23antony/audioshield-forensics/blob/main/src/metadata/extractor.py"
click node_metadataanalysis "https://github.com/allen23antony/audioshield-forensics/blob/main/src/metadata/analyzer.py"
click node_signal "https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/signal.py"
click node_temporal "https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/temporal.py"
click node_visualize "https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/visualize.py"
click node_segments "https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/segment.py"
click node_fusion "https://github.com/allen23antony/audioshield-forensics/blob/main/src/fusion/combine.py"
click node_fusionreport "https://github.com/allen23antony/audioshield-forensics/blob/main/src/fusion/report.py"
click node_save "https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/save.py"
click node_pdf "https://github.com/allen23antony/audioshield-forensics/blob/main/src/report/generator.py"
click node_hashing "https://github.com/allen23antony/audioshield-forensics/blob/main/src/utils/hashing.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_api,node_pipeline,node_browser toneBlue
class node_audio,node_features,node_predict,node_cnn toneAmber
class node_metadataextract,node_metadataanalysis,node_signal,node_temporal,node_visualize,node_segments,node_hashing toneMint
class node_fusion,node_fusionreport,node_save,node_pdf toneRose
class node_aasistmodel,node_dataset,node_config,node_aasisttrain,node_ffmpeg,node_probe toneIndigo
```

## Components

### Application flow

- [Upload API](https://github.com/allen23antony/audioshield-forensics/blob/main/src/api/main.py): `src/api/main.py`
- [Analysis pipeline](https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/pipeline.py): `src/inference/pipeline.py`

### Model inference

- [Audio preprocessing](https://github.com/allen23antony/audioshield-forensics/blob/main/src/audio_preprocessing.py): `src/audio_preprocessing.py`
- [Feature extraction](https://github.com/allen23antony/audioshield-forensics/blob/main/src/feature_extraction.py): `src/feature_extraction.py`
- [Ensemble predictions](https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/predict.py): `src/inference/predict.py`
- [CNN training/model](https://github.com/allen23antony/audioshield-forensics/blob/main/src/train_cnn_final.py): `src/train_cnn_final.py`

### Forensic analysis

- [Metadata extraction](https://github.com/allen23antony/audioshield-forensics/blob/main/src/metadata/extractor.py): `src/metadata/extractor.py`
- [Metadata checks](https://github.com/allen23antony/audioshield-forensics/blob/main/src/metadata/analyzer.py): `src/metadata/analyzer.py`
- [Signal analysis](https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/signal.py): `src/forensics/signal.py`
- [Temporal analysis](https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/temporal.py): `src/forensics/temporal.py`
- [Signal visualizations](https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/visualize.py): `src/forensics/visualize.py`
- [Segment scoring](https://github.com/allen23antony/audioshield-forensics/blob/main/src/forensics/segment.py): `src/forensics/segment.py`
- [Integrity hashes](https://github.com/allen23antony/audioshield-forensics/blob/main/src/utils/hashing.py): `src/utils/hashing.py`

### Evidence and reporting

- [Evidence fusion](https://github.com/allen23antony/audioshield-forensics/blob/main/src/fusion/combine.py): `src/fusion/combine.py`
- [Fusion reports](https://github.com/allen23antony/audioshield-forensics/blob/main/src/fusion/report.py): `src/fusion/report.py`
- [Prediction artifacts](https://github.com/allen23antony/audioshield-forensics/blob/main/src/inference/save.py): `src/inference/save.py`
- [Forensic PDF](https://github.com/allen23antony/audioshield-forensics/blob/main/src/report/generator.py): `src/report/generator.py`

### AASIST research

- [AASIST model](https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/model.py): `src/aasist/model.py`
- [AASIST dataset](https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/dataset.py): `src/aasist/dataset.py`
- [AASIST configuration](https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/config.py): `src/aasist/config.py`
- [AASIST training](https://github.com/allen23antony/audioshield-forensics/blob/main/src/aasist/train_balanced.py): `src/aasist/train_balanced.py`

### Other components

- **Browser user**
- **FFmpeg**
- **FFprobe / ExifTool**

## Connections

- Browser user → Upload API: uploads audio (evidence: `README.md`)
- Upload API → Analysis pipeline: invokes (evidence: `src/api/main.py`)
- Analysis pipeline → Ensemble predictions: requests predictions (evidence: `src/inference/pipeline.py`)
- Ensemble predictions → Audio preprocessing: preprocesses audio (evidence: `src/inference/predict.py`)
- Ensemble predictions → Feature extraction: extracts features (evidence: `src/inference/predict.py`)
- Ensemble predictions → CNN training/model: loads CNN (evidence: `src/inference/predict.py`)
- Ensemble predictions → AASIST model: runs AASIST (evidence: `src/inference/predict.py`)
- Analysis pipeline → Prediction artifacts: saves predictions (evidence: `src/inference/pipeline.py`)
- Analysis pipeline → Metadata extraction: extracts metadata (evidence: `src/inference/pipeline.py`)
- Analysis pipeline → Metadata checks: checks metadata (evidence: `src/inference/pipeline.py`)
- Metadata extraction → Integrity hashes: computes hashes (evidence: `src/metadata/extractor.py`)
- Metadata extraction → FFprobe / ExifTool: queries metadata (evidence: `README.md`)
- Analysis pipeline → Signal analysis: analyzes signal (evidence: `src/inference/pipeline.py`)
- Analysis pipeline → Segment scoring: scores segments (evidence: `src/inference/pipeline.py`)
- Segment scoring → Audio preprocessing: preprocesses audio (evidence: `src/forensics/segment.py`)
- Segment scoring → Ensemble predictions: reuses model inference (evidence: `src/forensics/segment.py`)
- Signal analysis → Temporal analysis: uses temporal checks (evidence: `src/forensics/analyze.py`)
- Signal analysis → Signal visualizations: produces plots (evidence: `src/forensics/analyze.py`)
- Analysis pipeline → Evidence fusion: combines evidence (evidence: `src/inference/pipeline.py`)
- Analysis pipeline → Fusion reports: writes fusion report (evidence: `src/inference/pipeline.py`)
- Analysis pipeline → Forensic PDF: generates PDF (evidence: `src/inference/pipeline.py`)
- Audio preprocessing → FFmpeg: decodes audio (evidence: `README.md`)
- AASIST training → AASIST dataset: loads examples (evidence: `src/aasist/train_balanced.py`)
- AASIST training → AASIST model: trains model (evidence: `src/aasist/train_balanced.py`)
- AASIST dataset → AASIST configuration: uses split settings (evidence: `src/aasist/dataset.py`)
