flutter_orb 1.0.0

High-performance, audio-reactive 3D particle voice orb visualizer in Flutter powered by Impeller-compatible runtime shaders and real-time microphone capture.

Flutter Orb (flutter_orb)

A high-performance, audio-reactive 3D particle voice orb visualizer in Flutter powered by Impeller-compatible GLSL runtime fragment shaders and real-time microphone amplitude capture.

---

✨ Features

• ⚡ GPU Accelerated: Raymarched 3D Simplex noise particle field rendered directly via Flutter's FragmentProgram / FragmentShader API (compatible with Impeller & Skia).
• 🎙️ Live Audio Reactive: Seamlessly streams decibel amplitude from the microphone via record package and maps to GPU uniforms in real-time.
• 🌊 Liquid-Smooth Dynamics: Built-in Exponential Moving Average (EMA) audio smoothing, configurable noise floors, peak ceilings, and non-linear power curves.
• 🎨 Fully Customizable & Presets: Includes built-in themes (Gemini, Cyberpunk, Solar Flare, Emerald Deep, Neon Rose, Monochrome) or provide custom silent/active colors, glow, radius, and speed.
• 📱 All-in-One & Standalone Modes:
  • AudioReactiveOrb: Drop-in widget with automatic mic capture, lifecycle handling, and permissions.
  • ParticleOrb: Pure visualizer widget driven by any audio energy stream (mic, TTS, music, speech synthesizer, or simulated animation).
• 🧪 Offline / Simulator Mode: Built-in speech cadence and pulse simulation when microphone is unavailable.

---

📸 Visual Showcase

Built-in 3D Particle Sphere Themes (100% Consistent Fullscreen View)

Google Gemini Aura	Cyberpunk Electric Pulse	Solar Flare Dynamics
[Gemini Neon Aura]	[Cyberpunk Pulse]	[Solar Flare Dynamics]

Emerald Deep Mint	Neon Rose Hot Pink	Monochrome Minimalist
[Emerald Deep Mint]	[Neon Rose Hot Pink]	[Monochrome Minimalist]

UI Features & Customization Modes

Compact Voice Assistant Bubble	Live Shader & Audio Tuning Panel
[Compact Assistant Bubble]	[Live Shader Tuning Sheet]

---

🚀 Getting Started

1. Add Dependency

Add flutter_orb to your pubspec.yaml:

dependencies:
  flutter_orb: ^1.0.0

2. Platform Permissions

Android (android/app/src/main/AndroidManifest.xml)

<uses-permission android:name="android.permission.RECORD_AUDIO" />

iOS (ios/Runner/Info.plist)

<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is needed for the voice orb visualizer.</string>

macOS (macos/Runner/Info.plist & Entitlements)

In Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is needed for the voice orb visualizer.</string>

In macos/Runner/DebugProfile.entitlements and Release.entitlements:

<key>com.apple.security.device.audio-input</key>
<true/>

---

🛠️ Usage Examples

1. Drop-In Audio Reactive Orb

The easiest way to display an audio-reactive voice orb:

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: Center(
        child: AudioReactiveOrb(
          style: OrbStyle.gemini(),
          width: 300,
          height: 300,
        ),
      ),
    );
  }
}

---

2. Pure Visualizer Widget (ParticleOrb)

If you want to feed custom audio values (e.g. from an audio player, TTS engine, or animation controller):

ParticleOrb(
  audioEnergy: 0.75, // 0.0 (silent) to 1.0 (loud)
  style: OrbStyle.cyberpunk(),
  width: 250,
  height: 250,
)

Or pass a ValueListenable<double>:

ParticleOrb(
  energyListenable: myEnergyNotifier,
  style: OrbStyle.solar(),
)

---

3. Custom Controller & Audio Tuning

Customize sensitivity, decibel ranges, smoothing responsiveness, or switch between live mic and simulated voice modes:

final controller = VoiceOrbController(
  minDb: -50.0, // Noise floor threshold
  maxDb: -10.0, // Peak loudness threshold
  smoothingFactor: 0.20, // Attack/decay responsiveness
  powerBoost: 1.6, // Exponential curve for punchy reactivity
);

// Start live microphone capture
await controller.start();

// Or enable simulated speech cadence for emulators or testing
controller.setSimulated(true, mode: SimulationMode.speech);

---

4. Custom Styling & Presets

// Custom Style
final customStyle = OrbStyle(
  silentColor: const Color(0xFF1E3A8A), // Deep Blue
  activeColor: const Color(0xFFF59E0B), // Vibrant Amber
  baseRadius: 0.24,
  glowIntensity: 1.3,
  speedMultiplier: 1.2,
);

// Built-in Presets
OrbStyle.gemini()      // Google Gemini Violet / Cyan
OrbStyle.cyberpunk()   // Magenta / Neon Lime
OrbStyle.solar()       // Crimson / Gold
OrbStyle.emerald()     // Forest Teal / Vivid Mint
OrbStyle.neonRose()    // Royal Purple / Hot Pink
OrbStyle.monochrome()  // Slate / Radiant White

---

📸 In-App Screenshot Automation

Generate and update all visual documentation screenshots natively through Flutter using package:integration_test and flutter drive:

cd example
flutter drive \
  --driver=test_driver/integration_test.dart \
  --target=integration_test/screenshot_test.dart

Screenshots are automatically captured in real-time with 60 FPS live particle simulations and saved directly to example/doc/screenshots/.

---

📄 License

MIT License. See LICENSE for details.