From f2e249d2ce8faec711f95be46abcba01ff08a2fd Mon Sep 17 00:00:00 2001
From: szekelyzol <szekelyzol@gmail.com>
Date: Wed, 17 Jul 2024 00:18:37 +0200
Subject: [PATCH 1/2] Add RTMPS streaming protocol to docs
---
live-streaming/create-a-live-stream.md | 6 ++--
live-streaming/live-stream-best-practices.md | 31 +++++++++++---------
live-streaming/restreams.md | 14 +++++----
openapi.yaml | 12 ++++----
4 files changed, 35 insertions(+), 28 deletions(-)
diff --git a/live-streaming/create-a-live-stream.md b/live-streaming/create-a-live-stream.md
index a20e840a..0df38b1b 100644
--- a/live-streaming/create-a-live-stream.md
+++ b/live-streaming/create-a-live-stream.md
@@ -13,7 +13,7 @@ Creating a live stream is simple with api.video. After you create it, you have a
This guide helps you follow along with the video and learn how to set up your live stream with api.video, and then use OBS to broadcast.
<Callout pad="2" type="info">
-api.video supports both `RTMP` and `SRT` protocols for live streaming.
+api.video supports `RTMPS`, `RTMP`, and `SRT` protocols for live streaming.
</Callout>
## API reference
@@ -191,9 +191,11 @@ In this example, we will use [OBS Studio](https://obsproject.com), which is an o
1. Open OBS and go to File and then Settings. In the Settings menu, go to **Stream**.
-2. Next, you have to set up the streaming service provider. With api.video, you have the option to choose between `RTMP` and `SRT` protocols for live streaming.
+2. Next, you have to set up the streaming service provider. With api.video, you have the option to choose between `RTMP`, `RTMPS`, and `SRT` protocols for live streaming.
- For `RTMP`, open the dropdown menu for Service, and select **Show all**. In the resulting list, find api.video. This will set up streaming through api.video's default `RTMP` server: `rtmp://broadcast.api.video/s`. You can find the **Stream key** in the API response you received when you created the live stream container.
+
+ - For `RTMPS`, open the dropdown menu for Service, and select **Custom**. Use this server URL: `rtmps://broadcast.api.video:1936/s`. You can find the **Stream key** in the API response you received when you created the live stream container.
- For `SRT`, open the dropdown menu for Service, and select **Custom**. Use this server URL: `srt://broadcast.api.video:6200?streamid={stream_key}` and replace `{stream_key}` with the **Stream key** in the API response that you received when you created the live stream container.
diff --git a/live-streaming/live-stream-best-practices.md b/live-streaming/live-stream-best-practices.md
index bb1169d6..d45932f8 100644
--- a/live-streaming/live-stream-best-practices.md
+++ b/live-streaming/live-stream-best-practices.md
@@ -1,5 +1,5 @@
---
-title: List Live Streams
+title: Live Stream best practices
meta:
description: This guide explains how you can make the most of your live stream implementation using best practices at api.video.
---
@@ -13,6 +13,18 @@ meta:
- In order to prevent the live stream from getting stuck (buffering indefinitely), please ensure that you are following the recommended [settings](#recommended-setting-for-ingestion).
- Make sure to verify that the connection speed is adequate and stable before the stream is starting.
+## Streaming protocols
+
+api.video supports `RTMPS`, `RTMP`, and `SRT` protocols for live streaming.
+
+## Streaming servers
+
+| Protocol | Description | Server URL |
+| -------- | ------------------------------------------ | ------------------------------------------------------ |
+| `RTMPS` | The secure streaming server. | `rtmps://broadcast.api.video:1936/s` |
+| `RTMP` | The default streaming server. | `rtmp://broadcast.api.video/s` |
+| `SRT` | The `SRT` server. | `srt://broadcast.api.video:6200?streamid={stream_key}` |
+
### SRT details
* The minimum accepted value for `latency` is 120 ms, lower values will be ignored.
@@ -20,9 +32,11 @@ meta:
### Which protocol to use
-Take network connection into consideration - if you or your users stream in stable conditions with a low risk of congestion, `RTMP` will probably achieve a better latency than `SRT`. If you or your users experience lots of buffering, or the network you use is known to be unstable, or network conditions may change like when using a mobile network, then `SRT` may be a good fit.
+First, if your project or restream destinations support `RTMPS`, api.video recommends using this protocol rather than `RTMP` for the security it provides.
+
+After this, take network connection into consideration - if you or your users stream in stable conditions with a low risk of congestion, `RTMPS` will probably achieve a better latency than `SRT`. If you or your users experience lots of buffering, or the network you use is known to be unstable, or network conditions may change like when using a mobile network, then `SRT` may be a good fit.
-Rembember that both protocols have their pros and cons - with bad network conditions, viewers might encounter buffering with `RTMP`, or they might encounter audio or visual glitches when using `SRT`.
+Remember that both protocols have their pros and cons - with bad network conditions, viewers might encounter buffering with `RTMPS`, or they might encounter audio or visual glitches when using `SRT`.
## DVR - reading history in live streams
@@ -40,17 +54,6 @@ When reaching the end of the playback, the player buffers until the live stream
Reconnection is handled by api.video, however, an edge case might occur (very slim chance), which will result in the inability to reconnect to the stream with good quality. In this case, we recommend creating a manual stream reconnection, where the streamer will create a new streaming key while the consumers will have to refresh their player instance.
-## Streaming protocols
-
-api.video supports both `RTMP` and `SRT` protocols for live streaming.
-
-## Streaming servers
-
-| Protocol | Description | Server URL |
-| -------- | ------------------------------------------ | ------------------------------------------------------ |
-| `RTMP` | The default streaming server. | `rtmp://broadcast.api.video/s` |
-| `SRT` | The `SRT` server. | `srt://broadcast.api.video:6200?streamid={stream_key}` |
-
## Recommended setting for ingestion
Video codec: H.264
diff --git a/live-streaming/restreams.md b/live-streaming/restreams.md
index 9a7baadb..c4026b76 100644
--- a/live-streaming/restreams.md
+++ b/live-streaming/restreams.md
@@ -14,7 +14,7 @@ Please note that Restreaming is currently a beta feature. The api.video engineer
If you are experiencing an issue, please do not hesitate to contact our support team.
</Callout>
-api.video gives you the ability to broadcast a live stream to multiple platforms simultaneously. You'll be able to stream to Youtube, Twitch, and any other platform that supports [RTMP](https://api.video/blog/video-trends/what-is-rtmp-and-why-do-we-use-it-for-live-streaming/) from one source.
+api.video enables you to broadcast a live stream to multiple platforms simultaneously. You can stream to Youtube, Twitch, and any other platform that supports streaming through `RTMPS` or `RTMP` protocols from one source.
## How it works
@@ -43,14 +43,14 @@ The Live stream endpoint has an optional field called `restreams` which is an ar
| Field | Type | Details |
| :---------- | :------- | :------------------------------------------------------------------------------------------------ |
| `name` | `string` | Arbitrary value for the name of the provider streaming provider. For example: `Youtube`, `Twitch` |
-| `serverUrl` | `string` | The RTMP url of the streaming server. |
+| `serverUrl` | `string` | The URL of the streaming server. The API accepts server URLs using `RTMPS` and `RTMP` protocols. |
| `streamKey` | `string` | Stream key provided by the streaming provider. |
<Callout pad="2" type="warning">
Please note that:
- Currently api.video supports up to 5 restreams
-- At this time, it's only possible to restream to RTMP
+- You can stream to `RTMPS` and `RTMP` destinations
- The names of the providers are arbitrary, you can provide any name you like
- When updating the restreams object, it's important to make sure that you are passing the previous values if you would like to keep them
- Modifying the restreams array while the live stream is already broadcasting will only take only effect after the stream has been restarted
@@ -58,14 +58,16 @@ Please note that:
## Supported Platforms
-api.video currently supports RTMP restreaming destinations. Providers that you can restream to include, and are not limited to:
+api.video currently supports `RTMPS` and `RTMP` restreaming destinations. Providers that you can restream to include, and are not limited to:
-- YouTube
+- Youtube
+- Facebook
+- Instagram
- Twitch
- LinkedIn
- Instagram (through [YellowDuck](https://yellowduck.tv/))
-Providers that use RTMPS, SRT or any other protocol (like Kick or Telegram) are currently not supported.
+Providers that use SRT or any other protocol (like Kick or Telegram) are currently not supported.
## Getting Started
diff --git a/openapi.yaml b/openapi.yaml
index 7037387e..3db11c16 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -14336,7 +14336,7 @@ components:
description: The unique identifier for the player.
example: pl4f4ferf5erfr5zed4fsdd
restreams:
- description: Use this parameter to add, edit, or remove RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations.
+ description: Use this parameter to add, edit, or remove `RTMPS` or `RTMP` services where you want to restream a live stream. The list can only contain up to 5 destinations.
maxItems: 5
type: array
items:
@@ -14367,7 +14367,7 @@ components:
description: The unique ID for the player associated with a live stream that you want to update.
example: pl45KFKdlddgk654dspkze
restreams:
- description: Use this parameter to add, edit, or remove RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations. This operation updates all restream destinations in the same request. If you do not want to modify an existing restream destination, you need to include it in your request, otherwise it is removed.
+ description: Use this parameter to add, edit, or remove `RTMPS` or `RTMP` services where you want to restream a live stream. The list can only contain up to 5 destinations. This operation updates all restream destinations in the same request. If you do not want to modify an existing restream destination, you need to include it in your request, otherwise it is removed.
maxItems: 5
type: array
items:
@@ -14384,9 +14384,9 @@ components:
name:
description: Use this parameter to define a name for the restream destination.
type: string
- example: My RTMP server
+ example: My restream server
serverUrl:
- description: Use this parameter to set the RTMP URL of the restream destination.
+ description: Use this parameter to set the `RTMPS` or `RTMP` server URL of the restream destination.
type: string
example: rtmp://my.broadcast.example.com/app
streamKey:
@@ -14400,9 +14400,9 @@ components:
name:
description: Returns the name of a restream destination.
type: string
- example: My RTMP server
+ example: My restream server
serverUrl:
- description: Returns the RTMP URL of a restream destination.
+ description: Returns the server URL of a restream destination.
type: string
example: rtmp://my.broadcast.example.com/app
streamKey:
From 31b3dd6cf9bfcd2fc4bde2e665b66b615dcf2061 Mon Sep 17 00:00:00 2001
From: szekelyzol <szekelyzol@gmail.com>
Date: Wed, 17 Jul 2024 12:04:14 +0200
Subject: [PATCH 2/2] Add rtmps to restreams error responses
---
openapi.yaml | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)
diff --git a/openapi.yaml b/openapi.yaml
index 3db11c16..8e33324d 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -5355,20 +5355,20 @@ paths:
detail: This value should not be blank.
name: restreams[0][name]
Missing app name in serverUrl:
- description: This error occurs when the rtmp app name is missing from `serverURL` in the `restreams` array.
+ description: This error occurs when the app name is missing from `serverURL` in the `restreams` array.
value:
type: https://docs.api.video/reference/invalid-attribute
title: An attribute is invalid.
status: 400
- detail: 'Missing app name: rtmp://[host]/[app name].'
+ detail: 'Missing app name: [rtmp|rtmps]://[host]/[app name].'
name: restreams[0][serverUrl]
Incorrect URL in serverUrl:
- description: This error occurs when the URL you set in `serverURL` is not `rtmp`.
+ description: This error occurs when the URL you set in `serverURL` is not `rtmps` or `rtmp`.
value:
type: https://docs.api.video/reference/invalid-attribute
title: An attribute is invalid.
status: 400
- detail: 'RTMP URL should have the following format: rtmp://[host]/[app name].'
+ detail: 'RTMP URL should have the following format: [rtmp|rtmps]://[host]/[app name].'
name: restreams[0][serverUrl]
Too many restream destinations:
description: This error occurs when you set more than 5 restream destinations.
@@ -6125,20 +6125,20 @@ paths:
detail: This value should not be blank.
name: restreams[0][name]
Missing app name in serverUrl:
- description: This error occurs when the rtmp app name is missing from `serverURL` in the `restreams` array.
+ description: This error occurs when the app name is missing from `serverURL` in the `restreams` array.
value:
type: https://docs.api.video/reference/invalid-attribute
title: An attribute is invalid.
status: 400
- detail: 'Missing app name: rtmp://[host]/[app name].'
+ detail: 'Missing app name: [rtmp|rtmps]://[host]/[app name].'
name: restreams[0][serverUrl]
Incorrect URL in serverUrl:
- description: This error occurs when the URL you set in `serverURL` is not `rtmp`.
+ description: This error occurs when the URL you set in `serverURL` is not `rtmps` or `rtmp`.
value:
type: https://docs.api.video/reference/invalid-attribute
title: An attribute is invalid.
status: 400
- detail: 'RTMP URL should have the following format: rtmp://[host]/[app name].'
+ detail: 'RTMP URL should have the following format: [rtmp|rtmps]://[host]/[app name].'
name: restreams[0][serverUrl]
Too many restream destinations:
description: This error occurs when you set more than 5 restream destinations.
@@ -13855,7 +13855,7 @@ components:
description: 'Whether or not you are broadcasting the live video you recorded for others to see. True means you are broadcasting to viewers, false means you are not.'
example: true
restreams:
- description: Returns the list of RTMP restream destinations.
+ description: Returns the list of restream destinations.
type: array
items:
$ref: '#/components/schemas/restreams-response-object'