@4players/odin/lib/api/room/types.d.ts

A cross-platform SDK enabling developers to integrate real-time VoIP chat technology into their projects

import { Backend } from '@4players/odin-common';
import { IOdinEvent } from '../../utils/odin-event-target';
import { AudioOutput } from '../media/audio-output';
import { AudioInput } from '../media/audio-input';
import { VideoOutput } from '../media/video-output';
import { VideoInput } from '../media/video-input';
import { RemotePeer } from '../peer/remote-peer';
import { LocalPeer } from '../peer/local-peer';
import { Room } from '.';
import Transport = Backend.Transport;
import SetupCipherSettings = Backend.SetupCipherSettings;
import JitterStats = Backend.JitterStats;
export type Writable<T> = {
    -readonly [P in keyof T]: T[P];
};
/**
 * Represents the parameters required to join a room.
 */
export interface JoinParams {
    /**
     * The address of the gateway.
     */
    readonly gateway: string | undefined;
    /**
     * The UserData of the own peer.
     */
    readonly userData?: Uint8Array;
    /**
     * The position of the own peer.
     */
    readonly position?: [number, number, number];
    /**
     * The id of the room.
     */
    readonly roomId?: string;
    /**
     * Cipher configuration used to encrypt data sent via ODIN.
     * When defined, end-to-end encryption (E2E) is enabled for the data transmission.
     * This ensures that the data remains confidential and secure between the sender and receiver.
     *
     * @readonly Optional. If not specified, encryption is not applied.
     */
    readonly cipher?: SetupCipherSettings;
    /**
     * Specifies the protocol to be used for establishing the connection.
     * Supported protocols are:
     * - H3: HTTP/3, suitable for environments where low-latency and reliable transport is required.
     * - WebRTC: Web Real-Time Communication that is supported in all major browsers.
     *
     * Ensure to select the appropriate protocol based on your application's requirements.
     */
    readonly transport?: Transport;
}
/**
 * All possible connection states of the room.
 */
export type RoomStatus = {
    status: 'disconnected' | 'joining' | 'joined' | 'reconnecting';
    reason?: string;
};
/**
 * Interface describing the payload of an `OdinConnectionStateChangedEventHandler`.
 */
export interface RoomStatusChangedPayload {
    /**
     * Previous state of the connection.
     */
    oldState: RoomStatus;
    /**
     * Current state of the connection.
     */
    newState: RoomStatus;
}
/**
 * Event emitted when the connection status of the internal main/room stream was updated.
 *
 * Provides both the old and the new connection state.
 */
export type RoomStatusChangedEventHandler = (event: IOdinEvent<RoomStatusChangedPayload>) => void;
/**
 * Interface describing the payload of a `RoomDataChangedEventHandler`.
 */
export interface RoomDataChangedPayload {
    /**
     * The updated `Room` instance.
     */
    room: Room;
}
/**
 * Event emitted when the user data of a room was updated.
 *
 * Provides the updated `Room` instance.
 */
export type RoomDataChangedEventHandler = (event: IOdinEvent<RoomDataChangedPayload>) => void;
/**
 * Interface describing the payload of a `PeerJoinedEventHandler`.
 */
export interface PeerJoinedPayload {
    /**
     * The room the peer joined/left.
     */
    room: Room;
    /**
     * The peer that joined/left.
     */
    peer: RemotePeer | LocalPeer;
}
/**
 * Interface describing the payload of an `JoinedEventHandler`.
 */
export interface JoinedPayload {
    /**
     * The room the peer joined/left.
     */
    room: Room;
    /**
     * The peer that joined/left.
     */
    peer: LocalPeer;
}
/**
 * Interface describing the payload of a `PeerLeftEventHandler`.
 */
export interface PeerLeftPayload extends PeerJoinedPayload {
}
/**
 * Event emitted after the room was joined.
 */
export type JoinedEvent = IOdinEvent<PeerJoinedPayload>;
/**
 * Callback invoked after the room was joined.
 */
export type JoinedEventHandler = (event: JoinedEvent) => void;
/**
 * Event emitted whenever a remote peer joined the room.
 *
 * Provides the updated `Room` instance and the specific `Peer` instance.
 */
export type PeerJoinedEventHandler = JoinedEventHandler;
/**
 * Event emitted whenever a remote peer left the room.
 *
 * Provides the updated `Room` instance and the specific `Peer` instance.
 */
export type PeerLeftEventHandler = (event: IOdinEvent<PeerLeftPayload>) => void;
/**
 * Interface describing the payload of a `PeerDataChangedEventHandler`.
 */
export interface UserDataChangedPayload {
    /**
     * The room where the peer was updated.
     */
    room: Room;
    /**
     * The updated `Peer` instance.
     */
    peer: RemotePeer;
}
/**
 * Event emitted when the user data of a remote peer was updated.
 *
 * Provides the updated `Peer` instance.
 */
export type PeerDataChangedEventHandler = (event: IOdinEvent<UserDataChangedPayload>) => void;
export interface MediaPayloadBase {
    room: Room;
    peer: LocalPeer | RemotePeer;
}
/**
 * Interface describing the payload of an `OdinMediaStartedStoppedEvent`.
 */
export interface MediaPayload extends MediaPayloadBase {
    /**
     * The media that was added/removed.
     */
    media: AudioInput | AudioOutput | VideoInput | VideoOutput;
}
export interface AudioInputPayload extends MediaPayloadBase {
    /**
     * The media that was added/removed.
     */
    media: AudioInput;
}
/**
 * Represents the payload for AudioOutput Events.
 * Extends the MediaPayloadBase interface.
 *
 * Contains a reference to a AudioOutput.
 */
export interface AudioOutputPayload extends MediaPayloadBase {
    /**
     * The media that was added/removed.
     */
    media: AudioOutput;
}
/**
 * Represents the payload for VideoOutput Events.
 * Extends the MediaPayloadBase interface.
 *
 * Contains a reference to a VideoOutput.
 */
export interface VideoOutputPayload extends MediaPayloadBase {
    /**
     * The media that was added/removed.
     */
    media: VideoOutput;
}
/**
 * Represents the payload for VideoInput Events.
 * Extends the MediaPayloadBase interface.
 *
 * Contains a reference to a VideoInput.
 */
export interface VideoInputPayload extends MediaPayloadBase {
    /**
     * The media that was added/removed.
     */
    media: VideoInput;
}
/**
 * Event emitted whenever an AudioCapture was started or stopped.
 *
 * Provides the updated `Room`, `Peer` and `OdinMedia` instances.
 */
export type AudioInputEventHandler = (event: IOdinEvent<AudioInputPayload>) => void;
/**
 * Event emitted whenever an AudioOutput was started or stopped.
 *
 * Provides the updated `Room`, `Peer` and `OdinMedia` instances.
 */
export type AudioOutputEventHandler = (event: IOdinEvent<AudioOutputPayload>) => void;
/**
 * Event emitted whenever an AudioOutput was started or stopped.
 *
 * Provides the updated `Room`, `Peer` and `OdinMedia` instances.
 */
export type VideoOutputEventHandler = (event: IOdinEvent<VideoOutputPayload>) => void;
/**
 * Event emitted whenever a VideoCapture was started or stopped.
 *
 * Provides the current `Room`, `Peer` and `OdinMedia` instances.
 */
export type VideoInputEventHandler = (event: IOdinEvent<VideoInputPayload>) => void;
/**
 * Event emitted whenever a Media was started or stopped.
 *
 * Provides the current `Room`, `Peer` and `OdinMedia` instances.
 */
export type MediaEventHandler = (event: IOdinEvent<MediaPayload>) => void;
/**
 * Interface describing the payload of an `OdinMediaActivityChangedEvent`.
 */
export interface AudioActivityPayload {
    media: AudioInput | AudioOutput;
}
/**
 * Event emitted when the sending/receiving status of a media changes (e.g. when a user starts/stops talking).
 *
 * Provides the updated `Room`, `Peer` and `OdinMedia` instances as well as the new state.
 */
export type AudioActivityEventHandler = (event: IOdinEvent<AudioActivityPayload>) => void;
export type JitterStatsEventHandler = (event: IOdinEvent<JitterStats>) => void;
/**
 * Interface describing the payload of an `OdinMessageReceivedEventHandler`.
 */
export interface MessageReceivedPayload {
    /**
     * The room where the message was received.
     */
    room: Room;
    /**
     * The ID of the peer that sent the message (might not be in proximity).
     */
    peer: RemotePeer | undefined;
    /**
     * A byte array with the message.
     */
    message: Uint8Array | undefined;
}
/**
 * Event emitted whenever a message with arbitrary data is received.
 *
 * Provides the `Room` instance where the message was received, the sender peer ID and the actual message data.
 */
export type MessageReceivedEventHandler = (event: IOdinEvent<MessageReceivedPayload>) => void;
/**
 * Interface describing the payload of an `OdinDisconnectedByServerEvent.`
 */
export interface LeftPayload {
    /**
     * The `Room` instace the stats ere coming from.
     */
    room: Room;
    /**
     * The reason why the server disconnected the room.
     */
    reason: string;
}
/**
 * Event emitted whenever a message with arbitrary data is received.
 *
 * Provides the `Room` instance where the message was received, the sender peer ID and the actual message data.
 */
export type ConnectionStatsEventHandler = (event: IOdinEvent<ConnectionStats>) => void;
/**
 * Event emitted when the server disconnected the room.
 *
 * Provides the room and the reason.
 */
export type LeftEventHandler = (event: IOdinEvent<LeftPayload>) => void;
export interface InputEvents {
    /**
     * Gets invoked when a new AudioInput was started.
     */
    AudioInputStarted: AudioInputEventHandler;
    /**
     * Gets invoked when a new AudioInput was stopped.
     */
    AudioInputStopped: AudioInputEventHandler;
    /**
     * Gets invoked when a new VideoInput was added to the room.
     */
    VideoInputStarted: VideoInputEventHandler;
    /**
     * Gets invoked when a new VideoInput was stopped.
     */
    VideoInputStopped: VideoInputEventHandler;
}
export interface OutputEvents {
    /**
     * Gets invoked when a new AudioOutput was started.
     */
    AudioOutputStarted: AudioOutputEventHandler;
    /**
     * Gets invoked when a new AudioOutput was stopped.
     */
    AudioOutputStopped: AudioOutputEventHandler;
    /**
     * Gets invoked when a new VideoOutput was added to the room.
     */
    VideoOutputAdded: VideoOutputEventHandler;
    /**
     * Gets invoked when a new VideOutput was stopped.
     */
    VideoOutputRemoved: VideoOutputEventHandler;
}
/**
 * All Media Started & Stopped events
 */
export interface MediaSharedEvents extends OutputEvents, InputEvents {
    /**
     * Gets invoked when a Media was started.
     * Current Medias are AudioInputs, AudioOutputs, VideoInput, VideoOutputs.
     */
    MediaStarted: MediaEventHandler;
    /**
     * Gets invoked when a Media was stopped.
     * Current Medias are AudioInputs, AudioOutputs, VideoInput, VideoOutputs.
     */
    MediaStopped: MediaEventHandler;
    /**
     * Gets invoked in an interval to provide connection stats.
     */
    ConnectionStats: ConnectionStatsEventHandler;
}
/**
 * Interface describing possible room events.
 */
export interface RoomEvents extends MediaSharedEvents {
    /**
     * Gets invoked after a Room join was successfully performed.
     */
    Joined: JoinedEventHandler;
    /**
     * Gets called when the server disconnected the client. Provides a reason.
     */
    Left: LeftEventHandler;
    /**
     * Gets called when the Room status changed.
     */
    RoomStatusChanged: RoomStatusChangedEventHandler;
    /**
     * Gets called when the Room data was updated.
     */
    RoomDataChanged: RoomDataChangedEventHandler;
    /**
     * Gets called when a new peer enters the room.
     */
    PeerJoined: PeerJoinedEventHandler;
    /**
     * Gets called when a peer left the room.
     */
    PeerLeft: PeerLeftEventHandler;
    /**
     * Gets called when a peer in the room updated its user data.
     */
    UserDataChanged: PeerDataChangedEventHandler;
    /**
     * Gets called when a media in the room is processing audio data.
     */
    AudioActivity: AudioActivityEventHandler;
    /**
     * Gets called when the rmsDBFS value of Medias changes.
     */
    AudioPowerLevel: AudioActivityEventHandler;
    /**
     * Gets called on receiving a message with arbitrary data.
     */
    MessageReceived: MessageReceivedEventHandler;
    /**
     * Gets called when the ConnectionStats are being updated.
     * Multiple rooms can use the same connection.
     */
    ConnectionStats: ConnectionStatsEventHandler;
}
/**
 * Interface describing possible media events.
 */
export interface MediaEvents {
    /**
     * The media is sending/receiving data.
     */
    Activity: AudioActivityEventHandler;
    PowerLevel: AudioActivityEventHandler;
    JitterStats: JitterStatsEventHandler;
}
/**
 * Interface describing a generic message payload.
 */
export interface IMessageData {
    message: Uint8Array;
    target_peer_ids?: number[];
}
export interface ConnectionStats extends Backend.ConnectionStats {
    bytesReceivedLastSecond: number;
    bytesSentLastSecond: number;
}