ai-mitra/heartbeat-anomaly-detector

Heartbeat Anomaly Detector

A deep learning-based heart sound classification system that analyzes phonocardiogram (PCG) recordings to detect cardiac anomalies. This model combines AI-powered classification with rule-based analysis to provide comprehensive heart sound assessment.

Model Description

The Heartbeat Anomaly Detector is a CNN-based deep learning model designed for automated heart sound analysis. It processes audio recordings of heart sounds and classifies them into four categories while providing detailed cardiac metrics and risk assessments.

Key Features

• Multi-Class Classification: Identifies normal heart sounds, murmurs, extra heart sounds, and artifacts
• Hybrid Analysis: Combines deep learning predictions with rule-based clinical logic
• Real-time Processing: Fast inference suitable for clinical workflows
• Comprehensive Metrics: Provides heart rate, rhythm analysis, and risk assessment
• RESTful API: Easy integration via FastAPI endpoints

Model Architecture

Neural Network Design

The model uses a 4-layer Convolutional Neural Network (CNN) architecture:

Input: [1, 60000] - 30 seconds of audio at 2000 Hz sample rate

Layer 1: Conv1d(1→32) + BatchNorm + ReLU + MaxPool + Dropout(0.2)
Layer 2: Conv1d(32→64) + BatchNorm + ReLU + MaxPool + Dropout(0.2)
Layer 3: Conv1d(64→128) + BatchNorm + ReLU + MaxPool + Dropout(0.3)
Layer 4: Conv1d(128→256) + BatchNorm + ReLU + AdaptiveAvgPool + Dropout(0.3)

Fully Connected: 256 → 128 → 64 → 4 classes

Technical Specifications

• Input Format: Mono audio, 2000 Hz sample rate, 30-second duration
• Model Size: Approximately 10-20 MB
• Framework: PyTorch
• Inference Time: < 1 second per audio file
• Device Support: CPU and CUDA-enabled GPU

Classes

The model classifies heart sounds into four categories:

Class	Description	Clinical Significance
Normal	Regular heart sounds with clear S1/S2	Healthy cardiac function
Murmur	Abnormal whooshing sounds	May indicate valve disorders
Extra Heart Sounds	Additional sounds (S3, S4, clicks)	Possible heart failure or structural issues
Artifact	Poor signal quality or noise	Recording quality issue

Signal Processing Pipeline

Preprocessing Steps

1. Audio Loading: Load audio file at 2000 Hz sample rate
2. Median Filtering: Remove impulse noise
3. Bandpass Filtering: Extract 20-200 Hz range (primary heart sound frequencies)
4. Notch Filtering: Remove 50/60 Hz power line interference
5. Envelope Enhancement: Apply Hilbert transform for amplitude modulation
6. Normalization: RMS-based amplitude normalization
7. Smoothing: Savitzky-Golay filter for signal refinement

Feature Extraction

• Heart Rate Detection: BioSPPy or peak detection algorithms
• S1/S2 Peak Identification: First and second heart sound detection
• Rhythm Analysis: Heart rate variability and irregularity scoring
• Amplitude Analysis: S1/S2 amplitude ratios

Usage

Installation

pip install fastapi uvicorn torch librosa numpy scipy matplotlib biosppy

Quick Start

1. Download the Model

from huggingface_hub import hf_hub_download

model_path = hf_hub_download(
    repo_id="ai-mitra/heartbeat-anomaly-detector",
    filename="heartbeat-anomaly-detector-model.pt"
)

2. Run the API Server

# Start the FastAPI server
uvicorn inference:app --host 0.0.0.0 --port 8000

3. Analyze Heart Sounds

Using cURL:

curl "http://localhost:8000/hb?filename=sounds/Heart_Failure_Sound.mp3"

Using Python:

import requests

response = requests.get(
    "http://localhost:8000/hb",
    params={"filename": "sounds/Normal_Heart_Sound.mp3"}
)
result = response.json()

print(f"Classification: {result['classification']['result']}")
print(f"Confidence: {result['classification']['confidence_percentage']}")
print(f"Heart Rate: {result['heart_rate']['average_bpm']} BPM")

Using JavaScript (React/Frontend):

fetch('http://localhost:8000/hb?filename=sounds/Normal_Heart_Sound.mp3')
  .then(response => response.json())
  .then(data => {
    console.log('Classification:', data.classification.result);
    console.log('Confidence:', data.classification.confidence_percentage);
    console.log('Heart Rate:', data.heart_rate.average_bpm, 'BPM');
  });

API Endpoints

GET /hb

Analyze a heart sound audio file.

Parameters:

• filename (string, required): Path to the audio file

Response:

{
  "status": "OK",
  "analysis_info": {
    "target_file": "Normal_Heart_Sound",
    "analysis_timestamp": "2026-01-13T10:30:00",
    "analysis_mode": "Hybrid (AI + Rule-Based)",
    "plot_filename": "Normal_Heart_Sound_analysis_20260113_103000.png",
    "plot_path": "/plot/Normal_Heart_Sound_analysis_20260113_103000.png"
  },
  "ai_prediction": {
    "predicted_class": "normal",
    "confidence": 0.9245,
    "probabilities": {
      "normal": 0.9245,
      "murmur": 0.0432,
      "extrahs": 0.0221,
      "artifact": 0.0102
    }
  },
  "classification": {
    "result": "Normal Heart Sounds",
    "confidence": 0.9245,
    "confidence_percentage": "92.5%"
  },
  "heart_rate": {
    "average_bpm": 75.3,
    "hr_mean": 75.3,
    "hr_std": 3.2,
    "hr_min": 70.1,
    "hr_max": 81.5,
    "irregularity_score": 0.042
  },
  "heart_sounds": {
    "num_s1": 38,
    "num_s2": 37,
    "s1_peaks": [245, 1523, 2801, ...],
    "s2_peaks": [876, 2154, 3432, ...],
    "s1_s2_ratio": 1.027
  },
  "detailed_findings": [
    {
      "condition": "AI Classification: Normal",
      "description": "Deep learning model prediction with 92.5% confidence",
      "severity": "Low",
      "recommendation": "AI Model: Normal detected",
      "source": "AI Model"
    }
  ],
  "recommendations": [
    "Analysis Method: Hybrid (AI + Rule-Based)",
    "AI-Rule Agreement: High"
  ]
}

GET /health

Check API health status.

Response:

{
  "status": "OK",
  "model_loaded": true,
  "biosppy_available": true,
  "timestamp": "2026-01-13T10:30:00"
}

GET /plot/{filename}

Retrieve generated analysis plot image.

Response: PNG image file

Clinical Features

Arrhythmia Detection

The system detects various cardiac rhythm abnormalities:

• Tachycardia: Heart rate > 100 BPM
• Severe Tachycardia: Heart rate > 150 BPM
• Bradycardia: Heart rate < 50 BPM
• Severe Bradycardia: Heart rate < 40 BPM
• Irregular Rhythm: High heart rate variability (possible atrial fibrillation)

Heart Attack Risk Assessment

Multi-factor risk scoring based on:

• Heart rate extremes (tachycardia/bradycardia)
• Rhythm irregularity
• Multiple high-severity findings
• Combined risk factors

Risk Levels:

• HIGH: Risk score ≥ 6 - Immediate medical attention required
• MODERATE: Risk score 3-5 - Urgent cardiology consultation needed
• LOW-MODERATE: Risk score 1-2 - Follow-up recommended
• LOW: Risk score 0 - Continue preventive care

Training Details

Dataset

The model was trained on a custom dataset of heart sound recordings including:

• Normal heart sounds
• Murmurs (various types)
• Extra heart sounds (S3, S4, clicks)
• Artifacts and noise

Training Configuration

• Sample Rate: 2000 Hz
• Audio Duration: 30 seconds
• Batch Normalization: Applied in all convolutional layers
• Dropout Rates: 0.2-0.5 for regularization
• Loss Function: Cross-entropy loss
• Optimizer: Adam (typical for CNN training)

Performance Baselines

Training statistics for different conditions:

Condition	Avg Heart Rate	Irregularity Score	S1/S2 Ratio
Normal	104.5 ± 7.6 BPM	0.317 ± 0.074	1.171 ± 0.244
Murmur	87.5 ± 27.5 BPM	0.185 ± 0.150	0.733 ± 0.092
Extra HS	82.3 ± 9.2 BPM	0.570 ± 0.068	0.836 ± 0.151

Limitations and Disclaimers

Important Medical Disclaimer

• This is an automated analysis tool for educational and research purposes only
• Results should NOT be used for medical diagnosis or treatment decisions
• Always consult qualified healthcare professionals for medical concerns
• The analysis may produce false positives/negatives
• Professional medical evaluation is required for all cardiac concerns

Technical Limitations

1. Audio Quality Dependent: Requires clear recordings without excessive noise
2. Limited Pathology Coverage: Trained on specific condition types
3. No Real-time Monitoring: Designed for recorded audio analysis
4. Context Required: Best used as part of comprehensive cardiac assessment
5. Regional Variations: May not account for all demographic differences

Use Cases

Appropriate Use

• Educational: Medical training and learning
• Research: Cardiac audio analysis studies
• Screening: Initial triage in low-resource settings
• Monitoring: Tracking changes over time with physician oversight
• Development: Building advanced cardiac diagnostic systems

Inappropriate Use

• Primary diagnostic tool without physician review
• Emergency medical decision-making
• Replacement for echocardiography or ECG
• Self-diagnosis or self-treatment

Model Files

• heartbeat-anomaly-detector-model.pt - PyTorch model weights (main file)
• inference.py - FastAPI server with inference code
• requirements.txt - Python dependencies

Dependencies

fastapi>=0.68.0
uvicorn>=0.15.0
torch>=1.9.0
librosa>=0.9.0
numpy>=1.19.0
scipy>=1.7.0
matplotlib>=3.3.0
biosppy>=0.8.0 (optional but recommended)

Citation

If you use this model in your research, please cite:

@misc{heartbeat-anomaly-detector,
  author = {AI Mitra},
  title = {Heartbeat Anomaly Detector: CNN-based Heart Sound Classification},
  year = {2026},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/ai-mitra/heartbeat-anomaly-detector}}
}

License

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

Contact and Support

For questions, issues, or contributions:

• Hugging Face: https://huggingface.co/ai-mitra/heartbeat-anomaly-detector
• Issues: Report bugs or request features via the repository issues page

Acknowledgments

• BioSPPy library for cardiac signal processing
• PyTorch framework for deep learning
• Medical professionals who provided domain expertise

Version History

• v2.0.0 (2026-01-13): Initial release with hybrid AI + rule-based analysis
  • 4-class CNN classification
  • Heart rate and rhythm analysis
  • Risk assessment module
  • FastAPI integration with CORS support

---

Remember: This tool is for research and educational purposes. Always seek professional medical advice for health concerns.