@guardvideo/player-sdk 1.0.2 → 1.2.0

package/README.md

@@ -1,26 +1,28 @@
 # GuardVideo Player SDK
 
-🎬 **Secure HLS video player with embed token authentication for React, Next.js, and vanilla JavaScript**
+🎬 **Secure HLS video player with embed token authentication — React, Next.js, and vanilla JavaScript**
 
 [![npm version](https://img.shields.io/npm/v/@guardvideo/player-sdk.svg)](https://www.npmjs.com/package/@guardvideo/player-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-✅ **Adaptive Bitrate Streaming** - Automatic quality switching based on network conditions  
-✅ **Secure Token Authentication** - API key never exposed to browser  
-✅ **Multi-Quality Support** - 1080p, 720p, 480p, 360p  
-✅ **AES-128 Encryption** - Secure video segment delivery  
-✅ **React & Next.js Support** - First-class TypeScript support  
-✅ **Vanilla JS Support** - Use without any framework  
-✅ **TypeScript Types** - Full type safety included  
-✅ **Browser Support** - All modern browsers + Safari/iOS native HLS  
+✅ **Custom Professional Player UI** — No native browser controls; full custom design  
+✅ **Adaptive Bitrate Streaming** — Automatic quality switching based on network conditions  
+✅ **Secure Token Authentication** — API key never exposed to the browser  
+✅ **Multi-Quality Support** — 1080p, 720p, 480p, 360p  
+✅ **AES-128 Encryption** — Secure video segment delivery  
+✅ **Forensic Watermark** — Viewer-identifying overlay baked into playback (default: on)  
+✅ **React & Next.js Support** — First-class TypeScript support  
+✅ **Vanilla JS / CDN Support** — Full custom UI without any framework  
+✅ **TypeScript Types** — Full type safety included  
+✅ **Browser Support** — All modern browsers + Safari/iOS native HLS  
 
 ---
 
 ## Installation
 
-### NPM/Yarn (for React/Next.js)
+### NPM / Yarn (React / Next.js)
 
 ```bash
 npm install @guardvideo/player-sdk
@@ -28,43 +30,52 @@ npm install @guardvideo/player-sdk
 yarn add @guardvideo/player-sdk
 ```
 
-### CDN (for vanilla JavaScript)
+### CDN (Vanilla JavaScript)
 
 ```html
+<!-- full bundle (recommended for development) -->
 <script src="https://cdn.jsdelivr.net/npm/@guardvideo/player-sdk@latest/dist/vanilla/guardvideo-player.js"></script>
+
+<!-- minified bundle (recommended for production) -->
+<script src="https://cdn.jsdelivr.net/npm/@guardvideo/player-sdk@latest/dist/vanilla/guardvideo-player.min.js"></script>
 ```
 
 ---
 
 ## Quick Start
 
-### React Component
+### React / Next.js Component
 
 ```tsx
 import { GuardVideoPlayer } from '@guardvideo/player-sdk';
 
-function App() {
+function VideoPage() {
   return (
     <GuardVideoPlayer
       videoId="your-video-id"
       embedTokenEndpoint="/api/embed-token"
       width="100%"
       height="500px"
-      autoplay={false}
-      controls={true}
+      viewerEmail="user@example.com"
+      viewerName="Jane Doe"
+      forensicWatermark    // default: true
       onReady={() => console.log('Video ready!')}
       onError={(error) => console.error(error)}
+      onQualityChange={(quality) => console.log('Quality:', quality)}
+      onStateChange={(state) => console.log('State:', state)}
     />
   );
 }
 ```
 
-### React Hook
+> **Note:** The component renders a fully custom player UI with play/pause, seek bar, volume control, quality selector, playback speed menu, and fullscreen. You do **not** need to add the native `controls` attribute or wrap it in any overlay.
+
+### React Hook (build your own controls)
 
 ```tsx
 import { useGuardVideoPlayer } from '@guardvideo/player-sdk';
 
-function VideoPlayer({ videoId }: { videoId: string }) {
+function CustomPlayer({ videoId }: { videoId: string }) {
   const {
     videoRef,
     isReady,
@@ -75,31 +86,38 @@ function VideoPlayer({ videoId }: { videoId: string }) {
     play,
     pause,
     seek,
+    setVolume,
     setQuality,
   } = useGuardVideoPlayer({
     videoId,
     embedTokenEndpoint: '/api/embed-token',
-    debug: true,
+    viewerEmail: 'user@example.com',
   });
 
+  const formatTime = (s: number) =>
+    `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
+
   return (
     <div>
-      <video ref={videoRef} style={{ width: '100%', height: 'auto' }} />
-      
-      <div>
-        <button onClick={play}>Play</button>
-        <button onClick={pause}>Pause</button>
-        <span>{currentTime} / {duration}</span>
-      </div>
-
-      <select onChange={(e) => setQuality(Number(e.target.value))}>
-        <option value="-1">Auto</option>
-        {qualityLevels.map((level) => (
-          <option key={level.index} value={level.index}>
-            {level.name}
-          </option>
-        ))}
-      </select>
+      <video ref={videoRef} style={{ width: '100%' }} />
+      {isReady && (
+        <div>
+          <button onClick={isPlaying ? pause : play}>
+            {isPlaying ? 'Pause' : 'Play'}
+          </button>
+          <input
+            type="range" min={0} max={duration} value={currentTime}
+            onChange={(e) => seek(Number(e.target.value))}
+          />
+          <span>{formatTime(currentTime)} / {formatTime(duration)}</span>
+          <select onChange={(e) => setQuality(Number(e.target.value))}>
+            <option value="-1">Auto</option>
+            {qualityLevels.map((l) => (
+              <option key={l.index} value={l.index}>{l.name}</option>
+            ))}
+          </select>
+        </div>
+      )}
     </div>
   );
 }
@@ -108,149 +126,72 @@ function VideoPlayer({ videoId }: { videoId: string }) {
 ### Next.js App Router
 
 ```tsx
+// app/watch/[videoId]/page.tsx
 'use client';
 
 import { GuardVideoPlayer } from '@guardvideo/player-sdk';
 
-export default function VideoPage({ params }: { params: { videoId: string } }) {
+export default function WatchPage({ params }: { params: { videoId: string } }) {
   return (
-    <div className="container">
-      <h1>Watch Video</h1>
-      <GuardVideoPlayer
-        videoId={params.videoId}
-        embedTokenEndpoint="/api/embed-token"
-        width="100%"
-        height="600px"
-        autoplay={false}
-        controls={true}
-        onReady={() => console.log('Ready!')}
-        onError={(error) => console.error('Error:', error)}
-        onQualityChange={(quality) => console.log('Quality:', quality)}
-      />
-    </div>
+    <GuardVideoPlayer
+      videoId={params.videoId}
+      embedTokenEndpoint="/api/embed-token"
+      width="100%"
+      height="600px"
+      viewerEmail="user@example.com"
+      onReady={() => console.log('Ready!')}
+      onError={(e) => console.error(e)}
+    />
   );
 }
 ```
 
-### Vanilla JavaScript
+### Vanilla JavaScript (CDN)
 
 ```html
 <!DOCTYPE html>
-<html>
+<html lang="en">
 <head>
+  <meta charset="UTF-8" />
   <title>GuardVideo Player</title>
   <style>
-    #video-container {
+    #player-container {
       width: 100%;
-      max-width: 800px;
+      max-width: 900px;
       aspect-ratio: 16/9;
-      margin: 0 auto;
+      margin: 40px auto;
     }
   </style>
 </head>
 <body>
-  <div id="video-container"></div>
+  <div id="player-container"></div>
 
-  <script src="https://cdn.jsdelivr.net/npm/@guardvideo/player-sdk@latest/dist/vanilla/guardvideo-player.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@guardvideo/player-sdk@latest/dist/vanilla/guardvideo-player.min.js"></script>
   <script>
-    // Create player
-    const player = GuardVideoPlayer.create('video-container', 'your-video-id', {
+    const player = GuardVideoPlayer.create('player-container', 'your-video-id', {
       embedTokenEndpoint: '/api/embed-token',
-      debug: true,
-      autoplay: false,
-      controls: true,
-      onReady: function() {
-        console.log('Video is ready!');
-        console.log('Available qualities:', player.getQualityLevels());
+      viewerEmail: 'user@example.com',
+      viewerName: 'Jane Doe',
+
+      onReady: function () {
+        console.log('Ready! Qualities:', player.getQualityLevels());
       },
-      onError: function(error) {
-        console.error('Player error:', error);
+      onError: function (err) {
+        console.error('Player error:', err);
       },
-      onQualityChange: function(quality) {
+      onQualityChange: function (quality) {
         console.log('Quality changed to:', quality);
       },
-      onStateChange: function(state) {
+      onStateChange: function (state) {
         console.log('State:', state);
-      }
-    });
-
-    // Control the player
-    document.getElementById('play-btn').addEventListener('click', function() {
-      player.play();
-    });
-
-    document.getElementById('pause-btn').addEventListener('click', function() {
-      player.pause();
-    });
-
-    document.getElementById('quality-select').addEventListener('change', function(e) {
-      player.setQuality(parseInt(e.target.value));
+      },
     });
   </script>
 </body>
 </html>
 ```
 
----
-
-## API Reference
-
-### PlayerConfig
-
-```typescript
-interface PlayerConfig {
-  // Required
-  embedTokenEndpoint: string;  // Your backend API endpoint
-
-  // Optional
-  apiBaseUrl?: string;          // Video API base URL
-  debug?: boolean;              // Enable debug logging (default: false)
-  autoplay?: boolean;           // Auto-play on load (default: false)
-  controls?: boolean;           // Show controls (default: true)
-  className?: string;           // CSS class name
-  style?: CSSProperties;        // Inline styles
-  hlsConfig?: HlsConfig;        // HLS.js config overrides
-
-  // Callbacks
-  onReady?: () => void;
-  onError?: (error: PlayerError) => void;
-  onQualityChange?: (quality: string) => void;
-  onStateChange?: (state: PlayerState) => void;
-}
-```
-
-### Player Methods
-
-```typescript
-interface PlayerInstance {
-  play(): Promise<void>;                    // Play video
-  pause(): void;                            // Pause video
-  getCurrentTime(): number;                 // Get current time (seconds)
-  seek(time: number): void;                 // Seek to time (seconds)
-  getDuration(): number;                    // Get duration (seconds)
-  getVolume(): number;                      // Get volume (0-1)
-  setVolume(volume: number): void;          // Set volume (0-1)
-  getQualityLevels(): QualityLevel[];       // Get available qualities
-  getCurrentQuality(): QualityLevel | null; // Get current quality
-  setQuality(levelIndex: number): void;     // Set quality (-1 for auto)
-  getState(): PlayerState;                  // Get current state
-  destroy(): void;                          // Cleanup and destroy
-}
-```
-
-### Player States
-
-```typescript
-enum PlayerState {
-  IDLE = 'idle',           // Not initialized
-  LOADING = 'loading',     // Loading video
-  READY = 'ready',         // Ready to play
-  PLAYING = 'playing',     // Currently playing
-  PAUSED = 'paused',       // Paused
-  BUFFERING = 'buffering', // Buffering
-  ERROR = 'error',         // Error occurred
-}
-```
+> The vanilla build bundles **everything** (hls.js included). No npm install, no bundler needed. The player renders the same full custom UI as the React component.
 
 ---
 
@@ -264,27 +205,28 @@ export async function POST(
   request: Request,
   { params }: { params: { videoId: string } }
 ) {
-  const VIDEO_API_KEY = process.env.VIDEO_API_KEY;
-  const VIDEO_API_BASE = process.env.NEXT_PUBLIC_VIDEO_API_BASE;
+  const VIDEO_API_KEY  = process.env.VIDEO_API_KEY!;
+  const VIDEO_API_BASE = process.env.NEXT_PUBLIC_VIDEO_API_BASE!;
 
   const response = await fetch(
     `${VIDEO_API_BASE}/videos/${params.videoId}/embed-token`,
     {
       method: 'POST',
       headers: {
-        'X-API-Key': VIDEO_API_KEY,  // API key stays on server!
-        'Content-Type': 'application/json'
+        'X-API-Key': VIDEO_API_KEY,   // API key stays on the server!
+        'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         allowedDomain: request.headers.get('origin'),
         expiresInMinutes: 120,
-        maxViews: null
-      })
+        maxViews: null,
+        viewerEmail: /* optionally forward from session */ undefined,
+        forensicWatermark: true,
+      }),
     }
   );
 
-  const embedData = await response.json();
-  return Response.json(embedData);
+  return Response.json(await response.json());
 }
 ```
 
@@ -297,86 +239,117 @@ NEXT_PUBLIC_VIDEO_API_BASE=http://localhost:3001
 
 ---
 
-## Advanced Usage
+## API Reference
 
-### Custom Controls with React Hook
+### React Component Props (`GuardVideoPlayerProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `videoId` | `string` | — | **Required.** Video ID to load |
+| `embedTokenEndpoint` | `string` | — | **Required.** Your backend endpoint that mints embed tokens |
+| `width` | `string \| number` | `"100%"` | Player container width |
+| `height` | `string \| number` | `"auto"` | Player container height |
+| `apiBaseUrl` | `string` | — | Override default API base URL |
+| `autoplay` | `boolean` | `false` | Auto-play on load |
+| `debug` | `boolean` | `false` | Enable verbose debug logging |
+| `viewerName` | `string` | — | Viewer name (used for forensic watermark) |
+| `viewerEmail` | `string` | — | Viewer email (used for forensic watermark) |
+| `forensicWatermark` | `boolean` | `true` | Show viewer-identifying watermark overlay |
+| `branding` | `BrandingConfig` | — | Custom accent colour and brand name |
+| `security` | `SecurityConfig` | — | Security hardening options |
+| `contextMenuItems` | `ContextMenuItem[]` | — | Extra context menu items |
+| `hlsConfig` | `HlsConfig` | — | HLS.js configuration overrides |
+| `onReady` | `() => void` | — | Called when video is ready to play |
+| `onError` | `(err: PlayerError) => void` | — | Called on error |
+| `onQualityChange` | `(quality: string) => void` | — | Called when quality changes |
+| `onStateChange` | `(state: PlayerState) => void` | — | Called on state transitions |
+| `onTimeUpdate` | `(time: number) => void` | — | Called on time updates |
+| `onEnded` | `() => void` | — | Called when video ends |
+
+### Vanilla JS Config (`PlayerConfig`)
+
+All React props above except JSX-specific ones (`className`, `style`) are available.
+Extra vanilla-only props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | Player container width CSS value |
+| `height` | `string` | `"auto"` | Player container height CSS value |
 
-```tsx
-function CustomVideoPlayer({ videoId }: { videoId: string }) {
-  const {
-    videoRef,
-    isReady,
-    isPlaying,
-    currentTime,
-    duration,
-    volume,
-    qualityLevels,
-    currentQuality,
-    play,
-    pause,
-    seek,
-    setVolume,
-    setQuality,
-  } = useGuardVideoPlayer({
-    videoId,
-    embedTokenEndpoint: '/api/embed-token',
-    debug: true,
-  });
+### Player Methods
 
-  const formatTime = (seconds: number) => {
-    const mins = Math.floor(seconds / 60);
-    const secs = Math.floor(seconds % 60);
-    return `${mins}:${secs.toString().padStart(2, '0')}`;
-  };
+```typescript
+player.play(): Promise<void>           // Start playback
+player.pause(): void                   // Pause
+player.seek(time: number): void        // Seek to time in seconds
+player.getCurrentTime(): number        // Current playback position (seconds)
+player.getDuration(): number           // Total duration (seconds)
+player.getVolume(): number             // Current volume (0–1)
+player.setVolume(v: number): void      // Set volume (0–1)
+player.getQualityLevels(): QualityLevel[]       // Available quality levels
+player.getCurrentQuality(): QualityLevel | null // Active quality
+player.setQuality(index: number): void          // Set quality (-1 = auto)
+player.getState(): PlayerState         // Current player state
+player.getVideoElement(): HTMLVideoElement | null  // Underlying <video> element
+player.destroy(): void                 // Clean up and remove player
+```
 
-  return (
-    <div className="video-player">
-      <video ref={videoRef} className="video-element" />
-      
-      {isReady && (
-        <div className="controls">
-          <button onClick={isPlaying ? pause : play}>
-            {isPlaying ? 'Pause' : 'Play'}
-          </button>
+### Player States
 
-          <input
-            type="range"
-            min="0"
-            max={duration}
-            value={currentTime}
-            onChange={(e) => seek(Number(e.target.value))}
-          />
+```typescript
+enum PlayerState {
+  IDLE      = 'idle',       // Not yet initialized
+  LOADING   = 'loading',    // Loading video
+  READY     = 'ready',      // Ready to play
+  PLAYING   = 'playing',    // Currently playing
+  PAUSED    = 'paused',     // Paused
+  BUFFERING = 'buffering',  // Re-buffering mid-play
+  ERROR     = 'error',      // Unrecoverable error
+}
+```
 
-          <span>{formatTime(currentTime)} / {formatTime(duration)}</span>
+### BrandingConfig
 
-          <input
-            type="range"
-            min="0"
-            max="1"
-            step="0.1"
-            value={volume}
-            onChange={(e) => setVolume(Number(e.target.value))}
-          />
+```typescript
+interface BrandingConfig {
+  accentColor?: string;   // Hex color, default: '#44c09b'
+  name?: string;          // Brand name shown in secure badge, default: 'GuardVideo'
+  logoUrl?: string;       // Logo URL (used in context menu)
+  websiteUrl?: string;    // Website URL (used in context menu)
+}
+```
 
-          <select
-            value={currentQuality?.index ?? -1}
-            onChange={(e) => setQuality(Number(e.target.value))}
-          >
-            <option value="-1">Auto Quality</option>
-            {qualityLevels.map((level) => (
-              <option key={level.index} value={level.index}>
-                {level.name} ({Math.round(level.bitrate / 1000)}kbps)
-              </option>
-            ))}
-          </select>
-        </div>
-      )}
-    </div>
-  );
+### SecurityConfig
+
+```typescript
+interface SecurityConfig {
+  disableContextMenu?: boolean;    // Block right-click (default: true)
+  disableDevTools?: boolean;       // Detect/block DevTools (default: false)
+  disablePiP?: boolean;            // Block Picture-in-Picture (default: false)
+  disableDragDrop?: boolean;       // Block drag-and-drop (default: true)
+  disableScreenshot?: boolean;     // Attempt screenshot blocking (default: false)
 }
 ```
 
-### Using Ref for Imperative Control
+---
+
+## Keyboard Shortcuts
+
+When the player has focus:
+
+| Key | Action |
+|-----|--------|
+| `Space` / `K` | Play / Pause |
+| `←` | Seek back 5 s |
+| `→` | Seek forward 5 s |
+| `↑` | Volume +10% |
+| `↓` | Volume −10% |
+| `M` | Toggle mute |
+| `F` | Toggle fullscreen |
+
+---
+
+## Using Ref for Imperative Control (React)
 
 ```tsx
 import { useRef } from 'react';
@@ -385,17 +358,6 @@ import { GuardVideoPlayer, GuardVideoPlayerRef } from '@guardvideo/player-sdk';
 function VideoWithRef() {
   const playerRef = useRef<GuardVideoPlayerRef>(null);
 
-  const handleSkipForward = () => {
-    if (playerRef.current) {
-      const currentTime = playerRef.current.getCurrentTime();
-      playerRef.current.seek(currentTime + 10);
-    }
-  };
-
-  const handleChangeQuality = (qualityIndex: number) => {
-    playerRef.current?.setQuality(qualityIndex);
-  };
-
   return (
     <div>
       <GuardVideoPlayer
@@ -403,7 +365,9 @@ function VideoWithRef() {
         videoId="your-video-id"
         embedTokenEndpoint="/api/embed-token"
       />
-      <button onClick={handleSkipForward}>Skip +10s</button>
+      <button onClick={() => playerRef.current?.seek(playerRef.current.getCurrentTime() + 10)}>
+        +10 s
+      </button>
     </div>
   );
 }
@@ -413,8 +377,6 @@ function VideoWithRef() {
 
 ## TypeScript Support
 
-The SDK is written in TypeScript and includes full type definitions:
-
 ```typescript
 import type {
   PlayerConfig,
@@ -422,7 +384,8 @@ import type {
   PlayerState,
   PlayerError,
   QualityLevel,
-  EmbedTokenResponse,
+  BrandingConfig,
+  SecurityConfig,
 } from '@guardvideo/player-sdk';
 ```
 
@@ -430,12 +393,14 @@ import type {
 
 ## Browser Support
 
-- ✅ Chrome 90+
-- ✅ Firefox 88+
-- ✅ Safari 14+ (native HLS)
-- ✅ Edge 90+
-- ✅ iOS Safari 14+
-- ✅ Android Chrome 90+
+| Browser | Minimum version |
+|---------|----------------|
+| Chrome  | 90+ |
+| Firefox | 88+ |
+| Safari  | 14+ (native HLS) |
+| Edge    | 90+ |
+| iOS Safari | 14+ |
+| Android Chrome | 90+ |
 
 ---
 
@@ -447,12 +412,98 @@ MIT © GuardVideo
 
 ## Support
 
-For issues and questions:
 - GitHub Issues: [github.com/guardvideo/player-sdk](https://github.com/guardvideo/player-sdk)
 - Documentation: [docs.guardvideo.com](https://docs.guardvideo.com)
+| `Space` / `K` | Play / Pause |
+| `←` | Seek back 5 s |
+| `→` | Seek forward 5 s |
+| `↑` | Volume +10% |
+| `↓` | Volume −10% |
+| `M` | Toggle mute |
+| `F` | Toggle fullscreen |
 
 ---
 
-## Contributing
+## Using Ref for Imperative Control (React)
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
+```tsx
+import { useRef } from 'react';
+import { GuardVideoPlayer, GuardVideoPlayerRef } from '@guardvideo/player-sdk';
+
+function VideoWithRef() {
+  const playerRef = useRef<GuardVideoPlayerRef>(null);
+
+  return (
+    <div>
+      <GuardVideoPlayer
+        ref={playerRef}
+        videoId="your-video-id"
+        embedTokenEndpoint="/api/embed-token"
+      />
+      <button onClick={() => playerRef.current?.seek(playerRef.current.getCurrentTime() + 10)}>
+        +10 s
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## TypeScript Support
+
+```typescript
+import type {
+  PlayerConfig,
+  PlayerInstance,
+  PlayerState,
+  PlayerError,
+  QualityLevel,
+  BrandingConfig,
+  SecurityConfig,
+} from '@guardvideo/player-sdk';
+```
+
+---
+
+## Browser Support
+
+| Browser | Minimum version |
+|---------|----------------|
+| Chrome  | 90+ |
+| Firefox | 88+ |
+| Safari  | 14+ (native HLS) |
+| Edge    | 90+ |
+| iOS Safari | 14+ |
+| Android Chrome | 90+ |
+
+---
+
+## License
+
+MIT © GuardVideo
+
+---
+
+## Support
+
+- GitHub Issues: [github.com/guardvideo/player-sdk](https://github.com/guardvideo/player-sdk)
+- Documentation: [docs.guardvideo.com](https://docs.guardvideo.com)
+
+| Safari  | 14+ (native HLS) |
+| Edge    | 90+ |
+| iOS Safari | 14+ |
+| Android Chrome | 90+ |
+
+---
+
+## License
+
+MIT (C) GuardVideo
+
+---
+
+## Support
+
+- GitHub Issues: https://github.com/guardvideo/player-sdk
+- Documentation: https://docs.guardvideo.com