@yang__yj/pixelstreaming-core 1.0.0 → 1.0.1

package/jest.config.js

@@ -0,0 +1,18 @@
+module.exports = {
+  preset: "ts-jest/presets/js-with-ts",
+  testEnvironment: "jsdom",
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        tsconfig: "tsconfig.jest.json",
+      },
+    ],
+  },
+  modulePathIgnorePatterns: ["<rootDir>/build/"],
+  testPathIgnorePatterns: ["<rootDir>/build/", "/node_modules/"],
+  globals: {
+    TextDecoder: TextDecoder,
+    TextEncoder: TextEncoder,
+  }
+};

package/package.json

@@ -1,18 +1,46 @@
-{
-  "name": "@yang__yj/pixelstreaming-core",
-  "version": "1.0.0",
-  "main": "library/dist/lib-pixelstreamingfrontend.js",
-  "module": "library/dist/lib-pixelstreamingfrontend.esm.js",
-  "types": "library/types/pixelstreamingfrontend.d.ts",
-  "files": [
-    "library/dist",
-    "library/types"
-  ],
-  "scripts": {
-    "prepublishOnly": "echo using existing build"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "ISC"
-}
+{
+    "name": "@yang__yj/pixelstreaming-core",
+    "version": "1.0.1",
+    "description": "Frontend library for Unreal Engine 5.3 Pixel Streaming",
+    "main": "dist/lib-pixelstreamingfrontend.js",
+    "module": "dist/lib-pixelstreamingfrontend.esm.js",
+    "types": "types/pixelstreamingfrontend.d.ts",
+    "sideEffects": false,
+    "scripts": {
+        "compile": "tsc --build --clean && tsc",
+        "build": "npx webpack --config webpack.prod.js",
+        "build-dev": "npx webpack --config webpack.dev.js",
+        "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
+        "test": "jest --detectOpenHandles --coverage=true",
+        "spellcheck": "cspell \"{README.md,.github/*.md,src/**/*.ts}\""
+    },
+    "devDependencies": {
+        "@types/jest": "27.5.1",
+        "@types/webxr": "^0.5.1",
+        "@typescript-eslint/eslint-plugin": "^5.16.0",
+        "@typescript-eslint/parser": "^5.16.0",
+        "cspell": "^4.1.0",
+        "eslint": "^8.11.0",
+        "jest": "^27.5.1",
+        "jest-environment-jsdom": "27.5.1",
+        "prettier": "2.8.3",
+        "ts-jest": "27.1.5",
+        "ts-loader": "^9.4.2",
+        "typedoc": "^0.23.24",
+        "typescript": "^4.9.4",
+        "webpack": "^5.75.0",
+        "webpack-cli": "^5.0.1"
+    },
+    "dependencies": {
+        "sdp": "^3.1.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/EpicGames/PixelStreamingInfrastructure.git"
+    },
+    "author": "Epic Games",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/readme.md

@@ -0,0 +1,15 @@
+## lib-pixelstreamingfrontend
+
+The core library for the browser/client side of Pixel Streaming experiences. **This library contains no UI.**
+
+See [lib-pixelstreamingfrontend-ui](/Frontend/implementations/typescript) for an example of how to build UI on top of this library.
+
+### Key features
+- Create a websocket connection to communicate with the signalling server.
+- Create a WebRTC player that displays the Unreal Engine video and audio.
+- Handling of input from the user and transmitting it back to Unreal Engine.
+- Opens a datachannel connection sending and receiving custom data (in addition to input).
+
+### Adding it to your project
+`npm i @epicgames-ps/lib-pixelstreamingfrontend-ue5.3`
+

package/src/AFK/AFKController.test.ts

@@ -0,0 +1,162 @@
+import { Config, Flags, NumericParameters } from '../Config/Config';
+import { PixelStreaming } from '../PixelStreaming/PixelStreaming';
+import { AfkTimedOutEvent, AfkWarningActivateEvent, AfkWarningUpdateEvent, AfkWarningDeactivateEvent } from '../Util/EventEmitter';
+import { mockRTCRtpReceiver, unmockRTCRtpReceiver } from '../__test__/mockRTCRtpReceiver';
+import {
+    AFKController
+} from './AFKController';
+
+describe('AFKController', () => {
+    let mockPixelStreaming: PixelStreaming;
+
+    beforeEach(() => {
+        mockRTCRtpReceiver();
+        jest.useFakeTimers();
+        mockPixelStreaming = {
+            dispatchEvent: jest.fn()
+        } as any as PixelStreaming; 
+    });
+
+    afterEach(() => {
+        unmockRTCRtpReceiver();
+        jest.resetAllMocks();
+    });
+
+    it('should not activate AFK timer if it has been disabled from settings', () => {
+        const config = new Config({ initialSettings: { [Flags.AFKDetection]: false } });
+        const onDismissAfk = jest.fn();
+        const afkController = new AFKController(config, mockPixelStreaming, onDismissAfk);
+
+        afkController.startAfkWarningTimer();
+        expect(afkController.active).toBe(false);
+
+        jest.advanceTimersByTime(1000000 * 1000);
+        expect(mockPixelStreaming.dispatchEvent).not.toHaveBeenCalled();
+    });
+
+    it('should activate AFK timer and trigger it after specified delay if it has been enabled from settings', () => {
+        const timeoutSeconds = 100;
+
+        const config = new Config({ initialSettings: { [Flags.AFKDetection]: true, [NumericParameters.AFKTimeoutSecs]: timeoutSeconds} });
+        const onDismissAfk = jest.fn();
+        const afkController = new AFKController(config, mockPixelStreaming, onDismissAfk);
+
+        afkController.startAfkWarningTimer();
+        expect(afkController.active).toBe(true);
+
+        // Advance to 1 second before AFK event:
+        jest.advanceTimersByTime((timeoutSeconds - 1) * 1000);
+        expect(mockPixelStreaming.dispatchEvent).not.toHaveBeenCalled();
+        
+        // advance 1 more second to trigger AFK warning
+        jest.advanceTimersByTime(1000);
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningActivateEvent({
+            countDown: 0,
+            dismissAfk: expect.anything()
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 10,
+        }));
+
+        // advance 10 more seconds to trigger AFK countdown updates and eventually timeout
+        jest.advanceTimersByTime(10 * 1000);
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 9,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 8,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 7,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 6,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 5,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 4,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 3,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 2,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 1,
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkTimedOutEvent());
+    });
+
+    it('should postpone AFK activation each time resetAfkWarningTimer is called', () => {
+        const timeoutSeconds = 100;
+
+        const config = new Config({ initialSettings: { [Flags.AFKDetection]: true, [NumericParameters.AFKTimeoutSecs]: timeoutSeconds} });
+        const onDismissAfk = jest.fn();
+        const afkController = new AFKController(config, mockPixelStreaming, onDismissAfk);
+
+        afkController.startAfkWarningTimer();
+
+        // Advance to 1 second before AFK event:
+        jest.advanceTimersByTime((timeoutSeconds - 1) * 1000);
+        expect(mockPixelStreaming.dispatchEvent).not.toHaveBeenCalled();
+
+        afkController.resetAfkWarningTimer();
+        
+        // advance 1 more second and ensure that AFK warning is not triggered since reset was called
+        jest.advanceTimersByTime(1000);
+        expect(mockPixelStreaming.dispatchEvent).not.toHaveBeenCalled();
+
+        // reset AFK timer once more and ensure it is triggered exactly after timeoutSeconds
+        afkController.resetAfkWarningTimer();
+
+        // Advance to 1 second before AFK event:
+        jest.advanceTimersByTime((timeoutSeconds - 1) * 1000);
+        expect(mockPixelStreaming.dispatchEvent).not.toHaveBeenCalled();
+
+        // advance 1 more second to trigger AFK warning
+        jest.advanceTimersByTime(1000);
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningActivateEvent({
+            countDown: 0,
+            dismissAfk: expect.anything()
+        }));
+    });
+
+    it('should dismiss AFK warning countdown if onAfkClick is called', () => {
+        const timeoutSeconds = 100;
+
+        const config = new Config({ initialSettings: { [Flags.AFKDetection]: true, [NumericParameters.AFKTimeoutSecs]: timeoutSeconds} });
+        const onDismissAfk = jest.fn();
+        const afkController = new AFKController(config, mockPixelStreaming, onDismissAfk);
+
+        afkController.startAfkWarningTimer();
+
+        // Advance to AFK event:
+        jest.advanceTimersByTime(timeoutSeconds * 1000);
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningActivateEvent({
+            countDown: 0,
+            dismissAfk: expect.anything()
+        }));
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 10,
+        }));
+
+        // Advance one more second and call onAfkClick
+        jest.advanceTimersByTime(1000);
+
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningUpdateEvent({
+            countDown: 9,
+        }));
+
+        afkController.onAfkClick();
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledWith(new AfkWarningDeactivateEvent());
+
+        // advance 10 more seconds and ensure there are no more countdown/timeout events emitted
+        jest.advanceTimersByTime(10 * 1000);
+        expect(mockPixelStreaming.dispatchEvent).toHaveBeenCalledTimes(4);
+    });
+
+
+});

package/src/AFK/AFKController.ts

@@ -0,0 +1,158 @@
+// Copyright Epic Games, Inc. All Rights Reserved.
+
+import { Config, Flags, NumericParameters } from '../Config/Config';
+import { Logger } from '../Logger/Logger';
+import { PixelStreaming } from '../PixelStreaming/PixelStreaming';
+import {
+    AfkTimedOutEvent,
+    AfkWarningActivateEvent,
+    AfkWarningDeactivateEvent,
+    AfkWarningUpdateEvent
+} from '../Util/EventEmitter';
+
+export class AFKController {
+    // time out logic details
+    closeTimeout = 10;
+    active = false;
+    countdownActive = false;
+    warnTimer: ReturnType<typeof setTimeout> = undefined;
+    countDown = 0;
+    countDownTimer: ReturnType<typeof setInterval> = undefined;
+    config: Config;
+    pixelStreaming: PixelStreaming;
+    onDismissAfk: () => void;
+
+    onAFKTimedOutCallback: () => void;
+
+    constructor(
+        config: Config,
+        pixelStreaming: PixelStreaming,
+        onDismissAfk: () => void
+    ) {
+        this.config = config;
+        this.pixelStreaming = pixelStreaming;
+        this.onDismissAfk = onDismissAfk;
+        this.onAFKTimedOutCallback = () => {
+            console.log(
+                'AFK timed out, did you want to override this callback?'
+            );
+        };
+    }
+
+    /**
+     * The methods that occur when an afk event listener is clicked
+     */
+    onAfkClick() {
+        clearInterval(this.countDownTimer);
+
+        if (this.active || this.countdownActive) {
+            this.startAfkWarningTimer();
+            this.pixelStreaming.dispatchEvent(
+                new AfkWarningDeactivateEvent()
+            );
+        }
+    }
+
+    /**
+     * Start the warning timer if a timeout is set greater that 0 seconds
+     */
+    startAfkWarningTimer() {
+        if (
+            this.config.getNumericSettingValue(
+                NumericParameters.AFKTimeoutSecs
+            ) > 0 &&
+            this.config.isFlagEnabled(Flags.AFKDetection)
+        ) {
+            this.active = true;
+        } else {
+            this.active = false;
+        }
+        this.resetAfkWarningTimer();
+    }
+
+    /**
+     * Stop the afk warning timer
+     */
+    stopAfkWarningTimer() {
+        this.active = false;
+        this.countdownActive = false;
+        clearTimeout(this.warnTimer);
+        clearInterval(this.countDownTimer);
+    }
+
+    /**
+     * Pause the timer which when elapsed will warn the user they are inactive.
+     */
+    pauseAfkWarningTimer() {
+        this.active = false;
+    }
+
+    /**
+     * If the user interacts then reset the warning timer.
+     */
+    resetAfkWarningTimer() {
+        if (this.active && this.config.isFlagEnabled(Flags.AFKDetection)) {
+            clearTimeout(this.warnTimer);
+            this.warnTimer = setTimeout(
+                () => this.activateAfkEvent(),
+                this.config.getNumericSettingValue(
+                    NumericParameters.AFKTimeoutSecs
+                ) * 1000
+            );
+        }
+    }
+
+    /**
+     * Show the AFK overlay and begin the countDown
+     */
+    activateAfkEvent() {
+        // Pause the timer while the user is looking at the inactivity warning overlay
+        this.pauseAfkWarningTimer();
+
+        // instantiate a new overlay
+        this.pixelStreaming.dispatchEvent(
+            new AfkWarningActivateEvent({
+                countDown: this.countDown,
+                dismissAfk: this.onDismissAfk
+            })
+        );
+
+        // update our countDown timer and overlay contents
+        this.countDown = this.closeTimeout;
+        this.countdownActive = true;
+        this.pixelStreaming.dispatchEvent(
+            new AfkWarningUpdateEvent({ countDown: this.countDown })
+        );
+
+        // if we are in locked mouse exit pointerlock
+        if (!this.config.isFlagEnabled(Flags.HoveringMouseMode)) {
+            // minor hack to alleviate ios not supporting pointerlock
+            if (document.exitPointerLock) {
+                document.exitPointerLock();
+            }
+        }
+
+        // reset our countDown interval accordingly
+        this.countDownTimer = setInterval(() => {
+            this.countDown--;
+            if (this.countDown == 0) {
+                // The user failed to click so hide the overlay and disconnect them.
+                this.pixelStreaming.dispatchEvent(
+                    new AfkTimedOutEvent()
+                );
+                this.onAFKTimedOutCallback();
+                Logger.Log(
+                    Logger.GetStackTrace(),
+                    'You have been disconnected due to inactivity'
+                );
+
+                // switch off the afk feature as stream has closed
+                this.stopAfkWarningTimer();
+            } else {
+                this.pixelStreaming.dispatchEvent(
+                    new AfkWarningUpdateEvent({ countDown: this.countDown })
+                );
+            }
+        }, 1000);
+    }
+}

package/src/Config/Config.test.ts

@@ -0,0 +1,222 @@
+import { mockRTCRtpReceiver, unmockRTCRtpReceiver } from '../__test__/mockRTCRtpReceiver';
+import {
+    Config,
+    Flags,
+    FlagsKeys,
+    NumericParameters,
+    NumericParametersKeys,
+    OptionParameters,
+    OptionParametersKeys,
+    TextParameters,
+    TextParametersKeys
+} from './Config';
+
+const allFlags = Object.keys(Flags).map((key) => Flags[key as FlagsKeys]);
+const allNumericParameters = Object.keys(NumericParameters).map(
+    (key) => NumericParameters[key as NumericParametersKeys]
+);
+const allTextParameters = Object.keys(TextParameters).map(
+    (key) => TextParameters[key as TextParametersKeys]
+);
+const allOptionParameters = Object.keys(OptionParameters).map(
+    (key) => OptionParameters[key as OptionParametersKeys]
+);
+
+const allParameters = [
+    ...allFlags,
+    ...allNumericParameters,
+    ...allTextParameters,
+    ...allOptionParameters
+];
+
+describe('Config', () => {
+    beforeEach(() => {
+        mockRTCRtpReceiver();
+    });
+
+    afterEach(() => {
+        unmockRTCRtpReceiver();
+        jest.resetAllMocks();
+    });
+
+    it('should populate initial values for all settings when initialized without parameters', () => {
+        const config = new Config();
+
+        const settings = config.getSettings();
+        expect(Object.keys(settings)).toEqual(
+            expect.arrayContaining(allParameters)
+        );
+    });
+
+    it('should populate given initial setting values', () => {
+        const initialSettings = {
+            [Flags.AutoPlayVideo]: false,
+            [NumericParameters.WebRTCMaxBitrate]: 12345,
+            [TextParameters.SignallingServerUrl]: 'url'
+        };
+
+        const config = new Config({ initialSettings });
+
+        expect(config.isFlagEnabled(Flags.AutoPlayVideo)).toEqual(
+            initialSettings[Flags.AutoPlayVideo]
+        );
+        expect(
+            config.getNumericSettingValue(NumericParameters.WebRTCMaxBitrate)
+        ).toEqual(initialSettings[NumericParameters.WebRTCMaxBitrate]);
+        expect(
+            config.getTextSettingValue(TextParameters.SignallingServerUrl)
+        ).toEqual(initialSettings[TextParameters.SignallingServerUrl]);
+    });
+
+    it('should replace setting values when new settings are set with setSettings', () => {
+        const config = new Config();
+
+        const preferredCodecs = ['c1', 'c2', 'c3'];
+        config.setOptionSettingOptions(
+            OptionParameters.PreferredCodec,
+            preferredCodecs
+        );
+
+        const changedSettings = {
+            [Flags.AutoPlayVideo]: false,
+            [NumericParameters.WebRTCMaxBitrate]: 54321,
+            [TextParameters.SignallingServerUrl]: 'signalling-url',
+            [OptionParameters.PreferredCodec]: 'c2'
+        };
+
+        config.setSettings(changedSettings);
+
+        expect(config.isFlagEnabled(Flags.AutoPlayVideo)).toEqual(
+            changedSettings[Flags.AutoPlayVideo]
+        );
+        expect(
+            config.getNumericSettingValue(NumericParameters.WebRTCMaxBitrate)
+        ).toEqual(changedSettings[NumericParameters.WebRTCMaxBitrate]);
+        expect(
+            config.getTextSettingValue(TextParameters.SignallingServerUrl)
+        ).toEqual(changedSettings[TextParameters.SignallingServerUrl]);
+        expect(
+            config.getSettingOption(OptionParameters.PreferredCodec).selected
+        ).toEqual(changedSettings[OptionParameters.PreferredCodec]);
+    });
+
+    it('should replace setting values when new settings are set with set* setters', () => {
+        const config = new Config();
+
+        const preferredCodecs = ['c1', 'c2', 'c3'];
+        config.setOptionSettingOptions(
+            OptionParameters.PreferredCodec,
+            preferredCodecs
+        );
+
+        const changedSettings = {
+            [Flags.AutoPlayVideo]: false,
+            [NumericParameters.WebRTCMaxBitrate]: 54321,
+            [TextParameters.SignallingServerUrl]: 'signalling-url',
+            [OptionParameters.PreferredCodec]: 'c2'
+        };
+
+        config.setFlagEnabled(
+            Flags.AutoPlayVideo,
+            changedSettings[Flags.AutoPlayVideo]
+        );
+        config.setNumericSetting(
+            NumericParameters.WebRTCMaxBitrate,
+            changedSettings[NumericParameters.WebRTCMaxBitrate]
+        );
+        config.setTextSetting(
+            TextParameters.SignallingServerUrl,
+            changedSettings[TextParameters.SignallingServerUrl]
+        );
+        config.setOptionSettingValue(
+            OptionParameters.PreferredCodec,
+            changedSettings[OptionParameters.PreferredCodec]
+        );
+
+        expect(config.isFlagEnabled(Flags.AutoPlayVideo)).toEqual(
+            changedSettings[Flags.AutoPlayVideo]
+        );
+        expect(
+            config.getNumericSettingValue(NumericParameters.WebRTCMaxBitrate)
+        ).toEqual(changedSettings[NumericParameters.WebRTCMaxBitrate]);
+        expect(
+            config.getTextSettingValue(TextParameters.SignallingServerUrl)
+        ).toEqual(changedSettings[TextParameters.SignallingServerUrl]);
+        expect(
+            config.getSettingOption(OptionParameters.PreferredCodec).selected
+        ).toEqual(changedSettings[OptionParameters.PreferredCodec]);
+    });
+
+    it('should persist config changes to window.location URL when updateURLParams() is called', () => {
+        const config = new Config({ useUrlParams: true });
+
+        const preferredCodecs = ['c1', 'c2', 'c3'];
+        config.setOptionSettingOptions(
+            OptionParameters.PreferredCodec,
+            preferredCodecs
+        );
+
+        const changedSettings = {
+            [Flags.AutoPlayVideo]: false,
+            [NumericParameters.WebRTCMaxBitrate]: 54321,
+            [TextParameters.SignallingServerUrl]: 'signalling-url',
+            [OptionParameters.PreferredCodec]: 'c2'
+        };
+
+        config.setSettings(changedSettings);
+
+        config
+            .getFlags()
+            .find((setting) => setting.id === Flags.AutoPlayVideo)
+            ?.updateURLParams();
+        config
+            .getNumericSettings()
+            .find(
+                (setting) => setting.id === NumericParameters.WebRTCMaxBitrate
+            )
+            ?.updateURLParams();
+        config
+            .getTextSettings()
+            .find(
+                (setting) => setting.id === TextParameters.SignallingServerUrl
+            )
+            ?.updateURLParams();
+        config
+            .getOptionSettings()
+            .find((setting) => setting.id === OptionParameters.PreferredCodec)
+            ?.updateURLParams();
+
+        const urlParams = new URLSearchParams(window.location.search);
+
+        expect(urlParams.get(Flags.AutoPlayVideo)).toEqual(
+            changedSettings[Flags.AutoPlayVideo].toString()
+        );
+        expect(urlParams.get(NumericParameters.WebRTCMaxBitrate)).toEqual(
+            changedSettings[NumericParameters.WebRTCMaxBitrate].toString()
+        );
+        expect(urlParams.get(TextParameters.SignallingServerUrl)).toEqual(
+            changedSettings[TextParameters.SignallingServerUrl].toString()
+        );
+        expect(urlParams.get(OptionParameters.PreferredCodec)).toEqual(
+            changedSettings[OptionParameters.PreferredCodec].toString()
+        );
+    });
+
+    it('should read initial config from window.location URL if initialized with useUrlParams: true', () => {
+        window.history.replaceState(
+            {},
+            '',
+            'http://localhost/?AutoPlayVideo=false&WebRTCMaxBitrate=43210&ss=signalling-url-from-url-param'
+        );
+
+        const config = new Config({ useUrlParams: true });
+
+        expect(config.isFlagEnabled(Flags.AutoPlayVideo)).toEqual(false);
+        expect(
+            config.getNumericSettingValue(NumericParameters.WebRTCMaxBitrate)
+        ).toEqual(43210);
+        expect(
+            config.getTextSettingValue(TextParameters.SignallingServerUrl)
+        ).toEqual('signalling-url-from-url-param');
+    });
+});