kplayer-ts 1.0.1 → 1.0.2

package/README.md

@@ -1,149 +1,477 @@
-## Usage
-
-```ts
-import KPlayer from 'kplayer';
-import type { KPlayerOptions } from 'kplayer';
-import 'kplayer/dist/kplayer.css';
-import Hls from 'hls.js';
-
-(window as Window & { Hls?: typeof Hls }).Hls = Hls;
-
-const container = document.getElementById('kplayer') as HTMLElement;
-
-const options: KPlayerOptions = {
-    container,
-    autoplay: false,
-    airplay: true,
-    chromecast: true,
-    theme: '#FF0000',
-    loop: true,
-    lang: 'mn',
-    screenshot: true,
-    hotkey: true,
-    preload: 'auto',
-    logo: 'https://cdn.cdn3.co/storage/image/setting/583dfa2d-a6c7-4772-89aa-147a31c16ace.png',
-    volume: 0.7,
-    mutex: true,
-    live: false,
-    playbackSpeed: [0.5, 1, 1.25, 1.5, 2],
-    preventClickToggle: false,
-
-    title: {
-        title: 'Noble Reincarnation: Born Blessed, So Ill Obtain Ultimate Power',
-        description: 'Өв залгах эрх хасалт. | 11-р анги',
-        back: true,
+# KPlayer
+
+A powerful, customizable HTML5 video player built with TypeScript.
+
+---
+
+## Installation
+
+```bash
+npm install kplayer-ts
+```
+
+Or load via CDN:
+
+```html
+<div id="kplayer"></div>
+<script src="kplayer.min.js"></script>
+```
+
+---
+
+## Quick Start
+
+```html
+<div id="kplayer"></div>
+```
+
+```typescript
+import KPlayer from "kplayer-ts";
+import type { KPlayerOptions } from "kplayer-ts";
+
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.mp4",
+    pic: "demo.jpg",
+    thumbnails: "thumbnails.jpg",
+  },
+});
+```
+
+---
+
+## Options
+
+| Name | Default | Description |
+|---|---|---|
+| `container` | `document.querySelector('.kplayer')` | Player container element |
+| `live` | `false` | Enable live mode |
+| `autoplay` | `false` | Auto play video on load |
+| `theme` | `'#b7daff'` | Main accent color |
+| `loop` | `false` | Loop video playback |
+| `lang` | `navigator.language` | UI language: `'en'`, `'mn'`, `'zh-cn'`, `'zh-tw'`, `'ko-kr'`, `'de'`, `'ja'`, `'ru'` |
+| `screenshot` | `false` | Enable screenshot button (requires CORS) |
+| `airplay` | `false` | Enable AirPlay (Safari only) |
+| `chromecast` | `false` | Enable Chromecast |
+| `hotkey` | `true` | Enable keyboard shortcuts |
+| `preload` | `'auto'` | Values: `'none'`, `'metadata'`, `'auto'` |
+| `volume` | `0.7` | Default volume (0–1). Player remembers user setting |
+| `playbackSpeed` | `[0.5, 0.75, 1, 1.25, 1.5, 2]` | Playback speed options |
+| `logo` | — | Logo URL shown in top-left corner |
+| `mutex` | `true` | Pause other players when this one starts |
+| `preventClickToggle` | `false` | Prevent play/pause toggle on player click |
+| `video` | — | Video configuration object (see below) |
+| `subtitle` | — | Subtitle configuration object (see below) |
+| `highlight` | `[]` | Time markers on the progress bar |
+| `contextmenu` | `[]` | Custom right-click menu items |
+| `title` | — | Title bar configuration |
+| `vastAD` | `false` | Enable VAST/VMAP ad support |
+| `vastADURL` | — | VAST or VMAP ad tag URL |
+| `ad` | — | Custom ad configuration |
+| `pluginOptions` | — | Options passed to MSE plugins (hls, flv, dash, webtorrent) |
+
+### `video` options
+
+| Name | Default | Description |
+|---|---|---|
+| `video.url` | — | Video URL |
+| `video.pic` | — | Video poster/thumbnail image |
+| `video.thumbnails` | — | Preview thumbnails image strip |
+| `video.type` | `'auto'` | `'auto'`, `'hls'`, `'flv'`, `'dash'`, `'webtorrent'`, `'normal'`, or custom type |
+| `video.customType` | — | Custom type handler functions (see MSE section) |
+| `video.quality` | — | Array of quality levels (see Quality Switching) |
+| `video.defaultQuality` | `0` | Default quality index |
+
+### `subtitle` options
+
+| Name | Default | Description |
+|---|---|---|
+| `subtitle.url` | required | Subtitle URL (string) or array of subtitle objects |
+| `subtitle.type` | `'webvtt'` | Subtitle format (`'webvtt'` supported) |
+| `subtitle.fontSize` | `'20px'` | Subtitle font size |
+| `subtitle.bottom` | `'40px'` | Distance from player bottom (e.g. `'10px'`, `'10%'`) |
+| `subtitle.color` | `'#fff'` | Subtitle text color |
+| `subtitle.defaultSubtitle` | — | Default subtitle lang or name |
+| `subtitle.encrypt` | `false` | Enable AES-CBC encrypted subtitles |
+| `subtitle.key` | — | AES key (hex string, 32 chars) |
+| `subtitle.iv` | — | AES IV (hex string, 32 chars) |
+
+### `title` options
+
+| Name | Default | Description |
+|---|---|---|
+| `title.title` | — | Title text |
+| `title.description` | — | Description / episode info |
+| `title.back` | `false` | Show back button |
+| `title.onBack` | — | Callback when back button is clicked |
+
+---
+
+## Full Example
+
+```typescript
+import KPlayer from "kplayer-ts";
+import type { KPlayerOptions } from "kplayer-ts";
+
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  autoplay: false,
+  theme: "#FF0000",
+  loop: true,
+  lang: "mn",
+  screenshot: true,
+  hotkey: true,
+  preload: "auto",
+  logo: "logo.png",
+  volume: 0.7,
+  mutex: true,
+  title: {
+    title: "Video Title",
+    description: "Episode 1",
+    back: true,
+  },
+  video: {
+    url: "demo.m3u8",
+    pic: "poster.jpg",
+    thumbnails: "thumbnails.jpg",
+    type: "hls",
+  },
+  pluginOptions: {
+    hls: {
+      debug: false,
+      maxBufferLength: 30,
+    },
+  },
+  subtitle: {
+    url: [
+      { name: "English", url: "en.vtt", lang: "en" },
+      { name: "Монгол", url: "mn.vtt", lang: "mn" },
+    ],
+    defaultSubtitle: "mn",
+    fontSize: "25px",
+    bottom: "10%",
+    color: "#ffffff",
+  },
+  highlight: [
+    { text: "OP Start", time: 20 },
+    { text: "OP End", time: 120 },
+    { text: "END Start", time: 520 },
+    { text: "END End", time: 550 },
+  ],
+  contextmenu: [
+    { text: "GitHub", link: "https://github.com/kenji-07" },
+    {
+      text: "Log player",
+      click: (player) => console.log(player),
+    },
+  ],
+});
+```
+
+---
+
+## API
+
+```typescript
+dp.play()                                          // Play video
+dp.pause()                                         // Pause video
+dp.toggle()                                        // Toggle play/pause
+dp.seek(time: number)                              // Seek to time in seconds
+dp.speed(rate: number)                             // Set playback rate
+dp.volume(percentage, nostorage?, nonotice?)       // Set volume (0–1)
+dp.notice(text, time?, opacity?)                   // Show notification
+dp.switchQuality(index: number)                    // Switch quality (manual list)
+dp.destroy()                                       // Destroy player instance
+```
+
+### Properties
+
+```typescript
+dp.video              // Native HTMLVideoElement
+dp.video.currentTime  // Current playback position (seconds)
+dp.video.duration     // Total duration (seconds)
+dp.video.paused       // Whether video is paused
+dp.plugins.hls        // hls.js instance (when type: 'hls')
+dp.plugins.flvjs      // flv.js instance (when type: 'flv')
+dp.plugins.dash       // dash.js instance (when type: 'dash')
+```
+
+### Fullscreen
+
+```typescript
+dp.fullScreen.request('browser')   // Browser fullscreen
+dp.fullScreen.request('web')       // Web (page-level) fullscreen
+dp.fullScreen.cancel('browser')
+dp.fullScreen.cancel('web')
+dp.fullScreen.toggle('browser')
+dp.fullScreen.toggle('web')
+```
+
+---
+
+## Events
+
+```typescript
+dp.on('play', () => console.log('playing'));
+dp.on('ended', () => console.log('ended'));
+```
+
+### Video Events
+
+`abort` · `canplay` · `canplaythrough` · `durationchange` · `emptied` · `ended` · `error` · `loadeddata` · `loadedmetadata` · `loadstart` · `pause` · `play` · `playing` · `progress` · `ratechange` · `seeked` · `seeking` · `stalled` · `suspend` · `timeupdate` · `volumechange` · `waiting`
+
+### Player Events
+
+`screenshot` · `thumbnails_show` · `thumbnails_hide` · `contextmenu_show` · `contextmenu_hide` · `notice_show` · `notice_hide` · `quality_start` · `quality_end` · `destroy` · `resize` · `fullscreen` · `fullscreen_cancel` · `webfullscreen` · `webfullscreen_cancel` · `subtitle_show` · `subtitle_hide` · `subtitle_change` · `title_back`
+
+---
+
+## Quality Switching
+
+### Manual quality list
+
+Provide a `quality` array with names and URLs. The player renders a quality menu automatically.
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    quality: [
+      { name: "HD", url: "demo.m3u8", type: "hls" },
+      { name: "SD", url: "demo.mp4", type: "normal" },
+    ],
+    defaultQuality: 0,
+    pic: "poster.jpg",
+    thumbnails: "thumbnails.jpg",
+  },
+});
+```
+
+### HLS adaptive quality (auto)
+
+When `type: 'hls'` is used, KPlayer automatically builds a quality menu from the HLS manifest levels, including an **Auto** option. Switching triggers `switching-quality` and `switched-quality` notices.
+
+---
+
+## MSE Support
+
+### HLS
+
+Requires [hls.js](https://github.com/video-dev/hls.js).
+
+```typescript
+import Hls from "hls.js";
+(window as any).Hls = Hls;
+
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.m3u8",
+    type: "hls",
+  },
+  pluginOptions: {
+    hls: {
+      debug: false,
+      maxBufferLength: 30,
+      startLevel: -1,           // -1 = auto
+      abrBandWidthFactor: 0.95,
+      fragLoadingMaxRetry: 6,
+      enableWorker: true,
+      // Request headers
+      xhrSetup: (xhr, url) => {
+        xhr.setRequestHeader("Authorization", "Bearer your-token");
+      },
     },
+  },
+});
+
+console.log(dp.plugins.hls); // hls.js instance
+```
+
+Using `customType`:
 
-    vastAD: false,
-    vastADURL: 'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpost&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator=',
-
-    // ── Single HLS video ────────────────────────────────────────────────
-    // video: {
-    //     url: 'https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_ts/master.m3u8',
-    //     pic: 'https://image.tmdb.org/t/p/original/nAxGnGHOsfzufThz20zgmRwKur3.jpg',
-    //     thumbnails: 'https://image.tmdb.org/t/p/original/nAxGnGHOsfzufThz20zgmRwKur3.jpg',
-    //     type: 'hls',
-    // },
-
-    // ── Ad examples ─────────────────────────────────────────────────────
-    ad: {
-        url: [
-            {
-                name: 'Image ad',
-                type: 'image',
-                backroundColor: '',
-                url: 'https://cdn.cdn3.co/storage/image/setting/583dfa2d-a6c7-4772-89aa-147a31c16ace.png',
-                deeplink: '',
-                startTime: 0,
-                skipTime: 10,
-            },
-            {
-                name: 'Text ad',
-                type: 'text',
-                backroundColor: 'FF0000',
-                url: 'Hello users ads watching',
-                deeplink: '',
-                startTime: 120,
-                skipTime: 10,
-            },
-            {
-                name: 'Video ad',
-                type: 'video',
-                backroundColor: '',
-                url: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-                deeplink: '',
-                startTime: 130,
-                skipTime: 10,
-            },
-        ],
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.m3u8",
+    type: "customHls",
+    customType: {
+      customHls: (video, player) => {
+        const hls = new Hls({ debug: false });
+        hls.loadSource(video.src);
+        hls.attachMedia(video);
+      },
     },
+  },
+});
+```
 
-    // ── Multi quality ────────────────────────────────────────────────────
-    video: {
-        quality: [
-            {
-                name: 'HD',
-                url: 'https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_ts/master.m3u8',
-                type: 'normal',
-            },
-            {
-                name: 'SD',
-                url: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-                type: 'normal',
-            },
-        ],
-        defaultQuality: 0,
-        pic: 'https://image.tmdb.org/t/p/original/nAxGnGHOsfzufThz20zgmRwKur3.jpg',
-        thumbnails: 'https://image.tmdb.org/t/p/original/nAxGnGHOsfzufThz20zgmRwKur3.jpg',
+### MPEG-DASH
+
+Requires [dash.js](https://github.com/Dash-Industry-Forum/dash.js).
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.mpd",
+    type: "dash",
+  },
+  pluginOptions: {
+    dash: {
+      // dash.js config
     },
+  },
+});
+
+console.log(dp.plugins.dash); // dash.js instance
+```
 
-    subtitle: {
-        url: [
-            {
-                name: 'English',
-                url: 'http://cdn.cdn3.co/storage/subtitle/e67dbcf0-96b2-4265-b787-680124cb9077.vtt',
-                lang: 'en',
-            },
-            {
-                name: 'Монгол',
-                url: 'http://cdn.cdn3.co/storage/subtitle/e67dbcf0-96b2-4265-b787-680124cb9077.vtt',
-                lang: 'mn',
-            },
-            {
-                name: '日本語',
-                url: 'https://raw.githubusercontent.com/videojs/video.js/main/docs/examples/shared/example-captions.vtt',
-                lang: 'ja',
-            },
-        ],
-        defaultSubtitle: 'mn',
-        type: 'webvtt',
-        fontSize: '25px',
-        bottom: '10%',
-        color: '#ffffff',
-        encrypt: false,
-        iv: '',
-        key: '',
+### FLV
+
+Requires [flv.js](https://github.com/bilibili/flv.js).
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.flv",
+    type: "flv",
+  },
+  pluginOptions: {
+    flv: {
+      mediaDataSource: {},
+      config: {},
     },
+  },
+});
 
-    contextmenu: [
-        {
-            text: 'custom1',
-            link: 'https://github.com/DIYgod/DPlayer',
-        },
-        {
-            text: 'custom2',
-            click: (player) => {
-                console.log(player);
-            },
-        },
-    ],
+console.log(dp.plugins.flvjs); // flv.js instance
+```
+
+### WebTorrent
+
+Requires [WebTorrent](https://github.com/webtorrent/webtorrent).
 
-    highlight: [
-        { text: 'OP Start', time: 20 },
-        { text: 'OP End',   time: 120 },
-        { text: 'END Start', time: 520 },
-        { text: 'END End',   time: 550 },
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "magnet:?xt=...",
+    type: "webtorrent",
+  },
+  pluginOptions: {
+    webtorrent: {
+      // WebTorrent config
+    },
+  },
+});
+
+console.log(dp.plugins.webtorrent); // WebTorrent instance
+```
+
+### Custom MSE library
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: {
+    url: "demo.m3u8",
+    type: "customHls",
+    customType: {
+      customHls: (video, player) => {
+        const hls = new Hls({
+          p2pConfig: { live: false },
+        });
+        hls.loadSource(video.src);
+        hls.attachMedia(video);
+      },
+    },
+  },
+});
+```
+
+---
+
+## Ads
+
+### Custom ads (image / text / video)
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: { url: "demo.mp4" },
+  ad: {
+    url: [
+      {
+        name: "Intro image ad",
+        type: "image",
+        url: "ad-banner.png",
+        deeplink: "https://example.com",
+        startTime: 0,
+        skipTime: 5,
+      },
+      {
+        name: "Mid-roll video ad",
+        type: "video",
+        url: "ad-video.mp4",
+        startTime: 120,
+        skipTime: 10,
+      },
+      {
+        name: "Text ad",
+        type: "text",
+        url: "Special offer – click to learn more",
+        backroundColor: "FF0000",
+        deeplink: "https://example.com",
+        startTime: 300,
+        skipTime: 5,
+      },
     ],
-};
+  },
+});
+```
+
+### VAST / VMAP
+
+```typescript
+const dp = new KPlayer({
+  container: document.getElementById("kplayer"),
+  video: { url: "demo.mp4" },
+  vastAD: true,
+  vastADURL: "https://your-ad-server.com/vmap.xml",
+});
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| `Space` | Play / Pause |
+| `←` | Seek back 10s |
+| `→` | Seek forward 10s |
+| `↑` | Volume up |
+| `↓` | Volume down |
+| `Esc` | Exit web fullscreen |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Donation
+
+If KPlayer has been useful to you, consider supporting its development. Your contribution helps keep the project maintained and growing.
+
+| Platform | Link |
+|---|---|
+| 💖 GitHub Sponsors | [github.com/sponsors/kenji-07](https://github.com/sponsors/kenji-07) |
 
-const player = new KPlayer(options);
+Thank you to all contributors and supporters! 🙏