Get Started in 5 Minutes

Quick Start Guide

Get Sentient UI running in your Flutter project with emotion-adaptive theming, intelligent UI responses, and seamless user experience enhancements.

What You'll Build

A Flutter app with emotion detection, context awareness, and adaptive UI that responds intelligently to user state and behavior.

1

Prerequisites

Before you begin, ensure you have the following installed and configured:

Flutter SDK ≥ 3.0.0

Latest stable Flutter installation with Dart support

Dart SDK ≥ 3.0.0

Included with Flutter, verify with dart --version

Camera & Microphone Permissions iOS/Android

Device capabilities for emotion and context sensing

Provider Package ^6.0.0

State management dependency (automatically included)

2

Installation

Add Sentient UI to your Flutter project using the Flutter CLI.

Terminal

flutter pub add sentient_ui

This command automatically adds the package to your pubspec.yaml and runs flutter pub get.

3

Basic Setup

Replace your standard MaterialApp with SentientApp to enable emotion-adaptive functionality.

lib/main.dart

import 'package:flutter/material.dart';
import 'package:sentient_ui/sentient_ui.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return SentientApp(
      title: 'My Sentient App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const MyHomeScreen(),
    );
  }
}

class MyHomeScreen extends StatelessWidget {
  const MyHomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
      ),
      body: const Center(
        child: Text('Welcome to Sentient UI!'),
      ),
    );
  }
}

What Just Happened?

SentientApp automatically initializes the emotion detection engine, manages permissions, and wraps your app with adaptive theming capabilities.

4

Configuration Options

Customize Sentient UI's behavior with these optional parameters:

Advanced Configuration

return SentientApp(
  title: 'My Sentient App',
  theme: ThemeData.light(),
  
  // Enable/disable emotion-adaptive theming
  enableEmotionTheming: true,
  
  // How often to sample emotion and context
  captureInterval: const Duration(seconds: 30),
  
  // Initial feature states (user can override in consent screen)
  enableEmotionDetection: true,
  enableContextSensing: true,
  enableBehaviorTracking: true,
  
  // Hide debug banner
  debugShowCheckedModeBanner: false,
  
  home: const MyHomeScreen(),
);

Parameter Reference

enableEmotionTheming bool (default: true)

Automatically adapts your app's theme based on detected emotions. When enabled, the UI smoothly transitions between emotional states (calm, excited, stressed).

captureInterval Duration (default: 30 seconds, min: 30s)

Controls sampling frequency for emotion and context detection. Shorter intervals increase responsiveness but consume more battery. The engine enforces a 30-second minimum to ensure reliable Bayesian filtering.

enableEmotionDetection bool (default: true)

Initial state for camera-based emotion detection. Users can disable this during the consent flow. Detects facial expressions to infer emotional state.

enableContextSensing bool (default: true)

Initial state for microphone and sensor-based context awareness. Analyzes ambient sound and device sensors to understand user environment.

enableBehaviorTracking bool (default: true)

Initial state for gesture and interaction tracking. Monitors taps, swipes, and navigation patterns to refine emotional predictions.

Privacy Note

All emotion and context data is processed locally on-device. No data is transmitted to external servers. Users can revoke permissions at any time through the app settings.

5

First Run Experience

On first launch, users will see the SentientConsentView — a permission and configuration screen that explains the framework's capabilities.

What Happens Behind the Scenes

1

Configuration Check

SentientEngine attempts to restore previous configuration from local storage (SharedPreferences).

2

Consent Screen

If no configuration exists, the consent view displays with toggles for emotion detection, context sensing, and behavior tracking.

3

Permission Requests

After user consent, iOS/Android system permission dialogs appear for camera and microphone access.

4

Engine Initialization

The SentientEngine initializes all managers (emotion, context, adaptation) and begins the capture loop.

5

App Launch

Your home widget loads with emotion-adaptive theming active. Configuration persists for future launches.

Returning Users

After initial setup, the consent screen is skipped on subsequent launches. Users can modify permissions through your app's settings or device settings.

Next Steps

Now that you have Sentient UI running, explore advanced features and customization:

Access Emotional State

Read current emotion data to customize your UI logic

final engine = context.read<SentientEngine>();
final emotion = engine.currentEmotion;

Custom Themes

Override default emotion themes with your brand colors

EmotionTheme.calm.copyWith(
  primaryColor: Colors.teal,
);

Listen to Changes

React to emotion state updates in real-time

Consumer<AdaptationManager>(
  builder: (context, mgr, _) {
    return Text(mgr.emotionLabel);
  },
);

Disable Features

Dynamically enable/disable detection at runtime

engine.updateConfig(
  enableEmotionDetection: false,
);

Additional Resources

API Reference (Coming Soon) Advanced Guides (Coming Soon) GitHub Repository Research Background