Equalizer
The equalizer lets you shape playback tone — boost the bass, tame the treble — either by applying a named preset (e.g. "Rock", "Jazz") or by setting custom band levels yourself. It wraps the system equalizer effect.
Android only
The equalizer is Android-only. On iOS and web every getter returns undefined and every setter is a no-op; neither platform has an equivalent system equalizer. Always treat the settings as possibly-absent (see Availability).
The UI snippets below import View / Text / Button from react-native and Slider from @react-native-community/slider; those import lines are omitted for brevity. Everything else comes from react-native-audio-browser.
Availability
getEqualizerSettings() returns EqualizerSettings | undefined. It's undefined whenever the equalizer isn't available: on iOS and web, and on Android before setupPlayer and for a short moment after it, until the player's audio session arrives. Use the reactive hook so a settings screen fills in when it does.
On Android, a setter called after setupPlayer but before the equalizer exists is kept and applied when it appears; the result arrives through onEqualizerChanged. A setter called before setupPlayer is dropped.
Reading the settings
useEqualizerSettings() returns the current settings and re-renders when they change:
import { useEqualizerSettings } from 'react-native-audio-browser'
function EqualizerStatus() {
const eq = useEqualizerSettings()
if (!eq) return <Text>Equalizer unavailable</Text>
return (
<Text>
{eq.enabled ? 'On' : 'Off'} · {eq.bandCount} bands
</Text>
)
}The EqualizerSettings object:
| Field | Type | Meaning |
|---|---|---|
enabled | boolean | Whether the effect is currently applied. |
bandCount | number | Number of frequency bands. |
bandLevels | number[] | Current level per band, in millibels. |
centerBandFrequencies | number[] | Center frequency per band, in milliHertz. |
lowerBandLevelLimit | number | Minimum level (millibels) any band accepts. |
upperBandLevelLimit | number | Maximum level (millibels) any band accepts. |
presets | string[] | Available preset names. |
activePreset | string | undefined | The applied preset, or undefined for custom levels. |
See the units note — both level and frequency values use "milli" units.
Outside React, read a snapshot with getEqualizerSettings() or subscribe with onEqualizerChanged.
All the setEqualizer* calls below are fire-and-forget — they return void. The updated settings come back through useEqualizerSettings / onEqualizerChanged, not as a return value.
Turning it on
The effect does nothing audible until it's enabled. Toggle it with setEqualizerEnabled:
import { setEqualizerEnabled } from 'react-native-audio-browser'
setEqualizerEnabled(true)Applying a preset
setEqualizerPreset takes one of the names from settings.presets. The match is case-insensitive; an unknown name is ignored (a warning is logged), so drive your UI from the actual presets list rather than hard-coded strings:
import {
setEqualizerPreset,
useEqualizerSettings
} from 'react-native-audio-browser'
function PresetPicker() {
const eq = useEqualizerSettings()
if (!eq) return null
return (
<View>
{eq.presets.map((preset) => (
<Button
key={preset}
title={preset}
onPress={() => setEqualizerPreset(preset)}
/>
))}
</View>
)
}After applying a preset, activePreset reflects it. Available presets come from the device's system equalizer, so the exact list varies by device.
Custom band levels
setEqualizerLevels sets every band at once, in millibels. The array length must equal bandCount — a mismatched array is ignored — and each value should fall within lowerBandLevelLimit … upperBandLevelLimit:
import { setEqualizerLevels } from 'react-native-audio-browser'
// Flatten all bands to 0, then boost the lowest band by 6 dB (600 mB).
const flat = new Array(eq.bandCount).fill(0)
flat[0] = 600
setEqualizerLevels(flat)Setting custom levels clears activePreset (it becomes undefined), even if they equal a preset's levels. To return to a preset, apply it again.
Whichever you applied last, preset or custom levels, carries over to the next audio session, along with the enabled state.
A complete equalizer screen
Guard for availability, then render an enable toggle, the device presets, and a slider per band:
import { View, Text, Button } from 'react-native'
import Slider from '@react-native-community/slider'
import {
useEqualizerSettings,
setEqualizerEnabled,
setEqualizerPreset,
setEqualizerLevels
} from 'react-native-audio-browser'
// Center frequencies are milliHertz; levels are millibels (1/100 dB).
const formatHz = (mHz: number) => {
const hz = mHz / 1000
if (hz < 1000) return `${hz.toFixed(0)} Hz`
return `${(hz / 1000).toFixed(hz >= 10000 ? 0 : 1)} kHz`
}
function EqualizerScreen() {
const eq = useEqualizerSettings()
if (!eq) return <Text>Equalizer not available</Text>
const setBand = (index: number, millibels: number) => {
const next = [...eq.bandLevels]
next[index] = millibels
setEqualizerLevels(next)
}
return (
<View>
<Button
title={eq.enabled ? 'Disable' : 'Enable'}
onPress={() => setEqualizerEnabled(!eq.enabled)}
/>
{eq.presets.map((preset) => (
<Button
key={preset}
title={preset === eq.activePreset ? `• ${preset}` : preset}
onPress={() => setEqualizerPreset(preset)}
/>
))}
{eq.centerBandFrequencies.map((mHz, index) => {
const level = eq.bandLevels[index] ?? 0
return (
<View key={mHz}>
<Text>
{formatHz(mHz)}: {(level / 100).toFixed(1)} dB
</Text>
<Slider
minimumValue={eq.lowerBandLevelLimit}
maximumValue={eq.upperBandLevelLimit}
value={level}
// Commit on release; onValueChange fires continuously.
onSlidingComplete={(millibels) => setBand(index, millibels)}
/>
</View>
)
})}
</View>
)
}If the thumbs don't follow a newly applied preset, give each Slider a key={eq.activePreset} so it remounts with the new levels.
A note on units
The system equalizer works in "milli" units, so convert for display:
- Levels (
bandLevels, the limits, and what you pass tosetEqualizerLevels) are in millibels — hundredths of a decibel.600mB = 6 dB; divide by 100 for dB. - Center frequencies (
centerBandFrequencies) are in milliHertz.60000= 60 Hz; divide by 1000 for Hz.
API summary
| API | Purpose |
|---|---|
useEqualizerSettings() / getEqualizerSettings() | Read settings (undefined if unavailable). |
onEqualizerChanged | Subscribe to settings changes outside React. |
setEqualizerEnabled(bool) | Turn the effect on or off. |
setEqualizerPreset(name) | Apply a preset from settings.presets. |
setEqualizerLevels(millibels[]) | Set all bands; length must equal bandCount. |
All are Android-only: no-ops or undefined on iOS and web.