@arcware-cloud/pixelstreaming-websdk 1.3.39 → 1.4.4

package/types/{lib → core}/ArcwareConfig.d.ts

@@ -1,12 +1,14 @@
 import { Config, ConfigParams } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
 import { Session } from "./domain/Session";
 import { Settings } from "./domain/ArcwareSettingsSchema";
-import { WhiteLabel } from "./features/ZWhiteLabel";
+import { WhiteLabel } from "./features/IWhiteLabel";
 import { EventHandler } from "./domain/EventHandler";
+import { Customization } from "./domain/CustomizationSchema";
 /** Default arcware signalling endpoint. */
 export declare const DefaultUrl: "wss://signalling-client.ragnarok.arcware.cloud";
 export interface ArcwareConfigParams extends ConfigParams {
-    settings: Settings;
+    settings?: Partial<Settings>;
+    customization?: Partial<Customization>;
     envName?: string;
 }
 export declare class ArcwareConfig extends Config {
@@ -28,13 +30,17 @@ export declare class ArcwareConfig extends Config {
     static PickIdsOfUrl(): Pick<Settings, "shareId" | "projectId">;
     readonly session: Session;
     readonly settings: Settings;
+    readonly customization: Customization;
     private _initialSettings;
-    readonly VERSION = "1.3.39";
+    readonly VERSION = "1.4.4";
     readonly whiteLabellingChanged: EventHandler<{
-        next: WhiteLabel;
+        next: Partial<WhiteLabel>;
         changed: boolean;
     }>;
     private signallingWlURL;
+    private static readonly DEFAULT_INITIAL_SETTINGS;
+    private static readonly DEFAULT_SETTINGS;
+    private static readonly DEFAULT_CUSTOMIZATION;
     constructor(config: ArcwareConfigParams);
     getWhiteLabelling(ShareId: string): Promise<WhiteLabel | undefined>;
     /** Setup connection string. */

package/types/core/ArcwarePixelStreaming.d.ts

@@ -0,0 +1,268 @@
+import { PixelStreaming, PixelStreamingOverrides } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
+import { FileTemplate } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5/dist/types/Util/FileUtil";
+import { ArcwareConfig } from "./ArcwareConfig";
+import * as Messages from "./Messages";
+import { EventHandler } from "./domain/EventHandler";
+import { Session } from "./domain/Session";
+import { AnalyticsEvent } from "./features/ArcwareEventUtil";
+import { WhiteLabel } from "./features/IWhiteLabel";
+type OutboundByKey<K extends keyof typeof Messages.Send> = {
+    type: K;
+} & Record<string, unknown>;
+export declare enum WebsocketState {
+    CONNECTING = 0,
+    OPEN = 1,
+    CLOSING = 2,
+    CLOSED = 3
+}
+/**
+ * Core streaming class extending Epic's PixelStreaming.
+ *
+ * Adds:
+ * - Identity-aware lifecycle handling
+ * - Analytics proxying
+ * - File transfer support
+ * - White-label branding hooks
+ * - Extended event system
+ */
+export declare class ArcwarePixelStreaming extends PixelStreaming {
+    /**
+     * * * * * * *
+     *  PROPERTIES / GETTERS / SETTERS
+     * * * * * * *
+     */
+    /** Core identity & state (Properties, Getters, Setters) */
+    private outbox;
+    private videoInitializedSent;
+    private _postInitSideEffectsDone;
+    config: ArcwareConfig;
+    streamInfo?: Messages.StreamInfo;
+    get session(): Session;
+    /** WebSocket / transport lifecycle (Properties, Getters, Setters) */
+    private _boundTransport?;
+    private _onWsOpen?;
+    private _onWsClose?;
+    private _transportWatchTimer?;
+    private get isWsOpen();
+    get websocketState(): WebsocketState;
+    /** Signaling & messaging (Properties, Getters, Setters) */
+    /** Event emitters (core signals) (Properties, Getters, Setters) */
+    /**
+     * Emits queue status updates from the backend.
+     *
+     * Triggered when the user enters or progresses in a streaming queue.
+     * The payload contains queue position and related metadata.
+     */
+    readonly queueHandler: EventHandler<Messages.Queue>;
+    /**
+     * Emits errors received from the signalling server or backend.
+     *
+     * This includes:
+     * - Stream termination errors
+     * - Backend rejection errors
+     * - Custom Unreal error messages
+     *
+     * Non-retryable errors may stop automatic reconnection.
+     */
+    readonly errorHandler: EventHandler<Messages.ErrorMessage>;
+    /**
+     * Emits informational messages ("Love Letters") sent from Unreal Engine.
+     *
+     * These are typically used to display user-facing messages
+     * such as loading hints or system notifications.
+     */
+    readonly loveLetterHandler: EventHandler<Messages.LoveLetter>;
+    /**
+     * Emits when a session ID is assigned by the backend.
+     *
+     * The session ID is used for reconnection and tracking.
+     */
+    readonly sessionIdHandler: EventHandler<string>;
+    /**
+     * Emits once when the first video frame is successfully rendered.
+     *
+     * This guarantees that:
+     * - WebRTC connection is active
+     * - Video dimensions are available
+     * - Stream is visually ready
+     */
+    readonly videoInitializedHandler: EventHandler<never>;
+    /**
+     * Emits when the underlying WebSocket connection closes.
+     *
+     * Provides the native CloseEvent from the browser.
+     */
+    readonly websocketOnCloseHandler: EventHandler<CloseEvent>;
+    /**
+     * Emits when white-labelling configuration changes.
+     *
+     * This can occur:
+     * - After fetching remote branding settings
+     * - When settings are modified at runtime
+     *
+     * `next` contains the updated branding values.
+     * `changed` indicates whether values were actually modified.
+     */
+    readonly whiteLabellingChangedHandler: EventHandler<{
+        next: Partial<WhiteLabel>;
+        changed: boolean;
+    }>;
+    /**
+     * Emits after initial stream side-effects have been applied.
+     *
+     * This occurs after:
+     * - First frame detection
+     * - Resolution synchronization
+     * - Mouse lock adjustments
+     *
+     * Useful for UI adjustments that depend on a fully initialized stream.
+     */
+    readonly postInitSideEffectsHandler: EventHandler<never>;
+    /**
+     * Emits when microphone usage is toggled.
+     *
+     * The event is triggered when `toggleMic()` is called.
+     */
+    readonly micToggleHandler: EventHandler<{
+        enabled: boolean;
+    }>;
+    /**
+     * Emits whenever an analytics event is dispatched
+     * (either from Unreal Engine or via `sendAnalyticsEvent`).
+     */
+    readonly analyticsEventHandler: EventHandler<AnalyticsEvent>;
+    /**
+     * Emits when Unreal Engine signals a file transfer.
+     *
+     * The actual file data can be retrieved via `getIncomingFile()`.
+     * If using ArcwareApplication, downloads are handled automatically.
+     */
+    readonly fileTransferHandler: EventHandler<{
+        filename?: string;
+    }>;
+    /**
+     * Emits raw Unreal Engine responses that are not handled internally
+     * (e.g. analytics events and file transfers).
+     *
+     * Use this to receive custom responses from your UE application.
+     */
+    readonly applicationResponseHandler: EventHandler<string>;
+    /** First-frame / stream readiness detection (Properties, Getters, Setters) */
+    private _rVFCsupported;
+    private _rvfcHandle?;
+    private _rVFCArmedForElement?;
+    private _mo?;
+    /** Resolution & stream behavior (Properties, Getters, Setters) */
+    /** Diagnostics & stats (Properties, Getters, Setters) */
+    private diagnosticsCollector;
+    /** Core utility (Properties, Getters, Setters) */
+    /**
+     * * * * * * *
+     *  CONSTRUCTOR
+     * * * * * * *
+     */
+    constructor(config: ArcwareConfig, overrides?: PixelStreamingOverrides);
+    /**
+     * * * * * * *
+     *  METHODS
+     * * * * * * *
+     */
+    /** WebSocket / transport lifecycle (Methods) */
+    private bindTransportEvents;
+    private startTransportWatcher;
+    private stopTransportWatcher;
+    private isRetryableClose;
+    reconnect(): void;
+    removePlayer(): void;
+    private onVersion;
+    /** Signaling & messaging (Methods) */
+    private addMessageHandler;
+    private _dispatchOrBuffer;
+    private flushOutbox;
+    private sendStats;
+    private onPing;
+    private onStreamInfo;
+    private onRender;
+    private onQueue;
+    private onError;
+    private onSessionId;
+    private onLoveLetter;
+    send<K extends keyof typeof Messages.Send>(message: OutboundByKey<K>): void;
+    send(type: string, payload?: Record<string, unknown>): void;
+    send(message: {
+        type: string;
+    } & Record<string, unknown>): void;
+    private handleUEResponse;
+    /**
+     * Sends an analytics event to the backend.
+     *
+     * This method can be used to emit analytics events from the frontend.
+     * Events coming from Unreal Engine are automatically proxied.
+     *
+     * The payload will be validated and truncated to the maximum allowed size.
+     *
+     * @param event - The analytics event object.
+     *
+     * @example
+     * stream.sendAnalyticsEvent({
+     *   type: "event",
+     *   customName: "button_clicked",
+     *   payload: JSON.stringify({ id: 42 })
+     * });
+     */
+    sendAnalyticsEvent(event: AnalyticsEvent): void;
+    private handleAnalyticsFromUnreal;
+    private _dispatchAnalytics;
+    /**
+     * Returns the most recently received file from Unreal Engine.
+     *
+     * This is populated when a file transfer message is received.
+     * Use together with `fileTransferHandler`.
+     *
+     * @returns The raw file object or undefined if no file is available.
+     */
+    getIncomingFile(): FileTemplate;
+    /**
+     * Triggers a browser download for the most recently received file.
+     *
+     * If no file is available, the method does nothing.
+     *
+     * @param filename - Optional custom filename (without extension).
+     */
+    fileDownload(filename?: string): void;
+    /** First-frame / stream readiness detection (Methods) */
+    private attachFirstRenderedFrameOnce;
+    private cancelFirstRenderedFrameHook;
+    private watchVideoElementReplacement;
+    private waitForFirstFrameWithTimeout;
+    private isVideoRenderingNow;
+    private sendVideoInitializedOnce;
+    private onVideoInitialized;
+    /** Resolution & stream behavior (Methods) */
+    private handleResolutionChange;
+    private handleMouseLock;
+    setAudioEnabled(enabled: boolean): void;
+    /** Diagnostics & stats (Methods) */
+    /** Core utility (Methods) */
+    private resetInitGuardsAndHooks;
+    static clearSessionId(): void;
+    private runPostInitSideEffectsOnce;
+    toggleAudio(videoElement: HTMLVideoElement, enabled: boolean): void;
+    /**
+     * Enables or disables microphone usage.
+     *
+     * When changed manually (isDefault = false), the stream reconnects
+     * to apply the new microphone configuration.
+     */
+    toggleMic(enable: boolean, isDefault: boolean): void;
+    /**
+     * Registers a callback that is invoked when streaming state changes.
+     *
+     * The callback is triggered on:
+     * - Video play
+     * - Video pause
+     * - Stream transport open/close
+     */
+    onStreamingStateChange(callback: (isStreaming: boolean) => void): void;
+}
+export {};

package/types/core/CoreSetup.d.ts

@@ -0,0 +1,10 @@
+import { PixelStreamingOverrides } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
+import { ArcwareConfig } from "./ArcwareConfig";
+import { ArcwarePixelStreaming } from "./ArcwarePixelStreaming";
+export declare function CoreSetup(config: ArcwareConfig, overrides?: PixelStreamingOverrides, options?: {
+    forceRefresh?: boolean;
+    allowMultipleInstances?: boolean;
+}): {
+    PixelStreaming: ArcwarePixelStreaming;
+    Config: ArcwareConfig;
+};

package/types/core/Messages/ErrorMessage.d.ts

@@ -0,0 +1,11 @@
+export interface ErrorMessage {
+    type: "error";
+    code: number;
+    reason: string;
+    verbosity: number;
+}
+/**
+ * Parse and validate an ErrorMessage payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseErrorMessage(input: unknown): ErrorMessage;

package/types/core/Messages/LoveLetter.d.ts

@@ -0,0 +1,11 @@
+export interface LoveLetter {
+    type: "letter";
+    reason: string;
+    code: number;
+    verbosity: number;
+}
+/**
+ * Parse and validate a LoveLetter payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseLoveLetter(input: unknown): LoveLetter;

package/types/core/Messages/Ping.d.ts

@@ -0,0 +1,10 @@
+export interface Ping {
+    type: "ping";
+    message?: string;
+    time: number;
+}
+/**
+ * Parse and validate a Ping payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parsePing(input: unknown): Ping;

package/types/core/Messages/Queue.d.ts

@@ -0,0 +1,23 @@
+export type QueueValueType = "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+export interface Queue {
+    type: "queue";
+    queue: {
+        /** Position in queue (zero based). */
+        index?: number;
+        /** Length of the queue. */
+        queueLength?: number;
+        /** Already waited for. */
+        waited?: number;
+        /** Estimated wait time. */
+        estimatedWaitTime?: number | null;
+        /** Average wait time. */
+        averageWaitTime?: number | null;
+        /** Type of all time-values in the queue. */
+        valueType: QueueValueType;
+    };
+}
+/**
+ * Parse and validate a Queue payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseQueue(input: unknown): Queue;

package/types/core/Messages/Render.d.ts

@@ -0,0 +1,8 @@
+export interface Render {
+    type: "render";
+}
+/**
+ * Parse and validate a Render payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseRender(input: unknown): Render;

package/types/core/Messages/SessionId.d.ts

@@ -0,0 +1,9 @@
+export interface SessionId {
+    type: "sessionId";
+    sessionId: string;
+}
+/**
+ * Parse and validate a SessionId payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseSessionId(input: unknown): SessionId;

package/types/core/Messages/Stats.d.ts

@@ -0,0 +1,34 @@
+import { AggregatedStats } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
+export interface Stats {
+    type: "stats";
+    stats?: {
+        codecs?: AggregatedStats["codecs"];
+        candidatePair?: AggregatedStats["candidatePairs"];
+        localCandidates?: AggregatedStats["localCandidates"];
+        remoteCandidates?: AggregatedStats["remoteCandidates"];
+        DataChannelStats?: AggregatedStats["datachannelStats"];
+        bytesReceived?: number;
+        packetsLost?: number;
+        frameWidth?: number;
+        frameHeight?: number;
+        framesDecoded?: number;
+        framesPerSecond?: number;
+        framesDropped?: number;
+        videoCodec?: string;
+        audioCodec?: string;
+        browserInfo?: {
+            userAgent?: string;
+            platform?: string | null;
+            language?: string;
+            [key: string]: unknown;
+        };
+        currentRTT?: number;
+        sessionRunTime?: string;
+        controlsStreamInput?: "true" | "false";
+        videoEncoderAvgQP?: number;
+        videoBitrate?: number;
+        audioBitrate?: number;
+        [key: string]: unknown;
+    };
+}
+export declare function parseStats(input: unknown): Stats;

package/types/core/Messages/StreamInfo.d.ts

@@ -0,0 +1,30 @@
+import { WebSdkSettingsType } from "./WebSdkSettings";
+export interface StreamInfo {
+    type: "streamInfo";
+    streamInfo: {
+        guid: string;
+        autoPlay?: boolean;
+        touchCapable?: boolean;
+        resolution?: {
+            width: number;
+            height: number;
+            dynamic?: boolean;
+            fixed?: boolean;
+        };
+        meta?: {
+            friendlyName?: string;
+            isTrial?: boolean;
+            mouseLock?: boolean;
+            poweredBy?: boolean;
+            version?: string;
+        };
+        webSdkSettings?: WebSdkSettingsType;
+        afk?: {
+            enabled: boolean;
+            warn: number;
+            error: number;
+            action: number;
+        };
+    };
+}
+export declare function parseStreamInfo(input: unknown): StreamInfo;

package/types/core/Messages/Version.d.ts

@@ -0,0 +1,9 @@
+export interface Version {
+    type: "version";
+    version?: string;
+}
+/**
+ * Parse and validate a Version payload.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseVersion(input: unknown): Version;

package/types/core/Messages/WebSdkSettings.d.ts

@@ -0,0 +1,31 @@
+export interface WebSdkSettingsType {
+    conf?: {
+        fullscreenButton?: boolean;
+        stopButton?: boolean;
+        audioButton?: boolean;
+        infoButton?: boolean;
+        micButton?: boolean;
+        settingsButton?: boolean;
+        connectionStrengthIcon?: boolean;
+    };
+    init?: {
+        KeyboardInput?: boolean;
+        MouseInput?: boolean;
+        GamepadInput?: boolean;
+        TouchInput?: boolean;
+        XRControllerInput?: boolean;
+        FakeMouseWithTouches?: boolean;
+        ForceMonoAudio?: boolean;
+        HoveringMouse?: boolean;
+    };
+    customization?: {
+        buttons_position?: "Bottom-Right" | "Bottom-Left" | "Top-Left" | "Top-Right";
+        buttons_orientation?: "Vertical" | "Horizontal";
+        buttons_reverse?: boolean;
+    };
+}
+/**
+ * Parse and validate WebSdkSettings.
+ * Throws on invalid input (mirrors previous Zod.parse behavior).
+ */
+export declare function parseWebSdkSettings(input: unknown): WebSdkSettingsType;

package/types/core/Messages/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./ErrorMessage";
+export * from "./LoveLetter";
+export * from "./SessionId";
+export * from "./StreamInfo";
+export * from "./Stats";
+export * from "./Ping";
+export * from "./Queue";
+export * from "./Version";
+export * from "./WebSdkSettings";
+export * from "./Render";
+import { parseStats } from "./Stats";
+export declare const Send: {
+    readonly stats: {
+        readonly parse: typeof parseStats;
+    };
+};
+export type SendType = keyof typeof Send | "onVideoInitialized";

package/types/core/domain/ArcwareSettingsSchema.d.ts

@@ -0,0 +1,61 @@
+import * as Messages from "../Messages";
+import { WhiteLabel } from "../features/IWhiteLabel";
+/** Orientation zoom configuration */
+export interface OrientationZoom {
+    landscape: number;
+    portrait: number;
+}
+/** Arcware Settings. */
+export interface Settings {
+    /** Overwrites the Session-Tool and uses the provided session instead. */
+    session?: string;
+    /** Can be used to be added to the request in order to verify access to private projects.
+     * For internal use only. => Preview page.
+     */
+    token?: string;
+    /** @deprecated in there for legacy use. Can only be used when token is provided. */
+    bypass?: boolean;
+    /** Handler for server side error messages. */
+    errorHandler?: (msg: Messages.ErrorMessage) => void;
+    /** Handler for queue events. */
+    queueHandler?: (msg: Messages.Queue) => void;
+    /** Handler for sessionId message. */
+    sessionIdHandler?: (sessionId: string) => void;
+    /** Handler for love letters.
+     * "LoveLetters" are send from backend to the SDK to state what phase the connection currently is in.
+     */
+    loveLetterHandler?: (msg: Messages.LoveLetter) => void;
+    /** Show or hide the fullscreen button. */
+    fullscreenButton?: boolean;
+    /** Show or hide the settings button. */
+    settingsButton?: boolean;
+    /** Show or hide the info button. */
+    infoButton?: boolean;
+    /** Show or hide the audio button. */
+    audioButton?: boolean;
+    /** Show or hide the microphone button. */
+    micButton?: boolean;
+    /** Show or hide the stop button. */
+    stopButton?: boolean;
+    /** Show or hide the connectionStrengthIcon button. */
+    connectionStrengthIcon?: boolean;
+    /** ShareId, used for sharing your project.
+     * Using ArcwareInit will set this required property for you.
+     */
+    shareId?: string;
+    /** Id of your project, only required if your shareId refers to multiple projects.
+     * Using ArcwareInit will set this required property for you.
+     */
+    projectId?: string;
+    /** Enable/Disable LoveLetter logging to the console. */
+    loveLetterLogging?: boolean;
+    /** Width with which instance should be started */
+    startWidth?: number;
+    /** Height with which instance should be started */
+    startHeight?: number;
+    /** Zoom functionality */
+    orientationZoom?: OrientationZoom;
+    /** Loader customization */
+    whiteLabelling?: WhiteLabel;
+    fetchRemoteWhiteLabelling?: boolean;
+}

package/types/core/domain/CustomizationSchema.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const ZCustomizationSchema: z.ZodOptional<z.ZodObject<{
+    buttons_position: z.ZodOptional<z.ZodEnum<["Bottom-Right", "Bottom-Left", "Top-Left", "Top-Right"]>>;
+    buttons_orientation: z.ZodOptional<z.ZodEnum<["Vertical", "Horizontal"]>>;
+    buttons_reverse: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    buttons_position?: "Bottom-Right" | "Bottom-Left" | "Top-Left" | "Top-Right";
+    buttons_orientation?: "Vertical" | "Horizontal";
+    buttons_reverse?: boolean;
+}, {
+    buttons_position?: "Bottom-Right" | "Bottom-Left" | "Top-Left" | "Top-Right";
+    buttons_orientation?: "Vertical" | "Horizontal";
+    buttons_reverse?: boolean;
+}>>;
+export type Customization = z.infer<typeof ZCustomizationSchema>;

package/types/core/domain/Session.d.ts

@@ -0,0 +1,31 @@
+interface Options {
+    localStorageKey: string;
+    /** seconds */
+    keepSession: number;
+}
+/**
+ * The sessionId is stored in the localStorage to allow for reconnection and
+ * to prevent spamming start requests of instances, when smashing F5.
+ */
+export declare class Session {
+    private _current?;
+    get current(): string;
+    get noSession(): boolean;
+    get id(): string | null;
+    private options;
+    private get localStorageKey();
+    constructor(options?: Partial<Options>);
+    /** Set's the session with creation date for the given storage key to the localStorage. */
+    set(sessionId: string): void;
+    /** Removes a session from the localStorage. */
+    unset(): void;
+    /**
+     * Try reading the session from localStorage; if blocked (3rd-party / privacy) fall back to sessionStorage.
+     */
+    private readSessionString;
+    /**
+     * Persist session id with graceful fallback when localStorage is blocked.
+     */
+    private writeSessionString;
+}
+export {};

package/types/core/domain/Stats.d.ts

@@ -0,0 +1,7 @@
+import * as Messages from "../Messages";
+import { AggregatedStats } from "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5";
+/**
+ * Build a Stats message payload from AggregatedStats.
+ * Keeps the same public API as before: Stats(stats)
+ */
+export declare function Stats(stats: AggregatedStats): Messages.Stats["stats"];

package/types/core/features/ArcwareFileTransferUtil.d.ts

@@ -0,0 +1,8 @@
+export interface FileTransferMsg {
+    type: "fileTransfer";
+    filename?: string;
+}
+/**
+ * Normalized parse + validate for fileTransfer control messages
+ */
+export declare function parseFileTransfer(input: unknown): FileTransferMsg;

package/types/{lib → core}/features/DiagnosticsCollector.d.ts

@@ -13,7 +13,7 @@
  */
 /**
  * These interfaces need to be copied manually from ITicket.ts for now if the interface changes there
- * The way how webpack, rollup and this whole mono repo is setup up, I cannot just import it......
+ * The way how webpack and this whole mono repo is setup up, I cannot just import it......
  */
 export interface IDiagnostics {
     device?: Device;