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 to an RTMP ingest URL (streaming).

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

Starting Streaming / Recording

To start recording, streaming or both, create an instance of HMSRecordingConfig.

HMSRecordingConfig takes the following:

1. meetingUrl: String. The URL the 100ms bot user will open to join your room. It must allow access without any user level interaction.

2. rtmpUrls: List<String>. 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.
   • Please refer to the platform specific documentation for details on how to obtain the stream URL and stream key. Here are some examples:
     • YouTube
     • Facebook
     • Instagram
     • Twitch
     • LinkedIn

3. record: Boolean. If recording is required, set true. If recording is not required, set false. This value has no effect on streaming.

4. resolution: HMSRtmpVideoResolution. An optional value for the output resolution of the stream. For instance default is landscape at 1280x720 but this could be set for a portrait mode of 720x1280. Or smaller values like 480x80.

The HMSRtmpVideoResolution takes Width and Height.

• 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: Only streaming is started. Recording can't be started unless streaming is stopped first.

If both are required, they have to be started together by providing both RTMP ingest Urls and recording = true.

The result of the action is sent in the callback for HMSActionResultListener. An attempt to start streaming/recording which is successful then onSuccess will be called. On failure to start then an error will be sent in onError(error: HMSException).

hmsSdk.startRtmpOrRecording(hmsRecordingConfig, object : HMSActionResultListener {

    override fun onSuccess() {
        // started successfully
    }

    override fun onError(error: HMSException) {
        // an error occurred
    }
 }
)

hmsSdk.startRtmpOrRecording(hmsRecordingConfig, new HMSActionResultListener() {
    @Override
    public void onSuccess() {
        // started successfully
    }

    @Override
    public void onError(@NonNull HMSException e) {
        // an error occurred
    }
});

Stopping Streaming / Recording

To stop streaming AND recording. It is not currently possible to stop just one, whatever is running will be stopped.

Here's how to stop both:

The stopRtmpAndRecording only takes a single parameter, a callback for HMSActionResultListener. An attempt to stop streaming and recording which is successful then onSuccess will be called. On failure to stop then an error will be sent in onError(error: HMSException).

hmsSdk.stopRtmpAndRecording(object : HMSActionResultListener {

    override fun onSuccess() {
        // Stop succeeded.
    }

    override fun onError(error: HMSException) {
        // Error while stopping.
    }

})

hmsSdk.stopRtmpAndRecording(new HMSActionResultListener() {
    @Override
    public void onSuccess() {
        // Stop succeeded.
    }

    @Override
    public void onError(@NonNull HMSException e) {
        // Error while stopping.
    }
});

Current Room Status

The current status for the room is always reflected in the HMSRoom object that is returned from the HMSUpdateListener.

Here are the relevant properties inside the HMSRoom object which you can read to get the current recording/streaming status of the room namely: rtmpHMSRtmpStreamingState, browserRecordingState, serverRecordingState and hlsStreamingState.

Each of them (except HLS) are objects which contain a boolean running which lets you know if it's active on the room right now and error which lets you know the details of an error if one occurred, and startedAt which contains a UNIX epoch timestamp of when the stream began.

Apart from the RTMP stream and the browser recording, which are ones you can start and stop, there is also a serverRecording, which can be turned on for the room for archival purposes and which cannot currently be stopped if enabled for the room from the dashboard. HLS streaming can be started as well.

1. rtmpHMSRtmpStreamingState an instance of HMSRtmpStreamingState, which looks like:

data class HMSRtmpStreamingState(
    val running : Boolean,
    val error : HMSException?,
    val startedAt: Long?,
    val stoppedAt: Long?
)

This represents a livestream to one or more RTMP urls.

startedAt is the UNIX epoch timestamp of when this recording was started.

stoppedAt is the UNIX epoch timestamp of when the recording was ended.

Both may be present and this means the recording was started at some point and stopped at a later date. If the recording is then restarted, it's possible for the stoppedAt to be before the startedAt.

2. browserRecordingState an instance of HMSBrowserRecordingState, which looks like:

data class HMSBrowserRecordingState(
    val running : Boolean,
    val error : HMSException?,
    val startedAt: Long?,
    val stoppedAt: Long?
)

This represents the recording that can be requested to start.

startedAt is the UNIX epoch timestamp of when this recording was started.

stoppedAt is the UNIX epoch timestamp of when the recording was ended.

Both may be present and this means the recording was started at some point and stopped at a later date. If the recording is then restarted, it's possible for the stoppedAt to be before the startedAt.

3. serverRecordingState an instance of HMSServerRecordingState, which looks like:

data class HMSServerRecordingState(
    val running : Boolean,
    val error : HMSException?,
    val startedAt: Long?
)

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.

startedAt is the UNIX epoch timestamp of when this recording was started. However server-side has a special case for recording. It is considered started when the current room's session has begun. A session is defined as the time from which the room goes from zero peers in it, to one, until the time at which the room contains no peers. (note: beam bots which join for recording will leave after a timeout if no other peers are present.)

Because the server side recording always begins when there's someone in the room the room creation time and this recording type's start time will be the same. Also there can't be a stoppedAt since that would mean the room has ended.

When to check for room status

As of SDK version 2.2.2, the room status can be checked when any of the three events of type HMSRoomUpdate in HMSUpdateListener appear:

• HMSRoomUpdate.SERVER_RECORDING_STATE_UPDATED,
• HMSRoomUpdate.RTMP_STREAMING_STATE_UPDATED
• HMSRoomUpdate.BROWSER_RECORDING_STATE_UPDATED

The properties mentioned above will be on the HMSRoom object.

• The values of the streaming and recording will be updated on the room object returned in onJoin. So saving an instance of the room received at that time is recommended.

Code sample

Refer to the code example within the 100ms advanced sample app for further information.