@mottosports/motto-video-player 1.0.1-rc.12 → 1.0.1-rc.5

package/README.md

@@ -1,6 +1,6 @@
 # Motto Video Player
 
-React video player component for the Motto platform, powered by Shaka Player with TanStack Query integration.
+A modern, feature-rich video player built on top of Shaka Player with React support.
 
 ## Features
 
@@ -17,217 +17,220 @@ React video player component for the Motto platform, powered by Shaka Player wit
 ## Installation
 
 ```bash
-npm install @motto-ui-components/motto-video-player @tanstack/react-query
+npm install @motto/video-player
+# or
+yarn add @motto/video-player
+# or  
+pnpm add @motto/video-player
 ```
 
-## Quick Start
+## Basic Usage
 
-### Setup QueryClient (Required for Video wrapper)
+```tsx
+import { Player } from '@motto/video-player';
 
-```jsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+function MyVideoPlayer() {
+  return (
+    <Player
+      src="https://example.com/video.m3u8"
+      autoPlay={false}
+      controls={true}
+      width={800}
+      height={450}
+    />
+  );
+}
+```
+
+## 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:
+
+### Option 1: Using next/dynamic (Recommended)
 
-const queryClient = new QueryClient();
+```tsx
+import dynamic from 'next/dynamic';
 
-function App() {
+const MottoPlayer = dynamic(
+  () => import('@motto/video-player').then((mod) => ({ default: mod.Player })),
+  { 
+    ssr: false,
+    loading: () => <div>Loading player...</div>
+  }
+);
+
+function MyVideoPage() {
   return (
-    <QueryClientProvider client={queryClient}>
-      <YourComponents />
-    </QueryClientProvider>
+    <div>
+      <h1>My Video</h1>
+      <MottoPlayer
+        src="https://example.com/video.m3u8"
+        autoPlay={false}
+        controls={true}
+        width={800}
+        height={450}
+      />
+    </div>
   );
 }
 ```
 
-### Basic Usage
-
-#### VideoPlayer (Bare Component)
-For direct stream URL playback:
+### Option 2: Using the built-in ClientOnlyPlayer
 
-```jsx
-import { VideoPlayer } from '@motto-ui-components/motto-video-player';
+```tsx
+import { ClientOnlyPlayer } from '@motto/video-player';
 
-function MyPlayer() {
+function MyVideoPage() {
   return (
-    <VideoPlayer
-      src="https://example.com/video.m3u8"
-      controls
-      aspectRatio={16/9}
-      onPlay={() => console.log('Playing')}
-      onError={(error) => console.error(error)}
-    />
+    <div>
+      <h1>My Video</h1>
+      <ClientOnlyPlayer
+        src="https://example.com/video.m3u8"
+        autoPlay={false}
+        controls={true}
+        width={800}
+        height={450}
+      />
+    </div>
   );
 }
 ```
 
-#### Video (Wrapper Component)
-For data fetching with TanStack Query:
+### Option 3: Using useEffect for client-side only rendering
+
+```tsx
+import { Player } from '@motto/video-player';
+import { useEffect, useState } from 'react';
 
-```jsx
-import { Video } from '@motto-ui-components/motto-video-player';
+function MyVideoPage() {
+  const [isClient, setIsClient] = useState(false);
+
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  if (!isClient) {
+    return <div>Loading player...</div>;
+  }
 
-function MyPlayer() {
   return (
-    <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')
-      }}
-    />
+    <div>
+      <h1>My Video</h1>
+      <Player
+        src="https://example.com/video.m3u8"
+        autoPlay={false}
+        controls={true}
+        width={800}
+        height={450}
+      />
+    </div>
   );
 }
 ```
 
-## Component Comparison
+## Player Props
+
+The player accepts the following props:
 
-| 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 |
+- `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
 
 ## Advanced Configuration
 
-### 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)
+### Quality Control
+
+```tsx
+<Player
+  src="https://example.com/video.m3u8"
+  qualityConfig={{
+    enableAutoQuality: true,
+    preferredVideoHeight: 720,
+    preferredAudioLanguage: 'en'
   }}
 />
 ```
 
-### Skip Controls
+### DRM Configuration
 
-```jsx
-<VideoPlayer
-  src="..."
-  skipConfig={{
-    showSkipBack: true,
-    showSkipForward: true,
-    skipDuration: 15,
-    position: 'controls' // or 'overlay'
+```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'
+    }
   }}
-  onSkipBack={(newTime) => console.log('Skipped to:', newTime)}
-  onSkipForward={(newTime) => console.log('Skipped to:', newTime)}
 />
 ```
 
-### Responsive Sizing
-
-```jsx
-// Default responsive 16:9
-<VideoPlayer src="..." />
+### Mux Analytics
 
-// Custom aspect ratio
-<VideoPlayer src="..." aspectRatio={4/3} />
-
-// Fixed dimensions
-<VideoPlayer src="..." width={800} height={450} />
-```
-
-### Analytics Integration
-
-```jsx
-<VideoPlayer
-  src="..."
+```tsx
+<Player
+  src="https://example.com/video.m3u8"
   muxConfig={{
-    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'
+    envKey: 'your-mux-env-key',
+    metadata: {
+      video_title: 'My Video',
+      viewer_user_id: 'user123'
     }
   }}
-  onMuxReady={(monitor) => console.log('Mux ready')}
 />
 ```
 
-## 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
-}
-```
-
-### 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
-  };
-}
+## 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)
+  }}
+/>
 ```
 
-## TanStack Query Benefits
+## Responsive Design
 
-### 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
+For responsive video players, omit the `width` and `height` props and optionally set an `aspectRatio`:
 
-### 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
+```tsx
+<Player
+  src="https://example.com/video.m3u8"
+  aspectRatio={16/9}
+  containerClassName="w-full max-w-4xl"
+/>
+```
 
-## Examples
+## Live Streaming
 
-Check out the [example app](../../apps/example) for comprehensive usage examples including:
+The player automatically detects live streams and shows appropriate UI:
 
-- Basic VideoPlayer usage
-- Video wrapper with TanStack Query
-- Pre-loaded data scenarios
-- Skip controls integration
-- Responsive design patterns
+```tsx
+<Player
+  src="https://example.com/live-stream.m3u8"
+  streamStartDate={new Date('2024-01-01T12:00:00Z')} // Optional: for absolute time display
+/>
+```
 
-## Contributing
+## Browser Support
 
-1. Clone the repository
-2. Install dependencies: `pnpm install`
-3. Start development: `pnpm dev`
-4. Build: `pnpm build`
+- Chrome 80+
+- Firefox 75+  
+- Safari 13+
+- Edge 80+
 
 ## License
 
-ISC 
+MIT 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import React, { HTMLAttributes } from 'react';
-import { QueryClient } from '@tanstack/react-query';
+import * as React from 'react';
+import React__default, { HTMLAttributes } from 'react';
 
 /**
  * Unified events interface for both Player and Video wrapper
@@ -225,7 +225,17 @@ interface PlayerProps extends Omit<HTMLAttributes<HTMLVideoElement>, 'src' | 'on
      * Event callbacks
      */
     events?: PlayerEvents;
+    /**
+     * CSS class name for the container element
+     */
     containerClassName?: string;
+    /**
+     * Optional manual override for stream start time
+     * If not provided, the player will attempt to auto-detect the stream start time
+     * from the manifest for live streams. When provided, shows elapsed time since
+     * stream started instead of the current playback position.
+     */
+    streamStartDate?: Date;
 }
 /**
  * Mux Analytics type definitions
@@ -320,7 +330,13 @@ interface MuxAnalyticsConfig {
     metadata?: MuxMetadata;
 }
 
-declare const Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
+declare const Player: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
+
+/**
+ * Client-only wrapper for the Player component to prevent SSR issues.
+ * This component only renders the Player on the client side after hydration.
+ */
+declare const ClientOnlyPlayer: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
 
 interface VideoData {
     id: string;
@@ -342,6 +358,22 @@ interface VideoListItem {
     }>;
     error?: string;
 }
+/**
+ * Fetches video data from the Motto Streaming API
+ * @param videoId - The ID of the video to fetch
+ * @param publicKey - The public key for authentication
+ * @param mottoToken - Optional motto token for authenticated requests
+ * @returns Promise<VideoData> - The video data
+ */
+declare const fetchVideoData: (videoId: string, publicKey: string, mottoToken?: string) => Promise<VideoData>;
+/**
+ * Fetches multiple videos data from the Motto Streaming API
+ * @param publicKey - The public key for authentication
+ * @param videoIds - Array of video IDs to fetch
+ * @param mottoToken - Optional motto token for authenticated requests
+ * @returns Promise<VideoListItem[]> - Array of video data
+ */
+declare function fetchVideosList(publicKey: string, videoIds: string[], mottoToken?: string, skip?: number, limit?: number): Promise<VideoListItem[]>;
 
 interface EventData {
     id: string;
@@ -357,6 +389,7 @@ declare enum EventsSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
+declare function fetchEventData(publicKey: string, eventId: string, unused?: any, filter?: string, order?: EventsSortDirection, locale?: string): Promise<EventData>;
 
 interface CreativeWorkData {
     id: string;
@@ -372,6 +405,7 @@ declare enum CreativeWorksSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
+declare function fetchCreativeWorkData(publicKey: string, creativeWorkId: string, unused?: any, filter?: string, order?: CreativeWorksSortDirection, locale?: string): Promise<CreativeWorkData>;
 
 interface VideoProps extends Omit<PlayerProps, 'src'> {
     videoId?: string;
@@ -392,7 +426,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         onCanPlay?: () => void;
         onPlayerReady?: () => void;
     };
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     className?: string;
     queryOptions?: {
         enabled?: boolean;
@@ -402,7 +436,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Video: React.FC<VideoProps>;
+declare const Video: React__default.FC<VideoProps>;
 
 interface EventProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -440,7 +474,7 @@ interface EventProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Event: React.FC<EventProps>;
+declare const Event: React__default.FC<EventProps>;
 
 interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -478,12 +512,21 @@ interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const CreativeWork: React.FC<CreativeWorkProps>;
+declare const CreativeWork: React__default.FC<CreativeWorkProps>;
+
+/**
+ * Client-side wrapper for the Event component to prevent SSR issues
+ * This component ensures that Event is only rendered on the client-side
+ */
+declare const ClientSideEvent: React__default.FC<EventProps>;
 
-declare const queryClient: QueryClient;
 interface QueryProviderProps {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
 }
-declare const QueryProvider: React.FC<QueryProviderProps>;
+declare const QueryProvider: React__default.FC<QueryProviderProps>;
+
+declare const _default: {
+    Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
+};
 
-export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, Player, type PlayerEvents, type PlayerProps, QueryProvider, Video, type VideoData, type VideoListItem, type VideoProps, queryClient };
+export { ClientOnlyPlayer, ClientSideEvent, CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, type MuxAnalyticsConfig, type MuxDataUpdatePayload, type MuxErrorTranslator, type MuxMetadata, Player, type PlayerEvents, type PlayerProps, QueryProvider, type SeekbarConfig, Video, type VideoData, type VideoListItem, type VideoProps, _default as default, fetchCreativeWorkData, fetchEventData, fetchVideoData, fetchVideosList };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import React, { HTMLAttributes } from 'react';
-import { QueryClient } from '@tanstack/react-query';
+import * as React from 'react';
+import React__default, { HTMLAttributes } from 'react';
 
 /**
  * Unified events interface for both Player and Video wrapper
@@ -225,7 +225,17 @@ interface PlayerProps extends Omit<HTMLAttributes<HTMLVideoElement>, 'src' | 'on
      * Event callbacks
      */
     events?: PlayerEvents;
+    /**
+     * CSS class name for the container element
+     */
     containerClassName?: string;
+    /**
+     * Optional manual override for stream start time
+     * If not provided, the player will attempt to auto-detect the stream start time
+     * from the manifest for live streams. When provided, shows elapsed time since
+     * stream started instead of the current playback position.
+     */
+    streamStartDate?: Date;
 }
 /**
  * Mux Analytics type definitions
@@ -320,7 +330,13 @@ interface MuxAnalyticsConfig {
     metadata?: MuxMetadata;
 }
 
-declare const Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
+declare const Player: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
+
+/**
+ * Client-only wrapper for the Player component to prevent SSR issues.
+ * This component only renders the Player on the client side after hydration.
+ */
+declare const ClientOnlyPlayer: React__default.ForwardRefExoticComponent<PlayerProps & React__default.RefAttributes<HTMLVideoElement>>;
 
 interface VideoData {
     id: string;
@@ -342,6 +358,22 @@ interface VideoListItem {
     }>;
     error?: string;
 }
+/**
+ * Fetches video data from the Motto Streaming API
+ * @param videoId - The ID of the video to fetch
+ * @param publicKey - The public key for authentication
+ * @param mottoToken - Optional motto token for authenticated requests
+ * @returns Promise<VideoData> - The video data
+ */
+declare const fetchVideoData: (videoId: string, publicKey: string, mottoToken?: string) => Promise<VideoData>;
+/**
+ * Fetches multiple videos data from the Motto Streaming API
+ * @param publicKey - The public key for authentication
+ * @param videoIds - Array of video IDs to fetch
+ * @param mottoToken - Optional motto token for authenticated requests
+ * @returns Promise<VideoListItem[]> - Array of video data
+ */
+declare function fetchVideosList(publicKey: string, videoIds: string[], mottoToken?: string, skip?: number, limit?: number): Promise<VideoListItem[]>;
 
 interface EventData {
     id: string;
@@ -357,6 +389,7 @@ declare enum EventsSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
+declare function fetchEventData(publicKey: string, eventId: string, unused?: any, filter?: string, order?: EventsSortDirection, locale?: string): Promise<EventData>;
 
 interface CreativeWorkData {
     id: string;
@@ -372,6 +405,7 @@ declare enum CreativeWorksSortDirection {
     ASC = "asc",
     DESC = "desc"
 }
+declare function fetchCreativeWorkData(publicKey: string, creativeWorkId: string, unused?: any, filter?: string, order?: CreativeWorksSortDirection, locale?: string): Promise<CreativeWorkData>;
 
 interface VideoProps extends Omit<PlayerProps, 'src'> {
     videoId?: string;
@@ -392,7 +426,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         onCanPlay?: () => void;
         onPlayerReady?: () => void;
     };
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     className?: string;
     queryOptions?: {
         enabled?: boolean;
@@ -402,7 +436,7 @@ interface VideoProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Video: React.FC<VideoProps>;
+declare const Video: React__default.FC<VideoProps>;
 
 interface EventProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -440,7 +474,7 @@ interface EventProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const Event: React.FC<EventProps>;
+declare const Event: React__default.FC<EventProps>;
 
 interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
     publicKey: string;
@@ -478,12 +512,21 @@ interface CreativeWorkProps extends Omit<PlayerProps, 'src'> {
         retryDelay?: number;
     };
 }
-declare const CreativeWork: React.FC<CreativeWorkProps>;
+declare const CreativeWork: React__default.FC<CreativeWorkProps>;
+
+/**
+ * Client-side wrapper for the Event component to prevent SSR issues
+ * This component ensures that Event is only rendered on the client-side
+ */
+declare const ClientSideEvent: React__default.FC<EventProps>;
 
-declare const queryClient: QueryClient;
 interface QueryProviderProps {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
 }
-declare const QueryProvider: React.FC<QueryProviderProps>;
+declare const QueryProvider: React__default.FC<QueryProviderProps>;
+
+declare const _default: {
+    Player: React.ForwardRefExoticComponent<PlayerProps & React.RefAttributes<HTMLVideoElement>>;
+};
 
-export { CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, Player, type PlayerEvents, type PlayerProps, QueryProvider, Video, type VideoData, type VideoListItem, type VideoProps, queryClient };
+export { ClientOnlyPlayer, ClientSideEvent, CreativeWork, type CreativeWorkData, type CreativeWorkProps, CreativeWorksSortDirection, Event, type EventData, type EventProps, EventsSortDirection, type MuxAnalyticsConfig, type MuxDataUpdatePayload, type MuxErrorTranslator, type MuxMetadata, Player, type PlayerEvents, type PlayerProps, QueryProvider, type SeekbarConfig, Video, type VideoData, type VideoListItem, type VideoProps, _default as default, fetchCreativeWorkData, fetchEventData, fetchVideoData, fetchVideosList };