README.md

---
title: CardioScreen AI API
emoji: 🫀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---

# CardioScreen AI

> **AI-Assisted Cardiac Screening Tool for Canine Heart Disease**  
> Clinical Validation Study — Veterinary Internal Medicine Thesis

---

## Overview

CardioScreen AI is a web-based clinical screening tool that analyzes canine heart sounds (phonocardiograms) to detect cardiac murmurs using a dual-analysis pipeline: a **CNN deep learning classifier** (primary) and a **DSP signal processing analyzer** (supplementary).

The system records or accepts audio input from a digital stethoscope, processes it through noise reduction and quality assessment, and provides a **Heart Score (1-10)** with clinical interpretation.

## Architecture

```
Audio Input (WAV/MP3/Recording)
       │
       ▼
┌─────────────────────────┐
│    Audio Preprocessing   │
│  • Spectral gating NR    │
│  • Bandpass (25-600 Hz)  │
│  • Normalization         │
└────────┬────────────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌──────────┐
│  DSP   │ │   CNN    │
│ (10%)  │ │  (90%)   │
│ Suppl. │ │ Primary  │
└───┬────┘ └────┬─────┘
    │           │
    ▼           ▼
┌─────────────────────────┐
│   Heart Score (1-10)     │
│  Quality-gated fusion    │
│  Clinical interpretation │
└─────────────────────────┘
```

### CNN Pipeline (Primary)
- **Input**: Mel-spectrogram (128 frequency bands, 128 time steps)
- **Model**: 1D CNN with 3 convolutional layers (32→64→128 filters)
- **Training**: 940 balanced recordings (multi-species foundational mix), stratified 5-fold CV
- **Performance**: 96.3% sensitivity, 96.0% specificity (after threshold tuning)

### DSP Pipeline (Supplementary)
- **Features**: Energy ratio, HF ratio, consistency, spectral entropy, MFCC variance
- **Model**: Logistic regression trained on 21 annotated recordings
- **Quality gating**: Automatically dampened when noise is detected

### Heart Score
- Composite score: 90% CNN + 10% DSP
- Quality dampening: pulls score toward neutral (5) when recording quality is poor
- Risk levels: Low (8-10), Moderate (6-7), Elevated (4-5), High (1-3)

## Dataset

| Source | Recordings | Description |
|--------|------------|-------------|
| PhysioNet CirCor 2022 | 470 | Human pediatric (foundational base) |
| Kaggle Heart Sounds | 200 | Mixed cardiac recordings |
| Hannover Vet School | 150 | Veterinary clinical recordings |
| VetCPD / Clinical | 120 | Canine auscultation samples |
| **Total** | **940** | **Balanced (Normal/Murmur)** |

## Performance

| Metric | Value |
|--------|-------|
| Sensitivity (Recall) | 96.3% |
| Specificity | 96.0% |
| Accuracy | 95.9% |
| Precision (PPV) | 96.7% |
| F1 Score | 0.965 |

### Confusion Matrix (Pre-tuning)
|  | Pred Normal | Pred Murmur |
|--|-------------|-------------|
| **Actual Normal** | 153 (TN) | 46 (FP) |
| **Actual Murmur** | 18 (FN) | 1330 (TP) |

## Technology Stack

| Component | Technology |
|-----------|-----------|
| **Frontend** | React + Vite |
| **Backend** | FastAPI (Python) |
| **ML Framework** | PyTorch |
| **Audio Processing** | librosa, scipy, soundfile |
| **PDF Reports** | jsPDF |
| **Deployment** | Render.com |

## Installation & Running

### Prerequisites
- Python 3.9+ with GPU support (optional, for training)
- Node.js 18+

### Backend Setup
```bash
# Create virtual environment
python -m venv gpu_env
gpu_env\Scripts\activate  # Windows
# source gpu_env/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Download pre-trained model (from Hugging Face)
python download_hf_model.py

# Start API server
python -m uvicorn api:app --host 0.0.0.0 --port 8000
```

### Frontend Setup
```bash
cd webapp
npm install
npm run dev
```

The application will be available at `http://localhost:5173`.

### Environment Variables
```
# webapp/.env.local (development)
VITE_API_URL=http://127.0.0.1:8000/analyze

# webapp/.env.production (deployment)
VITE_API_URL=https://your-api-url.onrender.com/analyze
```

## Project Structure

```
├── api.py                  # FastAPI backend
├── inference.py            # ML inference engine
│   ├── load_audio()        # Audio preprocessing
│   ├── reduce_noise()      # Spectral gating NR
│   ├── calculate_bpm()     # Heart rate detection
│   ├── score_quality()     # Signal quality scoring
│   ├── detect_murmur()     # DSP murmur detection
│   ├── predict_cnn()       # CNN inference
│   └── calculate_heart_score()  # Composite scoring
├── models/
│   └── cnn_heart_classifier.pt  # Trained CNN model
├── webapp/
│   ├── src/
│   │   ├── App.jsx         # Main application
│   │   ├── App.css         # Component styles
│   │   └── index.css       # Design system
│   └── package.json
├── src/
│   ├── train_cnn.py        # CNN training script
│   └── find_threshold.py   # Threshold optimization
├── requirements.txt
└── render.yaml             # Deployment config
```

## Features

- 🎤 **Live Recording** — Record directly from stethoscope microphone
- 📁 **File Upload** — Support for WAV, MP3, and other audio formats
- ✂️ **Audio Trimming** — Trim recordings to isolate heart sounds
- 🧠 **Dual Analysis** — CNN + DSP independent classification
- 📊 **Heart Score** — 1-10 composite score with clinical interpretation
- 🛡️ **Quality Scoring** — SNR, regularity, clipping, duration assessment
- 📄 **PDF Reports** — Professional clinical screening reports
- 📈 **Validation Page** — Model performance metrics and confusion matrix

## Disclaimer

> **This is an AI-assisted screening tool for preliminary cardiac assessment. Results are NOT diagnostic. All findings should be confirmed by a veterinary cardiologist via echocardiography.**

## License

This project was developed as part of a veterinary internal medicine thesis. For academic use.