@juandinella/audio-bands 0.2.0 → 0.3.0

package/README.md

@@ -4,19 +4,17 @@
 
 **Demo**: [audio-bands.juandinella.com](https://audio-bands.juandinella.com)
 
-Headless audio frequency analysis for the browser. Get real-time `bass`, `mid`, and `high` values normalized to `0–1` from a music track, a microphone, or both at the same time. No renderer included.
+Headless audio analysis for the browser. Get normalized `bass`, `mid`, `high`, custom named bands, raw FFT bins, or mic waveform data without shipping a renderer.
 
 ```ts
 const { bass, mid, high } = audio.getBands();
-// bass: 0.73, mid: 0.41, high: 0.12
-
+const custom = audio.getCustomBands();
 const fft = audio.getFftData();
-// Uint8Array(128) — raw frequency bins, 0–255 each
 ```
 
 ## Why
 
-Every audio visualization library either handles only playback (no analysis) or draws its own canvas and hides the data. This one only gives you numbers.
+Most audio libraries either only play audio or immediately draw a canvas for you. This one stays lower level: it gives you usable analysis data and lets you decide how to render it.
 
 ## Install
 
@@ -24,87 +22,75 @@ Every audio visualization library either handles only playback (no analysis) or
 npm install @juandinella/audio-bands
 ```
 
-The root entrypoint is framework-agnostic. If you use the React hook, install `react` and import it from `@juandinella/audio-bands/react`.
+### Entry points
+
+- `@juandinella/audio-bands`: main framework-agnostic export
+- `@juandinella/audio-bands/core`: explicit core-only entry
+- `@juandinella/audio-bands/react`: React hook
+
+If you use the React hook, install `react` as well.
 
 ## Usage
 
 ### Vanilla JS
 
-Works in Vue, Svelte, plain HTML — anything.
-
-```js
+```ts
 import { AudioBands } from '@juandinella/audio-bands';
 
 const audio = new AudioBands({
-  onPlay: () => console.log('playing'),
-  onPause: () => console.log('paused'),
-  onError: () => console.error('failed to load'),
-  onMicStart: () => console.log('mic on'),
-  onMicStop: () => console.log('mic off'),
+  music: {
+    fftSize: 512,
+    smoothingTimeConstant: 0.7,
+  },
+  customBands: {
+    presence: { from: 0.25, to: 0.5 },
+    air: { from: 0.5, to: 1 },
+  },
+  onLoadError: (error) => console.error('track error', error),
+  onMicError: (error) => console.error('mic error', error),
 });
 
 await audio.load('/track.mp3');
 
-// Call inside your animation loop
 function loop() {
   const { bass, mid, high, overall } = audio.getBands();
-  // drive your canvas, SVG, CSS, WebGL — whatever
+  const custom = audio.getCustomBands();
+  const fft = audio.getFftData();
 
-  const fft = audio.getFftData(); // raw bins for spectrum visualizations
   requestAnimationFrame(loop);
 }
-requestAnimationFrame(loop);
 
-// Clean up when done
-audio.destroy();
+requestAnimationFrame(loop);
 ```
 
 ### React hook
 
 ```tsx
 import { useAudioBands } from '@juandinella/audio-bands/react';
-import { useEffect, useRef } from 'react';
 
 function Visualizer() {
-  const { loadTrack, togglePlayPause, toggleMic, getBands, isPlaying } =
-    useAudioBands();
-  const canvasRef = useRef<HTMLCanvasElement>(null);
-
-  useEffect(() => {
-    loadTrack('/track.mp3');
-  }, []);
-
-  useEffect(() => {
-    const canvas = canvasRef.current!;
-    const ctx = canvas.getContext('2d')!;
-    let raf: number;
-
-    function loop() {
-      const { bass, mid, high } = getBands();
-
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      ctx.beginPath();
-      ctx.arc(
-        canvas.width / 2,
-        canvas.height / 2,
-        20 + bass * 80,
-        0,
-        Math.PI * 2,
-      );
-      ctx.fill();
-
-      raf = requestAnimationFrame(loop);
-    }
-
-    raf = requestAnimationFrame(loop);
-    return () => cancelAnimationFrame(raf);
-  }, [getBands]);
+  const {
+    isPlaying,
+    hasTrack,
+    loadError,
+    micError,
+    loadTrack,
+    togglePlayPause,
+    toggleMic,
+    getBands,
+    getCustomBands,
+  } = useAudioBands({
+    customBands: {
+      presence: { from: 0.25, to: 0.5 },
+    },
+  });
 
   return (
     <>
-      <canvas ref={canvasRef} width={400} height={400} />
+      <button onClick={() => loadTrack('/track.mp3')}>load</button>
       <button onClick={togglePlayPause}>{isPlaying ? 'Pause' : 'Play'}</button>
       <button onClick={toggleMic}>Toggle mic</button>
+      <pre>{JSON.stringify({ hasTrack, loadError, micError, ...getBands(), ...getCustomBands() }, null, 2)}</pre>
     </>
   );
 }
@@ -113,93 +99,135 @@ function Visualizer() {
 ### Mic input
 
 ```ts
-// Enable mic — browser will ask for permission
 await audio.enableMic();
 
-// Get frequency bands from the mic
-const { bass } = audio.getBands('mic');
+const micBands = audio.getBands('mic');
+const micCustomBands = audio.getCustomBands('mic');
+const waveform = audio.getWaveform();
+```
 
-// Get raw waveform data (time-domain)
-const waveform = audio.getWaveform(); // Uint8Array | null
+## When To Use Bands Vs FFT
 
-// Disable mic and stop the stream
-audio.disableMic();
-```
+Use `getBands()` when you want stable, simple control signals:
+
+- pulsing a blob with low-end energy
+- scaling UI based on overall intensity
+- animating typography or CSS variables
+- driving scenes where three broad zones are enough
+
+Use `getCustomBands()` when the default bass/mid/high split is too coarse, but you still want named, high-level buckets:
+
+- separate `presence`, `air`, or `sub`
+- tune bands to your own design system or animation logic
+- keep your render code semantic instead of index-based
+
+Use `getFftData()` when you need bin-level detail:
+
+- bar visualizers
+- line spectrums
+- log interpolation
+- any renderer that maps directly over bins
+
+Rule of thumb:
+
+- `getBands()` for product UI
+- `getCustomBands()` for art direction
+- `getFftData()` for visualizers
 
 ## API
 
-### `AudioBands` (vanilla JS)
+### `AudioBands`
 
 ```ts
-new AudioBands(callbacks?: AudioBandsCallbacks)
+new AudioBands(options?: AudioBandsOptions)
 ```
 
-| Method                | Description                                                                                   |
-| --------------------- | --------------------------------------------------------------------------------------------- |
-| `load(url)`           | Load and play an audio file. Resolves when playback starts.                                   |
-| `togglePlayPause()`   | Toggle playback.                                                                              |
-| `enableMic()`         | Request mic access and start analysis.                                                        |
-| `disableMic()`        | Stop mic stream and clean up.                                                                 |
-| `getBands(source?)`   | Returns `Bands` for `'music'` (default) or `'mic'`. Call inside RAF.                          |
-| `getFftData(source?)` | Returns raw `Uint8Array` of frequency bins (0–255) for `'music'` or `'mic'`. Call inside RAF. |
-| `getWaveform()`       | Returns raw time-domain `Uint8Array` from mic. Call inside RAF.                               |
-| `destroy()`           | Stop playback, release mic, close AudioContext.                                               |
+#### Methods
 
-### `useAudioBands()` (React)
+| Method                  | Description |
+| ----------------------- | ----------- |
+| `load(url)`             | Load and play a track. Rejects with `AudioBandsError` on failure. |
+| `togglePlayPause()`     | Toggle the current track. |
+| `enableMic()`           | Request microphone access and start mic analysis. Rejects with `AudioBandsError` on failure. |
+| `disableMic()`          | Stop mic input and clean up the stream. |
+| `getBands(source?)`     | Returns normalized `{ bass, mid, high, overall }`. |
+| `getCustomBands(source?)` | Returns normalized values for configured custom bands. |
+| `getFftData(source?)`   | Returns raw `Uint8Array` frequency bins. |
+| `getWaveform()`         | Returns raw mic time-domain data. |
+| `getState()`            | Returns the current playback/mic/error state. |
+| `destroy()`             | Stop playback, release the mic and close the `AudioContext`. |
 
-Same capabilities as `AudioBands`. `destroy()` is called automatically on unmount.
+### `useAudioBands()`
 
 ```ts
 const {
   isPlaying,
   micActive,
+  hasTrack,
   audioError,
+  loadError,
+  micError,
+  state,
   loadTrack,
   togglePlayPause,
   toggleMic,
   getBands,
+  getCustomBands,
   getFftData,
   getWaveform,
-} = useAudioBands();
+} = useAudioBands(options);
 ```
 
-Import it from:
+### `AudioBandsOptions`
 
 ```ts
-import { useAudioBands } from '@juandinella/audio-bands/react';
-```
-
-### `Bands`
-
-```ts
-type Bands = {
-  bass: number; // 0–1 — low frequencies (0–8% of spectrum)
-  mid: number; // 0–1 — mid frequencies (8–40%)
-  high: number; // 0–1 — high frequencies (40–100%)
-  overall: number; // 0–1 — weighted mix: bass×0.5 + mid×0.3 + high×0.2
+type AudioBandsOptions = {
+  music?: {
+    fftSize?: number;
+    smoothingTimeConstant?: number;
+  };
+  mic?: {
+    fftSize?: number;
+    smoothingTimeConstant?: number;
+  };
+  bandRanges?: {
+    bass?: { from: number; to: number };
+    mid?: { from: number; to: number };
+    high?: { from: number; to: number };
+  };
+  customBands?: Record<string, { from: number; to: number }>;
+  onError?: (error: AudioBandsError) => void;
+  onLoadError?: (error: AudioBandsError) => void;
+  onMicError?: (error: AudioBandsError) => void;
+  onStateChange?: (state: AudioBandsState) => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onMicStart?: () => void;
+  onMicStop?: () => void;
 };
 ```
 
-### `AudioBandsCallbacks`
+### `AudioBandsState`
 
 ```ts
-type AudioBandsCallbacks = {
-  onPlay?: () => void;
-  onPause?: () => void;
-  onError?: (error?: unknown) => void;
-  onMicStart?: () => void;
-  onMicStop?: () => void;
+type AudioBandsState = {
+  isPlaying: boolean;
+  micActive: boolean;
+  hasTrack: boolean; // a track source is assigned, even if playback later fails
+  loadError: AudioBandsError | null;
+  micError: AudioBandsError | null;
 };
 ```
 
 ## Notes
 
-- `AudioContext` is created lazily on the first call to `load()` or `enableMic()`. Browsers require a user gesture before audio can start.
-- The root package export does not depend on React. The React hook lives at `@juandinella/audio-bands/react`.
-- The mic analyser is **not** connected to `AudioContext.destination`, so there is no feedback loop.
-- `getBands()`, `getFftData()`, and `getWaveform()` read live data from the audio graph. Call them inside `requestAnimationFrame`, not in response to React state.
-- `getFftData()` returns the same underlying buffer on every call. Copy it if you need to compare frames: `Array.from(fft)`.
-- `load()` and `enableMic()` reject on browser playback/permission errors. Use `try/catch` if you need custom handling.
+- `AudioContext` is created lazily on the first call to `load()` or `enableMic()`.
+- `hasTrack` means a track source is currently assigned to the instance. It can still be `true` if `play()` fails due to autoplay policy or another playback error.
+- The mic analyser is not connected to `AudioContext.destination`, so it will not feed back into the speakers.
+- `getBands()`, `getCustomBands()`, `getFftData()`, and `getWaveform()` read live data. Call them inside `requestAnimationFrame`, not from React state updates.
+- `getFftData()` returns the same underlying buffer on each call. Copy it if you need frame-to-frame comparisons.
+- `fftSize` must be a power of two between `32` and `32768`.
+- Band ranges are normalized from `0` to `1`, where `0` is the start of the analyser spectrum and `1` is the end.
 
 ## License
 

package/dist/chunk-UAMH5Y33.js

@@ -0,0 +1,344 @@
+// src/errors.ts
+var AudioBandsError = class extends Error {
+  constructor(kind, code, message, cause) {
+    super(message);
+    this.name = "AudioBandsError";
+    this.kind = kind;
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
+// src/core.ts
+var DEFAULT_MUSIC_ANALYSER = {
+  fftSize: 256,
+  smoothingTimeConstant: 0.85
+};
+var DEFAULT_MIC_ANALYSER = {
+  fftSize: 256,
+  smoothingTimeConstant: 0.8
+};
+var DEFAULT_CLASSIC_RANGES = {
+  bass: { from: 0, to: 0.08 },
+  mid: { from: 0.08, to: 0.4 },
+  high: { from: 0.4, to: 1 }
+};
+var ZERO = { bass: 0, mid: 0, high: 0, overall: 0 };
+function avg(arr, from, to) {
+  let sum = 0;
+  for (let i = from; i < to; i++) sum += arr[i];
+  return sum / (to - from);
+}
+function isPowerOfTwo(value) {
+  return (value & value - 1) === 0;
+}
+function normalizeAnalyserConfig(config, fallback) {
+  const fftSize = config?.fftSize ?? fallback.fftSize;
+  const smoothingTimeConstant = config?.smoothingTimeConstant ?? fallback.smoothingTimeConstant;
+  if (!Number.isInteger(fftSize) || fftSize < 32 || fftSize > 32768 || !isPowerOfTwo(fftSize)) {
+    throw new AudioBandsError(
+      "config",
+      "invalid_config",
+      "fftSize must be a power of two between 32 and 32768"
+    );
+  }
+  if (typeof smoothingTimeConstant !== "number" || smoothingTimeConstant < 0 || smoothingTimeConstant > 1) {
+    throw new AudioBandsError(
+      "config",
+      "invalid_config",
+      "smoothingTimeConstant must be between 0 and 1"
+    );
+  }
+  return { fftSize, smoothingTimeConstant };
+}
+function normalizeRange(name, range) {
+  const normalized = range ?? DEFAULT_CLASSIC_RANGES[name];
+  if (typeof normalized?.from !== "number" || typeof normalized?.to !== "number" || normalized.from < 0 || normalized.to > 1 || normalized.from >= normalized.to) {
+    throw new AudioBandsError(
+      "config",
+      "invalid_config",
+      `Band range "${name}" must satisfy 0 <= from < to <= 1`
+    );
+  }
+  return normalized;
+}
+function normalizeClassicRanges(ranges) {
+  return {
+    bass: normalizeRange("bass", ranges?.bass),
+    mid: normalizeRange("mid", ranges?.mid),
+    high: normalizeRange("high", ranges?.high)
+  };
+}
+function normalizeCustomBands(customBands) {
+  if (!customBands) return {};
+  return Object.fromEntries(
+    Object.entries(customBands).map(([name, range]) => [name, normalizeRange(name, range)])
+  );
+}
+function getIndexes(len, range) {
+  const from = Math.max(0, Math.min(len - 1, Math.floor(len * range.from)));
+  const to = Math.max(from + 1, Math.min(len, Math.floor(len * range.to)));
+  return [from, to];
+}
+function getRangeValue(data, range) {
+  const [from, to] = getIndexes(data.length, range);
+  return avg(data, from, to) / 255;
+}
+function fillFrequencyData(analyser, data) {
+  analyser.getByteFrequencyData(data);
+  return data;
+}
+function computeBands(data, ranges) {
+  const bass = getRangeValue(data, ranges.bass);
+  const mid = getRangeValue(data, ranges.mid);
+  const high = getRangeValue(data, ranges.high);
+  return {
+    bass,
+    mid,
+    high,
+    overall: bass * 0.5 + mid * 0.3 + high * 0.2
+  };
+}
+function computeCustomBands(data, ranges) {
+  return Object.fromEntries(
+    Object.entries(ranges).map(([name, range]) => [name, getRangeValue(data, range)])
+  );
+}
+function cloneState(state) {
+  return { ...state };
+}
+var AudioBands = class {
+  constructor(options = {}) {
+    this.state = {
+      isPlaying: false,
+      micActive: false,
+      hasTrack: false,
+      loadError: null,
+      micError: null
+    };
+    this.ctx = null;
+    this.musicAnalyser = null;
+    this.musicData = null;
+    this.micAnalyser = null;
+    this.micData = null;
+    this.micWaveformData = null;
+    this.audioEl = null;
+    this.musicSource = null;
+    this.micSource = null;
+    this.micStream = null;
+    this.destroyed = false;
+    this.options = options;
+    this.musicConfig = normalizeAnalyserConfig(options.music, DEFAULT_MUSIC_ANALYSER);
+    this.micConfig = normalizeAnalyserConfig(options.mic, DEFAULT_MIC_ANALYSER);
+    this.classicRanges = normalizeClassicRanges(options.bandRanges);
+    this.customBandRanges = normalizeCustomBands(options.customBands);
+  }
+  getState() {
+    return cloneState(this.state);
+  }
+  getCustomBands(source = "music") {
+    const data = this.readFrequencyData(source);
+    if (!data) return computeCustomBands(new Uint8Array(1), this.customBandRanges);
+    return computeCustomBands(data, this.customBandRanges);
+  }
+  async load(url) {
+    let ctx;
+    try {
+      ctx = this.ensureCtx();
+    } catch (error) {
+      throw this.handleError("load", error);
+    }
+    this.teardownMusic();
+    const audio = new Audio();
+    audio.crossOrigin = "anonymous";
+    audio.src = url;
+    audio.loop = true;
+    this.audioEl = audio;
+    this.setState({ hasTrack: true, loadError: null });
+    const source = ctx.createMediaElementSource(audio);
+    source.connect(this.musicAnalyser);
+    this.musicSource = source;
+    try {
+      await audio.play();
+      this.setState({ isPlaying: true, loadError: null });
+      this.options.onPlay?.();
+    } catch (error) {
+      throw this.handleError("load", error, "load_error");
+    }
+  }
+  togglePlayPause() {
+    const audio = this.audioEl;
+    if (!audio) return;
+    if (audio.paused) {
+      void audio.play().then(() => {
+        this.setState({ isPlaying: true, loadError: null });
+        this.options.onPlay?.();
+      }).catch((error) => {
+        this.handleError("load", error, "playback_error");
+      });
+      return;
+    }
+    audio.pause();
+    this.setState({ isPlaying: false });
+    this.options.onPause?.();
+  }
+  async enableMic() {
+    let ctx;
+    try {
+      ctx = this.ensureCtx();
+    } catch (error) {
+      throw this.handleError("mic", error);
+    }
+    if (this.micStream) return;
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: true,
+        video: false
+      });
+      this.micStream = stream;
+      const analyser = this.createAnalyser(ctx, this.micConfig);
+      this.micAnalyser = analyser;
+      this.micData = new Uint8Array(
+        analyser.frequencyBinCount
+      );
+      this.micWaveformData = new Uint8Array(
+        analyser.fftSize
+      );
+      const source = ctx.createMediaStreamSource(stream);
+      source.connect(analyser);
+      this.micSource = source;
+      this.setState({ micActive: true, micError: null });
+      this.options.onMicStart?.();
+    } catch (error) {
+      throw this.handleError("mic", error, "mic_error");
+    }
+  }
+  disableMic() {
+    const hadMic = Boolean(this.micStream || this.micSource || this.micAnalyser);
+    this.micStream?.getTracks().forEach((track) => track.stop());
+    this.micStream = null;
+    try {
+      this.micSource?.disconnect();
+    } catch {
+    }
+    this.micSource = null;
+    this.micAnalyser = null;
+    this.micData = null;
+    this.micWaveformData = null;
+    this.setState({ micActive: false });
+    if (hadMic) this.options.onMicStop?.();
+  }
+  getBands(source = "music") {
+    const data = this.readFrequencyData(source);
+    if (!data) return { ...ZERO };
+    return computeBands(data, this.classicRanges);
+  }
+  getFftData(source = "music") {
+    return this.readFrequencyData(source);
+  }
+  getWaveform() {
+    if (!this.micAnalyser || !this.micWaveformData) return null;
+    this.micAnalyser.getByteTimeDomainData(this.micWaveformData);
+    return this.micWaveformData;
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.teardownMusic();
+    this.disableMic();
+    void this.ctx?.close();
+    this.ctx = null;
+    this.musicAnalyser = null;
+    this.musicData = null;
+    this.setState({ isPlaying: false, micActive: false, hasTrack: false });
+    this.options = {};
+    this.destroyed = true;
+  }
+  readFrequencyData(source) {
+    if (source === "mic") {
+      if (!this.micAnalyser || !this.micData) return null;
+      return fillFrequencyData(this.micAnalyser, this.micData);
+    }
+    if (!this.musicAnalyser || !this.musicData) return null;
+    return fillFrequencyData(this.musicAnalyser, this.musicData);
+  }
+  ensureCtx() {
+    if (this.destroyed) {
+      throw new AudioBandsError(
+        "lifecycle",
+        "destroyed",
+        "This AudioBands instance was destroyed"
+      );
+    }
+    if (this.ctx) return this.ctx;
+    const Ctx = window.AudioContext || window.webkitAudioContext;
+    if (!Ctx) {
+      throw new AudioBandsError(
+        "lifecycle",
+        "unsupported_audio_context",
+        "AudioContext is not supported in this environment"
+      );
+    }
+    const ctx = new Ctx();
+    const analyser = this.createAnalyser(ctx, this.musicConfig);
+    analyser.connect(ctx.destination);
+    this.ctx = ctx;
+    this.musicAnalyser = analyser;
+    this.musicData = new Uint8Array(
+      analyser.frequencyBinCount
+    );
+    return ctx;
+  }
+  createAnalyser(ctx, config) {
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = config.fftSize;
+    analyser.smoothingTimeConstant = config.smoothingTimeConstant;
+    return analyser;
+  }
+  handleError(kind, error, fallbackCode = kind === "mic" ? "mic_error" : "load_error") {
+    const wrapped = error instanceof AudioBandsError ? error : new AudioBandsError(
+      kind,
+      fallbackCode,
+      kind === "mic" ? "Failed to access microphone input" : "Failed to load or play audio track",
+      error
+    );
+    if (kind === "load") {
+      this.setState({ isPlaying: false, loadError: wrapped });
+      this.options.onLoadError?.(wrapped);
+    } else {
+      this.setState({ micActive: false, micError: wrapped });
+      this.options.onMicError?.(wrapped);
+    }
+    this.options.onError?.(wrapped);
+    return wrapped;
+  }
+  setState(patch) {
+    let changed = false;
+    for (const [key, value] of Object.entries(patch)) {
+      if (this.state[key] !== value) {
+        this.state[key] = value;
+        changed = true;
+      }
+    }
+    if (changed) this.options.onStateChange?.(this.getState());
+  }
+  teardownMusic() {
+    this.audioEl?.pause();
+    if (this.audioEl) {
+      this.audioEl.src = "";
+      this.audioEl.load();
+    }
+    this.audioEl = null;
+    try {
+      this.musicSource?.disconnect();
+    } catch {
+    }
+    this.musicSource = null;
+    this.setState({ isPlaying: false, hasTrack: false });
+  }
+};
+
+export {
+  AudioBandsError,
+  AudioBands
+};
+//# sourceMappingURL=chunk-UAMH5Y33.js.map