@adea-ai/audio 0.10.8 → 0.10.9

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -p tsconfig.json

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+/** Optional soundtrack hooks for Agent HQ. */
+export declare const AUDIO_BASE_URL = "/assets/audio";
+export declare const MUSIC_DIR = "/assets/audio/sounds/music";
+export declare const MUSIC_FILES: {
+    readonly silent: "";
+};
+export type MusicId = keyof typeof MUSIC_FILES;

package/dist/config.js

@@ -0,0 +1,6 @@
+/** Optional soundtrack hooks for Agent HQ. */
+export const AUDIO_BASE_URL = "/assets/audio";
+export const MUSIC_DIR = `${AUDIO_BASE_URL}/sounds/music`;
+export const MUSIC_FILES = {
+    silent: "",
+};

package/dist/controller.d.ts

@@ -0,0 +1,27 @@
+import { type MusicId } from "./config";
+export type MusicOptions = {
+    /** 0..1 track gain (default 0.8). */
+    volume?: number;
+    /** Crossfade/fade duration in ms (default 500). */
+    fadeMs?: number;
+};
+export declare class SoundController {
+    private musicElements;
+    private desiredMusic;
+    private currentMusic;
+    private activeFades;
+    private _musicMuted;
+    constructor();
+    get musicMuted(): boolean;
+    /** Retry queued playback after a user gesture. */
+    unlock(): Promise<void>;
+    /** Start or switch to a looping soundtrack. */
+    playMusic(id: MusicId, options?: MusicOptions): void;
+    setMusicMuted(muted: boolean): void;
+    toggleMusicMute(): boolean;
+    private prepareMusicElement;
+    private startMusic;
+    private startDesiredMusic;
+    private fadeMusic;
+}
+export declare const soundController: SoundController;

package/dist/controller.js

@@ -0,0 +1,152 @@
+import { MUSIC_DIR, MUSIC_FILES } from "./config";
+const MUSIC_MUTE_KEY = "agent-hq:audio:music-muted";
+const LEGACY_MUTE_KEY = "agent-hq:audio:muted";
+const DEFAULT_MUSIC_VOLUME = 0.8;
+const FADE_STEP_MS = 30;
+function clampVolume(value) {
+    return value <= 0 ? 0 : value > 1 ? 1 : value;
+}
+function readStorage(key) {
+    if (typeof window === "undefined")
+        return null;
+    try {
+        return window.localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStorage(key, muted) {
+    if (typeof window === "undefined")
+        return;
+    try {
+        if (muted)
+            window.localStorage.setItem(key, "1");
+        else
+            window.localStorage.removeItem(key);
+    }
+    catch {
+        // Storage can be unavailable; the in-memory mute still applies.
+    }
+}
+function loadMusicMuted() {
+    return readStorage(MUSIC_MUTE_KEY) === "1" || readStorage(LEGACY_MUTE_KEY) === "1";
+}
+export class SoundController {
+    musicElements = new Map();
+    desiredMusic = null;
+    currentMusic = null;
+    activeFades = new Set();
+    _musicMuted;
+    constructor() {
+        this._musicMuted = loadMusicMuted();
+    }
+    get musicMuted() {
+        return this._musicMuted;
+    }
+    /** Retry queued playback after a user gesture. */
+    async unlock() {
+        this.startDesiredMusic();
+    }
+    /** Start or switch to a looping soundtrack. */
+    playMusic(id, options = {}) {
+        if (!MUSIC_FILES[id])
+            return;
+        this.desiredMusic = id;
+        this.prepareMusicElement(id);
+        if (!this.musicMuted)
+            this.startMusic(id, options);
+    }
+    setMusicMuted(muted) {
+        this._musicMuted = muted;
+        writeStorage(MUSIC_MUTE_KEY, muted);
+        for (const element of this.musicElements.values()) {
+            if (muted)
+                element.pause();
+        }
+        if (!muted)
+            this.startDesiredMusic();
+    }
+    toggleMusicMute() {
+        this.setMusicMuted(!this._musicMuted);
+        return this._musicMuted;
+    }
+    prepareMusicElement(id) {
+        if (this.musicElements.has(id))
+            return;
+        const element = new Audio(`${MUSIC_DIR}/${MUSIC_FILES[id]}`);
+        element.loop = true;
+        // Defer the request until playback is allowed so audio never competes with
+        // the scene's first visual and physics assets.
+        element.preload = "none";
+        this.musicElements.set(id, element);
+    }
+    startMusic(id, options = {}) {
+        if (this.currentMusic === id) {
+            const active = this.musicElements.get(id);
+            if (active?.paused)
+                void active.play().catch(() => undefined);
+            return;
+        }
+        const fadeMs = options.fadeMs ?? 500;
+        const target = clampVolume(options.volume ?? DEFAULT_MUSIC_VOLUME);
+        const previousId = this.currentMusic;
+        const previous = previousId ? (this.musicElements.get(previousId) ?? null) : null;
+        this.currentMusic = id;
+        const element = this.musicElements.get(id);
+        if (!element)
+            return;
+        element.volume = 0;
+        element.currentTime = 0;
+        void element
+            .play()
+            .then(() => {
+            if (this.currentMusic !== id) {
+                element.pause();
+                return;
+            }
+            if (previous) {
+                this.fadeMusic(previous, 0, fadeMs, () => {
+                    previous.pause();
+                    previous.currentTime = 0;
+                });
+            }
+            this.fadeMusic(element, target, fadeMs);
+        })
+            .catch(() => {
+            // Autoplay is blocked before the first user gesture. Keep the desired
+            // track so unlock() can retry it later.
+            if (previous)
+                this.currentMusic = previousId;
+            else
+                this.currentMusic = null;
+        });
+    }
+    startDesiredMusic() {
+        if (this.musicMuted || !this.desiredMusic)
+            return;
+        const desired = this.desiredMusic;
+        if (this.currentMusic !== desired) {
+            this.startMusic(desired);
+            return;
+        }
+        const element = this.musicElements.get(desired);
+        if (element?.paused)
+            void element.play().catch(() => undefined);
+    }
+    fadeMusic(element, target, durationMs, onDone) {
+        const start = element.volume;
+        const startTime = performance.now();
+        const interval = window.setInterval(() => {
+            const progress = Math.min(1, (performance.now() - startTime) / Math.max(durationMs, 1));
+            element.volume = start + (target - start) * progress;
+            if (progress >= 1) {
+                window.clearInterval(interval);
+                this.activeFades.delete(interval);
+                onDone?.();
+            }
+        }, FADE_STEP_MS);
+        this.activeFades.add(interval);
+    }
+}
+export const soundController = new SoundController();

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AUDIO_BASE_URL, MUSIC_FILES, type MusicId } from "./config";
+export { SoundController, soundController, type MusicOptions } from "./controller";
+export { musicForScene, sceneMusicTracks } from "./scene-music";
+export { MusicToggle, SoundProvider, useSceneMusic, useSound, type SoundContextValue, } from "./react";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Optional soundtrack hooks for Agent HQ.
+export { AUDIO_BASE_URL, MUSIC_FILES } from "./config";
+export { SoundController, soundController } from "./controller";
+export { musicForScene, sceneMusicTracks } from "./scene-music";
+export { MusicToggle, SoundProvider, useSceneMusic, useSound, } from "./react";

package/dist/react.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import { soundController, type MusicOptions } from "./controller";
+import type { MusicId } from "./config";
+export type SoundContextValue = {
+    controller: typeof soundController;
+    ready: boolean;
+    musicMuted: boolean;
+    toggleMusicMute: () => void;
+    playMusic: (id: MusicId, options?: MusicOptions) => void;
+};
+export declare function SoundProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useSound(): SoundContextValue;
+export declare function useSceneMusic(sceneId: string | null | undefined): void;
+export declare function MusicToggle(): import("react").JSX.Element;

package/dist/react.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { Music, Music2 } from "lucide-react";
+import { soundController } from "./controller";
+import { musicForScene } from "./scene-music";
+const SoundContext = createContext(null);
+export function SoundProvider({ children }) {
+    const [musicMuted, setMusicMuted] = useState(false);
+    const [ready, setReady] = useState(false);
+    useEffect(() => {
+        let mounted = true;
+        queueMicrotask(() => {
+            if (mounted)
+                setMusicMuted(soundController.musicMuted);
+        });
+        const onGesture = () => {
+            void soundController.unlock().then(() => {
+                if (mounted)
+                    setReady(true);
+            });
+        };
+        window.addEventListener("pointerdown", onGesture, { capture: true });
+        window.addEventListener("keydown", onGesture, { capture: true });
+        window.addEventListener("touchstart", onGesture, { capture: true });
+        if (new URLSearchParams(window.location.search).has("debug")) {
+            window.__agentHqSound =
+                soundController;
+        }
+        return () => {
+            mounted = false;
+            window.removeEventListener("pointerdown", onGesture, { capture: true });
+            window.removeEventListener("keydown", onGesture, { capture: true });
+            window.removeEventListener("touchstart", onGesture, { capture: true });
+        };
+    }, []);
+    const value = useMemo(() => ({
+        controller: soundController,
+        ready,
+        musicMuted,
+        toggleMusicMute: () => setMusicMuted(soundController.toggleMusicMute()),
+        playMusic: (id, options) => soundController.playMusic(id, options),
+    }), [musicMuted, ready]);
+    return _jsx(SoundContext.Provider, { value: value, children: children });
+}
+export function useSound() {
+    const value = useContext(SoundContext);
+    if (!value)
+        throw new Error("useSound must be used within <SoundProvider>");
+    return value;
+}
+export function useSceneMusic(sceneId) {
+    useEffect(() => {
+        const timeout = window.setTimeout(() => {
+            soundController.playMusic(musicForScene(sceneId));
+        }, 1500);
+        return () => window.clearTimeout(timeout);
+    }, [sceneId]);
+}
+function MusicButton({ muted, onToggle }) {
+    return (_jsx("button", { type: "button", "aria-label": muted ? "Unmute music" : "Mute music", "aria-pressed": muted, onClick: onToggle, className: `inline-flex size-9 items-center justify-center rounded-lg border border-input bg-background transition-colors ${muted ? "text-muted-foreground hover:text-foreground" : "bg-primary text-primary-foreground"}`, children: muted ? (_jsx(Music, { className: "size-5", "aria-hidden": "true" })) : (_jsx(Music2, { className: "size-5", "aria-hidden": "true" })) }));
+}
+export function MusicToggle() {
+    const { musicMuted, toggleMusicMute } = useSound();
+    return _jsx(MusicButton, { muted: musicMuted, onToggle: toggleMusicMute });
+}

package/dist/scene-music.d.ts

@@ -0,0 +1,4 @@
+import type { MusicId } from "./config";
+/** Scene route id -> optional track. Deployments can add tracks without changing scene code. */
+export declare const sceneMusicTracks: Record<string, MusicId>;
+export declare function musicForScene(sceneId: string | null | undefined): MusicId;

package/dist/scene-music.js

@@ -0,0 +1,8 @@
+/** Scene route id -> optional track. Deployments can add tracks without changing scene code. */
+export const sceneMusicTracks = {
+    "hq-home": "silent",
+    "hq-work": "silent",
+};
+export function musicForScene(sceneId) {
+    return sceneMusicTracks[sceneId ?? ""] ?? "silent";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/audio",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",