AudioListener

AudioListener overrides the default audio listener position. By default, the Web Audio listener follows the active R3F camera. Mount this component to follow a different Object3D instead (e.g., a player ref).

import { AudioListener } from "@carverjs/core/components";

Quick Start #

import { useRef } from "react";
import { Game, World, Actor } from "@carverjs/core/components";
import { AudioListener } from "@carverjs/core/components";
import type { Group } from "@carverjs/core/types";

function SplitScreenGame() {
  const player1Ref = useRef<Group>(null);

  return (
    <Game>
      <World>
        <AudioListener listenerRef={player1Ref} />
        <Actor ref={player1Ref} type="model" src="/player.glb" />
      </World>
    </Game>
  );
}

When to Use #

• Split-screen: Listener should follow one player, not the camera

• 2D games: The camera is often far from the action plane (e.g., at Z=100). Setting the listener to the player gives correct left/right stereo panning based on world positions

• Cutscenes: Listener stays on a character while the camera moves freely

When AudioListener is not mounted, the listener automatically follows the active R3F camera (the default behavior set by AudioFlush inside Game).

Props #

The listener position is updated every frame (at priority -49, just before AudioFlush at -48).

On unmount, the override is cleared and the listener falls back to the camera.

Type Definitions #

See Types for AudioListenerConfig.