@capgo/capacitor-video-player

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/video-player/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-video-player` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-video-player
bunx cap sync

iOS Chromecast setup

iOS Chromecast uses the Google Cast SDK default media receiver. When chromecast is enabled, the plugin adds a Cast button over the fullscreen iOS player, loads the current media on the selected receiver, and keeps plugin play/pause/seek/volume calls pointed at the active Cast session.

For Cast discovery on iOS, add local network keys to your app Info.plist.

<key>NSBonjourServices</key>
<array>
  <string>_googlecast._tcp</string>
  <string>_CC1AD845._googlecast._tcp</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string>$(PRODUCT_NAME) uses the local network to discover Cast-enabled devices on your WiFi network.</string>

await VideoPlayer.initPlayer({
  playerId: 'fullscreen',
  mode: 'fullscreen',
  url: 'https://example.com/video.mp4',
  title: 'Video title',
  smallTitle: 'Video subtitle',
  artwork: 'https://example.com/poster.jpg',
  chromecast: true,
});

Supported Features

Chromecast (Android)

Chromecast is supported on Android in fullscreen mode. Enable it with the chromecast option. When a Cast session starts, the plugin loads the same media URL on the receiver, keeps the current playback position, and routes play, pause, seek, and timeline controls through the Cast session.

await VideoPlayer.initPlayer({
  mode: 'fullscreen',
  playerId: 'main-player',
  url: 'https://example.com/video.m3u8',
  title: 'Video title',
  smallTitle: 'Optional subtitle',
  artwork: 'https://example.com/artwork.jpg',
  chromecast: true,
  showControls: true,
});

Chromecast Options

Requirements and Notes

• The media URL must be reachable by the Chromecast device, not only by the Android app.
• Cast support depends on the receiver app and device media support. MP4, HLS, DASH, and SmoothStreaming streams are mapped to Cast-compatible MIME types by the plugin.
• Widevine DRM metadata is forwarded to the Cast media item. DRM-protected streams may still require a receiver that supports your license server and DRM flow.
• Request headers used by the Android local player are not automatically available to the Chromecast receiver. Use public URLs, signed URLs, cookies supported by your receiver, or a custom receiver for secured media.

Android Picture in Picture

Picture in Picture on Android requires your app activity to declare PiP support in android/app/src/main/AndroidManifest.xml:

<activity
  android:name=".MainActivity"
  android:supportsPictureInPicture="true"
  android:launchMode="singleTask"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"
  ...>
</activity>

launchMode="singleTask" and the configChanges flags prevent the player activity from being recreated when entering or leaving PiP.

API

initPlayer(options: capVideoPlayerOptions) => Promise<capVideoPlayerResult>

isPlaying(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

play(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

pause(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

getDuration(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

getCurrentTime(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

setCurrentTime(options: capVideoTimeOptions) => Promise<capVideoPlayerResult>

getVolume(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

setVolume(options: capVideoVolumeOptions) => Promise<capVideoPlayerResult>

getMuted(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

setMuted(options: capVideoMutedOptions) => Promise<capVideoPlayerResult>

setRate(options: capVideoRateOptions) => Promise<capVideoPlayerResult>

getRate(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>

stopAllPlayers() => Promise<capVideoPlayerResult>

showController() => Promise<capVideoPlayerResult>

isControllerIsFullyVisible() => Promise<capVideoPlayerResult>

exitPlayer() => Promise<capVideoPlayerResult>