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.