Player Lifecycle

Understanding the lifecycle of the VideoPlayer is crucial for managing resources effectively and ensuring a smooth user experience.

Creation and Initialization

1. Instantiation: A VideoPlayer instance is created by calling its constructor with a video source (URL, VideoSource, or VideoConfig).

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

2. Native Player Creation: Internally this creates a native player instance tailored to the platform (iOS/Android).

info

Player does not initialize asset right after JS class creation. Asset will be initialized when you call preload() or access any property/method of the player.

Playing a Video

1. Loading: When play() is called for the first time, or after replaceSourceAsync(), the player starts loading the video metadata and buffering content.
   • onLoadStart: Fired when the video starts loading.
   • onLoad: Fired when the video metadata is loaded and the player is ready to play (duration, dimensions, etc., are available).
   • onBuffer: Fired when buffering starts or ends.
2. Playback: Once enough data is buffered, playback begins.
   • onPlaybackStateChange: Fired when the playback state changes (e.g., from buffering to playing).
   • onProgress: Fired periodically with the current playback time.
   • onReadyToDisplay: Fired when the first frame is ready to be displayed.

Controlling Playback

• pause(): Pauses playback. status changes to paused.
• seekTo(time), seekBy(time): Changes the current playback position. onSeek is fired when the seek operation completes.
• set volume(value), set muted(value), set loop(value), set rate(value): Modify player properties. Corresponding events like onVolumeChange or onPlaybackRateChange might be fired.

Changing Source

• replaceSourceAsync(newSource): This method allows you to change the video source dynamically.
  1. The current native player resources associated with the old source are released (similar to release() but specifically for the source).
  2. A new native player instance (or reconfigured existing one) is prepared for the newSource.
  3. The loading lifecycle events (onLoadStart, onLoad, etc.) will fire for the new source.
• replaceSourceAsync(null): This effectively unloads the current video and releases its associated resources without loading a new one. This is useful for freeing up memory if the player is temporarily not needed but might be used again later.

Releasing Resources

There are two main ways to release resources:

1. replaceSourceAsync(null): This is a less destructive way to free resources related only to the current video source.

   • The VideoPlayer instance itself remains usable.
   • You can later call replaceSourceAsync(newSource) to load and play a new video.

2. release(): This is a destructive operation.

danger

After calling release(), the player instance becomes unusable. Any subsequent calls to its methods or property access will result in errors.

tip

It is recommended to use replaceSourceAsync(null) when you want to free resources related to the current video source. You should call release() only when you are 100% sure that you don't need the player instance anymore. Anyway garbage collector will release the player instance when it is no longer needed.

Error Handling

• The onError callback, if provided, will be called when a VideoRuntimeError occurs. This allows you to handle issues like network errors, invalid source, or platform-specific playback problems.
• If onError is not provided, errors might be thrown as exceptions.

Using with Hooks (useVideoPlayer)

The useVideoPlayer hook simplifies managing the VideoPlayer lifecycle within React components.

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

const MyComponent = () => {
  const player = useVideoPlayer('https://example.com/video.mp4', (playerInstance) => {
    // Optional setup function: configure the player instance after creation
    playerInstance.loop = true;
  });

  // ... use player ...

  return <VideoView player={player} />;
};

• Automatic Creation: useVideoPlayer creates a VideoPlayer instance when the component mounts or when the source dependency changes.
• Automatic Cleanup: It automatically cleanup resources when the component unmounts or before recreating the player due to a source change. This prevents resource leaks.
• Dependency Management: If the source prop passed to useVideoPlayer changes, the hook will clean up the old player instance and create a new one with the new source.

tip

Using useVideoPlayer is the recommended way to manage VideoPlayer instances in functional components to ensure proper lifecycle management and resource cleanup.