RTC Events

Your call screen doesn't ask the room "what changed?" over and over. Instead, the room tells your app with events: someone joined, a video is ready, the network dropped. Your code listens and updates the screen.

This page lists every event a Room can fire. There are 28 in total. They're the same on @livqeno/rtc and @livqeno/react-native, because both use the same Room class. These are in-app events. To tell your backend what happened (for logs or billing your own users), use webhooks instead.

A typical call, as events

Here's what alice's app sees when bob joins, turns on his camera, mutes, and leaves:

connectionStateChanged('connected')   alice is in the room
participantJoined(bob)                bob arrives       → add a tile for bob
trackPublished('camera', bob)         bob's camera exists
trackSubscribed(track, bob)           bob's video is ready → attach it to bob's tile
trackMuted('microphone', bob)         bob muted         → show a muted icon
participantLeft(bob)                  bob leaves        → remove bob's tile

Listen and stop listening

function onJoin(participant: RemoteParticipant) {
  console.log(`${participant.identity} joined`);
}
 
room.on('participantJoined', onJoin);
room.off('participantJoined', onJoin);      // keep the reference to unsubscribe

room.on() returns the room, so you can chain calls:

room.on('connected', render).on('participantJoined', render).on('participantLeft', render);

Connection events

Use these to show the call's status: "Connecting…", "Reconnecting…", or "Call ended".

reconnected sends nothing because there's nothing for you to redo. See Reconnection.

Participant events

Use these to add and remove people's tiles.

These are only for other people, not you.

Other people's tracks

Use these to show other people's video and audio, and their mute icons.

Muted is not the same as unpublished. A muted track is still there. Keep the person's tile and show a muted icon. Don't remove and rebuild it.

Speaking, quality, and paused video

The media server measures these for everyone in the room and pushes them to every app, so all participants see the same answer.

room.on('activeSpeakersChanged', (speakers) => {
  highlight(speakers[0]);                 // the loudest speaker, or undefined
});
 
room.on('connectionQualityChanged', (participant, quality) => {
  if (participant === room.localParticipant && quality === 'poor') showWeakNetworkBanner();
});
 
room.on('trackSubscriptionStateChanged', (track) => {
  // 'paused_bandwidth': your connection can't carry this video right now
  setPausedOverlay(track, track.subscriptionState === 'paused_bandwidth');
});

Each participant also fires its own events, for a component that only cares about one person:

participant.on('isSpeakingChanged', (speaking) => tile.classList.toggle('speaking', speaking));
participant.on('connectionQualityChanged', (quality) => setBadge(quality));

and has the current values on it: participant.isSpeaking, participant.audioLevel (0 to 1) and participant.connectionQuality ('unknown' until the server has scored them). See Tracks for subscriptionState.

Your own tracks

Use these to keep your own buttons and self-view correct, for example when the user stops a screen share from the browser's own button.

A live-stream viewer promoted to the stage is the common case for permissionsChanged:

room.on('permissionsChanged', (permissions) => {
  setCanPublish(permissions.publish);
});

Captions and AI agents

These fire only when your backend has started a transcription or an AI voice agent in the room.

participant.isAgent and participant.isTranscriber tell the platform's bots apart from your users, for example to give the agent its own tile. Rather than applying the interim and final rules yourself, fold segments through a CaptionStore:

import { CaptionStore } from '@livqeno/rtc';
 
const captions = new CaptionStore();
captions.attach(room);
captions.subscribe(() => render(captions.getSnapshot())); // { segments, interim, active }

Data and errors

participant on dataReceived is missing for a message sent by your server, or by an SDK too old to carry a sender. Handle the undefined case.

import { isRTCError } from '@livqeno/rtc';
 
room.on('error', (error) => {
  if (isRTCError(error) && error.code === 'CAMERA_PERMISSION_DENIED') {
    showPermissionHelp();
  }
});

Things that are not events

Other platforms

React and Flutter give you the same information in their own style, so you rarely call on() directly.

const state = useConnectionState();
const participants = useParticipants();
const remote = useRemoteParticipants();
const local = useLocalParticipant();
const error = useLivqenoError();
const speakers = useActiveSpeakers();               // activeSpeakersChanged
const speaking = useIsSpeaking(participant);        // isSpeakingChanged
const quality = useConnectionQuality(participant);  // connectionQualityChanged
const { state: videoState } = useTrackSubscriptionState(track);
const e2ee = useE2EEState(participant);             // e2eeStateChanged
const { segments, interim, active } = useTranscription(); // transcriptionSegment
const agentState = useAgentState(agent);            // agentStateChanged

room.connectionStateChanges.listen((state) { });
room.participantChanges.listen((participants) { });
room.data.listen((bytes) { });
room.errors.listen((error) { });
room.grantChanges.listen((grants) { });          // permissionsChanged
room.localTracksMutedByServer.listen((kind) { }); // localTrackMutedByServer
room.warnings.listen((warning) { });
room.activeSpeakerChanges.listen((speakers) { });     // activeSpeakersChanged
room.connectionQualityChanges.listen((update) { });   // connectionQualityChanged
room.subscriptionStateChanges.listen((update) { });   // trackSubscriptionStateChanged
room.e2eeStateChanges.listen((update) { });           // e2eeStateChanged
room.transcriptionSegments.listen((segment) { });     // transcriptionSegment
room.transcriptionStateChanges.listen((state) { });   // transcriptionStateChanged
room.agentStateChanges.listen((update) { });          // agentStateChanged
// After a disconnect: room.disconnectReason

Next steps

• Chat events · Stream events
• Event catalogue: every event, including webhooks.
• Signaling protocol: the messages underneath these events.