@lucaismyname/ginger 0.0.30 → 0.0.31

package/README.md

@@ -64,8 +64,47 @@ Mount **`<Ginger.Player />`** once inside the same provider tree so the hidden a
 - `@lucaismyname/ginger/client`
 - `@lucaismyname/ginger/testing`
 - `@lucaismyname/ginger/waveform`
+- `@lucaismyname/ginger/equalizer`
 - `@lucaismyname/ginger/experimental-gapless`
 
+### Equalizer
+
+```tsx
+import { useGingerEqualizer } from "@lucaismyname/ginger/equalizer";
+
+function MyPlayer() {
+  const { setBandGain, bands, error } = useGingerEqualizer({
+    bands: [
+      { frequency: 60 },
+      { frequency: 250 },
+      { frequency: 1000 },
+      { frequency: 4000 },
+      { frequency: 16000 },
+    ],
+  });
+
+  return (
+    <div>
+      {bands.map((band, i) => (
+        <input
+          key={band.frequency}
+          type="range"
+          min={-12}
+          max={12}
+          step={0.5}
+          defaultValue={0}
+          onChange={(e) => setBandGain(i, Number(e.target.value))}
+          aria-label={`${band.frequency} Hz`}
+        />
+      ))}
+      {error && <p>{error}</p>}
+    </div>
+  );
+}
+```
+
+The EQ and `useGingerLiveAnalyzer` share the same `AudioContext` and can be used together. EQ filters are inserted before the analyser in the Web Audio graph.
+
 ### Experimental Notice
 
 `@lucaismyname/ginger/experimental-gapless` is intentionally non-production.
@@ -734,15 +773,15 @@ Example:
 
 - **Headless control bindings** (bind to your own components): **`useSeekBarBinding()`**, **`useVolumeSlider()`**, **`usePlayPauseBinding({ playAriaLabel?, pauseAriaLabel? })`**. Each returns props such as `value`, `min`, `max`, handlers, and `ariaLabel` / `ariaValueText` where relevant.
 
-- **Advanced hooks** — **`useGingerKeyboardShortcuts()`**, **`useGingerSleepTimer()`**, **`useSeekDrag()`**, **`useNextTrackPrefetch()`**, **`useGingerChapters()`**, **`useGingerLyricsSync()`**, and **`useGingerDebugLog()`** are available for custom UX and diagnostics.
+- **Advanced hooks** — **`useGingerKeyboardShortcuts()`**, **`useGingerSleepTimer()`**, **`useSeekDrag()`**, **`useNextTrackPrefetch()`**, **`useGingerChapters()`**, **`useGingerChapterProgress()`**, **`useGingerLyricsSync()`**, **`useGingerDebugLog()`**, **`useGingerPlaybackHistory()`**, **`useGingerVolumeFade()`** are available for custom UX and diagnostics.
 
 - **Locale** — Pass **`locale={partialMessages}`** on `Ginger.Provider` (type **`GingerLocaleMessages`**) to translate built-in control strings, chapter list labels, and synced lyrics list names; **`useGingerLocale()`** reads the merged messages anywhere under the provider.
 
-- **Track extras** — Optional **`metadata?: Record<string, unknown>`** on **`Track`** (and on **`PlaylistMeta`**) is ignored by core logic; use it for badges, flags, or UI-only fields.
+- **Track extras** — Optional **`metadata?: Record<string, unknown>`** on **`Track`** (and on **`PlaylistMeta`**) is ignored by core logic; use it for badges, flags, or UI-only fields. Chapter entries and timed lyric lines are now typed as the named exports **`TrackChapter`** and **`TrackLyricLine`** respectively.
 
 - **Buffered UI** — **`Ginger.Current.BufferRail`** shows load progress; **`Ginger.Current.TimeRail`** supports **`showBuffered`** to stack a buffered layer behind the played segment.
 
-- **Audio analyzers** — Live Web Audio data for real-time visuals (**`useGingerLiveAnalyzer`**, main package) and whole-file grids for waveforms or spectrograms (**`useAudioFileAnalysis`** / **`analyzeAudioFile`**, `@lucaismyname/ginger/waveform`). See [Audio analyzers (visualizations)](#audio-analyzers-visualizations).
+- **Audio analyzers** — Live Web Audio data for real-time visuals (**`useGingerLiveAnalyzer`**, main package), parametric EQ (**`useGingerEqualizer`**, `@lucaismyname/ginger/equalizer`), and whole-file grids for waveforms or spectrograms (**`useAudioFileAnalysis`** / **`analyzeAudioFile`**, `@lucaismyname/ginger/waveform`). See [Audio analyzers (visualizations)](#audio-analyzers-visualizations).
 
 Recipes below cover queue lifecycle and media edge cases.
 
@@ -787,7 +826,12 @@ Important:
 - **CORS** — For cross-origin `fileUrl` values, set **`crossOrigin`** on **`Ginger.Player`** (for example `"anonymous"`) so the media element is usable with **`AudioContext`**.
 - **One `MediaElementAudioSourceNode` per `<audio>`** — The library reuses a single Web Audio graph per underlying element. Multiple instances of **`useGingerLiveAnalyzer`** attach extra **`AnalyserNode`**s as taps; only one tap carries audio to **`destination`** so volume stays correct.
 - **Autoplay** — The **`AudioContext`** may start **`suspended`** until a user gesture; call **`resume()`** or start playback after interaction.
-- **Reading buffers** — `frequencyData` and `timeDomainData` are updated each animation frame while enabled; read them during render after **`frequencyBinCount > 0`** (they are backed by mutable buffers that the hook fills in a `requestAnimationFrame` loop).
+- **Reading buffers** — `frequencyData` and `timeDomainData` are updated each animation frame while enabled; read them during render after **`frequencyBinCount > 0`** (they are backed by mutable buffers that the hook fills in a `requestAnimationFrame` loop). Because the array _reference_ never changes, use the returned **`frame`** counter as a `useMemo` / `useEffect` dependency to react to new data:
+
+  ```ts
+  const { frequencyData, frame } = useGingerLiveAnalyzer();
+  const peak = useMemo(() => Math.max(...frequencyData), [frame]);
+  ```
 
 ### Whole file: `@lucaismyname/ginger/waveform`
 
@@ -864,15 +908,18 @@ import { useGingerKeyboardShortcuts } from "@lucaismyname/ginger";
 function Hotkeys() {
   useGingerKeyboardShortcuts(true, {
     playPause: " ",
-    next: "ArrowRight",
-    previous: "ArrowLeft",
+    next: "n",
+    previous: "p",
     mute: "m",
+    seekForward: "ArrowRight",
+    seekBackward: "ArrowLeft",
+    seekSeconds: 5,
   });
   return null;
 }
 ```
 
-`mute` is optional; if omitted, no mute key binding is installed.
+`mute`, `seekForward`, and `seekBackward` are all optional; keys are lower-cased before comparison. `seekSeconds` defaults to `5` when seek bindings are set.
 
 ### Chapters and synced lyrics
 
@@ -918,6 +965,76 @@ export function App() {
 
 The hook preloads the **logical** next track (same rules as the Next button) using a detached `HTMLAudioElement` with `preload="auto"`. Pass **`crossOrigin`** when it matches **`Ginger.Player`** for cross-origin URLs.
 
+### Playback history
+
+```tsx
+import { useGingerPlaybackHistory } from "@lucaismyname/ginger";
+
+function RecentTracks() {
+  const { history, clearHistory } = useGingerPlaybackHistory({ maxLength: 20 });
+  return (
+    <ul>
+      {history.map((entry, i) => (
+        <li key={i}>{entry.track.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Records every track change in chronological order (most recent last). Useful for displaying play history or implementing "smart previous" in shuffle mode. History lives in component state and is reset on remount.
+
+### Volume fade
+
+```tsx
+import { useGingerVolumeFade } from "@lucaismyname/ginger";
+
+function FadeButton() {
+  const { fadeVolumeTo, cancelFade, isFading } = useGingerVolumeFade();
+  return (
+    <button
+      onClick={() => fadeVolumeTo({ targetVolume: 0, durationMs: 1500, onComplete: pause })}
+      disabled={isFading}
+    >
+      Fade out
+    </button>
+  );
+}
+```
+
+Smoothly interpolates volume over a given duration using `requestAnimationFrame`. Call `cancelFade()` to hold at the current level.
+
+### Chapter progress
+
+```tsx
+import { useGingerChapterProgress } from "@lucaismyname/ginger";
+
+function ChapterBar() {
+  const { progress, elapsed, remaining } = useGingerChapterProgress();
+  return <progress value={progress} max={1} />;
+}
+```
+
+Returns `progress` (0–1 fraction through the active chapter), `elapsed` (seconds into it), and `remaining` (seconds until the next chapter or track end). Complements `useGingerChapters` for chapter scrubber UIs.
+
+### Framework-agnostic store
+
+```ts
+import { createGingerStore } from "@lucaismyname/ginger";
+
+const store = createGingerStore({ tracks: myTracks });
+
+const unsub = store.subscribe((state) => {
+  console.log("current track index:", state.currentIndex);
+});
+
+store.dispatch({ type: "NEXT" });
+store.init({ tracks: newTracks });
+unsub();
+```
+
+A pure-JS store wrapping `gingerReducer` with `getState`, `dispatch`, `subscribe`, and `init`. No React required — usable in Svelte, Vue, Node.js testing environments, or server-side rendering.
+
 ### Sleep timer and drag seek
 
 ```tsx
@@ -930,6 +1047,8 @@ function Extras({ duration }: { duration: number }) {
 }
 ```
 
+When `respectPause` is `true` (default), pausing stops the countdown and elapsed time is preserved across pause/resume cycles — the timer picks up where it left off rather than restarting from the full duration.
+
 ### Persistence + resume
 
 `Ginger.Provider` accepts:
@@ -938,7 +1057,20 @@ function Extras({ duration }: { duration: number }) {
 - `hydrateOnMount?: boolean`
 - `resumeOnTrackChange?: boolean`
 
-This allows persisted volume/rate/repeat/index and optional per-track resume positions.
+This allows persisted volume/rate/repeat/index and optional per-track resume positions. Errors thrown by the adapter are caught and logged as dev-mode warnings so a storage quota error never crashes the player.
+
+### Provider event callbacks
+
+New callbacks available on `Ginger.Provider`:
+
+- `onVolumeChange?: (volume: number, muted: boolean) => void` — fired when volume or mute state changes
+- `onPlaybackRateChange?: (rate: number) => void` — fired when playback speed changes
+- `onSeek?: (timeSeconds: number) => void` — fired on any `seek()` call
+
+### Provider layout props
+
+- `dir?: "ltr" | "rtl" | "auto"` — explicit layout direction; takes priority over the automatic RTL heuristic derived from locale strings
+- `prevRestartThresholdSeconds?: number` — pressing previous restarts the current track when `currentTime > threshold` (default `3`); set to `0` to always skip to the previous track
 
 ### Queue mutation actions and single-track mode
 

package/dist/analyzer/liveAudioGraph.d.ts

@@ -1,4 +1,8 @@
-/** One MediaElementAudioSourceNode per HTMLAudioElement; multiple AnalyserNodes may tap the source. */
+/**
+ * One MediaElementAudioSourceNode per HTMLAudioElement; multiple AnalyserNodes may tap the source.
+ * An optional processing chain (e.g. EQ filters) can be inserted between the source and the
+ * analysers via `setProcessingChain`.
+ */
 export type LiveAnalyserOptions = {
     fftSize: number;
     smoothingTimeConstant: number;
@@ -11,4 +15,13 @@ export declare function attachLiveAnalyser(element: HTMLAudioElement, options: L
     analyser: AnalyserNode;
 };
 export declare function detachLiveAnalyser(element: HTMLAudioElement, id: number): void;
+/**
+ * Insert an ordered processing chain (e.g. BiquadFilterNode[]) between the audio source and the
+ * analyser consumers. Pass an empty array to clear the chain.
+ *
+ * Safe to call while analyser consumers are active; the graph is rebuilt immediately.
+ * Note: because `createMediaElementSource` can only be called once per element, the EQ and live
+ * analyser share the same AudioContext. Calling both for the same element is supported.
+ */
+export declare function setProcessingChain(element: HTMLAudioElement, nodes: AudioNode[]): void;
 //# sourceMappingURL=liveAudioGraph.d.ts.map

package/dist/analyzer/liveAudioGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"liveAudioGraph.d.ts","sourceRoot":"","sources":["../../src/analyzer/liveAudioGraph.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAsBF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,mBAAmB,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAkC/D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CA6B9E"}
+{"version":3,"file":"liveAudioGraph.d.ts","sourceRoot":"","sources":["../../src/analyzer/liveAudioGraph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA2HF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,mBAAmB,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAiB/D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAoB9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAoBtF"}

package/dist/analyzer/useGingerLiveAnalyzer.d.ts

@@ -16,6 +16,12 @@ export type UseGingerLiveAnalyzerResult = {
     isSuspended: boolean;
     error: string | null;
     resume: () => Promise<void>;
+    /**
+     * Monotonically increasing counter incremented each animation frame.
+     * Use as a `useMemo` / `useEffect` dependency to respond to new audio data, since
+     * `frequencyData` and `timeDomainData` are mutated in-place (their reference never changes).
+     */
+    frame: number;
 };
 export declare function useGingerLiveAnalyzer(options?: UseGingerLiveAnalyzerOptions): UseGingerLiveAnalyzerResult;
 //# sourceMappingURL=useGingerLiveAnalyzer.d.ts.map

package/dist/analyzer/useGingerLiveAnalyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGingerLiveAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/useGingerLiveAnalyzer.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,4BAA4B,GAAG;IACzC,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,kHAAkH;IAClH,aAAa,EAAE,UAAU,CAAC;IAC1B,8DAA8D;IAC9D,cAAc,EAAE,UAAU,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAKF,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAkK7B"}
+{"version":3,"file":"useGingerLiveAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/useGingerLiveAnalyzer.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,4BAA4B,GAAG;IACzC,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,kHAAkH;IAClH,aAAa,EAAE,UAAU,CAAC;IAC1B,8DAA8D;IAC9D,cAAc,EAAE,UAAU,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAKF,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAiK7B"}

package/dist/client.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./ginger-YDZhJqet.cjs"),r=require("./useNextTrackPrefetch-pBFiWDyx.cjs"),a=require("./GingerSplitContexts-C7puo0M7.cjs");exports.Chapters=e.Chapters;exports.Ginger=e.Ginger;exports.LyricsSynced=e.LyricsSynced;exports.Pause=e.Pause;exports.Play=e.Play;exports.RepeatGlyph=e.RepeatGlyph;exports.ShuffleIcon=e.ShuffleIcon;exports.SkipBack=e.SkipBack;exports.SkipForward=e.SkipForward;exports.Volume2=e.Volume2;exports.VolumeX=e.VolumeX;exports.Wrapper=e.Wrapper;exports.clampPlaybackRate=e.clampPlaybackRate;exports.clampVolume=e.clampVolume;exports.defaultGingerLocale=e.defaultGingerLocale;exports.derivePlaybackUiState=e.derivePlaybackUiState;exports.parseLrc=e.parseLrc;exports.useGingerChapters=e.useGingerChapters;exports.useGingerLocale=e.useGingerLocale;exports.useGingerLyricsSync=e.useGingerLyricsSync;exports.usePlayPauseBinding=e.usePlayPauseBinding;exports.useSeekBarBinding=e.useSeekBarBinding;exports.useVolumeSlider=e.useVolumeSlider;exports.attachLiveAnalyser=r.attachLiveAnalyser;exports.detachLiveAnalyser=r.detachLiveAnalyser;exports.useGinger=r.useGinger;exports.useGingerDebugLog=r.useGingerDebugLog;exports.useGingerKeyboardShortcuts=r.useGingerKeyboardShortcuts;exports.useGingerLiveAnalyzer=r.useGingerLiveAnalyzer;exports.useGingerSleepTimer=r.useGingerSleepTimer;exports.useNextTrackPrefetch=r.useNextTrackPrefetch;exports.useSeekDrag=r.useSeekDrag;exports.gingerStateFromContextValues=a.gingerStateFromContextValues;exports.gingerStateFromContexts=a.gingerStateFromContexts;exports.useGingerMedia=a.useGingerMedia;exports.useGingerPlayback=a.useGingerPlayback;exports.useGingerState=a.useGingerState;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./ginger-NEcOSSJD.cjs"),i=require("./liveAudioGraph-D1BXMv_u.cjs"),r=require("./useGingerChapterProgress-BOqUimE7.cjs"),s=require("./selectors-YXnP8Y8g.cjs"),a=require("./GingerSplitContexts-C7puo0M7.cjs");exports.Chapters=e.Chapters;exports.Ginger=e.Ginger;exports.LyricsSynced=e.LyricsSynced;exports.Pause=e.Pause;exports.Play=e.Play;exports.RepeatGlyph=e.RepeatGlyph;exports.ShuffleIcon=e.ShuffleIcon;exports.SkipBack=e.SkipBack;exports.SkipForward=e.SkipForward;exports.Volume2=e.Volume2;exports.VolumeX=e.VolumeX;exports.Wrapper=e.Wrapper;exports.clampPlaybackRate=e.clampPlaybackRate;exports.clampVolume=e.clampVolume;exports.defaultGingerLocale=e.defaultGingerLocale;exports.parseLrc=e.parseLrc;exports.useGingerChapters=e.useGingerChapters;exports.useGingerLocale=e.useGingerLocale;exports.useGingerLyricsSync=e.useGingerLyricsSync;exports.usePlayPauseBinding=e.usePlayPauseBinding;exports.useSeekBarBinding=e.useSeekBarBinding;exports.useVolumeSlider=e.useVolumeSlider;exports.attachLiveAnalyser=i.attachLiveAnalyser;exports.detachLiveAnalyser=i.detachLiveAnalyser;exports.setProcessingChain=i.setProcessingChain;exports.useGinger=i.useGinger;exports.createGingerStore=r.createGingerStore;exports.useGingerChapterProgress=r.useGingerChapterProgress;exports.useGingerDebugLog=r.useGingerDebugLog;exports.useGingerKeyboardShortcuts=r.useGingerKeyboardShortcuts;exports.useGingerLiveAnalyzer=r.useGingerLiveAnalyzer;exports.useGingerPlaybackHistory=r.useGingerPlaybackHistory;exports.useGingerSleepTimer=r.useGingerSleepTimer;exports.useGingerVolumeFade=r.useGingerVolumeFade;exports.useNextTrackPrefetch=r.useNextTrackPrefetch;exports.useSeekDrag=r.useSeekDrag;exports.derivePlaybackUiState=s.derivePlaybackUiState;exports.gingerStateFromContextValues=a.gingerStateFromContextValues;exports.gingerStateFromContexts=a.gingerStateFromContexts;exports.useGingerMedia=a.useGingerMedia;exports.useGingerPlayback=a.useGingerPlayback;exports.useGingerState=a.useGingerState;
 //# sourceMappingURL=client.cjs.map

package/dist/client.js

@@ -1,43 +1,50 @@
-import { C as s, G as r, L as i, P as u, a as n, R as t, S as g, b as l, c, V as o, d as p, W as G, e as S, f as y, g as m, h as d, p as h, u as k, i as L, j as f, k as P, l as b, m as x } from "./ginger-DYlsaFGA.js";
-import { a as C, d as v, u as B, b as A, c as F, e as R, f as D, g as T, h as W } from "./useNextTrackPrefetch-BZdly__j.js";
-import { g as w, a as z, u as I, b as K, c as M } from "./GingerSplitContexts-BzBExb95.js";
+import { C as s, G as r, L as i, P as u, a as t, R as n, S as g, b as o, c, V as l, d as p, W as G, e as y, f as S, g as d, p as m, u as h, h as P, i as f, j as k, k as L, l as b } from "./ginger-L2ZFgzH4.js";
+import { a as C, d as V, s as v, u as B } from "./liveAudioGraph-CmEsdLgZ.js";
+import { c as A, u as R, a as D, b as T, d as W, e as j, f as w, g as z, h as H, i as I } from "./useGingerChapterProgress-DLYdGytK.js";
+import { d as M } from "./selectors-BalBCc7X.js";
+import { g as U, a as X, u as q, b as E, c as J } from "./GingerSplitContexts-BzBExb95.js";
 export {
   s as Chapters,
   r as Ginger,
   i as LyricsSynced,
   u as Pause,
-  n as Play,
-  t as RepeatGlyph,
+  t as Play,
+  n as RepeatGlyph,
   g as ShuffleIcon,
-  l as SkipBack,
+  o as SkipBack,
   c as SkipForward,
-  o as Volume2,
+  l as Volume2,
   p as VolumeX,
   G as Wrapper,
   C as attachLiveAnalyser,
-  S as clampPlaybackRate,
-  y as clampVolume,
-  m as defaultGingerLocale,
-  d as derivePlaybackUiState,
-  v as detachLiveAnalyser,
-  w as gingerStateFromContextValues,
-  z as gingerStateFromContexts,
-  h as parseLrc,
+  y as clampPlaybackRate,
+  S as clampVolume,
+  A as createGingerStore,
+  d as defaultGingerLocale,
+  M as derivePlaybackUiState,
+  V as detachLiveAnalyser,
+  U as gingerStateFromContextValues,
+  X as gingerStateFromContexts,
+  m as parseLrc,
+  v as setProcessingChain,
   B as useGinger,
-  k as useGingerChapters,
-  A as useGingerDebugLog,
-  F as useGingerKeyboardShortcuts,
-  R as useGingerLiveAnalyzer,
-  L as useGingerLocale,
+  R as useGingerChapterProgress,
+  h as useGingerChapters,
+  D as useGingerDebugLog,
+  T as useGingerKeyboardShortcuts,
+  W as useGingerLiveAnalyzer,
+  P as useGingerLocale,
   f as useGingerLyricsSync,
-  I as useGingerMedia,
-  K as useGingerPlayback,
-  D as useGingerSleepTimer,
-  M as useGingerState,
-  T as useNextTrackPrefetch,
-  P as usePlayPauseBinding,
-  b as useSeekBarBinding,
-  W as useSeekDrag,
-  x as useVolumeSlider
+  q as useGingerMedia,
+  E as useGingerPlayback,
+  j as useGingerPlaybackHistory,
+  w as useGingerSleepTimer,
+  J as useGingerState,
+  z as useGingerVolumeFade,
+  H as useNextTrackPrefetch,
+  k as usePlayPauseBinding,
+  L as useSeekBarBinding,
+  I as useSeekDrag,
+  b as useVolumeSlider
 };
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}
+{"version":3,"file":"client.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/context/GingerProvider.d.ts

@@ -1,3 +1,3 @@
 import { GingerProviderProps } from '../types';
-export declare function GingerProvider({ children, initialTracks, initialIndex, initialPlaylistMeta, initialShuffle, initialRepeatMode, initialPlaybackMode, initialPaused, initialVolume, initialMuted, initialPlaybackRate, initialStateKey, locale, mediaSession, beforePlay, onPlayBlocked, persistence, hydrateOnMount, resumeOnTrackChange, unstyled, asChild, className, style, onTrackChange, onPlay, onPause, onQueueEnd, onError, }: GingerProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function GingerProvider({ children, initialTracks, initialIndex, initialPlaylistMeta, initialShuffle, initialRepeatMode, initialPlaybackMode, initialPaused, initialVolume, initialMuted, initialPlaybackRate, initialStateKey, locale, mediaSession, beforePlay, onPlayBlocked, persistence, hydrateOnMount, resumeOnTrackChange, unstyled, asChild, className, style, dir: dirProp, prevRestartThresholdSeconds, onTrackChange, onPlay, onPause, onQueueEnd, onError, onVolumeChange, onPlaybackRateChange, onSeek, }: GingerProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=GingerProvider.d.ts.map

package/dist/context/GingerProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GingerProvider.d.ts","sourceRoot":"","sources":["../../src/context/GingerProvider.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,mBAAmB,EAKpB,MAAM,UAAU,CAAC;AAuBlB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,aAAkB,EAClB,YAAgB,EAChB,mBAA0B,EAC1B,cAAsB,EACtB,iBAAyB,EACzB,mBAAgC,EAChC,aAAoB,EACpB,aAAiB,EACjB,YAAoB,EACpB,mBAAuB,EACvB,eAAe,EACf,MAAM,EACN,YAAoB,EACpB,UAAU,EACV,aAAa,EACb,WAAW,EACX,cAAsB,EACtB,mBAA2B,EAC3B,QAAgB,EAChB,OAAe,EACf,SAAS,EACT,KAAK,EACL,aAAa,EACb,MAAM,EACN,OAAO,EACP,UAAU,EACV,OAAO,GACR,EAAE,mBAAmB,2CAqiBrB"}
+{"version":3,"file":"GingerProvider.d.ts","sourceRoot":"","sources":["../../src/context/GingerProvider.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,mBAAmB,EAKpB,MAAM,UAAU,CAAC;AAuBlB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,aAAkB,EAClB,YAAgB,EAChB,mBAA0B,EAC1B,cAAsB,EACtB,iBAAyB,EACzB,mBAAgC,EAChC,aAAoB,EACpB,aAAiB,EACjB,YAAoB,EACpB,mBAAuB,EACvB,eAAe,EACf,MAAM,EACN,YAAoB,EACpB,UAAU,EACV,aAAa,EACb,WAAW,EACX,cAAsB,EACtB,mBAA2B,EAC3B,QAAgB,EAChB,OAAe,EACf,SAAS,EACT,KAAK,EACL,GAAG,EAAE,OAAO,EACZ,2BAA+B,EAC/B,aAAa,EACb,MAAM,EACN,OAAO,EACP,UAAU,EACV,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,MAAM,GACP,EAAE,mBAAmB,2CAsmBrB"}

package/dist/core/playbackReducer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playbackReducer.d.ts","sourceRoot":"","sources":["../../src/core/playbackReducer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAY7E,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnD;AAkBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,WAAW,CA0Bd;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,CA2OnF"}
+{"version":3,"file":"playbackReducer.d.ts","sourceRoot":"","sources":["../../src/core/playbackReducer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAY7E,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnD;AAkBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,WAAW,CA0Bd;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,CAiQnF"}

package/dist/equalizer/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react"),c=require("../liveAudioGraph-D1BXMv_u.cjs"),B=[{frequency:60},{frequency:250},{frequency:1e3},{frequency:4e3},{frequency:16e3}];function C(q={}){const{enabled:d=!0,bands:m=B}=q,{audioRef:o,state:h}=c.useGinger(),[l,g]=s.useState(m),[p,y]=s.useState(null),a=s.useRef([]);s.useEffect(()=>{const e=o.current;if(!(!e||typeof window>"u")){if(!d){c.setProcessingChain(e,[]),a.current=[];return}try{const t=c.attachLiveAnalyser(e,{fftSize:32,smoothingTimeConstant:0,minDecibels:-100,maxDecibels:0}),{context:n,id:f}=t,i=l.map(r=>{const u=n.createBiquadFilter();return u.type=r.type??"peaking",u.frequency.value=r.frequency,u.gain.value=r.gain??0,u.Q.value=r.q??1,u});a.current=i,c.setProcessingChain(e,i),c.detachLiveAnalyser(e,f),y(null)}catch(t){const n=t instanceof Error?t.message:"Failed to create equalizer";y(n),a.current=[]}return()=>{const t=o.current;t&&c.setProcessingChain(t,[]),a.current=[]}}},[d,l,o,h.currentIndex]);const v=s.useCallback((e,t)=>{const n=a.current[e];n&&(n.gain.value=t),g(f=>f.map((i,r)=>r===e?{...i,gain:t}:i))},[]),S=s.useCallback(e=>{g(e)},[]);return{setBandGain:v,setBands:S,bands:l,error:p}}exports.useGingerEqualizer=C;
+//# sourceMappingURL=index.cjs.map

package/dist/equalizer/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../src/equalizer/useGingerEqualizer.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n  attachLiveAnalyser,\n  detachLiveAnalyser,\n  setProcessingChain,\n} from \"../analyzer/liveAudioGraph\";\nimport { useGinger } from \"../hooks/useGinger\";\n\nexport type EqualizerBand = {\n  /** Center frequency in Hz (e.g. 60, 250, 1000, 4000, 16000). */\n  frequency: number;\n  /** Gain in dB. Positive = boost, negative = cut. Typical range: -12 to +12. Default: 0. */\n  gain?: number;\n  /** Q factor (bandwidth). Higher = narrower. Default: 1. */\n  q?: number;\n  /** BiquadFilterNode type. Default: \"peaking\". */\n  type?: BiquadFilterType;\n};\n\nexport type UseGingerEqualizerOptions = {\n  /** When false, EQ nodes are detached and the audio path is bypassed. Default: true. */\n  enabled?: boolean;\n  /** Band definitions. Each band maps to one BiquadFilterNode. */\n  bands?: EqualizerBand[];\n};\n\nexport type UseGingerEqualizerResult = {\n  /** Update a single band's gain in dB without rebuilding the filter chain. */\n  setBandGain: (bandIndex: number, gainDb: number) => void;\n  /** Replace all bands (rebuilds the filter chain). */\n  setBands: (bands: EqualizerBand[]) => void;\n  /** Current band definitions (reflects the latest `setBands` call). */\n  bands: EqualizerBand[];\n  /** Error string if Web Audio is unavailable or filter creation failed. */\n  error: string | null;\n};\n\nconst DEFAULT_BANDS: EqualizerBand[] = [\n  { frequency: 60 },\n  { frequency: 250 },\n  { frequency: 1000 },\n  { frequency: 4000 },\n  { frequency: 16000 },\n];\n\n/**\n * Inserts a parametric EQ into the Web Audio graph for the active Ginger media element.\n *\n * Each band is a `BiquadFilterNode` connected in series between the audio source and the\n * speakers. If `useGingerLiveAnalyzer` is also active, the EQ is inserted before the analyser\n * — both share the same `AudioContext` (the browser allows only one `MediaElementAudioSourceNode`\n * per element).\n *\n * Available as a subpath export:\n * ```ts\n * import { useGingerEqualizer } from \"@lucaismyname/ginger/equalizer\";\n * ```\n */\nexport function useGingerEqualizer(\n  options: UseGingerEqualizerOptions = {},\n): UseGingerEqualizerResult {\n  const { enabled = true, bands: initialBands = DEFAULT_BANDS } = options;\n  const { audioRef, state } = useGinger();\n\n  const [bands, setBandsState] = useState<EqualizerBand[]>(initialBands);\n  const [error, setError] = useState<string | null>(null);\n\n  const filterNodesRef = useRef<BiquadFilterNode[]>([]);\n\n  useEffect(() => {\n    const el = audioRef.current;\n    if (!el || typeof window === \"undefined\") {\n      return;\n    }\n\n    if (!enabled) {\n      setProcessingChain(el, []);\n      filterNodesRef.current = [];\n      return;\n    }\n\n    try {\n      // Attach a temporary analyser solely to get (or create) the shared AudioContext.\n      // The graph is rebuilt by liveAudioGraph after we call setProcessingChain, so this\n      // temporary consumer is detached immediately after we have the context reference.\n      const attached = attachLiveAnalyser(el, {\n        fftSize: 32,\n        smoothingTimeConstant: 0,\n        minDecibels: -100,\n        maxDecibels: 0,\n      });\n      const { context, id: tempId } = attached;\n\n      const filters: BiquadFilterNode[] = bands.map((band) => {\n        const node = context.createBiquadFilter();\n        node.type = band.type ?? \"peaking\";\n        node.frequency.value = band.frequency;\n        node.gain.value = band.gain ?? 0;\n        node.Q.value = band.q ?? 1;\n        return node;\n      });\n\n      filterNodesRef.current = filters;\n\n      // Install processing chain BEFORE removing the temp analyser so the graph stays valid\n      setProcessingChain(el, filters);\n      detachLiveAnalyser(el, tempId);\n\n      setError(null);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : \"Failed to create equalizer\";\n      setError(msg);\n      filterNodesRef.current = [];\n    }\n\n    return () => {\n      const element = audioRef.current;\n      if (element) {\n        setProcessingChain(element, []);\n      }\n      filterNodesRef.current = [];\n    };\n  }, [enabled, bands, audioRef, state.currentIndex]);\n\n  const setBandGain = useCallback((bandIndex: number, gainDb: number) => {\n    const node = filterNodesRef.current[bandIndex];\n    if (node) {\n      node.gain.value = gainDb;\n    }\n    setBandsState((prev) => prev.map((b, i) => (i === bandIndex ? { ...b, gain: gainDb } : b)));\n  }, []);\n\n  const setBands = useCallback((nextBands: EqualizerBand[]) => {\n    setBandsState(nextBands);\n  }, []);\n\n  return { setBandGain, setBands, bands, error };\n}\n"],"names":["DEFAULT_BANDS","useGingerEqualizer","options","enabled","initialBands","audioRef","state","useGinger","bands","setBandsState","useState","error","setError","filterNodesRef","useRef","useEffect","el","setProcessingChain","attached","attachLiveAnalyser","context","tempId","filters","band","node","detachLiveAnalyser","e","msg","element","setBandGain","useCallback","bandIndex","gainDb","prev","b","i","setBands","nextBands"],"mappings":"qJAqCMA,EAAiC,CACrC,CAAE,UAAW,EAAA,EACb,CAAE,UAAW,GAAA,EACb,CAAE,UAAW,GAAA,EACb,CAAE,UAAW,GAAA,EACb,CAAE,UAAW,IAAA,CACf,EAeO,SAASC,EACdC,EAAqC,GACX,CAC1B,KAAM,CAAE,QAAAC,EAAU,GAAM,MAAOC,EAAeJ,GAAkBE,EAC1D,CAAE,SAAAG,EAAU,MAAAC,CAAA,EAAUC,YAAA,EAEtB,CAACC,EAAOC,CAAa,EAAIC,EAAAA,SAA0BN,CAAY,EAC/D,CAACO,EAAOC,CAAQ,EAAIF,EAAAA,SAAwB,IAAI,EAEhDG,EAAiBC,EAAAA,OAA2B,EAAE,EAEpDC,EAAAA,UAAU,IAAM,CACd,MAAMC,EAAKX,EAAS,QACpB,GAAI,GAACW,GAAM,OAAO,OAAW,KAI7B,IAAI,CAACb,EAAS,CACZc,EAAAA,mBAAmBD,EAAI,EAAE,EACzBH,EAAe,QAAU,CAAA,EACzB,MACF,CAEA,GAAI,CAIF,MAAMK,EAAWC,EAAAA,mBAAmBH,EAAI,CACtC,QAAS,GACT,sBAAuB,EACvB,YAAa,KACb,YAAa,CAAA,CACd,EACK,CAAE,QAAAI,EAAS,GAAIC,CAAA,EAAWH,EAE1BI,EAA8Bd,EAAM,IAAKe,GAAS,CACtD,MAAMC,EAAOJ,EAAQ,mBAAA,EACrB,OAAAI,EAAK,KAAOD,EAAK,MAAQ,UACzBC,EAAK,UAAU,MAAQD,EAAK,UAC5BC,EAAK,KAAK,MAAQD,EAAK,MAAQ,EAC/BC,EAAK,EAAE,MAAQD,EAAK,GAAK,EAClBC,CACT,CAAC,EAEDX,EAAe,QAAUS,EAGzBL,EAAAA,mBAAmBD,EAAIM,CAAO,EAC9BG,EAAAA,mBAAmBT,EAAIK,CAAM,EAE7BT,EAAS,IAAI,CACf,OAASc,EAAG,CACV,MAAMC,EAAMD,aAAa,MAAQA,EAAE,QAAU,6BAC7Cd,EAASe,CAAG,EACZd,EAAe,QAAU,CAAA,CAC3B,CAEA,MAAO,IAAM,CACX,MAAMe,EAAUvB,EAAS,QACrBuB,GACFX,EAAAA,mBAAmBW,EAAS,EAAE,EAEhCf,EAAe,QAAU,CAAA,CAC3B,EACF,EAAG,CAACV,EAASK,EAAOH,EAAUC,EAAM,YAAY,CAAC,EAEjD,MAAMuB,EAAcC,EAAAA,YAAY,CAACC,EAAmBC,IAAmB,CACrE,MAAMR,EAAOX,EAAe,QAAQkB,CAAS,EACzCP,IACFA,EAAK,KAAK,MAAQQ,GAEpBvB,EAAewB,GAASA,EAAK,IAAI,CAACC,EAAGC,IAAOA,IAAMJ,EAAY,CAAE,GAAGG,EAAG,KAAMF,CAAA,EAAWE,CAAE,CAAC,CAC5F,EAAG,CAAA,CAAE,EAECE,EAAWN,cAAaO,GAA+B,CAC3D5B,EAAc4B,CAAS,CACzB,EAAG,CAAA,CAAE,EAEL,MAAO,CAAE,YAAAR,EAAa,SAAAO,EAAU,MAAA5B,EAAO,MAAAG,CAAA,CACzC"}

package/dist/equalizer/index.d.ts

@@ -0,0 +1,3 @@
+export { useGingerEqualizer } from './useGingerEqualizer';
+export type { EqualizerBand, UseGingerEqualizerOptions, UseGingerEqualizerResult, } from './useGingerEqualizer';
+//# sourceMappingURL=index.d.ts.map

package/dist/equalizer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/equalizer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/equalizer/index.js

@@ -0,0 +1,51 @@
+import { useState as y, useRef as A, useEffect as S, useCallback as q } from "react";
+import { u as x, s as f, a as z, d as C } from "../liveAudioGraph-CmEsdLgZ.js";
+const D = [
+  { frequency: 60 },
+  { frequency: 250 },
+  { frequency: 1e3 },
+  { frequency: 4e3 },
+  { frequency: 16e3 }
+];
+function L(g = {}) {
+  const { enabled: l = !0, bands: p = D } = g, { audioRef: u, state: h } = x(), [i, d] = y(p), [v, m] = y(null), s = A([]);
+  S(() => {
+    const e = u.current;
+    if (!(!e || typeof window > "u")) {
+      if (!l) {
+        f(e, []), s.current = [];
+        return;
+      }
+      try {
+        const t = z(e, {
+          fftSize: 32,
+          smoothingTimeConstant: 0,
+          minDecibels: -100,
+          maxDecibels: 0
+        }), { context: n, id: o } = t, c = i.map((r) => {
+          const a = n.createBiquadFilter();
+          return a.type = r.type ?? "peaking", a.frequency.value = r.frequency, a.gain.value = r.gain ?? 0, a.Q.value = r.q ?? 1, a;
+        });
+        s.current = c, f(e, c), C(e, o), m(null);
+      } catch (t) {
+        const n = t instanceof Error ? t.message : "Failed to create equalizer";
+        m(n), s.current = [];
+      }
+      return () => {
+        const t = u.current;
+        t && f(t, []), s.current = [];
+      };
+    }
+  }, [l, i, u, h.currentIndex]);
+  const B = q((e, t) => {
+    const n = s.current[e];
+    n && (n.gain.value = t), d((o) => o.map((c, r) => r === e ? { ...c, gain: t } : c));
+  }, []), E = q((e) => {
+    d(e);
+  }, []);
+  return { setBandGain: B, setBands: E, bands: i, error: v };
+}
+export {
+  L as useGingerEqualizer
+};
+//# sourceMappingURL=index.js.map

package/dist/equalizer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/equalizer/useGingerEqualizer.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n  attachLiveAnalyser,\n  detachLiveAnalyser,\n  setProcessingChain,\n} from \"../analyzer/liveAudioGraph\";\nimport { useGinger } from \"../hooks/useGinger\";\n\nexport type EqualizerBand = {\n  /** Center frequency in Hz (e.g. 60, 250, 1000, 4000, 16000). */\n  frequency: number;\n  /** Gain in dB. Positive = boost, negative = cut. Typical range: -12 to +12. Default: 0. */\n  gain?: number;\n  /** Q factor (bandwidth). Higher = narrower. Default: 1. */\n  q?: number;\n  /** BiquadFilterNode type. Default: \"peaking\". */\n  type?: BiquadFilterType;\n};\n\nexport type UseGingerEqualizerOptions = {\n  /** When false, EQ nodes are detached and the audio path is bypassed. Default: true. */\n  enabled?: boolean;\n  /** Band definitions. Each band maps to one BiquadFilterNode. */\n  bands?: EqualizerBand[];\n};\n\nexport type UseGingerEqualizerResult = {\n  /** Update a single band's gain in dB without rebuilding the filter chain. */\n  setBandGain: (bandIndex: number, gainDb: number) => void;\n  /** Replace all bands (rebuilds the filter chain). */\n  setBands: (bands: EqualizerBand[]) => void;\n  /** Current band definitions (reflects the latest `setBands` call). */\n  bands: EqualizerBand[];\n  /** Error string if Web Audio is unavailable or filter creation failed. */\n  error: string | null;\n};\n\nconst DEFAULT_BANDS: EqualizerBand[] = [\n  { frequency: 60 },\n  { frequency: 250 },\n  { frequency: 1000 },\n  { frequency: 4000 },\n  { frequency: 16000 },\n];\n\n/**\n * Inserts a parametric EQ into the Web Audio graph for the active Ginger media element.\n *\n * Each band is a `BiquadFilterNode` connected in series between the audio source and the\n * speakers. If `useGingerLiveAnalyzer` is also active, the EQ is inserted before the analyser\n * — both share the same `AudioContext` (the browser allows only one `MediaElementAudioSourceNode`\n * per element).\n *\n * Available as a subpath export:\n * ```ts\n * import { useGingerEqualizer } from \"@lucaismyname/ginger/equalizer\";\n * ```\n */\nexport function useGingerEqualizer(\n  options: UseGingerEqualizerOptions = {},\n): UseGingerEqualizerResult {\n  const { enabled = true, bands: initialBands = DEFAULT_BANDS } = options;\n  const { audioRef, state } = useGinger();\n\n  const [bands, setBandsState] = useState<EqualizerBand[]>(initialBands);\n  const [error, setError] = useState<string | null>(null);\n\n  const filterNodesRef = useRef<BiquadFilterNode[]>([]);\n\n  useEffect(() => {\n    const el = audioRef.current;\n    if (!el || typeof window === \"undefined\") {\n      return;\n    }\n\n    if (!enabled) {\n      setProcessingChain(el, []);\n      filterNodesRef.current = [];\n      return;\n    }\n\n    try {\n      // Attach a temporary analyser solely to get (or create) the shared AudioContext.\n      // The graph is rebuilt by liveAudioGraph after we call setProcessingChain, so this\n      // temporary consumer is detached immediately after we have the context reference.\n      const attached = attachLiveAnalyser(el, {\n        fftSize: 32,\n        smoothingTimeConstant: 0,\n        minDecibels: -100,\n        maxDecibels: 0,\n      });\n      const { context, id: tempId } = attached;\n\n      const filters: BiquadFilterNode[] = bands.map((band) => {\n        const node = context.createBiquadFilter();\n        node.type = band.type ?? \"peaking\";\n        node.frequency.value = band.frequency;\n        node.gain.value = band.gain ?? 0;\n        node.Q.value = band.q ?? 1;\n        return node;\n      });\n\n      filterNodesRef.current = filters;\n\n      // Install processing chain BEFORE removing the temp analyser so the graph stays valid\n      setProcessingChain(el, filters);\n      detachLiveAnalyser(el, tempId);\n\n      setError(null);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : \"Failed to create equalizer\";\n      setError(msg);\n      filterNodesRef.current = [];\n    }\n\n    return () => {\n      const element = audioRef.current;\n      if (element) {\n        setProcessingChain(element, []);\n      }\n      filterNodesRef.current = [];\n    };\n  }, [enabled, bands, audioRef, state.currentIndex]);\n\n  const setBandGain = useCallback((bandIndex: number, gainDb: number) => {\n    const node = filterNodesRef.current[bandIndex];\n    if (node) {\n      node.gain.value = gainDb;\n    }\n    setBandsState((prev) => prev.map((b, i) => (i === bandIndex ? { ...b, gain: gainDb } : b)));\n  }, []);\n\n  const setBands = useCallback((nextBands: EqualizerBand[]) => {\n    setBandsState(nextBands);\n  }, []);\n\n  return { setBandGain, setBands, bands, error };\n}\n"],"names":["DEFAULT_BANDS","useGingerEqualizer","options","enabled","initialBands","audioRef","state","useGinger","bands","setBandsState","useState","error","setError","filterNodesRef","useRef","useEffect","el","setProcessingChain","attached","attachLiveAnalyser","context","tempId","filters","band","node","detachLiveAnalyser","e","msg","element","setBandGain","useCallback","bandIndex","gainDb","prev","b","i","setBands","nextBands"],"mappings":";;AAqCA,MAAMA,IAAiC;AAAA,EACrC,EAAE,WAAW,GAAA;AAAA,EACb,EAAE,WAAW,IAAA;AAAA,EACb,EAAE,WAAW,IAAA;AAAA,EACb,EAAE,WAAW,IAAA;AAAA,EACb,EAAE,WAAW,KAAA;AACf;AAeO,SAASC,EACdC,IAAqC,IACX;AAC1B,QAAM,EAAE,SAAAC,IAAU,IAAM,OAAOC,IAAeJ,MAAkBE,GAC1D,EAAE,UAAAG,GAAU,OAAAC,EAAA,IAAUC,EAAA,GAEtB,CAACC,GAAOC,CAAa,IAAIC,EAA0BN,CAAY,GAC/D,CAACO,GAAOC,CAAQ,IAAIF,EAAwB,IAAI,GAEhDG,IAAiBC,EAA2B,EAAE;AAEpD,EAAAC,EAAU,MAAM;AACd,UAAMC,IAAKX,EAAS;AACpB,QAAI,GAACW,KAAM,OAAO,SAAW,MAI7B;AAAA,UAAI,CAACb,GAAS;AACZ,QAAAc,EAAmBD,GAAI,EAAE,GACzBH,EAAe,UAAU,CAAA;AACzB;AAAA,MACF;AAEA,UAAI;AAIF,cAAMK,IAAWC,EAAmBH,GAAI;AAAA,UACtC,SAAS;AAAA,UACT,uBAAuB;AAAA,UACvB,aAAa;AAAA,UACb,aAAa;AAAA,QAAA,CACd,GACK,EAAE,SAAAI,GAAS,IAAIC,EAAA,IAAWH,GAE1BI,IAA8Bd,EAAM,IAAI,CAACe,MAAS;AACtD,gBAAMC,IAAOJ,EAAQ,mBAAA;AACrB,iBAAAI,EAAK,OAAOD,EAAK,QAAQ,WACzBC,EAAK,UAAU,QAAQD,EAAK,WAC5BC,EAAK,KAAK,QAAQD,EAAK,QAAQ,GAC/BC,EAAK,EAAE,QAAQD,EAAK,KAAK,GAClBC;AAAA,QACT,CAAC;AAED,QAAAX,EAAe,UAAUS,GAGzBL,EAAmBD,GAAIM,CAAO,GAC9BG,EAAmBT,GAAIK,CAAM,GAE7BT,EAAS,IAAI;AAAA,MACf,SAASc,GAAG;AACV,cAAMC,IAAMD,aAAa,QAAQA,EAAE,UAAU;AAC7C,QAAAd,EAASe,CAAG,GACZd,EAAe,UAAU,CAAA;AAAA,MAC3B;AAEA,aAAO,MAAM;AACX,cAAMe,IAAUvB,EAAS;AACzB,QAAIuB,KACFX,EAAmBW,GAAS,EAAE,GAEhCf,EAAe,UAAU,CAAA;AAAA,MAC3B;AAAA;AAAA,EACF,GAAG,CAACV,GAASK,GAAOH,GAAUC,EAAM,YAAY,CAAC;AAEjD,QAAMuB,IAAcC,EAAY,CAACC,GAAmBC,MAAmB;AACrE,UAAMR,IAAOX,EAAe,QAAQkB,CAAS;AAC7C,IAAIP,MACFA,EAAK,KAAK,QAAQQ,IAEpBvB,EAAc,CAACwB,MAASA,EAAK,IAAI,CAACC,GAAGC,MAAOA,MAAMJ,IAAY,EAAE,GAAGG,GAAG,MAAMF,EAAA,IAAWE,CAAE,CAAC;AAAA,EAC5F,GAAG,CAAA,CAAE,GAECE,IAAWN,EAAY,CAACO,MAA+B;AAC3D,IAAA5B,EAAc4B,CAAS;AAAA,EACzB,GAAG,CAAA,CAAE;AAEL,SAAO,EAAE,aAAAR,GAAa,UAAAO,GAAU,OAAA5B,GAAO,OAAAG,EAAA;AACzC;"}

package/dist/equalizer/useGingerEqualizer.d.ts

@@ -0,0 +1,41 @@
+export type EqualizerBand = {
+    /** Center frequency in Hz (e.g. 60, 250, 1000, 4000, 16000). */
+    frequency: number;
+    /** Gain in dB. Positive = boost, negative = cut. Typical range: -12 to +12. Default: 0. */
+    gain?: number;
+    /** Q factor (bandwidth). Higher = narrower. Default: 1. */
+    q?: number;
+    /** BiquadFilterNode type. Default: "peaking". */
+    type?: BiquadFilterType;
+};
+export type UseGingerEqualizerOptions = {
+    /** When false, EQ nodes are detached and the audio path is bypassed. Default: true. */
+    enabled?: boolean;
+    /** Band definitions. Each band maps to one BiquadFilterNode. */
+    bands?: EqualizerBand[];
+};
+export type UseGingerEqualizerResult = {
+    /** Update a single band's gain in dB without rebuilding the filter chain. */
+    setBandGain: (bandIndex: number, gainDb: number) => void;
+    /** Replace all bands (rebuilds the filter chain). */
+    setBands: (bands: EqualizerBand[]) => void;
+    /** Current band definitions (reflects the latest `setBands` call). */
+    bands: EqualizerBand[];
+    /** Error string if Web Audio is unavailable or filter creation failed. */
+    error: string | null;
+};
+/**
+ * Inserts a parametric EQ into the Web Audio graph for the active Ginger media element.
+ *
+ * Each band is a `BiquadFilterNode` connected in series between the audio source and the
+ * speakers. If `useGingerLiveAnalyzer` is also active, the EQ is inserted before the analyser
+ * — both share the same `AudioContext` (the browser allows only one `MediaElementAudioSourceNode`
+ * per element).
+ *
+ * Available as a subpath export:
+ * ```ts
+ * import { useGingerEqualizer } from "@lucaismyname/ginger/equalizer";
+ * ```
+ */
+export declare function useGingerEqualizer(options?: UseGingerEqualizerOptions): UseGingerEqualizerResult;
+//# sourceMappingURL=useGingerEqualizer.d.ts.map

package/dist/equalizer/useGingerEqualizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGingerEqualizer.d.ts","sourceRoot":"","sources":["../../src/equalizer/useGingerEqualizer.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,qDAAqD;IACrD,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAC3C,sEAAsE;IACtE,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAUF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA6E1B"}