ogplayer 0.1.1 → 0.2.0

package/dist/core/player.d.ts

@@ -1,3 +1,4 @@
+import { type HlsConfig } from "hls.js";
 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";
@@ -9,6 +10,22 @@ export interface OGPlayerOptions {
     /** Seek button increments, default 10s each way. */
     seekForwardIncrementMs?: number;
     seekBackwardIncrementMs?: number;
+    /**
+     * Extra hls.js configuration merged over the SDK's defaults — buffer
+     * targets, ABR knobs, anything hls.js accepts. SDK-managed fields
+     * (EME/DRM wiring, text-track rendering) win over conflicting keys.
+     */
+    hlsConfig?: Partial<HlsConfig>;
+    /** `<video preload>` hint, default "auto". "metadata" defers segment
+     *  loading until play — the standby setting for pooled players. */
+    preload?: "" | "none" | "metadata" | "auto";
+    /**
+     * When the browser blocks autoplay-with-audio (NotAllowedError), retry
+     * muted instead of staying paused. Fires `onMutedAutoplayFallback` and a
+     * `MutedAutoplayFallback` analytics event so the UI can offer unmute.
+     * Default false — the standard player shows the big play button instead.
+     */
+    fallbackToMutedAutoplay?: boolean;
 }
 export interface LoadOptions {
     startPositionMs?: number;
@@ -75,6 +92,10 @@ export declare class OGPlayer {
     private lastAdInfo;
     /** Break transitions on ACTIVE content are silent (mobile parity). */
     private suppressAdBreakTransition;
+    private hlsConfig;
+    /** See `OGPlayerOptions.fallbackToMutedAutoplay`; mutable so a host (or
+     *  the vertical feed pool) can flip it per lifecycle phase. */
+    fallbackToMutedAutoplay: boolean;
     /** 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). */
@@ -92,6 +113,17 @@ export declare class OGPlayer {
     set volume(v: number);
     get isMuted(): boolean;
     set isMuted(v: boolean);
+    /** Loop the current item seamlessly (native `<video loop>`); survives
+     *  across load() calls, mirroring Android/iOS `setLooping`. */
+    get isLooping(): boolean;
+    setLooping(v: boolean): void;
+    /**
+     * Buffer discipline for pooled players (the vertical feed): STANDBY caps
+     * appetite (10s forward / 8MB, no back-buffer, metadata-only preload for
+     * progressive sources); ACTIVE restores full defaults. Mirrors Android's
+     * `setBufferRole` / iOS `setPreferredForwardBufferDuration`.
+     */
+    setBufferRole(role: "STANDBY" | "ACTIVE"): void;
     /** Web routes all volume to the element; kept for API parity. */
     volumeControlMode: VolumeControlMode;
     get isLicensed(): boolean;

package/dist/core/types.d.ts

@@ -23,6 +23,12 @@ export interface SubtitleStyle {
     edgeType: SubtitleEdgeType;
     edgeColor: string;
     applyEmbeddedStyles: boolean;
+    /**
+     * Caption font-family (any CSS font-family value, e.g. "Georgia, serif");
+     * null = platform default. Accessibility note: captions are a reading
+     * surface — prefer a highly legible face and test at small sizes.
+     */
+    fontFamily: string | null;
 }
 export declare const DEFAULT_TEXT_SIZE_FRACTION = 0.045;
 export declare const defaultSubtitleStyle: SubtitleStyle;
@@ -76,6 +82,9 @@ export interface OGMediaItem {
     url: string;
     streamType?: StreamType;
     title?: string;
+    /** Poster image shown by the UI until playback first starts (native
+     *  <video poster>). */
+    posterUrl?: string;
     drm?: DrmConfig;
     sideloadedSubtitles?: SubtitleSource[];
     contentRatings?: ContentRating[];
@@ -123,6 +132,9 @@ export interface PlaybackListener {
     onPlaybackCompleted?(): void;
     onLiveEdgeChanged?(atLiveEdge: boolean): void;
     onDrmSessionRenewed?(reason: DrmRenewalReason): void;
+    /** The browser blocked autoplay-with-audio and `fallbackToMutedAutoplay`
+     *  restarted playback muted — show your own unmute affordance. */
+    onMutedAutoplayFallback?(): void;
     onError?(error: OGPlayerError): void;
 }
 /** One frame of a storyboard/trick-play track: a crop within a sprite. */
@@ -166,6 +178,22 @@ export type AnalyticsEvent = {
     type: "DrmKeysLoaded";
 } | {
     type: "Complete";
+} | {
+    type: "MutedAutoplayFallback";
+} | {
+    type: "VerticalFeedImpression";
+    index: number;
+    url: string;
+} | {
+    type: "VerticalFeedItemLooped";
+    index: number;
+    loopCount: number;
+} | {
+    type: "VerticalFeedItemWatched";
+    index: number;
+    url: string;
+    watchTimeMs: number;
+    loopCount: number;
 } | {
     type: "Error";
     error: OGPlayerError;
@@ -201,4 +229,4 @@ export interface OGPlayerError {
     httpStatusCode?: number;
     cause?: unknown;
 }
-export declare const OGPLAYER_VERSION = "0.1.0";
+export declare const OGPLAYER_VERSION: string;

package/dist/core/vertical-feed.d.ts

@@ -0,0 +1,126 @@
+import { OGPlayer } from "./player.js";
+import type { AnalyticsEvent, OGMediaItem, OGPlayerError } from "./types.js";
+/**
+ * Vertical feed data model + player pool — the web counterpart of the
+ * Android `VerticalFeedPlayerPool` (the reference implementation) and its
+ * iOS mirror. The pool owns at most `preloadAhead + keepBehind + 1` (≤3)
+ * engine instances: neighbours of the visible page sit PREPARED — muted,
+ * paused at 0, on capped standby buffers — so swipes start instantly;
+ * pages outside the window are recycled; everything is released on dispose.
+ *
+ * The UI element `<og-vertical-feed>` drives this; the pool is UI-free and
+ * unit-testable.
+ */
+export type SplitAudioSource = "PRIMARY" | "SECONDARY";
+export type TextPlacement = "OVERLAY" | "ABOVE_VIDEO" | "BELOW_VIDEO";
+export type VerticalFeedContentFit = "FILL" | "FIT";
+/** One action on the feed's right rail — the host's buttons; the SDK ships
+ *  none. State changes flow by re-supplying the items array. */
+export interface RailAction {
+    /** Inline SVG markup for the icon (24×24 viewBox recommended). */
+    iconSvg: string;
+    /** Optional label under the icon (usually a count or a state word). */
+    label?: string;
+    isActive?: boolean;
+    accessibilityLabel?: string;
+    onClick: () => void;
+}
+/** One entry of a vertical feed: media plus feed-specific presentation. */
+export interface OGVerticalFeedItem {
+    media: OGMediaItem;
+    /** Second source for the split-video layout: plays in the bottom half,
+     *  starts in the same frame as the primary, pauses/resumes with it. */
+    secondaryMedia?: OGMediaItem;
+    /** Which half of a split-video page is audible (default PRIMARY). */
+    splitAudioSource?: SplitAudioSource;
+    /** Per-item override of the feed-level fit. */
+    contentFit?: VerticalFeedContentFit;
+    /** Poster shown for pages outside the player window. Falls back to
+     *  `media.posterUrl`. */
+    posterUrl?: string;
+    /** Up to six host buttons for the right rail. */
+    railActions?: RailAction[];
+    title?: string;
+    subtitle?: string;
+    /** OVERLAY (default) or one of the split text layouts. */
+    textPlacement?: TextPlacement;
+    /** Marks an ad item: "Sponsored" chip, never loops, auto-advances. */
+    isSponsored?: boolean;
+}
+/** All knobs, mirroring the Android `OGVerticalFeedConfig` names. */
+export interface OGVerticalFeedConfig {
+    preloadAhead: number;
+    keepBehind: number;
+    loopItems: boolean;
+    contentFit: VerticalFeedContentFit;
+    showTitle: boolean;
+    showSubtitle: boolean;
+    showProgressBar: boolean;
+    showSponsoredBadge: boolean;
+    /** Hairline thickness in px. */
+    progressBarThickness: number;
+    progressBarColor: string;
+    progressBarTrackColor: string;
+    /** Inline SVG replacing the center play glyph. */
+    playIconSvg: string | null;
+    /** CSS font-family for title/subtitle/band text; null = system. */
+    textFontFamily: string | null;
+    /** px */
+    titleTextSize: number;
+    /** px */
+    subtitleTextSize: number;
+    /** CSS color of the split-text band background. */
+    textBandColor: string;
+    /** Fraction of the page height the text band owns (0.15–0.5). */
+    textBandFraction: number;
+    /** px between the band's top edge and its text. */
+    textBandTopMargin: number;
+    /** `onNearEnd` fires when this many items remain below the active one. */
+    paginationThreshold: number;
+    /** Items longer than this are skipped at prepare time; 0 = no limit. */
+    maxItemDurationSeconds: number;
+    licenseKey: string | null;
+    /** Replace the SDK's default error copy (level 2 of error handling). */
+    errorMessageProvider: ((error: OGPlayerError) => string | null) | null;
+}
+export declare const defaultVerticalFeedConfig: OGVerticalFeedConfig;
+export interface VerticalFeedPoolCallbacks {
+    onActiveItemChanged?(index: number): void;
+    onNearEnd?(remaining: number): void;
+    onItemSkipped?(index: number, reason: string): void;
+    onItemError?(index: number, error: OGPlayerError): void;
+    onAnalyticsEvent?(event: AnalyticsEvent): void;
+    /** Pool assignments changed — the UI re-parents `<video>` elements. */
+    onAssignmentsChanged?(): void;
+    /** A sponsored item ended — the UI advances to the next page. */
+    onAdvanceRequested?(fromIndex: number): void;
+}
+export declare class VerticalFeedPlayerPool {
+    private config;
+    private callbacks;
+    private items;
+    private entries;
+    private readonly capacity;
+    private activeIndexValue;
+    private released;
+    private feedMuted;
+    private skipped;
+    private licensedValue;
+    constructor(config: OGVerticalFeedConfig, callbacks: VerticalFeedPoolCallbacks);
+    get activeIndex(): number;
+    get isLicensed(): boolean | null;
+    get skippedIndices(): ReadonlySet<number>;
+    updateItems(items: OGVerticalFeedItem[]): void;
+    playerAt(index: number): OGPlayer | null;
+    setFeedMuted(muted: boolean): void;
+    /** The pager settled on `index`: promote, demote, recycle, prefill. */
+    settle(index: number): void;
+    releaseAll(): void;
+    private primaryMuted;
+    private windowOrder;
+    private entryFor;
+    private createEntry;
+    private demote;
+    private recycle;
+    private emitWatched;
+}

package/dist/index.d.ts

@@ -11,6 +11,8 @@ 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 { VerticalFeedPlayerPool, defaultVerticalFeedConfig, type OGVerticalFeedItem, type OGVerticalFeedConfig, type RailAction, type SplitAudioSource, type TextPlacement, type VerticalFeedContentFit, } from "./core/vertical-feed.js";
+export { OGVerticalFeedElement, defineOGVerticalFeedElement } from "./ui/og-vertical-feed.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). */