@needle-tools/engine/lib/engine-components/Voip.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { Behaviour } from "./Component.js";
import { EventList } from "./EventList.js";
export declare const noVoip = "noVoip";
/**
 * [Voip](https://engine.needle.tools/docs/api/Voip) Voice over IP (VoIP) component for real-time audio communication between users.
 * Allows sending and receiving audio streams in networked rooms.
 *
 * **Requirements:**
 * - Active network connection (via {@link SyncedRoom} or manual connection)
 * - User permission for microphone access (requested automatically)
 * - HTTPS connection (required for WebRTC)
 *
 * **Features:**
 * - Automatic connection when joining rooms (`autoConnect`)
 * - Background audio support (`runInBackground`)
 * - Optional UI toggle button (`createMenuButton`)
 * - Mute/unmute control
 *
 * **Debug:** Use `?debugvoip` URL parameter or set `debug = true` for logging.
 * Press 'v' to toggle mute, 'c' to connect/disconnect when debugging.
 *
 * @example Enable VoIP in your scene
 * ```ts
 * const voip = myObject.addComponent(Voip);
 * voip.autoConnect = true;
 * voip.createMenuButton = true;
 *
 * // Manual control
 * voip.connect();    // Start sending audio
 * voip.disconnect(); // Stop sending
 * voip.setMuted(true); // Mute microphone
 * ```
 *
 * @summary Voice over IP for networked audio communication
 * @category Networking
 * @group Components
 * @see {@link SyncedRoom} for room management
 * @see {@link NetworkedStreams} for the underlying streaming
 * @see {@link ScreenCapture} for video streaming
 * @link https://engine.needle.tools/docs/networking.html
 */
export declare class Voip extends Behaviour {
    /** When enabled, VoIP will start when a room is joined or when this component is enabled while already in a room.
     * @default true
    */
    autoConnect: boolean;
    /**
     * When enabled, VoIP will stay connected even when the browser tab is not focused/active anymore.
     * @default true
     */
    runInBackground: boolean;
    /**
     * When enabled, a menu button will be created to allow the user to toggle VoIP on and off.
     */
    createMenuButton: boolean;
    /**
     * When enabled debug messages will be printed to the console. This is useful for debugging audio issues. You can also append ?debugvoip to the URL to enable this.
     */
    debug: boolean;
    private _volume;
    /**
     * Volume for incoming audio streams (0 = silent, 1 = full volume).
     * Changes apply immediately to all active incoming streams.
     */
    get volume(): number;
    set volume(val: number);
    /**
     * Get the incoming audio element for a specific user.
     * Use this to route audio through the Web Audio API for spatial audio, effects, or analysis.
     * @param userId The connection ID of the remote user
     * @returns The HTMLAudioElement for this user's stream, or undefined if not connected
     * @example
     * ```ts
     * const audioEl = voip.getAudioElement(userId);
     * if (audioEl) {
     *   const audioCtx = new AudioContext();
     *   const source = audioCtx.createMediaElementSource(audioEl);
     *   const panner = audioCtx.createPanner();
     *   source.connect(panner).connect(audioCtx.destination);
     * }
     * ```
     */
    getAudioElement(userId: string): HTMLAudioElement | undefined;
    /**
     * Get all active incoming audio streams as a Map of userId → HTMLAudioElement.
     * Useful for iterating over all connected voice users.
     */
    get incomingStreams(): ReadonlyMap<string, HTMLAudioElement>;
    /**
     * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
     * they are considered "speaking". Default is 30.
     */
    speakingThreshold: number;
    /**
     * Event fired when a user's speaking state changes.
     * Passes `{ userId: string, isSpeaking: boolean, volume: number }`.
     */
    onSpeakingChanged: EventList;
    private _speakingStates;
    private _analysers;
    private _net?;
    private _menubutton?;
    /** @internal */
    awake(): void;
    /** @internal */
    onEnable(): void;
    /** @internal */
    onDisable(): void;
    /** @internal */
    onDestroy(): void;
    /** Set via the mic button (e.g. when the websocket connection closes and rejoins but the user was muted before we don't want to enable VOIP again automatically) */
    private _allowSending;
    private _outputStream;
    /**
     * @returns true if the component is currently sending audio
     */
    get isSending(): boolean;
    /** Start sending audio. */
    connect(audioSource?: MediaTrackConstraints): Promise<boolean>;
    /** Stop sending audio (muting your own microphone) */
    disconnect(opts?: {
        remember: boolean;
    }): void;
    /**
     * Mute or unmute the audio stream (this will only mute incoming streams and not mute your own microphone. Use disconnect() to mute your own microphone)
     */
    setMuted(mute: boolean): void;
    /** Returns true if the audio stream is currently muted */
    get isMuted(): boolean;
    private updateButton;
    /** @deprecated */
    getFrequency(_userId: string | null): number | null;
    private getAudioStream;
    private onJoinedRoom;
    private onLeftRoom;
    private _incomingStreams;
    /** @internal */
    update(): void;
    private setupAnalyser;
    private cleanupAnalyser;
    private onReceiveStream;
    private onStreamEnded;
    private onEnabledChanged;
    private onVisibilityChanged;
}