From a924209b345f5e29d389a4e6b26ce02983079e37 Mon Sep 17 00:00:00 2001 From: pema-s <81958801+pema-s@users.noreply.github.com> Date: Thu, 6 Jan 2022 18:59:03 +0530 Subject: [PATCH] Web SDK Staging Docs --- .../muting-and-unmuting-connected-device.md | 30 ++++++++++++++----- web-sdk/overview.md | 26 ++++++++++------ web-sdk/passing-a-custom-sourceNode.md | 13 ++++---- .../passing-custom-ondevicechange-handler.md | 16 ++++++---- web-sdk/reconnecting-real-time.md | 25 +++++++++++----- web-sdk/stopping-realtime-connection.md | 12 +++++--- web-sdk/subscribe-to-realtime.md | 20 ++++++++----- ...nscribing-live-audio-through-microphone.md | 14 ++++++--- web-sdk/web-sdk-reference.md | 2 ++ 9 files changed, 107 insertions(+), 51 deletions(-) diff --git a/web-sdk/muting-and-unmuting-connected-device.md b/web-sdk/muting-and-unmuting-connected-device.md index 1f864e54..a7754cd8 100644 --- a/web-sdk/muting-and-unmuting-connected-device.md +++ b/web-sdk/muting-and-unmuting-connected-device.md @@ -1,7 +1,7 @@ --- id: muting-and-unmuting-connected-device title: Muting and Unmuting Connected Device (Beta) -sidebar_label: Muting and Unmuting Connected Devic (Beta) +sidebar_label: Muting and Unmuting Connected Device (Beta) slug: /web-sdk/muting-and-unmuting-connected-device --- @@ -10,27 +10,43 @@ import TabItem from '@theme/TabItem'; --- +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + You can mute and unmute the connected device by simply calling `symbl.mute()` or `symbl.unmute()`. -### Muting +### Muting Device A quick snippet on how to use the mute method is given below: ```js (async () => { - const connection = await symbl.startRealtimeRequest(connectionConfig); - await symbl.mute(connection); + // Creates the WebSocket in a non-processing state + const stream = await symbl.createStream(connectionConfig); + await symbl.mute(stream); })(); ``` -### Unmuting +:::note Using createStream to start a realtime request +Creating a stream using `symbl.startRealtimeRequest(config)` has been deprecated in favor of `symbl.createStream(config)`. For `createStream`, the WebSocket is started in a non processing state. You must send the start request before processing any audio. + +After the stream is created, you need to call `symbl.mute(stream)` to mute the device. +::: + +### Unmuting Device A quick snippet on how to use the unmute method is given below: ```js (async () => { - const connection = await symbl.startRealtimeRequest(connectionConfig); - await symbl.unmute(connection); + // Creates the WebSocket in a non-processing state + const stream = await symbl.createStream(connectionConfig); + await symbl.unmute(stream); })(); ``` +:::note Using createStream to start a realtime request +Creating a stream using `symbl.startRealtimeRequest(config)` has been deprecated in favor of `symbl.createStream(config)`. For `createStream`, the WebSocket is started in a non processing state. You must send the start request before processing any audio. +After the stream is created, you need to call `symbl.unmute(stream)` to unmute the device. +::: diff --git a/web-sdk/overview.md b/web-sdk/overview.md index 674b3b8d..68b204a0 100644 --- a/web-sdk/overview.md +++ b/web-sdk/overview.md @@ -10,6 +10,10 @@ import TabItem from '@theme/TabItem'; --- +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + The Symbl Web SDK provides access to the Symbl APIs for applications directly in the browser. > **Source Code**
@@ -31,7 +35,7 @@ Find the source code here: [https://github.com/symblai/symbl-web-sdk](https://gi --- **To use the Symbl Web SDK,** -Include it via script tags in your HTML file: +Include the following script tag in your HTML file: ```html @@ -89,21 +93,21 @@ sdk.init({ ``` -:::note Web SDK in Labs -The Web SDK is available as a part of [Symbl Labs](/docs/labs) with select features. You can find the Web SDK Labs Readme here: [https://github.com/symblai/symbl-web-sdk/blob/labs/README.md](https://github.com/symblai/symbl-web-sdk/blob/labs/README.md) and the source code here: [https://github.com/symblai/symbl-web-sdk/tree/labs](https://github.com/symblai/symbl-web-sdk/tree/labs). +:::info Web SDK in Labs +The Web SDK is also available as a part of the [Symbl Labs](/docs/labs) with select features. You can find the Web SDK Labs Readme here: [https://github.com/symblai/symbl-web-sdk/blob/labs/README.md](https://github.com/symblai/symbl-web-sdk/blob/labs/README.md) and the source code here: [https://github.com/symblai/symbl-web-sdk/tree/labs](https://github.com/symblai/symbl-web-sdk/tree/labs). ::: ## Streaming API config options -The full details of the Streaming API config options can be seen [here](https://docs.symbl.ai/docs/streaming-api/api-reference/#request-parameters). +You can utilize the config options provided for our Streaming API. To read about the Streaming API config options, go to [Streaming API Reference](https://docs.symbl.ai/docs/streaming-api/api-reference/#request-parameters). ### Additional Web SDK configs -These are configs that have been added that are specific to the Web SDK. +You can also pass the following configurations that are available specifically with the Web SDK: | Name | Default | Description | | -------| ---------- | ------- | -| `sourceNode` | `null` | For passing in an external [MediaStreamAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamAudioSourceNode/MediaStreamAudioSourceNode) object. By default the Web SDK will handle audio context and source nodes on it's own, though if you wish to handle that externally we've provided that option. | -| `reconnectOnError` | `true` | If true the Web SDK will attempt to reconnect to the WebSocket in case of error. You can also make sure of our `onReconnectFail` callback which will fire in case the reconnection attempt fails. | +| `sourceNode` | `null` | For passing in an external [MediaStreamAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamAudioSourceNode/MediaStreamAudioSourceNode) object. Although the Web SDK will handle the audio context and source nodes on its own by default, you can pass this option if you wish to handle it externally. | +| `reconnectOnError` | `true` | If this option is set to `true`, the Web SDK will attempt to reconnect to the WebSocket in case of an error. You can also make use of our [onReconnectFail](/docs/web-sdk/web-sdk-reference#onreconnectfailerr) callback which will fire in case the reconnection attempt fails. | ### Usage Example @@ -138,7 +142,9 @@ await symbl.unmute(stream); --- We have prepared a list of tutorials to help you understand how to use the Web SDK. -* [Transcribing Live Audio Input through Microphone](/docs/web-sdk/transcribing-live-audio-through-microphone) +* [How to Transcribe a Live Audio Input through Microphone](/docs/web-sdk/transcribing-live-audio-through-microphone) +* [How to pass a custom Node Source](/docs/web-sdk/passing-custom-sourcenode) +* [How to pass a custom Device Change Handler](/docs/web-sdk/passing-custom-ondevicechange-handler) ### Web SDK Reference --- @@ -148,4 +154,6 @@ The supported Handlers and Callbacks for the Web SDK are listed below: * [onSpeechDetected](/docs/javascript-sdk/reference#onspeechdetected) * [onMessageResponse](/docs/javascript-sdk/reference#onmessageresponse) * [onInsightResponse](/docs/javascript-sdk/reference#oninsightresponse) - * [onTopicResponse](/docs/javascript-sdk/reference#ontopicresponse) \ No newline at end of file + * [onTopicResponse](/docs/javascript-sdk/reference#ontopicresponse)
+ +👉 See the complete Web SDK Reference [here](/docs/web-sdk/web-sdk-reference). \ No newline at end of file diff --git a/web-sdk/passing-a-custom-sourceNode.md b/web-sdk/passing-a-custom-sourceNode.md index 85f719fa..a9d05a50 100644 --- a/web-sdk/passing-a-custom-sourceNode.md +++ b/web-sdk/passing-a-custom-sourceNode.md @@ -10,12 +10,15 @@ import TabItem from '@theme/TabItem'; --- -If you wish you can pass in a custom `MediaStreamAudioSourceNode` object to the Web SDK. By default the Web SDK will create the AudioContext and the `MediaStreamAudioSourceNode` object automatically but using this will give you more control over those. +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: -Once you create the `MediaStreamAudioSourceNode` object you can pass it via the `connectionConfig` as sourceNode +You can pass a custom `MediaStreamAudioSourceNode` object to the Web SDK. By default the Web SDK will create the AudioContext and the `MediaStreamAudioSourceNode` object automatically but using this will give you more control over those. -```js +Once you create the `MediaStreamAudioSourceNode` object you can pass it via the `connectionConfig` as sourceNode. +```js // create the MediaStreamAudioSourceNode const AudioContext = window.AudioContext || window.webkitAudioContext; stream = await navigator.mediaDevices.getUserMedia({ @@ -29,7 +32,7 @@ symbl.init({ appId: '', appSecret: '', // accessToken: '', // can be used instead of appId and appSecret - basePath: 'https://api-labs.symbl.ai', + basePath: 'https://api.symbl.ai', }); const id = btoa("my-first-symbl-ai-code"); @@ -94,7 +97,7 @@ const connectionConfig = { ### Updating your external source node -If you wish to update your external source node you can do se by using the `symbl.updateSourceNode` function: +If you wish to update your external source node you can do so by using the `symbl.updateSourceNode` function: ```js symbl.updateSourceNode(stream, sourceNode); diff --git a/web-sdk/passing-custom-ondevicechange-handler.md b/web-sdk/passing-custom-ondevicechange-handler.md index 8a494666..46c5d769 100644 --- a/web-sdk/passing-custom-ondevicechange-handler.md +++ b/web-sdk/passing-custom-ondevicechange-handler.md @@ -1,7 +1,7 @@ --- id: passing-custom-ondevicechange-handler -title: Passing a custom ondevicechange handler (Beta) -sidebar_label: Passing a custom ondevicechange handler (Beta) +title: Passing a Custom Device Change Handler (Beta) +sidebar_label: Passing a Custom Device Change Handler (Beta) slug: /web-sdk/passing-custom-ondevicechange-handler --- @@ -10,14 +10,19 @@ import TabItem from '@theme/TabItem'; --- -By default, the Symbl Web SDK will handle the `ondevicechange` event and send a `modify_request` event to modify the sample rate with the new device's sample rate. If you wish to override this logic you can pass in your own `ondevicechange` handler in the handlers config. +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + + +By default, the Symbl Web SDK will handle the `ondevicechange` event and send a `modify_request` event to modify the sample rate with the new device's sample rate. If you wish to override this logic, you can pass in your own `ondevicechange` handler in the handlers config. ```js symbl.init({ appId: '', appSecret: '', // accessToken: '', // can be used instead of appId and appSecret - basePath: 'https://api-labs.symbl.ai', + basePath: 'https://api.symbl.ai', }); const id = btoa("my-first-symbl-ai-code"); // pass in the MediaStreamAudioSourceNode as sourceNode @@ -51,5 +56,4 @@ You can also make use of our callback using our `deviceChanged` callback: symbl.deviceChanged = () => { // Add your logic here } -``` - +``` \ No newline at end of file diff --git a/web-sdk/reconnecting-real-time.md b/web-sdk/reconnecting-real-time.md index 0c19b3ef..c4a88419 100644 --- a/web-sdk/reconnecting-real-time.md +++ b/web-sdk/reconnecting-real-time.md @@ -1,7 +1,7 @@ --- id: reconnecting-real-time -title: Reconnecting to an Existing Real-time Connection (Beta) -sidebar_label: Reconnecting to an Existing Real-time Connection +title: Reconnecting to a Real-time Connection (Beta) +sidebar_label: Reconnecting to a Real-time Connection slug: /web-sdk/reconnecting-real-time --- @@ -10,6 +10,10 @@ import TabItem from '@theme/TabItem'; --- +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + In case a user closes their browser or has an interruption in their WebSocket connection, you can use the `store` object to grab the Connection ID you last used. ```js @@ -64,14 +68,19 @@ const connectionConfig = { }; (async () => { - const connection = await symbl.startRealtimeRequest(connectionConfig); + // Creates the WebSocket in a non-processing state + const stream = await symbl.createStream(connectionConfig); + + // Send the start request + await stream.start(stream); })(); ``` - -The `startRealtimeRequest` connects to a Streaming API Web Socket endpoint using the provided configuration options. Read more about `startRealtimeRequest` [here](/docs/web-sdk/web-sdk-reference#startrealtimerequest). - -Read about the Streaming API parameters for `connectionConfig` [here](/docs/streaming-api/api-reference/#request-parameters). - +:::note Using createStream to start a realtime request +Creating a stream using `symbl.startRealtimeRequest(config)` has been deprecated in favor of `symbl.createStream(config)`. For createStream, the WebSocket is started in a non processing state. You must send the start request before processing any audio. + +After the stream is created, you need to call `symbl.start(stream)` to start the stream. +::: + Read more about the supported Event Handlers:     👉   [onSpeechDetected](/docs/web-sdk/web-sdk-reference#onspeechdetected)
diff --git a/web-sdk/stopping-realtime-connection.md b/web-sdk/stopping-realtime-connection.md index 443268cd..be0f3b0d 100644 --- a/web-sdk/stopping-realtime-connection.md +++ b/web-sdk/stopping-realtime-connection.md @@ -1,7 +1,7 @@ --- id: stop-realtime-connection -title: Stopping Realtime Connection (Beta) -sidebar_label: Stopping Realtime Connection (Beta) +title: Stopping Real-time Connection (Beta) +sidebar_label: Stopping Real-time Connection (Beta) slug: /web-sdk/stop-realtime-connection --- @@ -10,10 +10,14 @@ import TabItem from '@theme/TabItem'; --- -In order to end the connection to the realtime WebSocket you'll need to use the following command with your connection object: +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + +In order to end the real-time WebSocket connection, you'll need to use the following command with your connection object: ```js symbl.stopRequest(connection); ``` -If you do not sever the connection you could use more minutes of time than intended, so it is recommended to always end the connection programmatically. \ No newline at end of file +If you do not sever the connection, you could use more minutes of time than intended, so it is recommended to always end the connection programmatically. \ No newline at end of file diff --git a/web-sdk/subscribe-to-realtime.md b/web-sdk/subscribe-to-realtime.md index 904a97eb..871fcf2f 100644 --- a/web-sdk/subscribe-to-realtime.md +++ b/web-sdk/subscribe-to-realtime.md @@ -1,7 +1,7 @@ --- id: subscribe-to-realtime -title: Subscribing to an existing realtime connection with Subscribe API (Beta) -sidebar_label: Subscribing to an existing realtime connection with Subscribe API (Beta) +title: Subscribing to a Real-time Connection (Beta) +sidebar_label: Subscribing to a Real-time Connection (Beta) slug: /web-sdk/subscribe-to-realtime --- @@ -10,7 +10,11 @@ import TabItem from '@theme/TabItem'; --- -With the Subscribe API you can connect to an existing connection via the connection ID. You'll want to open this example in a different browser while the realtime transcription example is running. +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + +With the Subscribe API you can connect to an existing connection via the connection ID. You'll want to open this example in a different browser while the real-time transcription is running. ## Current call signature @@ -36,14 +40,14 @@ symbl.subscribeToStream(id, (data) => { }) ``` -| Name | Description | -| -------| ---------- | -| `reconnectOnError` | `true` | If true the Web SDK will attempt to reconnect to the WebSocket in case of error. You can also make sure of our `onReconnectFail` callback which will fire in case the reconnection attempt fails.) | +| Name | Default | Description | +| -------| ---------- | --------- | +| `reconnectOnError` | `true` | If `true`, the Web SDK will attempt to reconnect to the WebSocket in case of an error. You can also make sure of our `onReconnectFail` callback which will fire in case the reconnection attempt fails.) | ## Subscribe API Handlers -| Name | Default value | Description | -| -------| ---------- | ------- | +| Name | Description | +| -------| ---------- | | `onMessage(message)` | Fired any time a message is received. | If true the Web SDK will attempt to reconnect to the WebSocket in case of error. You can also make sure of our `onReconnectFail` callback which will fire in case the reconnection attempt fails.) | | `onSubscribe()` | Fired when the connection intially subscribes. | `onClose()` | Fired when the connection is closed. diff --git a/web-sdk/transcribing-live-audio-through-microphone.md b/web-sdk/transcribing-live-audio-through-microphone.md index bf791a24..9e5839f0 100644 --- a/web-sdk/transcribing-live-audio-through-microphone.md +++ b/web-sdk/transcribing-live-audio-through-microphone.md @@ -10,9 +10,13 @@ import TabItem from '@theme/TabItem'; --- -As a simple test of the Streaming API you can simply setup a live microphone and push the audio stream using the browser APIs to access the microphone. +:::note IN BETA PHASE +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + +To transcribe live audio via Streaming API, you can setup a live microphone and push the audio stream using the browser APIs to access the microphone. -Initialize the SDK and connect via the built-in websocket connector. This will output the live transcription to the console. +Initialize the SDK and connect via the built-in WebSocket connector. This will output the live transcription to the console. ### Initialize the SDK @@ -44,7 +48,7 @@ symbl.init({ basePath: 'https://api-labs.symbl.ai', }); -const id = btoa("symbl-ai-is-the-best"); +const id = btoa("my-first-symbl-ai-code"); const connectionConfig = { id, @@ -108,4 +112,6 @@ Read more about the supported Event Handlers:     👉   [onSpeechDetected](/docs/web-sdk/web-sdk-reference#onspeechdetected)
    👉   [onMessageResponse](/docs/web-sdk/web-sdk-reference#onmessageresponse)
    👉   [onInsightResponse](/docs/web-sdk/web-sdk-reference#oninsightresponse)
-    👉   [onTopicResponse](/docs/web-sdk/web-sdk-reference#ontopicresponse) \ No newline at end of file +    👉   [onTopicResponse](/docs/web-sdk/web-sdk-reference#ontopicresponse)
+ +👉 See the complete Web SDK Reference [here](/docs/web-sdk/web-sdk-reference). \ No newline at end of file diff --git a/web-sdk/web-sdk-reference.md b/web-sdk/web-sdk-reference.md index 08a8ee51..f17d4c8c 100644 --- a/web-sdk/web-sdk-reference.md +++ b/web-sdk/web-sdk-reference.md @@ -10,6 +10,8 @@ import TabItem from '@theme/TabItem'; --- +This page contains a complete reference of the methods and event handlers supported with the Symbl Web SDK. + ## Public Methods ### init