react-native-elementary

Use Elementary Audio in your React Native app

Project status

Alpha. The API is subject to change.

Supported platforms

• iOS
• Android

Supported features

• Native Elementary Audio renderer via useRenderer hook
• Real-time setProperty for graph parameter updates
• iOS audio session configuration and management
• Configurable event polling (el.snapshot, el.meter, el.scope, el.fft)
• Audio resource loading via VFS

Known issues

• Native node types (el.metro, el.time, el.fft, el.convolve) are not yet supported (see #4)
• Audio I/O may not update automatically when device connection changes; engine restart on route change is handled, re-graph against new route is pending (see #15)

Installation

npm install react-native-elementary

Usage

import { el } from '@elemaudio/core';
import { useRenderer } from 'react-native-elementary';

const MyComponent = () => {
  const { core } = useRenderer();

  if (!core) {
    return <Text>Initialising audio...</Text>;
  }

  return (
    <View>
      <Button
        title="Play"
        onPress={() => core.render(el.cycle(440), el.cycle(441))}
      />
    </View>
  );
};

iOS audio session

For simple playback apps, no setup is required. react-native-elementary lazily configures and activates an iOS AVAudioSession with playback-oriented defaults before the native audio engine starts.

If your app needs different iOS audio behavior, configure the session before the first render or resource load:

import { configureAudioSession } from 'react-native-elementary';

configureAudioSession({
  iosCategory: 'playback',
  iosMode: 'default',
  iosOptions: ['mixWithOthers', 'allowBluetoothA2DP'],
});

If your app or another audio library owns AVAudioSession, opt out of Elementary's session management before the first render or resource load:

import { disableAudioSessionManagement } from 'react-native-elementary';

disableAudioSessionManagement();

activateAudioSession() and deactivateAudioSession() are also available when you need to explicitly control the iOS session lifecycle. These audio-session helpers are no-ops on Android.

Event polling

By default, react-native-elementary does not start polling for runtime events. This avoids unnecessary JS thread overhead for apps that only use setProperty for real-time updates and don't need el.snapshot, el.meter, or el.scope data.

If your app needs snapshot/meter/scope events, opt in explicitly:

import { startEventPolling, stopEventPolling, configureEventPolling } from 'react-native-elementary';

// Start polling at default ~30Hz (33ms)
await startEventPolling();

// Or configure a different rate before starting:
await configureEventPolling(100); // 100ms ≈ 10Hz (drift correction only)
await startEventPolling();

// Stop polling when you don't need events anymore:
await stopEventPolling();

Listening for events

Events are emitted on the elementaryEvent channel via NativeEventEmitter. Each callback receives a single event object with a type field and event-specific data:

import { NativeEventEmitter, NativeModules } from 'react-native';

const elementaryEmitter = new NativeEventEmitter(NativeModules.Elementary);

const subscription = elementaryEmitter.addListener('elementaryEvent', (event) => {
  // event = { type: 'snapshot', source: 'playhead', data: 1.25 }
  // event = { type: 'meter',   source: 'level',   data: 0.75 }
  // event = { type: 'scope',  data: [...] }
  console.log(event.type, event);
});

// Don't forget to remove on unmount:
subscription.remove();

Polling rates

Interval	Rate	Use case
33ms	~30Hz	Smooth metering, playhead UI
100ms	~10Hz	Drift correction only, minimal overhead

Values are clamped to 10–1000ms.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library