@vyonio/player 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+# @vyonio/player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shaka Player engine with Plyr chrome for Vyonio DRM video playback. Plyr styles and the control-icon SVG sprite ship with the package, so playback does not depend on the Plyr CDN or require it in the host's Content Security Policy. If Plyr fails to initialize, the player falls back to native `<video controls>`.
+
+> **Release availability:** source checkouts can be ahead of npm. Check available
+> versions with `npm view @vyonio/player versions`. For an unpublished checkout,
+> use `npm run verify:package` or a local `npm pack` tarball. Customer setup is in
+> the [public npm guide](https://developers.vyonio.com/npm-player/) and
+> [shared backend guide](https://developers.vyonio.com/protected-playback/).
+
+## Installation
+
+```bash
+npm install @vyonio/player
+```
+
+The ESM package bundles Shaka and Plyr and exports TypeScript declarations.
+Import `@vyonio/player/style.css` once in your application. The default API is
+`https://api.vyonio.com`; set `apiBase` only when using another environment.
+
+For a clean repository checkout, first run `npm ci --prefix packages/player`,
+then `npm ci --prefix <app>` for each app you use (`client`, `course`, `player`,
+`dash`). App build and dev scripts build the shared package before starting;
+they do not install dependencies. Run `npm --prefix packages/player run verify:package` to pack, install, type-check, and build an independent consumer.
+`npm pack` runs the library build through `prepack`. Local verification prepares
+a release artifact; publishing npm and hosted artifacts is a separate step.
+
+## Usage
+
+### Public video
+
+```js
+import { VyonioPlayer } from '@vyonio/player';
+import '@vyonio/player/style.css';
+
+const { player, destroy } = await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  autoplay: false,
+  muted: false,
+  loop: false,
+  controls: true,
+  controlItems: ['play-large', 'play', 'progress', 'current-time', 'fullscreen'],
+  settingsItems: ['quality'],
+  language: 'cs',
+  accentColor: '#7c3aed',
+  badge: {
+    text: 'AI-assisted',
+    position: 'top-right',
+    style: 'accent'
+  },
+  startSeconds: 0
+});
+```
+
+The optional playback settings are intended for hosted embeds as well as
+direct integrations. Browsers generally require `muted: true` when autoplay is
+enabled. A rejected autoplay attempt leaves the player ready for manual play.
+`controlItems` accepts Plyr control names and is ignored when `controls` is
+false. `settingsItems` accepts `quality` and `speed`; it defaults to
+`['quality']`, so playback speed is opt-in. An empty array removes the settings
+menu, and unavailable quality choices hide automatically. `language` accepts
+`en` and `cs` and defaults to English. Unsupported languages fall back to
+English. `accentColor` accepts only a six-digit hex color. Badge text is rendered
+as plain text inside Plyr's fullscreen container and is limited to 64
+characters; positions are the four corners and styles are `dark`, `light`, or
+`accent`.
+
+### Popularity histogram
+
+Pass equal-duration popularity buckets to render a YouTube-like engagement
+curve above the seek bar (white top stroke, fade-to-transparent fill). The
+overlay is non-interactive and only appears while the progress control is
+hovered or scrubbed:
+
+```js
+await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  popularityHistogram: {
+    buckets: [12, 18, 31, 24, 15]
+  }
+});
+```
+
+Each bucket spans an equal portion of the video duration, and heights are
+normalized against the largest value. The player also accepts the same array
+from `popularity_histogram.buckets` in the playback descriptor when a backend
+provides it. Explicit mount-option buckets take precedence. The current Vyonio
+Platform descriptor does not supply popularity buckets; aggregation and API
+delivery are a separate backend feature.
+
+HTML badges stay visible in normal Plyr fullscreen, but cannot be guaranteed in
+native video fallback, Picture in Picture, AirPlay, casting, or downloaded
+media. Use a burned-in watermark for compliance-critical or tamper-resistant
+marking.
+
+Fetches the video descriptor from `{apiBase}/v1/embed/{embedUuid}`, attaches a `<video>` element with Plyr controls (or native controls on Plyr failure), configures Widevine DRM, and loads the DASH manifest. Safari/FairPlay is scaffolded and throws until Apple FPS credentials are deployed.
+
+The returned handle also exposes media controls used by the hosted iframe API:
+
+```js
+const handle = await VyonioPlayer.mount(element, options);
+
+await handle.play();
+handle.pause();
+handle.seek(30);
+handle.setMuted(true);
+console.log(handle.getState());
+```
+
+`seek(seconds)` accepts a nonnegative finite number and clamps it to the known
+duration. `getState()` returns `currentTime`, `duration`, `paused`, `ended`, and
+`muted`. The underlying `HTMLVideoElement` is available as `mediaElement` for
+advanced event handling.
+
+If the descriptor includes a `telemetry` endpoint and signed context, the
+player automatically emits batched `start`, `heartbeat`, `pause`, `seek`,
+`end`, `leave`, and `error` events. Telemetry is best-effort: failures and an
+absent telemetry descriptor never interrupt playback. Pipeline credentials are
+held by the Platform API and are never exposed to the browser.
+
+Every mounted player uses a fresh random session UUID. Heartbeat, pause, end,
+and leave events close continuous watched spans with millisecond start/end,
+duration, watched time, buffering time, and playback rate. A seek closes the
+preceding span and records only its origin and destination, so skipped content
+is not counted as watched. Telemetry contains no user/member ID, stable device
+ID, fingerprint, page/referrer URL, or cross-session cookie.
+
+### Protected video (playback JWT)
+
+For a same-origin customer endpoint:
+
+```js
+const handle = await VyonioPlayer.mount(element, {
+  embedUuid: 'your-embed-uuid',
+  tokenEndpoint: '/api/playback-token',
+  tokenHeaders: { 'X-CSRF-Token': csrfToken }
+});
+```
+
+The endpoint receives `POST` JSON `{ embedUuid }` with same-origin credentials
+and must authenticate the viewer and recheck entitlement on every request.
+Return JSON `{ token, expires_in: 600 }` with `Cache-Control: no-store`.
+Keep the Vyonio API key only on your server. Customers never need Vyonio's JWT signing secret.
+`tokenEndpoint` and `getPlaybackToken` are mutually exclusive. Endpoint URLs
+must be same-origin; `tokenHeaders` cannot include Authorization. Token
+acquisition times out after 15 seconds and rejects with `PlaybackTokenError`
+(`PLAYBACK_TOKEN_FAILED` or `PLAYBACK_TOKEN_TIMEOUT`).
+
+Pass `tokenEndpoint` or `getPlaybackToken` to attach a short-lived playback JWT before the descriptor fetch. The player:
+
+- Sends `Authorization: Bearer <token>` on the descriptor request and all Shaka network requests (via a request filter)
+- Appends `access_token=<token>` to the DASH manifest URL (for AirPlay / devices that cannot send headers)
+- Replaces `access_token` on subsequent platform manifest, segment, and license request URLs after each token refresh
+- Schedules automatic refresh from the JWT `exp` claim, **120 seconds before expiry**
+- Starts refresh scheduling only after the manifest loads successfully
+- On refresh failure, marks the mount and video elements with `data-state="error"`, emits a `vyonio-player-error` event from the mount element, calls optional `onError`, then destroys the player and removes the video element
+
+```js
+const { player, destroy } = await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  onError: ({ code, message, error }) => {
+    // code is PLAYBACK_AUTH_REFRESH_FAILED for token refresh failures.
+    showPlaybackError(message);
+  },
+  getPlaybackToken: async () => {
+    const res = await fetch('/api/playback-token', {
+      method: 'POST',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      redirect: 'error',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
+      body: JSON.stringify({ embedUuid: '550e8400-e29b-41d4-a716-446655440000' })
+    });
+    if (!res.ok) throw new Error(`Token mint failed: ${res.status}`);
+    const { token } = await res.json();
+    return token;
+  }
+});
+```
+
+The `vyonio-player-error` event is a `CustomEvent` with the same `{ code, message, error }` object in `event.detail`. This lets applications surface an authentication or entitlement error even when they do not provide `onError`.
+
+When both authentication options are omitted, behavior matches the public path (no Bearer header, no manifest query param, no refresh timer).
+
+## Playback descriptor: captions and chapters
+
+The embed descriptor (`GET {apiBase}/v1/embed/{embedUuid}`) may include:
+
+```json
+{
+  "captions": [
+    {
+      "language": "cs",
+      "label": "Čeština",
+      "kind": "subtitles",
+      "vtt_url": "https://media.example/caption_tracks/1/vtt",
+      "default": true
+    }
+  ],
+  "chapters": [
+    { "title": "Intro", "start_seconds": 0 },
+    { "title": "Main", "start_seconds": 42 }
+  ]
+}
+```
+
+- **`captions`**: optional array of sidecar WebVTT tracks. Each entry supplies `language`, `label`, `kind` (`subtitles` or `captions`), authenticated `vtt_url`, and optional `default` (boolean). When `getPlaybackToken` is used, the player appends `access_token` to each `vtt_url` the same way it does for the DASH manifest.
+- **`chapters`**: optional array of chapter cues with `title` and `start_seconds`. The player builds an in-memory chapters WebVTT track for Plyr's chapter menu; cue end times are the next chapter start or video duration.
+
+When either field is absent or empty, the corresponding Plyr control stays idle.
+
+## Tests
+
+```bash
+npm test
+```
+
+## React and SSR
+
+The browser engine uses DOM globals. Import `@vyonio/player` dynamically inside
+a client effect; do not import the engine in a server-evaluated module. Import
+the CSS once through your framework's supported global CSS entry. Cancel stale
+mounts, destroy their late handles, and call `destroy()` on cleanup. The
+[public npm guide](https://developers.vyonio.com/npm-player/#react-and-server-rendering)
+contains the complete lifecycle example.
+
+See the [runnable customer example](../../examples/protected-playback/README.md)
+for the same-origin `{ embedUuid }` request, CSRF `tokenHeaders`, server-only key,
+current entitlement checks, and Node/PHP host replacement points. Its login is
+local demonstration authentication, not a production identity system. Protected
+access can be used with clear or DRM media; this package preserves your existing
+account DRM configuration and does not provision FairPlay.
+
+## Maintainer releases
+
+From the repository root, use Node 22.12+ and your own npm account with Vyonio
+publish access. Commit package changes first, leave the Git index empty, and sign
+in once with `npm login`. Use a named branch with Git `user.name`/`user.email`
+configured and no merge/rebase in progress.
+
+```sh
+# First publication of the existing package version:
+npm --prefix packages/player run release -- current --dry-run
+npm --prefix packages/player run release -- current
+
+# Later bug-fix release:
+npm --prefix packages/player run release -- patch --dry-run
+npm --prefix packages/player run release -- patch
+```
+
+Choose `minor` for a feature release or `major` for breaking changes. These commands
+accept stable versions only; prereleases need a separately reviewed release.
+The command builds a temporary copy of tracked package source, installs locked
+dependencies, runs all package tests, and verifies the tarball in an independent
+TypeScript/browser consumer. A real release asks for confirmation and uses npm's
+normal login/2FA flow. Only that verified tarball is published. It then checks
+registry integrity and installs the exact version from npm.
+
+Dry runs, cancellation and failed preparation leave your working version files
+unchanged, and create no commits or tags. After publication and registry
+installation verification, a bumped release commits only the manifest and
+lockfile, then creates an annotated `player-vX.Y.Z` tag on that exact commit.
+`current` tags the existing matching-version commit without adding an empty
+commit. The annotation records the npm artifact integrity. Existing local/origin
+tags are never overwritten. Unrelated unstaged work stays outside the release
+commit; any staged work blocks release.
+
+Review the local release commit and tag, then push them through your normal Git
+workflow. The command does not push tags or deploy hosted/docs assets. Read the
+[release runbook](../../docs/player-release.md) for first-release setup, Git/tag
+recovery and post-release documentation.