@mottosports/motto-video-player 1.0.1-rc.7 → 1.0.1-rc.70

package/README.md

@@ -1,6 +1,6 @@
 # Motto Video Player
 
-A modern, feature-rich video player built on top of Shaka Player with React support.
+React video player component for the Motto platform, powered by Shaka Player with TanStack Query integration.
 
 ## Features
 
@@ -8,6 +8,7 @@ A modern, feature-rich video player built on top of Shaka Player with React supp
 - 🔄 **TanStack Query Integration**: Advanced caching, background refetching, and error handling
 - 📱 **Responsive Design**: Automatic aspect ratio handling and mobile-friendly controls
 - 🎮 **Skip Controls**: Built-in skip back/forward buttons with customizable durations
+- ⌨️ **Keyboard Controls**: Desktop keyboard shortcuts (arrows for skip, spacebar for play/pause)
 - 🎯 **Quality Control**: Automatic quality selection and manual quality switching
 - 📊 **Analytics**: Built-in Mux analytics support
 - 🖥️ **Chromecast Support**: Cast videos to compatible devices
@@ -17,220 +18,227 @@ A modern, feature-rich video player built on top of Shaka Player with React supp
 ## Installation
 
 ```bash
-npm install @motto/video-player
-# or
-yarn add @motto/video-player
-# or  
-pnpm add @motto/video-player
+npm install @motto-ui-components/motto-video-player @tanstack/react-query
 ```
 
-## Basic Usage
+## Quick Start
 
-```tsx
-import { Player } from '@motto/video-player';
+### Setup QueryClient (Required for Video wrapper)
 
-function MyVideoPlayer() {
+```jsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
   return (
-    <Player
-      src="https://example.com/video.m3u8"
-      autoPlay={false}
-      controls={true}
-      width={800}
-      height={450}
-    />
+    <QueryClientProvider client={queryClient}>
+      <YourComponents />
+    </QueryClientProvider>
   );
 }
 ```
 
-## Next.js Usage (SSR Support)
-
-If you're using Next.js, you need to handle server-side rendering (SSR) since Shaka Player requires browser APIs. Here are three approaches:
+### Basic Usage
 
-### Option 1: Using next/dynamic (Recommended)
+#### VideoPlayer (Bare Component)
+For direct stream URL playback:
 
-```tsx
-import dynamic from 'next/dynamic';
+```jsx
+import { VideoPlayer } from '@motto-ui-components/motto-video-player';
 
-const MottoPlayer = dynamic(
-  () => import('@motto/video-player').then((mod) => ({ default: mod.Player })),
-  { 
-    ssr: false,
-    loading: () => <div>Loading player...</div>
-  }
-);
-
-function MyVideoPage() {
+function MyPlayer() {
   return (
-    <div>
-      <h1>My Video</h1>
-      <MottoPlayer
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
+    <VideoPlayer
+      src="https://example.com/video.m3u8"
+      controls
+      aspectRatio={16/9}
+      onPlay={() => console.log('Playing')}
+      onError={(error) => console.error(error)}
+    />
   );
 }
 ```
 
-### Option 2: Using the built-in ClientOnlyPlayer
+#### Video (Wrapper Component)
+For data fetching with TanStack Query:
 
-```tsx
-import { ClientOnlyPlayer } from '@motto/video-player';
+```jsx
+import { Video } from '@motto-ui-components/motto-video-player';
 
-function MyVideoPage() {
+function MyPlayer() {
   return (
-    <div>
-      <h1>My Video</h1>
-      <ClientOnlyPlayer
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
+    <Video
+      videoId="your-video-id"
+      publicKey="your-public-key"
+      controls
+      refetchInterval={30000}
+      events={{
+        onVideoData: (video) => console.log('Video loaded:', video),
+        onError: (error) => console.error('Error:', error),
+        onPlay: () => console.log('Playing')
+      }}
+    />
   );
 }
 ```
 
-### Option 3: Using useEffect for client-side only rendering
+## Component Comparison
 
-```tsx
-import { Player } from '@motto/video-player';
-import { useEffect, useState } from 'react';
+| Feature | VideoPlayer | Video |
+|---------|-------------|-------|
+| **Use Case** | Direct stream URL | Data fetching with videoId |
+| **Data Fetching** | ❌ Manual | ✅ Automatic with TanStack Query |
+| **Caching** | ❌ None | ✅ Smart caching & background updates |
+| **Loading States** | ❌ Manual | ✅ Built-in loading indicators |
+| **Error Handling** | ❌ Manual | ✅ Automatic retry with exponential backoff |
+| **Performance** | ✅ Minimal overhead | ✅ Optimized with query deduplication |
 
-function MyVideoPage() {
-  const [isClient, setIsClient] = useState(false);
+## Advanced Configuration
 
-  useEffect(() => {
-    setIsClient(true);
-  }, []);
+### TanStack Query Options
+
+```jsx
+<Video
+  videoId="123"
+  publicKey="key"
+  refetchInterval={30000}
+  queryOptions={{
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 3,
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
+  }}
+/>
+```
 
-  if (!isClient) {
-    return <div>Loading player...</div>;
-  }
+### Skip Controls
 
-  return (
-    <div>
-      <h1>My Video</h1>
-      <Player
-        src="https://example.com/video.m3u8"
-        autoPlay={false}
-        controls={true}
-        width={800}
-        height={450}
-      />
-    </div>
-  );
-}
+```jsx
+<VideoPlayer
+  src="..."
+  skipConfig={{
+    showSkipBack: true,
+    showSkipForward: true,
+    skipDuration: 15,
+    position: 'controls' // or 'overlay'
+  }}
+  onSkipBack={(newTime) => console.log('Skipped to:', newTime)}
+  onSkipForward={(newTime) => console.log('Skipped to:', newTime)}
+/>
 ```
 
-## Player Props
+### Keyboard Controls
 
-The player accepts the following props:
+Desktop users can control the player using keyboard shortcuts:
 
-- `src` (string, required): URL of the video manifest (HLS, DASH, etc.)
-- `autoPlay` (boolean, default: false): Whether to start playing automatically
-- `controls` (boolean, default: true): Whether to show player controls
-- `width` (number): Fixed width in pixels
-- `height` (number): Fixed height in pixels  
-- `aspectRatio` (number, default: 16/9): Aspect ratio for responsive sizing
-- `poster` (string): URL of poster image to show before video loads
-- `muted` (boolean, default: false): Whether to start muted
-- `loop` (boolean, default: false): Whether to loop the video
+- **←** Left Arrow: Skip back 15 seconds
+- **→** Right Arrow: Skip forward 15 seconds  
+- **Space**: Play/Pause toggle
 
-## Advanced Configuration
+Keyboard controls are automatically enabled on desktop devices (disabled on mobile) and work when the player is focused or when no input fields are active.
 
-### Quality Control
+### Responsive Sizing
 
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  qualityConfig={{
-    enableAutoQuality: true,
-    preferredVideoHeight: 720,
-    preferredAudioLanguage: 'en'
-  }}
-/>
-```
+```jsx
+// Default responsive 16:9
+<VideoPlayer src="..." />
 
-### DRM Configuration
+// Custom aspect ratio
+<VideoPlayer src="..." aspectRatio={4/3} />
 
-```tsx
-<Player
-  src="https://example.com/protected-video.mpd"
-  drmConfig={{
-    servers: {
-      'com.widevine.alpha': 'https://license-server.com/widevine',
-      'com.microsoft.playready': 'https://license-server.com/playready'
-    }
-  }}
-/>
+// Fixed dimensions
+<VideoPlayer src="..." width={800} height={450} />
 ```
 
-### Mux Analytics
+### Analytics Integration
 
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
+```jsx
+<VideoPlayer
+  src="..."
   muxConfig={{
-    envKey: 'your-mux-env-key',
-    metadata: {
-      video_title: 'My Video',
-      viewer_user_id: 'user123'
+    debug: false,
+    data: {
+      env_key: 'your-mux-env-key',
+      video_title: 'Video Title',
+      video_id: 'video-123',
+      player_name: 'Web Player',
+      viewer_user_id: 'user-456'
     }
   }}
+  onMuxReady={(monitor) => console.log('Mux ready')}
 />
 ```
 
-## Event Handling
-
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  events={{
-    onPlay: () => console.log('Video started playing'),
-    onPause: () => console.log('Video paused'),
-    onEnded: () => console.log('Video ended'),
-    onError: (error) => console.error('Playback error:', error),
-    onQualityChange: (quality) => console.log('Quality changed:', quality)
-  }}
-/>
+## API Reference
+
+### VideoPlayer Props
+
+```typescript
+interface VideoPlayerProps {
+  src: string;                    // Video source URL
+  autoPlay?: boolean;            // Auto-play video
+  controls?: boolean;            // Show player controls
+  aspectRatio?: number;          // Video aspect ratio (default: 16/9)
+  width?: number;               // Fixed width
+  height?: number;              // Fixed height
+  skipConfig?: SkipConfig;      // Skip controls configuration
+  muxConfig?: MuxConfig;        // Mux analytics configuration
+  onPlay?: () => void;          // Play event callback
+  onPause?: () => void;         // Pause event callback
+  onError?: (error: any) => void; // Error event callback
+  // ... more props
+}
 ```
 
-## Responsive Design
+### Video Props
+
+```typescript
+interface VideoProps extends Omit<VideoPlayerProps, 'src'> {
+  videoId?: string;             // Video ID for data fetching
+  publicKey?: string;           // Public key for API authentication
+  videoData?: VideoData;        // Pre-loaded video data
+  refetchInterval?: number;     // Background refetch interval (ms)
+  queryOptions?: QueryOptions;  // TanStack Query configuration
+  events?: {
+    onVideoData?: (video: VideoData) => void;
+    onEmptyPlaylists?: () => void;
+    onError?: (error: Error) => void;
+    // ... player events
+  };
+}
+```
 
-For responsive video players, omit the `width` and `height` props and optionally set an `aspectRatio`:
+## TanStack Query Benefits
 
-```tsx
-<Player
-  src="https://example.com/video.m3u8"
-  aspectRatio={16/9}
-  containerClassName="w-full max-w-4xl"
-/>
-```
+### Caching & Performance
+- **Automatic Caching**: Videos are cached with configurable stale time
+- **Background Refetching**: Data stays fresh with background updates
+- **Request Deduplication**: Identical requests are automatically deduplicated
+- **Garbage Collection**: Memory-efficient cleanup of unused cache entries
 
-## Live Streaming
+### Resilience & UX
+- **Smart Retries**: Exponential backoff retry logic for failed requests
+- **Loading States**: Built-in loading indicators for better UX
+- **Error Recovery**: Automatic error handling and recovery mechanisms
+- **Optimistic Updates**: Support for optimistic UI updates
 
-The player automatically detects live streams and shows appropriate UI:
+## Examples
 
-```tsx
-<Player
-  src="https://example.com/live-stream.m3u8"
-  streamStartDate={new Date('2024-01-01T12:00:00Z')} // Optional: for absolute time display
-/>
-```
+Check out the [example app](../../apps/example) for comprehensive usage examples including:
+
+- Basic VideoPlayer usage
+- Video wrapper with TanStack Query
+- Pre-loaded data scenarios
+- Skip controls integration
+- Responsive design patterns
 
-## Browser Support
+## Contributing
 
-- Chrome 80+
-- Firefox 75+  
-- Safari 13+
-- Edge 80+
+1. Clone the repository
+2. Install dependencies: `pnpm install`
+3. Start development: `pnpm dev`
+4. Build: `pnpm build`
 
 ## License
 
-MIT 
+ISC