{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

If using Next.js, next.config.ts handles this automatically once tsconfig.json is updated.

3. Tailwind CSS 4. This package targets Tailwind CSS v4. Ensure your tailwind.config.ts (or CSS-first config) scans the source directory:

// tailwind.config.ts
export default {
  content: [
    './src/**/*.{ts,tsx}',
    './src/livekit-agents-ui/**/*.{ts,tsx}',
  ],
};

4. Environment variables. You need a LiveKit server URL and a participant token. Typically these come from a backend token endpoint:

NEXT_PUBLIC_LIVEKIT_URL=wss://your-livekit-server.livekit.cloud

5. Token route (Next.js). The file components/agents-ui/nextjs-api-token-route.ts provides a ready-made Next.js API route helper. Copy it to app/api/token/route.ts and configure your LiveKit API key/secret via:

LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret

6. Import from the barrel. Use index.ts as the import source:

import { AgentSessionProvider, AgentControlBar, AgentChatTranscript } from '@/livekit-agents-ui';

Public API

AgentSessionProvider

import { AgentSessionProvider } from '@/livekit-agents-ui';

// Wraps your UI tree with LiveKit session context.
// Accepts a tokenSource (from livekit-client TokenSource) or serverUrl + token props.
function AgentSessionProvider(props: {
  tokenSource?: TokenSource;
  serverUrl?: string;
  token?: string;
  agentName?: string;
  children: React.ReactNode;
}): JSX.Element;

Use this as the outermost wrapper for any Agents UI component tree. It establishes the LiveKit room connection and exposes session context to all children. Without it, none of the other components will function.

AgentControlBar

import { AgentControlBar } from '@/livekit-agents-ui';

function AgentControlBar(props?: {
  className?: string;
}): JSX.Element;

Renders a pre-built control bar with microphone toggle, camera toggle, and disconnect button. Drop it at the bottom of your agent UI layout. All state is derived from the surrounding AgentSessionProvider context.

AgentChatTranscript

import { AgentChatTranscript } from '@/livekit-agents-ui';

function AgentChatTranscript(props?: {
  className?: string;
}): JSX.Element;

Displays the real-time conversation transcript between the local user and the agent. Automatically scrolls to the latest message. Use this when you want a text-based view of the voice conversation alongside audio.

AgentAudioVisualizerBar

import { AgentAudioVisualizerBar } from '@/livekit-agents-ui';

function AgentAudioVisualizerBar(props?: {
  className?: string;
}): JSX.Element;

Renders an animated bar-style audio visualizer reflecting the agent's audio output level. Four visualizer styles are available (bar, grid, radial, wave, aura); swap as needed.

AgentSessionBlock

import { AgentSessionBlock } from '@/livekit-agents-ui';

function AgentSessionBlock(props?: {
  className?: string;
}): JSX.Element;

A fully pre-assembled session view block (agent-session-view-01) combining visualizer, tile view, and controls. Use this for a zero-configuration starting point.

Working examples

Scenario - Minimal voice agent page

A single-page voice agent with microphone controls and a bar visualizer. No chat, no video.

'use client';

import { TokenSource } from 'livekit-client';
import {
  AgentSessionProvider,
  AgentControlBar,
  AgentAudioVisualizerBar,
  StartAudioButton,
} from '@/livekit-agents-ui';

const tokenSource = TokenSource.literal({
  serverUrl: process.env.NEXT_PUBLIC_LIVEKIT_URL!,
  participantToken: 'your-generated-jwt',
});

export default function VoiceAgentPage() {
  return (
    <AgentSessionProvider tokenSource={tokenSource} agentName="example-agent">
      <div className="flex flex-col items-center gap-6 p-8">
        <StartAudioButton />
        <AgentAudioVisualizerBar className="w-full max-w-md" />
        <AgentControlBar />
      </div>
    </AgentSessionProvider>
  );
}

Scenario - Voice agent with chat transcript

Adds a scrollable transcript panel alongside the audio visualizer for a voice-plus-text experience.

'use client';

import { TokenSource } from 'livekit-client';
import {
  AgentSessionProvider,
  AgentControlBar,
  AgentChatTranscript,
  AgentAudioVisualizerWave,
  AgentChatIndicator,
} from '@/livekit-agents-ui';

const tokenSource = TokenSource.literal({
  serverUrl: process.env.NEXT_PUBLIC_LIVEKIT_URL!,
  participantToken: 'your-generated-jwt',
});

export default function VoiceChatPage() {
  return (
    <AgentSessionProvider tokenSource={tokenSource} agentName="example-agent">
      <div className="flex flex-col h-screen">
        <div className="flex-1 overflow-hidden flex flex-col gap-4 p-4">
          <AgentAudioVisualizerWave className="h-24" />
          <AgentChatIndicator />
          <AgentChatTranscript className="flex-1 overflow-y-auto" />
        </div>
        <div className="border-t p-4">
          <AgentControlBar />
        </div>
      </div>
    </AgentSessionProvider>
  );
}

Scenario - Pre-built session block (zero configuration)

Use the AgentSessionBlock composite component for the fastest possible integration.

'use client';

import { TokenSource } from 'livekit-client';
import { AgentSessionProvider } from '@/livekit-agents-ui';
import { AgentSessionBlock } from '@/livekit-agents-ui';

const tokenSource = TokenSource.literal({
  serverUrl: process.env.NEXT_PUBLIC_LIVEKIT_URL!,
  participantToken: 'your-generated-jwt',
});

export default function QuickStartPage() {
  return (
    <AgentSessionProvider tokenSource={tokenSource} agentName="example-agent">
      <AgentSessionBlock className="h-screen" />
    </AgentSessionProvider>
  );
}

Scenario - Using a raw visualizer hook

Bypass the component layer and drive a custom canvas with useAgentAudioVisualizerBar.

'use client';

import { useRef } from 'react';
import { useAgentAudioVisualizerBar } from '@/livekit-agents-ui/hooks/agents-ui/use-agent-audio-visualizer-bar';

export function CustomVisualizer() {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  useAgentAudioVisualizerBar(canvasRef);

  return <canvas ref={canvasRef} width={400} height={80} className="w-full rounded-lg" />;
}

File walkthrough

• index.ts - Barrel re-export of every public component and hook; use this as the sole import point.
• components/agents-ui/agent-session-provider.tsx - Establishes the LiveKit room connection and React context.
• components/agents-ui/agent-control-bar.tsx - Pre-built mic/camera/disconnect toolbar.
• components/agents-ui/agent-chat-transcript.tsx - Scrollable real-time conversation transcript.
• components/agents-ui/agent-chat-indicator.tsx - Animated typing indicator while the agent is responding.
• components/agents-ui/agent-audio-visualizer-bar.tsx - Bar-style animated audio level display.
• components/agents-ui/agent-audio-visualizer-grid.tsx - Grid-style animated audio visualizer.
• components/agents-ui/agent-audio-visualizer-radial.tsx - Radial/circular audio visualizer.
• components/agents-ui/agent-audio-visualizer-wave.tsx - Waveform audio visualizer.
• components/agents-ui/agent-audio-visualizer-aura.tsx - Aura/glow-style audio visualizer.
• components/agents-ui/agent-disconnect-button.tsx - Standalone disconnect button.
• components/agents-ui/agent-track-toggle.tsx - Toggle button for a single media track (mic/camera).
• components/agents-ui/agent-track-control.tsx - Device selector + toggle for a media track.
• components/agents-ui/start-audio-button.tsx - Prompts the browser to unlock audio autoplay.
• components/agents-ui/react-shader-toy.tsx - WebGL shader canvas, used by the aura visualizer.
• components/agents-ui/nextjs-api-token-route.ts - Next.js App Router token endpoint helper.
• components/agents-ui/blocks/agent-session-view-01/ - Full pre-assembled session view block.
• components/ai-elements/conversation.tsx - Conversation container layout primitive.
• components/ai-elements/message.tsx - Individual message bubble (user or agent).
• components/ai-elements/shimmer.tsx - Shimmer skeleton for loading states.
• components/ui/ - Shadcn base components (Button, Toggle, Tooltip, Select, Separator, Sonner, Alert, ButtonGroup).
• components/session-provider.tsx - Minimal re-export wrapper around LiveKit session context.
• hooks/agents-ui/ - Standalone hooks for each visualizer type and the control bar.
• lib/utils.ts - cn() utility combining clsx + tailwind-merge.
• scripts/ - Internal tooling for registry and doc generation; not imported at runtime.
• vitest.config.ts / vitest.setup.ts - Test runner configuration (jsdom, ResizeObserver/IntersectionObserver mocks).

Common pitfalls and fixes

• Audio not playing on page load. Browsers block autoplay; always render <StartAudioButton /> and wait for user interaction before audio streams.
• cn import fails. Ensure lib/utils.ts is reachable via the @/* alias and that both clsx and tailwind-merge are installed.
• Tailwind classes not applied. Add the agents-ui source directory to Tailwind's content array; classes are not inlined and must be scanned.
• Tailwind CSS v3 vs v4 mismatch. This package uses Tailwind v4 syntax (@import "tailwindcss"); if your project is on v3, upgrade or convert the CSS entry point.
• ResizeObserver is not defined in tests. Copy the mock from vitest.setup.ts into your own test setup file; Radix UI components require it.
• WebGL unavailable in test environment. react-shader-toy.tsx uses WebGL; mock or skip it in jsdom tests with vi.mock('@/livekit-agents-ui/components/agents-ui/react-shader-toy').
• Token expiry disconnects session. TokenSource supports dynamic token refresh; use TokenSource.fromFunction with a fetch to your token endpoint rather than a static literal in production.

Vibe-coding prompt template

I have a LiveKit Agents UI component library located in `source/` and documented in `USAGE.md`.
The upstream npm package is `@livekit/components@0.0.0`.

Please integrate this library into my existing Next.js project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Copy the contents of `source/` into `src/livekit-agents-ui/` preserving the directory structure.
3. Add the `@/*` path alias to `tsconfig.json` pointing to the project root.
4. Install all dependencies listed in the "Required dependencies" section of `USAGE.md`.
5. Create a Next.js API route at `app/api/livekit-token/route.ts` using the helper in
   `source/components/agents-ui/nextjs-api-token-route.ts`.
6. Create a client component at `app/agent/page.tsx` that:
   - Fetches a token from the API route on mount
   - Wraps the UI in `AgentSessionProvider` with the fetched token
   - Renders `AgentAudioVisualizerBar`, `AgentChatTranscript`, and `AgentControlBar`
7. Add the `src/livekit-agents-ui` directory to Tailwind's content array.
8. Do not invent any component props or exports not documented in `USAGE.md`.

License and credit

The upstream source is part of the LiveKit Components JS monorepo. See source/LICENSE if present, or refer to the upstream repository for the applicable license (Apache 2.0). Upstream package: @livekit/components.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Ably Pub/Sub Realtime JavaScript SDK Plugin

Automation, Utilities & Developer Tools

無料