ogplayer 0.1.0

package/dist/core/player.d.ts

@@ -0,0 +1,182 @@
+import { type AudioTrack, type LiveInfo, type OGAnalyticsListener, type OGMediaItem, type PlaybackListener, type PlaybackState, type SubtitleStyle, type TextTrack as OGTextTrack, type ThumbnailFrame, type VideoQuality, type VolumeControlMode } from "./types.js";
+import type { AdListener } from "../ads/types.js";
+import type { AdsProvider } from "../ads/provider.js";
+export interface OGPlayerOptions {
+    /** Offline license key (`OGP1.…`); without one the watermark shows. */
+    licenseKey?: string;
+    /** onProgress cadence, default 250ms (Android DEFAULT_PROGRESS_INTERVAL_MS). */
+    progressUpdateIntervalMs?: number;
+    /** Seek button increments, default 10s each way. */
+    seekForwardIncrementMs?: number;
+    seekBackwardIncrementMs?: number;
+}
+export interface LoadOptions {
+    startPositionMs?: number;
+    autoplay?: boolean;
+}
+/**
+ * The OGPlayer playback engine — the web counterpart of the Android
+ * `OGPlayer` (the reference platform), wrapping an HTML `<video>` element:
+ * HLS via hls.js (MSE) everywhere, natively on Safari, progressive files
+ * directly. UI is `<og-player>` from the `ui` module; the engine also works
+ * fully headless.
+ */
+export declare class OGPlayer {
+    readonly videoElement: HTMLVideoElement;
+    private hls;
+    private item;
+    private stateValue;
+    private listeners;
+    private analyticsListeners;
+    private adListeners;
+    private progressTimer;
+    private snapshotTimer;
+    private opts;
+    private startedOnce;
+    private didDispatchPause;
+    private seekTargetMs;
+    private atLiveEdgeValue;
+    private wasEnded;
+    private licensedValue;
+    private licenseListeners;
+    private loadGeneration;
+    private lastBitrate;
+    private sideloadedDefaultId;
+    private nativeLoadListeners;
+    private detachDrm;
+    private sawEncrypted;
+    private drmKeysAnnounced;
+    private drmLicenseRequests;
+    private thumbnailTrack;
+    private lastDroppedTotal;
+    /** Saved content position while a content-element ads provider holds the
+     * media element (FreeWheel handoff). */
+    private breakResume;
+    /** Opt-in client-side ads integration (e.g. `ImaAdsProvider`). Set before
+     * `load()`ing an item with `adBreaks`. */
+    adsProvider: AdsProvider | null;
+    private adContainer;
+    private attachedAdsProvider;
+    private pendingAdConfig;
+    /** Video+tag sessions whose whole ad schedule finished — watched ads are
+     *  not re-requested when the same video+tag reloads in this instance. */
+    private completedAdSessions;
+    private currentAdSessionKey;
+    /** Last item passed to load() — what retry() reloads. */
+    private lastLoadedItem;
+    /** Position from the last healthy progress tick — where retry() resumes. */
+    private lastStablePositionMs;
+    private pendingContentAutoplay;
+    private isPlayingAdFlag;
+    private adsPendingFlag;
+    private adPausedFlag;
+    private adProgressValue;
+    private adCuePointsValue;
+    private lastAdInfo;
+    /** Break transitions on ACTIVE content are silent (mobile parity). */
+    private suppressAdBreakTransition;
+    /** While true, nothing may start playback — play() and every internal
+     * resume path no-op. Used by the hard ad-block policy; equally useful for
+     * host-side gates (paywalls, age gates). */
+    holdPlayback: boolean;
+    constructor(options?: OGPlayerOptions);
+    get state(): PlaybackState;
+    get isPlaying(): boolean;
+    get currentItem(): OGMediaItem | null;
+    get currentPositionMs(): number;
+    get durationMs(): number;
+    get bufferedPositionMs(): number;
+    get playbackSpeed(): number;
+    set playbackSpeed(v: number);
+    get volume(): number;
+    set volume(v: number);
+    get isMuted(): boolean;
+    set isMuted(v: boolean);
+    /** Web routes all volume to the element; kept for API parity. */
+    volumeControlMode: VolumeControlMode;
+    get isLicensed(): boolean;
+    get seekForwardIncrementMs(): number;
+    get seekBackwardIncrementMs(): number;
+    get isPlayingAd(): boolean;
+    /** True between an autoplay load-with-ads and the first provider verdict
+     * (content pause OR resume) — the UI keeps controls hidden meanwhile. */
+    get adsPending(): boolean;
+    get adPaused(): boolean;
+    /** Progress of the current ad (drives the yellow ad bar), or null. */
+    get adProgress(): {
+        positionMs: number;
+        durationMs: number;
+        adIndex: number;
+        adCount: number;
+    } | null;
+    /** VMAP cue-point times in seconds (negative = postroll). */
+    get adCuePoints(): number[];
+    get currentLoadGeneration(): number;
+    subtitleStyle: SubtitleStyle;
+    subtitleTextScale: number;
+    onLicenseChanged(cb: (licensed: boolean) => void): void;
+    addListener(l: PlaybackListener): void;
+    removeListener(l: PlaybackListener): void;
+    addAnalyticsListener(l: OGAnalyticsListener): void;
+    removeAnalyticsListener(l: OGAnalyticsListener): void;
+    addAdListener(l: AdListener): void;
+    removeAdListener(l: AdListener): void;
+    private dispatch;
+    private emit;
+    load(item: OGMediaItem, options?: LoadOptions): void;
+    /** Wire the media pipeline for `item` — everything about the SOURCE, none
+     * of the session state. Reused to restore content after a provider that
+     * plays ads in the content element (FreeWheel) hands it back. */
+    /**
+     * Reloads the last loaded item after a fatal error — VOD resumes at the
+     * last healthy playback position, live streams rejoin at the edge. The
+     * built-in error overlay's Retry button calls this; hosts building their
+     * own UI can too. No-op before the first load().
+     */
+    retry(): void;
+    private attachSource;
+    private adSessionKey;
+    private beginAdsIfNeeded;
+    private startAdsSession;
+    private resetAdSession;
+    private dispatchAd;
+    /** Provider → player bridge (the web `AdsProviderCallbacks`). */
+    private readonly adCallbacks;
+    play(): void;
+    pause(): void;
+    skipAd(): void;
+    clickAd(): void;
+    /** Ad-break cue positions in ms, Android encoding (postroll = duration). */
+    get adCuePositionsMs(): number[];
+    /** True when the current item carries a storyboard (trick-play) track. */
+    get hasThumbnails(): boolean;
+    /** The storyboard frame covering `positionMs`, or null (mobile parity:
+     * `getThumbnail`). The frame is a crop within a sprite image. */
+    getThumbnail(positionMs: number): Promise<ThumbnailFrame | null>;
+    /** Supplied by `<og-player>`: the element IMA renders its ad UI into. */
+    attachAdContainer(el: HTMLElement): void;
+    /** The player surface was resized — keep the ad UI matched. */
+    notifyAdViewResize(width: number, height: number, fullscreen: boolean): void;
+    seekTo(positionMs: number): void;
+    seekForward(): void;
+    seekBackward(): void;
+    seekToLiveEdge(): void;
+    release(): void;
+    private teardownSource;
+    get audioTracks(): AudioTrack[];
+    selectAudioTrack(id: string): void;
+    /** Embedded + sideloaded subtitle tracks, unified (sideloaded ids `ext-N`). */
+    get textTracks(): OGTextTrack[];
+    selectTextTrack(id: string | null): void;
+    get videoQualities(): VideoQuality[];
+    selectVideoQuality(id: string): void;
+    get liveInfo(): LiveInfo | null;
+    private setState;
+    private bindVideoEvents;
+    private bindHlsEvents;
+    private attachSideloadedSubtitles;
+    private startProgressTimer;
+    private stopProgressTimer;
+    private startSnapshotTimer;
+    private stopSnapshotTimer;
+}

package/dist/core/thumbnails.d.ts

@@ -0,0 +1,26 @@
+import type { ThumbnailFrame } from "./types.js";
+/**
+ * Storyboard (trick-play) track — the web counterpart of the mobile SDKs'
+ * `hasThumbnails` / `getThumbnail`. Parses a WebVTT storyboard where each cue
+ * names a sprite image, optionally with a `#xywh=` media fragment (the format
+ * Mux, JW and Bitmovin tooling emit):
+ *
+ *     00:00:00.000 --> 00:00:05.000
+ *     storyboard.jpg#xywh=0,0,284,160
+ */
+interface Cue {
+    startMs: number;
+    endMs: number;
+    frame: ThumbnailFrame;
+}
+export declare function parseStoryboardVtt(vtt: string, baseUrl: string): Cue[];
+/** Lazily-fetched storyboard for one media item. */
+export declare class ThumbnailTrack {
+    private readonly vttUrl;
+    private cues;
+    private loading;
+    constructor(vttUrl: string);
+    private ensureLoaded;
+    frameAt(positionMs: number): Promise<ThumbnailFrame | null>;
+}
+export {};

package/dist/core/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * OGPlayer web SDK — public model types. The web counterpart of Android's
+ * `com.ogplayer.api` (the reference platform): same names, same semantics,
+ * so code and docs translate 1:1 across Android / iOS / web.
+ */
+export type StreamType = "VOD" | "LIVE" | "LIVE_DVR";
+export type PlaybackState = "IDLE" | "BUFFERING" | "READY" | "ENDED";
+/** Web has no per-app device-volume routing; DEVICE behaves like PLAYER. */
+export type VolumeControlMode = "DEVICE" | "PLAYER";
+export interface SubtitleSource {
+    url: string;
+    language: string;
+    label: string;
+    isDefault?: boolean;
+}
+export type SubtitleEdgeType = "NONE" | "OUTLINE" | "DROP_SHADOW" | "RAISED" | "DEPRESSED";
+/** Caption styling — colors are CSS color strings on the web. */
+export interface SubtitleStyle {
+    textSizeFraction: number;
+    foregroundColor: string;
+    backgroundColor: string;
+    windowColor: string;
+    edgeType: SubtitleEdgeType;
+    edgeColor: string;
+    applyEmbeddedStyles: boolean;
+}
+export declare const DEFAULT_TEXT_SIZE_FRACTION = 0.045;
+export declare const defaultSubtitleStyle: SubtitleStyle;
+export type ContentRatingAge = "ALL" | "SIX" | "NINE" | "TWELVE" | "FOURTEEN" | "SIXTEEN" | "EIGHTEEN";
+export type ContentRatingDescriptor = "VIOLENCE" | "FEAR" | "SEX" | "DISCRIMINATION" | "DRUGS_ALCOHOL" | "COARSE_LANGUAGE";
+/** Kijkwijzer-style presets + custom icon URL (the web `Custom`). */
+export type ContentRating = {
+    age: ContentRatingAge;
+} | {
+    descriptor: ContentRatingDescriptor;
+} | {
+    customIconUrl: string;
+};
+export interface DrmSchemeConfig {
+    licenseUrl: string;
+    headers?: Record<string, string>;
+}
+/** Why a DRM session was renewed (mobile parity). */
+export type DrmRenewalReason = "PROACTIVE" | "REACTIVE";
+/** One license request about to go out — passed to the token provider. */
+export interface DrmTokenRequest {
+    licenseUrl: string;
+    /** True when this is a renewal on an existing session, not the first key. */
+    renewal: boolean;
+}
+/**
+ * Fresh headers for every license request — the web counterpart of the
+ * Android/iOS token providers. Called per request (renewals included) so
+ * expiring tokens can rotate; the result is merged OVER the scheme's static
+ * `headers`. Failures surface as DRM_TOKEN_FETCH_FAILED (4002).
+ */
+export type DrmTokenProvider = (request: DrmTokenRequest) => Promise<Record<string, string>>;
+/**
+ * Multi-DRM configuration — the web counterpart of Android's `DrmConfig` /
+ * iOS's `FairPlayConfig`, unified: configure every scheme you have and the
+ * SDK picks whichever the visitor's browser supports (Chrome/Firefox/Android
+ * → Widevine, Edge → PlayReady or Widevine, Safari → FairPlay).
+ */
+export interface DrmConfig {
+    widevine?: DrmSchemeConfig & {
+        serverCertificateUrl?: string;
+    };
+    playready?: DrmSchemeConfig;
+    fairplay?: DrmSchemeConfig & {
+        certificateUrl: string;
+    };
+    /** Rotating-token hook, applied to whichever scheme engages. */
+    tokenProvider?: DrmTokenProvider;
+}
+export interface OGMediaItem {
+    url: string;
+    streamType?: StreamType;
+    title?: string;
+    drm?: DrmConfig;
+    sideloadedSubtitles?: SubtitleSource[];
+    contentRatings?: ContentRating[];
+    thumbnailTrackUrl?: string;
+    /** Interpreted by the active ads provider (web providers ship later). */
+    adBreaks?: import("../ads/types.js").AdBreakConfig;
+}
+export interface AudioTrack {
+    id: string;
+    label: string;
+    language: string;
+    channelCount: number;
+    isSelected: boolean;
+}
+export interface TextTrack {
+    id: string;
+    label: string;
+    language: string;
+    isSelected: boolean;
+}
+export interface VideoQuality {
+    id: string;
+    width: number;
+    height: number;
+    bitrate: number;
+    isSelected: boolean;
+}
+export interface LiveInfo {
+    streamType: StreamType;
+    dvrWindowMs: number;
+    atLiveEdge: boolean;
+    latencyMs: number;
+    playheadWallClockMs: number | null;
+}
+/** Android's PlaybackListener, method-for-method. All members optional. */
+export interface PlaybackListener {
+    onStateChanged?(state: PlaybackState): void;
+    onPlay?(): void;
+    onPause?(): void;
+    onResume?(): void;
+    onIsPlayingChanged?(isPlaying: boolean): void;
+    onProgress?(positionMs: number, bufferedMs: number, durationMs: number): void;
+    onSeekStarted?(fromMs: number, toMs: number): void;
+    onSeekCompleted?(positionMs: number): void;
+    onPlaybackCompleted?(): void;
+    onLiveEdgeChanged?(atLiveEdge: boolean): void;
+    onDrmSessionRenewed?(reason: DrmRenewalReason): void;
+    onError?(error: OGPlayerError): void;
+}
+/** One frame of a storyboard/trick-play track: a crop within a sprite. */
+export interface ThumbnailFrame {
+    /** Sprite image URL (resolved against the storyboard VTT). */
+    url: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type AnalyticsEvent = {
+    type: "Play";
+} | {
+    type: "Pause";
+} | {
+    type: "Seek";
+    fromMs: number;
+    toMs: number;
+} | {
+    type: "BufferStart";
+} | {
+    type: "BufferEnd";
+} | {
+    type: "BitrateChanged";
+    bitrate: number;
+    width: number;
+    height: number;
+    frameRate: number;
+} | {
+    type: "QualitySnapshot";
+    positionMs: number;
+    bufferedMs: number;
+    bandwidthEstimateBps: number;
+    droppedFramesTotal: number;
+} | {
+    type: "DroppedFrames";
+    count: number;
+    elapsedMs: number;
+} | {
+    type: "DrmKeysLoaded";
+} | {
+    type: "Complete";
+} | {
+    type: "Error";
+    error: OGPlayerError;
+};
+export type OGAnalyticsListener = (event: AnalyticsEvent) => void;
+/** Error taxonomy — same numeric codes as Android/iOS. */
+export declare const ErrorCodes: {
+    readonly NETWORK_CONNECTION_FAILED: 2000;
+    readonly NETWORK_TIMEOUT: 2001;
+    readonly NETWORK_HTTP_STATUS: 2002;
+    readonly SOURCE_MALFORMED: 3000;
+    readonly SOURCE_UNSUPPORTED: 3001;
+    readonly SOURCE_NOT_FOUND: 3002;
+    readonly DRM_LICENSE_FAILED: 4000;
+    readonly DRM_LICENSE_HTTP_STATUS: 4001;
+    readonly DRM_TOKEN_FETCH_FAILED: 4002;
+    readonly DRM_PROVISIONING_FAILED: 4003;
+    readonly DRM_SESSION_EXPIRED: 4004;
+    readonly DRM_UNSUPPORTED: 4005;
+    readonly DECODER_INIT_FAILED: 5000;
+    readonly DECODING_FAILED: 5001;
+    readonly AUDIO_OUTPUT_FAILED: 5002;
+    readonly BEHIND_LIVE_WINDOW: 6000;
+    readonly UNKNOWN: 9000;
+};
+export type ErrorCategory = "Network" | "Source" | "Drm" | "Renderer" | "Live" | "Unknown";
+export interface OGPlayerError {
+    code: number;
+    codeName: string;
+    category: ErrorCategory;
+    message: string;
+    retryable: boolean;
+    httpStatusCode?: number;
+    cause?: unknown;
+}
+export declare const OGPLAYER_VERSION = "0.1.0";

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * OGPlayer web SDK — one video player API across Android, iOS and the web.
+ * A product of Inverse DOO.
+ */
+export { OGPlayer, type OGPlayerOptions, type LoadOptions } from "./core/player.js";
+export * from "./core/types.js";
+export { verifyLicense, type LicenseResult } from "./core/license.js";
+export * from "./ads/types.js";
+export type { AdsProvider, AdsProviderCallbacks } from "./ads/provider.js";
+export { ImaAdsProvider, type ImaAdsProviderOptions } from "./ads/ima.js";
+export { freewheelVmapTagUrl, isFreewheelConfig, type FreewheelConfig } from "./ads/freewheel.js";
+export { FreewheelAdsProvider, type FreewheelAdsProviderOptions } from "./ads/freewheel-provider.js";
+export { OGPlayerElement, defineOGPlayerElement, hidingAllControls, type OGUIConfig, type CustomAction, defaultUIConfig, } from "./ui/og-player.js";
+export type { OGControlColors, OGControlDimens } from "./ui/tokens.js";
+export { defaultColors, embeddedDimens, fullscreenDimens } from "./ui/tokens.js";
+/** Build timestamp of this bundle (diagnosing stale caches). */
+export declare const OGPLAYER_BUILD: string;