English | 日本語

Heartbeat BPM Analyzer

This tool is a heuristic based algorithm for phonocardiogram (PCG) Analysis. It analyzes audio recordings of heart sounds to detect heartbeats and graphs the Beats Per Minute (BPM) over time.

GUI Interface:

You only need to generate the heart rate graph but there are other options in case you need more information

🔗 Outputs Heart Rate Graph:

Spectrogram View:

This script includes a spectrogram view for debugging but it is very slow to generate

Configuration

All tunable parameters for the bpm_analysis.py engine are located in config.py The parameters are organized into logical categories for easier navigation and tuning.

• Multi-Format Audio Support: Accepts most common media files such as WAV, MP3, M4A, MOV, by converting them to .wav format for analysis.

Dependencies

To run this script, you will need Python and the following libraries:

• numpy, pandas, scipy, plotly, ttkbootstrap, pydub
• librosa (handles audio loading and resampling)
• soxr (improves resampling quality when used with librosa)
• matplotlib (used for spectrogram and plotting)
• kaleido (required for exporting Plotly graphs to PNG)
• PyWavelets (provides the pywt module used for wavelet denoising)

You will also need FFmpeg installed and accessible in your system's PATH for pydub to function correctly. Follow the installation instructions for your operating system from the official FFmpeg website.

On Windows, ensure you have Microsoft Visual C++ Redistributable Latest supported v14 (for Visual Studio 2017–2026).

Installation

1. Clone or download this repository, then open a terminal in the project directory.

2. (Recommended) Install all dependencies from the requirements file:

pip install -r requirements.txt

Alternatively, install only the core dependencies manually:

pip install numpy pandas scipy plotly ttkbootstrap pydub librosa soxr matplotlib PyWavelets kaleido

How to Run

From the project directory in a terminal:

python main.py

Or use the windowless launcher:

python main.pyw

Tip: You can double-click main.pyw to launch the app without opening a command prompt.

Extra Features:

Import the generated heart rate graph into Blender to easily calculate the change in bpm over time. Blender file and scripts are located in Blender BPM tool folder

Select the Geometry Nodes object and enter edit mode. This will allow you to calculate:

• Heart Rate Recovery (HRR)
• maximal rate of heart rate increase

You can also make any BPM/Time graph and export it out of blender using the Export graph data.py script

Import any CSV file with format: Time(Seconds), Beats Per Minute