From b0847bdab753ae30a0b37d2b50a62907b48d9029 Mon Sep 17 00:00:00 2001 From: Aswinraaj23 Date: Tue, 17 Oct 2023 17:46:36 +0530 Subject: [PATCH] Add documentation to schedule live stream --- docs/server-api/live-stream.md | 161 +++++++++++++++++++++++++++++---- 1 file changed, 142 insertions(+), 19 deletions(-) diff --git a/docs/server-api/live-stream.md b/docs/server-api/live-stream.md index 6f4226b7..d1eba814 100644 --- a/docs/server-api/live-stream.md +++ b/docs/server-api/live-stream.md @@ -4,12 +4,15 @@ sidebar_position: 4 # Live Streams -- A live stream is a real-time video broadcast delivered through a streaming platform.This endpoint creates an live stream allowing users to ingest media content into the TP Streams system for processing and delivery. +- A live stream is a real-time video broadcast delivered through a streaming platform. You can create live streams, allowing users to ingest media content into the TP Streams system for processing and delivery. +- With the TP Streams system, you have the ability to create live streams in two distinct ways: -## Create a live stream +1. [Create a live stream instantly](../server-api/live-stream.md#create-a-live-stream-instantly) +2. [Schedule live streams and start them later](../server-api/live-stream.md#schedule-a-live-stream-and-start-the-server-later) -To Create a live stream you need to send an HTTP POST request to the API Endpoint, with the [authentication Header](../server-api/authentication.md). +## Create a live stream instantly +To Create a live stream instantly you need to send an HTTP POST request to the API Endpoint, with the [authentication Header](../server-api/authentication.md). ```bash @@ -52,51 +55,135 @@ For valid requests the API server returns a JSON: "parent_id": null } ``` -To notify your application about things that happen asynchronously [Create a Web Hook](../server-api/webhooks.md). +:::important + +- The live stream server typically takes around 20-30 seconds to start. +- Once it's up and running, both the "rtmp_url" and "stream_key" will become accessible. + + +::: +To automatically receive rtmp_url and stream key as soon as the server is established,[Create a Web Hook](../server-api/webhooks.md). After successfully registering the webhook, you will receive an updated webhook response. +## Schedule a live stream and start the server later +### Schedule a live stream +To Schedule a live stream you need to send an HTTP POST request to the API Endpoint, with the [authentication Header](../server-api/authentication.md). + + +```bash +https://app.tpstreams.com/api/v1//assets/live_streams/ +``` + +**Fields** + +| Name | Type | Description | Required | +| ----------- | ----------- | ----------- | ---------- | +| title | string | Specify a text string or identifier which can be used for filtering or searching the live stream.| Yes | +| start | string | Specify the date and time (in the format: "YYYY-MM-DD HH:MM:SS") when the live stream should be scheduled.| Yes | + +**Sample request body** + +```json +{ + "title": "Data science Live class", + "start": "2024-10-05 15:30:00" +} + +``` + +For valid requests the API server returns a JSON: + +```json +{ + "title": "Data science Live class", + "bytes": null, + "type": "livestream", + "video": null, + "id": "AuC9yX2EtBr", + "live_stream": { + "rtmp_url": "", + "stream_key": null, + "status": "Not Started", + "hls_url": "https://d28qihy7z761lk.cloudfront.net/live/gnarys/AuC9yX2EtBr/video.m3u8", + "start": "2024-10-05 15:30:00", + "transcode_recorded_video": true, + "enable_drm": false, + "chat_embed_url": null, + "resolutions": [ + "240p", + "480p", + "720p" + ] + }, + "parent": null, + "parent_id": null +} +``` +Live stream is created with the scheduled time for you to start the server later. + +Above response has the details of the live stream scheduled which can also be obtained by API +**/api/v1//assets//** :::important -To fetch the RTMP URL and stream key, you need to wait for the status to change to "Available." Once the status changes, you will receive the required information via a webhook. +- Scheduled live streams will not automatically start at the specified time; they must be manually initiated. +- RTMP URL and stream key will be available once you start the stream + ::: -## WebHook Response -Whenever the status of live stream changes, response will be sent to the webhook. +### Start the server for the scheduled live stream +To Start a server for the scheduled live stream you need to send an HTTP POST request to the API Endpoint, with the [authentication Header](../server-api/authentication.md). + + +```bash +https://app.tpstreams.com/api/v1//assets//start_server/ +``` +For valid requests the API server returns a JSON: -**Sample webhook response is as follows** ```json { "title": "Data science Live class", "bytes": null, "type": "livestream", "video": null, - "id": "4PtERT9d9uK", + "id": "8XGEEj6ptnB", "live_stream": { - "rtmp_url": "rtmp://23.427.127.24/live", - "stream_key": "org-4xu8ay-live-4PtERT9d9uK-jKP4", - "status": "Available", - "hls_url": "https://d28qihy7z761lk.cloudfront.net/live/4xu8ay/4PtERT9d9uK/video.m3u8", - "start": null, + "rtmp_url": "", + "stream_key": null, + "status": "Not Started", + "hls_url": "https://d3cydmgt9q030i.cloudfront.net/live/edee9b/8XGEEj6ptnB/video.m3u8", + "start": "2024-10-05 15:30:00", "transcode_recorded_video": true, - "chat_embed_url":"https://app.tpstreams.com/live-chat/4PtERT9d9uK/" + "enable_drm": false, + "chat_embed_url": "https://app.tpstreams.com/live-chat/edee9b/8XGEEj6ptnB/", + "resolutions": [ + "240p", + "480p", + "720p" + ] }, + "parent": null, "parent_id": null } ``` -After getting the rtmp_url and stream_key paste it in the obs stream settings **Settings > Stream** - +This will start the server for specified live stream +Above response has the details of the live stream started which can also be obtained by API +**/api/v1//assets//** +:::important +- The live stream server typically takes around 20-30 seconds to start. +- Once it's up and running, both the "rtmp_url" and "stream_key" will become accessible. - ![OBS settings](/img/obs.png) +::: +To automatically receive rtmp_url and stream key as soon as the server is established,[Create a Web Hook](../server-api/webhooks.md). +After successfully registering the webhook, you will receive an updated webhook response. ## Stop a live stream - To Stop a live stream you need to send an HTTP POST request to the API Endpoint, with the [authentication Header](../server-api/authentication.md). @@ -152,3 +239,39 @@ If the value of the parameter "transcode_recorded_video" is set to true, you wil "parent_id": null } ``` + + +## WebHook Response +Upon a successful creation of live stream, to notify your application about things that happen asynchronously , +[Create a Web Hook](../server-api/webhooks.md). + +After successfully registering the webhook, whenever the status of live stream changes, response will be sent to the webhook. + +**Sample webhook response for livestream is as follows** +```json +{ + "title": "Data science Live class", + "bytes": null, + "type": "livestream", + "video": null, + "id": "4PtERT9d9uK", + "live_stream": { + "rtmp_url": "rtmp://23.427.127.24/live", + "stream_key": "org-4xu8ay-live-4PtERT9d9uK-jKP4", + "status": "Available", + "hls_url": "https://d28qihy7z761lk.cloudfront.net/live/4xu8ay/4PtERT9d9uK/video.m3u8", + "start": null, + "transcode_recorded_video": true, + "chat_embed_url":"https://app.tpstreams.com/live-chat/4PtERT9d9uK/" + }, + "parent_id": null +} +``` +After getting the rtmp_url and stream_key paste it in the obs stream settings **Settings > Stream** + + + + + + + ![OBS settings](/img/obs.png)