Unified Video Framework

Common errors

• Player element not found: #unified-player

  cause The HTML element specified as the player container (`config.container`) does not exist in the DOM when the player is initialized, or its ID is incorrect.
  fix Ensure the target HTML element is rendered before the player initialization script runs. Verify the ID matches exactly, e.g., `<div id="unified-player"></div>`.

• Error: Unsupported video format or codec.

  cause The provided video `source.url` points to a file with an unsupported format or codec for the current browser/platform, or the `source.type` is incorrect.
  fix Verify the video URL is accessible and the content type (`video/mp4`, `application/x-mpegURL`, `application/dash+xml`) matches the actual media format. Test with commonly supported formats first. Ensure any required DRM or adaptive streaming configurations are correctly applied.

• TypeScript Error: Property 'on' does not exist on type 'UnifiedVideoPlayer'.

  cause The `UnifiedVideoPlayer` instance's event listener methods are not recognized, often due to an outdated type definition, incorrect import, or a change in the API for event handling.
  fix Ensure you are using the correct version of `@types/unified-video-framework` (if a separate types package exists) or that the `unified-video-framework` package is up-to-date. Refer to the official documentation for the correct event subscription API (e.g., `player.addEventListener('play', ...)` or `player.on('play', ...)`).

Warnings

• gotcha Key platforms like iOS/Android (Native/React Native), Smart TVs (Tizen, webOS), and Streaming Devices (Roku, Apple TV, Android TV) are explicitly listed as 'On Progress' in the README. This implies that the SDK's functionality, stability, and feature completeness on these platforms may not be fully mature or may change significantly.
  Fix: Always refer to the latest official documentation or release notes for platform-specific capabilities and limitations. Thoroughly test features on 'on progress' platforms before relying on them in production.
• breaking Due to the 'On Progress' status for several core platforms, minor version updates may introduce breaking changes or require significant refactoring for platform-specific integrations as the API evolves and stabilizes. Always review release notes carefully.
  Fix: Pin to specific patch versions (`~1.x.x` or `1.x.x`) rather than major (`^1.x.x`) if strict API stability is required during rapid development phases. Automate testing across target platforms to catch regressions early.
• gotcha The framework's core value proposition is a 'unified API' across platforms. However, platform-specific integrations (e.g., DRM, advertising, native UI overlays) may still require platform-specific code or configurations that diverge from the unified API, especially for 'On Progress' platforms.
  Fix: Consult the official Flicknexs documentation and examples for each target platform. Plan for potential platform-specific adaptations beyond the core unified player API, particularly for advanced features or complex integrations.

Install

• npm install unified-video-framework npm
• yarn add unified-video-framework yarn
• pnpm add unified-video-framework pnpm

Imports

• UnifiedVideoPlayer
  wrong:

  const UnifiedVideoPlayer = require('unified-video-framework');

  correct:

  import { UnifiedVideoPlayer } from 'unified-video-framework';

  The library primarily uses ES Modules. CommonJS `require` syntax is generally incorrect for modern usage, especially in TypeScript or bundler environments. The main player class/constructor is expected to be a named export.
• PlayerConfig

  import type { PlayerConfig } from 'unified-video-framework';

  Imports for TypeScript types should use `import type` to ensure they are stripped from the JavaScript output, preventing runtime errors or unnecessary bundle size in environments that don't support type imports natively.
• VideoSource

  import { UnifiedVideoPlayer, type VideoSource } from 'unified-video-framework';

  Assuming a `VideoSource` type or interface exists for defining video content. It's often co-imported with the player for configuration.

Quickstart

This quickstart demonstrates how to initialize the `UnifiedVideoPlayer` in a web environment, attach it to a DOM element, configure a video source, and listen for basic playback events.

import { UnifiedVideoPlayer } from 'unified-video-framework';

document.addEventListener('DOMContentLoaded', () => {
  const playerElement = document.getElementById('unified-player');
  if (!playerElement) {
    console.error('Player element #unified-player not found in DOM.');
    return;
  }

  // Example configuration, adjust as per actual API documentation
  const config = {
    container: playerElement,
    source: {
      url: 'https://cdn.example.com/your-video.mp4',
      type: 'video/mp4' // Or 'application/x-mpegURL' for HLS, 'application/dash+xml' for DASH
    },
    autoplay: true,
    controls: true,
    // An API key might be required for certain features or backend services
    // apiKey: process.env.UNIFIED_PLAYER_API_KEY ?? '' 
  };

  try {
    const player = new UnifiedVideoPlayer(config);
    player.on('play', () => console.log('Video started playing.'));
    player.on('ended', () => console.log('Video ended.'));
    console.log('Unified Video Player initialized successfully.');
  } catch (error) {
    console.error('Failed to initialize Unified Video Player:', error);
  }
});