User Audio Control

The UserAudioControl component provides a comprehensive microphone control interface that includes microphone toggle functionality, device selection, and optional audio visualization. It integrates with the Pipecat Client SDK to automatically manage microphone state and device selection.

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

<UserAudioComponent
  onClick={() => console.log("Toggle mic")}
  availableMics={[
    {deviceId: "mic1", label: "Built-in Microphone"},
    {deviceId: "mic2", label: "External USB Mic"},
  ]}
  selectedMic={{deviceId: "mic1", label: "Built-in Microphone"}}
  updateMic={(deviceId) => console.log("Selected:", deviceId)}
  isMicEnabled={true}
/>

Component Variants

UserAudioControl

The UserAudioControl component is the connected variant that automatically integrates with the Pipecat Client SDK. It must be used within a PipecatClientProvider context.

You must call initDevices on the client before using the component.

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

<UserAudioControl />

Prop	Type	Default
`variant?`	`"primary" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "link" \| "active" \| "inactive"`	`"secondary"`
`size?`	`"sm" \| "md" \| "lg" \| "xl"`	`"md"`
`state?`	`"default" \| "active" \| "inactive"`	`undefined`
`buttonProps?`	`Partial<ButtonProps>`	`undefined`
`classNames?`	`{ button?: string; buttongroup?: string; dropdownMenuTrigger?: string; dropdownMenuContent?: string; dropdownMenuCheckboxItem?: string; activeText?: string; inactiveText?: string; }`	`undefined`
`dropdownButtonProps?`	`Partial<ButtonProps>`	`undefined`
`deviceDropDownProps?`	`Partial<DeviceDropDownComponentProps>`	`undefined`
`noDevicePicker?`	`boolean`	`false`
`noVisualizer?`	`boolean`	`false`
`visualizerProps?`	`Partial<VoiceVisualizerProps>`	`undefined`
`noAudio?`	`boolean`	`false`
`noAudioText?`	`string \| null`	`"Audio disabled"`
`noIcon?`	`boolean`	`false`
`activeText?`	`string`	`undefined`
`inactiveText?`	`string`	`undefined`
`children?`	`React.ReactNode`	`undefined`

UserAudioComponent

The UserAudioComponent is the headless variant that accepts all microphone state and callbacks as props. This allows you to use it with any framework or state management solution.

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

// Example with mock data
const mockMics = [
  { deviceId: "mic1", label: "Built-in Microphone" },
  { deviceId: "mic2", label: "External USB Mic" },
];

function Demo() {
  const [isMicEnabled, setIsMicEnabled] = React.useState(false);
  const [selectedMic, setSelectedMic] = React.useState(mockMics[0]);

  return (
    <UserAudioComponent
      isMicEnabled={isMicEnabled}
      onClick={() => setIsMicEnabled(!isMicEnabled)}
      availableMics={mockMics}
      selectedMic={selectedMic}
      updateMic={(deviceId) => {
        const mic = mockMics.find(m => m.deviceId === deviceId);
        if (mic) setSelectedMic(mic);
      }}
      activeText="Listening"
      inactiveText="Click to start"
    />
  );
}

render(<Demo />);

Prop	Type	Default
`onClick?`	`() => void`	`undefined`
`isMicEnabled?`	`boolean`	`false`
`availableMics?`	`MediaDeviceInfo[]`	`undefined`
`selectedMic?`	`OptionalMediaDeviceInfo`	`undefined`
`updateMic?`	`(deviceId: string) => void`	`undefined`
`variant?`	`"primary" \| "secondary" \| "outline" \| "destructive" \| "ghost" \| "link" \| "active" \| "inactive"`	`"secondary"`
`size?`	`"sm" \| "md" \| "lg" \| "xl"`	`"md"`
`state?`	`"default" \| "active" \| "inactive"`	`undefined`
`buttonProps?`	`Partial<ButtonProps>`	`undefined`
`classNames?`	`{ button?: string; buttongroup?: string; dropdownMenuTrigger?: string; dropdownMenuContent?: string; dropdownMenuCheckboxItem?: string; activeText?: string; inactiveText?: string; }`	`undefined`
`dropdownButtonProps?`	`Partial<ButtonProps>`	`undefined`
`deviceDropDownProps?`	`Partial<DeviceDropDownComponentProps>`	`undefined`
`noDevicePicker?`	`boolean`	`false`
`noVisualizer?`	`boolean`	`false`
`visualizerProps?`	`Partial<VoiceVisualizerProps>`	`undefined`
`noAudio?`	`boolean`	`false`
`noAudioText?`	`string \| null`	`"Audio disabled"`
`noIcon?`	`boolean`	`false`
`activeText?`	`string`	`undefined`
`inactiveText?`	`string`	`undefined`
`children?`	`React.ReactNode`	`undefined`

Usage Examples

Basic Usage

The UserAudioControl component automatically manages microphone state and device selection.

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

<UserAudioControl />

Custom Text Labels

You can customize the text displayed when the microphone is active or inactive.

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

<UserAudioControl
  activeText="Listening..."
  inactiveText="Click to speak"
/>

Different Variants

The component supports different visual variants to match your design system.

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

<div className="flex gap-4">
  <UserAudioControl variant="primary" />
  <UserAudioControl variant="outline" />
  <UserAudioControl variant="ghost" />
</div>

Different Sizes

You can use different sizes for the microphone control.

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

<div className="flex gap-4 items-center">
  <UserAudioControl size="sm" />
  <UserAudioControl size="md" />
  <UserAudioControl size="lg" />
  <UserAudioControl size="xl" />
</div>

Without Device Picker

Hide the device selection dropdown for a simpler interface.

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

<UserAudioControl noDevicePicker />

Without Visualizer

Hide the audio visualizer for a minimal microphone button.

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

<UserAudioControl noVisualizer />

Disabled Audio State

Show a disabled state when audio functionality is not available.

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

function Demo() {
  return (
    <UserAudioComponent
      noAudio={true}
      noAudioText="Microphone not available"
      isMicEnabled={false}
      onClick={() => {}}
    />
  );
}

render(<Demo />);

Custom Visualizer Configuration

Customize the audio visualizer appearance and behavior.

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

<UserAudioControl
  visualizerProps={{
    barCount: 15,
    barGap: 1,
    barMaxHeight: 30,
    barWidth: 2,
  }}
/>

Customize the device dropdown behavior and appearance.

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

<UserAudioControl
  deviceDropDownProps={{
    menuLabel: "Select Microphone",
    placeholder: "Choose a microphone...",
  }}
/>

Custom Styling

Apply custom CSS classes to different parts of the component.

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

<UserAudioControl
  classNames={{
    button: "border-2 border-primary",
    dropdownMenuTrigger: "bg-primary text-white",
    activeText: "font-bold text-green-600",
    inactiveText: "text-gray-500",
  }}
/>

Features

Microphone Toggle: Click to enable/disable microphone input
Device Selection: Built-in dropdown for selecting different microphone devices
Audio Visualization: Optional real-time audio level visualization
Loading States: Automatic loading indicators during connection setup
Accessible: Includes proper ARIA labels and keyboard navigation
Responsive: Adapts to different screen sizes and container widths
Theme Support: Integrates with the Voice UI Kit theming system
Flexible: Available in both connected and headless variants

Integration

The connected UserAudioControl component uses several hooks from the Pipecat Client React SDK:

usePipecatClientMediaDevices for device management
usePipecatClientTransportState for connection state
PipecatClientMicToggle for microphone control

This means it must be used within a PipecatClientProvider context to function properly.

The component will automatically:

Fetch available microphone devices
Display the currently selected microphone
Handle device selection changes
Manage microphone enable/disable state
Show appropriate loading states during connection setup
Update the Pipecat Client's microphone configuration

Visual States

The component displays different visual states based on the microphone status:

Inactive: Shows microphone off icon with inactive styling
Active: Shows microphone on icon with active styling and visualizer
Loading: Shows loading spinner during connection setup
Disabled: Shows disabled state when audio is not available

Device Management

The component includes a dropdown menu for device selection that:

Lists all available microphone devices
Shows the currently selected device
Allows switching between devices
Can be hidden with the noDevicePicker prop
Integrates with the DeviceDropDown component

On this page