@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";
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 _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;
    private onReceiveStream;
    private onStreamEnded;
    private onEnabledChanged;
    private onVisibilityChanged;
}