kplayer-ts 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,477 @@
+# 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`:
+
+```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);
+      },
+    },
+  },
+});
+```
+
+### 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
+```
+
+### 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: {},
+    },
+  },
+});
+
+console.log(dp.plugins.flvjs); // flv.js instance
+```
+
+### WebTorrent
+
+Requires [WebTorrent](https://github.com/webtorrent/webtorrent).
+
+```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) |
+
+Thank you to all contributors and supporters! 🙏