@capgo/capacitor-jw-player

Play videos and playlists from JW Player in your Capacitor app with the native JW Player SDKs on iOS and Android, in a fullscreen player.

🤖 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-jw-player in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-jw-player to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Playback: initialize() with your license key, then play(), pause(), resume(), stop() and seekTo().
• Playlists: loadPlaylist(), loadPlaylistWithItems() and setPlaylistIndex().
• Tracks: audio track and captions selection.
• Controls: setVolume(), setSpeed(), getPosition() and getState().
• Platforms: iOS, Android and Web. Uses JWPlayerKit on iOS and the JW Player Android SDK. Web uses the JW Player web player.

Play videos from jwplayer.com with a fullscreen player interface. The plugin provides a comprehensive API for controlling JW Player playback, playlists, and tracks.

The latest version of the player require a min version of IOS 15

Key Features

• Always fullscreen player
• Supports both single videos and playlists
• Complete control over playback (play, pause, seek, etc.)
• Audio track selection
• Caption/subtitle support
• Event listeners for player state changes Playes videos from jwplayer.com

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/jw-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-jw-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:

npm install @capgo/capacitor-jw-player
npx cap sync

Android

Edit build.gradle in order for the plugin to work:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://mvn.jwplayer.com/content/repositories/releases/'
        }
    }
}

Usage Examples

Basic Setup and Playback

import { JwPlayer } from '@capgo/capacitor-jw-player';

// Initialize the player with your license key
await JwPlayer.initialize({ 
  licenseKey: 'YOUR_JW_PLAYER_LICENSE_KEY' 
});

// Play a video
await JwPlayer.play({
  mediaUrl: 'https://example.com/video.mp4',
  mediaType: 'video' 
});

// Play a playlist
await JwPlayer.play({
  mediaUrl: 'https://cdn.jwplayer.com/v2/playlists/PLAYLIST_ID',
  mediaType: 'playlist'
});

Playback Controls

// Pause playback
await JwPlayer.pause();

// Resume playback
// Note: No need to call play() again with the URL, it resumes current content
await JwPlayer.play();

// Seek to a specific position (in seconds)
await JwPlayer.seekTo({ time: 30 });

// Set volume (0.0 to 1.0)
await JwPlayer.setVolume({ volume: 0.5 });

// Change playback speed
await JwPlayer.setSpeed({ speed: 1.5 });

// Stop and release the player
await JwPlayer.stop();

Working with Playlists

// Load a playlist by URL
await JwPlayer.loadPlaylist({ 
  playlistUrl: 'https://cdn.jwplayer.com/v2/playlists/PLAYLIST_ID' 
});

// Load a playlist with custom items
await JwPlayer.loadPlaylistWithItems({
  playlist: [
    { file: 'https://example.com/video1.mp4', title: 'Video 1' },
    { file: 'https://example.com/video2.mp4', title: 'Video 2' }
  ]
});

// Jump to a specific item in the playlist
await JwPlayer.setPlaylistIndex({ index: 2 });

// Get information about the current playlist
const playlistInfo = await JwPlayer.currentPlaylist();
console.log(playlistInfo.playlist);

Audio and Caption Tracks

// Get available audio tracks
const { tracks } = await JwPlayer.getAudioTracks();
console.log('Available audio tracks:', tracks);

// Get current audio track
const { index } = await JwPlayer.getCurrentAudioTrack();
console.log('Current audio track index:', index);

// Set audio track
await JwPlayer.setCurrentAudioTrack({ index: 1 });

// Get available captions
const { captions } = await JwPlayer.getCaptions();
console.log('Available captions:', captions);

// Set captions track (0 is usually "Off")
await JwPlayer.setCurrentCaptions({ index: 1 });

Event Listeners

import { JwPlayer } from '@capgo/capacitor-jw-player';

// Listen for player ready event
JwPlayer.addListener('ready', () => {
  console.log('Player is ready');
});

// Listen for playback state changes
JwPlayer.addListener('play', () => {
  console.log('Playback started');
});

JwPlayer.addListener('pause', (data) => {
  console.log('Playback paused, reason:', data.reason);
});

JwPlayer.addListener('complete', () => {
  console.log('Playback completed');
});

// Listen for time updates
JwPlayer.addListener('time', (data) => {
  console.log(`Position: ${data.position}, Duration: ${data.duration}`);
});

// Listen for playlist changes
JwPlayer.addListener('playlist', (data) => {
  console.log(`Playlist loaded with ${data.playlistSize} items`);
});

JwPlayer.addListener('playlistItem', (data) => {
  console.log(`Now playing item at index ${data.index}`);
});

// Listen for errors
JwPlayer.addListener('error', (data) => {
  console.error('Player error:', data.message);
});

// Clean up listeners when done
function cleanup() {
  JwPlayer.removeAllListeners();
}

API

• initialize(...)
• play(...)
• pause()
• resume()
• stop()
• seekTo(...)
• setVolume(...)
• getPosition()
• getState()
• setSpeed(...)
• setPlaylistIndex(...)
• loadPlaylist(...)
• loadPlaylistWithItems(...)
• getAudioTracks()
• getCurrentAudioTrack()
• setCurrentAudioTrack(...)
• getCaptions()
• getCurrentCaptions()
• setCurrentCaptions(...)
• currentPlaylist()

initialize(...)

initialize(options: { licenseKey: string; playerUrl?: string; }) => Promise<void>

Initialize the JW Player

play(...)

play(options: { mediaUrl: string; mediaType: 'video' | 'playlist'; autostart?: boolean; }) => Promise<void>

Play a video

pause()

pause() => Promise<void>

Pause the currently playing media

resume()

resume() => Promise<void>

Resume the currently paused media

stop()

stop() => Promise<void>

Stop the currently playing media

seekTo(...)

seekTo(options: { time: number; }) => Promise<void>

Seek to a specific position in the currently playing media

setVolume(...)

setVolume(options: { volume: number; }) => Promise<void>

Set the volume level

getPosition()

getPosition() => Promise<{ position: number; }>

Get the current position in the media

Returns: Promise<{ position: number; }>

getState()

getState() => Promise<{ state: number; }>

Get the current player state

Returns: Promise<{ state: number; }>

setSpeed(...)

setSpeed(options: { speed: number; }) => Promise<void>

Set the playback speed

setPlaylistIndex(...)

setPlaylistIndex(options: { index: number; }) => Promise<void>

Set the current item in the playlist by index

loadPlaylist(...)

loadPlaylist(options: { playlistUrl: string; }) => Promise<void>

Load a playlist

loadPlaylistWithItems(...)

loadPlaylistWithItems(options: { playlist: any[]; }) => Promise<void>

Load a playlist with items

getAudioTracks()

getAudioTracks() => Promise<{ tracks: any[]; }>

Get available audio tracks

Returns: Promise<{ tracks: any[]; }>

getCurrentAudioTrack()

getCurrentAudioTrack() => Promise<{ index: number; }>

Get the current audio track

Returns: Promise<{ index: number; }>

setCurrentAudioTrack(...)

setCurrentAudioTrack(options: { index: number; }) => Promise<void>

Set the current audio track

getCaptions()

getCaptions() => Promise<{ captions: any[]; }>

Get the available captions/subtitles

Returns: Promise<{ captions: any[]; }>

getCurrentCaptions()

getCurrentCaptions() => Promise<{ index: number; }>

Get the current captions/subtitles track

Returns: Promise<{ index: number; }>

setCurrentCaptions(...)

setCurrentCaptions(options: { index: number; }) => Promise<void>

Set the current captions/subtitles track

currentPlaylist()

currentPlaylist() => Promise<any>

Get the current playlist

Returns: Promise<any>

Event Listeners

The plugin emits the following events that you can listen for: