Synheart Emotion

On-device emotion inference from biosignals (HR/RR) for Flutter applications

🚀 Features

• 📱 Cross-Platform: Works on iOS and Android
• 🔄 Real-Time Inference: Live emotion detection from heart rate and RR intervals
• 🧠 On-Device Processing: All computations happen locally for privacy
• 📊 Unified Output: Consistent emotion labels with confidence scores
• 🔒 Privacy-First: No raw biometric data leaves your device
• ⚡ High Performance: < 5ms inference latency on mid-range devices

📦 Installation

Add synheart_emotion to your pubspec.yaml:

dependencies:
  synheart_emotion: ^0.2.3

Then run:

flutter pub get

🎯 Quick Start

Basic Usage

import 'package:synheart_emotion/synheart_emotion.dart';

void main() async {
  // Initialize the emotion engine
  final engine = EmotionEngine.fromPretrained(
    const EmotionConfig(
      window: Duration(seconds: 60),
      step: Duration(seconds: 5),
    ),
  );

  // Push biometric data
  engine.push(
    hr: 72.0,
    rrIntervalsMs: [823, 810, 798, 815, 820],
    timestamp: DateTime.now().toUtc(),
  );

  // Get emotion results (synchronous - no await needed)
  final results = engine.consumeReady();
  for (final result in results) {
    print('Emotion: ${result.emotion} (${(result.confidence * 100).toStringAsFixed(1)}%)');
  }
}

Real-Time Streaming

// Stream emotion results
final emotionStream = EmotionStream.emotionStream(
  engine,
  tickStream, // Your biometric data stream
);

await for (final result in emotionStream) {
  print('Current emotion: ${result.emotion}');
  print('Probabilities: ${result.probabilities}');
}

Integration with synheart-wear

synheart_emotion works independently but integrates seamlessly with synheart-wear for real wearable data.

First, add both to your pubspec.yaml:

dependencies:
  synheart_wear: ^0.1.0    # For wearable data
  synheart_emotion: ^0.2.3  # For emotion inference

Then integrate in your app:

import 'package:synheart_wear/synheart_wear.dart';
import 'package:synheart_emotion/synheart_emotion.dart';

// Initialize both SDKs
final wear = SynheartWear();
final emotionEngine = EmotionEngine.fromPretrained(
  const EmotionConfig(window: Duration(seconds: 60)),
);

await wear.initialize();

// Stream wearable data to emotion engine
wear.streamHR(interval: Duration(seconds: 1)).listen((metrics) {
  emotionEngine.push(
    hr: metrics.getMetric(MetricType.hr),
    rrIntervalsMs: metrics.getMetric(MetricType.rrIntervals),
    timestamp: DateTime.now().toUtc(),
  );
  
  // Get emotion results (synchronous - no await needed)
  final emotions = emotionEngine.consumeReady();
  for (final emotion in emotions) {
    // Use emotion data in your app
    updateUI(emotion);
  }
});

See examples/lib/integration_example.dart for complete integration examples.

📊 Supported Emotions

The library currently supports three emotion categories:

• 😊 Amused: Positive, engaged emotional state
• 😌 Calm: Relaxed, peaceful emotional state
• 😰 Stressed: Anxious, tense emotional state

🔧 API Reference

EmotionEngine

The main class for emotion inference:

class EmotionEngine {
  // Create engine with pretrained model
  factory EmotionEngine.fromPretrained(
    EmotionConfig config, {
    LinearSvmModel? model,
    void Function(String level, String message, {Map<String, Object?>? context})? onLog,
  });

  // Push new biometric data
  void push({
    required double hr,
    required List<double> rrIntervalsMs,
    required DateTime timestamp,
    Map<String, double>? motion,
  });

  // Get ready emotion results
  List<EmotionResult> consumeReady();

  // Get buffer statistics
  Map<String, dynamic> getBufferStats();

  // Clear all buffered data
  void clear();
}

EmotionConfig

Configuration for the emotion engine:

class EmotionConfig {
  final String modelId;                 // Model identifier
  final Duration window;                // Rolling window size (default: 60s)
  final Duration step;                  // Emission cadence (default: 5s)
  final int minRrCount;                 // Min RR intervals needed (default: 30)
  final bool returnAllProbas;           // Return all probabilities (default: true)
  final double? hrBaseline;             // Optional HR personalization
  final Map<String,double>? priors;     // Optional label priors
}

EmotionResult

Result of emotion inference:

class EmotionResult {
  final DateTime timestamp;             // When inference was performed
  final String emotion;                 // Predicted emotion (top-1)
  final double confidence;              // Confidence score (0.0-1.0)
  final Map<String, double> probabilities; // All label probabilities
  final Map<String, double> features;   // Extracted features
  final Map<String, dynamic> model;     // Model metadata
}

🔒 Privacy & Security

• On-Device Processing: All emotion inference happens locally
• No Data Retention: Raw biometric data is not retained after processing
• No Network Calls: No data is sent to external servers
• Privacy-First Design: No built-in storage - you control what gets persisted
• Real Trained Models: Uses WESAD-trained models with 78% accuracy

📱 Example App

Check out the complete examples in the synheart-emotion repository:

# Clone the main repository for examples
git clone https://github.com/synheart-ai/synheart-emotion.git
cd synheart-emotion/examples
flutter pub get
flutter run

The example demonstrates:

• Real-time emotion detection
• Probability visualization
• Buffer management
• Logging system

🧪 Testing

Run the test suite:

flutter test

Run benchmarks:

flutter test test/benchmarks_test.dart

Tests cover:

• Feature extraction accuracy
• Model inference performance
• Edge case handling
• Memory usage patterns

📊 Performance

Target Performance (mid-range phone):

• Latency: < 5ms per inference
• Model Size: < 100 KB
• CPU Usage: < 2% during active streaming
• Memory: < 3 MB (engine + buffers)
• Accuracy: 78% on WESAD dataset (3-class emotion recognition)

Benchmarks:

• HR mean calculation: < 1ms
• SDNN/RMSSD calculation: < 2ms
• Model inference: < 1ms
• Full pipeline: < 5ms

🏗️ Architecture

Biometric Data (HR, RR)
         │
         ▼
┌─────────────────────┐
│   EmotionEngine     │
│  [RingBuffer]       │
│  [FeatureExtractor] │
│  [Model Inference]  │
└─────────────────────┘
         │
         ▼
   EmotionResult
         │
         ▼
    Your App

🔗 Integration

With synheart-wear

Perfect integration with the Synheart Wear SDK for real wearable data:

// Stream from Apple Watch, Fitbit, etc.
final wearStream = synheartWear.streamHR();
final emotionStream = EmotionStream.emotionStream(engine, wearStream);

With swip-core

Feed emotion results into the SWIP impact measurement system:

for (final emotion in emotionResults) {
  swipCore.ingestEmotion(emotion);
}

📄 License

Apache 2.0 License

🤝 Contributing

We welcome contributions! See our Contributing Guidelines for details.

🔗 Links

• Main Repository: synheart-emotion (Source of Truth)
• Documentation: RFC E1.1
• Model Card: Model Card
• Examples: Examples
• Models: Pre-trained Models
• Tools: Development Tools
• Synheart Wear: synheart-wear
• Synheart AI: synheart.ai
• Issues: GitHub Issues

👥 Authors

• Synheart AI Team - Initial work, RFC Design & Architecture

---

Made with ❤️ by the Synheart AI Team

Technology with a heartbeat.

Patent Pending Notice

This project is provided under an open-source license. Certain underlying systems, methods, and architectures described or implemented herein may be covered by one or more pending patent applications.

Nothing in this repository grants any license, express or implied, to any patents or patent applications, except as provided by the applicable open-source license.