@3dsource/angular-unreal-module 0.0.93 → 0.0.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3dsource/angular-unreal-module",
-  "version": "0.0.93",
+  "version": "0.0.97",
   "description": "Angular Unreal module for connect with unreal engine stream",
   "keywords": [
     "3dsource",

package/types/3dsource-angular-unreal-module.d.ts

@@ -361,10 +361,6 @@ declare const DEFAULT_RECONNECT_DELAY_MS = 1000;
 declare const DEFAULT_RECONNECT_ON_ICE_FAILURE = true;
 declare const DEFAULT_RECONNECT_ON_DATACHANNEL_CLOSE = true;
 
-declare function provideAngularUnrealModule(config?: {
-    playwright: boolean;
-}): i0.EnvironmentProviders;
-
 interface NormalizeAndQuantizeUnsignedValue {
     inRange: boolean;
     x: number;
@@ -1031,6 +1027,182 @@ declare class AnalyticsService {
     static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsService>;
 }
 
+/**
+ * Adaptive FPS controller that monitors the incoming WebRTC video stream
+ * quality and dynamically adjusts Unreal Engine's `t.MaxFPS` console variable.
+ *
+ * ## How it works
+ *
+ * The service subscribes to `VideoService.videoStats$` (emitted every 250 ms)
+ * and collects samples of FPS, bitrate, and QP (Quantisation Parameter).
+ * Every {@link SAMPLE_WINDOW} ticks (~2 s) it averages the collected samples
+ * and feeds them into a set of **fuzzy-logic membership functions** that
+ * classify each metric into overlapping quality bands.
+ *
+ * ### Input signals
+ *
+ * **1. FPS ratio** = `actualFPS / currentTargetFPS` (0..1+)
+ *
+ * | Band   | Range               | Meaning                                       |
+ * |--------|---------------------|-----------------------------------------------|
+ * | low    | ratio < 0.7 → 1.0, linear ramp 0.7..0.9 → 0   | Stream cannot keep up with the target         |
+ * | ok     | triangle 0.8..1.0, peak at 0.95                 | Stream roughly matches the target             |
+ * | high   | ratio 0.9..1.0 → ramp, >1.0 → 1.0              | Stream meets or exceeds the target            |
+ *
+ * **2. Bitrate load** = `currentBitrate / MAX_BITRATE` (0..1+)
+ *
+ * `MAX_BITRATE` = 20 Mbit/s — the reference ceiling for the encoder.
+ *
+ * | Band   | Range                                           | Meaning                                       |
+ * |--------|-------------------------------------------------|-----------------------------------------------|
+ * | high   | load 0.5..0.8 → ramp, >0.8 → 1.0               | Encoder is using most of the available bandwidth |
+ * | not high | load < 0.5 → 0.0                              | Bandwidth headroom is available                |
+ *
+ * **3. Quality** — mapped from QP via `mapQpToQuality()` (see {@link Quality}):
+ *
+ * | Quality  | QP range  | Meaning                                         |
+ * |----------|-----------|-------------------------------------------------|
+ * | `lime`   | QP <= 26  | Good — encoder has enough headroom              |
+ * | `orange` | QP 27..35 | Fair — encoder is under moderate pressure        |
+ * | `red`    | QP > 35   | Poor — heavy compression, visible artefacts      |
+ *
+ * ### Decision rules (evaluated in priority order, first match wins)
+ *
+ * | # | Condition                                                  | Decision     |
+ * |---|------------------------------------------------------------|--------------|
+ * | 1 | FPS ratio is **low** (membership > 0.5)                    | **decrease** |
+ * | 2 | FPS ratio is **ok** AND quality is `red`                   | **decrease** |
+ * | 3 | FPS ratio is **ok** AND bitrate **high** AND quality is `orange` | **hold** |
+ * | 4 | FPS ratio is **high** AND quality is `lime` AND bitrate **not high** | **increase** |
+ * | — | Everything else                                            | **hold**     |
+ *
+ * ## Cooldown-based throttling
+ *
+ * The service continuously evaluates fuzzy rules every sample window.
+ * After each FPS step change it enforces a cooldown before the next
+ * change can be applied. The cooldown duration depends on the
+ * (previous decision → next decision) pair:
+ *
+ * | Previous  | Next      | Cooldown                                            |
+ * |-----------|-----------|-----------------------------------------------------|
+ * | decrease  | decrease  | {@link COOLDOWN_DECREASE_AFTER_DECREASE_MS} (2 s)   |
+ * | decrease  | increase  | {@link COOLDOWN_INCREASE_AFTER_DECREASE_MS} (10 s)  |
+ * | increase  | decrease  | {@link COOLDOWN_AFTER_INCREASE_MS} (2 s)            |
+ * | increase  | increase  | {@link COOLDOWN_AFTER_INCREASE_MS} (2 s)            |
+ *
+ * This means the system reacts quickly after an increase (2 s in any
+ * direction) but is cautious about stepping back up after a decrease
+ * (10 s), while still allowing consecutive decreases at 2 s intervals.
+ *
+ * ## FPS dispatch
+ *
+ * FPS changes are dispatched via the NgRx `setMaxFps` action, which triggers
+ * the existing `UnrealEffects.setMaxFps$` effect that sends the
+ * `t.MaxFPS <value>` console command to Unreal Engine.
+ */
+declare class FpsMonitorService {
+    private videoService;
+    private store;
+    /** Discrete FPS targets the controller can switch between (ascending order). */
+    private readonly FPS_STEPS;
+    /** Reference ceiling for bitrate (bits/sec) used to normalise bitrate load to 0..1. */
+    private readonly MAX_BITRATE;
+    /**
+     * Cooldown (ms) for any decision (increase or decrease) following an increase.
+     * After an increase the system should react faster.
+     */
+    private readonly COOLDOWN_AFTER_INCREASE_MS;
+    /**
+     * Cooldown (ms) for a decrease following a previous decrease.
+     */
+    private readonly COOLDOWN_DECREASE_AFTER_DECREASE_MS;
+    /**
+     * Cooldown (ms) for an increase following a previous decrease.
+     * The stream needs more time to stabilise before stepping back up.
+     */
+    private readonly COOLDOWN_INCREASE_AFTER_DECREASE_MS;
+    /**
+     * Number of videoStats$ ticks to accumulate before evaluating.
+     * At 250 ms per tick this gives a ~2 s sliding evaluation window,
+     * long enough to smooth out single-frame jitter.
+     */
+    private readonly SAMPLE_WINDOW;
+    /** Current FPS target; starts at max (60 FPS) and adapts downward/upward. */
+    private currentFpsTarget;
+    private samples;
+    private lastDecisionTime;
+    private lastUpgrade;
+    constructor();
+    protected init(): void;
+    /**
+     * Called on every videoStats$ emission (~250 ms).
+     * Accumulates samples and evaluates once per SAMPLE_WINDOW.
+     */
+    private processTick;
+    private handleMonitoring;
+    /**
+     * Combines fuzzy membership values into a single discrete decision.
+     * Rules are evaluated in priority order — first match wins.
+     *
+     * Inputs:
+     * - `fpsRatio`    = avgFPS / currentTargetFPS  (e.g. 45/60 = 0.75)
+     * - `bitrateLoad` = avgBitrate / 20 Mbit/s     (e.g. 12M/20M = 0.6)
+     * - `quality`     = mapQpToQuality(avgQP)       → 'lime' | 'orange' | 'red'
+     */
+    private evaluateDecision;
+    /**
+     * FPS ratio membership "low".
+     * Input: ratio = actualFPS / targetFPS (e.g. 42/60 = 0.70).
+     *
+     *   ratio < 0.7  → 1.0  (clearly failing, e.g. 40/60)
+     *   ratio 0.7..0.9 → linear ramp down (e.g. 0.8 → 0.5)
+     *   ratio > 0.9  → 0.0  (keeping up)
+     */
+    private membershipFpsLow;
+    /**
+     * FPS ratio membership "ok" — triangle shape.
+     * Input: ratio = actualFPS / targetFPS.
+     *
+     *   ratio < 0.8  → 0.0
+     *   ratio 0.8..0.95 → ramp up, peak at 0.95 (e.g. 57/60)
+     *   ratio 0.95..1.0 → ramp down
+     *   ratio > 1.0  → 0.0
+     */
+    private membershipFpsOk;
+    /**
+     * FPS ratio membership "high".
+     * Input: ratio = actualFPS / targetFPS.
+     *
+     *   ratio < 0.9  → 0.0
+     *   ratio 0.9..1.0 → linear ramp up (e.g. 0.95 → 0.5)
+     *   ratio >= 1.0 → 1.0  (meeting or exceeding target, e.g. 60/60)
+     */
+    private membershipFpsHigh;
+    /**
+     * Bitrate load membership "high".
+     * Input: load = currentBitrate / MAX_BITRATE (20 Mbit/s).
+     *
+     *   load < 0.5  → 0.0  (below 10 Mbit/s — plenty of headroom)
+     *   load 0.5..0.8 → linear ramp (e.g. 13M/20M = 0.65 → 0.5)
+     *   load > 0.8  → 1.0  (above 16 Mbit/s — near capacity)
+     */
+    private membershipBitrateHigh;
+    private upgradeFps;
+    /**
+     * Get the next FPS target based on current target and decision.
+     * Clamps to valid FPS_STEPS range.
+     */
+    private getNextFpsTarget;
+    /**
+     * Find the closest FPS step index for a given target value.
+     */
+    private findClosestFpsIndex;
+    /** Average all collected samples for the current evaluation window. */
+    private averageSamples;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FpsMonitorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FpsMonitorService>;
+}
+
 declare function AnswerHandler(this: SignallingService, msg: RTCSessionDescriptionInit): void;
 
 declare function ConfigHandler(this: SignallingService, msg: ConfigMessage): void;
@@ -1142,7 +1314,7 @@ declare class LatencyTimings {
     OnAllLatencyTimingsReady(_: any): void;
 }
 
-declare function mapQpToQuality(VideoEncoderQP: number): Quality;
+declare const mapQpToQuality: (VideoEncoderQP: number) => Quality;
 
 declare const trackMixpanelEvent: _ngrx_store.ActionCreator<string, (props: {
     event: string;
@@ -2163,5 +2335,9 @@ declare class SafePipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<SafePipe, "safe", true>;
 }
 
-export { AFKService, AfkPlaywrightService, AggregatorPlaywrightService, AggregatorService, AnalyticsService, AnswerHandler, CONSOLE_COMMAND_DISABLE_MESSAGES, CONSOLE_COMMAND_ENABLE_MESSAGES, CONSOLE_COMMAND_PIXEL_QUALITY, ClickableOverlayComponent, CommandTelemetryPlaywrightService, CommandTelemetryService, ConfigHandler, ConsoleExtensionsPlaywrightService, ConsoleExtensionsService, DATA_CHANNEL_CONNECTION_TIMEOUT, DEBOUNCE_TO_MANY_RESIZE_CALLS, DEFAULT_AFK_TIMEOUT, DEFAULT_AFK_TIMEOUT_PERIOD, DEFAULT_RECONNECT_DELAY_MS, DEFAULT_RECONNECT_ENABLED, DEFAULT_RECONNECT_MAX_ATTEMPTS, DEFAULT_RECONNECT_ON_DATACHANNEL_CLOSE, DEFAULT_RECONNECT_ON_ICE_FAILURE, DataFlowMonitor, DevModeService, DisconnectReason, EControlSchemeType, EMessageType, EToClientMessageType, FULL_HD_HEIGHT, FULL_HD_WIDTH, FileHandlerService, FileReceiverPlaywrightService, FileReceiverService, FilterSettingsComponent, FreezeFrameComponent, FreezeFramePlaywrightService, FreezeFrameService, IceCandidateHandler, ImageLoadingSrcComponent, InputOptions, InputPlaywrightService, InputService, InstanceReadyHandler, InstanceReservedHandler, IntroSrcComponent, KalmanFilter1D, LatencyTimings, LowBandwidthDetectorComponent, LowBandwidthModalComponent, MINIMAL_FPS, MouseButton, MouseButtonsMask, OnCloseHandler, OnErrorHandler, OnMessageHandler, OnOpenHandler, OrchestrationMessageTypes, POLLING_TIME, PingHandler, PlayerCountHandler, RegionsPingService, ResetTelemetry, SAME_SIZE_THRESHOLD, SCREEN_LOCKER_CONTAINER_ID, SIGNALLING_PERCENT_VALUE, SSInfoHandler, STREAMING_VIDEO_ID, SafePipe, SignallingPlaywrightService, SignallingService, SpecialKeyCodes, StatGraphComponent, StreamStatusTelemetryPlaywrightService, StreamStatusTelemetryService, SubService, TelemetryStart, TelemetryStop, UNREAL_CONFIG, UnrealCommunicatorPlaywrightService, UnrealCommunicatorService, UnrealEffects, UnrealInternalSignalEvents, UnrealSceneComponent, UnrealStatusMessage, VideoRecorder, VideoService, VideoStatsComponent, WSCloseCode_CIRRUS_ABNORMAL_CLOSURE, WSCloseCode_CIRRUS_MAX_PLAYERS_ERROR, WSCloseCode_CIRRUS_PLAYER_DISCONNECTED, WSCloseCode_CIRRUS_STREAMER_KIKED_PLAYER, WSCloseCode_FORCE_CIRRUS_CLOSE, WSCloseCode_NORMAL_AFK_TIMEOUT, WSCloseCode_NORMAL_CLOSURE, WSCloseCode_NORMAL_MANUAL_DISCONNECT, WSCloseCode_UNKNOWN, WSCloseCodes, WS_OPEN_STATE, WS_TIMEOUT, WebRtcPlayerService, WebrtcErrorModalComponent, abortEstablishingConnection, changeLowBandwidth, changeStatusMainVideoOnScene, changeStreamResolutionAction, changeStreamResolutionSuccessAction, commandCompleted, commandStarted, dataChannelConnected, dataChannelReady, decodeData, destroyRemoteConnections, destroyUnrealScene, disconnectStream, dispatchResize, dropConnection, floatToSmoothPercents, forceResizeUnrealVideo, fromResizeObserver, fromSignal, fromUnrealCallBackSignal, getActiveUrl, getImageFromVideoStream, getRtcErrorMessage, iceConnectionFailed, initSignalling, initialState, isLoaderScreenVisible, keepMaxUntilReset, mapQpToQuality, observeCommandResponse, provideAngularUnrealModule, reconnectPeer, reconnectPeerFailed, reconnectPeerSuccess, removeExileCommands, resetAfk, resetAfkAction, resetConfig, resetDataChannelForReconnect, resetIntroSrc, resetWarnTimeout, saveAnalyticsEvent, selectClientAndViewIds, selectCommandProgress, selectCommandsInProgress, selectFreezeFrameCombinedDataUrl, selectFreezeFrameDataUrl, selectFreezeFrameDataUrlFromVideo, selectFreezeFrameProgressMessageFromVideo, selectIsAutostart, selectIsExistMatchUrls, selectIsFreezeFrameLoading, selectIsVideoPlayingAndDataChannelConnected, selectLastCommandInProgress, selectLoaderCommands, selectShowLoader, selectShowReconnectPopup, selectSignalingParameters, selectStreamConfig, selectTotalProgress, selectWarnTimeout, sendSignal, setAfkTimerHide, setAfkTimerVisible, setAwsInstance, setCirrusConnected, setCirrusDisconnected, setConfig, setDataChannelConnected, setEstablishingConnection, setFreezeFrame, setFreezeFrameFromVideo, setIntroImageSrc, setIntroVideoSrc, setLoadingImageSrc, setLoopBackCommandIsCompleted, setMaxFps, setOrchestrationContext, setOrchestrationMessage, setOrchestrationParameters, setOrchestrationProgress, setSignalingName, setStatusMessage, setStatusPercentSignallingServer, setStreamClientCompanyId, setStreamViewId, setUnrealPlaywrightConfig, setViewportNotReady, setViewportReady, showPopupWithoutAutoStart, showUnrealErrorMessage, smoothTransition, startStream, trackMixpanelEvent, unrealFeature, unrealReducer, updateCirrusInfo };
+declare function provideAngularUnrealModule(config?: {
+    playwright: boolean;
+}): i0.EnvironmentProviders;
+
+export { AFKService, AfkPlaywrightService, AggregatorPlaywrightService, AggregatorService, AnalyticsService, AnswerHandler, CONSOLE_COMMAND_DISABLE_MESSAGES, CONSOLE_COMMAND_ENABLE_MESSAGES, CONSOLE_COMMAND_PIXEL_QUALITY, ClickableOverlayComponent, CommandTelemetryPlaywrightService, CommandTelemetryService, ConfigHandler, ConsoleExtensionsPlaywrightService, ConsoleExtensionsService, DATA_CHANNEL_CONNECTION_TIMEOUT, DEBOUNCE_TO_MANY_RESIZE_CALLS, DEFAULT_AFK_TIMEOUT, DEFAULT_AFK_TIMEOUT_PERIOD, DEFAULT_RECONNECT_DELAY_MS, DEFAULT_RECONNECT_ENABLED, DEFAULT_RECONNECT_MAX_ATTEMPTS, DEFAULT_RECONNECT_ON_DATACHANNEL_CLOSE, DEFAULT_RECONNECT_ON_ICE_FAILURE, DataFlowMonitor, DevModeService, DisconnectReason, EControlSchemeType, EMessageType, EToClientMessageType, FULL_HD_HEIGHT, FULL_HD_WIDTH, FileHandlerService, FileReceiverPlaywrightService, FileReceiverService, FilterSettingsComponent, FpsMonitorService, FreezeFrameComponent, FreezeFramePlaywrightService, FreezeFrameService, IceCandidateHandler, ImageLoadingSrcComponent, InputOptions, InputPlaywrightService, InputService, InstanceReadyHandler, InstanceReservedHandler, IntroSrcComponent, KalmanFilter1D, LatencyTimings, LowBandwidthDetectorComponent, LowBandwidthModalComponent, MINIMAL_FPS, MouseButton, MouseButtonsMask, OnCloseHandler, OnErrorHandler, OnMessageHandler, OnOpenHandler, OrchestrationMessageTypes, POLLING_TIME, PingHandler, PlayerCountHandler, RegionsPingService, ResetTelemetry, SAME_SIZE_THRESHOLD, SCREEN_LOCKER_CONTAINER_ID, SIGNALLING_PERCENT_VALUE, SSInfoHandler, STREAMING_VIDEO_ID, SafePipe, SignallingPlaywrightService, SignallingService, SpecialKeyCodes, StatGraphComponent, StreamStatusTelemetryPlaywrightService, StreamStatusTelemetryService, SubService, TelemetryStart, TelemetryStop, UNREAL_CONFIG, UnrealCommunicatorPlaywrightService, UnrealCommunicatorService, UnrealEffects, UnrealInternalSignalEvents, UnrealSceneComponent, UnrealStatusMessage, VideoRecorder, VideoService, VideoStatsComponent, WSCloseCode_CIRRUS_ABNORMAL_CLOSURE, WSCloseCode_CIRRUS_MAX_PLAYERS_ERROR, WSCloseCode_CIRRUS_PLAYER_DISCONNECTED, WSCloseCode_CIRRUS_STREAMER_KIKED_PLAYER, WSCloseCode_FORCE_CIRRUS_CLOSE, WSCloseCode_NORMAL_AFK_TIMEOUT, WSCloseCode_NORMAL_CLOSURE, WSCloseCode_NORMAL_MANUAL_DISCONNECT, WSCloseCode_UNKNOWN, WSCloseCodes, WS_OPEN_STATE, WS_TIMEOUT, WebRtcPlayerService, WebrtcErrorModalComponent, abortEstablishingConnection, changeLowBandwidth, changeStatusMainVideoOnScene, changeStreamResolutionAction, changeStreamResolutionSuccessAction, commandCompleted, commandStarted, dataChannelConnected, dataChannelReady, decodeData, destroyRemoteConnections, destroyUnrealScene, disconnectStream, dispatchResize, dropConnection, floatToSmoothPercents, forceResizeUnrealVideo, fromResizeObserver, fromSignal, fromUnrealCallBackSignal, getActiveUrl, getImageFromVideoStream, getRtcErrorMessage, iceConnectionFailed, initSignalling, initialState, isLoaderScreenVisible, keepMaxUntilReset, mapQpToQuality, observeCommandResponse, provideAngularUnrealModule, reconnectPeer, reconnectPeerFailed, reconnectPeerSuccess, removeExileCommands, resetAfk, resetAfkAction, resetConfig, resetDataChannelForReconnect, resetIntroSrc, resetWarnTimeout, saveAnalyticsEvent, selectClientAndViewIds, selectCommandProgress, selectCommandsInProgress, selectFreezeFrameCombinedDataUrl, selectFreezeFrameDataUrl, selectFreezeFrameDataUrlFromVideo, selectFreezeFrameProgressMessageFromVideo, selectIsAutostart, selectIsExistMatchUrls, selectIsFreezeFrameLoading, selectIsVideoPlayingAndDataChannelConnected, selectLastCommandInProgress, selectLoaderCommands, selectShowLoader, selectShowReconnectPopup, selectSignalingParameters, selectStreamConfig, selectTotalProgress, selectWarnTimeout, sendSignal, setAfkTimerHide, setAfkTimerVisible, setAwsInstance, setCirrusConnected, setCirrusDisconnected, setConfig, setDataChannelConnected, setEstablishingConnection, setFreezeFrame, setFreezeFrameFromVideo, setIntroImageSrc, setIntroVideoSrc, setLoadingImageSrc, setLoopBackCommandIsCompleted, setMaxFps, setOrchestrationContext, setOrchestrationMessage, setOrchestrationParameters, setOrchestrationProgress, setSignalingName, setStatusMessage, setStatusPercentSignallingServer, setStreamClientCompanyId, setStreamViewId, setUnrealPlaywrightConfig, setViewportNotReady, setViewportReady, showPopupWithoutAutoStart, showUnrealErrorMessage, smoothTransition, startStream, trackMixpanelEvent, unrealFeature, unrealReducer, updateCirrusInfo };
 export type { AnySignalingMessage, AwsInstance, CandidateMessage, CloseReason, CommandsLoaderState, ConfigMessage, ConnectionError, DataFlowCheckResult, DisconnectReasonType, EControlSchemeTypeValues, EMessageTypeValues, ForceClientDisconnect, FreezeFrameMessage, IAggregatedStat, InboundVideoStats, InputProps, InstanceReady, InstanceReserved, InterruptClientStream, LBMStats, ListStreamersMessage, MessageBase, NormalizeAndQuantizeSignedValue, NormalizeAndQuantizeUnsignedValue, ObservedCallbackResponse, OrchestrationErrorMessage, OrchestrationMessageType, P2PEstablishedMessage, PingMessage, PlayerCountMessage, PollingOrchestrationMessage, Quality, ReceivedFile, ReconnectConfig, RequestStream, SSInfo, SignalDescriptor, SignalingData, SignalingMessageHandler, SignalingMessageMap, StreamConfig, StreamRequestContext, StreamResolutionProps, StreamerListMessage, TelemetryType, UnknownFields, UnquantizeAndDenormalizeUnsignedValue, UnrealCallBackJson, UnrealInitialConfig, UnrealState, WSCloseCodesValues, WrappedMetaBoxCommandPacket, streamPreparedForUserInteractionMessage };