Skip to main content

Interface: UseEqualizerOptions

Defined in: packages/player/src/hooks/useEqualizer.ts:69

Options for useEqualizer.

Properties​

chain?​

readonly optional chain?: Omit<EqualizerPresetChainOptions, "editable">;

Defined in: packages/player/src/hooks/useEqualizer.ts:130

How the EQ curve is compiled — pre-amp on top of the automatic headroom, the bell width, and the tail limiter. See EqualizerPresetChainOptions.

Note the limiter is on by default for every curve that is not flat, cut-only curves included; { limiter: false } removes it. It is sample-identical below full scale, so this is not a tone decision — see EqualizerPresetChainOptions.limiter for what it does and does not change.

editable is not yours to set here: this hook always compiles an editable chain, because that is what lets a slider move a band without rebuilding the filter graph (see the remarks on useEqualizer).

extraFilters?​

readonly optional extraFilters?: readonly AudioFilter[];

Defined in: packages/player/src/hooks/useEqualizer.ts:114

The rest of your filter chain — crossfeed, a compressor, an aformat, anything from AudioFilters. They are appended after the EQ bands, so the signal is equalised first.

Deprecated​

Call player.setAudioFilters([...]) directly. This hook now owns only its own labelled entries and composes with the user chain instead of replacing it, so there is nothing left for this option to work around. It still behaves exactly as it did — the entries land in the same place in the chain — and it will be removed one release from now.

Remarks​

This existed because Player.setAudioFilters used to be replaced wholesale by this hook. It no longer is: the hook writes Player.setEqualizerFilters, which rewrites the @rnmedia_eq_… entries and leaves every other filter — yours, and the managed loudness entry — exactly where it is. A chain set behind the hook's back now survives a slider drag, which is what this option was invented to fake.

The one behavioural difference between the two routes is position. Entries passed here sit inside the managed half, immediately after the EQ limiter; entries passed to setAudioFilters sit after the managed half, which is the same place in the compiled chain. They are interchangeable today, and the direct call is the one that keeps working.

May change between renders; the chain is rewritten only when it actually compiles to something different.

gainRangeDb?​

readonly optional gainRangeDb?: EqualizerGainRange;

Defined in: packages/player/src/hooks/useEqualizer.ts:135

Slider bounds. Every gain that goes in through this hook is clamped to them. Defaults to DEFAULT_EQUALIZER_GAIN_RANGE_DB.

initialEnabled?​

readonly optional initialEnabled?: boolean;

Defined in: packages/player/src/hooks/useEqualizer.ts:85

Whether the EQ starts switched on. Defaults to true — with flat gains that is still an empty chain, and it means the first slider drag is audible without a second tap.

Read once, on mount; a persisted value wins over it.

initialPreset?​

readonly optional initialPreset?: string | EqualizerPreset;

Defined in: packages/player/src/hooks/useEqualizer.ts:77

The curve to start on — a built-in id ('rock'), or any EqualizerPreset. Defaults to flat, which compiles to no filters at all, so an equaliser nobody has touched costs nothing.

Read once, on mount. A persisted curve (see storage) wins over it.

onStorageError?​

readonly optional onStorageError?: (cause: unknown) => void;

Defined in: packages/player/src/hooks/useEqualizer.ts:161

A read or write against storage failed — a broken dependency, not bad data (a corrupt record is handled silently, because that is an ordinary runtime condition and the answer to it is "start from the defaults").

Unhandled, it is one console.warn. It is a callback rather than a returned field because it is not renderable state: nothing on an EQ screen changes because a write failed, and putting it in the snapshot would make every consumer destructure something it will never draw.

Parameters​

ParameterType
causeunknown

Returns​

void

storage?​

readonly optional storage?: EqualizerStorage;

Defined in: packages/player/src/hooks/useEqualizer.ts:147

Where the user's equaliser is remembered — their saved curves and whatever they last had applied.

Omit it and everything is in-memory for the session, which is the correct default for a library: an EQ that silently writes to a storage engine the app did not choose is a dependency, not a feature. See EqualizerStorage.

Read once, on mount.

storageKey?​

readonly optional storageKey?: string;

Defined in: packages/player/src/hooks/useEqualizer.ts:149

Storage key. Defaults to DEFAULT_EQUALIZER_STORAGE_KEY.