Voxweave Avatars

Voxweave Avatars is a collection of customizable and interactive voice UI animations for the Voxweave's React Component. It provides visually stunning three.js and webgl visualizations for voice interactions, perfect for your AI Agent user interface.

Features

• 🎨 Multiple animation styles for different visual experiences
• 🌓 Light and dark mode compatible
• 📊 Real-time audio responsive animations
• ⚡️ Optimized performance with Three.js
• 🚀 WebGL-powered rendering
• 🔒 Type-safe implementation
• ✅ Seamless integration with Voxweave React

Installation

You can install Voxweave Avatars using npm, pnpm, or bun:

# Using npm
npm install @hoosei/voxweave-avatars

# Using pnpm
pnpm add @hoosei/voxweave-avatars   

# Using bun
bun add @hoosei/voxweave-avatars

Quick Start

Import and use the animations directly with Voxweave React:

import { Voxweave } from '@hoosei/voxweave-react'
import { BlobAnimation } from '@hoosei/voxweave-avatars'

function YourComponent() {
  return (
    <Voxweave
      animation={BlobAnimation}
      isListening={true}
      size={180}
      // other props...
      onStartCall={() => {
        // Handle call start
      }}
      onClose={() => {
        // Handle close
      }}
    />
  )
}

Usage

To use Voxweave Avatars in your React application, follow these steps:

1. Import the components you need:

import { AvatarWaveAnimation, BlobAnimation, AuroraAnimation, FluidAnimation, NeonFutureAnimation, PulseLineAnimation, PulseLineModern, PulseLineNeobrutalist, PulseRing, StaticRing, WatercolorAnimation } from '@hoosei/voxweave-avatars';

2. Use the components in your application:

<AvatarWaveAnimation />
<BlobAnimation />
<AuroraAnimation />
<FluidAnimation />
<NeonFutureAnimation />

Available Animations

Voxweave Avatars includes a variety of animation styles:

| Animation | Description | |-----------|-------------| | BlobAnimation | Organic, fluid blob that responds to audio input | | AuroraAnimation | Colorful waves inspired by aurora borealis | | WatercolorAnimation | Soft, watercolor-like fluid animation | | NeonFutureAnimation | Futuristic neon-style visualization | | FluidAnimation | Smooth, liquid-like motion | | PulseLineModern | Modern audio waveform visualization | | PulseLineAnimation | Classic audio waveform display | | PulseRing | Concentric rings that pulse with audio | | StaticRing | Simple ring visualization | | EtherealWaveAnimation | Gentle, ethereal wave patterns | | AvatarWaveAnimation | Avatar-centric wave visualization |

Animation Props

All animations accept standard properties:

| Prop | Type | Description | |------|------|-------------| | size | number | Size of the animation in pixels | | isListening | boolean | Whether the animation should show active listening state | | audioData | Uint8Array | null | Audio frequency data for visualization | | agentAudioData | Uint8Array | null | Agent's audio data for response visualization | | listeningColors | [string, string] | Gradient colors for listening state | | notListeningColors | [string, string] | Gradient colors for inactive state | | agentStatus | 'idle' | 'speaking' | 'listening' | 'thinking' | Current status of the agent |

Using with Voxweave React

When using with Voxweave React, simply pass the animation component:

import { Voxweave } from '@hoosei/voxweave-react'
import { FluidAnimation, PulseRing } from '@hoosei/voxweave-avatars'

function MyApp() {
  // For simple usage
  return (
    <Voxweave
      animation={FluidAnimation}
      // other props...
    />
  )
  
  // Or conditionally select an animation
  const selectAnimation = () => {
    return isMinimal ? PulseRing : FluidAnimation
  }
  
  return (
    <Voxweave
      animation={selectAnimation()}
      // other props...
    />
  )
}

Custom Animations

You can create custom animations by implementing the VoxweaveThreeJSProps interface:

import { VoxweaveThreeJSProps } from '@hoosei/voxweave-react'
import { Canvas } from '@react-three/fiber'

const MyCustomAnimation: React.FC<VoxweaveThreeJSProps> = ({
  size,
  isListening,
  audioData,
  listeningColors,
  notListeningColors
}) => {
  return (
    <Canvas style={{ width: size, height: size }}>
      {/* Your Three.js implementation */}
    </Canvas>
  )
}

// Then use it with Voxweave
<Voxweave animation={MyCustomAnimation} />

Contributing

We welcome contributions! Please read the CONTRIBUTING.md file for details.

Development

For local development:

# Clone the repository
git clone https://github.com/hoosei/voxweave.git

# Navigate to the avatars package
cd voxweave/packages/avatars

# Install dependencies
npm install

# Start development server
npm run dev

License

This project is proprietary software owned by Hoosei Limited. See the LICENSE.md file in the root directory for details.

Hoosei® is a registered trademark, No. UK00003747539 of Hoosei Limited, 10 Upper Grosvenor Road, Tunbridge Wells, England, TN1 2EP. Registered England & Wales Company No. 13834192.

For licensing inquiries or permissions, please contact Hoosei Limited.