Audio Playback

As of stream-chat-react-native@8.11.0, you can build audio players using:

• AudioPlayerProvider React component
• useAudioPlayerControl hook
• useActiveAudioPlayer hook

Best Practices

• Wrap audio UI in AudioPlayerProvider to keep playback stable in lists.
• Use useStateStore selectors to avoid re-rendering on unrelated audio state.
• Prefer single-playback mode unless your UX clearly needs concurrency.
• Reuse the shared player pool instead of creating per-row players.
• Test playback when items unmount to confirm continuity.

The old useAudioPlayer hook is deprecated; most functionality is now in AudioPlayer.

Audio playback is controlled via AudioPlayerProvider and useAudioPlayerControl. The provider maintains a pool of AudioPlayer instances; access them with useAudioPlayerControl.

By default, Channel renders AudioPlayerProvider, so its children share a single pool.

Audio Playback mode

Choose between single or concurrent playback:

Single-playback mode: only one audio at a time (default in Channel). Concurrent-playback mode: multiple audios can play at once.

Enable concurrent playback by setting allowConcurrentPlayback in AudioPlayerProvider’s value.

Building Audio Components

To build audio components outside Channel:

1. Have a top-level component render AudioPlayerProvider

const TopLevelComponent = ({ children }) => {
  return (
    <AudioPlayerProvider value={{ allowConcurrentPlayback: false }}>
      {children}
    </AudioPlayerProvider>
  );
};

2. Render the audio player in a child component

import {
  AudioPlayerState,
  useAudioPlayerControl,
  useStateStore,
} from "stream-chat-react-native";

const audioPlayerSelector = (state: AudioPlayerState) => ({
  currentPlaybackRate: state.currentPlaybackRate,
  duration: state.duration,
  isPlaying: state.isPlaying,
  position: state.position,
  progress: state.progress,
});

const AudioPlayerComponent = () => {
  const audioPlayer = useAudioPlayerControl({
    duration: item.duration ?? 0,
    mimeType: item.mime_type ?? "",
    requester: "audio-player-component",
    type: isVoiceRecording ? "voiceRecording" : "audio",
    uri: item.asset_url ?? "",
  });
  // You can use the following state to build your own audio player UI
  const { duration, isPlaying, position, progress, currentPlaybackRate } =
    useStateStore(audioPlayer.state, audioPlayerSelector);
};

3. Get the active audio player

In single-playback mode, a global player UI can show the active audio even if the user scrolls away.

Note: This is relevant only for single-playback mode.

import { useActiveAudioPlayer } from "stream-chat-react-native";

const activeAudioPlayer = useActiveAudioPlayer();

Audio Player API

Use the following AudioPlayer methods to build a UI:

Getters

Setters

Methods

play - plays the audio.

audioPlayer.play();

pause - pauses the audio.

audioPlayer.pause();

toggle - toggles the playing state of the audio.

audioPlayer.toggle();

seek - seeks to a specific position in the audio.

await audioPlayer.seek(positionInSeconds);

stop - stops the audio.

await audioPlayer.stop();

changePlaybackRate - changes the playback rate of the audio.

await audioPlayer.changePlaybackRate(playbackRate);

initPlayer - initializes the audio player using the provided URL or provided player reference.

await audioPlayer.initPlayer({ url: "https://example.com/audio.mp3" });