GITBOOK-451: Added concludeHlsLive API

AirenSoft · Jul 5, 2024 · d7ced77 · d7ced77
1 parent 5b116f5
commit d7ced77
Show file tree

Hide file tree

Showing 4 changed files with 110 additions and 10 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -42,6 +42,7 @@
         * [Stream](rest-api/v1/virtualhost/application/stream/README.md)
           * [Send Event](rest-api/v1/virtualhost/application/stream/send-event.md)
           * [HLS Dump](rest-api/v1/virtualhost/application/stream/hls-dump.md)
+          * [Conclude HLS Live](rest-api/v1/virtualhost/application/stream/conclude-hls-live.md)
         * [ScheduledChannel](rest-api/v1/virtualhost/application/scheduledchannel-api.md)
         * [MultiplexChannel](rest-api/v1/virtualhost/application/scheduledchannel-api-1.md)
     * [Statistics](rest-api/v1/statistics/README.md)

diff --git a/docs/rest-api/v1/virtualhost/application/stream/conclude-hls-live.md b/docs/rest-api/v1/virtualhost/application/stream/conclude-hls-live.md
@@ -0,0 +1,104 @@
+# Conclude HLS Live
+
+For live streaming of certain events, it may be necessary to immediately stop the HLS live stream and switch to VoD after the HLS live broadcast ends. This API transitions to VoD by stopping segment updates for LL-HLS and HLS streams and inserting #EXT-X-ENDLIST. By using this API with a [Scheduled Channel](../../../../../live-source/scheduled-channel.md), you can implement additional application services.
+
+> ### Request
+
+<details>
+
+<summary><mark style="color:blue;">POST</mark> v1/vhosts/{vhost}/apps/{app}/streams/{stream}:concludeHlsLive</summary>
+
+#### Header
+
+```http
+Authorization: Basic {credentials}
+
+# Authorization
+    Credentials for HTTP Basic Authentication created with <AccessToken>
+```
+
+#### Body
+
+```json
+{}
+```
+
+</details>
+
+> ### Responses
+
+<details>
+
+<summary><mark style="color:blue;">200</mark> Ok</summary>
+
+The request has succeeded
+
+#### **Header**
+
+```
+Content-Type: application/json
+```
+
+#### **Body**
+
+```json
+{
+	"statusCode": 200,
+	"message": "OK",
+}
+
+# statusCode
+	Same as HTTP Status Code
+# message
+	A human-readable description of the response code
+```
+
+</details>
+
+<details>
+
+<summary><mark style="color:red;">400</mark> Bad Request</summary>
+
+Invalid request. Body is not a Json Object or does not have a required value
+
+</details>
+
+<details>
+
+<summary><mark style="color:red;">401</mark> Unauthorized</summary>
+
+Authentication required
+
+#### **Header**
+
+```http
+WWW-Authenticate: Basic realm=”OvenMediaEngine”
+```
+
+#### **Body**
+
+```json
+{
+    "message": "[HTTP] Authorization header is required to call API (401)",
+    "statusCode": 401
+}
+```
+
+</details>
+
+<details>
+
+<summary><mark style="color:red;">404</mark> Not Found</summary>
+
+The given vhost name or app name could not be found.
+
+#### **Body**
+
+```json
+{
+    "statusCode": 404,
+    "message": "Could not find the application: [default/non-exists] (404)"
+}
+```
+
+</details>
diff --git a/docs/rest-api/v1/virtualhost/application/stream/send-event.md b/docs/rest-api/v1/virtualhost/application/stream/send-event.md
@@ -76,10 +76,6 @@ Content-Type: application/json
 {
 	"statusCode": 200,
 	"message": "OK",
-	"response": [
-		"stream",
-		"stream2"
-	]
 }
 
 # statusCode

diff --git a/docs/streaming/hls.md b/docs/streaming/hls.md
@@ -69,12 +69,11 @@ To use HLS, you need to add the `<HLS>` elements to the `<Publishers>` in the co
 </Server>
 ```
 
-| Element         | Decscription                                                                                                                                                                                                                     |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Bind            | Set the HTTP ports to provide HLS.                                                                                                                                                                                               |
-| SegmentDuration | Set the length of the segment in seconds. Therefore, a shorter value allows the stream to start faster. However, a value that is too short will make legacy HLS players unstable. Apple recommends **6** seconds for this value. |
-| SegmentCount    | The number of segments listed in the playlist. 5 is recommended for HLS players. Do not set below 3. It can only be used for experimentation.                                                                                    |
-| CrossDomains    | Control the domain in which the player works through `<CorssDomain>`. For more information, please refer to the [CrossDomain](broken-reference) section.                                                                         |
+<table><thead><tr><th width="241">Element</th><th>Decscription</th></tr></thead><tbody><tr><td>Bind</td><td>Set the HTTP ports to provide HLS.</td></tr><tr><td>SegmentDuration</td><td>Set the length of the segment in seconds. Therefore, a shorter value allows the stream to start faster. However, a value that is too short will make legacy HLS players unstable. Apple recommends <strong>6</strong> seconds for this value.</td></tr><tr><td>SegmentCount</td><td>The number of segments listed in the playlist. 5 is recommended for HLS players. Do not set below 3. It can only be used for experimentation.</td></tr><tr><td>CrossDomains</td><td>Control the domain in which the player works through <code>&#x3C;CorssDomain></code>. For more information, please refer to the <a href="broken-reference">CrossDomain</a> section.</td></tr><tr><td>DVR</td><td><p><strong>Enable</strong> <br>You can turn DVR on or off.</p><p><strong>EventPlaylistType</strong> <br>Inserts #EXT-X-PLAYLIST-TYPE: EVENT into the m3u8 file.</p><p><strong>TempStoragePath</strong> <br>Specifies a temporary folder to store old segments.</p><p><strong>MaxDuration</strong> <br>Sets the maximum duration of recorded files in milliseconds.</p></td></tr></tbody></table>
+
+{% hint style="warning" %}
+Safari Native Player only provides the Seek UI if `#EXT-X-PLAYLIST-TYPE: EVENT` is present. Since it is specified that nothing can be removed from the playlist when it is of type EVENT, you must call the [concludeHlsLive API](../rest-api/v1/virtualhost/application/stream/conclude-hls-live.md) to switch to VoD or terminate the stream before MaxDuration is exceeded if you use this option. Otherwise, unexpected behavior may occur in the Safari Player.
+{% endhint %}
 
 ## Playback