@sdkrouter/aisphere

Audio-reactive 3D liquid orb component for AI interfaces. Built with React Three Fiber, custom GLSL shaders, and WebAudio API.

Features

4 visual modes: idle, listening, thinking, speaking
Real-time audio reactivity via WebAudio AnalyserNode
Simplex noise vertex displacement with matcap + Fresnel iridescence shading
Configurable presets, audio gains, and transition speed
Pulse effects (success, error, info)
CSS glow with smooth fade-in on load
Suspense-wrapped for Next.js compatibility

Install

pnpm add @sdkrouter/aisphere

Peer dependencies: react, react-dom, three, @react-three/fiber, @react-three/drei

Usage

import { LiquidOrb } from '@sdkrouter/aisphere';

<LiquidOrb size={400} mode="idle" />

With audio

import { LiquidOrb } from '@sdkrouter/aisphere';

const audio = new Audio('/speech.mp3');
audio.play();

<LiquidOrb size={400} mode="speaking" audioSource={audio} />

With provider (shared context)

import { LiquidOrbProvider, LiquidOrb, useLiquidOrb } from '@sdkrouter/aisphere';

function Controls() {
  const { mode, setMode, triggerPulse } = useLiquidOrb();
  return <button onClick={() => setMode('thinking')}>Think</button>;
}

<LiquidOrbProvider audioSource={audio}>
  <LiquidOrb size={400} />
  <Controls />
</LiquidOrbProvider>

Custom config

import { LiquidOrb } from '@sdkrouter/aisphere';
import type { LiquidOrbConfig } from '@sdkrouter/aisphere';

const config: LiquidOrbConfig = {
  presets: {
    idle: { noiseAmplitude: 0.05, color1: '#ff6b6b' },
  },
  audioReactivity: { lowGain: 0.1, volumeGain: 0.4 },
  lerpSpeed: 0.06,
};

<LiquidOrb size={400} config={config} />

API

`<LiquidOrb />`

Prop	Type	Default	Description
`mode`	`LiquidOrbMode`	`'idle'`	Visual mode
`audioSource`	`HTMLAudioElement`	—	Audio element for reactivity
`size`	`number`	`300`	Size in px
`config`	`LiquidOrbConfig`	`{}`	Override presets, audio gains, lerp speed
`className`	`string`	—	CSS class on container

Modes

idle — calm breathing, blue/purple
listening — slightly more active, cyan/indigo
thinking — faster noise, purple/pink, distortion
speaking — moderate activity, green/blue

Exports

// Components
LiquidOrb, LiquidOrbProvider, useLiquidOrb

// Constants
DEFAULT_PRESETS, DEFAULT_AUDIO_REACTIVITY

// Types
LiquidOrbMode, LiquidOrbProps, LiquidOrbConfig,
AudioReactivityConfig, OrbParams, PulseType, AudioFrame

Development

make dev     # Start Vite dev server on :3333
make check   # TypeScript check