unified-video-framework 1.0.0

package/README.md

@@ -0,0 +1,315 @@
+# Unified Video Player Framework
+
+A comprehensive cross-platform video player framework that provides a unified API for building video applications across all major platforms.
+
+## 🎯 Supported Platforms
+
+- **Mobile**: iOS, Android
+- **Web**: All modern browsers
+- **Smart TVs**: 
+  - Samsung Tizen (using Enact)
+  - LG webOS (using Enact)
+- **Streaming Devices**: 
+  - Roku
+  - Android TV
+  - Apple TV
+- **Desktop**: Windows, macOS, Linux (via web)
+
+## ✨ Features
+
+- **Unified API**: Single API across all platforms
+- **DRM Support**: FairPlay, Widevine, PlayReady
+- **Adaptive Streaming**: HLS, DASH support
+- **Analytics**: Built-in analytics integration
+- **Offline Playback**: Download and play offline
+- **Casting**: Chromecast and AirPlay support
+- **Picture-in-Picture**: Supported platforms
+- **4K/8K & HDR**: High-quality video support
+- **Subtitles & Multiple Audio Tracks**
+- **Ad Integration**: Pre-roll, mid-roll, post-roll ads
+- **Remote Control**: Full TV remote support
+
+## 📦 Installation
+
+### Using npm
+```bash
+npm install @company/unified-video-framework
+```
+
+### Using yarn
+```bash
+yarn add @company/unified-video-framework
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { UnifiedVideoPlayer } from '@company/unified-video-framework';
+
+function App() {
+  return (
+    <UnifiedVideoPlayer
+      source={{
+        url: 'https://example.com/video.m3u8',
+        type: 'application/x-mpegURL'
+      }}
+      config={{
+        autoPlay: true,
+        controls: true
+      }}
+      onReady={() => console.log('Player ready')}
+      onError={(error) => console.error('Player error:', error)}
+    />
+  );
+}
+```
+
+### With DRM
+
+```typescript
+import { UnifiedVideoPlayer, DRMType } from '@company/unified-video-framework';
+
+function SecureVideoApp() {
+  return (
+    <UnifiedVideoPlayer
+      source={{
+        url: 'https://example.com/encrypted-video.mpd',
+        type: 'application/dash+xml',
+        drm: {
+          type: DRMType.WIDEVINE,
+          licenseUrl: 'https://license.example.com/widevine',
+          headers: {
+            'X-Auth-Token': 'your-auth-token'
+          }
+        }
+      }}
+      config={{
+        autoPlay: false,
+        adaptiveBitrate: {
+          autoLevelEnabled: true,
+          startLevel: -1
+        }
+      }}
+    />
+  );
+}
+```
+
+## 🏗️ Framework Architecture
+
+```
+┌────────────────────────────────────────────────┐
+│          Application Layer (Your App)           │
+├────────────────────────────────────────────────┤
+│     Unified Video Framework API (TypeScript)    │
+├────────────────────────────────────────────────┤
+│              Platform Bridge Layer              │
+├──────┬──────┬──────────┬──────┬──────────┬────┤
+│ iOS  │Android│  Enact   │ Roku │   Web    │Win │
+│Native│Native │(Tizen/LG)│Bridge│ Browser  │UWP │
+└──────┴──────┴──────────┴──────┴──────────┴────┘
+```
+
+## 📱 Platform-Specific Setup
+
+### iOS
+```bash
+cd ios && pod install
+```
+
+### Android
+Add to `android/app/build.gradle`:
+```gradle
+dependencies {
+    implementation 'com.google.android.exoplayer:exoplayer:2.18.0'
+}
+```
+
+### Samsung Tizen TV
+```bash
+npm run build:tizen
+tizen install -n dist/tizen/app.wgt
+```
+
+### LG webOS TV
+```bash
+npm run build:webos
+ares-install dist/webos/app.ipk
+```
+
+### Roku
+```bash
+npm run build:roku
+# Upload via Roku Developer Dashboard
+```
+
+## 🛠️ Development
+
+### Setup
+```bash
+# Install dependencies
+npm install
+
+# Bootstrap monorepo
+npm run bootstrap
+
+# Build all packages
+npm run build
+```
+
+### Running Examples
+```bash
+# Run mobile demo
+cd apps/mobile-demo
+npm run ios
+# or
+npm run android
+
+# Run TV demo
+cd apps/tv-demo
+npm run serve
+
+# Run web demo
+cd apps/web-demo
+npm start
+```
+
+## 📖 API Documentation
+
+### VideoPlayer Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `load(source)` | Load a video source | `Promise<void>` |
+| `play()` | Start playback | `Promise<void>` |
+| `pause()` | Pause playback | `void` |
+| `seek(time)` | Seek to position | `void` |
+| `setVolume(level)` | Set volume (0-1) | `void` |
+| `setQuality(quality)` | Set video quality | `void` |
+| `setSubtitle(track)` | Set subtitle track | `void` |
+| `destroy()` | Clean up player | `void` |
+
+### Events
+
+| Event | Description | Payload |
+|-------|-------------|---------|
+| `ready` | Player initialized | - |
+| `play` | Playback started | - |
+| `pause` | Playback paused | - |
+| `ended` | Playback ended | - |
+| `error` | Error occurred | `{error: Error}` |
+| `timeupdate` | Position updated | `{currentTime: number}` |
+| `progress` | Buffer progress | `{buffered: number}` |
+| `qualitychange` | Quality changed | `{quality: Quality}` |
+
+## 🎮 Remote Control Support
+
+The framework automatically handles remote control inputs on TV platforms:
+
+- **Play/Pause**: Media play/pause keys
+- **Seek**: Left/Right arrow keys
+- **Volume**: Up/Down arrow keys
+- **Back**: Return/Back button
+- **Select**: OK/Enter button
+
+## 📊 Analytics Integration
+
+```typescript
+import { GoogleAnalytics, MixPanel } from '@company/analytics';
+
+<UnifiedVideoPlayer
+  source={videoSource}
+  config={{
+    analytics: {
+      enabled: true,
+      providers: [
+        new GoogleAnalytics({ trackingId: 'UA-XXXXX' }),
+        new MixPanel({ token: 'your-token' })
+      ]
+    }
+  }}
+/>
+```
+
+## 🔒 DRM Configuration
+
+### FairPlay (iOS/Apple TV)
+```typescript
+{
+  type: DRMType.FAIRPLAY,
+  certificateUrl: 'https://example.com/certificate',
+  licenseUrl: 'https://example.com/license'
+}
+```
+
+### Widevine (Android/Chrome/Smart TVs)
+```typescript
+{
+  type: DRMType.WIDEVINE,
+  licenseUrl: 'https://example.com/widevine/license'
+}
+```
+
+### PlayReady (Windows/Xbox/Smart TVs)
+```typescript
+{
+  type: DRMType.PLAYREADY,
+  licenseUrl: 'https://example.com/playready/license'
+}
+```
+
+## 🧪 Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run E2E tests
+npm run test:e2e
+
+# Platform-specific tests
+npm run test:ios
+npm run test:android
+npm run test:tizen
+```
+
+## 📈 Performance Optimization
+
+- **Lazy Loading**: Platform-specific code is loaded on demand
+- **Code Splitting**: Automatic code splitting for web builds
+- **Memory Management**: Automatic cleanup and resource management
+- **Adaptive Bitrate**: Automatic quality adjustment based on network
+
+## 💳 Paywall Rentals (Stripe, Pesapal, Google Pay)
+
+- For per-video rentals (no subscriptions), follow our step-by-step implementation guide:
+  - See PAYWALL_RENTAL_FLOW.md: [PAYWALL_RENTAL_FLOW.md](./PAYWALL_RENTAL_FLOW.md)
+- Documentation index: [docs/](./docs/README.md)
+
+## 🤝 Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Documentation**: [https://docs.example.com](https://docs.example.com)
+- **Issues**: [GitHub Issues](https://github.com/your-org/unified-video-framework/issues)
+- **Discord**: [Join our Discord](https://discord.gg/example)
+- **Email**: support@example.com
+
+## 🙏 Acknowledgments
+
+- React Native team for the mobile framework
+- Enact team for the Smart TV framework
+- ExoPlayer team for Android video engine
+- AVPlayer team for iOS video engine
+
+---
+
+Built with ❤️ by Your Company

package/RUN_LOCALLY.md

@@ -0,0 +1,151 @@
+# How to Run the Unified Video Framework Locally
+
+Due to browser security policies (CORS), you need to run a local web server to properly test all features of the video framework, especially streaming formats like HLS and DASH.
+
+## Quick Start Options
+
+### Option 1: Using Node.js (Recommended)
+
+If you have Node.js installed:
+
+```bash
+# Navigate to the project directory
+cd "C:\Users\Webnexs\Documents\OfficeBackup\AI\VideoPlayer FrameWork\unified-video-framework"
+
+# Run the Node.js server
+node server.js
+```
+
+Then open your browser and go to: **http://localhost:3000**
+
+### Option 2: Using Python 3
+
+If you have Python 3 installed:
+
+```bash
+# Navigate to the project directory
+cd "C:\Users\Webnexs\Documents\OfficeBackup\AI\VideoPlayer FrameWork\unified-video-framework"
+
+# Run the Python server
+python server.py
+# or
+python3 server.py
+```
+
+Then open your browser and go to: **http://localhost:3000**
+
+### Option 3: Using Python's Built-in Server (Simple)
+
+For a quick test with Python:
+
+```bash
+# Navigate to the project directory
+cd "C:\Users\Webnexs\Documents\OfficeBackup\AI\VideoPlayer FrameWork\unified-video-framework"
+
+# Python 3
+python -m http.server 3000
+
+# Python 2 (if that's what you have)
+python -m SimpleHTTPServer 3000
+```
+
+Then open: **http://localhost:3000/apps/demo/demo.html**
+
+### Option 4: Using Live Server Extension (VS Code)
+
+If you're using Visual Studio Code:
+
+1. Install the "Live Server" extension by Ritwick Dey
+2. Right-click on `apps/demo/demo.html`
+3. Select "Open with Live Server"
+
+### Option 5: Using npm's http-server
+
+If you have npm installed globally:
+
+```bash
+# Install http-server globally (one time only)
+npm install -g http-server
+
+# Navigate to the project directory
+cd "C:\Users\Webnexs\Documents\OfficeBackup\AI\VideoPlayer FrameWork\unified-video-framework"
+
+# Run the server
+http-server -p 3000 --cors
+```
+
+Then open: **http://localhost:3000/apps/demo/demo.html**
+
+## Why a Web Server is Required
+
+### ❌ What Doesn't Work with file:// Protocol:
+- **CORS restrictions**: External libraries (HLS.js, dash.js) may not load
+- **Module imports**: ES6 modules won't work
+- **Streaming protocols**: HLS and DASH streams won't play
+- **Fetch requests**: Can't load external resources
+- **Security features**: Some browser APIs are restricted
+
+### ✅ What Works with a Proper Web Server:
+- All video formats (MP4, HLS, DASH)
+- Dynamic library loading
+- Full CORS support
+- Proper MIME types for streaming
+- All browser features enabled
+
+## Testing the Demo
+
+Once your server is running:
+
+1. **Open the demo**: Go to http://localhost:3000
+2. **Test basic playback**: Click on any MP4 sample video
+3. **Test streaming**: Try HLS or DASH samples
+4. **Toggle modes**: Switch between Enhanced and Native modes
+5. **Test features**: Try quality selection, PiP, fullscreen, etc.
+
+## Browser Compatibility
+
+For best results, use modern browsers:
+- **Chrome/Edge**: Full support for all features
+- **Firefox**: Full support for all features
+- **Safari**: Native HLS support, full feature set
+- **Opera**: Full support for all features
+
+## Troubleshooting
+
+### Port Already in Use
+If port 3000 is busy, you can change it:
+- In `server.js` or `server.py`, change `PORT = 3000` to another number
+- Use `http-server -p 8080` for a different port
+
+### CORS Errors
+If you see CORS errors:
+- Make sure you're using one of the server methods above
+- Don't open the HTML file directly (file:// protocol)
+- Check that the server is running properly
+
+### Videos Not Playing
+- Check browser console for errors (F12)
+- Ensure Enhanced Mode is ON for HLS/DASH content
+- Try a different browser
+- Check your internet connection for streaming samples
+
+## Development Tips
+
+1. **Keep the server running** while developing
+2. **Use browser DevTools** (F12) to debug
+3. **Check the Console** for error messages
+4. **Test in multiple browsers** for compatibility
+5. **Use Enhanced Mode** for full streaming support
+
+## Production Deployment
+
+For production, you would typically:
+- Serve files from a proper web server (Apache, Nginx, IIS)
+- Use a CDN for video content
+- Implement proper authentication if needed
+- Set up HTTPS for security
+- Configure proper CORS policies
+
+---
+
+Need help? Check the main README.md or open an issue on the project repository.

package/apps/demo/cast-sender-min.html

@@ -0,0 +1,173 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Minimal Cast Sender</title>
+  <style>
+    body { font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; margin: 20px; }
+    .row { display: flex; gap: 8px; align-items: center; margin-bottom: 10px; flex-wrap: wrap; }
+    input[type="text"] { width: 480px; max-width: 100%; padding: 8px; }
+    button { padding: 8px 12px; cursor: pointer; }
+    .status { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: #111; color: #ddd; padding: 10px; white-space: pre-wrap; border-radius: 6px; min-height: 80px; }
+    .note { color: #666; font-size: 13px; }
+    .controls button { min-width: 100px; }
+  </style>
+  <script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
+</head>
+<body>
+  <h1>Minimal Cast Sender</h1>
+  <div class="row">
+    <label for="url">Media URL:</label>
+    <input id="url" type="text" value="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" />
+    <button id="cast">Cast</button>
+    <button id="stop">Stop Casting</button>
+  </div>
+  <div class="row controls">
+    <button id="playPause">Play/Pause</button>
+    <button id="back">-10s</button>
+    <button id="fwd">+10s</button>
+    <button id="mute">Mute/Unmute</button>
+    <button id="volDown">Vol -</button>
+    <button id="volUp">Vol +</button>
+  </div>
+  <div class="row"><span class="note">Tip: This page focuses on sender/receiver control. It does not play local video.</span></div>
+  <h3>Status</h3>
+  <div id="status" class="status"></div>
+
+  <script>
+    const statusEl = document.getElementById('status');
+    const log = (...args) => {
+      try { console.log('[CastMini]', ...args); } catch(_) {}
+      try { statusEl.textContent += args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n'; } catch(_) {}
+    };
+
+    let remotePlayer = null;
+    let remoteController = null;
+
+    function inferContentType(url) {
+      const u = (url || '').toLowerCase();
+      if (u.includes('.m3u8')) return 'application/vnd.apple.mpegurl';
+      if (u.includes('.mpd')) return 'application/dash+xml';
+      if (u.includes('.webm')) return 'video/webm';
+      return 'video/mp4';
+    }
+
+    function attachRemoteEvents() {
+      if (!(window.cast && cast.framework) || !remoteController) return;
+      const RPET = cast.framework.RemotePlayerEventType;
+      const add = (t, lab) => remoteController.addEventListener(t, () => {
+        try {
+          log(`${lab}`, {
+            isPaused: remotePlayer?.isPaused,
+            playerState: remotePlayer?.playerState,
+            currentTime: remotePlayer?.currentTime,
+            duration: remotePlayer?.duration,
+            isMuted: remotePlayer?.isMuted,
+            volumeLevel: remotePlayer?.volumeLevel,
+            isConnected: remotePlayer?.isConnected,
+          });
+        } catch(_) {}
+      });
+      add(RPET.IS_PAUSED_CHANGED, 'EVT IS_PAUSED_CHANGED');
+      add(RPET.PLAYER_STATE_CHANGED, 'EVT PLAYER_STATE_CHANGED');
+      add(RPET.CURRENT_TIME_CHANGED, 'EVT CURRENT_TIME_CHANGED');
+      add(RPET.DURATION_CHANGED, 'EVT DURATION_CHANGED');
+      add(RPET.IS_MUTED_CHANGED, 'EVT IS_MUTED_CHANGED');
+      add(RPET.VOLUME_LEVEL_CHANGED, 'EVT VOLUME_LEVEL_CHANGED');
+      add(RPET.IS_CONNECTED_CHANGED, 'EVT IS_CONNECTED_CHANGED');
+    }
+
+    function ensureRemote() {
+      if (!remotePlayer) remotePlayer = new cast.framework.RemotePlayer();
+      if (!remoteController) remoteController = new cast.framework.RemotePlayerController(remotePlayer);
+      attachRemoteEvents();
+    }
+
+    async function doCast() {
+      try {
+        if (!(window.cast && cast.framework)) {
+          alert('Cast framework not ready yet. Try again in a moment.');
+          return;
+        }
+        const context = cast.framework.CastContext.getInstance();
+        context.setOptions({ receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID });
+        log('Requesting session...');
+        await context.requestSession();
+        const session = context.getCurrentSession();
+        if (!session) { log('No session after request'); return; }
+        try {
+          const id = (typeof session.getSessionId === 'function') ? session.getSessionId() : (session.sessionId || null);
+          let device = null;
+          if (typeof session.getCastDevice === 'function') {
+            const d = session.getCastDevice();
+            device = (d && d.friendlyName) || null;
+          }
+          log('Session', { id, device });
+        } catch(_) {}
+
+        const url = document.getElementById('url').value.trim();
+        const ct = inferContentType(url);
+        log('Loading media', { url, contentType: ct });
+        const mediaInfo = new chrome.cast.media.MediaInfo(url, ct);
+        const req = new chrome.cast.media.LoadRequest(mediaInfo);
+        await session.loadMedia(req);
+        log('Media loaded on receiver');
+        ensureRemote();
+      } catch (err) {
+        log('Cast error', String(err));
+      }
+    }
+
+    function stopCasting() {
+      try {
+        const ctx = cast.framework.CastContext.getInstance();
+        const sess = ctx.getCurrentSession();
+        if (sess) { sess.endSession(true); log('Session ended'); }
+      } catch (e) { log('Stop error', String(e)); }
+    }
+
+    // Controls
+    function playPause() {
+      try { ensureRemote(); remoteController.playOrPause(); log('playOrPause()'); } catch (e) { log('playPause error', String(e)); }
+    }
+    function seekDelta(delta) {
+      try {
+        ensureRemote();
+        const d = remotePlayer.duration || 0;
+        const c = remotePlayer.currentTime || 0;
+        const n = Math.max(0, Math.min(d, c + delta));
+        remotePlayer.currentTime = n; remoteController.seek();
+        log('seek()', { to: n });
+      } catch (e) { log('seek error', String(e)); }
+    }
+    function muteToggle() {
+      try { ensureRemote(); remoteController.muteOrUnmute(); log('muteOrUnmute()'); } catch (e) { log('mute error', String(e)); }
+    }
+    function vol(delta) {
+      try { ensureRemote(); const cur = remotePlayer.volumeLevel || 0; const nx = Math.max(0, Math.min(1, cur + delta)); remoteController.setVolumeLevel(nx); log('setVolumeLevel()', { to: nx }); } catch (e) { log('volume error', String(e)); }
+    }
+
+    // Wire UI events
+    document.getElementById('cast').addEventListener('click', doCast);
+    document.getElementById('stop').addEventListener('click', stopCasting);
+    document.getElementById('playPause').addEventListener('click', playPause);
+    document.getElementById('back').addEventListener('click', () => seekDelta(-10));
+    document.getElementById('fwd').addEventListener('click', () => seekDelta(10));
+    document.getElementById('mute').addEventListener('click', muteToggle);
+    document.getElementById('volDown').addEventListener('click', () => vol(-0.1));
+    document.getElementById('volUp').addEventListener('click', () => vol(0.1));
+
+    // Cast API ready hook
+    window.__onGCastApiAvailable = function(isAvailable) {
+      if (isAvailable && window.cast && cast.framework) {
+        cast.framework.CastContext.getInstance().setOptions({ receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID });
+        log('Cast framework ready');
+      } else {
+        log('Cast API not available yet');
+      }
+    };
+  </script>
+</body>
+</html>
+