Basic Visualizer

The VoiceVisualizer component provides a real-time audio spectrum visualization that displays frequency data as animated bars. It integrates with the Pipecat Client SDK to automatically connect to audio streams and provides extensive customization options for visual appearance and behavior.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="w-64 h-32">
  <VoiceVisualizer participantType="local" />
</div>

Props Reference

Prop	Type	Default
`participantType`	`"local" \| "remote" \| "bot"`	`undefined`
`backgroundColor?`	`string`	`"transparent"`
`barColor?`	`string`	`"black"`
`noPeaks?`	`boolean`	`true`
`peakLineColor?`	`string`	`"red"`
`peakLineSpeed?`	`number`	`0.2`
`peakLineThickness?`	`number`	`2`
`peakOffset?`	`number`	`0`
`peakFadeSpeed?`	`number`	`0.02`
`barCount?`	`number`	`5`
`barGap?`	`number`	`12`
`barLineCap?`	`"round" \| "square"`	`"round"`
`barMaxHeight?`	`number`	`120`
`barOrigin?`	`"top" \| "bottom" \| "center"`	`"center"`
`barWidth?`	`number`	`30`
`className?`	`string`	`undefined`

Basic Usage

The VoiceVisualizer component requires a participantType prop to specify which audio stream to visualize. It must be used within a PipecatClientProvider context.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="bg-gray-100 rounded-lg p-4">
  <VoiceVisualizer 
    participantType="local"
    barCount={8}
    barColor="blue"
    barMaxHeight={120}
  />
</div>

Visual Customization

Bar Appearance

Customize the visual appearance of the frequency bars with various styling options.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">Default Style</h4>
    <div className="bg-gray-50 rounded p-4">
      <VoiceVisualizer participantType="local" />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Custom Colors & Size</h4>
    <div className="bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barColor="green"
        barWidth={20}
        barGap={8}
        barMaxHeight={100}
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Square Line Caps</h4>
    <div className="bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barLineCap="square"
        barColor="purple"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Custom Bar Heights</h4>
    <div className="space-y-4">
      <div>
        <p className="text-xs text-gray-600 mb-1">Short bars (60px)</p>
        <div className="bg-gray-50 rounded p-4">
          <VoiceVisualizer 
            participantType="local"
            barMaxHeight={60}
            barColor="blue"
          />
        </div>
      </div>
      <div>
        <p className="text-xs text-gray-600 mb-1">Medium bars (120px - default)</p>
        <div className="bg-gray-50 rounded p-4">
          <VoiceVisualizer 
            participantType="local"
            barMaxHeight={120}
            barColor="green"
          />
        </div>
      </div>
      <div>
        <p className="text-xs text-gray-600 mb-1">Tall bars (200px)</p>
        <div className="bg-gray-50 rounded p-4">
          <VoiceVisualizer 
            participantType="local"
            barMaxHeight={200}
            barColor="red"
          />
        </div>
      </div>
    </div>
  </div>
</div>

Bar Origins

Control how bars grow from different anchor points.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">Center Origin (Default)</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barOrigin="center"
        barColor="blue"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Top Origin</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barOrigin="top"
        barColor="green"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Bottom Origin</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barOrigin="bottom"
        barColor="red"
      />
    </div>
  </div>
</div>

Peak Indicators

The visualizer includes optional peak indicators that show the maximum amplitude reached by each frequency band. Peak indicators decay more slowly than the main bars, creating a visual "memory" of audio peaks.

Basic Peak Usage

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">Peaks Disabled (Default)</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        noPeaks={true}
        barColor="blue"
        barOrigin="bottom"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Peaks Enabled</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        noPeaks={false}
        barColor="blue"
        peakLineColor="red"
        barOrigin="bottom"
        barLineCap="square"
      />
    </div>
  </div>
</div>

Peak Customization

Customize peak appearance and behavior with various options.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">Custom Peak Color & Thickness</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        noPeaks={false}
        barColor="blue"
        peakLineColor="yellow"
        peakLineThickness={4}
        barOrigin="top"
        barLineCap="square"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Peak Offset</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        noPeaks={false}
        barColor="green"
        peakLineColor="orange"
        peakOffset={5}
        barOrigin="bottom"
        barLineCap="square"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Fast Peak Decay</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        noPeaks={false}
        barColor="purple"
        peakLineColor="cyan"
        peakLineSpeed={0.5}
        peakFadeSpeed={0.05}
        barOrigin="top"
        barLineCap="square"
      />
    </div>
  </div>
</div>

Advanced Configuration

High Resolution Visualization

For more detailed frequency analysis, increase the number of bars.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">High Resolution (20 bars)</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barCount={20}
        barWidth={12}
        barGap={4}
        barColor="blue"
        noPeaks={false}
        peakLineColor="red"
        barOrigin="bottom"
        barLineCap="square"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Ultra High Resolution (32 bars)</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barCount={32}
        barWidth={8}
        barGap={2}
        barColor="green"
        noPeaks={false}
        peakLineColor="yellow"
        peakLineThickness={1}
        barOrigin="top"
        barLineCap="square"
      />
    </div>
  </div>
</div>

CSS Variable Integration

Use CSS custom properties for dynamic theming.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">CSS Variables</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barColor="--color-blue-300"
        noPeaks={false}
        peakLineColor="--color-blue-500"
        barOrigin="bottom"
        barLineCap="square"
      />
    </div>
  </div>
</div>

Current Color Integration

Use currentColor to make the visualizer inherit colors from CSS classes, perfect for theme integration and dynamic styling.

import { VoiceVisualizer } from "@pipecat-ai/voice-ui-kit";

<div className="space-y-8">
  <div>
    <h4 className="text-sm font-medium mb-2">Red Theme</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barColor="currentColor"
        noPeaks={false}
        peakLineColor="currentColor"
        barOrigin="bottom"
        barLineCap="square"
        className="text-red-500"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Green Theme</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barColor="currentColor"
        noPeaks={false}
        peakLineColor="currentColor"
        barOrigin="top"
        barLineCap="square"
        className="text-green-600"
      />
    </div>
  </div>
  
  <div>
    <h4 className="text-sm font-medium mb-2">Purple Theme</h4>
    <div className="h-32 bg-gray-50 rounded p-4">
      <VoiceVisualizer 
        participantType="local"
        barColor="currentColor"
        noPeaks={false}
        peakLineColor="currentColor"
        barOrigin="bottom"
        barLineCap="square"
        className="text-purple-600"
      />
    </div>
  </div>
</div>

The component uses requestAnimationFrame for smooth 60fps animations
Canvas rendering is optimized with 2x scaling for crisp visuals on high-DPI displays
Peak tracking is conditionally executed only when noPeaks is false
Color resolution is cached in refs to avoid repeated DOM queries

Browser Compatibility

The component requires:

Web Audio API support
Canvas 2D context support
MediaStream API support

Modern browsers (Chrome 14+, Firefox 25+, Safari 6+) are fully supported.