@xmaxai/sdk 0.1.0

package/dist/rtc-manager-gYDkADGw.d.ts

@@ -0,0 +1,412 @@
+type SDKLocale = 'en-US' | 'zh-CN';
+
+type SDKMessages = Record<string, string>;
+type SDKI18n = {
+    locale: SDKLocale;
+    t: (key: string, params?: Record<string, string | number | boolean | null | undefined>) => string;
+};
+declare function getDefaultMessages(locale: SDKLocale): SDKMessages;
+declare function createSDKI18n(input?: {
+    locale?: SDKLocale;
+    messages?: Record<string, string>;
+    t?: SDKI18n['t'];
+}): SDKI18n;
+
+type XmaxErrorNotifier = (message: string, error?: unknown) => void;
+
+/** Deployment region for the published package. */
+type XmaxSdkRegion = "cn" | "global";
+/** Region → official Open API v1 production base URL. */
+declare const XMAX_OPEN_API_BASE_URLS: Record<XmaxSdkRegion, string>;
+/**
+ * Official Xmax Open Platform production API base URL (Open API v1) for the
+ * region this package was built for:
+ * - `@xmaxai/sdk` (cn):        https://cloud.xmax.22duck.cn/open/api/v1
+ * - `@xmaxai/sdk-global`:      https://api.xmax.cloud/open/api/v1
+ */
+declare const XMAX_OPEN_API_PRODUCTION_BASE_URL: string;
+declare const ACTIVE_STATUS = "ACTIVE";
+interface ModelExtra {
+    room_id?: string;
+    bot_name?: string;
+    user_id?: string;
+    rtc_app_id?: string;
+    room_token?: string;
+}
+interface Session {
+    sessionUid: string;
+    userUid?: string;
+    modelTypeUid?: string;
+    modelTypeName?: string;
+    modelUid?: string;
+    modelExtra?: ModelExtra;
+    status?: string;
+    lastHeartbeatTimestamp?: string;
+    closeTimestamp?: string | null;
+    closeReason?: string | null;
+    createTimestamp?: string;
+    updateTimestamp?: string;
+}
+interface StsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+interface CosSts {
+    type: string;
+    bucket: string;
+    region: string;
+    endpoint: string;
+    prefix: string;
+    credentials: StsCredentials;
+}
+interface UploadImageResult {
+    key: string;
+    url: string;
+    raw: unknown;
+    sts: CosSts;
+}
+interface UploadVideoResult {
+    key: string;
+    url: string;
+    raw: unknown;
+    sts: CosSts;
+}
+interface RtcJoinInfo {
+    appId: string;
+    roomId: string;
+    userId: string;
+    token: string;
+    botName?: string;
+}
+interface XmaxLogEntry {
+    id: string;
+    level: "info" | "success" | "warn" | "error";
+    message: string;
+    data?: unknown;
+    timestamp: string;
+}
+interface ClientOptions {
+    apiKey: string;
+    /** Open API base URL, e.g. {@link XMAX_OPEN_API_PRODUCTION_BASE_URL}. */
+    baseUrl: string;
+    authToken?: string;
+    timeoutMs?: number;
+    locale?: SDKLocale;
+    i18n?: SDKI18n;
+    onError?: XmaxErrorNotifier;
+}
+declare class XmaxOpenClient {
+    private readonly apiKey;
+    private readonly authToken;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly i18n;
+    private readonly onError;
+    private stsCache;
+    private heartbeatIntervalId;
+    private suppressErrorNotification;
+    private teardownAbortController;
+    private readonly pendingRequestControllers;
+    constructor(options: ClientOptions);
+    private throwError;
+    /** Stop heartbeat, abort in-flight API requests, and suppress error toasts during teardown. */
+    beginTeardown(): void;
+    endTeardown(): void;
+    private isAbortError;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    createSession(model: string): Promise<Session>;
+    getSession(sessionUid: string): Promise<Session>;
+    heartbeatSession(sessionUid: string): Promise<Session>;
+    closeSession(sessionUid: string): Promise<Session | null>;
+    getCosSts(forceRefresh?: boolean): Promise<CosSts>;
+    private uploadObject;
+    uploadImage(file: File): Promise<UploadImageResult>;
+    uploadVideo(file: File): Promise<UploadVideoResult>;
+    startHeartbeat(sessionUid: string, intervalMs?: number, onHeartbeat?: (session: Session) => void, onError?: (error: unknown) => void): void;
+    stopHeartbeat(): void;
+    getRtcJoinInfo(session: Session): RtcJoinInfo;
+}
+
+/** Max viewport width treated as mobile H5 (matches app `useIsMobile`). */
+declare const MOBILE_PUBLISH_MAX_WIDTH_PX = 768;
+declare const RTC_PUBLISH_FPS_WEB = 30;
+declare const RTC_PUBLISH_FPS_MOBILE = 24;
+/** @deprecated Use {@link resolveRtcPublishFps} — web default only. */
+declare const RTC_PUBLISH_FPS = 30;
+type ResolveRtcPublishFpsOptions = {
+    /** When set, skips viewport detection. */
+    mobile?: boolean;
+    /** Explicit fps override. */
+    fps?: number;
+    /** Upload/file publish — use detail encoding and higher max bitrate. */
+    highQuality?: boolean;
+};
+declare function isMobilePublishEnvironment(): boolean;
+declare function resolveRtcPublishFps(options?: ResolveRtcPublishFpsOptions): number;
+declare function resolveRtcPublishFrameIntervalS(options?: ResolveRtcPublishFpsOptions): number;
+/** Web @ 30fps — use {@link resolveRtcPublishFrameIntervalS} when mobile-aware. */
+declare const RTC_PUBLISH_FRAME_INTERVAL_S: number;
+declare const RTC_PUBLISH_FRAME_INTERVAL_MS: number;
+/** Tolerance when comparing media-time deltas (seconds). */
+declare const MEDIA_TIME_EPSILON_S = 0.001;
+/** Media time jumped backward beyond this threshold — treat as loop/seek reset. */
+declare const MEDIA_TIME_LOOP_JUMP_S = 0.05;
+
+interface RtcLogEntry {
+    level: "info" | "success" | "warn" | "error";
+    message: string;
+    data?: unknown;
+}
+interface RtcStateSnapshot {
+    roomId: string | null;
+    userId: string | null;
+    appId: string | null;
+    botUserId: string | null;
+    joined: boolean;
+    localVideoPublished: boolean;
+    remoteVideoUserId: string | null;
+    users: string[];
+}
+type RemoteSeiReceivedPayload = {
+    sei: string;
+    userId: string;
+};
+interface RtcManagerOptions {
+    onLog?: (entry: RtcLogEntry) => void;
+    onStateChange?: (state: RtcStateSnapshot) => void;
+    onSeiGateChange?: (state: {
+        expectedSei: string | null;
+        sei: string | null;
+        userId: string | null;
+        matched: boolean;
+    }) => void;
+    /** Fired for H.264 SEI received on a remote (non-local) stream — e.g. backend/bot output. */
+    onRemoteSeiReceived?: (payload: RemoteSeiReceivedPayload) => void;
+    /** Fired when remote output stops presenting new frames after playback had started. */
+    onRemoteOutputStalled?: (info: {
+        userId: string;
+        stallMs: number;
+    }) => void;
+    /** Fired after the remote player is mounted (used to forward MediaStream via onRemoteStream). */
+    onRemotePlayerMounted?: () => void;
+    debug?: boolean;
+    i18n?: SDKI18n;
+}
+type VideoSize = [number, number];
+type RtcSessionSeiOptions = {
+    repeatCount?: number;
+    intervalMs?: number;
+};
+/** Cold publish: bootstrap already waits 3 frames — buffer before first start only. */
+declare const PUBLISH_START_MIN_FRAMES = 5;
+declare const PUBLISH_START_FRAME_TIMEOUT_MS = 800;
+declare const PUBLISH_COLD_MIN_FRAMES = 12;
+declare const PUBLISH_COLD_FRAME_TIMEOUT_MS = 1500;
+/** Minimum publish duration before first start (encoder/network warmup). */
+declare const PUBLISH_COLD_WARMUP_MS = 600;
+/** Skip cold-start ensure when publish has been active this long. */
+declare const PUBLISH_WARM_SKIP_MS = 800;
+type LocalPublishReadyResult = {
+    ready: boolean;
+    reason: "sent-frame-rate" | "sent-bitrate" | "already-ready" | "not-published" | "timeout";
+    elapsedSincePublishMs: number;
+};
+declare class RtcManager {
+    private engine;
+    private leaveTask;
+    private readonly users;
+    private currentJoinInfo;
+    private joined;
+    private preserveRemoteDom;
+    private localVideoPublished;
+    private localVideoSourceType;
+    private shouldMirrorLocalPreview;
+    private externalVideoTrack;
+    private remoteVideoUserId;
+    private pendingRemoteVideoUserId;
+    private pendingRemoteVideoMediaType;
+    /** Subscribed to RTC media, but player may still be gated by SEI / container. */
+    private subscribedRemoteUserId;
+    private subscribedRemoteMediaType;
+    private readonly onLog;
+    private readonly onStateChange;
+    private readonly onSeiGateChange;
+    private readonly onRemoteSeiReceived;
+    private readonly onRemoteOutputStalled;
+    private onRemotePlayerMounted;
+    private localVideoContainer;
+    private remoteVideoContainer;
+    private expectedRemoteSei;
+    private lastRemoteSei;
+    private lastRemoteSeiUserId;
+    private localSeiMessage;
+    private localSeiRepeatCount;
+    private seiSendInterval;
+    private lastSeiSentAtMs;
+    private hasLoggedSeiSendFailure;
+    private seiSupport;
+    private hasLoggedSeiUnsupported;
+    private readonly debug;
+    private lastDebugSeiMatched;
+    private lastDebugRemoteSei;
+    private remoteFrameWatchStop;
+    private uploadPreviewLayoutObserverStop;
+    private remoteOutputRecoveryCooldownUntil;
+    private readonly i18n;
+    private joinedAtMs;
+    private publishStartedAtMs;
+    private lastRoomStartEventAtMs;
+    private localStreamStatsCount;
+    private firstNonZeroSentFrameRateAtMs;
+    private lastObservedSentFrameRate;
+    private publishReadyWaiters;
+    private stablePublishWaiters;
+    private publishReadyBufferTimer;
+    private seiGateFallbackTimer;
+    private seiMatchedDelayTimer;
+    private lastSentResolution;
+    private lastReceivedResolution;
+    private static readonly SEI_GATE_FALLBACK_MS;
+    private static readonly SEI_MATCHED_DISPLAY_DELAY_MS;
+    constructor(options?: RtcManagerOptions);
+    private emitSeiGateState;
+    setPreserveRemoteDom(preserve: boolean): void;
+    setOnRemotePlayerMounted(callback: RtcManagerOptions["onRemotePlayerMounted"]): void;
+    setLocalVideoContainer(container: HTMLElement | null): void;
+    setRemoteVideoContainer(container: HTMLElement | null): void;
+    /** Display-only gate: expect bot output SEI to match task id — no local SEI send, no start blocking. */
+    configureSessionSei(sessionId: string | null, _options?: RtcSessionSeiOptions): void;
+    private clearSeiGateFallbackTimer;
+    private clearSeiMatchedDelayTimer;
+    /** Show output if bot SEI never arrives — UI gate only, RTC bind is not blocked. */
+    private scheduleSeiGateFallback;
+    get snapshot(): RtcStateSnapshot;
+    getLocalVideoSize(): {
+        width: number;
+        height: number;
+    } | null;
+    join(joinInfo: RtcJoinInfo): Promise<void>;
+    startVideoPublishing(size?: VideoSize): Promise<void>;
+    startExternalVideoPublishing(track: MediaStreamTrack, encoderSize?: VideoSize, publishOptions?: ResolveRtcPublishFpsOptions): Promise<void>;
+    stopVideoPublishing(options?: {
+        preserveExternalTrack?: boolean;
+    }): Promise<void>;
+    leave(): Promise<void>;
+    /**
+     * Resolve whether to wait for input frames before start.
+     * Warm pipelines (restart / long-lived publish) skip — iOS sends start while frames already flow.
+     */
+    resolveInputFrameWaitOptions(): {
+        minFrames: number;
+        timeoutMs: number;
+        minPublishMs: number;
+    } | null;
+    /**
+     * Wait until the published input track produces enough frames before sending start.
+     * Uses actual frame delivery instead of sentFrameRate (~2s Volcengine stats window).
+     */
+    waitForPublishedInputFrames(options?: {
+        minFrames?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        ready: boolean;
+        frameCount: number;
+        elapsedMs: number;
+    }>;
+    /**
+     * Before every start: ensure the publish track is producing frames.
+     * Cold — longer warmup; warm restart — quick sync (~200ms) so backend gets steady input after start.
+     */
+    ensurePublishedInputBeforeStart(): Promise<void>;
+    /** @deprecated Use {@link ensurePublishedInputBeforeStart}. */
+    waitForRtcOutboundBeforeStart(options?: {
+        timeoutMs?: number;
+    }): Promise<LocalPublishReadyResult>;
+    /** @deprecated Use {@link waitForRtcOutboundBeforeStart}. */
+    waitForPublishedInputFramesBeforeStart(): Promise<{
+        ready: boolean;
+        frameCount: number;
+        elapsedMs: number;
+        rtcSendReady: boolean;
+        rtcSendReason?: LocalPublishReadyResult["reason"];
+        rtcSendElapsedMs?: number;
+    }>;
+    private waitForMinPublishDuration;
+    /**
+     * Subscribe to the bot output stream before start — iOS bindRemoteVideoRenderer runs pre-request.
+     */
+    prepareRemoteVideoForGeneration(): Promise<void>;
+    /**
+     * Wait until outbound sentFrameRate reaches minFps and stays there for stableMs.
+     * Avoids starting while Volcengine encoder is still ramping (causes early dropped frames).
+     */
+    waitForStableLocalPublishReady(options?: {
+        minFps?: number;
+        timeoutMs?: number;
+        stableMs?: number;
+    }): Promise<LocalPublishReadyResult>;
+    /**
+     * Wait until Volcengine reports non-zero sentFrameRate (~2s stats window).
+     * Prefer this over local track frame counts before start — backend only processes from start.
+     */
+    waitForLocalPublishReady(options?: {
+        timeoutMs?: number;
+    }): Promise<LocalPublishReadyResult>;
+    sendRoomEvent(event: unknown): Promise<void>;
+    clearRemoteVideo(options?: {
+        preserveDom?: boolean;
+    }): void;
+    refreshRemoteVideoBinding(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    private bindEngineEvents;
+    private emitState;
+    private ensureReadyForMessaging;
+    private bindLocalVideoPlayer;
+    private bindUploadPreviewLayout;
+    private clearUploadPreviewLayoutObserver;
+    /** Re-bind local preview after the container becomes visible or is resized (mobile H5). */
+    refreshLocalVideoPreview(options?: {
+        force?: boolean;
+    }): void;
+    private switchToExternalVideoSource;
+    private switchToInternalVideoSource;
+    private applyLocalVideoCaptureConfig;
+    private resolveEncoderMaxKbps;
+    private applyVideoEncoderPreference;
+    private attachRemoteVideo;
+    private ensureRemoteStreamSubscribed;
+    private bindRemoteVideoPlayerToContainer;
+    private mountRemoteVideoPlayer;
+    private startRemoteFrameWatch;
+    private stopRemoteFrameWatch;
+    private isRemoteSeiUser;
+    /** Always mount remote player — SEI gate is UI-only (see deriveOutputVisibility). */
+    private canRenderRemoteVideo;
+    /** Whether remote SEI matches the active task (display gate). */
+    private isSeiMatched;
+    /** Low-rate SEI until remote output SEI matches — avoids Volcengine sendSEIMessage timeouts. */
+    private startContinuousSeiSending;
+    private stopSeiSending;
+    private canSendLocalSeiNow;
+    private flushSeiMessage;
+    private ensureSeiSupport;
+    private normalizeSei;
+    private normalizeSeiRepeatCount;
+    private decodeSeiMessage;
+    private supportsVideo;
+    private clearVideoContainers;
+    private clearContainer;
+    private getRequiredContainer;
+    private emitRemotePlayerMounted;
+    private log;
+    private resolvePublishReadyWaiters;
+    private clearPublishReadyWaiters;
+    private notifyStablePublishWaiters;
+    private schedulePublishReadyWhenStable;
+    private logLocalStreamStats;
+    private debugLog;
+}
+
+export { ACTIVE_STATUS as A, XMAX_OPEN_API_PRODUCTION_BASE_URL as B, type ClientOptions as C, type XmaxLogEntry as D, type XmaxSdkRegion as E, createSDKI18n as F, getDefaultMessages as G, isMobilePublishEnvironment as H, resolveRtcPublishFps as I, resolveRtcPublishFrameIntervalS as J, type LocalPublishReadyResult as L, MEDIA_TIME_EPSILON_S as M, PUBLISH_COLD_FRAME_TIMEOUT_MS as P, type RtcStateSnapshot as R, type SDKLocale as S, type UploadImageResult as U, type XmaxErrorNotifier as X, type SDKI18n as a, XmaxOpenClient as b, type CosSts as c, MEDIA_TIME_LOOP_JUMP_S as d, MOBILE_PUBLISH_MAX_WIDTH_PX as e, type ModelExtra as f, PUBLISH_COLD_MIN_FRAMES as g, PUBLISH_COLD_WARMUP_MS as h, PUBLISH_START_FRAME_TIMEOUT_MS as i, PUBLISH_START_MIN_FRAMES as j, PUBLISH_WARM_SKIP_MS as k, RTC_PUBLISH_FPS as l, RTC_PUBLISH_FPS_MOBILE as m, RTC_PUBLISH_FPS_WEB as n, RTC_PUBLISH_FRAME_INTERVAL_MS as o, RTC_PUBLISH_FRAME_INTERVAL_S as p, type RemoteSeiReceivedPayload as q, type ResolveRtcPublishFpsOptions as r, type RtcJoinInfo as s, type RtcLogEntry as t, RtcManager as u, type SDKMessages as v, type Session as w, type StsCredentials as x, type UploadVideoResult as y, XMAX_OPEN_API_BASE_URLS as z };

package/dist/video-file-stream-UXJ6TNIB.js

@@ -0,0 +1,4 @@
+export { createVideoFileStream } from './chunk-EGNRAZ5U.js';
+import './chunk-PLU2YVAS.js';
+//# sourceMappingURL=video-file-stream-UXJ6TNIB.js.map
+//# sourceMappingURL=video-file-stream-UXJ6TNIB.js.map

package/dist/video-file-stream-UXJ6TNIB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"video-file-stream-UXJ6TNIB.js"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@xmaxai/sdk",
+  "version": "0.1.0",
+  "description": "Browser SDK for Xmax Open Platform — HTTP session, Volcengine RTC, and React bindings.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Xmax",
+  "keywords": [
+    "Xmax",
+    "rtc",
+    "realtime",
+    "video",
+    "ai",
+    "sdk"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./experimental": {
+      "types": "./dist/experimental/index.d.ts",
+      "import": "./dist/experimental/index.js",
+      "require": "./dist/experimental/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:cn": "XMAX_SDK_REGION=cn tsup",
+    "build:global": "XMAX_SDK_REGION=global tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test",
+    "publish:cn": "node scripts/publish-sdk.mjs cn",
+    "publish:global": "node scripts/publish-sdk.mjs global",
+    "publish:all": "npm run publish:cn && npm run publish:global"
+  },
+  "peerDependencies": {
+    "react": "^18",
+    "react-dom": "^18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@volcengine/rtc": "^4.68.5",
+    "cos-js-sdk-v5": "^1.10.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.4"
+  }
+}