Sound Hook

1"use client"
2 
3import { useCallback, useEffect, useRef, useState } from "react"
4 
5/**
6 * Cache storage for loaded audio buffers to prevent duplicate network requests and memory usage.
7 * Maps audio URL to its decoded AudioBuffer.
8 */
9const audioCache = new Map<
10  string,
11  {
12    buffer: AudioBuffer
13    loading: Promise<AudioBuffer>
14  } | null
15>()
16 
17/**
18 * Shared AudioContext instance to avoid creating multiple contexts.
19 * Multiple AudioContexts can cause performance issues and resource exhaustion.
20 */
21let sharedAudioContext: AudioContext | null = null
22 
23/**
24 * Gets or creates a shared AudioContext instance.
25 */
26function getAudioContext(): AudioContext | null {
27  if (sharedAudioContext) return sharedAudioContext
28 
29  const AudioContextClass =
30    window.AudioContext ||
31    (window as unknown as { webkitAudioContext: typeof AudioContext })
32      .webkitAudioContext
33 
34  if (!AudioContextClass) {
35    console.warn("Web Audio API is not supported in this browser.")
36    return null
37  }
38 
39  sharedAudioContext = new AudioContextClass()
40  return sharedAudioContext
41}
42 
43/**
44 * Custom React hook to load and play a sound from a given URL using the Web Audio API.
45 *
46 * This hook implements caching to prevent duplicate network requests and memory usage
47 * when the same audio file is used across multiple components.
48 *
49 * @param url - The URL of the audio file to load and play.
50 * @returns A function that, when called, plays the loaded sound.
51 *
52 * @remarks
53 * - Audio buffers are cached globally, so the same file is only loaded once
54 * - Uses a shared AudioContext to avoid resource exhaustion
55 * - If the Web Audio API is not supported in the browser, a warning is logged and playback is disabled
56 * - Errors during fetching or decoding the audio are logged to the console
57 *
58 * @example
59 * ```tsx
60 * const playClick = useSound('/sounds/click.mp3');
61 * // Later in an event handler:
62 * playClick();
63 * ```
64 */
65export function useSound(url: string) {
66  const audioCtxRef = useRef<AudioContext | null>(null)
67  const bufferRef = useRef<AudioBuffer | null>(null)
68 
69  useEffect(() => {
70    const audioCtx = getAudioContext()
71    if (!audioCtx) return
72 
73    audioCtxRef.current = audioCtx
74 
75    // Check if already cached
76    const cached = audioCache.get(url)
77    if (cached?.buffer) {
78      bufferRef.current = cached.buffer
79      return
80    }
81 
82    // Check if already loading
83    if (cached?.loading) {
84      cached.loading
85        .then((decoded) => {
86          bufferRef.current = decoded
87        })
88// … truncated