From 7544c8cbe0dc6ec0819845c6a8e0fa31ed9ad7d6 Mon Sep 17 00:00:00 2001
From: Zita Szupera <szuperaz@gmail.com>
Date: Fri, 4 Oct 2024 14:30:29 -0500
Subject: [PATCH] closed captions documentation

---
 .../api/transcription/closed_captions.mdx     | 130 ++++++++++++++++++
 .../docs/api/transcription/storage.mdx        |   2 +-
 2 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 docusaurus/video/docusaurus/docs/api/transcription/closed_captions.mdx

diff --git a/docusaurus/video/docusaurus/docs/api/transcription/closed_captions.mdx b/docusaurus/video/docusaurus/docs/api/transcription/closed_captions.mdx
new file mode 100644
index 00000000..c15e03cd
--- /dev/null
+++ b/docusaurus/video/docusaurus/docs/api/transcription/closed_captions.mdx
@@ -0,0 +1,130 @@
+---
+id: closed-captions
+sidebar_position: 2
+title: Closed captions
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import apiJson from '../video-client-openapi.json';
+import OpenApiModels from '../_common_/OpenApiModels.jsx';
+
+The Stream API supports adding real-time closed captions (subtitles for participants) to your calls.
+
+## Call and call type settings
+
+Make sure that the closed caption feature is enabled in your app's dashboard. The closed caption feature can be set on the call type level, and the available options are:
+
+- `available`: the feature is available for your call and can be started.
+- `disabled`: the feature is not available for your call
+- `auto-on`: the feature is available and will be started automatically once the user is connected to the call.
+
+It's also possible to override the call type's default when creating/updating a call:
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+// Call type level
+client.video.updateCallType({
+  name: 'default',
+  settings: {
+    transcription: {
+      mode: 'available',
+      closed_caption_mode: 'available',
+    },
+  },
+});
+
+// Call level
+await call.getOrCreate({
+  data: {
+    settings_override: {
+      transcription: {
+        mode: 'available',
+        closed_caption_mode: 'available',
+      },
+    },
+    created_by_id: 'john',
+  },
+});
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+# Call type level
+curl -X PUT "https://video.stream-io-api.com/api/v2/video/calltypes/${CALL_TYPE_NAME}?api_key=${API_KEY}" \
+  -H "Authorization: ${TOKEN}" \
+  -H "stream-auth-type: jwt" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "settings_override": {
+      "transcription": {
+        "mode": "available",
+        "closed_caption_mode": "available"
+      }
+    }
+  }'
+
+# Call level
+curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
+  -H "Authorization: ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "stream-auth-type: jwt" \
+  -d '{
+    "data": {
+      "created_by_id": "john",
+      "settings_override": {
+        "transcription": {
+          "mode": "available",
+          "closed_caption_mode": "available"
+        }
+      }
+    }
+  }'
+```
+
+</TabItem>
+</Tabs>
+
+## Start-stop closed captions
+
+If you set `closed_caption_mode` to `available` you need to start closed caption events when you want to see captions:
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+await call.startClosedCaptions();
+
+// to disable closed caption events
+await call.stopClosedCaptions();
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/start_closed_captions?api_key=${API_KEY}" \
+  -H "Authorization: ${TOKEN}" \
+  -H "stream-auth-type: jwt"
+
+# disable closed caption events
+curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/stop_closed_captions?api_key=${API_KEY}" \
+  -H "Authorization: ${TOKEN}" \
+  -H "stream-auth-type: jwt"
+```
+
+</TabItem>
+</Tabs>
+
+## Closed caption events
+
+Once closed captions are started, clients will start receiving closed caption events.
+
+<OpenApiModels
+  modelName={'ClosedCaptionEvent'}
+  apiJson={apiJson}
+></OpenApiModels>
diff --git a/docusaurus/video/docusaurus/docs/api/transcription/storage.mdx b/docusaurus/video/docusaurus/docs/api/transcription/storage.mdx
index aeabbf21..822cf704 100644
--- a/docusaurus/video/docusaurus/docs/api/transcription/storage.mdx
+++ b/docusaurus/video/docusaurus/docs/api/transcription/storage.mdx
@@ -1,6 +1,6 @@
 ---
 id: storage
-sidebar_position: 2
+sidebar_position: 3
 slug: /transcribing/storage
 title: Storage
 ---