# Source: https://docs.livekit.io/home/get-started/api-primitives.md

LiveKit docs › Get Started › Rooms, participants, and tracks

---

# Rooms, participants, and tracks

> Guide to the core API primitives in LiveKit.

## Overview

LiveKit has only three core constructs: a room, participant, and track. A room is simply a realtime session between one or more participants. A participant can publish one or more tracks and/or subscribe to one or more tracks from another participant.

## Room

A `Room` is a container object representing a LiveKit session.

Each participant in a room receives updates about changes to other participants in the same room. For example, when a participant adds, removes, or modifies the state (for example, mute) of a track, other participants are notified of this change. This is a powerful mechanism for synchronizing state and fundamental to building any realtime experience.

A room can be created manually via [server API](https://docs.livekit.io/home/server/managing-rooms.md#create-a-room), or automatically, when the first participant joins it. Once the last participant leaves a room, it closes after a short delay.

## Participant

A `Participant` is a user or process that is participating in a realtime session. They are represented by a unique developer-provided `identity` and a server-generated `sid`. A participant object also contains metadata about its state and tracks they've published.

> ❗ **Important**
> 
> A participant's identity is unique per room. Thus, if participants with the same identity join a room, only the most recent one to join will remain; the server automatically disconnects other participants using that identity.

There are two kinds of participant objects in the SDKs:

- A `LocalParticipant` represents the current user who, by default, can publish tracks in a room.
- A `RemoteParticipant` represents a remote user. The local participant, by default, can subscribe to any tracks published by a remote participant.

A participant may also [exchange data](https://docs.livekit.io/home/client/data.md) with one or many other participants.

### Hidden participants

A participant is hidden if their participant [permissions](https://docs.livekit.io/reference/server/server-apis.md#participantpermission) has `hidden` set to `true`. You can set this field in the participant's [access token](https://docs.livekit.io/home/get-started/authentication.md#video-grant). A hidden participant is not visible to other participants in the room.

### Participant fields

| Field | Type | Description |
| sid | string | A UID for this particular participant, generated by LiveKit server. |
| identity | string | Unique identity of the participant, as specified when connecting. |
| name | string | Optional display name. |
| state | ParticipantInfo.State | JOINING, JOINED, ACTIVE, or DISCONNECTED. |
| tracks | List<[TrackInfo](https://docs.livekit.io/reference/server/server-apis.md#trackinfo)> | Tracks published by the participant. |
| metadata | string | User-specified metadata for the participant. |
| joined_at | int64 | Timestamp when the participant joined the room. |
| kind | ParticipantInfo.Kind | [Type](#types-of-participants) of participant. |
| kind_detail | ParticipantInfo.KindDetail | Additional details about participant type. Valide values are `CLOUD_AGENT` or `FORWARDED`. |
| attributes | string | User-specified [attributes](https://docs.livekit.io/home/client/data.md) for the participant. |
| permission | [ParticipantPermission](https://docs.livekit.io/reference/server/server-apis.md#participantpermission) | Permissions granted to the participant. |

### Types of participants

In a realtime session, a participant could represent an end-user, as well as a server-side process. It's possible to distinguish between them with the `kind` field:

- `STANDARD`: A regular participant, typically an end-user in your application.
- `AGENT`: An agent spawned with the [Agents framework](https://docs.livekit.io/agents.md).
- `SIP`: A telephony user connected via [SIP](https://docs.livekit.io/sip.md).
- `EGRESS`: A server-side process that is recording the session using [LiveKit Egress](https://docs.livekit.io/home/egress/overview.md).
- `INGRESS`: A server-side process that is ingesting media into the session using [LiveKit Ingress](https://docs.livekit.io/home/ingress/overview.md).

## Track

A `Track` represents a stream of information, be it audio, video or custom data. By default, a participant in a room may publish tracks, such as their camera or microphone streams and subscribe to one or more tracks published by other participants. In order to model a track which may not be subscribed to by the local participant, all track objects have a corresponding `TrackPublication` object:

- `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 to by the local participant and available for playback locally, it will have a `.track` attribute representing the associated `Track` object.

We can now list and manipulate tracks (via track publications) published by other participants, even if the local participant is not subscribed to them.

### TrackPublication fields

A `TrackPublication` contains information about its associated track:

| Field | Type | Description |
| sid | string | A UID for this particular track, generated by LiveKit server. |
| kind | Track.Kind | The type of track, whether it be audio, video or arbitrary data. |
| source | Track.Source | Source of media: Camera, Microphone, ScreenShare, or ScreenShareAudio. |
| name | string | The name given to this particular track when initially published. |
| subscribed | boolean | Indicates whether or not this track has been subscribed to by the local participant. |
| track | Track | If the local participant is subscribed, the associated `Track` object representing a WebRTC track. |
| muted | boolean | Whether this track is muted or not by the local participant. While muted, it won't receive new bytes from the server. |

### Track subscription

When a participant is subscribed to a track (which hasn't been muted by the publishing participant), they continuously receive its data. If the participant unsubscribes, they stop receiving media for that track and may resubscribe to it at any time.

When a participant creates or joins a room, the `autoSubscribe` option is set to `true` by default. This means the participant automatically subscribes to all existing tracks being published and any track published in the future. For more fine-grained control over track subscriptions, you can set `autoSubscribe` to `false` and instead use [selective subscriptions](https://docs.livekit.io/home/client/receive.md#selective-subscription).

> ℹ️ **Note**
> 
> For most use cases, muting a track on the publisher side or unsubscribing from it on the subscriber side is typically recommended over unpublishing it. Publishing a track requires a negotiation phase and consequently has worse time-to-first-byte performance.

---

This document was rendered at 2025-11-18T23:54:49.181Z.
For the latest version of this document, see [https://docs.livekit.io/home/get-started/api-primitives.md](https://docs.livekit.io/home/get-started/api-primitives.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).