@newgameplusinc/alpha-spatial-comms 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,342 @@
+/**
+ * Position and Direction Types
+ *
+ * Coordinate system conventions:
+ * - Unreal Engine: X=forward, Y=right, Z=up (centimeters)
+ * - Standard/WebAudio: X=right, Y=up, Z=forward (meters)
+ */
+/**
+ * 3D position in space
+ */
+interface Position {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * 3D direction vector (normalized)
+ */
+interface Direction {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/**
+ * Spatial Audio Types
+ *
+ * Type definitions for spatial audio processing
+ */
+/**
+ * Spatial audio distance configuration
+ *
+ * DISTANCE-BASED GAIN SPECIFICATION (CUBIC FALLOFF):
+ * ┌──────────────┬─────────┬────────────────────────────────┐
+ * │ Distance     │ Gain %  │ Description                    │
+ * ├──────────────┼─────────┼────────────────────────────────┤
+ * │ 0.0 - 0.5m   │ 100%    │ Full volume (intimate)         │
+ * │ 1.0m         │ ~90%    │ Very close - still loud        │
+ * │ 2.0m         │ ~72%    │ Normal talking - NOTICEABLE    │
+ * │ 3.0m         │ ~57%    │ Across table - CLEARLY QUIETER │
+ * │ 5.0m         │ ~33%    │ Across room - MUCH QUIETER     │
+ * │ 7.0m         │ ~17%    │ Far end of room - very faint   │
+ * │ 10.0m        │ ~4%     │ Barely audible                 │
+ * │ ≥15.0m       │ 0%      │ Silent (COMPLETE CUTOFF)       │
+ * └──────────────┴─────────┴────────────────────────────────┘
+ */
+interface SpatialDistanceConfig {
+    refDistance?: number;
+    maxDistance?: number;
+    rolloffFactor?: number;
+    unit?: "auto" | "meters" | "centimeters";
+}
+/**
+ * Denoiser options for noise suppression
+ */
+interface DenoiserOptions {
+    enabled?: boolean;
+    threshold?: number;
+    noiseFloor?: number;
+    release?: number;
+    attack?: number;
+    holdMs?: number;
+    maxReduction?: number;
+    hissCut?: number;
+    expansionRatio?: number;
+    learnRate?: number;
+    voiceBoost?: number;
+    voiceSensitivity?: number;
+    voiceEnhancement?: boolean;
+    silenceFloor?: number;
+    silenceHoldMs?: number;
+    silenceReleaseMs?: number;
+    speechBoost?: number;
+    highBandGate?: number;
+    highBandAttack?: number;
+    highBandRelease?: number;
+}
+
+/**
+ * Spatial Audio Channel
+ *
+ * Processes audio for spatial positioning using Web Audio API
+ */
+
+/**
+ * Spatial audio configuration
+ */
+interface SpatialAudioConfig {
+    distance?: SpatialDistanceConfig;
+    denoiser?: DenoiserOptions;
+}
+
+/**
+ * Participant Types
+ */
+
+/**
+ * Media state for a participant
+ */
+interface MediaState {
+    audio: boolean;
+    video: boolean;
+    sharescreen: boolean;
+}
+/**
+ * Full participant data
+ */
+interface Participant {
+    participantId: string;
+    userId: string;
+    deviceId: string;
+    name?: string;
+    avatarUrl?: string;
+    isLocal: boolean;
+    audioTrack?: MediaStreamTrack;
+    videoTrack?: MediaStreamTrack;
+    producers: Map<string, any>;
+    consumers: Map<string, any>;
+    position: Position;
+    direction: Direction;
+    mediaState: MediaState;
+    rot?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    pan?: number;
+    dxLocal?: number;
+    bodyHeight?: string;
+    bodyShape?: string;
+    userName?: string;
+    userEmail?: string;
+    currentChannel?: string;
+}
+
+/**
+ * SDK Event Types
+ */
+
+/**
+ * Result returned when space live broadcast starts successfully
+ * Contains info needed for Vue to write to Firebase
+ */
+interface SpaceLiveBroadcastResult {
+    producerId: string;
+    roomId: string;
+    serverUrl: string;
+    timestamp: number;
+}
+/**
+ * Space Live Broadcast available event - emitted when someone starts broadcasting to space
+ */
+interface SpaceLiveBroadcastAvailableEvent {
+    roomId: string;
+    producerId: string;
+    producerUserId: string;
+    userName: string;
+}
+/**
+ * Space Live Broadcast stopped event - emitted when broadcast ends
+ */
+interface SpaceLiveBroadcastStoppedEvent {
+    roomId: string;
+}
+/**
+ * Space Live Broadcast status response
+ */
+interface SpaceLiveBroadcastStatusResponse {
+    isActive: boolean;
+    producerId?: string;
+    producerUserId?: string;
+    userName?: string;
+}
+/**
+ * All SDK event types
+ */
+type OdysseyEvent = "connected" | "disconnected" | "room-joined" | "all-participants-update" | "new-participant" | "participant-left" | "producer-created" | "consumer-created" | "consumer-closed" | "participant-media-state-updated" | "participant-position-updated" | "error" | "huddle-invite-received" | "private-huddle-started" | "huddle-updated" | "huddle-invite-rejected" | "huddle-ended" | "participant-channel-changed" | "mute-requested" | "space-live-broadcast-available" | "space-live-broadcast-stopped";
+
+/**
+ * Room and Transport Types
+ */
+
+/**
+ * Room joined data from server
+ */
+interface RoomJoinedData {
+    participants: Participant[];
+    routerRtpCapabilities: any;
+    participantId: string;
+    roomId: string;
+    iceServers: any[];
+}
+
+interface ChatMessage {
+    text?: string;
+    notification?: any;
+    [key: string]: any;
+}
+
+interface OdysseySpatialCommsHandle {
+    room: {
+        id: string;
+        participants: Map<string, Participant>;
+    } | null;
+    on(event: OdysseyEvent, listener: (...args: any[]) => void): void;
+    off(event: OdysseyEvent, listener: (...args: any[]) => void): void;
+    initializeMLNoiseSuppression(modelPath: string, workletUrl?: string): Promise<void>;
+    joinRoom(data: {
+        roomId: string;
+        userId: string;
+        deviceId: string;
+        participantId?: string;
+        position: Position;
+        direction: Direction;
+        bodyHeight?: string;
+        bodyShape?: string;
+        userName?: string;
+        userEmail?: string;
+    }): Promise<Participant>;
+    leaveRoom(): void;
+    resumeAudio(): Promise<void>;
+    getAudioContextState(): AudioContextState;
+    enhanceOutgoingAudioTrack(track: MediaStreamTrack): Promise<MediaStreamTrack>;
+    isMLNoiseSuppressionActive(): boolean;
+    getNoiseSuppressionMode(): "ml" | "audioworklet" | "none";
+    setMasterMuted(muted: boolean): void;
+    getMasterMuted(): boolean;
+    produceTrack(track: MediaStreamTrack, appData?: {
+        isScreenshare?: boolean;
+    }): Promise<any>;
+    recreateProducers(): Promise<void>;
+    updatePosition(position: Position, direction: Direction, spatialData?: {
+        cameraDistance?: number;
+        screenPos?: {
+            x: number;
+            y: number;
+        } | null;
+        rot?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        pan?: number;
+        dxLocal?: number;
+    }): void;
+    updateMediaState(mediaState: MediaState): void;
+    stopScreenShare(): Promise<void>;
+    stopVideoProducer(): Promise<void>;
+    startSpaceLiveBroadcast(): Promise<SpaceLiveBroadcastResult>;
+    stopSpaceLiveBroadcast(): Promise<void>;
+    getSpaceLiveBroadcastStatus(callback: (info: {
+        isActive: boolean;
+        producerId?: string;
+        producerUserId?: string;
+        userName?: string;
+    }) => void): void;
+    readonly isSpaceLiveBroadcasting: boolean;
+    setListenerPosition(position: Position, orientation: {
+        forwardX: number;
+        forwardY: number;
+        forwardZ: number;
+        upX: number;
+        upY: number;
+        upZ: number;
+    }): void;
+    setListenerFromLSD(listenerPos: Position, cameraPos: Position, lookAtPos: Position, rot?: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    chat: {
+        init(data: {
+            userId: string;
+            userName?: string;
+            channelId: string;
+            channelName?: string;
+        }): Promise<void>;
+        sendMessage(message: ChatMessage): Promise<any>;
+        sendNotification(data: {
+            text: string;
+            participants: string[];
+            sender: {
+                deviceId: string;
+                name?: string;
+                img?: string;
+            };
+        }): Promise<any>;
+        leave(): Promise<void>;
+        onMessage(callback: (message: any) => void): void;
+    };
+    sendHuddleInvite(toParticipantId: string): Promise<{
+        success?: boolean;
+        inviteId?: string;
+        huddleId?: string;
+        error?: string;
+    }>;
+    acceptHuddleInvite(inviteId: string): Promise<{
+        success?: boolean;
+        huddleId?: string;
+        participants?: string[];
+        error?: string;
+    }>;
+    rejectHuddleInvite(inviteId: string): Promise<{
+        success?: boolean;
+        error?: string;
+    }>;
+    joinHuddle(): Promise<{
+        success?: boolean;
+        channelId?: string;
+        error?: string;
+    }>;
+    leaveHuddle(): Promise<{
+        success?: boolean;
+        channelId?: string;
+        error?: string;
+    }>;
+    getParticipantChannel(participantId: string): Promise<string>;
+    muteParticipant(participantId: string): Promise<{
+        success?: boolean;
+        error?: string;
+    }>;
+    getCurrentChannel(): string;
+}
+/**
+ * Create an Odyssey Spatial Comms instance (browser-only SDK).
+ * @param apiKey        SDK API key issued by Odyssey (from payment service)
+ * @param userToken     JWT access token for the authenticated user (from SSO)
+ * @param spatialOptions  Optional spatial audio configuration
+ */
+declare function createOdysseySpatialComms(apiKey: string, userToken: string, spatialOptions?: SpatialAudioConfig): OdysseySpatialCommsHandle;
+
+declare const SpatialCommsSDK: {
+    /**
+     * Create a new SDK client instance.
+     * @param apiKey        SDK API key issued by Odyssey (from payment service)
+     * @param userToken     JWT access token for the authenticated user (from SSO)
+     * @param spatialOptions  Optional spatial audio configuration
+     */
+    readonly create: (apiKey: string, userToken: string, spatialOptions?: SpatialAudioConfig) => OdysseySpatialCommsHandle;
+};
+
+export { type ChatMessage, type Direction, type MediaState, type OdysseyEvent, type OdysseyEvent as OdysseySDKEvent, type OdysseySpatialCommsHandle, type Participant, type Position, type RoomJoinedData, type SpaceLiveBroadcastAvailableEvent, type SpaceLiveBroadcastResult, type SpaceLiveBroadcastStatusResponse, type SpaceLiveBroadcastStoppedEvent, type SpatialAudioConfig as SpatialAudioOptions, SpatialCommsSDK, createOdysseySpatialComms };

package/dist/index.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Position and Direction Types
+ *
+ * Coordinate system conventions:
+ * - Unreal Engine: X=forward, Y=right, Z=up (centimeters)
+ * - Standard/WebAudio: X=right, Y=up, Z=forward (meters)
+ */
+/**
+ * 3D position in space
+ */
+interface Position {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * 3D direction vector (normalized)
+ */
+interface Direction {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/**
+ * Spatial Audio Types
+ *
+ * Type definitions for spatial audio processing
+ */
+/**
+ * Spatial audio distance configuration
+ *
+ * DISTANCE-BASED GAIN SPECIFICATION (CUBIC FALLOFF):
+ * ┌──────────────┬─────────┬────────────────────────────────┐
+ * │ Distance     │ Gain %  │ Description                    │
+ * ├──────────────┼─────────┼────────────────────────────────┤
+ * │ 0.0 - 0.5m   │ 100%    │ Full volume (intimate)         │
+ * │ 1.0m         │ ~90%    │ Very close - still loud        │
+ * │ 2.0m         │ ~72%    │ Normal talking - NOTICEABLE    │
+ * │ 3.0m         │ ~57%    │ Across table - CLEARLY QUIETER │
+ * │ 5.0m         │ ~33%    │ Across room - MUCH QUIETER     │
+ * │ 7.0m         │ ~17%    │ Far end of room - very faint   │
+ * │ 10.0m        │ ~4%     │ Barely audible                 │
+ * │ ≥15.0m       │ 0%      │ Silent (COMPLETE CUTOFF)       │
+ * └──────────────┴─────────┴────────────────────────────────┘
+ */
+interface SpatialDistanceConfig {
+    refDistance?: number;
+    maxDistance?: number;
+    rolloffFactor?: number;
+    unit?: "auto" | "meters" | "centimeters";
+}
+/**
+ * Denoiser options for noise suppression
+ */
+interface DenoiserOptions {
+    enabled?: boolean;
+    threshold?: number;
+    noiseFloor?: number;
+    release?: number;
+    attack?: number;
+    holdMs?: number;
+    maxReduction?: number;
+    hissCut?: number;
+    expansionRatio?: number;
+    learnRate?: number;
+    voiceBoost?: number;
+    voiceSensitivity?: number;
+    voiceEnhancement?: boolean;
+    silenceFloor?: number;
+    silenceHoldMs?: number;
+    silenceReleaseMs?: number;
+    speechBoost?: number;
+    highBandGate?: number;
+    highBandAttack?: number;
+    highBandRelease?: number;
+}
+
+/**
+ * Spatial Audio Channel
+ *
+ * Processes audio for spatial positioning using Web Audio API
+ */
+
+/**
+ * Spatial audio configuration
+ */
+interface SpatialAudioConfig {
+    distance?: SpatialDistanceConfig;
+    denoiser?: DenoiserOptions;
+}
+
+/**
+ * Participant Types
+ */
+
+/**
+ * Media state for a participant
+ */
+interface MediaState {
+    audio: boolean;
+    video: boolean;
+    sharescreen: boolean;
+}
+/**
+ * Full participant data
+ */
+interface Participant {
+    participantId: string;
+    userId: string;
+    deviceId: string;
+    name?: string;
+    avatarUrl?: string;
+    isLocal: boolean;
+    audioTrack?: MediaStreamTrack;
+    videoTrack?: MediaStreamTrack;
+    producers: Map<string, any>;
+    consumers: Map<string, any>;
+    position: Position;
+    direction: Direction;
+    mediaState: MediaState;
+    rot?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    pan?: number;
+    dxLocal?: number;
+    bodyHeight?: string;
+    bodyShape?: string;
+    userName?: string;
+    userEmail?: string;
+    currentChannel?: string;
+}
+
+/**
+ * SDK Event Types
+ */
+
+/**
+ * Result returned when space live broadcast starts successfully
+ * Contains info needed for Vue to write to Firebase
+ */
+interface SpaceLiveBroadcastResult {
+    producerId: string;
+    roomId: string;
+    serverUrl: string;
+    timestamp: number;
+}
+/**
+ * Space Live Broadcast available event - emitted when someone starts broadcasting to space
+ */
+interface SpaceLiveBroadcastAvailableEvent {
+    roomId: string;
+    producerId: string;
+    producerUserId: string;
+    userName: string;
+}
+/**
+ * Space Live Broadcast stopped event - emitted when broadcast ends
+ */
+interface SpaceLiveBroadcastStoppedEvent {
+    roomId: string;
+}
+/**
+ * Space Live Broadcast status response
+ */
+interface SpaceLiveBroadcastStatusResponse {
+    isActive: boolean;
+    producerId?: string;
+    producerUserId?: string;
+    userName?: string;
+}
+/**
+ * All SDK event types
+ */
+type OdysseyEvent = "connected" | "disconnected" | "room-joined" | "all-participants-update" | "new-participant" | "participant-left" | "producer-created" | "consumer-created" | "consumer-closed" | "participant-media-state-updated" | "participant-position-updated" | "error" | "huddle-invite-received" | "private-huddle-started" | "huddle-updated" | "huddle-invite-rejected" | "huddle-ended" | "participant-channel-changed" | "mute-requested" | "space-live-broadcast-available" | "space-live-broadcast-stopped";
+
+/**
+ * Room and Transport Types
+ */
+
+/**
+ * Room joined data from server
+ */
+interface RoomJoinedData {
+    participants: Participant[];
+    routerRtpCapabilities: any;
+    participantId: string;
+    roomId: string;
+    iceServers: any[];
+}
+
+interface ChatMessage {
+    text?: string;
+    notification?: any;
+    [key: string]: any;
+}
+
+interface OdysseySpatialCommsHandle {
+    room: {
+        id: string;
+        participants: Map<string, Participant>;
+    } | null;
+    on(event: OdysseyEvent, listener: (...args: any[]) => void): void;
+    off(event: OdysseyEvent, listener: (...args: any[]) => void): void;
+    initializeMLNoiseSuppression(modelPath: string, workletUrl?: string): Promise<void>;
+    joinRoom(data: {
+        roomId: string;
+        userId: string;
+        deviceId: string;
+        participantId?: string;
+        position: Position;
+        direction: Direction;
+        bodyHeight?: string;
+        bodyShape?: string;
+        userName?: string;
+        userEmail?: string;
+    }): Promise<Participant>;
+    leaveRoom(): void;
+    resumeAudio(): Promise<void>;
+    getAudioContextState(): AudioContextState;
+    enhanceOutgoingAudioTrack(track: MediaStreamTrack): Promise<MediaStreamTrack>;
+    isMLNoiseSuppressionActive(): boolean;
+    getNoiseSuppressionMode(): "ml" | "audioworklet" | "none";
+    setMasterMuted(muted: boolean): void;
+    getMasterMuted(): boolean;
+    produceTrack(track: MediaStreamTrack, appData?: {
+        isScreenshare?: boolean;
+    }): Promise<any>;
+    recreateProducers(): Promise<void>;
+    updatePosition(position: Position, direction: Direction, spatialData?: {
+        cameraDistance?: number;
+        screenPos?: {
+            x: number;
+            y: number;
+        } | null;
+        rot?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        pan?: number;
+        dxLocal?: number;
+    }): void;
+    updateMediaState(mediaState: MediaState): void;
+    stopScreenShare(): Promise<void>;
+    stopVideoProducer(): Promise<void>;
+    startSpaceLiveBroadcast(): Promise<SpaceLiveBroadcastResult>;
+    stopSpaceLiveBroadcast(): Promise<void>;
+    getSpaceLiveBroadcastStatus(callback: (info: {
+        isActive: boolean;
+        producerId?: string;
+        producerUserId?: string;
+        userName?: string;
+    }) => void): void;
+    readonly isSpaceLiveBroadcasting: boolean;
+    setListenerPosition(position: Position, orientation: {
+        forwardX: number;
+        forwardY: number;
+        forwardZ: number;
+        upX: number;
+        upY: number;
+        upZ: number;
+    }): void;
+    setListenerFromLSD(listenerPos: Position, cameraPos: Position, lookAtPos: Position, rot?: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    chat: {
+        init(data: {
+            userId: string;
+            userName?: string;
+            channelId: string;
+            channelName?: string;
+        }): Promise<void>;
+        sendMessage(message: ChatMessage): Promise<any>;
+        sendNotification(data: {
+            text: string;
+            participants: string[];
+            sender: {
+                deviceId: string;
+                name?: string;
+                img?: string;
+            };
+        }): Promise<any>;
+        leave(): Promise<void>;
+        onMessage(callback: (message: any) => void): void;
+    };
+    sendHuddleInvite(toParticipantId: string): Promise<{
+        success?: boolean;
+        inviteId?: string;
+        huddleId?: string;
+        error?: string;
+    }>;
+    acceptHuddleInvite(inviteId: string): Promise<{
+        success?: boolean;
+        huddleId?: string;
+        participants?: string[];
+        error?: string;
+    }>;
+    rejectHuddleInvite(inviteId: string): Promise<{
+        success?: boolean;
+        error?: string;
+    }>;
+    joinHuddle(): Promise<{
+        success?: boolean;
+        channelId?: string;
+        error?: string;
+    }>;
+    leaveHuddle(): Promise<{
+        success?: boolean;
+        channelId?: string;
+        error?: string;
+    }>;
+    getParticipantChannel(participantId: string): Promise<string>;
+    muteParticipant(participantId: string): Promise<{
+        success?: boolean;
+        error?: string;
+    }>;
+    getCurrentChannel(): string;
+}
+/**
+ * Create an Odyssey Spatial Comms instance (browser-only SDK).
+ * @param apiKey        SDK API key issued by Odyssey (from payment service)
+ * @param userToken     JWT access token for the authenticated user (from SSO)
+ * @param spatialOptions  Optional spatial audio configuration
+ */
+declare function createOdysseySpatialComms(apiKey: string, userToken: string, spatialOptions?: SpatialAudioConfig): OdysseySpatialCommsHandle;
+
+declare const SpatialCommsSDK: {
+    /**
+     * Create a new SDK client instance.
+     * @param apiKey        SDK API key issued by Odyssey (from payment service)
+     * @param userToken     JWT access token for the authenticated user (from SSO)
+     * @param spatialOptions  Optional spatial audio configuration
+     */
+    readonly create: (apiKey: string, userToken: string, spatialOptions?: SpatialAudioConfig) => OdysseySpatialCommsHandle;
+};
+
+export { type ChatMessage, type Direction, type MediaState, type OdysseyEvent, type OdysseyEvent as OdysseySDKEvent, type OdysseySpatialCommsHandle, type Participant, type Position, type RoomJoinedData, type SpaceLiveBroadcastAvailableEvent, type SpaceLiveBroadcastResult, type SpaceLiveBroadcastStatusResponse, type SpaceLiveBroadcastStoppedEvent, type SpatialAudioConfig as SpatialAudioOptions, SpatialCommsSDK, createOdysseySpatialComms };