DeepShield

Robust audio deepfake detection using CNN-BiLSTM, spectral-temporal modeling, explainability, and production-ready inference.

DeepShield is a research and engineering project for detecting bonafide speech versus spoofed or AI-generated speech. The project is built around reproducible evaluation, leakage control, robustness testing, and practical inference performance rather than a single headline metric.

Current status

Phase 1 establishes the repository and engineering foundation. Dataset ingestion, feature extraction, model training, evaluation, and application code are intentionally not implemented yet.

The primary research dataset selected in Phase 0 is ASVspoof 5 Track 1. Official train, development, and evaluation partitions will be preserved as provided. Evaluation data will not be used for tuning, calibration, checkpoint selection, or preprocessing statistics.

Research plan

The minimum model comparison is:

1. MFCC + Logistic Regression
2. CNN
3. BiLSTM
4. CNN-LSTM
5. CNN-BiLSTM

CNN-BiLSTM is the main research architecture, not a predetermined production winner. Production selection will consider detection quality, generalization, robustness, preprocessing and inference latency, model size, and memory usage.

Planned deep-learning input pipeline:

audio -> preprocessing -> fixed-duration windows -> log-mel spectrogram -> model -> probability

The initial audio specification is 16 kHz mono, 4-second windows, 25 ms STFT windows, 10 ms hop, FFT size 512, 128 Mel bands, 0-8 kHz, and log/dB scaling. MFCCs are reserved for the classical baseline and relevant ablations.

Repository layout

.github/workflows/    Continuous integration
configs/              Experiment and runtime configuration
src/deepshield/       Python package
  data/               Dataset and protocol handling
  features/           Audio preprocessing and features
  models/             Model definitions
  training/           Training pipeline
  evaluation/         Metrics and evaluation
  inference/          Production inference path
tests/                 Automated tests
data/                  Local dataset workspace; raw data is not versioned
models/                Local checkpoints and exported models; not versioned
results/               Local experiment outputs; not versioned
notebooks/             Focused analysis notebooks
docs/                  Project documentation
api/                   FastAPI application
frontend/              React application
docker/                Container configuration

Directories are added to version control when they contain real project files. Empty placeholder modules are avoided.

Development

Python 3.12 is the primary target.

python -m venv .venv

Activate the environment, then install the development dependencies:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Run the checks used by CI:

ruff check .
ruff format --check .
pytest

Data and artifacts

Raw ASVspoof data, audio dumps, generated features, checkpoints, experiment outputs, credentials, and local environment files are excluded from Git. Dataset archives and large training artifacts belong in external storage such as Google Drive, not in this repository.

Production inference will not depend on ASVspoof or Google Drive. The deployed path is expected to load the selected model once at API startup and process requests as:

audio -> preprocessing -> loaded model -> prediction

License

MIT License. See LICENSE.