OvenPlayer Documentation

OvenPlayer is an open-source HTML5 player designed for sub-second latency streaming, specifically optimized for OvenMediaEngine (OME) via WebRTC.

Key Capabilities:

• Protocol Support: WebRTC (for sub-second latency), HLS, Low Latency MPEG-DASH (LLDASH), and standard MPEG-DASH.
• Automatic Fallback: Automatically switches to HLS or MPEG-DASH if WebRTC is unavailable.
• Signaling: Conforms to the OME signaling protocol specification.
• DRM Support: Plays DRM-protected HLS using FairPlay, Widevine, and PlayReady.
• Subtitles: Supports SMI, VTT, and SRT formats.
• UI: Features a customizable and responsive user interface.

OvenPlayer is a JavaScript-based HTML5 video player optimized for low-latency streaming, specifically designed to work with OvenMediaEngine.

Supported Streaming Protocols

• Sub-Second Latency: WebRTC (Signalling Protocol conforms to the OME Specification).
• Low Latency: LLHLS, LLDASH (Chunked CMAF).
• Legacy: HLS, MPEG-DASH.

Key Capabilities

• Automatic Fallback: Automatically switches between streaming protocols if one fails.
• Customization: Fully customizable UI and SDK.
• Ad Insertion: Supports VAST4, VAST3, VAST2, VPAID2 (HTML5), and VMAP1.0.1.
• Subtitle Support: Supports SMI, VTT, and SRT formats.

OvenPlayer uses a utility called LikeA$ (similar to jQuery) to search, access, and manipulate elements within the player.

Common Operations

• Create/Select: let $player = LA$('#player');
• Search: $player.find('.className');
• Access raw element: $player.find('.className').get();
• Modify CSS: $player.find('.className').css('color', '#ffffff');

Note: LikeA$ is used within the template system via $container (the parent element) and $current (the element owned by the current template item).

import LA$ from 'utils/likeA$';

let $player = LA$('#player');
$player.find('.textView');
$player.find('.textView').get();
$player.find('.textView').css('color', '#d9d9d9');

OvenPlayer uses an event-driven architecture to notify consumers about changes in playback state, media metadata, UI interactions, and underlying stream protocols (HLS/DASH).

Developers can subscribe to these events to synchronize external UI components, track analytics, or trigger custom logic when specific conditions are met (e.g., when a user seeks, when the buffer changes, or when the player is resized).

The OvenPlayer UI is built using a template system where each component consists of a controller and a view.

• Controller ({name}.js): Handles logic, lifecycle, and events.
• View ({name}Template.js): Returns the HTML string for the component.

Template Lifecycle

A template follows a minimal lifecycle:

1. onRendered(): Called when the template is rendered onto the screen.
2. onDestroyed(): Called when the template is removed.

Component Hierarchy

• view/view.js is the top-level parent template.
• view.js creates child Controls and Helpers templates.
• Controls and Helpers in turn create and manage their own child templates.

When running on an iPhone, iPad, or iPod, OvenPlayer uses the device's native engine instead of hls.js. This changes the FairPlay key exchange behavior:

• Requirements: Both licenseUrl and serverCertificateUrl are strictly required.
• Certificate: The player fetches the server certificate as base64 text and decodes it.
• Request Format: The license request is a POST with Content-Type: application/x-www-form-urlencoded and a body of spc=<base64-encoded SPC>.
• Response Format: The license server must respond with the base64-encoded CKC as the response body.
• Headers: licenseHeaders are applied to this native request just as they are in the hls.js path.

Warning: If your license server only implements the form-encoded spc= contract, verify compatibility with macOS Safari separately, as macOS Safari uses the hls.js path.

To build the modified source code into a production-ready format, use the build script. The resulting built files will be located in the dist/ directory. Note that if you are cloning the project for the first time, pre-built files may already exist in the dist/ directories.

npm run build

Every MDX documentation page must include a YAML frontmatter block at the top to define its metadata. This metadata controls how the page is titled, ordered in the sidebar, and described by search engines.

Required fields:

• description: A one-sentence meta description (~120–155 characters) that includes the term "OvenPlayer". This is critical for SEO and AI discoverability. If omitted, the site uses a low-quality auto-excerpt.

Optional fields:

• title: The page title used in the browser tab and as the H1 heading.
• sidebar_position: An integer determining the order within a section (lower numbers appear higher).
• slug: Overrides the default URL path (e.g., slug: / for an intro page).

---
title: Initialization
sidebar_position: 2
description: How to initialize OvenPlayer on a web page.
---