@capgo/capacitor-jw-player

@capgo/capacitor-jw-player

WIP: Do not use it yet, it’s in development

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

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

Installation

npm

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

yarn

yarn add @capgo/capacitor-jw-player
npx cap sync

pnpm

pnpm add @capgo/capacitor-jw-player
npx cap sync

bun

bun add @capgo/capacitor-jw-player
npx cap sync

Android Configuration

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(…)

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

Initialize the JW Player

Param	Type	Description
options	{ licenseKey: string; playerUrl?: string; }	The options for the JW Player

play(…)

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

Play a video

Param	Type	Description
options	{ mediaUrl: string; mediaType: 'video' | 'playlist'; autostart?: boolean; }	The options for the JW Player

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

Param	Type	Description
options	{ time: number; }	Options for seeking

setVolume(…)

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

Set the volume level

Param	Type	Description
options	{ volume: number; }	Options for setting volume

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

Param	Type	Description
options	{ speed: number; }	Options for setting speed

setPlaylistIndex(…)

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

Set the current item in the playlist by index

Param	Type	Description
options	{ index: number; }	Options for setting playlist item

loadPlaylist(…)

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

Load a playlist

Param	Type	Description
options	{ playlistUrl: string; }	Options for loading a playlist

loadPlaylistWithItems(…)

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

Load a playlist with items

Param	Type	Description
options	{ playlist: any[]; }	Options for loading a playlist

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

Param	Type	Description
options	{ index: number; }	Options for setting 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

Param	Type	Description
options	{ index: number; }	Options for setting captions 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:

Event	Description	Data
ready	Player is ready to use	None
play	Playback has started	None
pause	Playback is paused	{ reason: number }
complete	Playback of the current item is complete	None
time	Playback time has updated	{ position: number, duration: number }
setupError	Error during setup	{ code: number, message: string }
error	General playback error	{ code: number, message: string }
warning	Player warning	{ code: number, message: string }
playlist	Playlist has been loaded	{ playlistSize: number }
playlistItem	Current playlist item has changed	{ index: number, file: string, title: string }
playerDismissed	Player has been closed/dismissed	None