Koei's Digital Garden

Rooms, Participants, and Tracks

5 min read

Rooms, Participants, and Tracks

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

Room

LiveKit セッションを表すコンテナオブジェクト。

作成タイミング:

  • サーバー API で明示的に作成
  • 最初の Participant が join した瞬間に自動作成

最後の Participant が退出すると、少し遅延してから自動で閉じる。 管理は RoomServiceClient 経由でバックエンドから行う（作成・一覧・削除）。

stateDiagram-v2
    [*] --> Active: API で明示作成
    [*] --> Active: 最初の Participant が join（自動作成）
    Active --> Active: Participant が join / leave
    Active --> クローズ待ち: 最後の Participant が退出
    クローズ待ち --> [*]: empty timeout 経過 → Room クローズ

State Sync メカニズム（後で深掘り）: Room 内の Participant は、他の Participant の変化（Track の追加・削除・mute など）を全員が受け取る。 これが LiveKit のリアルタイム体験を支える根幹の仕組み。

Participant

Room に参加するエンティティ。全ての参加者（人間・AI・電話・録画プロセスも）が同じ Participant として扱われる。

SDK 上の2クラス

クラス説明
LocalParticipant自分自身。Track の publish 主体
RemoteParticipantそれ以外の全員。デフォルトで全 Track を subscribe できる

Participant の kind（種別）

kind説明
STANDARD普通のエンドユーザー
AGENTAgents Framework で作った AI エージェント
SIP電話ユーザー（固定電話・IP電話）
EGRESS録画・配信用サーバープロセス
INGRESS外部メディアを取り込むサーバープロセス

identity vs sid

  • identity = 開発者が設定する識別子（例: “koei”, “agent-001”）。Room 内で一意
  • sid = LiveKit サーバーが自動生成する UID。同じ人が再 join するたびに新しい sid が振られる

→ identity は「誰か」、sid は「この接続セッション」を指す

権限管理

2タイミングで設定できる：

  1. join 前: Access Token 生成時に初期権限を埋め込む
  2. join 後: UpdateParticipant API でリアルタイムに変更（例: 聴衆 → 発言者への昇格）

管理方法

  • RoomServiceClient = バックエンドサーバーから管理（kick・mute・権限変更など）
  • SDK の LocalParticipant = クライアント/エージェントが自分自身を操作

特殊な Participant の種類

Hidden Participant: hidden = true に設定すると他の Participant から見えなくなる。サーバープロセスなどに使う。

Linked Participant（後で深掘り）: エージェントは一度に1人の Participant としか対話できない。その対象を Linked Participant と呼ぶ。

重要な API

  • ListParticipants / GetParticipant — 一覧・詳細取得
  • UpdateParticipant — 権限・メタデータ・属性の変更
  • MoveParticipant — 別 Room への移動（LiveKit Cloud のみ）
  • ForwardParticipant — 複数 Room へのトラック共有（LiveKit Cloud のみ）
  • RemoveParticipant — 強制切断

Track

Participant 間を流れるメディアストリーム（音声・映像・データ）。

Track と TrackPublication の違い

説明
TrackPublication「誰かがこの Track を publish している」というメタデータ。subscribe していなくても存在する
Track実際に再生できるメディアストリーム本体（WebRTC MediaStreamTrack のラッパー）

関係性:

graph LR
    TP["TrackPublication\n──────────────\nメタ情報・常に全員に見える\n（subscribe不要）"]
    T["Track\n──────────────\nメディア実体\n（subscribe した人だけ）"]
    Null["track = null\n（subscribe していない人）"]

    TP -->|".track（subscribeあり）"| T
    TP -.->|".track（subscribeなし）"| Null

具体例: Aさんがカメラをオンにした → 全員に TrackPublication が通知される → subscribe した人だけ .track に実際の映像が入る → subscribe していない人は「Aさんが配信している」という情報だけ持つ

→ 「誰が何を publish しているか」は subscribe なしに知れる。実際に見る・聴くには subscribe が必要。

Track の種類（source）

source内容
Cameraカメラ映像
Microphoneマイク音声
ScreenShare画面共有映像
ScreenShareAudio画面共有音声
Data任意データ（テキスト・JSON・バイナリ）

autoSubscribe

デフォルト true。join した瞬間、Room 内の全 Track を自動 subscribe し始める。 細かく制御したい場合は false にして selective subscription を使う。

Mute vs Unpublish

Mute を優先しろ。 Track の publish には WebRTC のネゴシエーションフェーズが必要でコストが高い。 一時的に止めたいだけなら mute の方が効率的（再開も速い）。

Webhooks & Events

→ Webhooks and Events に詳細をまとめた。

Graph View

Backlinks