useLumioSound

Control sound playback in browser sources from an extension. Sounds must exist in the account's sound library - either uploaded by the user or bundled with the extension.

Signature

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

Return value

Property	Type	Description
playSound	(soundId: string, volume?: number) => Promise<void>	Trigger playback of a sound in all subscribed browser sources
stopSound	(soundId: string) => Promise<void>	Stop playback of a sound in all subscribed browser sources
getSounds	() => Promise<Sound[]>	Fetch the list of sounds in the account's library

Sound

Field	Type	Description
id	string	Sound UUID
name	string	Display name
file_size	number	File size in bytes
duration_ms	number | null	Duration in milliseconds
created_at	string	ISO-8601 upload timestamp
source_extension_name	string | null	Extension that bundled this sound, or null for user-uploaded sounds

Parameters

playSound(soundId, volume?)

Parameter	Type	Required	Description
soundId	string	Yes	UUID of the sound to play
volume	number	No	Playback volume 0.0–1.0 (default 1.0)

Plays the sound in every browser source subscribed to the sounds:{accountId} WebSocket channel. Returns a promise that resolves when the play command is dispatched.

stopSound(soundId)

Parameter	Type	Required	Description
soundId	string	Yes	UUID of the sound to stop

Stops playback in all subscribed browser sources.

getSounds()

Fetches the account's sound library. Returns an array of Sound objects. The result is not cached - call once on mount if you only need it for initial state.

Example - play a configured sound

import { useLumioConfig, useLumioSound, Button } from "@zaflun/lumio-sdk";

interface MyConfig {
  alertSound: string | null;
  alertVolume: number;
}

function AlertPanel() {
  const [config] = useLumioConfig<MyConfig>();
  const { playSound } = useLumioSound();

  const handlePlay = async () => {
    if (!config.alertSound) return;
    await playSound(config.alertSound, config.alertVolume ?? 1.0);
  };

  return (
    <Button onClick={handlePlay} disabled={!config.alertSound}>
      Play alert
    </Button>
  );
}

Example - build a sound picker in editor.tsx

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

function SoundEditor() {
  const [config, setConfig] = useLumioConfig();
  const { getSounds } = useLumioSound();
  const [sounds, setSounds] = useState([]);

  useEffect(() => {
    getSounds().then(setSounds);
  }, []);

  const options = [
    { value: "", label: "None" },
    ...sounds.map((s) => ({ value: s.id, label: s.name })),
  ];

  return (
    <EditorSelect
      label="Alert sound"
      value={config.alertSound ?? ""}
      options={options}
      onChange={(v) => setConfig((prev) => ({ ...prev, alertSound: v || null }))}
    />
  );
}

Required permissions

The extension must declare sounds:play in lumio.config.json to use playSound and stopSound:

{
  "permissions": ["sounds:play"]
}

getSounds does not require any declared permission - it is available to all extensions by default.

Notes

• playSound and stopSound broadcast to all browser sources in the account. There is no per-surface targeting from the SDK - use the REST or GraphQL API directly if you need to target a specific overlay key.
• Sounds must exist in the account's library. If soundId does not exist, the server returns a 404 and the promise rejects.
• The feature:sounds feature flag must be enabled for the account. If it is disabled, all three methods throw a FEATURE_DISABLED error.