@capgo/capacitor-video-player

Play videos in a native fullscreen player in your Capacitor app, with subtitles, picture in picture and Chromecast support.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-video-player in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-video-player to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Players: initPlayer() creates a player for a URL, with play(), pause() and stopAllPlayers().
• Playback control: setCurrentTime(), setVolume(), setMuted() and setRate(), with matching getters.
• Subtitles: one or more subtitle tracks with language options.
• Native extras: picture in picture, background mode, loop on end and Chromecast casting.
• Controller: showController() and isControllerIsFullyVisible() for the native controls.
• Platforms: iOS, Android and Web. Web also supports an embedded player mode.

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.

iOS Picture in Picture and background audio

On iOS the native player configures AVAudioSession for PiP and background playback when pipEnabled or bkmodeEnabled is true (both default to true). Your app still needs the right plist and capability entries:

1. In Xcode, add the Background Modes capability and enable Audio, AirPlay, and Picture in Picture.
2. In ios/App/App/Info.plist, include the audio background mode:

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>

Test PiP on a physical iPhone (the Simulator does not support Picture in Picture). Setting audioCategory: 'ambient' respects the silent switch but silences audio on screen lock; leave it unset or use playback for audible background playback.

API

• initPlayer(...)
• isPlaying(...)
• play(...)
• pause(...)
• getDuration(...)
• getCurrentTime(...)
• setCurrentTime(...)
• getVolume(...)
• setVolume(...)
• getMuted(...)
• setMuted(...)
• setRate(...)
• getRate(...)
• stopAllPlayers()
• showController()
• isControllerIsFullyVisible()
• exitPlayer()
• hidePlayer()
• showPlayer()
• getPluginVersion()
• Interfaces

initPlayer(...)

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

Initialize a video player

Returns: Promise<capVideoPlayerResult>

isPlaying(...)

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

Return if a given playerId is playing

Returns: Promise<capVideoPlayerResult>

play(...)

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

Play the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

pause(...)

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

Pause the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

getDuration(...)

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

Get the duration of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

getCurrentTime(...)

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

Get the current time of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

setCurrentTime(...)

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

Set the current time to seek the current video to from a given playerId

Returns: Promise<capVideoPlayerResult>

getVolume(...)

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

Get the volume of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

setVolume(...)

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

Set the volume of the current video to from a given playerId

Returns: Promise<capVideoPlayerResult>

getMuted(...)

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

Get the muted of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

setMuted(...)

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

Set the muted of the current video to from a given playerId

Returns: Promise<capVideoPlayerResult>

setRate(...)

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

Set the rate of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

getRate(...)

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

Get the rate of the current video from a given playerId

Returns: Promise<capVideoPlayerResult>

stopAllPlayers()

stopAllPlayers() => Promise<capVideoPlayerResult>

Stop all players playing

Returns: Promise<capVideoPlayerResult>

showController()

showController() => Promise<capVideoPlayerResult>

Show controller

Returns: Promise<capVideoPlayerResult>

isControllerIsFullyVisible()

isControllerIsFullyVisible() => Promise<capVideoPlayerResult>

isControllerIsFullyVisible

Returns: Promise<capVideoPlayerResult>

exitPlayer()

exitPlayer() => Promise<capVideoPlayerResult>

Exit player

Returns: Promise<capVideoPlayerResult>

hidePlayer()

hidePlayer() => Promise<capVideoPlayerResult>

Hide the currently presented player UI without stopping playback (native fullscreen).

Call showPlayer() to show it again.

Returns: Promise<capVideoPlayerResult>

showPlayer()

showPlayer() => Promise<capVideoPlayerResult>

Show again a previously hidden player UI (native fullscreen).

Returns: Promise<capVideoPlayerResult>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version. On web, the implementation returns "web".

Returns: Promise<{ version: string; }>

Interfaces

capVideoPlayerResult

capVideoPlayerOptions

VideoSubtitle

VideoChapter

SubTitleOptions

Optional styling for on-screen subtitles.

On iOS, colors and font size are applied through AVPlayerItem textStyleRules, which Apple documents for WebVTT only. IMSC1 and other in-manifest timed text formats are not styled through this API. Inline WebVTT cue styles can take precedence over equivalent subtitleOptions values; the plugin sets text style rules as a platform fallback, not a guaranteed override of authored cue styling.

DrmOptions

FairPlayDrmOptions

PlayreadyDrmOptions

WidevineDrmOptions

capVideoPlayerIdOptions

capVideoTimeOptions

capVideoVolumeOptions

capVideoMutedOptions

capVideoRateOptions