Performance Optimization

Optimizing video performance is crucial for providing smooth playback, reducing startup time, and minimizing resource usage. This guide covers performance best practices based on React Native Video’s architecture.

Player Lifecycle Management

Proper Initialization

Control when the player initializes to optimize resource usage:

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

// Defer initialization for better performance
const player = new VideoPlayer({
  uri: 'https://example.com/video.mp4',
  initializeOnCreation: false,
});

// Initialize when needed (e.g., when component mounts or user scrolls into view)
await player.initialize();

Lazy InitializationSet initializeOnCreation: false for videos in lists or tabs that aren’t immediately visible. Initialize only when the user is about to view the content.

Preloading for Instant Playback

Use preload() for faster playback start:

// Preload without full initialization
await player.preload();

// When user requests playback, initialize and play
await player.initialize();
player.play();

Memory Management

The player automatically manages memory through garbage collection, but you should explicitly release resources when done:

// When player is no longer needed
player.release();

Released Players Cannot Be ReusedAfter calling release(), the player instance cannot be used again. Create a new player instance if needed.

Replace Source Without Recreation

Reuse player instances by replacing the source:

// Efficient: Reuse existing player
await player.replaceSourceAsync({
  uri: 'https://example.com/new-video.mp4',
});

// Inefficient: Creating new player each time
const newPlayer = new VideoPlayer({ uri: 'new-video.mp4' });

Playlist PerformanceUse replaceSourceAsync() for playlist functionality instead of creating new player instances for each video.

Buffer Configuration Optimization

Adaptive Buffering

Adjust buffer settings based on content type and network conditions:

Short Videos
Long Videos
Live Streams

const shortVideoConfig = {
  minBufferMs: 5000,
  maxBufferMs: 15000,
  bufferForPlaybackMs: 1000,
  bufferForPlaybackAfterRebufferMs: 2000,
};

const player = new VideoPlayer({
  uri: 'https://example.com/short-clip.mp4',
  bufferConfig: shortVideoConfig,
});

Optimize for quick startup and minimal memory usage.

const longVideoConfig = {
  minBufferMs: 30000,
  maxBufferMs: 120000,
  bufferForPlaybackMs: 2500,
  bufferForPlaybackAfterRebufferMs: 5000,
  backBufferDurationMs: 20000,
};

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

Optimize for smooth playback and seeking.

const liveConfig = {
  livePlayback: {
    targetOffsetMs: 3000,
    minOffsetMs: 2000,
    maxOffsetMs: 6000,
  },
  minBufferMs: 5000,
  maxBufferMs: 10000,
  bufferForPlaybackMs: 1500,
  bufferForPlaybackAfterRebufferMs: 3000,
};

const player = new VideoPlayer({
  uri: 'https://example.com/live-stream.m3u8',
  bufferConfig: liveConfig,
});

Optimize for low latency and smooth live playback.

Network-Aware Configuration

iOS provides built-in network-aware configuration:

const networkAwareConfig = {
  // WiFi settings
  preferredPeakBitRate: 5000000, // 5 Mbps
  preferredMaximumResolution: {
    width: 1920,
    height: 1080,
  },
  // Cellular settings
  preferredPeakBitRateForExpensiveNetworks: 2000000, // 2 Mbps
  preferredMaximumResolutionForExpensiveNetworks: {
    width: 1280,
    height: 720,
  },
};

const player = new VideoPlayer({
  uri: 'https://example.com/adaptive-stream.m3u8',
  bufferConfig: networkAwareConfig,
});

List and Feed Optimization

import { FlatList } from 'react-native';
import { VideoView, VideoPlayer } from 'react-native-video';

function VideoFeed() {
  const [players] = useState(() => {
    // Create a pool of reusable players
    return Array(3).fill(null).map(() => 
      new VideoPlayer({ 
        uri: '',
        initializeOnCreation: false 
      })
    );
  });
  
  const [activeIndex, setActiveIndex] = useState(0);

  const onViewableItemsChanged = useCallback(({ viewableItems }) => {
    const visibleIndex = viewableItems[0]?.index ?? 0;
    setActiveIndex(visibleIndex);
    
    // Pause others, play visible
    players.forEach((player, idx) => {
      if (idx === visibleIndex) {
        player.play();
      } else {
        player.pause();
      }
    });
  }, [players]);

  return (
    <FlatList
      data={videos}
      onViewableItemsChanged={onViewableItemsChanged}
      viewabilityConfig={{ itemVisiblePercentThreshold: 50 }}
      renderItem={({ item, index }) => (
        <VideoItem 
          video={item} 
          player={players[index % players.length]}
          isActive={index === activeIndex}
        />
      )}
    />
  );
}

Player PoolingCreate a small pool of reusable players (3-5) and cycle through them as the user scrolls. This is more efficient than creating/destroying players for every item.

Viewport-Based Loading

function VideoItem({ player, video, isActive }) {
  const [isVisible, setIsVisible] = useState(false);
  const viewRef = useRef(null);

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => setIsVisible(entry.isIntersecting),
      { threshold: 0.5 }
    );

    if (viewRef.current) {
      observer.observe(viewRef.current);
    }

    return () => observer.disconnect();
  }, []);

  useEffect(() => {
    if (isVisible && isActive) {
      // Load and play when visible
      player.replaceSourceAsync({ uri: video.uri }).then(() => {
        player.play();
      });
    } else {
      // Pause when not visible
      player.pause();
    }
  }, [isVisible, isActive, player, video]);

  return (
    <View ref={viewRef}>
      <VideoView player={player} />
    </View>
  );
}

Event Handling Optimization

Throttle Event Listeners

import { throttle } from 'lodash';

// Throttle progress updates to reduce re-renders
const handleProgress = throttle((currentTime) => {
  updateProgressBar(currentTime);
}, 250); // Update every 250ms

player.onProgress = (event) => {
  handleProgress(event.currentTime);
};

Cleanup Event Listeners

function useVideoPlayer(uri: string) {
  const playerRef = useRef<VideoPlayer>();

  useEffect(() => {
    const player = new VideoPlayer({ uri });
    playerRef.current = player;

    // Set up event listeners
    player.onProgress = handleProgress;
    player.onError = handleError;
    player.onEnd = handleEnd;

    // Cleanup
    return () => {
      player.onProgress = undefined;
      player.onError = undefined;
      player.onEnd = undefined;
      player.release();
    };
  }, [uri]);

  return playerRef.current;
}

Platform-Specific Optimizations

iOS
Android

iOS Performance Tips

import { Platform } from 'react-native';

const iosOptimizations = {
  // Limit bandwidth on cellular
  bufferConfig: {
    preferredPeakBitRateForExpensiveNetworks: 2000000,
    preferredMaximumResolutionForExpensiveNetworks: {
      width: 1280,
      height: 720,
    },
  },
  // Enable background playback only when needed
  initializeOnCreation: false,
};

const player = new VideoPlayer({
  uri: 'video.mp4',
  ...(Platform.OS === 'ios' ? iosOptimizations : {}),
});

Use preferredPeakBitRate to limit bandwidth and improve battery life.

Android Performance Tips

const androidOptimizations = {
  bufferConfig: {
    // Optimize for lower-end devices
    minBufferMs: 10000,
    maxBufferMs: 30000,
    bufferForPlaybackMs: 2000,
    bufferForPlaybackAfterRebufferMs: 3000,
    // Keep less in back buffer
    backBufferDurationMs: 5000,
  },
};

const player = new VideoPlayer({
  uri: 'video.mp4',
  ...(Platform.OS === 'android' ? androidOptimizations : {}),
});

Adjust backBufferDurationMs to balance memory usage with seeking performance.

Memory Optimization

Monitor Memory Usage

The player automatically updates its memory footprint:

// Memory is updated automatically after:
// - initialize()
// - preload()
// - replaceSourceAsync()
// - release()

Release Unused Resources

// Clear source to free memory without destroying player
await player.replaceSourceAsync(null);

// Player is still usable, can load new source later
await player.replaceSourceAsync({ uri: 'new-video.mp4' });

Background Tab OptimizationWhen users navigate away from video content, replace the source with null to free memory while keeping the player instance for quick reuse.

Startup Time Optimization

Progressive Loading Strategy

class VideoManager {
  private player: VideoPlayer;
  
  async loadVideo(uri: string) {
    // 1. Create player without initialization
    this.player = new VideoPlayer({
      uri,
      initializeOnCreation: false,
    });
    
    // 2. Preload in background
    await this.player.preload();
    
    // 3. Show poster/thumbnail while preloading
    // 4. Initialize when user hits play
    await this.player.initialize();
    this.player.play();
  }
}

Optimized Buffer Settings for Fast Start

const fastStartConfig = {
  // Start playback quickly
  bufferForPlaybackMs: 1000,
  // Build buffer after playback starts
  minBufferMs: 10000,
  maxBufferMs: 30000,
  // Recover quickly from stalls
  bufferForPlaybackAfterRebufferMs: 2500,
};

Best Practices Summary

Use Lazy InitializationSet initializeOnCreation: false and initialize only when needed to reduce startup time and memory usage.

Reuse Player InstancesUse replaceSourceAsync() instead of creating new players for playlists and video lists.

Implement Player PoolingFor feeds and lists, maintain a small pool (3-5) of reusable players instead of creating one per item.

Configure Buffers AppropriatelyAdjust buffer settings based on content type, expected network conditions, and target devices.

Clean Up ProperlyAlways release players and clear event listeners when components unmount to prevent memory leaks.

Throttle Event HandlersThrottle high-frequency events like onProgress to reduce unnecessary re-renders and improve performance.

Platform-Specific OptimizationUse platform-specific buffer configurations and features for optimal performance on each platform.

Monitor and ProfileUse React Native’s performance monitoring tools and platform-specific profilers to identify bottlenecks.

Performance Monitoring

import { performance } from 'react-native-performance';

class VideoPerformanceMonitor {
  private player: VideoPlayer;
  private startTime: number = 0;
  
  async measureStartupTime(uri: string) {
    this.startTime = performance.now();
    
    this.player = new VideoPlayer({ 
      uri,
      initializeOnCreation: false 
    });
    
    await this.player.initialize();
    
    const initTime = performance.now() - this.startTime;
    console.log(`Initialization took ${initTime}ms`);
    
    this.player.onLoadStart = () => {
      this.startTime = performance.now();
    };
    
    this.player.onLoad = () => {
      const loadTime = performance.now() - this.startTime;
      console.log(`Load took ${loadTime}ms`);
      
      // Log to analytics
      analytics.logEvent('video_load_time', {
        uri,
        duration: loadTime,
        platform: Platform.OS,
      });
    };
    
    this.player.play();
  }
}

Troubleshooting Performance Issues

High Memory Usage

Reduce maxBufferMs in buffer config
Decrease backBufferDurationMs
Implement player pooling for lists
Release players when not in use

Slow Startup

Lower bufferForPlaybackMs
Use preload() ahead of time
Optimize video encoding (codec, bitrate)
Use CDN for better network performance

Frequent Rebuffering

Increase minBufferMs
Raise bufferForPlaybackAfterRebufferMs
Lower video bitrate/resolution
Implement adaptive bitrate streaming

Choppy Playback

Increase buffer settings
Check device performance capabilities
Reduce video resolution
Disable unnecessary background processes

Getting Started

Core Concepts

Guides

Advanced

Plugins

Migration & Updates

Player Lifecycle Management

Proper Initialization

Preloading for Instant Playback

Memory Management

Replace Source Without Recreation

Buffer Configuration Optimization

Adaptive Buffering

Network-Aware Configuration

List and Feed Optimization

Viewport-Based Loading

Event Handling Optimization

Throttle Event Listeners

Cleanup Event Listeners

Platform-Specific Optimizations

iOS Performance Tips

Android Performance Tips

Memory Optimization

Monitor Memory Usage

Release Unused Resources

Startup Time Optimization

Progressive Loading Strategy

Optimized Buffer Settings for Fast Start

Best Practices Summary

Performance Monitoring

Troubleshooting Performance Issues

High Memory Usage

Slow Startup

Frequent Rebuffering

Choppy Playback

Getting Started

Core Concepts

Guides

Advanced

Plugins

Migration & Updates

​Player Lifecycle Management

​Proper Initialization

​Preloading for Instant Playback

​Memory Management

​Replace Source Without Recreation

​Buffer Configuration Optimization

​Adaptive Buffering

​Network-Aware Configuration

​List and Feed Optimization

​Video List Best Practices

​Viewport-Based Loading

​Event Handling Optimization

​Throttle Event Listeners

​Cleanup Event Listeners

​Platform-Specific Optimizations

​iOS Performance Tips

​Android Performance Tips

​Memory Optimization

​Monitor Memory Usage

​Release Unused Resources

​Startup Time Optimization

​Progressive Loading Strategy

​Optimized Buffer Settings for Fast Start

​Best Practices Summary

​Performance Monitoring

​Troubleshooting Performance Issues

​High Memory Usage

​Slow Startup

​Frequent Rebuffering

​Choppy Playback

Player Lifecycle Management

Proper Initialization

Preloading for Instant Playback

Memory Management

Replace Source Without Recreation

Buffer Configuration Optimization

Adaptive Buffering

Network-Aware Configuration

List and Feed Optimization

Video List Best Practices

Viewport-Based Loading

Event Handling Optimization

Throttle Event Listeners

Cleanup Event Listeners

Platform-Specific Optimizations

iOS Performance Tips

Android Performance Tips

Memory Optimization

Monitor Memory Usage

Release Unused Resources

Startup Time Optimization

Progressive Loading Strategy

Optimized Buffer Settings for Fast Start

Best Practices Summary

Performance Monitoring

Troubleshooting Performance Issues

High Memory Usage

Slow Startup

Frequent Rebuffering

Choppy Playback