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

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 |