examples/README.md

# Deepfake Hunter - Examples

This directory contains example files for testing and demonstration purposes.

## Files

### analysis_report.json
Example JSON report from video analysis showing:
- Overall deepfake detection result
- Frame-by-frame scores
- Temporal consistency analysis
- Physiological signal detection
- Detailed breakdown of all detection methods

### Sample Videos (Not Included)

For testing, you can use these publicly available datasets:

#### Real Videos
- Download from: [YouTube-8M](https://research.google.com/youtube8m/)
- Or use your own webcam recordings

#### Deepfake Videos
- **FaceForensics++**: https://github.com/ondyari/FaceForensics
  - Download sample videos for testing
  - Includes various manipulation methods (Deepfakes, Face2Face, FaceSwap, NeuralTextures)

- **Celeb-DF**: https://github.com/yuezunli/celeb-deepfakeforensics
  - High-quality celebrity deepfakes
  - More challenging test cases

- **DFDC Preview**: https://ai.facebook.com/datasets/dfdc/
  - Facebook Deepfake Detection Challenge dataset
  - Diverse range of manipulation techniques

## Usage Examples

### 1. Analyze Sample Image

```python
from deepfake_detector import DeepfakeDetector
import cv2

# Initialize detector
detector = DeepfakeDetector(use_gpu=True)

# Analyze image
image = cv2.imread('path/to/image.jpg')
image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

result = detector.detect_image(image)
print(f"Is deepfake: {result.is_deepfake}")
print(f"Confidence: {result.confidence:.2%}")
print(f"Explanation: {result.explanation}")
```

### 2. Analyze Sample Video

```python
from deepfake_detector import DeepfakeDetector
from video_analyzer import VideoAnalyzer

# Initialize
detector = DeepfakeDetector(use_gpu=True)
analyzer = VideoAnalyzer(detector, sample_rate=2)

# Analyze video
result = analyzer.analyze_video(
    'path/to/video.mp4',
    export_timeline=True,
    export_report=True,
    output_dir='./results'
)

print(f"Video is deepfake: {result.is_deepfake}")
print(f"Confidence: {result.confidence:.2%}")
print(f"Suspect frames: {len(result.suspect_frames)}")
```

### 3. Using the API

```bash
# Start the API server
python api_server.py

# Analyze image via API
curl -X POST "http://localhost:8001/analyze/image" \
  -H "X-API-Key: your-secret-key" \
  -F "file=@path/to/image.jpg" \
  -F "context=general"

# Analyze video via API
curl -X POST "http://localhost:8001/analyze/video" \
  -H "X-API-Key: your-secret-key" \
  -F "file=@path/to/video.mp4" \
  -F "context=general" \
  -F "sample_rate=2"
```

### 4. Using the Web Interface

```bash
# Start Gradio app
python app.py

# Open browser to http://localhost:7860
# Upload images/videos via the web interface
```

## Creating Your Own Test Cases

### Record Authentic Video
```bash
# Using webcam (Linux)
ffmpeg -f v4l2 -i /dev/video0 -t 10 real_video.mp4

# Using webcam (macOS)
ffmpeg -f avfoundation -i "0" -t 10 real_video.mp4

# Using webcam (Windows)
ffmpeg -f dshow -i video="Your Webcam Name" -t 10 real_video.mp4
```

### Test Different Scenarios

1. **Good Lighting**: Well-lit face, clear features
2. **Poor Lighting**: Test robustness to lighting conditions
3. **Multiple Faces**: Test multi-face detection
4. **Profile View**: Test with non-frontal faces
5. **Occlusions**: Test with glasses, masks, etc.
6. **Video Quality**: Test with different resolutions and compression levels

## Expected Results

### Real Videos
- Confidence: 0.0 - 0.3 (low score = likely real)
- Physiological signals detected (if sufficient frames)
- Natural temporal consistency
- Low artifact scores

### Deepfake Videos
- Confidence: 0.7 - 1.0 (high score = likely fake)
- No physiological signals or irregular patterns
- Temporal inconsistencies
- High artifact scores (blending, GAN fingerprints)

## Benchmarking

To benchmark the detector on standard datasets:

```bash
# Download FaceForensics++ test set
# Then run benchmark
python benchmark.py \
  --dataset faceforensics \
  --data-dir /path/to/faceforensics \
  --output results/benchmark.json
```

## Troubleshooting

### Low Accuracy
- Check GPU is being used: `detector.device` should be "cuda"
- Ensure sufficient video length (>5 seconds for physiological signals)
- Try adjusting sensitivity: `detector.sensitivity = "high"`

### Slow Processing
- Reduce video sample rate: `analyzer.sample_rate = 4`
- Use GPU acceleration
- Process at lower resolution
- Limit max frames: `max_frames=300`

### False Positives
- Lower sensitivity: `detector.sensitivity = "low"`
- Increase thresholds: `detector.set_thresholds({'ensemble': 0.8})`
- Check for compression artifacts in original video

## Contributing Examples

Have interesting test cases? Contribute them!

1. Create anonymized examples
2. Document expected results
3. Submit PR with examples and documentation

## License

Example files are provided under CC0 (public domain) where possible.
Some referenced datasets have their own licenses - check before use.