Overview
The Synheart Emotion Python SDK provides emotion inference from biosignals for research, backend services, and data analysis applications. Supported Emotions:- Baseline: Relaxed, peaceful emotional state
- Stress: Anxious, tense emotional state
Installation
Requirements
- Python >= 3.8
- NumPy >= 1.21.0
- Pandas >= 1.3.0
- onnxruntime >= 1.15.0 (for ONNX model inference)
Quick Start
Basic Usage
Configuration
Real-Time Processing
Available Models
extratrees_w120s60_binary_v1_0: 120-second window, 60-second step (default)extratrees_w60s5_binary_v1_0: 60-second window, 5-second stepextratrees_w120s5_binary_v1_0: 120-second window, 5-second step
API Reference
EmotionEngine
Main engine for emotion inference.
Methods:
| Method | Description | Returns |
|---|---|---|
from_pretrained(config, model=None, on_log=None) | Load pretrained model | EmotionEngine |
push(hr, rr_intervals_ms, timestamp, motion=None) | Push biosignal data | None |
consume_ready() | Get ready results | List[EmotionResult] |
get_buffer_stats() | Get current buffer statistics | Dict[str, Any] |
clear() | Clear all buffered data | None |
EmotionConfig
Configuration for the engine.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
model_id | str | "extratrees_w120s60_binary_v1_0" | Model identifier |
window_seconds | float | 120.0 | Window size (seconds) |
step_seconds | float | 60.0 | Step size (seconds) |
min_rr_count | int | 30 | Minimum RR intervals required |
return_all_probas | bool | True | Return all label probabilities |
hr_baseline | Optional[float] | None | Optional HR baseline |
priors | Optional[Dict[str, float]] | None | Optional label priors |
EmotionResult
Emotion inference result.
Attributes:
| Attribute | Type | Description |
|---|---|---|
emotion | str | Detected emotion label (“Baseline” or “Stress”) |
confidence | float | Confidence score (0.0-1.0) |
timestamp | datetime | When inferred |
probabilities | Dict[str, float] | All label probabilities |
features | Dict[str, float] | Extracted 14 HRV features |
model | Dict[str, Any] | Model metadata |
| Method | Description | Returns |
|---|---|---|
from_inference(...) | Create from raw inference data | EmotionResult |
to_dict() | Convert to dictionary | Dict[str, Any] |
Resources
- PyPI: synheart-emotion
- Repository: synheart-emotion-python
- Full README: View on GitHub
- Issues: GitHub Issues
Author: Israel Goytom