Skip to Content
Mux Docs: Home

Mux Real-Time Video has been sunset and is unavailable for new usage. Existing access will end on December 31, 2023. We recommend migrating your application to our partner, LiveKit. Please reach out to real-time-video@mux.com if you need more help or details.

Build real-time video experiences

The Mux Video API allows you to build real-time video experiences into your application, including communications spaces and broadcasts to live streams.

1Create a space

Full API ReferenceAPI

A space is where real-time communication happens in the Mux Video API. It is the basic level of abstraction for building real-time communication into your application. You can create a space through the Mux Dashboard.

From the Spaces section, click Create your first space.

Make sure to select the environment you're working in from the dropdown at the top of the page.

Click Run Request to create the space.

Take note of the new space's id.

This response will contain information about your new space. Be sure to take note of the id field, as you’ll need this space identifier for the rest of the real-time guides.

You can also use the Create Space APIAPI to manage spaces programmatically. Follow this guide to learn how to call the Mux API. You will need to create an Access Token if you've never called the API before.

2Sign a JWT

Now that you have a space to join, you need a JWT signed using a Mux signing key-pair. Follow this guide to learn more.

Make sure to create your signing key-pair in the same environment as the space you created in the previous step.

Once the JWT has been signed, the signed JWT can be safely passed to the client. The client will then use the signed JWT to authenticate to the Mux Spaces API. You should only sign a JWT on the server, where you can keep your signing key secret. You should not put your signing key in the client itself.

JWT Payload and authentication behavior

JWTs are used to join a space. The payload of a JWT is a simple JSON object with a few fields. Here's an example JWT for accessing a space:

{
// The ID of the space
"sub": "${SPACE_ID}",
// Set the audience to "rt" for real-time
"aud": "rt",
// Put your signing key ID here
"kid": "${SIGNING_KEY_ID}",
// The expiration date in the future, in epoch format
"exp": 1680602773,
// One of "publisher", "subscriber"
// This is optional, defaults to "publisher"
"role": "publisher",
// Optional external Participant ID - See below
"participant_id": "MY_CUSTOM_ID"
}

The expiration in the exp field must be in the future. Please note that once the JWT expires, the client will no longer be able to join using that JWT.

The participant_id is an optional field which you can provide to identify a participant within a space. The Mux Spaces SDKs will also represent each participant with a connection_id. The SDKs will expose both of these IDs so that you can choose to use whichever identifier you wish.

While the connection_ids will always change when a participant reconnects, the participant_id will remain the same if you specify this optional ID.

Participant Enforcement

If a participant_id is not provided in the JWT payload, the server will auto-generate one. Using the same JWT multiple times is allowed if there's no participant_id specified.

A participant_id can be used to enforce participant uniqueness in a space. If participant_id is provided in the JWT, and a client joins a space with that JWT, the Mux Spaces API will check to see if there is already a participant with that particular ID, and if so, it will reject the new connection.

This hybrid approach enables you as the developer to pick between strong access control and more fluid use cases where granular access control is not as important.

3Integrate a Mux Spaces SDK

Now you're ready to integrate real-time communications into your application. Follow the guides depending on which platforms you want to support.

Android SDK

Swift SDK

Next Steps

Broadcast your space to a Live Stream

Connect your space to a live stream by adding a broadcast.

Was this page helpful?