kplayer-ts 1.0.3 → 1.0.4

package/README.md

@@ -41,6 +41,99 @@ const dp = new KPlayer({
 
 ---
 
+## React / Next.js
+
+KPlayer is **SSR-safe** — importing the package never touches `window` / `document`
+at module load, so it works in Next.js (App Router or Pages Router) and during the
+server build without crashing.
+
+The player ships with a built-in `16 / 9` aspect ratio, so it stays visible even when
+the container has no explicit height. Give the container a `height` to override it.
+
+### Use the bundled component (recommended)
+
+A ready-made wrapper is published at `kplayer-ts/react`. It creates the player in
+`useEffect` and destroys it on unmount for you. `react` is an optional peer dependency.
+
+```tsx
+import { KPlayer } from "kplayer-ts/react";
+
+export function VideoPlayer({ url }: { url: string }) {
+  return (
+    <KPlayer
+      options={{ video: { url, type: "hls" } }}
+      style={{ width: "100%" }}
+    />
+  );
+}
+```
+
+In **Next.js (App Router)**, add `"use client"` at the top of the file. To access the
+underlying instance, pass a `ref` or use `onReady`:
+
+```tsx
+"use client";
+import { useRef } from "react";
+import { KPlayer, type KPlayerInstance } from "kplayer-ts/react";
+
+export default function VideoPlayer({ url }: { url: string }) {
+  const ref = useRef<KPlayerInstance>(null);
+  return (
+    <KPlayer
+      ref={ref}
+      options={{ video: { url, type: "hls" } }}
+      onReady={(player) => console.log("ready", player.version)}
+      style={{ width: "100%" }}
+    />
+  );
+}
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `options` | `Omit<KPlayerOptions, "container">` | Player options (no `container` — the component owns the `<div>`). Read once on mount; change `key` to reload. |
+| `onReady` | `(player) => void` | Called once with the instance right after creation |
+| `ref` | `Ref<KPlayerInstance>` | Receives the player instance (`null` after unmount) |
+| …rest | `HTMLAttributes<HTMLDivElement>` | `style`, `className`, etc. are forwarded to the container `<div>` |
+
+### Or wire it up manually
+
+If you prefer not to use the wrapper, create the instance yourself inside `useEffect`
+(browser only) and call `destroy()` on unmount:
+
+```tsx
+"use client";
+import { useEffect, useRef } from "react";
+import KPlayer from "kplayer-ts";
+
+export default function VideoPlayer({ url }: { url: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    const dp = new KPlayer({ container: ref.current, video: { url, type: "hls" } });
+    return () => dp.destroy();
+  }, [url]);
+  return <div ref={ref} style={{ width: "100%" }} />;
+}
+```
+
+### Loading `hls.js`
+
+`hls.js` is an external peer of the bundle — the player reads it from `window.Hls`.
+Import it and expose it before creating the player:
+
+```tsx
+import Hls from "hls.js";
+if (typeof window !== "undefined") {
+  (window as unknown as { Hls: typeof Hls }).Hls = Hls;
+}
+```
+
+Alternatively, pass your own instance via [`video.customType`](#mse-support) — that
+path does not need `window.Hls`.
+
+---
+
 ## Options
 
 | Name | Default | Description |
@@ -96,6 +189,31 @@ const dp = new KPlayer({
 | `subtitle.encrypt` | `false` | Enable AES-CBC encrypted subtitles |
 | `subtitle.key` | — | AES key (hex string, 32 chars) |
 | `subtitle.iv` | — | AES IV (hex string, 32 chars) |
+| `subtitle.keyProvider` | — | `() => { key, iv } \| Promise<{ key, iv }>` — fetch the key/iv at runtime instead of hard-coding them |
+
+> ⚠️ **Security note on encrypted subtitles.** Decryption happens **in the browser**,
+> so the `key` and `iv` can never be fully hidden from a determined user — they are
+> always recoverable from DevTools / the Network tab / the JS bundle. Subtitle
+> "encryption" here only deters *casual* scraping; it is **not** real content
+> protection. Two practical steps:
+>
+> 1. **Don't hard-code the key in your page/bundle.** Use `keyProvider` to fetch it
+>    at runtime from an authenticated backend endpoint, so the key isn't published
+>    in static source and the server can apply auth / rate-limiting / per-session keys.
+> 2. For genuine protection of the *video* itself, use DRM (EME — Widevine / PlayReady
+>    / FairPlay), not client-side AES.
+>
+> ```ts
+> subtitle: {
+>   url: [{ name: "Монгол", url: "mn.vtt", lang: "mn" }],
+>   encrypt: true,
+>   // key/iv-г bundle-д бичихгүйгээр backend-ээс татаж авна
+>   keyProvider: async () => {
+>     const res = await fetch("/api/subtitle-key", { credentials: "include" });
+>     return res.json(); // → { key: "…hex…", iv: "…hex…" }
+>   },
+> }
+> ```
 
 ### `title` options
 
@@ -458,6 +576,34 @@ const dp = new KPlayer({
 | `↓` | Volume down |
 | `Esc` | Exit web fullscreen |
 
+### Touch gestures (mobile)
+
+| Gesture | Action |
+|---|---|
+| Single tap | Show / hide controls |
+| Double-tap left half | Seek back 10s (repeat to stack: 20s, 30s…) |
+| Double-tap right half | Seek forward 10s (repeat to stack) |
+
+A YouTube-style ripple shows the seek direction and accumulated amount.
+
+---
+
+## Accessibility
+
+KPlayer ships with built-in a11y support:
+
+- All controls are real `<button>`s with localized `aria-label`s; decorative icons are
+  `aria-hidden`. The player root is a labelled `role="region"` (uses the video title).
+- The progress and volume bars are `role="slider"` with live `aria-valuenow` /
+  `aria-valuetext`, and are keyboard-operable when focused:
+  - **Seek bar**: `←` / `→` (±5s), `PageUp` / `PageDown` (±30s), `Home` / `End`.
+  - **Volume bar**: `↑` / `↓` (±5%), `Home` / `End`.
+- Settings-menu rows are `role="menuitem"`, reachable by `Tab` and activated with
+  `Enter` / `Space`.
+- A visible focus ring is shown for keyboard users (`:focus-visible`).
+
+Labels are localized in every supported `lang`.
+
 ---
 
 ## License