Audio tag (<Audio>)

Experimental

React component that mimics web <Audio> behavior.

caution

This API lives under react-native-audio-api/development/react and is experimental: behavior and props may change.

Usage

import React, { useRef } from 'react';
import { View } from 'react-native';
import { Audio, AudioTagHandle } from 'react-native-audio-api/development/react';

const DEMO_URL = 'https://example.com/audio.mp3';

export function Player() {
  const ref = useRef<AudioTagHandle>(null);

  return (
    <View style={{ flex: 1 }}>
      <Audio
        ref={ref}
        source={DEMO_URL}
        controls
        onLoad={() => console.log('ready')}
        onError={(e) => console.error(e)}
        onPositionChange={(seconds) => {}}
      />
    </View>
  );
}

Props (AudioProps)

Only required field is a source. Callbacks default to no-ops if omitted.

Name	Type	Default	Description
source	AudioSource	—	Asset id (require(...)), string URI/path, or { uri?, headers? } for HTTP(S).
context	BaseAudioContext	—	Optional. Native: implicit AudioContext when omitted. Web: unused for HTML element playback.
autoPlay	boolean	false	Start playback after load.
controls	boolean	false	When true, renders default AudioControls above children.
loop	boolean	false	Loop playback.
muted	boolean	false	Muted state.
volume	number	1	Linear volume passed to the underlying source.
preload	PreloadType	'auto'	Web support only
playbackRate	number	1	Web support only
preservesPitch	boolean	true	Web support only
onLoadStart	() => void	no-op	Load started.
onLoad	() => void	no-op	Source decoded / graph attached.
onError	(error: Error) => void	no-op	Network, decode, or unsupported format (e.g. missing FFmpeg) errors.
onPositionChange	(seconds: number) => void	no-op	Playback position updates while playing.
onEnded	() => void	no-op	Natural end of playback (also used internally when looping restarts).
onPlay	() => void	no-op	After play().
onPause	() => void	no-op	After pause().
onVolumeChange	(volume: number) => void	no-op	When effective volume changes.

AudioSource

• string — URI or path (http(s):, file://, or platform-specific asset path).
• number — Result of require('./file.mp3') (bundled asset).
• AudioURISource — { uri?: string; headers?: Record<string, string> } for fetch with custom headers.

Ref handle (AudioTagHandle) methods

play

Start or resume playback.

pause

Pause playback.

seekToTime

Parameter	Type	Description
seconds	number	Seek to a time in seconds (clamped to duration when known).

setVolume

Parameter	Type	Description
volume	number	Updates volume state .

setMuted

Parameter	Type	Description
muted	boolean	Updates muted state .

useAudioTagContext

Types

type AudioComponentContextType = {
  play: () => void;
  pause: () => void;
  seekToTime: (seconds: number) => void;
  setVolume: (volume: number) => void;
  setMuted: (muted: boolean) => void;

  ready: boolean;
  volume: number;
  muted: boolean;
  playbackState: AudioTagPlaybackState;
  currentTime: number;
  duration: number;
  autoPlay: boolean;
  loop: boolean;
  preload: PreloadType;
  playbackRate: number;
  preservesPitch: boolean;
  audioContext: BaseAudioContext | null;
};

Useful for creating your custom UI component. Must be used under <Audio>. Throws an Error if used outside the provider.

import React from 'react';
import { Button } from 'react-native';

const AudioControls: React.FC = () => {
  const {
    play,
    pause,
    seekToTime,
  } = useAudioTagContext();

  return (
    <>
      <Button onPress={() => play()}>Play</Button>
      <Button onPress={() => pause()}>Pause</Button>
      <Button onPress={() => seekToTime(10)}>Seek to 10</Button>
    </>
  );
}

const MyAudioTagWrapper : React.FC = () => {
  const URL = ...;

  return (
    <Audio source={URL}>
      <AudioControls />
    </Audio>
  );
}

Remarks

• FFmpeg: Some formats require a build with FFmpeg; otherwise createFileSource may fail and onError receives a NotSupportedError.