Audio Control

Manage audio mixing, background playback, and silent switch behavior

React Native Video provides comprehensive audio control features including audio mixing with other apps, background playback, and iOS-specific silent switch handling.

Audio Mixing Modes

The mixAudioMode property controls how the video player’s audio interacts with other audio sources on the device.

import { VideoPlayer } from 'react-native-video';

const player = new VideoPlayer({
  uri: 'https://example.com/video.mp4',
});

player.mixAudioMode = 'duckOthers';

Available Mix Modes

mixAudioMode · MixAudioMode · default: "auto"

Controls audio mixing behavior with other apps.

auto

Automatically determines the appropriate mixing behavior based on the content and platform.

player.mixAudioMode = 'auto';

This is the default mode and is recommended for most use cases.

mixWithOthers

Allows the video’s audio to play simultaneously with audio from other apps without affecting their volume.

player.mixAudioMode = 'mixWithOthers';

Use Case: Social Media Feeds

Ideal for auto-playing videos in social feeds where users might be listening to music in the background.

duckOthers

Lowers the volume of other audio sources while the video is playing, then restores their volume when playback stops or pauses.

player.mixAudioMode = 'duckOthers';

Use Case: News & Educational Content

Perfect for content where audio is important but you want to be respectful of background audio.

doNotMix

Stops all other audio sources when the video starts playing. This is the most intrusive mode.

player.mixAudioMode = 'doNotMix';

Use Case: Movies & Full-Screen Video

Best for immersive video experiences where the user expects full control of device audio.

Background Playback

Control whether video continues playing when the app is in the background.

Play in Background

playInBackground · boolean · default: "false"

Enables audio playback when the app is backgrounded.

const player = new VideoPlayer({
  uri: 'https://example.com/podcast.mp4',
});

player.playInBackground = true;

iOS Requirements

To enable background playback on iOS, you must configure background modes in your app’s capabilities:

1. Open your iOS project in Xcode
2. Select your target
3. Go to “Signing & Capabilities”
4. Add “Background Modes” capability
5. Enable “Audio, AirPlay, and Picture in Picture”

Play When Inactive

playWhenInactive · boolean · default: "false"

Enables playback to continue when the app becomes inactive (e.g., during phone calls or notifications).

player.playWhenInactive = true;

This is useful for video streaming apps where playback should continue even when interrupted by system events.

iOS Silent Switch Control

On iOS, you can control whether video audio respects the device’s silent switch.

ignoreSilentSwitchMode · IgnoreSilentSwitchMode · default: "auto"

Controls how the silent switch affects video audio.

Available Modes

auto

player.ignoreSilentSwitchMode = 'auto';

Automatically determines behavior based on context. This is the default and recommended setting.

ignore

player.ignoreSilentSwitchMode = 'ignore';

Video audio plays regardless of the silent switch position. Use this for video-focused apps where audio is essential.

Ideal for video streaming apps, movies, and TV shows where users expect audio even with silent switch on.

obey

player.ignoreSilentSwitchMode = 'obey';

Video audio is muted when the silent switch is on. Use this for social media apps and casual browsing.

Best for social media feeds and content discovery apps where respecting user intent for silence is important.

Volume Control

Direct control over the video player’s volume.

volume · number · default: "1.0"

Sets the audio volume level (0.0 to 1.0).

// Set volume to 50%
player.volume = 0.5;

// Mute completely
player.volume = 0;

// Full volume
player.volume = 1.0;

Muted State

muted · boolean · default: "false"

Mutes or unmutes the video audio.

// Mute the video
player.muted = true;

// Unmute the video
player.muted = false;

Volume vs Muted

Use muted for temporary muting (e.g., toggle mute button) and volume for fine-grained volume control. The muted state is independent of the volume value.

Notification Controls

Enable system media controls and lock screen playback controls.

showNotificationControls · boolean · default: "false"

Shows media controls in the notification panel and lock screen.

const player = new VideoPlayer({
  uri: 'https://example.com/audio.mp4',
});

player.playInBackground = true;
player.showNotificationControls = true;

This enables:

• Lock screen playback controls
• Notification panel controls
• Integration with system media keys
• Bluetooth headset controls

Complete Examples

Music/Podcast Player

import { VideoPlayer } from 'react-native-video';

const audioPlayer = new VideoPlayer({
  uri: 'https://example.com/podcast.mp3',
});

// Configure for background audio playback
audioPlayer.playInBackground = true;
audioPlayer.showNotificationControls = true;
audioPlayer.mixAudioMode = 'doNotMix';

// Initialize and play
await audioPlayer.initialize();
audioPlayer.play();

Social Media Feed Video

import { VideoPlayer } from 'react-native-video';

const feedPlayer = new VideoPlayer({
  uri: 'https://example.com/feed-video.mp4',
});

// Configure for non-intrusive playback
feedPlayer.mixAudioMode = 'mixWithOthers';
feedPlayer.ignoreSilentSwitchMode = 'obey';
feedPlayer.muted = true; // Start muted, unmute on user interaction

await feedPlayer.initialize();
feedPlayer.play();

Full-Screen Video Player

import { VideoPlayer } from 'react-native-video';
import { Platform } from 'react-native';

const videoPlayer = new VideoPlayer({
  uri: 'https://example.com/movie.mp4',
});

// Configure for immersive playback
videoPlayer.mixAudioMode = 'doNotMix';
videoPlayer.playInBackground = true;

if (Platform.OS === 'ios') {
  videoPlayer.ignoreSilentSwitchMode = 'ignore';
  videoPlayer.playWhenInactive = true;
}

videoPlayer.showNotificationControls = true;

await videoPlayer.initialize();
videoPlayer.play();

Fitness/Workout Video

import { VideoPlayer } from 'react-native-video';

const workoutPlayer = new VideoPlayer({
  uri: 'https://example.com/workout.mp4',
});

// Mix with user's workout music
workoutPlayer.mixAudioMode = 'mixWithOthers';
workoutPlayer.playInBackground = true;
workoutPlayer.volume = 0.7; // Slightly lower to blend with music

await workoutPlayer.initialize();
workoutPlayer.play();

Platform Considerations

iOS

iOS-Specific Features

• Silent Switch: Use ignoreSilentSwitchMode to control behavior
• Background Playback: Requires background mode capability in Xcode
• Play When Inactive: Use playWhenInactive for interruption handling

if (Platform.OS === 'ios') {
  player.ignoreSilentSwitchMode = 'ignore';
  player.playWhenInactive = true;
}

Android

Android-Specific Features

• Background Playback: Works out of the box, no special permissions needed
• Audio Focus: Automatically managed by the system
• Notification Controls: Integrated with MediaSession API

player.playInBackground = true;
player.showNotificationControls = true;

Best Practices

Respect User Intent

For social media and casual content, use mixWithOthers or duckOthers to avoid interrupting user’s music. For dedicated video content, doNotMix provides the best experience.

Start Muted for Auto-Play

When auto-playing videos in feeds, start with muted = true and unmute only on explicit user interaction to comply with platform guidelines and user expectations.

Configure Notification Controls for Background Playback

Always enable showNotificationControls when using playInBackground to provide users with standard system controls.

Test Silent Switch Behavior

On iOS, test your app with different ignoreSilentSwitchMode settings to ensure it matches your use case and user expectations.

TypeScript Types

type MixAudioMode = 'mixWithOthers' | 'doNotMix' | 'duckOthers' | 'auto';

type IgnoreSilentSwitchMode = 'auto' | 'ignore' | 'obey';

interface AudioControlProperties {
  // Audio mixing
  mixAudioMode: MixAudioMode;
  
  // Volume control
  volume: number; // 0.0 to 1.0
  muted: boolean;
  
  // Background playback
  playInBackground: boolean;
  playWhenInactive: boolean; // iOS only
  showNotificationControls: boolean;
  
  // iOS silent switch
  ignoreSilentSwitchMode: IgnoreSilentSwitchMode; // iOS only
}