Interface: Equalizer
Defined in: packages/player/src/hooks/useEqualizer.ts:172
The equaliser: its live state, and every operation an EQ screen performs on it.
Stable identity — the object is rebuilt only when something in it actually
changed — so passing it whole to a memoised <EqualizerScreen> costs no
render on an unrelated player update.
Properties
bands
readonly bands: readonly EqualizerBand[];
Defined in: packages/player/src/hooks/useEqualizer.ts:179
One entry per band of EQUALIZER_BANDS, low to high — the array to
.map() into sliders.
enabled
readonly enabled: boolean;
Defined in: packages/player/src/hooks/useEqualizer.ts:174
Whether the EQ is applied at all. false leaves your other filters running.
error
readonly error: PlayerError | undefined;
Defined in: packages/player/src/hooks/useEqualizer.ts:217
Why the last apply failed, or undefined while the chain is healthy.
The realistic cause is a libmpv built without the filters (code: 'mpv',
errno: -11): mpv rejects the whole chain, leaves the previous one
playing, and this says so. The UI state here is still what the user asked
for — read player.getAudioFilters() for what mpv actually has.
gainRangeDb
readonly gainRangeDb: EqualizerGainRange;
Defined in: packages/player/src/hooks/useEqualizer.ts:187
The slider bounds every gain is clamped to.
gainsDb
readonly gainsDb: readonly number[];
Defined in: packages/player/src/hooks/useEqualizer.ts:185
The same curve as bands, as the bare gainsDb array every other
function in this package takes. Hand it to defineEqualizerPreset, store
it, diff it.
hydrated
readonly hydrated: boolean;
Defined in: packages/player/src/hooks/useEqualizer.ts:230
Whether the persisted equaliser has been read back yet.
Always true when no storage was given (there is nothing to wait for),
and already true on the first render for a synchronous engine (MMKV),
which is read through inside the mount effect.
With an asynchronous engine (AsyncStorage) it is false until the record
arrives, and nothing is written to mpv in the meantime — so a saved
curve is applied once, rather than flat first and the real curve a
microtask later.
preset
readonly preset: EqualizerPreset | undefined;
Defined in: packages/player/src/hooks/useEqualizer.ts:197
The preset the current curve is, or undefined when it matches none —
which is what a UI shows as "Custom".
Derived by comparing the gains, not remembered from the last
applyPreset: dragging a slider away from Rock and back onto it
lands on Rock again, and no sequence of edits can leave the chip
highlighted on a curve that is not playing.
presets
readonly presets: readonly EqualizerPreset[];
Defined in: packages/player/src/hooks/useEqualizer.ts:203
Everything selectable, in picker order: the built-ins
(EQUALIZER_PRESET_LIST, Flat first then alphabetical) followed by
the user's saved curves in save order.
savedPresets
readonly savedPresets: readonly EqualizerPreset[];
Defined in: packages/player/src/hooks/useEqualizer.ts:208
Just the user's saved curves — the subset deletePreset accepts, so a picker can draw a delete affordance on exactly the right rows.
Methods
applyPreset()
applyPreset(preset: string | EqualizerPreset): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:262
Apply a preset — the chip tap.
Parameters
| Parameter | Type | Description |
|---|---|---|
preset | string | EqualizerPreset | A built-in id ('rock'), a saved preset's id, or any EqualizerPreset object (which need not be in presets). |
Returns
void
Throws
PlayerErrorException invalid-state when a string names no
known preset.
deletePreset()
deletePreset(id: string): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:294
Forget a saved curve.
Deleting the preset that is currently applied does not change the sound — the curve stays exactly where it is, it simply stops having a name.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | A savedPresets id. An unknown id is a no-op (deleting twice is not an error). |
Returns
void
Throws
PlayerErrorException invalid-state for a built-in id —
those ship with the library and cannot be removed.
reset()
reset(): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:270
Flatten every band to 0 dB — the "Reset" button.
Only the curve: enabled and the saved presets are untouched, and a flat curve compiles to an empty chain, so this genuinely removes the EQ from the signal path rather than leaving ten no-op biquads in it.
Returns
void
savePreset()
savePreset(name: string): EqualizerPreset;
Defined in: packages/player/src/hooks/useEqualizer.ts:282
Save the current curve under a name, so it joins presets.
Saving twice under the same name replaces — the name is the identity of a user curve, which is what "Save as…" means everywhere else.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | Human label. Non-empty. |
Returns
The stored preset, so a caller can select it or show it immediately.
Throws
PlayerErrorException invalid-state on an empty name.
setBandGain()
setBandGain(index: number, gainDb: number): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:243
Move one band.
Parameters
| Parameter | Type | Description |
|---|---|---|
index | number | Position in EQUALIZER_BANDS / bands. |
gainDb | number | New gain, clamped to gainRangeDb — a slider cannot throw halfway through a drag. |
Returns
void
Throws
PlayerErrorException invalid-state if index is not a
band, or gainDb is not a finite number. Both are programming errors, not
user input.
setBandGains()
setBandGains(gainsDb: readonly number[]): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:253
Replace the whole curve at once — restoring a profile, or applying a curve computed somewhere else.
Parameters
| Parameter | Type | Description |
|---|---|---|
gainsDb | readonly number[] | Exactly EQUALIZER_BAND_COUNT finite gains, low band first. Each is clamped to gainRangeDb. |
Returns
void
Throws
PlayerErrorException invalid-state on the wrong length or
a non-finite entry.
setEnabled()
setEnabled(enabled: boolean): void;
Defined in: packages/player/src/hooks/useEqualizer.ts:232
Switch the EQ half of the chain on or off, keeping the curve.
Parameters
| Parameter | Type |
|---|---|
enabled | boolean |
Returns
void