@capgo/capacitor-jw-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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

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

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

| 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 |