Skip to main content

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
The SDK uses ExtraTrees classifiers with 14 HRV features for binary emotion classification.

Installation

pip install synheart-emotion

Requirements

  • Python >= 3.8
  • NumPy >= 1.21.0
  • Pandas >= 1.3.0
  • onnxruntime >= 1.15.0 (for ONNX model inference)

Quick Start

Basic Usage

from datetime import datetime
from synheart_emotion import EmotionEngine, EmotionConfig

# Initialize engine
config = EmotionConfig()
engine = EmotionEngine.from_pretrained(config)

# Push biosignal data
engine.push(
    hr=72.0,
    rr_intervals_ms=[850.0, 820.0, 830.0, 845.0, 825.0],
    timestamp=datetime.now()
)

# Get inference results
results = engine.consume_ready()
for result in results:
    print(f"Emotion: {result.emotion} ({result.confidence:.1%})")

Configuration

# Default configuration (120s window, 60s step)
config = EmotionConfig()
engine = EmotionEngine.from_pretrained(config)

# Custom configuration
config = EmotionConfig(
    window_seconds=120.0,  # 120 second window (default)
    step_seconds=60.0,     # 60 second step (default)
)

engine = EmotionEngine.from_pretrained(config)

Real-Time Processing

import time

engine = EmotionEngine.from_pretrained()

while True:
    # Get biosignal from your data source
    biosignal = get_latest_biosignal()

    # Push to engine
    engine.push(
        hr=biosignal.hr,
        rr_intervals_ms=biosignal.rr_intervals,
        timestamp=datetime.now()
    )

    # Consume results
    results = engine.consume_ready()
    for result in results:
        print(f"[{result.timestamp}] {result.emotion}: {result.confidence:.1%}")

    time.sleep(1)

Available Models

  • extratrees_w120s60_binary_v1_0: 120-second window, 60-second step (default)
  • extratrees_w60s5_binary_v1_0: 60-second window, 5-second step
  • extratrees_w120s5_binary_v1_0: 120-second window, 5-second step

API Reference

EmotionEngine

Main engine for emotion inference. Methods:
MethodDescriptionReturns
from_pretrained(config, model=None, on_log=None)Load pretrained modelEmotionEngine
push(hr, rr_intervals_ms, timestamp, motion=None)Push biosignal dataNone
consume_ready()Get ready resultsList[EmotionResult]
get_buffer_stats()Get current buffer statisticsDict[str, Any]
clear()Clear all buffered dataNone

EmotionConfig

Configuration for the engine. Parameters:
ParameterTypeDefaultDescription
model_idstr"extratrees_w120s60_binary_v1_0"Model identifier
window_secondsfloat120.0Window size (seconds)
step_secondsfloat60.0Step size (seconds)
min_rr_countint30Minimum RR intervals required
return_all_probasboolTrueReturn all label probabilities
hr_baselineOptional[float]NoneOptional HR baseline
priorsOptional[Dict[str, float]]NoneOptional label priors

EmotionResult

Emotion inference result. Attributes:
AttributeTypeDescription
emotionstrDetected emotion label (“Baseline” or “Stress”)
confidencefloatConfidence score (0.0-1.0)
timestampdatetimeWhen inferred
probabilitiesDict[str, float]All label probabilities
featuresDict[str, float]Extracted 14 HRV features
modelDict[str, Any]Model metadata
Methods:
MethodDescriptionReturns
from_inference(...)Create from raw inference dataEmotionResult
to_dict()Convert to dictionaryDict[str, Any]

Resources

For comprehensive documentation, see the full README on GitHub.
Author: Israel Goytom