@webex/media-helpers 3.0.0-beta.126 → 3.0.0-beta.128

package/README.md

@@ -21,6 +21,80 @@ npm install --save @webex/media-helpers
 
 ## Usage
 
+### Effects
+There are two effects included in this package:
+
+Virtual background (e.g., blur, image replacement, video replacement)
+Noise reduction (e.g., background noise removal)
+
+#### Virtual background
+The virtual background effect provides a virtual background for video calling. The virtual background may be an image, an mp4 video, or the user's background with blur applied.
+
+**Applying the effect**
+1. Create a new camera track instance by using LocalCameraTrack() method.
+2. Create a VirtualBackgroundEffect instance by passing appropriate constraints.
+3. Use addEffect() method on cameraTrack to apply effect on it.
+4. Enable the effect after adding it to cameraTrack using enable() method available on effect. Effect will be enabled on cameraTrack.
+
+```javascript
+import {LocalCameraTrack, VirtualBackgroundEffect} from '@webex/media-helpers';
+
+// Create a new video stream by a getting user's video media.
+const stream = await navigator.mediaDevices.getUserMedia({ video: { width, height } });
+
+const videoTrackFromLocalStream = stream.getVideoTracks()[0];
+
+const cameraTrack = new LocalCameraTrack(new MediaStream([videoTrackFromLocalStream]));
+
+// Create the effect.
+const effect = new VirtualBackgroundEffect({
+  authToken: '<encoded-string>',
+  mode: `BLUR`,
+  blurStrength: `STRONG`,
+  quality: `LOW`,
+});
+
+// add the effect on the input camera track.
+await cameraTrack.addEffect("background-blur", effect);
+
+//enable the effect once it is added to the track
+await effect.enable()
+```
+
+#### Noise reduction
+The noise reduction effect removes background noise from an audio stream to provide clear audio for calling.
+
+**Applying the effect**
+1. Create a new microphone track instance by using LocalMicrophoneTrack() method.
+2. Create a NoiseReductionEffect instance by passing appropriate constraints.
+3. Use addEffect() method on microphoneTrack to apply effect on it.
+4. Enable the effect after adding it to microphoneTrack using enable() method available on effect. Effect will be enabled on microphoneTrack.
+
+```javascript
+import {LocalMicrophoneTrack, NoiseReductionEffect} from '@webex/media-helpers';
+
+// Create a new audio stream by getting a user's audio media.
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+const audioTrackFromLocalStream = stream.getAudioTracks()[0];
+
+const microphoneTrack = new LocalMicrophoneTrack(new MediaStream([audioTrackFromLocalStream]));
+
+// Create the effect.
+const effect = new NoiseReductionEffect({
+  authToken: '<encoded-string>',
+  workletProcessorUrl: 'https://my-worklet-processor-url', // For 'WORKLET' mode
+  legacyProcessorUrl: 'https://my-legacy-processor-url', // For 'LEGACY' mode
+  mode: 'WORKLET', // or 'LEGACY'
+});
+
+// add the effect on microphone track.
+await microphoneTrack.addEffect("background-noise-removal", effect);
+
+//enable the effect once it is added to the track
+await effect.enable()
+```
+
 ## Maintainers
 
 This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).

package/dist/index.js

@@ -46,6 +46,18 @@ _Object$defineProperty(exports, "LocalTrackEvents", {
     return _webrtcCore.LocalTrackEvents;
   }
 });
+_Object$defineProperty(exports, "NoiseReductionEffect", {
+  enumerable: true,
+  get: function get() {
+    return _webMediaEffects.NoiseReductionEffect;
+  }
+});
+_Object$defineProperty(exports, "VirtualBackgroundEffect", {
+  enumerable: true,
+  get: function get() {
+    return _webMediaEffects.VirtualBackgroundEffect;
+  }
+});
 _Object$defineProperty(exports, "createCameraTrack", {
   enumerable: true,
   get: function get() {
@@ -65,4 +77,5 @@ _Object$defineProperty(exports, "createMicrophoneTrack", {
   }
 });
 var _webrtcCore = require("./webrtc-core");
+var _webMediaEffects = require("@webex/web-media-effects");
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"names":[],"sources":["index.ts"],"sourcesContent":["export {\n  LocalTrack,\n  LocalDisplayTrack,\n  LocalTrackEvents,\n  type TrackMuteEvent,\n  type ServerMuteReason,\n  LocalMicrophoneTrackEvents,\n  LocalCameraTrackEvents,\n  LocalMicrophoneTrack,\n  LocalCameraTrack,\n  createMicrophoneTrack,\n  createCameraTrack,\n  createDisplayTrack,\n} from './webrtc-core';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA"}
+{"version":3,"names":[],"sources":["index.ts"],"sourcesContent":["export {\n  LocalTrack,\n  LocalDisplayTrack,\n  LocalTrackEvents,\n  type TrackMuteEvent,\n  type ServerMuteReason,\n  LocalMicrophoneTrackEvents,\n  LocalCameraTrackEvents,\n  LocalMicrophoneTrack,\n  LocalCameraTrack,\n  createMicrophoneTrack,\n  createCameraTrack,\n  createDisplayTrack,\n} from './webrtc-core';\n\nexport {NoiseReductionEffect, VirtualBackgroundEffect} from '@webex/web-media-effects';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAeA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webex/media-helpers",
-  "version": "3.0.0-beta.126",
+  "version": "3.0.0-beta.128",
   "description": "",
   "license": "Cisco EULA (https://www.cisco.com/c/en/us/products/end-user-license-agreement.html)",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
     "node": ">=16"
   },
   "dependencies": {
-    "@webex/internal-media-core": "1.38.2"
+    "@webex/internal-media-core": "1.38.2",
+    "@webex/web-media-effects": "^2.8.0"
   },
   "browserify": {
     "transform": [
@@ -23,8 +24,8 @@
     ]
   },
   "devDependencies": {
-    "@webex/test-helper-chai": "3.0.0-beta.126",
-    "@webex/test-helper-mock-webex": "3.0.0-beta.126",
+    "@webex/test-helper-chai": "3.0.0-beta.128",
+    "@webex/test-helper-mock-webex": "3.0.0-beta.128",
     "sinon": "^9.2.4"
   }
 }

package/src/index.ts

@@ -12,3 +12,5 @@ export {
   createCameraTrack,
   createDisplayTrack,
 } from './webrtc-core';
+
+export {NoiseReductionEffect, VirtualBackgroundEffect} from '@webex/web-media-effects';

package/test/unit/spec/webrtc-core.js

@@ -1,115 +1,134 @@
 import {assert, expect} from '@webex/test-helper-chai';
 import sinon from 'sinon';
-import {LocalCameraTrack, LocalMicrophoneTrack, LocalMicrophoneTrackEvents, LocalCameraTrackEvents, LocalDisplayTrack, createCameraTrack, createMicrophoneTrack, createDisplayTrack} from '@webex/media-helpers';
+import {
+  LocalCameraTrack,
+  LocalMicrophoneTrack,
+  LocalMicrophoneTrackEvents,
+  LocalCameraTrackEvents,
+  LocalDisplayTrack,
+  createCameraTrack,
+  createMicrophoneTrack,
+  createDisplayTrack,
+} from '../../../src/webrtc-core';
 import * as wcmetracks from '@webex/internal-media-core';
 
 describe('media-helpers', () => {
   describe('webrtc-core', () => {
-
     const classesToTest = [
-      {className: LocalCameraTrack, title: 'LocalCameraTrack', event: LocalCameraTrackEvents, createFn: createCameraTrack, spyFn: 'createCameraTrack'},
-      {className: LocalMicrophoneTrack, title: 'LocalMicrophoneTrack', event: LocalMicrophoneTrackEvents, createFn: createMicrophoneTrack, spyFn: 'createMicrophoneTrack'},
+      {
+        className: LocalCameraTrack,
+        title: 'LocalCameraTrack',
+        event: LocalCameraTrackEvents,
+        createFn: createCameraTrack,
+        spyFn: 'createCameraTrack',
+      },
+      {
+        className: LocalMicrophoneTrack,
+        title: 'LocalMicrophoneTrack',
+        event: LocalMicrophoneTrackEvents,
+        createFn: createMicrophoneTrack,
+        spyFn: 'createMicrophoneTrack',
+      },
     ];
 
     classesToTest.forEach(({className, title, event, createFn, spyFn}) =>
-    describe(title, () => {
-      const fakeStream = {
-        getTracks: sinon.stub().returns([{
-          label: 'fake track',
-          id: 'fake track id',
-          enabled: true,
-        }])
-      };
-      const track = new className(fakeStream);
-
-      afterEach(() => {
-        sinon.restore();
-      });
-
-      it('by default allows unmuting', async () => {
-        assert.equal(track.isUnmuteAllowed(), true);
-        await track.setMuted(false);
-      })
+      describe(title, () => {
+        const fakeStream = {
+          getTracks: sinon.stub().returns([
+            {
+              label: 'fake track',
+              id: 'fake track id',
+              enabled: true,
+            },
+          ]),
+        };
+        const track = new className(fakeStream);
 
-      it('rejects setMute(false) if unmute is not allowed', async () => {
-        track.setUnmuteAllowed(false);
+        afterEach(() => {
+          sinon.restore();
+        });
 
-        assert.equal(track.isUnmuteAllowed(), false);
-        const fn = () => track.setMuted(false);
-        expect(fn).to.throw(/Unmute is not allowed/);
-      });
+        it('by default allows unmuting', async () => {
+          assert.equal(track.isUnmuteAllowed(), true);
+          await track.setMuted(false);
+        });
 
-      it('resolves setMute(false) if unmute is allowed', async () => {
-        track.setUnmuteAllowed(true);
+        it('rejects setMute(false) if unmute is not allowed', async () => {
+          track.setUnmuteAllowed(false);
 
-        assert.equal(track.isUnmuteAllowed(), true);
-        await track.setMuted(false);
-      });
+          assert.equal(track.isUnmuteAllowed(), false);
+          const fn = () => track.setMuted(false);
+          expect(fn).to.throw(/Unmute is not allowed/);
+        });
 
-      describe('#setServerMuted', () => {
+        it('resolves setMute(false) if unmute is allowed', async () => {
+          track.setUnmuteAllowed(true);
 
-        afterEach(() => {
-          sinon.restore();
+          assert.equal(track.isUnmuteAllowed(), true);
+          await track.setMuted(false);
         });
 
-        const checkSetServerMuted = async (startMute, setMute, expectedCalled) => {
-          await track.setMuted(startMute);
+        describe('#setServerMuted', () => {
+          afterEach(() => {
+            sinon.restore();
+          });
 
-          assert.equal(track.muted, startMute);
+          const checkSetServerMuted = async (startMute, setMute, expectedCalled) => {
+            await track.setMuted(startMute);
 
-          const handler = sinon.fake();
-          track.on(event.ServerMuted, handler);
+            assert.equal(track.muted, startMute);
 
-          await track.setServerMuted(setMute, 'remotelyMuted');
+            const handler = sinon.fake();
+            track.on(event.ServerMuted, handler);
 
-          assert.equal(track.muted, setMute);
-          if (expectedCalled) {
-            assert.calledOnceWithExactly(handler, {muted: setMute, reason: 'remotelyMuted'});
-          } else {
-            assert.notCalled(handler);
-          }
-        };
+            await track.setServerMuted(setMute, 'remotelyMuted');
 
-        it('tests true to false', async () => {
-          await checkSetServerMuted(true, false, true);
-        });
-  
-        it('tests false to true', async () => {
-          await checkSetServerMuted(false, true, true);
-        });
-  
-        it('tests true to true', async () => {
-          await checkSetServerMuted(true, true, false);
-        });
-  
-        it('tests false to false', async () => {
-          await checkSetServerMuted(false, false, false);
-        });
-      });
+            assert.equal(track.muted, setMute);
+            if (expectedCalled) {
+              assert.calledOnceWithExactly(handler, {muted: setMute, reason: 'remotelyMuted'});
+            } else {
+              assert.notCalled(handler);
+            }
+          };
+
+          it('tests true to false', async () => {
+            await checkSetServerMuted(true, false, true);
+          });
+
+          it('tests false to true', async () => {
+            await checkSetServerMuted(false, true, true);
+          });
 
-      describe('#wcmeCreateMicrophoneTrack, #wcmeCreateCameraTrack', () => {
-        it('checks creating tracks', async () => {
-          const constraints = {devideId: 'abc'};
-  
-          const spy = sinon.stub(wcmetracks, spyFn).returns('something');
-          const result = createFn(constraints);
-  
-          assert.equal(result, 'something');
-          assert.calledOnceWithExactly(spy, className, constraints);
+          it('tests true to true', async () => {
+            await checkSetServerMuted(true, true, false);
+          });
+
+          it('tests false to false', async () => {
+            await checkSetServerMuted(false, false, false);
+          });
         });
-      });
 
-    })
-  );
+        describe('#wcmeCreateMicrophoneTrack, #wcmeCreateCameraTrack', () => {
+          it('checks creating tracks', async () => {
+            const constraints = {devideId: 'abc'};
 
-  describe('createDisplayTrack', () => {
-    it('checks createDisplayTrack', async () => {
-      const spy = sinon.stub(wcmetracks, 'createDisplayTrack').returns('something');
-      const result = createDisplayTrack();
-      assert.equal(result, 'something');
-      assert.calledOnceWithExactly(spy, LocalDisplayTrack);
-    });
+            const spy = sinon.stub(wcmetracks, spyFn).returns('something');
+            const result = createFn(constraints);
 
+            assert.equal(result, 'something');
+            assert.calledOnceWithExactly(spy, className, constraints);
+          });
+        });
+      })
+    );
+
+    describe('createDisplayTrack', () => {
+      it('checks createDisplayTrack', async () => {
+        const spy = sinon.stub(wcmetracks, 'createDisplayTrack').returns('something');
+        const result = createDisplayTrack();
+        assert.equal(result, 'something');
+        assert.calledOnceWithExactly(spy, LocalDisplayTrack);
+      });
+    });
   });
- });
-});
+});