TruthLens: AI Fake Image & Video Detector

Deep-learning powered detector for AI-generated images and videos.
Identifies content from DALL·E, Midjourney, Stable Diffusion, Sora, and deepfake pipelines.

---

Table of Contents

1. Project Overview
2. Architecture
3. Installation
4. Dataset Setup
5. Training
6. Evaluation & Grad-CAM
7. Inference CLI
8. Web UI
9. Performance Targets
10. Model Comparison
11. Security Considerations
12. License
13. References

---

Project Overview

This project provides a production-ready pipeline to detect whether an image or short video clip was created by a human or generated by an AI system. It operates in two domains simultaneously:

Domain	Signal	Module
Spatial (RGB)	Pixel-level semantic + texture artefacts	EfficientNet-B4 / Xception backbone
Frequency (FFT)	Unnatural spectral peaks from GAN upsampling	fft_features.py + DualStreamDetector

A DualStreamDetector fuses both branches; an EnsembleDetector averages multiple models for maximum robustness.

---

Architecture

Input Image (380 × 380 × 3)
       │
       ├──────────────────────────────────┐
       │                                  │
  ┌────▼──────────┐               ┌───────▼────────┐
  │ EfficientNet  │               │  FFT Branch    │
  │  -B4 (RGB)    │               │  (1×H×W mag.)  │
  └────┬──────────┘               └───────┬────────┘
       │  1792-dim feature                │  256-dim feature
       └────────────┬─────────────────────┘
                    │  Concatenate (2048-dim)
             ┌──────▼──────┐
             │  MLP Head   │
             │  BN → Drop  │
             │ → 512 → 2   │
             └──────┬──────┘
                 Logits
          [P(real), P(fake)]

---

Installation

# 1. Clone the repository
git clone https://github.com/YOUR_USERNAME/TruthLens.git
cd TruthLens

# 2. Create a virtual environment
python -m venv venv

# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

GPU note: If you have an NVIDIA GPU, replace the torch line in
requirements.txt with the CUDA wheel matching your driver:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

---

Dataset Setup

This project uses CIFAKE — 120,000 images (60k real from CIFAR-10, 60k AI-generated with Stable Diffusion).

Step 1 — Get Kaggle credentials

1. Visit kaggle.com/account
2. Click Create New API Token → downloads kaggle.json
3. Place it at ~/.kaggle/kaggle.json
4. On Linux/macOS: chmod 600 ~/.kaggle/kaggle.json

Step 2 — Run the setup script

python setup_data.py
# Optional: specify a different destination
python setup_data.py --dest_dir /path/to/data

After completion, the directory layout will be:

data/
├── train/
│   ├── real/    # 50,000 images
│   └── fake/    # 50,000 images
└── val/
    ├── real/    # 10,000 images
    └── fake/    # 10,000 images

---

Training

# Quick start — EfficientNet-B4 for 30 epochs
python src/train.py \
    --data_dir    data \
    --model       efficientnet \
    --epochs      30 \
    --batch_size  32 \
    --lr          3e-4 \
    --warmup      3 \
    --patience    7 \
    --output_dir  checkpoints

# Train the dual-stream (RGB + FFT) model
python src/train.py \
    --data_dir  data \
    --model     dual_stream \
    --epochs    40 \
    --batch_size 24

# Train Xception
python src/train.py \
    --data_dir  data \
    --model     xception \
    --epochs    30

CLI Flags Reference

Flag	Default	Description
--data_dir	data	Root data directory
--model	efficientnet	Architecture: efficientnet, xception, dual_stream, ensemble
--epochs	30	Total training epochs
--batch_size	32	Mini-batch size
--lr	3e-4	Peak learning rate (after warm-up)
--warmup	3	Linear warm-up epochs
--patience	7	Early stopping patience
--output_dir	checkpoints	Checkpoint + log destination
--num_workers	4	DataLoader worker threads

Training artefacts:

• checkpoints/best_model.pth — best validation checkpoint
• checkpoints/training_log.csv — epoch-by-epoch metrics

---

Evaluation & Grad-CAM

# Evaluate on the validation set
python src/evaluate.py \
    --checkpoint  checkpoints/best_model.pth \
    --data_dir    data \
    --output_dir  eval_results

# Output:
#   eval_results/confusion_matrix.png
#   eval_results/roc_curve.png
#   prints classification_report + AUC

# Grad-CAM visualisation for a single image
python src/evaluate.py \
    --checkpoint   checkpoints/best_model.pth \
    --data_dir     data \
    --gradcam_img  path/to/suspicious_image.jpg \
    --output_dir   eval_results

# Output: eval_results/gradcam_overlay.png

---

Inference CLI

# Image
python src/predict.py image.jpg \
    --checkpoint checkpoints/best_model.pth \
    --threshold  0.5

# Video
python src/predict.py video.mp4 \
    --checkpoint  checkpoints/best_model.pth \
    --threshold   0.45 \
    --every_n     5 \
    --max_frames  128

# FFT visualisation only (no model needed)
python src/fft_features.py --image image.jpg --output fft_spectrum.png

Example output:

─────────────────────────────────────────────
  VERDICT : FAKE
  Real probability : 4.2%
  Fake probability : 95.8%
  Confidence       : 95.8%
─────────────────────────────────────────────

---

Web UI

# Launch on localhost:7860
python app.py

# Custom checkpoint + public share link
python app.py \
    --checkpoint checkpoints/best_model.pth \
    --port 7860 \
    --share

Open http://localhost:7860 in your browser.

Image tab — upload any image → see real/fake probabilities, FFT spectrum, and verdict card.
Video tab — upload a clip → see frame-level probability chart and overall verdict.

---

Performance Targets

Metric	Target	Notes
Accuracy (val)	≥ 95%	On CIFAKE validation set
AUC-ROC	≥ 0.98	Area under the ROC curve
Inference speed	< 100ms/img	Single image on GPU
False Positive Rate	< 5%	Real images classified as fake

---

Model Comparison

Model	Params	Val Accuracy*	AUC-ROC*	Speed (GPU)
EfficientNet-B4	19M	~96–97%	~0.990	~30ms
Xception	23M	~95–96%	~0.988	~35ms
DualStream (RGB+FFT)	20M	~97–98%	~0.993	~40ms
Ensemble (Eff+Xc)	42M	~98%	~0.995	~65ms

*Approximate targets based on published results on CIFAKE.
Actual numbers depend on hardware, training duration, and augmentation settings.

---

Security Considerations

This project involves handling user-uploaded files and loading pre-trained model weights, which have security implications.

• Model Checkpoints (.pth files): Loading model weights with torch.load can be risky if the source is untrusted, as it may execute arbitrary code. This project has been updated to use torch.load(..., weights_only=True), which is a safer method that prevents arbitrary code execution. Always ensure you are loading checkpoint files that you have trained yourself or that come from a trusted source.
• File Processing: The application processes images and videos using libraries like OpenCV and Pillow. Malformed files could potentially exploit vulnerabilities in these underlying libraries. It is recommended to run the application in a containerized environment (e.g., Docker) to isolate it from the host system, especially when exposing it to the internet.
• Gradio Web UI: When launching the Gradio app with --share, your local server is exposed to the public internet via a tunnel. Be aware of the risks associated with exposing local services.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

References

1. FaceForensics++ — Rössler et al. (2019) — Benchmark for face manipulation detection.
   https://arxiv.org/abs/1901.08971
2. Detecting Fake Images in the Wild (CNNDetect) — Wang et al. (2020)
   https://arxiv.org/abs/1912.11035
3. CIFAKE Dataset — Bird & Lotfi (2023)
   https://arxiv.org/abs/2303.14126
   Kaggle: https://www.kaggle.com/datasets/birdy654/cifake-real-and-ai-generated-synthetic-images
4. EfficientNet — Tan & Le (2019)
   https://arxiv.org/abs/1905.11946
5. Grad-CAM — Selvaraju et al. (2017)
   https://arxiv.org/abs/1610.02391
6. Xception — Chollet (2017) — Used for deepfake detection (FaceForensics++ baseline)
   https://arxiv.org/abs/1610.02357
7. Towards Universal Fake Image Detection Exploiting Diffusion Models — Ojha et al. (2023)
   https://arxiv.org/abs/2306.10719

---

Project Structure

.
├── app.py               # Gradio web UI
├── setup_data.py        # Download & organise CIFAKE
├── requirements.txt
├── .gitignore
├── README.md
├── src/
│   ├── dataset.py       # DataLoader + augmentations
│   ├── model.py         # EfficientNet, Xception, DualStream, Ensemble
│   ├── fft_features.py  # Frequency-domain feature extraction
│   ├── train.py         # Training loop with AMP + scheduler
│   ├── evaluate.py      # Metrics, Grad-CAM
│   ├── predict.py       # Inference CLI
│   └── video_utils.py   # Frame extraction + video prediction
├── checkpoints/         # Saved model weights (git-ignored)
└── data/                # Dataset (git-ignored)
    ├── train/
    │   ├── real/
    │   └── fake/
    └── val/
        ├── real/
        └── fake/

---

Full Pipeline End-to-End

# 1. Install dependencies
pip install -r requirements.txt

# 2. Download dataset
python setup_data.py

# 3. Train
python src/train.py --data_dir data --model efficientnet --epochs 30

# 4. Evaluate
python src/evaluate.py --checkpoint checkpoints/best_model.pth --data_dir data --output_dir eval_results

# 5. Predict a single image
python src/predict.py test_image.jpg --checkpoint checkpoints/best_model.pth

# 6. Launch Web UI
python app.py

---

Made with ❤️ using PyTorch, EfficientNet-B4, and Gradio