Skip to main content

useLumioSound

Play a sound from the account's sound library in the surface that renders your extension: the overlay or widget browser source (also in OBS), or the dashboard preview. The sound plays only in that page. It is not sent to the account's other overlays.

Signature​

const { playSound, stopSound, getSounds } = useLumioSound();

Return value​

NameTypeDescription
playSound(soundId: string, volume?: number) => Promise<void>Plays the sound. volume is clamped to 0–1; without it the sound plays at full volume. Playing a sound that is already playing restarts it.
stopSound(soundId: string) => Promise<void>Stops the sound if it is playing in this surface.
getSounds() => Promise<Sound[]>Lists the account's sounds. Available in the dashboard (editor and preview) only; on an overlay or widget it rejects.

soundId is the UUID of a sound in the account's library, usually the value of a sound config field. A malformed id rejects with an invalid-params error. A sound that does not exist in the account rejects with Sound not found.

Sound has id, name, file_size, duration_ms, created_at and source_extension_name.

Permission​

Declare sounds:play in lumio.config.json:

{
  "permissions": ["events:read", "sounds:play"]
}

Without it the host refuses all three calls. The permission only lets the extension play sounds in its own surface. It does not grant the account's sounds:play API permission, which plays a sound on every overlay (POST /v1/sounds/{id}/play).

Example​

import { useLumioConfig, useLumioEvent, useLumioSound } from "@zaflun/lumio-sdk";
import { useEffect } from "react";

function FollowSound() {
  const [config] = useLumioConfig();
  const follow = useLumioEvent("twitch:follower");
  const { playSound } = useLumioSound();

  useEffect(() => {
    const sound = config.settings?.alertSound;
    const volume = config.settings?.volume;
    if (!follow || typeof sound !== "string") return;
    playSound(sound, typeof volume === "number" ? volume : undefined).catch(() => {});
  }, [follow]);

  return null;
}

Notes​

  • A dashboard browser tab can refuse to start audio before the user has interacted with the page. playSound then rejects. OBS browser sources play without a click.
  • Each surface downloads a sound once and keeps it until the surface closes.
  • In lumio dev, the dev host logs the call with its parameters.
  • For integrations outside an extension, use the Sounds REST API with an appropriately scoped personal or service key.