useAudio

import { useAudio } from "@carverjs/core/hooks";

import { useGameLoop, useInput, useAudio } from "@carverjs/core/hooks";

function Player() {
  const { isActionJustPressed } = useInput({ actions: { jump: ["Space"] } });
  const { play } = useAudio({
    sounds: {
      jump: { src: "/sounds/jump.mp3" },
      land: { src: ["/sounds/land.webm", "/sounds/land.mp3"] },
    },
  });

  useGameLoop(() => {
    if (isActionJustPressed("jump")) play("jump");
  });

  return <Actor type="primitive" shape="box" color="blue" />;
}

const audio = useAudio({
  sounds: {
    jump: { src: "/sounds/jump.mp3" },
    coin: { src: "/sounds/coin.ogg", volume: 0.8 },
  },
  enabled: true,
});

sounds: {
  explosion: {
    src: ["/sounds/explosion.webm", "/sounds/explosion.ogg", "/sounds/explosion.mp3"],
  },
}

const { play } = useAudio({ sounds: { hit: { src: "/sounds/hit.mp3" } } });

play("hit"); // Fire and forget

const handle = play("hit", {
  volume: 0.5,       // Override volume
  rate: 1.2,         // Speed up
  loop: true,        // Loop this instance
  fadeIn: 0.3,       // Fade in over 0.3 seconds
  delay: 0.5,        // Wait 0.5 seconds before playing
  onEnd: () => {},   // Called when playback finishes (non-looping)
});

const handle = play("engine", { loop: true });

// Later...
handle?.setVolume(0.3);
handle?.setRate(1.5);
handle?.fade(1, 0, 2);    // Fade from 1 to 0 over 2 seconds
handle?.pause();
handle?.resume();
handle?.stop();

function Enemy() {
  const ref = useRef<Group>(null);
  const { play } = useAudio({
    sounds: { growl: { src: "/sounds/growl.ogg", loop: true } },
  });

  useEffect(() => {
    play("growl", {
      spatial: {
        ref,
        panningModel: "HRTF",      // Realistic 3D audio (default)
        distanceModel: "inverse",   // Volume rolloff model (default)
        refDistance: 2,             // Full volume within 2 units
        maxDistance: 50,            // Silent beyond 50 units
        rolloffFactor: 1,          // Rolloff speed
      },
    });
  }, [play]);

  return <Actor ref={ref} type="model" src="/models/enemy.glb" />;
}

const { playMusic, isUnlocked } = useAudio();

useEffect(() => {
  if (isUnlocked) {
    playMusic("/music/level1.mp3", { loop: true });
  }
}, [isUnlocked, playMusic]);

// Playing track A...
playMusic("/music/boss.mp3", {
  crossfade: { duration: 3 }, // 3-second crossfade
});
// Track A fades out, boss music fades in

stopMusic(2);     // Fade out over 2 seconds
pauseMusic();     // Pause (preserves position)
resumeMusic();    // Resume from paused position

const { play } = useAudio({
  sounds: {
    footsteps: {
      src: "/sounds/footsteps.ogg",
      sprites: {
        left:  { start: 0, duration: 0.3 },
        right: { start: 0.4, duration: 0.3 },
        run:   { start: 0.8, duration: 0.2, loop: true },
      },
    },
  },
});

play("footsteps", { sprite: "left" });
play("footsteps", { sprite: "run" });

[Source] → [Instance Gain] → [Channel Gain] → [Master Gain] → Output

function SettingsMenu() {
  const { setVolume, getVolume, setMute, isMuted } = useAudio();

  return (
    <div>
      <label>
        Master Volume
        <input
          type="range"
          min={0} max={1} step={0.01}
          defaultValue={getVolume("master")}
          onChange={(e) => setVolume("master", parseFloat(e.target.value))}
        />
      </label>
      <label>
        <input
          type="checkbox"
          checked={isMuted("sfx")}
          onChange={(e) => setMute("sfx", e.target.checked)}
        />
        Mute SFX
      </label>
    </div>
  );
}

const { isUnlocked, playMusic } = useAudio();

// Music starts as soon as the user interacts
useEffect(() => {
  if (isUnlocked) playMusic("/music/bg.mp3");
}, [isUnlocked, playMusic]);