unified-video-framework 1.0.0

package/packages/roku/source/VideoPlayer.brs

@@ -0,0 +1,231 @@
+' ********************************************************
+' ** Unified Video Framework - Roku Implementation
+' ** VideoPlayer.brs - Main video player component
+' ********************************************************
+
+' Initialize the video player component
+Function VideoPlayer_Init() as Object
+    this = {
+        ' Component properties
+        videoContent: CreateObject("roSGNode", "ContentNode")
+        video: invalid
+        state: "idle"
+        config: {}
+        
+        ' Public methods
+        Load: VideoPlayer_Load
+        Play: VideoPlayer_Play
+        Pause: VideoPlayer_Pause
+        Stop: VideoPlayer_Stop
+        Seek: VideoPlayer_Seek
+        SetVolume: VideoPlayer_SetVolume
+        GetCurrentTime: VideoPlayer_GetCurrentTime
+        GetDuration: VideoPlayer_GetDuration
+        GetState: VideoPlayer_GetState
+        Destroy: VideoPlayer_Destroy
+        
+        ' Event handling
+        SetEventCallback: VideoPlayer_SetEventCallback
+        eventCallback: invalid
+    }
+    
+    ' Create the video node
+    this.video = CreateObject("roSGNode", "Video")
+    this.video.observeField("state", "OnVideoStateChange")
+    this.video.observeField("position", "OnPositionChange")
+    this.video.observeField("duration", "OnDurationChange")
+    
+    return this
+End Function
+
+' Load a video source
+Function VideoPlayer_Load(source as Object) as Void
+    m.videoContent.url = source.url
+    m.videoContent.title = source.title
+    
+    ' Set streaming format
+    if source.type = "application/x-mpegURL" then
+        m.videoContent.streamFormat = "hls"
+    else if source.type = "application/dash+xml" then
+        m.videoContent.streamFormat = "dash"
+    else
+        m.videoContent.streamFormat = "mp4"
+    end if
+    
+    ' Handle DRM if present
+    if source.drm <> invalid then
+        VideoPlayer_SetupDRM(source.drm)
+    end if
+    
+    ' Set subtitles if present
+    if source.subtitles <> invalid then
+        VideoPlayer_SetupSubtitles(source.subtitles)
+    end if
+    
+    m.video.content = m.videoContent
+    m.state = "loaded"
+    
+    ' Trigger ready event
+    if m.eventCallback <> invalid then
+        m.eventCallback("ready", {})
+    end if
+End Function
+
+' Start playback
+Function VideoPlayer_Play() as Void
+    if m.state = "loaded" or m.state = "paused" then
+        m.video.control = "play"
+        m.state = "playing"
+        
+        if m.eventCallback <> invalid then
+            m.eventCallback("play", {})
+        end if
+    end if
+End Function
+
+' Pause playback
+Function VideoPlayer_Pause() as Void
+    if m.state = "playing" then
+        m.video.control = "pause"
+        m.state = "paused"
+        
+        if m.eventCallback <> invalid then
+            m.eventCallback("pause", {})
+        end if
+    end if
+End Function
+
+' Stop playback
+Function VideoPlayer_Stop() as Void
+    m.video.control = "stop"
+    m.state = "stopped"
+    
+    if m.eventCallback <> invalid then
+        m.eventCallback("stop", {})
+    end if
+End Function
+
+' Seek to position (in seconds)
+Function VideoPlayer_Seek(position as Float) as Void
+    m.video.seek = position
+    
+    if m.eventCallback <> invalid then
+        m.eventCallback("seeking", {position: position})
+    end if
+End Function
+
+' Set volume (0.0 to 1.0)
+Function VideoPlayer_SetVolume(volume as Float) as Void
+    ' Roku doesn't have direct volume control from apps
+    ' This would typically be handled by the system
+    print "Volume control is handled by system"
+End Function
+
+' Get current playback position in seconds
+Function VideoPlayer_GetCurrentTime() as Float
+    return m.video.position
+End Function
+
+' Get video duration in seconds
+Function VideoPlayer_GetDuration() as Float
+    return m.video.duration
+End Function
+
+' Get current player state
+Function VideoPlayer_GetState() as String
+    return m.state
+End Function
+
+' Clean up resources
+Function VideoPlayer_Destroy() as Void
+    m.video.control = "stop"
+    m.video = invalid
+    m.videoContent = invalid
+    m.state = "idle"
+End Function
+
+' Set event callback function
+Function VideoPlayer_SetEventCallback(callback as Function) as Void
+    m.eventCallback = callback
+End Function
+
+' Setup DRM configuration
+Function VideoPlayer_SetupDRM(drm as Object) as Void
+    if drm.type = "playready" then
+        m.videoContent.drmParams = {
+            licenseServerURL: drm.licenseUrl
+            serializationURL: drm.certificateUrl
+        }
+    else if drm.type = "widevine" then
+        m.videoContent.drmParams = {
+            keySystem: "Widevine"
+            licenseServerURL: drm.licenseUrl
+        }
+    end if
+End Function
+
+' Setup subtitles
+Function VideoPlayer_SetupSubtitles(subtitles as Object) as Void
+    subtitleTracks = []
+    
+    for each subtitle in subtitles
+        track = {
+            url: subtitle.url
+            language: subtitle.language
+            name: subtitle.label
+        }
+        subtitleTracks.push(track)
+    end for
+    
+    m.videoContent.subtitleTracks = subtitleTracks
+End Function
+
+' Handle video state changes
+Sub OnVideoStateChange()
+    state = m.video.state
+    
+    if state = "playing" then
+        m.state = "playing"
+        if m.eventCallback <> invalid then
+            m.eventCallback("playing", {})
+        end if
+    else if state = "paused" then
+        m.state = "paused"
+    else if state = "buffering" then
+        if m.eventCallback <> invalid then
+            m.eventCallback("buffering", {})
+        end if
+    else if state = "error" then
+        m.state = "error"
+        if m.eventCallback <> invalid then
+            m.eventCallback("error", {
+                code: m.video.errorCode
+                message: m.video.errorMsg
+            })
+        end if
+    else if state = "finished" then
+        m.state = "ended"
+        if m.eventCallback <> invalid then
+            m.eventCallback("ended", {})
+        end if
+    end if
+End Sub
+
+' Handle position changes
+Sub OnPositionChange()
+    if m.eventCallback <> invalid then
+        m.eventCallback("timeupdate", {
+            currentTime: m.video.position
+            duration: m.video.duration
+        })
+    end if
+End Sub
+
+' Handle duration changes
+Sub OnDurationChange()
+    if m.eventCallback <> invalid then
+        m.eventCallback("durationchange", {
+            duration: m.video.duration
+        })
+    end if
+End Sub

package/packages/roku/source/main.brs

@@ -0,0 +1,28 @@
+' Main entry point for Roku Unified Video Player
+sub Main(args as Dynamic)
+    ' Initialize the screen
+    screen = CreateObject("roSGScreen")
+    m.port = CreateObject("roMessagePort")
+    screen.setMessagePort(m.port)
+    
+    ' Create the main scene
+    scene = screen.CreateScene("MainScene")
+    screen.show()
+    
+    ' Pass launch arguments to scene
+    if args <> invalid and args.contentId <> invalid then
+        scene.launchArgs = args
+    end if
+    
+    ' Main event loop
+    while true
+        msg = wait(0, m.port)
+        msgType = type(msg)
+        
+        if msgType = "roSGScreenEvent" then
+            if msg.isScreenClosed() then
+                return
+            end if
+        end if
+    end while
+end sub

package/packages/web/GETTING_STARTED.md

@@ -0,0 +1,292 @@
+# Getting Started
+
+## Install
+
+### npm
+```bash
+npm i @unified-video/web
+# Optional (recommended for production control of adaptive streaming):
+npm i hls.js dashjs
+```
+
+### yarn
+```bash
+yarn add @unified-video/web
+# Optional:
+yarn add hls.js dashjs
+```
+
+### pnpm
+```bash
+pnpm add @unified-video/web
+# Optional:
+pnpm add hls.js dashjs
+```
+
+> Notes
+> - hls.js and dashjs are optional peer dependencies. If you don’t install them, the player can load them from public CDNs at runtime. For production builds and offline environments, install them as shown above.
+> - TypeScript types are bundled—no extra @types package needed.
+
+## Quick start (bundler)
+```ts
+import { WebPlayer } from '@unified-video/web';
+
+const player = new WebPlayer();
+
+async function main() {
+  // Attach the player to a container (element or selector)
+  await player.initialize('#player', {
+    autoPlay: false,
+    muted: false,
+    enableAdaptiveBitrate: true, // allows auto quality with HLS/DASH
+    debug: false,
+  });
+
+  // Load a source (mp4, hls, dash, webm)
+  await player.load({
+    url: 'https://example.com/stream.m3u8',
+    type: 'hls', // 'mp4' | 'hls' | 'dash' | 'webm' | 'auto'
+    subtitles: [
+      {
+        url: 'https://example.com/subs/en.vtt',
+        language: 'en',
+        label: 'English',
+        kind: 'subtitles',
+        default: true,
+      },
+    ],
+    metadata: {
+      title: 'My Stream',
+      description: 'An example stream with metadata-driven UI',
+      thumbnailUrl: 'https://example.com/thumb.jpg',
+      posterUrl: 'https://example.com/poster.jpg'
+    },
+  });
+
+  await player.play();
+}
+
+main().catch(console.error);
+```
+
+### Container markup
+```html
+<div id="player" style="width: 100%; max-width: 960px; margin: 0 auto;"></div>
+```
+
+### Chromecast (optional)
+```html
+<!-- Add this if you want Cast sender support in the browser -->
+<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1" async></script>
+```
+
+## Enhanced UI and Dynamic Theming
+The WebPlayer renders a premium UI (gradient border, top action buttons, animated center play, watermark, modern control bar) and supports live theming via CSS variables.
+
+Set a theme at runtime (after initialize and before/after load):
+```ts
+// Single accent (accent2 is derived)
+player.setTheme('#00bcd4');
+
+// Full theme object
+player.setTheme({
+  accent: '#ff0000',
+  accent2: '#ff4d4f',
+  iconColor: '#ffffff',
+  textPrimary: '#ffffff',
+  textSecondary: 'rgba(255,255,255,0.75)',
+});
+```
+
+### Theme variables
+- `--uvf-accent-1`, `--uvf-accent-2` (accent gradient)
+- `--uvf-accent-1-20` (translucent accent for glow/badges)
+- `--uvf-icon-color`
+- `--uvf-text-primary`, `--uvf-text-secondary`
+- Settings menu scrollbar tuning:
+  - `--uvf-scrollbar-width`
+  - `--uvf-scrollbar-thumb-start`, `--uvf-scrollbar-thumb-end`
+  - `--uvf-scrollbar-thumb-hover-start`, `--uvf-scrollbar-thumb-hover-end`
+
+You can also adjust scrollbar behavior programmatically:
+```ts
+player.setSettingsScrollbarStyle('compact'); // 'default' | 'compact' | 'overlay'
+player.setSettingsScrollbarConfig({ widthPx: 6, intensity: 1 });
+```
+
+## Metadata-driven UI (WebPlayer)
+- The built-in title bar is shown only if at least one of `title`, `description`, or `thumbnailUrl` is present in `source.metadata`.
+- When those fields are omitted, the title bar stays hidden; no default text is displayed.
+- For the underlying video poster, you can provide `metadata.posterUrl`.
+- The built-in Share action uses the Web Share API when available; it includes `title`/`text` only if provided, otherwise it shares just the current page URL.
+
+## Keyboard shortcuts (Web)
+- Space or K: Play/Pause
+- Arrow Left/Right: Seek -/+ 10s
+- Arrow Up/Down: Volume up/down
+- M: Mute/Unmute
+- F: Toggle Fullscreen
+- P: Picture-in-Picture
+- 0..9: Seek to 0%, 10%, …, 90%
+
+## Local demo (monorepo)
+- Build the web package:
+  - `npm run build:web`
+- Start the demo server from the repo root:
+  - `npm run serve:demo`
+- Open the enhanced demo:
+  - http://localhost:3000/apps/demo/enhanced-player.html
+
+## Tests (monorepo)
+- Run the web package tests:
+  - `npm run test -w packages/web`
+
+## Events and controls
+```ts
+// Listen to player events
+player.on('onPlay', () => console.log('playing'));
+player.on('onPause', () => console.log('paused'));
+player.on('onQualityChanged', (q) => console.log('quality ->', q?.label));
+player.on('onError', (err) => console.error('player error', err));
+
+// Control playback
+await player.play();
+player.pause();
+player.seek(60);        // 60 seconds
+player.setVolume(0.5);  // 50%
+player.toggleMute();
+
+// Query state
+console.log(player.getState());
+```
+
+## CDN / no-bundler usage (ESM via CDN)
+```html
+<div id="player"></div>
+
+<script type="module">
+  import { WebPlayer } from 'https://esm.sh/@unified-video/web';
+
+  const player = new WebPlayer();
+  await player.initialize('#player', { autoPlay: false });
+
+  await player.load({
+    url: 'https://example.com/video.mp4',
+    type: 'mp4',
+  });
+
+  await player.play();
+</script>
+```
+
+## Requirements
+- Modern browsers with standard DOM APIs.
+- For HLS/DASH playback, install `hls.js`/`dashjs` or allow the player to fetch them from CDNs at runtime.
+
+## Tip
+- To keep bundle size under control and avoid network fetches during playback startup, prefer installing `hls.js` and `dashjs` in your app rather than relying on runtime CDN loading.
+
+---
+
+## React usage
+
+A built-in React component is provided: `WebPlayerView`. It renders the enhanced UI and supports live theming via the `playerTheme` prop.
+
+Basic usage
+```tsx path=null start=null
+import React from 'react';
+import { WebPlayerView } from '@unified-video/web';
+
+export default function PlayerSection() {
+  return (
+    <div style={{ maxWidth: 960, margin: '0 auto' }}>
+      <WebPlayerView
+        url="https://example.com/stream.m3u8"
+        type="hls"
+        autoPlay={false}
+        muted={false}
+        enableAdaptiveBitrate={true}
+        cast={true} // loads Cast sender SDK and shows Cast button
+        metadata={{
+          title: 'My Stream',
+          description: 'An example stream with metadata-driven UI',
+          thumbnailUrl: 'https://example.com/thumb.jpg',
+          posterUrl: 'https://example.com/poster.jpg',
+        }}
+        playerTheme={{
+          accent: '#ff0000',
+          accent2: '#ff4d4f',
+          iconColor: '#ffffff',
+          textPrimary: '#ffffff',
+          textSecondary: 'rgba(255,255,255,0.75)',
+        }}
+        style={{ width: '100%' }}
+      />
+    </div>
+  );
+}
+```
+
+Dynamic theme updates
+```tsx path=null start=null
+import React, { useState } from 'react';
+import { WebPlayerView } from '@unified-video/web';
+
+export default function ThemedPlayer() {
+  const [theme, setTheme] = useState({
+    accent: '#ff0000',
+    accent2: '#ff4d4f',
+    iconColor: '#ffffff',
+    textPrimary: '#ffffff',
+    textSecondary: 'rgba(255,255,255,0.75)',
+  });
+
+  return (
+    <>
+      <div style={{ marginBottom: 12 }}>
+        <button onClick={() => setTheme({ accent: '#00bcd4', accent2: '#40c4ff', iconColor: '#fff', textPrimary: '#e6f7ff', textSecondary: 'rgba(230,247,255,0.7)' })}>
+          Switch to Cyan
+        </button>
+        <button onClick={() => setTheme('#7e57c2')} style={{ marginLeft: 8 }}>
+          Single Accent (Purple)
+        </button>
+      </div>
+
+      <WebPlayerView
+        url="https://example.com/stream.m3u8"
+        type="hls"
+        playerTheme={theme}
+        style={{ width: '100%', maxWidth: 960, margin: '0 auto' }}
+      />
+    </>
+  );
+}
+```
+
+Advanced tweaks (onReady)
+```tsx path=null start=null
+import React from 'react';
+import { WebPlayerView, WebPlayer } from '@unified-video/web';
+
+export default function PlayerWithControls() {
+  const onReady = (player: WebPlayer) => {
+    // Compact settings menu scrollbar and tuned look
+    player.setSettingsScrollbarStyle('compact'); // 'default' | 'compact' | 'overlay'
+    player.setSettingsScrollbarConfig({ widthPx: 6, intensity: 1 });
+  };
+
+  return (
+    <WebPlayerView
+      url="https://example.com/stream.m3u8"
+      type="hls"
+      onReady={onReady}
+      playerTheme="#00bcd4"
+    />
+  );
+}
+```
+
+Notes
+- `cast` adds the Cast sender SDK; a Cast button appears when the framework is ready and compatible devices are available.
+- Use client-side rendering for SSR frameworks.
+- The enhanced UI in React matches the web build and honors the same theme variables.

package/packages/web/jest.config.js

@@ -0,0 +1,28 @@
+module.exports = {
+  testEnvironment: 'jsdom',
+  roots: ['<rootDir>/src'],
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/__tests__/**/*.test.tsx',
+    '**/?(*.)+(spec|test).[tj]s?(x)'
+  ],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'babel-jest',
+      {
+        presets: [
+          ['@babel/preset-env', { targets: { node: 'current' } }],
+          '@babel/preset-typescript'
+        ]
+      }
+    ]
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'json'],
+  moduleNameMapper: {
+    '^@unified-video/core$': '<rootDir>/../core/src/index.ts',
+    '^@unified-video/core/(.*)$': '<rootDir>/../core/src/$1'
+  },
+  transformIgnorePatterns: ['/node_modules/'],
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
+};
+

package/packages/web/jest.setup.ts

@@ -0,0 +1,110 @@
+// Jest setup for DOM APIs not implemented by JSDOM
+
+// Mock HTMLMediaElement methods used by the player
+Object.defineProperty(HTMLMediaElement.prototype, 'load', {
+  configurable: true,
+  value: jest.fn()
+});
+Object.defineProperty(HTMLMediaElement.prototype, 'play', {
+  configurable: true,
+  value: jest.fn().mockResolvedValue()
+});
+Object.defineProperty(HTMLMediaElement.prototype, 'pause', {
+  configurable: true,
+  value: jest.fn()
+});
+
+// Mock Canvas 2D context
+Object.defineProperty(HTMLCanvasElement.prototype, 'getContext', {
+  configurable: true,
+  value: () => {
+    return {
+      clearRect: jest.fn(),
+      fillText: jest.fn(),
+      createLinearGradient: () => ({ addColorStop: jest.fn() }),
+      font: '',
+      fillStyle: '',
+      textAlign: 'left'
+    } as any;
+  }
+});
+
+// Stub HLS.js for tests to avoid dynamic script loading
+// Provides minimal API used by WebPlayer
+// @ts-ignore
+window.Hls = {
+  isSupported: () => true,
+  Events: {
+    MANIFEST_PARSED: 'manifestParsed',
+    LEVEL_SWITCHED: 'levelSwitched',
+    ERROR: 'error'
+  },
+  ErrorTypes: {
+    NETWORK_ERROR: 'networkError',
+    MEDIA_ERROR: 'mediaError'
+  }
+};
+
+// Provide constructor behavior
+// @ts-ignore
+window.Hls = class {
+  static isSupported() { return true; }
+  static Events = {
+    MANIFEST_PARSED: 'manifestParsed',
+    LEVEL_SWITCHED: 'levelSwitched',
+    ERROR: 'error'
+  };
+  static ErrorTypes = {
+    NETWORK_ERROR: 'networkError',
+    MEDIA_ERROR: 'mediaError'
+  };
+  private handlers: Record<string, Function[]> = {};
+  constructor(_: any) {}
+  loadSource(_: string) {}
+  attachMedia(_: HTMLVideoElement | null) {}
+  on(evt: string, handler: Function) {
+    this.handlers[evt] = this.handlers[evt] || [];
+    this.handlers[evt].push(handler);
+  }
+  startLoad() {}
+  recoverMediaError() {}
+  destroy() {}
+  get currentLevel() { return -1; }
+  set currentLevel(_val: number) {}
+};
+
+// Stub dash.js for tests to avoid dynamic script loading
+// @ts-ignore
+(function(){
+  const MediaPlayer = function() {
+    return {
+      create() {
+        const listeners: Record<string, Function[]> = {};
+        return {
+          initialize: (_video: HTMLVideoElement | null, _url: string, _autoPlay?: boolean) => {},
+          updateSettings: (_: any) => {},
+          on: (evt: string, handler: Function) => {
+            listeners[evt] = listeners[evt] || [];
+            listeners[evt].push(handler);
+          },
+          reset: () => {},
+          setQualityFor: (_type: string, _index: number) => {},
+          getBitrateInfoListFor: (_type: string) => [
+            { height: 1080, width: 1920, bitrate: 4000000 },
+            { height: 720, width: 1280, bitrate: 2500000 }
+          ]
+        } as any;
+      }
+    };
+  };
+  // Attach static events map to function object
+  // @ts-ignore
+  MediaPlayer.events = {
+    QUALITY_CHANGE_RENDERED: 'qualityChangeRendered',
+    STREAM_INITIALIZED: 'streamInitialized',
+    ERROR: 'error'
+  };
+  // @ts-ignore
+  window.dashjs = { MediaPlayer };
+})();
+