RTMP Streaming & Recording

Want to preserve your video call for posterity in a recording? Or live stream it out to millions of viewers on Twitch or YouTube or whatever gives you an RTMP ingest URL?

Turn on RTMP Streaming or Recording!

In 100ms, recording and streaming is usually achieved by having a bot join your room and stream what it sees and hears to a file (recording) or an RTMP ingest URL (streaming).

Types of Recordings

Apart from the RTMP stream and the browser recording, there is also a Server Recording, which can be turned on for the room.

- Server Recording

This is used for archival purposes and cannot be stopped by method calls from SDK. This can only be enabled/disabled from the dashboard. This represents that the room was set to be recorded when it was created and all sessions within it will always be recorded for archival by the server.

- Browser Recording

This is a normal recording that can be enabled/disabled using HMSSDK instance method startRTMPOrRecording with record property set to true.

RTMP Streaming & Recording

The topics covered in this doc are:

  1. How to start streaming / recording.
  2. How to stop streaming / recording.
  3. How to check the current status for streaming / recording.
  4. When to check the current status

Permissions

Can't let just anyone record and stream room audio and video. First, you need to create a role with the permissions to record and stream room.

You can check if you (local peer) have permission to record and stream room as follows -

const localPeer = await hmsInstance.getLocalPeer(); // Permissions are available on `HMSRole` object of Local Peer const localPeerPermissions: HMSPermissions = localPeer.role?.permissions; // Check if Local Peer has Room Recording Permission const canRecord: boolean = localPeerPermissions?.browserRecording; // Check if Local Peer has Room Streaming Permission const canStream: boolean = localPeerPermissions?.rtmpStreaming;

Start Streaming / Recording

Let's understand the process by following steps:

Create an HMSRTMPConfig instance

HMSRTMPConfig object will be used to start the Room recording and streaming.

import { HMSRTMPConfig } from '@100mslive/react-native-hms'; const roomJoinLink = 'https://...app.100ms.live/streaming/meeting...'; const recordingConfig = new HMSRTMPConfig({ meetingURL: `${roomJoinLink}/viewer?token=beam_recording`, rtmpURLs: [], record: true });

Let's look at how HMSRTMPConfig object looks like -

interface HMSRTMPConfig { meetingURL?: string; rtmpURLs?: string[]; record: boolean; resolution?: HMSRtmpVideoResolution; }
  1. meetingURL: string | undefined, The URL that the 100ms bot user will open to join your room. It must allow access without any user-level interaction. It is an optional parameter.

  2. rtmpURLs: string[] | undefined, If streaming is required, this has to be one or more RTMP Ingest URLs with a max limit of 3 URLs where the stream should go. If only recording, this can be an empty list.

    • Format: rtmp://server.com/app/STREAM_KEY
    • Example: rtmp://a.rtmp.youtube.com/live2/k0jv-329m-1y7f-ktth-ck48
      • "rtmp://a.rtmp.youtube.com/live2/" - RTMP stream URL.
      • "k0jv-329m-1y7f-ktth-ck48" - RTMP stream key.
  3. record: boolean, If the recording is required, set it true. If the recording is not required, set it to false. This value does not affect streaming.

  4. resolution: HMSRtmpVideoResolution, An optional value for the output resolution of the stream. For instance, the default is a landscape at 1280x720 but this could be set for a portrait mode to 720x1280 or smaller values like 480x80. The HMSResolution class takes width and height.

Key Notes

  • If both rtmpURLs and record = true are provided, both streaming and recording will begin.
  • If only rtmpURLs are provided, only streaming will begin.
  • If only record = true is provided, only recording will begin.

If either one is started, the other can't be started without first stopping whatever is running.

Eg: If only streaming is started then recording can't be started unless streaming is stopped first.

If both are required, they have to be started together by providing both rtmpURLs and record = true.

Call method on HMSSDK instance

After creating config (HMSRTMPConfig) object, You can use startRTMPOrRecording method available on HMSSDK instance to start the RTMP Streaming and Recording as follows -

Make sure you have above mentioned permissions for starting RTMP streaming and recording.

try { // Calling `startRTMPOrRecording` with config created in above step await hmsInstance.startRTMPOrRecording(recordingConfig); console.log('Start Recording Success'); } catch (error) { console.log('Start Recording Error: ', error); }

Stop Streaming / Recording

You can use stopRtmpAndRecording method available on HMSSDK instance to stop the RTMP Streaming and Recording.

Make sure you have above mentioned permissions for stopping RTMP streaming and recording.

try { await hmsInstance.stopRtmpAndRecording(); console.log('Stop Recording Success'); } catch (error) { console.log('Stop Recording Error: ', error); }

Current Room Status

The current status for the room is always reflected in the HMSRoom object which we can get from getRoom method available on HMSSDK instance or HMSUpdateListenerActions.ON_ROOM_UPDATE event.

This can be used to show the stream or recording status on UI something similar to this:

stream-state

Here are the relevant properties inside the HMSRoom object which we can read to get the current recording/streaming status of the room:

  • rtmpHMSRtmpStreamingState - Contains info about RTMP Streaming, running attribute if true indicates streaming is ON currently
  • browserRecordingState - Contains info about Browser Recording, running attribute if true indicates browser recording is ON currently
  • serverRecordingState - Contains info about Server Recording, running attribute if true indicates server recording is ON currently

Each of them is an object which contains a boolean running which lets you know if it's active in the room right now and error which lets you know if there was an error.

  1. rtmpHMSRtmpStreamingState is an instance of HMSRtmpStreamingState, which looks like:
interface HMSRtmpStreamingState { running: boolean; // `true` indicates that RTMP streaming is running error?: HMSException; // Gets populated if there is some error in starting the stream or recording startedAt: Date; // time at which RTMP streaming was started stoppedAt: Date; // time at which RTMP streaming was stopped state: HMSStreamingState; // indicates the current state of RTMP Streaming }

HMSStreamingState is a enum which can have the following values:

enum HMSStreamingState { NONE, STARTING, STARTED, STOPPED, FAILED, }
  1. browserRecordingState is an instance of HMSBrowserRecordingState, which looks like:
interface HMSBrowserRecordingState { running: boolean; // `true` indicates that browser recording is running error?: HMSException; // Gets populated if there is some error in starting the browser recording startedAt: Date; // time at which browser recording was started stoppedAt: Date; // time at which browser recording was stopped state: HMSRecordingState; // indicates the current state of Browser Recording }
  1. serverRecordingState is an instance of HMSServerRecordingState, which looks like:

This represents that the room was set to be recorded when it was created and all sessions within it will always be recorded for archival by the server.

interface HMSServerRecordingState { running: boolean; // `true` indicates that server recording is running error?: HMSException; // Gets populated if there is some error in starting the server recording startedAt: Date; // time at which server recording was started state: HMSRecordingState; // indicates the current state of Server Recording }

Here is a listing of all possible values for HMSRecordingState -

enum HMSRecordingState { NONE, STARTING, STARTED, PAUSED, RESUMED, STOPPED, FAILED, }

When to check for room status

The room status should be checked in any of the following ways -

  1. Inside onJoinListener function which is subscribed to HMSUpdateListenerActions.ON_JOIN event
  2. Inside onRoomListener function which is subscribed to HMSUpdateListenerActions.ON_ROOM_UPDATE event
  3. When hmsInstance.startRTMPOrRecording(recordingConfig) is called
  4. When hmsInstance.stopRtmpAndRecording() is called
  • In the above mentioned onJoinListener & onRoomListener functions, The properties mentioned above will be on the HMSRoom object.
  • Whenever either of the startRTMPOrRecording or stopRtmpAndRecording functions are called, the values of the streaming and recording will be updated on the room object available in onRoomListener function. So, You should update the instance of HMSRoom in your application at that time.

Have a suggestion? Recommend changes ->

Was this helpful?

1234