Mux

The Mux Developer Hub

Welcome to the Mux developer hub. You'll find comprehensive guides and documentation to help you start working with Mux as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Live Streaming

Whether you’re looking to build “Twitch for X”, online classrooms, a news & sports broadcasting platform or something the world’s never seen before, the Mux Live Streaming API makes it easy to build live video into your own software. With a simple API call you get everything you need to push a live stream and play it back at high quality for a global audience.

  1. Create a unique Live Stream using the Mux API
  2. Pass the Live Stream's Stream Key to your “streamer” for live streaming from broadcast software (e.g. OBS) or from your own app.
  3. Use the Live Stream's Playback ID to play the live stream in your video player.

0. Get an API Access Token

If you haven't already, create an API access token. Be sure to set it to have "Full Access" for Mux Video. See the access token guide for more help.

1. Create a unique Live Stream

(Detailed API Reference)

The Live Stream object in the Mux API is a record of a live stream of video that will be pushed to Mux. To create your first Live Stream, send a POST request to the /live-streams endpoint.

You can either replace ${MUX_TOKEN_ID} and ${MUX_TOKEN_SECRET} with your own access token details or make sure to export those environment variables with the correct values first.

curl https://api.mux.com/video/v1/live-streams \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "playback_policy": ["public"], "new_asset_settings": { "playback_policy": ["public"] } }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET} | json_pp
    

The response will include a Playback ID and a Stream Key.

  • Playback IDs for a Live Stream can be used the same way as Playback IDs for an Asset. You can use it to play video or create thumbnails.
  • The Stream Key is a secret that can be used along with Mux's RTMP Server URL rtmp://live.mux.com/app to configure RTMP streaming software.
IMPORTANT

The Stream Key should be treated as a private key for live streaming. Anyone with the key can use it to stream video to the Live Stream it belongs to, so make sure your users know to keep it safe. If you lose control of a stream key, you can either delete the Live Stream or reset the stream key.

{
  "data": {
    "id": "QrikEQpEXp3RvklQSHyHSYOakQkXlRId",
    "stream_key": "super-secret-stream-key",
    "status": "idle",
    "playback_ids": [
      {
        "policy": "public",
        "id": "OJxPwQuByldIr02VfoXDdX6Ynl01MTgC8w02"
      }
    ],
    "created_at": "1527110899"
  }
}

2. Start Broadcasting

Mux supports live streaming using the RTMP protocol, which is supported by most broadcast software/hardware as well as open source software for mobile applications.

Your users or your client app will need software that can push an RTMP stream. That software will be configured using the Stream Key from the prior step along with Mux's RTMP Server URL rtmp://live.mux.com/app.

Learn more about:

If you want to live stream with a protocol other than RTMP, let us know!

rtmp://live.mux.com/app
[OBS](https://obsproject.com/) Live Stream Settings

OBS Live Stream Settings

The broadcast software will describe how to start and stop an RTMP session. Once the session begins, the software will start pushing live video to Mux and the Live Stream will change its status to active indicating it is receiving the RTMP stream and is playable using the Playback ID.

Broadcasting Webhooks

When a Streamer begins sending video and the Live Stream changes status, your application can respond by using Webhooks. There are a few related events that Mux will send. You application may benefit from some or none of these events, depending on the specific user experience you want to provide.

  • video.live_stream.connected - The Streamer's broadcasting software/hardware has successfully connected with Mux servers. Video is not yet being recorded and is not yet playable.
  • video.live_stream.disconnected - The Streamer's broadcasting software/hardware has disconnected from Mux servers, either intentionally or unintentionally because of a network drop.
  • video.live_stream.recording - Video is being recorded and prepared for playback. The recording of the live stream (the Active Asset) will include video sent after this point. If your UI has a red "recording" light, this would be the event that turns it on.
  • video.live_stream.active - The Live Stream is now playable using the Live Stream's Playback ID or the Active Asset's Playback ID
  • video.live_stream.idle - The Streamer's broadcasting software/hardware previously disconnected from Mux servers and the reconnect_window has now expired. The recording of the live stream (the Active Asset) will now be considered complete. The next time video is streamed using the same Stream Key it will create a new Asset for the recording.
  • video.asset.live_stream_completed - This event is fired by the Active Asset when the Live Stream enters the idle state and the Active Asset is considered complete. The Asset's playback URL will switch to being an "on-demand" (not live) video.

3. Play It!

To play back a live stream, use the PLAYBACK_ID that was returned when you created the Live Stream along with stream.mux.com to create an HTTP Live Streaming (HLS) URL. HLS is an adaptive streaming format supported by almost all players and devices. It provides a better streaming experience over static files like MP4s and is the only live streaming video format supported by Apple devices.

https://stream.mux.com/{PLAYBACK_ID}.m3u8

The easiest way to test playback is to try this playback URL in Safari (Mac) or Edge (Windows), which can natively play back HLS video.

See our playback guide for more information about how to integrate with a video player.

Don't forget to integrate Mux Data with your player for monitoring and improved performance! It's free for Mux Video streams.

4. Stop Broadcasting

When the Streamer is finished they will stop the broadcast software/hardware, which will disconnect from the Mux servers. After the reconnect_window time (if any) runs out, the Live Stream will transition to a status of idle.

IMPORTANT

Mux automatically disconnects clients after 12 hours.
Contact us if you require longer live streams.

Live Streaming


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.