Create live-streaming-rtmp-ingestion.mdx

docs/server-side/v2/how-to-guides/live-streaming-rtmp-ingestion.mdx

@@ -0,0 +1,169 @@
+---
+title: Live Streaming using RTMP Ingestion
+nav: 8
+---
+
+This guide will help you to start a live stream in 100ms from OBS or any external broadcasting application over RTMP. 
+
+
+<StepsToc
+    parentId="rtmp-ingestion-flow"
+    descriptions={[
+        "Setting up your template for RTMP-In Live Stream experience.",
+        "Generating RTMP Stream Key and RTMP URL for your room(s).",
+        "Inputting stream details in your broadcasting software.",
+        "Starting, interacting, and ending your live streams."
+    ]}
+/>
+
+<StepsContainer id="rtmp-ingestion-flow">
+
+### Create a Template
+
+1. On the 100ms Dashboard, click on ‘Create Template’.
+
+![create template](/docs/v2/create-a-template.png)
+
+2. Select ‘Live Streaming’ as your use-case and click on ‘Configure’.
+3. Proceed through the steps by answering the questions according to your preferences.
+
+Follow the detailed guide available [here](/get-started/v2/get-started/features/live-streaming#get-started-with-prebuilt-no-code) to create a live streaming template.
+
+  {/* The first step is to create a template which is suitable for media ingestion through RTMP followed by live streaming through HLS.
+1. On the 100ms Dashboard, click on ‘Create Template’.
+2. Select ‘Live Streaming’ as your use-case and click on ‘Configure’.
+3. Choose the "RTMP-In (External)" option when asked, "Where will the Broadcaster stream from?". Then, proceed to the "Select Add-ons" section.
+4. Proceed through the rest of the steps by answering the questions according to your preferences.
+5. On the last screen, the RTMP Ingest details (stream key and RTMP Endpoint) are displayed for the default room created for the template. [Input the stream key](ksdf), share the viewer role link and start your stream.  */}
+
+
+> **Note on editing an existing templates (Not recommended)**
+> 
+> Live Streaming over RTMP In can also be enabled on creating new rooms with existing templates that have live streaming enabled. RTMP Stream keys can be generated on these  rooms using the steps mentioned below. However, this is not recommended as other modifications need to be made for the broadcaster role to join the room without going live from the browser. 
+> 
+
+### Getting stream details
+
+Since the live stream is started for a specific room, a room needs to be created using the [Create Room API](/server-side/v2/api-reference/Rooms/create-via-api) or through the [100ms Dashboard](/server-side/v2/api-reference/Rooms/create-via-dashboard). Once a room is created, a stream key needs to be generated for the room. Using the stream key and the RTMP Ingest end point, any third party application can send a media stream to the room over RTMP. Once a stream key is generated, it remains valid until explicitly reset or disabled by the user.
+
+Stream key along with RTMP Ingest Endpoint for a room can be generated and fetched using the below steps.
+
+{/*
+**Using the** **Dashboard**
+    1. On 100ms, dashboard, click on ‘Create Room’ and configure the room name and template settings. 
+    2. Continue to create a new room based on the selected template.
+    3. In Join your room panel, Click on ‘Stream Details’ under ‘Go live using RTMP Ingest’ section to generate and access the stream key and RTMP URL.
+
+**Room Details Page** 
+
+1. In the **‘Rooms’** section, navigate to the ‘Room Details’ page by clicking on the specific room name or room ID.
+2. For the specific room, the RTMP Stream Key and RTMP URL will be available. In case they are not, you can create them by clicking the ‘Generate’ button.
+3. Existing stream key can be reset or disabled at any time using the options here. The new stream key will take effect from the subsequent RTMP Ingest connections. 
+
+To navigate to all the rooms under a particular template, click on ‘Templates’ section in the left menu on 100ms Dashboard and go to the desired template. Use the overflow menu in the top right to view all rooms under that template. 
+
+> **Note on disabled rooms**
+>
+> Stream keys and RTMP URL cannot be generated for disabled rooms. Learn more about managing room statuses [here](/server-side/v2/api-reference/Rooms/disable-or-enable).
+*/}
+
+<Tabs id="fetching-stream-details" items={['REST APIs']} />
+<Tab id='fetching-stream-details-0'>
+
+1. Use the [Create Stream Key API](/server-side/v2/api-reference/stream-key/create-rtmp-stream-key) to create the stream key for a specific room. 
+
+2. Existing stream key for a room can be fetched using the [Get Stream Key API](/server-side/v2/api-reference/stream-key/get-rtmp-stream-key).  
+
+3. In case the stream key is compromised or not to be used again, it can be disabled using the [Disable Stream Key API](/server-side/v2/api-reference/stream-key/disable-rtmp-stream-key). Alternatively, a room can be disabled which deactivates its linked stream key. Enabling the room reactivates the linked stream key.
+
+</Tab>
+
+> **Note**
+>
+> There is a possibility that RTMP Endpoint might change for the specified room.  We recommend fetching the stream key details using the [Get Stream Key API] (/server-side/v2 api-reference/stream-key/get-rtmp-stream-key) each time before starting a new stream in any room.  
+>
+
+### Input stream details
+We’re using the example of OBS Studio although you can use any software that supports RTMP-Out.
+
+1. Click on ‘**Settings**’ in the software interface.
+
+![obs studio interface](/docs/v2/obs-studio-interface.png)
+
+2. Click on ‘Stream’ and input RTMP URL in the ‘Server’ field and the stream key in the ‘Stream Key’ field.
+
+![obs studio stream settings](/docs/v2/obs-studio-stream-settings.png)
+
+3. Click on ‘OK’ to confirm the details.
+
+Refer to [this guide](https://obsproject.com/kb/) to set up OBS Studio for the desired experience.
+
+### Managing the live stream
+
+#### Starting the live stream
+Start your live stream directly from the broadcasting software. In case of OBS Studio, click on the ‘Start Streaming’ button under ‘Controls’ to begin the live stream. 
+
+![obs studio start live stream](/docs/v2/obs-studio-start-live-stream.png)
+
+> **Note on starting the live stream**
+> 
+> While starting a live stream with RTMP Ingest, do not use ‘Start live stream’ API or SDK functionality. The live stream will commence automatically upon a successful connection to 100ms Ingest servers by OBS or the external application.
+>
+
+Once the RTMP connection request is initiated from OBS/external application, the following web hooks will be dispatched to indicate the progression of the live stream. 
+
+| Web hook                                                                                                | What does it signify                                                                                                                                                                                 |
+|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`ingest.start.success`](/server-side/v2/how-to-guides/configure-webhooks/webhook#ingeststartsuccess)   | Connection with 100ms Ingest server is successfully established. Our server will internally initiate a request to start a live stream on the room.                                                   |
+| [`hls.started.success`](/server-side/v2/how-to-guides/configure-webhooks/webhook#hlsstartedsuccess)     | Live stream on the room has successfully started. Playback is active from this point onwards. Application can enable the viewer to join the room with the viewer role.                               |
+| [`ingest.start.failure`](/server-side/v2/how-to-guides/configure-webhooks/webhook#ingestfailure)        | Connection with 100ms Ingest server has failed. The exact reason can be inferred from the error code and error message                                                                               |
+| [`hls.failure`](/server-side/v2/how-to-guides/configure-webhooks/webhook#hlsfailure)                    | Any internal failure in the live stream start up process.                                                                                                                                            |
+| [`ingest.end.success`](/server-side/v2/how-to-guides/configure-webhooks/webhook#ingestendsuccess)       | Connection with 100ms Ingest has successfully terminated. This is sent on stopping the stream from OBS / external application. Our server will internally signal to stop the live stream on the room |
+| [`hls.stopped.success`](/server-side/v2/how-to-guides/configure-webhooks/webhook#hlsstoppedsuccess)     | Live Stream has stopped. Playback is not active from this point onwards                                                                                                                              |
+| [`hls.recording.success`](/server-side/v2/how-to-guides/configure-webhooks/webhook#hlsrecordingsuccess) | Recording for the live stream is successfully generated                                                                                                                                              |
+
+> **Previewing your live stream**
+> 
+> There is no built-in functionality is available to preview the stream as of now. However, you can preview and watch along by joining in through the `viewer` role.
+>
+
+#### Interactivity during live stream
+The interactivity between the broadcaster and the viewers will be very limited in case of RTMP-In live streams since there is no interface apart from 
+
+1. On-stage and off-stage functionality is not supported. Since the media is ingested from an external source and directly streamed through HLS, the viewers of the HLS stream will not be able to see anything going inside the conferencing (WebRTC) room. This feature is meant for a one-way broadcast from a single broadcaster to an audience
+2. The peers in the conferencing (WebRTC) room (if any) will not be able to watch the incoming RTMP-Ingested media stream.
+3. The `broadcaster` role created for the given template can chat with the viewers, but the experience will be sub-optimal as the stream is running couple of seconds delayed.
+
+#### Ending the live stream
+To instantly terminate the live stream, use 100ms SDK methods or [REST APIs](/server-side/v2/api-reference/live-streams/stop-live-stream-for-room), 
+
+On stopping the stream from OBS/external streaming application, only the RTMP connection to 100ms Ingestion servers will terminate. Note that this will merely stop the ingest from the external streaming application into 100ms room. **The live stream will NOT end** and continue to run with a disconnected slate shown in the playback until the reconnection window expires. The same behaviour applies when the external streaming application faces disconnection with 100ms Ingest servers due to any network interruptions.
+
+![disconnection slate](/docs/v2/disconnection-slate.png)
+
+The duration of  the live stream’s reconnection window can be configured using the `autoStopTimeout` field in the [Policy API](/server-side/v2/api-reference/policy/create-template-via-api).  After the reconnect window elapses, the live stream will be terminated automatically.
+
+> **Note**
+> 
+> Any new RTMP connection initiated from OBS/ external streaming application within the live stream’s reconnect window will be treated as a reconnection of ingest to the existing live stream. Once the reconnection is established successfully,  the disconnection slate in the live stream will be replaced with the incoming feed from the broadcaster. 
+>
+
+
+#### After the live stream
+Based on your live streaming use-case, you can choose to do any of the following after the live stream has ended.
+- Continue using the same room for your live streams. The older stream key and RTMP URL will be valid to start future live streams as well since they do not have an expiry.
+- Create a new stream key but continue using the same room. You can reset stream key by:
+    1. Disabling it by using the [Disable Stream Key API](/server-side/v2/api-reference/stream-key/disable-rtmp-stream-key).
+    2. Regenerating a new stream key using the [Create Stream Key API](/server-side/v2/api-reference/stream-key/create-rtmp-stream-key).
+
+{/*Effectively, there are two methods to reset or regenerate a new stream key.*/}
+
+- Disable the stream key or lock / disable the room.
+    1. Disabling the stream key by using the [Disable Stream Key API](/server-side/v2/api-reference/stream-key/disable-rtmp-stream-key).
+    2. Disabling the room by either using 100ms dashboard or by using the [Disable / Enable Room API](/server-side/v2/api-reference/Rooms/disable-or-enable).
+
+{/* This can be accomplished using following two methods.*/}
+
+
+</StepsContainer>
+