Skip to main content

Core Concepts

LiveKit is a flexible system, built around three core constructs: a Room, Participants, and Tracks. With just these, you can build a myriad of realtime experiences.

Room

A Room is a container for a LiveKit session. Participants in the same room may subscribe to one another's tracks.

Everyone in the room will also receive updates about changes to other participants in the same room. When a single participant changes their tracks (e.g. mutes or unpublishes), other participants will be notified of this change. This is a powerful mechanism for synchronizing state, and fundamental to building any realtime experience.

Participants within the room may also exchange data with one another, including one-to-one and one-to-many deliveries.

Rooms may be manually created with server APIs, or automatically created when the first participant attempts to join a room. When the last remaining participant leaves a room, it will be closed after a short delay.

Participant

A participant represents a user in a room. Each one is represented by a unique, client-provided identity, and a server-generated sid. If multiple participants attempt to join a room using the same identity, the last one to join will remain in the room; the server will automatically disconnect other participants using the same identity.

A Participant object contains metadata about its state, as well as a list of tracks they have published.

There are two kinds of participants:

  • LocalParticipant - represents the current user. Publishes tracks to the room.
  • RemoteParticipant - represents a remote user. You may subscribe to any of the tracks they've published.

Track and TrackPublication

LiveKit represents tracks using two related concepts:

  • Track - a wrapper around the native WebRTC MediaStreamTrack, representing a playable track.
  • TrackPublication - a track that's been published to the server. If the track is subscribed by the current participant, and available for playback locally, it will have a .track attribute representing the underlying Track object.

Having a separate TrackPublication construct lets us represent tracks which may not be subscribed to by the current participant. We can now list and manipulate track publications others have published, without the local participant necessarily being subscribed.

TrackPublication attributes

TrackPublication holds metadata about the track. The following are accessible fields on a track publication object:

FieldTypeDescription
sidstringA uid for this particular track, generated by LiveKit server.
kindTrack.KindThe type of track, whether it be audio or video.
sourceTrack.SourceSource of media: Camera, Microphone, ScreenShare, or ScreenShareAudio.
namestringThe name given to this particular track, during publishing.
subscribedbooleanIndicates whether or not this track has been subscribed to by the current client.
trackTrackIf the client is subscribed, the associated Track object representing a WebRTC track.
mutedbooleanWhether this track is muted or not. Muted tracks won't receive new bytes from the server until unmuted.

Track subscription

Each participant in the room may subscribe to one or more tracks published by other participants. When autoSubscribe is set to true (default), participants will automatically subscribe to all published tracks.

When unsubscribed, a participant will stop receiving media for that track, and may re-subscribe to it at any time.