https://github.com/cap-go/capacitor-jw-player
Capacitor plugin to plays videos natively with jwplayer
https://github.com/cap-go/capacitor-jw-player
capacitor ionic jwplayer plugin
Last synced: 4 months ago
JSON representation
Capacitor plugin to plays videos natively with jwplayer
- Host: GitHub
- URL: https://github.com/cap-go/capacitor-jw-player
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-04-17T10:19:39.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-10T18:03:02.000Z (5 months ago)
- Last Synced: 2026-01-11T00:33:10.622Z (5 months ago)
- Topics: capacitor, ionic, jwplayer, plugin
- Language: Swift
- Homepage: https://capgo.app
- Size: 998 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# @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
```bash
npm install @capgo/capacitor-jw-player
npx cap sync
```
## Android
Edit `build.gradle` in order for the plugin to work:
```gradle
allprojects {
repositories {
google()
mavenCentral()
maven {
url 'https://mvn.jwplayer.com/content/repositories/releases/'
}
}
}
```
## Usage Examples
### Basic Setup and Playback
```typescript
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
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
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)
* [`play(...)`](#play)
* [`pause()`](#pause)
* [`resume()`](#resume)
* [`stop()`](#stop)
* [`seekTo(...)`](#seekto)
* [`setVolume(...)`](#setvolume)
* [`getPosition()`](#getposition)
* [`getState()`](#getstate)
* [`setSpeed(...)`](#setspeed)
* [`setPlaylistIndex(...)`](#setplaylistindex)
* [`loadPlaylist(...)`](#loadplaylist)
* [`loadPlaylistWithItems(...)`](#loadplaylistwithitems)
* [`getAudioTracks()`](#getaudiotracks)
* [`getCurrentAudioTrack()`](#getcurrentaudiotrack)
* [`setCurrentAudioTrack(...)`](#setcurrentaudiotrack)
* [`getCaptions()`](#getcaptions)
* [`getCurrentCaptions()`](#getcurrentcaptions)
* [`setCurrentCaptions(...)`](#setcurrentcaptions)
* [`currentPlaylist()`](#currentplaylist)
### initialize(...)
```typescript
initialize(options: { licenseKey: string; playerUrl?: string; }) => Promise
```
Initialize the JW Player
| Param | Type | Description |
| ------------- | -------------------------------------------------------- | ------------------------------- |
| **`options`** | { licenseKey: string; playerUrl?: string; } | - The options for the JW Player |
--------------------
### play(...)
```typescript
play(options: { mediaUrl: string; mediaType: 'video' | 'playlist'; autostart?: boolean; }) => Promise
```
Play a video
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
| **`options`** | { mediaUrl: string; mediaType: 'video' \| 'playlist'; autostart?: boolean; } | - The options for the JW Player |
--------------------
### pause()
```typescript
pause() => Promise
```
Pause the currently playing media
--------------------
### resume()
```typescript
resume() => Promise
```
Resume the currently paused media
--------------------
### stop()
```typescript
stop() => Promise
```
Stop the currently playing media
--------------------
### seekTo(...)
```typescript
seekTo(options: { time: number; }) => Promise
```
Seek to a specific position in the currently playing media
| Param | Type | Description |
| ------------- | ------------------------------ | --------------------- |
| **`options`** | { time: number; } | - Options for seeking |
--------------------
### setVolume(...)
```typescript
setVolume(options: { volume: number; }) => Promise
```
Set the volume level
| Param | Type | Description |
| ------------- | -------------------------------- | ---------------------------- |
| **`options`** | { volume: number; } | - Options for setting volume |
--------------------
### getPosition()
```typescript
getPosition() => Promise<{ position: number; }>
```
Get the current position in the media
**Returns:** Promise<{ position: number; }>
--------------------
### getState()
```typescript
getState() => Promise<{ state: number; }>
```
Get the current player state
**Returns:** Promise<{ state: number; }>
--------------------
### setSpeed(...)
```typescript
setSpeed(options: { speed: number; }) => Promise
```
Set the playback speed
| Param | Type | Description |
| ------------- | ------------------------------- | --------------------------- |
| **`options`** | { speed: number; } | - Options for setting speed |
--------------------
### setPlaylistIndex(...)
```typescript
setPlaylistIndex(options: { index: number; }) => Promise
```
Set the current item in the playlist by index
| Param | Type | Description |
| ------------- | ------------------------------- | ----------------------------------- |
| **`options`** | { index: number; } | - Options for setting playlist item |
--------------------
### loadPlaylist(...)
```typescript
loadPlaylist(options: { playlistUrl: string; }) => Promise
```
Load a playlist
| Param | Type | Description |
| ------------- | ------------------------------------- | -------------------------------- |
| **`options`** | { playlistUrl: string; } | - Options for loading a playlist |
--------------------
### loadPlaylistWithItems(...)
```typescript
loadPlaylistWithItems(options: { playlist: any[]; }) => Promise
```
Load a playlist with items
| Param | Type | Description |
| ------------- | --------------------------------- | -------------------------------- |
| **`options`** | { playlist: any[]; } | - Options for loading a playlist |
--------------------
### getAudioTracks()
```typescript
getAudioTracks() => Promise<{ tracks: any[]; }>
```
Get available audio tracks
**Returns:** Promise<{ tracks: any[]; }>
--------------------
### getCurrentAudioTrack()
```typescript
getCurrentAudioTrack() => Promise<{ index: number; }>
```
Get the current audio track
**Returns:** Promise<{ index: number; }>
--------------------
### setCurrentAudioTrack(...)
```typescript
setCurrentAudioTrack(options: { index: number; }) => Promise
```
Set the current audio track
| Param | Type | Description |
| ------------- | ------------------------------- | --------------------------------- |
| **`options`** | { index: number; } | - Options for setting audio track |
--------------------
### getCaptions()
```typescript
getCaptions() => Promise<{ captions: any[]; }>
```
Get the available captions/subtitles
**Returns:** Promise<{ captions: any[]; }>
--------------------
### getCurrentCaptions()
```typescript
getCurrentCaptions() => Promise<{ index: number; }>
```
Get the current captions/subtitles track
**Returns:** Promise<{ index: number; }>
--------------------
### setCurrentCaptions(...)
```typescript
setCurrentCaptions(options: { index: number; }) => Promise
```
Set the current captions/subtitles track
| Param | Type | Description |
| ------------- | ------------------------------- | ------------------------------------ |
| **`options`** | { index: number; } | - Options for setting captions track |
--------------------
### currentPlaylist()
```typescript
currentPlaylist() => Promise
```
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 |