react-hooks

LiveKit React Hooks

LiveKit のフックを使って、リアルタイムの音声／動画アプリケーション用のカスタム React UI を構築します。

LiveKit MCP サーバーのツール

このスキルは LiveKit MCP サーバーと連携して動作します。LiveKit MCP サーバーを使うと、最新の LiveKit ドキュメント、コード例、変更履歴に直接アクセスできます。このスキルの作成後に変更されている可能性のある最新情報が必要な場合は、これらのツールを使用してください。

利用可能な MCP ツール：

• docs_search - LiveKit のドキュメントサイトを検索します
• get_pages - パスを指定してドキュメントページを取得します
• get_changelog - LiveKit パッケージの最近のリリースと更新情報を取得します
• code_search - LiveKit のリポジトリからコード例を検索します
• get_python_agent_example - 100 件以上の Python エージェント例を参照します

MCP ツールを使用する場合：

• 最新の API ドキュメントや機能の更新情報が必要な場合
• 最近の例やコードパターンを探す場合
• 最近のリリースで機能が追加されたかどうかを確認する場合
• ローカルのリファレンスに特定のトピックが記載されていない場合

ローカルのリファレンスを使用する場合：

• このスキルで扱う基本概念をすばやく確認したい場合
• オフラインで作業する場合や、一般的なパターンにすばやくアクセスしたい場合
• リファレンスの情報で十分な場合

最適な使い方として、MCP ツールとローカルのリファレンスを併用してください。

対象範囲

このスキルの対象は、@livekit/components-react のフックのみです。これらのフックは LiveKit のルーム状態、参加者、トラック、エージェントデータに低レベルでアクセスでき、完全にカスタマイズされた UI を構築できます。

重要：エージェントアプリケーションでは、@livekit/components-react の UI コンポーネントを使用しないでください。 すべての UI コンポーネントには、shadcn ベースのコンポーネントを提供する livekit-agents-ui スキルのものを使用してください。

• AgentSessionProvider - 音声レンダリングを備えたセッションラッパー
• AgentControlBar - メディアコントロール
• AgentAudioVisualizerBar/Grid/Radial - 音声ビジュアライザー
• AgentChatTranscript - チャット表示
• その他多数

Agents UI コンポーネントでは提供されないカスタム動作が必要な場合に限り、このスキルのフックを使用してください。Agents UI コンポーネントは内部でこれらのフックを使用しています。

リファレンス

必要に応じて、次のリソースを参照してください。

• ./references/livekit-overview.md -- LiveKit エコシステムの概要と、各スキルの連携方法
• ./references/participant-hooks.md -- 参加者のデータと状態にアクセスするフック
• ./references/track-hooks.md -- 音声／動画トラックを操作するフック
• ./references/room-hooks.md -- ルーム接続と状態を扱うフック
• ./references/session-hooks.md -- 管理対象のエージェントセッション向けフック（useSession、useSessionMessages）
• ./references/agent-hooks.md -- 音声 AI エージェント連携用のフック
• ./references/data-hooks.md -- チャットとデータチャネル用のフック

インストール

npm install @livekit/components-react livekit-client

クイックスタート

AgentSessionProvider でフックを使う（標準的な方法）

エージェントアプリでは、セッションプロバイダーに livekit-agents-ui スキルの AgentSessionProvider を使用してください。このパッケージの useSession フックは、AgentSessionProvider 用のセッションを作成するために必須です。

必須のフック：useSession を使用してセッションオブジェクトを作成します。

import { useRef, useEffect } from 'react';
import { useSession } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';

function App() {
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.endpoint('/api/token')
  ).current;

  // Create session using useSession hook (required for AgentSessionProvider)
  const session = useSession(tokenSource, { agentName: 'your-agent' });

  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <AgentSessionProvider session={session}>
      <MyAgentUI />
    </AgentSessionProvider>
  );
}

エージェントの状態を扱う追加フック：useVoiceAssistant を使用して、エージェントの状態、音声トラック、文字起こしにアクセスします。

import { useVoiceAssistant } from '@livekit/components-react';

// This component must be inside an AgentSessionProvider
function CustomAgentStatus() {
  const { state, audioTrack, agentTranscriptions } = useVoiceAssistant();

  return (
    <div>
      <p>Agent state: {state}</p>
      {agentTranscriptions.map((t) => (
        <p key={t.id}>{t.text}</p>
      ))}
    </div>
  );
}

コンポーネントの詳細については、livekit-agents-ui スキルを参照してください。

カスタムのマイク切り替え

import { useTrackToggle } from '@livekit/components-react';
import { Track } from 'livekit-client';

// Use this inside an AgentSessionProvider for custom toggle behavior
function CustomMicrophoneButton() {
  const { enabled, toggle, pending } = useTrackToggle({
    source: Track.Source.Microphone,
  });

  return (
    <button onClick={() => toggle()} disabled={pending}>
      {enabled ? 'Mute' : 'Unmute'}
    </button>
  );
}

完全にカスタマイズする方法：useSession + SessionProvider（非推奨）

注：このパターンでは、@livekit/components-react の UI コンポーネントを直接使用します。エージェントアプリケーションでは、代わりに livekit-agents-ui の AgentSessionProvider を使用してください。このプロバイダーはこれらのコンポーネントをラップし、より優れた開発者エクスペリエンスを提供します。

Agents UI コンポーネントを使わずに完全にカスタマイズした実装を行う場合は、useSession、SessionProvider、RoomAudioRenderer を直接使用できます。これにより完全な制御が可能になりますが、より多くの手動セットアップが必要です。

このパターンは、Agents UI の AgentSessionProvider を使用できない場合に限って使用してください。

import { useEffect, useRef } from 'react';
import { useSession, useAgent, SessionProvider, RoomAudioRenderer } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';

function AgentApp() {
  // Use useRef to prevent recreating TokenSource on each render
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.sandboxTokenServer('your-sandbox-id')
  ).current;

  const session = useSession(tokenSource, {
    agentName: 'your-agent-name',
  });
  const agent = useAgent(session);

  // Auto-start session with cleanup
  useEffect(() => {
    session.start();
    return () => {
      session.end();
    };
  }, []);

  return (
    <SessionProvider session={session}>
      <RoomAudioRenderer />
      <div>
        <p>Connection: {session.connectionState}</p>
        <p>Agent: {agent.state}</p>
      </div>
    </SessionProvider>
  );
}

本番環境では、サンドボックスの代わりに TokenSource.endpoint() を使用してください。

const tokenSource: TokenSourceConfigurable = useRef(
  TokenSource.endpoint('/api/token')
).current;

const session = useSession(tokenSource, {
  roomName: 'my-room',
  participantIdentity: 'user-123',
  participantName: 'John',
  agentName: 'my-agent',
});

フックのカテゴリ

参加者フック

参加者のデータと状態にアクセスします。

• useParticipants() - すべての参加者（ローカル＋リモート）
• useLocalParticipant() - メディア状態を含むローカル参加者
• useRemoteParticipants() - すべてのリモート参加者
• useRemoteParticipant(identity) - 特定のリモート参加者
• useParticipantInfo() - ID、名前、メタデータ
• useParticipantAttributes() - 参加者の属性

トラックフック

音声／動画トラックを操作します。

• useTracks(sources) - トラック参照の配列
• useParticipantTracks(sources, identity) - 特定の参加者のトラック
• useTrackToggle({ source }) - マイク／カメラ／画面の切り替え
• useIsMuted(trackRef) - トラックがミュートされているか確認
• useIsSpeaking(participant) - 参加者が話しているか確認
• useTrackVolume(track) - 音量レベル

ルームフック

ルームの接続と状態を操作します。

• useConnectionState() - ルームの接続状態
• useRoomInfo() - ルーム名とメタデータ
• useLiveKitRoom(props) - ルームインスタンスの作成と管理
• useIsRecording() - ルームが録音中か確認
• useMediaDeviceSelect({ kind }) - 音声／動画デバイスの選択

セッションフック（ベータ版）

セッション管理用（AgentSessionProvider に必要）：

• useSession(tokenSource, options) - 接続のライフサイクルを含むエージェントセッションの作成と管理。AgentSessionProvider に必要です。
• useSessionMessages(session) - チャットと文字起こしのメッセージを統合して取得

エージェントフック（ベータ版）

音声 AI エージェントとの統合：

• useVoiceAssistant() - エージェントの状態、トラック、文字起こしを扱う主要なフック。AgentSessionProvider 内で使用できます。
• useAgent(session) - ライフサイクルヘルパーを含む、エージェントの全状態。useSession で取得したセッションが必要です。

データフック

チャットとデータチャネル：

• useChat() - チャットメッセージの送受信
• useDataChannel(topic) - 低レベルのデータメッセージング
• useTextStream(topic) - テキストストリームを購読（ベータ版）
• useTranscriptions() - 文字起こしデータを取得（ベータ版）
• useEvents(instance, event, handler) - セッション／エージェントから型付きイベントを購読

コンテキストの要件

ほとんどのフックにはルームコンテキストが必要です。エージェントアプリケーションでは、次の 2 つの方法があります。

オプション 1：useSession + AgentSessionProvider（標準）

useSession でセッションを作成し、それを livekit-agents-ui の AgentSessionProvider に渡します。AgentSessionProvider は SessionProvider をラップし、音声再生用の RoomAudioRenderer を含みます。useVoiceAssistant、useTrackToggle、useChat などのフックは、このプロバイダー内で自動的に動作します。

import { useRef, useEffect } from 'react';
import { useSession, useVoiceAssistant } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';

function App() {
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.endpoint('/api/token')
  ).current;

  // Create session using useSession hook (required)
  const session = useSession(tokenSource, { agentName: 'your-agent' });

  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <AgentSessionProvider session={session}>
      {/* Hooks from @livekit/components-react work here */}
      <MyAgentComponent />
    </AgentSessionProvider>
  );
}

function MyAgentComponent() {
  // useVoiceAssistant works inside AgentSessionProvider
  const { state, audioTrack } = useVoiceAssistant();
  return <div>Agent: {state}</div>;
}

オプション 2：useSession + SessionProvider（非推奨）

注：このパターンでは、@livekit/components-react の UI コンポーネントを直接使用します。エージェントアプリケーションでは、代わりに livekit-agents-ui の AgentSessionProvider を使用するオプション 1 を選んでください。

Agents UI コンポーネントを使わず、完全に手動で制御する必要がある場合に限って、このパターンを使用してください。RoomAudioRenderer を手動で含める必要があります。

import { useRef, useEffect } from 'react';
import { useSession, useAgent, SessionProvider, RoomAudioRenderer } from '@livekit/components-react';
import { TokenSource, TokenSourceConfigurable } from 'livekit-client';

function App() {
  const tokenSource: TokenSourceConfigurable = useRef(
    TokenSource.sandboxTokenServer('your-sandbox-id')
  ).current;

  const session = useSession(tokenSource, { agentName: 'your-agent' });
  const agent = useAgent(session); // Pass session explicitly when using useSession

  useEffect(() => {
    session.start();
    return () => session.end();
  }, []);

  return (
    <SessionProvider session={session}>
      <RoomAudioRenderer />
      <MyAgentComponent agent={agent} />
    </SessionProvider>
  );
}

ベストプラクティス

全般

1. 標準的な UI には Agents UI を使用する - ほとんどのエージェントアプリケーションでは、livekit-agents-ui の構築済みコンポーネントを使用してください。これらのフックは、カスタム動作が必要な場合にのみ使用してください。
2. updateOnlyOn で最適化する - 多くのフックでは updateOnlyOn を指定して、特定のイベントにのみ再レンダリングを制限できます。
3. 接続状態を処理する - ルームデータにアクセスする前に、必ず useConnectionState() を確認してください。
4. TokenSource をメモ化する - レンダリングのたびに再作成されないよう、TokenSource を作成する際は必ず useRef を使用してください。

エージェントアプリケーション向け

5. useSession を AgentSessionProvider と併用する - ほとんどのエージェントアプリでは、useSession でセッションを作成し、livekit-agents-ui の AgentSessionProvider に渡してください。AgentSessionProvider が音声のレンダリングを自動的に処理します。

6. エージェントの状態には useVoiceAssistant を使用する - AgentSessionProvider 内では、useVoiceAssistant を使用してエージェントの状態と文字起こしにアクセスしてください。これは useAgent より簡単です。

import { useVoiceAssistant } from '@livekit/components-react';

function AgentDisplay() {
  const { state, audioTrack, agentTranscriptions } = useVoiceAssistant();
  // state: "disconnected" | "connecting" | "initializing" | "listening" | "thinking" | "speaking"
}

7. エージェントの状態を適切に処理する - useAgent を使用する場合は、'idle'、'pre-connect-buffering'、'failed' を含むすべての状態を処理してください。

const agent = useAgent(session);

if (agent.state === 'failed') {
  console.error('Agent failed:', agent.failureReasons);
}

if (agent.isPending) {
  // Show loading state
}

8. 必ず AgentSessionProvider を使用する - すべてのエージェントアプリケーションで、livekit-agents-ui の useSession と AgentSessionProvider を使用してください。これが標準的な推奨方法です。

パフォーマンス

9. メディア制御には LiveKit 組み込みのフックを使用する - トラックの切り替え、デバイスの選択などの機能には、独自に実装するのではなく、提供されているフック（useTrackToggle、useMediaDeviceSelect）を使用してください。これらのフックは複雑な状態管理を処理し、厳密にテストされています。

10. useEvents でイベントを購読する - イベントリスナーを手動で管理する代わりに、useEvents を使用して、適切なクリーンアップとともにセッションおよびエージェントのイベントを購読してください。

useEvents(agent, AgentEvent.StateChanged, (state) => {
  console.log('Agent state:', state);
});

ベータ版のフック

@livekit/components-react のいくつかのフックはベータ版であり、変更される可能性があります。

• useSession、useSessionMessages
• useAgent、useVoiceAssistant
• useTextStream、useTranscriptions

これらのフックの更新については、LiveKit コンポーネントの変更履歴を確認してください。