Skip to content

Latest commit

聽

History

History
178 lines (124 loc) 路 9.76 KB

rtmp-streaming-and-browser-recording.mdx

File metadata and controls

178 lines (124 loc) 路 9.76 KB
Raw
title nav
RTMP Streaming & Browser Recording
11

import RtmpExternalConfig from '@/common/rtmp-external-config.md';

Introduction

RTMP Streaming can be used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, MUX, etc. Browser Recording can be used to record your video conferencing apps to a file, for subsequent access. You can start either RTMP Streaming or Browser Recording or both for any room

Pre-requisites

  1. Management token

  2. Single click meeting URL to directly enter a room

  3. 100ms SDK logs should be logged to console for the web-app URL provided above. The SDK logs will be analysed to detect any room join failures and retries will be attempted to fix the same. If SDK logs are not enabled then the server will stop recording/streaming and return error (after fixed number of retries).

APIs

Start Streaming/Recording

curl \
    --location \
    --request POST 'https://prod-in2.100ms.live/api/v2/beam' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <management_token>' \
    --data-raw '{
        "operation": "start",
        "room_id": <rooom_id>,
        "meeting_url": <meeting_url>,
        "rtmp_urls": [<rtmp_url_1>, <rtmp_url_2>],
        "record": true,
        "resolution" : {"width": 1280, "height": 720}
    }'

Note: Please use https://prod-us2.100ms.live/api/v2/beam or https://prod-eu2.100ms.live/api/v2/beam as API endpoint if your room's region is US or EU.

Headers

Name Value Required
Content-type
application/json Yes
Authorization
Bearer <management token> Yes

Body Parameters

Name Type Description Required
operation
string Must be "start" Yes
room_id
string The room id of the room which we need to start streaming/recording Yes
meeting_url
string Single click meeting URL which we need to start streaming/recording (see below for more details) Yes
rtmp_urls
array List of RTMP output URLs to which the meeting will be streamed.
Required when RTMP streaming needs to be started.
Supports up to 3 rtmp:// / rtmps:// urls		 No
record
bool Flag to enable browser recording No
resolution
object Video resolution for streaming/recording No
meeting_url

This is a URL which lands into the meeting directly. If you are using 100ms apps then this will be like - https://<domain>.app.100ms.live/preview/<room_id>/<role>?skip_preview=true.

Please check the following to understand how these params are useful while starting RTMP streaming or browser recording with 100ms app links:

  • skip_preview=true: skips the preview page and directly joins the meeting with header and controls disabled.
  • skip_preview_headful=true: skips the preview page and directly joins the meeting with header and controls enabled.
  • auth_token=token1234: Use this to pass the auth token to authenticate the room join request for the beam bot to join the web app to start recording.
  • ui_mode=activespeaker: opens active speaker mode by default for recording. In active speaker mode, the current speaker will show up in the center, and rest of the peers will show up in the sidebar.
  • name=johndoe: Use this to add a name for the respective peer.

Example - https://myname.app.100ms.live/preview/61101349d0f56e684b608c08/__internal_recorder?skip_preview=true&auth_token=token1234&ui_mode=activespeaker

Note: Ensure meeting_url belongs to the room_id so that beam is aware of the meeting session.

rtmp_urls

This URL is the combination of RTMP server URL and stream key. You can add up to 3 RTMP URLs (as array of strings) for this argument.

  • 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.
resolution

Minimum Resolution supported from 500x480 (in landscape mode) and 500x500 (in portrait mode) Maximum Resolution supported up to 1920x1080 (in landscape mode) and 1080x1920 (in portrait mode)

Name Type Description Required
width
int Width of the video.
Range: 500-1920. If height>1080 then max width=1080.
Default: 1280		 Yes
height
int Height of the video.
Range: 480-1920. If width>1080 then max height=1080.
Default: 720		 Yes

Stop Streaming/Recording

curl \
    --location \
    --request POST 'https://prod-in2.100ms.live/api/v2/beam' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <management_token>' \
    --data-raw '{
        "operation": "stop",
        "room_id": <rooom_id>
    }'

Headers

Name Value Required
Content-type
application/json Yes
Authorization
Bearer <management token> Yes

Body Paramters

Name Type Description Required
operation
string Must be "stop" Yes
room_id
string The room id of the room for which we need to stop streaming/recording Yes

Error messages in RTMP API

Message Code Description
Error: beam already started 1 RTMP streaming or Recording already running for the room
Error: internal server error 2 server error
Error: room_id missing 3 room id is missing in the request payload
Error: room_id invalid 4 Room id provided is invalid
Error: rtmp_url and record missing 5 RTMP URLs or record flag is required
Error: meeting_url missing 6 Meeting URL is missing in the request payload
Error: meeting_url invalid 7 Meeting URL is invalid
Error: operation invalid 8 Operation provided is invalid
Error: operation missing 9 Operation field is missing in the request payload
Error: no active beam found for the passed in identifiers 10 No Active beam running in the room
Error: Resolution not supported 11 Input Resolution not Supported

Recording upload destination

By default recordings will be uploaded to 100ms storage and a pre-signed URL for the same will be provided to customers via a webhook. The pre-signed URL will expire in 12 hours. Customers can also configure the recordings to be stored in their cloud storage. The configuration for the same can be provided when creating the room.

Create Room

Recording mp4 will be placed at - <upload_type>://<location>/<prefix>/beam/<room_id>/<start_date>/Rec-<room_id>-<epoch>.mp4. Example s3://test-bucket/test-prefix/beam/61101349d0f56e684b608c08/20210721/Rec-61101349d0f56e684b608c08-1626898422000.mp4