Skip to content

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:

tsx
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:

FieldTypeMeaning
enabledbooleanWhether the effect is currently applied.
bandCountnumberNumber of frequency bands.
bandLevelsnumber[]Current level per band, in millibels.
centerBandFrequenciesnumber[]Center frequency per band, in milliHertz.
lowerBandLevelLimitnumberMinimum level (millibels) any band accepts.
upperBandLevelLimitnumberMaximum level (millibels) any band accepts.
presetsstring[]Available preset names.
activePresetstring | undefinedThe 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:

ts
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:

tsx
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:

ts
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:

tsx
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 to setEqualizerLevels) are in millibels — hundredths of a decibel. 600 mB = 6 dB; divide by 100 for dB.
  • Center frequencies (centerBandFrequencies) are in milliHertz. 60000 = 60 Hz; divide by 1000 for Hz.

API summary ​

APIPurpose
useEqualizerSettings() / getEqualizerSettings()Read settings (undefined if unavailable).
onEqualizerChangedSubscribe 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.