From d2db3ac677e8e0d5563c5e34ab67e400870f1368 Mon Sep 17 00:00:00 2001 From: Matvei Andrienko Date: Tue, 30 Jul 2024 14:35:52 +0200 Subject: [PATCH] docs: update media filters API docs (#1450) The media filters API has been updated in #1415. However, I missed a part of the docs where this changed API is used. This PR fixes the docs. --------- Co-authored-by: Oliver Lazoroski --- .../02-guides/04-camera-and-microphone.mdx | 50 ++++++++++++++++--- .../02-guides/04-camera-and-microphone.mdx | 50 ++++++++++++++++--- 2 files changed, 88 insertions(+), 12 deletions(-) diff --git a/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx b/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx index 81980a504d..cc03150f1c 100644 --- a/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx +++ b/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx @@ -312,20 +312,30 @@ import { Call } from '@stream-io/video-client'; let call: Call; // apply a custom video filter -const unregisterMyVideoFilter = await camera.registerFilter( - async function myVideoFilter(inputMediaStream: MediaStream) { +const { unregister: unregisterMyVideoFilter } = camera.registerFilter( + function myVideoFilter(inputMediaStream: MediaStream) { // initialize the video filter, do some magic and // return the modified media stream - return mediaStreamWithFilterApplied; + return { + output: mediaStreamWithFilterApplied, + stop: () => { + // optional cleanup function + }, + }; }, ); // apply a custom audio filter -const unregisterMyAudioFilter = await microphone.registerFilter( - async function myAudioFilter(inputMediaStream: MediaStream) { +const { unregister: unregisterMyAudioFilter } = microphone.registerFilter( + function myAudioFilter(inputMediaStream: MediaStream) { // initialize the audio filter, do some magic and // return the modified media stream - return mediaStreamWithFilterApplied; + return { + output: mediaStreamWithFilterApplied, + stop: () => { + // optional cleanup function + }, + }; }, ); @@ -338,6 +348,34 @@ Filters can be registered and unregistered at any time, and the SDK will take ca Filters can be chained, and the order of registration matters. The first registered filter will be the first to modify the raw `MediaStream`. +A filter may be asynchronous. In this case, the function passed to the `registerFilter` method should _synchronously_ +return an object where `output` is a promise that resolves to a `MediaStream`: + +```typescript +camera.registerFilter(function myVideoFilter(inputMediaStream: MediaStream) { + // note that output is returned synchronously! + return { + output: new Promise((resolve) => resolve(mediaStreamWithFilterApplied)), + stop: () => { + // optional cleanup function + }, + }; +}); +``` + +Registering a filter is not instantaneous. If you need to know when a filter is registered (e.g. to show +a spinner in the UI), await for the `registered` promise returned by the `registerFilter` method: + +```typescript +const { registered } = camera.registerFilter( + (inputMediaStream: MediaStream) => { + // your video filter + }, +); +await registered; +// at this point, the filter is registered +``` + Once a filter(s) is registered, the SDK will send the last returned `MediaStream` to the remote participants. ## Speaker management diff --git a/packages/react-sdk/docusaurus/docs/React/02-guides/04-camera-and-microphone.mdx b/packages/react-sdk/docusaurus/docs/React/02-guides/04-camera-and-microphone.mdx index 07f396a25b..1ce8d9bc55 100644 --- a/packages/react-sdk/docusaurus/docs/React/02-guides/04-camera-and-microphone.mdx +++ b/packages/react-sdk/docusaurus/docs/React/02-guides/04-camera-and-microphone.mdx @@ -235,20 +235,30 @@ const { camera } = useCameraState(); const { microphone } = useMicrophoneState(); // apply a custom video filter -const unregisterMyVideoFilter = await camera.registerFilter( - async function myVideoFilter(inputMediaStream: MediaStream) { +const { unregister: unregisterMyVideoFilter } = camera.registerFilter( + function myVideoFilter(inputMediaStream: MediaStream) { // initialize the video filter, do some magic and // return the modified media stream - return mediaStreamWithFilterApplied; + return { + output: mediaStreamWithFilterApplied, + stop: () => { + // optional cleanup function + }, + }; }, ); // apply a custom audio filter -const unregisterMyAudioFilter = await microphone.registerFilter( - async function myAudioFilter(inputMediaStream: MediaStream) { +const { unregister: unregisterMyAudioFilter } = microphone.registerFilter( + function myAudioFilter(inputMediaStream: MediaStream) { // initialize the audio filter, do some magic and // return the modified media stream - return mediaStreamWithFilterApplied; + return { + output: mediaStreamWithFilterApplied, + stop: () => { + // optional cleanup function + }, + }; }, ); @@ -261,6 +271,34 @@ Filters can be registered and unregistered at any time, and the SDK will take ca Filters can be chained, and the order of registration matters. The first registered filter will be the first to modify the raw `MediaStream`. +A filter may be asynchronous. In this case, the function passed to the `registerFilter` method should _synchronously_ +return an object where `output` is a promise that resolves to a `MediaStream`: + +```typescript +camera.registerFilter(function myVideoFilter(inputMediaStream: MediaStream) { + // note that output is returned synchronously! + return { + output: new Promise((resolve) => resolve(mediaStreamWithFilterApplied)), + stop: () => { + // optional cleanup function + }, + }; +}); +``` + +Registering a filter is not instantaneous. If you need to know when a filter is registered (e.g. to show +a spinner in the UI), await for the `registered` promise returned by the `registerFilter` method: + +```typescript +const { registered } = camera.registerFilter( + (inputMediaStream: MediaStream) => { + // your video filter + }, +); +await registered; +// at this point, the filter is registered +``` + Once a filter(s) is registered, the SDK will send the last returned `MediaStream` to the remote participants. ## Speaker management