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.
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.
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.
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
.trackattribute representing the underlying
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 holds metadata about the track. The following are accessible fields on a track publication object:
|sid||string||A uid for this particular track, generated by LiveKit server.|
|kind||Track.Kind||The type of track, whether it be audio or video.|
|source||Track.Source||Source of media: Camera, Microphone, ScreenShare, or ScreenShareAudio.|
|name||string||The name given to this particular track, during publishing.|
|subscribed||boolean||Indicates whether or not this track has been subscribed to by the current client.|
|track||Track||If the client is subscribed, the associated |
|muted||boolean||Whether this track is muted or not. Muted tracks won't receive new bytes from the server until unmuted.|
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.