@livekit/track-processors 0.6.0 → 0.7.0

package/README.md

@@ -10,15 +10,16 @@ npm add @livekit/track-processors
 
 ### Available processors
 
-This package exposes the `BackgroundBlur` and `VirtualBackground` pre-prepared processor pipelines.
+This package exposes the `BackgroundProcessor` pre-prepared processor pipeline, which can be used in a few ways:
 
-- `BackgroundBlur(blurRadius)`
-- `VirtualBackground(imagePath)`
+- `BackgroundProcessor({ mode: 'background-blur', blurRadius: 10 /* (optional) */ })`
+- `BackgroundProcessor({ mode: 'virtual-background', imagePath: "http://path.to/image.png" })`
+- `BackgroundProcessor({ mode: 'disabled' })`
 
 ### Usage example
 
 ```ts
-import { BackgroundBlur, supportsBackgroundProcessors, supportsModernBackgroundProcessors } from '@livekit/track-processors';
+import { BackgroundProcessor, supportsBackgroundProcessors, supportsModernBackgroundProcessors } from '@livekit/track-processors';
 
 if(!supportsBackgroundProcessors()) {
   throw new Error("this browser does not support background processors")
@@ -29,19 +30,40 @@ if(supportsModernBackgroundProcessors()) {
 }
 
 const videoTrack = await createLocalVideoTrack();
-const blur = BackgroundBlur(10);
-await videoTrack.setProcessor(blur);
+const processor = BackgroundProcessor({ mode: 'background-blur' });
+await videoTrack.setProcessor(processor);
 room.localParticipant.publishTrack(videoTrack);
 
 async function disableBackgroundBlur() {
   await videoTrack.stopProcessor();
 }
 
-async updateBlurRadius(radius) {
-  return blur.updateTransformerOptions({blurRadius: radius})
+async function updateBlurRadius(radius) {
+  return processor.switchTo({ mode: 'background-blur', blurRadius: radius });
 }
+```
+
+In a real application, it's likely you will want to only sometimes apply background effects. You
+could accomplish this by calling `videoTrack.setProcessor(...)` / `videoTrack.stopProcessor(...)` on
+demand, but these functions can sometimes result in output visual artifacts as part of the switching
+process, which can result in a poor user experience.
+
+A better option which won't result in any visual artifacts while switching is to initialize the
+`BackgroundProcessor` in its "disabled" mode, and then later on switch to the desired mode. For
+example:
+```ts
+const videoTrack = await createLocalVideoTrack();
+const processor = BackgroundProcessor({ mode: 'disabled' });
+await videoTrack.setProcessor(processor);
+room.localParticipant.publishTrack(videoTrack);
 
+async function enableBlur(radius) {
+  await processor.switchTo({ mode: 'background-blur', blurRadius: radius });
+}
 
+async function disableBlur() {
+  await videoTrack.switchTo({ mode: 'disabled' });
+}
 ```
 
 ## Developing your own processors
@@ -58,7 +80,7 @@ export const VirtualBackground = (imagePath: string) => {
 
 ### Available base transformers
 
-- BackgroundTransformer (can blur background or use a virtual background);
+- BackgroundTransformer (can blur background, use a virtual background, or be put into a disabled state);
 
 
 ## Running the sample app