Buffer configuration allows you to fine-tune how the video player manages buffering, which directly impacts playback performance, startup time, and user experience.
Overview
The bufferConfig property accepts a BufferConfig object that controls buffering behavior. Different platforms offer different configuration options optimized for their native video players.
import { VideoPlayer } from 'react-native-video';
const player = new VideoPlayer({
uri: 'https://example.com/video.mp4',
bufferConfig: {
minBufferMs: 15000,
maxBufferMs: 50000,
bufferForPlaybackMs: 2500,
bufferForPlaybackAfterRebufferMs: 5000,
},
});
Android Buffer Configuration
Android uses ExoPlayer’s buffer settings to manage buffering behavior.
Basic Buffer Settings
Minimum duration (in milliseconds) the player will attempt to keep buffered.Increase this value for better resilience against network fluctuations, but it will use more memory.
Maximum duration (in milliseconds) the player will attempt to keep buffered.Set this higher for long-form content where users might seek ahead frequently.
Duration (in milliseconds) of media that must be buffered for playback to start or resume following a user action such as a seek.Lower values reduce startup time but may cause more frequent rebuffering.
bufferForPlaybackAfterRebufferMs
Duration (in milliseconds) of media that must be buffered for playback to resume after a rebuffer.Typically set higher than bufferForPlaybackMs to prevent repeated rebuffering.
Duration (in milliseconds) of media that must be buffered before it can be played from the back buffer.Useful for maintaining smooth seeking backwards without re-downloading content.
Example: Android Adaptive Streaming
const adaptiveConfig = {
minBufferMs: 15000,
maxBufferMs: 30000,
bufferForPlaybackMs: 2500,
bufferForPlaybackAfterRebufferMs: 5000,
backBufferDurationMs: 10000,
};
const player = new VideoPlayer({
uri: 'https://example.com/adaptive.m3u8',
bufferConfig: adaptiveConfig,
});
iOS Buffer Configuration
iOS uses AVPlayer’s buffer settings with focus on network bandwidth management.
Forward Buffer Settings
preferredForwardBufferDurationMs
The preferred duration (in milliseconds) of media that the player will attempt to retain in the buffer.AVPlayer automatically manages the buffer, but this provides a hint for the preferred buffer size.
Bandwidth Management
The desired limit, in bits per second, of network bandwidth used for loading the current item.Set this to limit bandwidth usage on all networks.
preferredPeakBitRateForExpensiveNetworks
The desired limit, in bits per second, of network bandwidth used for loading when on an expensive network (e.g., cellular).Use this to provide a better user experience by reducing data usage on cellular networks.
Resolution Management
preferredMaximumResolution
The preferred maximum resolution of the video.preferredMaximumResolution: {
width: 1920,
height: 1080
}
preferredMaximumResolutionForExpensiveNetworks
The preferred maximum resolution when on an expensive network (e.g., cellular).preferredMaximumResolutionForExpensiveNetworks: {
width: 1280,
height: 720
}
Example: iOS Network-Aware Configuration
const iosConfig = {
preferredForwardBufferDurationMs: 10000,
preferredPeakBitRate: 5000000, // 5 Mbps
preferredPeakBitRateForExpensiveNetworks: 2000000, // 2 Mbps on cellular
preferredMaximumResolution: {
width: 1920,
height: 1080,
},
preferredMaximumResolutionForExpensiveNetworks: {
width: 1280,
height: 720,
},
};
const player = new VideoPlayer({
uri: 'https://example.com/video.m3u8',
bufferConfig: iosConfig,
});
Live Playback Configuration
Live streaming requires special buffer configuration to maintain low latency while ensuring smooth playback.
Configuration for live playback behavior.
Live Playback Parameters
livePlayback.targetOffsetMs
Target live offset in milliseconds. The player will try to maintain this offset from the live edge.Lower values reduce latency but increase the risk of rebuffering.
Minimum allowed live offset. The player won’t go below this limit.
Maximum allowed live offset. The player won’t exceed this limit.
livePlayback.minPlaybackSpeed
Minimum playback speed for catching up to target live offset.Values less than 1.0 will slow down playback to stay behind the live edge.
livePlayback.maxPlaybackSpeed
Maximum playback speed for catching up to target live offset.Values greater than 1.0 will speed up playback to catch up to the live edge.
Example: Low-Latency Live Streaming
const liveConfig = {
livePlayback: {
targetOffsetMs: 3000, // 3 second delay from live edge
minOffsetMs: 2000,
maxOffsetMs: 6000,
minPlaybackSpeed: 0.95,
maxPlaybackSpeed: 1.05,
},
// Android settings for live streams
minBufferMs: 5000,
maxBufferMs: 10000,
bufferForPlaybackMs: 1500,
bufferForPlaybackAfterRebufferMs: 3000,
};
const livePlayer = new VideoPlayer({
uri: 'https://example.com/live-stream.m3u8',
bufferConfig: liveConfig,
});
Best Practices
Start Conservative, Then OptimizeBegin with default buffer settings and adjust based on your specific use case and user feedback. Monitor playback metrics to identify optimal values.
Consider Network ConditionsUse different buffer configurations for WiFi vs cellular connections. iOS provides built-in support via preferredPeakBitRateForExpensiveNetworks, while Android requires manual network detection.
Balance Startup Time vs StabilityLower bufferForPlaybackMs reduces startup time but increases rebuffering risk. Higher values provide smoother playback but slower starts.
Live Streaming LatencyFor live streams, lower targetOffsetMs reduces latency but requires more aggressive buffering. Find the sweet spot for your audience and content type.
Common Use Cases
Short-Form Content (< 5 minutes)
const shortFormConfig = {
minBufferMs: 5000,
maxBufferMs: 15000,
bufferForPlaybackMs: 1000,
bufferForPlaybackAfterRebufferMs: 2000,
};
Long-Form Content (Movies, TV Shows)
const longFormConfig = {
minBufferMs: 30000,
maxBufferMs: 120000,
bufferForPlaybackMs: 2500,
bufferForPlaybackAfterRebufferMs: 5000,
backBufferDurationMs: 20000,
};
Live Sports (Low Latency)
const liveSportsConfig = {
livePlayback: {
targetOffsetMs: 2000,
minOffsetMs: 1000,
maxOffsetMs: 5000,
minPlaybackSpeed: 0.98,
maxPlaybackSpeed: 1.02,
},
minBufferMs: 3000,
maxBufferMs: 8000,
bufferForPlaybackMs: 1000,
bufferForPlaybackAfterRebufferMs: 2000,
};
TypeScript Types
interface BufferConfig {
livePlayback?: LivePlaybackParams;
// Android
minBufferMs?: number;
maxBufferMs?: number;
bufferForPlaybackMs?: number;
bufferForPlaybackAfterRebufferMs?: number;
backBufferDurationMs?: number;
// iOS
preferredForwardBufferDurationMs?: number;
preferredPeakBitRate?: number;
preferredMaximumResolution?: Resolution;
preferredPeakBitRateForExpensiveNetworks?: number;
preferredMaximumResolutionForExpensiveNetworks?: Resolution;
}
interface LivePlaybackParams {
minPlaybackSpeed?: number; // Android only
maxPlaybackSpeed?: number; // Android only
maxOffsetMs?: number; // Android only
minOffsetMs?: number; // Android only
targetOffsetMs?: number; // All platforms
}
interface Resolution {
width: number;
height: number;
}