@mantequilla-soft/3speak-player 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,400 @@
+/** Video source with CDN fallback chain */
+interface VideoSource {
+    /** Primary HLS URL (.m3u8) */
+    url: string;
+    /** Fallback HLS URLs in priority order */
+    fallbacks?: string[];
+    /** Poster/thumbnail image URL */
+    poster?: string;
+}
+/** Video metadata returned by the 3Speak API */
+interface VideoMetadata {
+    owner: string;
+    permlink: string;
+    title: string;
+    status: string;
+    videoUrl: string;
+    videoUrlFallback1: string | null;
+    videoUrlFallback2: string | null;
+    videoUrlFallback3: string | null;
+    thumbnail: string | null;
+    duration: number;
+    views: number;
+    short: boolean;
+    isPlaceholder: boolean;
+}
+/** Player state snapshot */
+interface PlayerState {
+    currentTime: number;
+    duration: number;
+    paused: boolean;
+    muted: boolean;
+    volume: number;
+    ready: boolean;
+    loading: boolean;
+    isVertical: boolean | null;
+    videoWidth: number;
+    videoHeight: number;
+    /** Buffered progress (0-1) */
+    buffered: number;
+    /** Picture-in-Picture active */
+    pip: boolean;
+    /** Fullscreen active */
+    fullscreen: boolean;
+    /** Audio-only mode active */
+    audioOnly: boolean;
+}
+/** HLS quality level (hls.js only) */
+interface QualityLevel {
+    index: number;
+    height: number;
+    width: number;
+    bitrate: number;
+}
+/** Events emitted by the player */
+interface PlayerEvents {
+    ready: (state: {
+        isVertical: boolean;
+        width: number;
+        height: number;
+    }) => void;
+    play: () => void;
+    pause: () => void;
+    ended: () => void;
+    timeupdate: (state: {
+        currentTime: number;
+        duration: number;
+        paused: boolean;
+    }) => void;
+    error: (error: {
+        message: string;
+        code?: number;
+        fatal: boolean;
+    }) => void;
+    /** Fired when falling back to an alternate CDN source */
+    fallback: (info: {
+        url: string;
+        index: number;
+    }) => void;
+    /** Fired when video dimensions are known */
+    resize: (info: {
+        width: number;
+        height: number;
+        isVertical: boolean;
+    }) => void;
+    /** Loading state changed */
+    loading: (isLoading: boolean) => void;
+    /** Buffered progress changed (0-1) */
+    buffered: (progress: number) => void;
+    /** Picture-in-Picture state changed */
+    pip: (active: boolean) => void;
+    /** Fullscreen state changed */
+    fullscreen: (active: boolean) => void;
+    /** Quality level changed (hls.js only) */
+    qualitychange: (level: QualityLevel) => void;
+    /** Video element visibility changed (IntersectionObserver) */
+    visibility: (visible: boolean) => void;
+    /** Playback resumed from saved position */
+    resume: (info: {
+        time: number;
+        ref: string;
+    }) => void;
+}
+/** Configuration for creating a player instance */
+interface PlayerConfig {
+    /** 3Speak player API base URL (default: https://play.3speak.tv) */
+    apiBase?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Start muted (required for autoplay on most browsers) */
+    muted?: boolean;
+    /** Loop playback */
+    loop?: boolean;
+    /** Show poster/thumbnail image during loading (default: true) */
+    poster?: boolean;
+    /** hls.js configuration overrides */
+    hlsConfig?: Record<string, unknown>;
+    /** Start in audio-only mode */
+    audioOnly?: boolean;
+    /** Auto-pause when video scrolls out of viewport (IntersectionObserver) */
+    autopause?: boolean;
+    /** Resume playback from last position (uses localStorage) */
+    resume?: boolean;
+}
+/** Platform detection results */
+interface PlatformInfo {
+    isIOS: boolean;
+    isSafari: boolean;
+    supportsNativeHLS: boolean;
+    supportsMSE: boolean;
+    supportsHlsJs: boolean;
+}
+/** Type-safe event emitter */
+type EventHandler<T extends keyof PlayerEvents> = PlayerEvents[T];
+type EventUnsubscribe = () => void;
+
+/**
+ * 3Speak video API client.
+ * Fetches video metadata and HLS URLs from the snapie player API.
+ */
+declare class ThreeSpeakApi {
+    private apiBase;
+    private debug;
+    constructor(apiBase?: string, debug?: boolean);
+    private log;
+    /**
+     * Fetch full video metadata from the embed API.
+     * @param author - Hive account name
+     * @param permlink - 3Speak video permlink
+     */
+    fetchVideoMetadata(author: string, permlink: string): Promise<VideoMetadata>;
+    /**
+     * Fetch just the HLS source URLs (convenience wrapper).
+     * Returns a VideoSource ready to pass to the player.
+     */
+    fetchSource(author: string, permlink: string): Promise<VideoSource>;
+    /**
+     * Prefetch an HLS manifest AND its first video segment to warm CDN + browser cache.
+     * This means when hls.js actually starts playback, the first segment is already cached.
+     */
+    prefetchManifest(hlsUrl: string): Promise<void>;
+    /**
+     * Parse a media playlist and prefetch its first .ts/.m4s segment.
+     */
+    private prefetchFirstSegment;
+    /**
+     * Increment view count for a video.
+     */
+    recordView(owner: string, permlink: string, type?: string): Promise<void>;
+}
+/**
+ * Convert API metadata to a VideoSource with fallback chain.
+ */
+declare function metadataToSource(meta: VideoMetadata): VideoSource;
+
+/**
+ * 3Speak HLS Video Player.
+ *
+ * Framework-agnostic — works with any <video> element.
+ * Handles HLS playback via native Safari HLS or hls.js (Chrome/Firefox/Edge).
+ *
+ * @example
+ * ```js
+ * import { Player } from '@mantequilla-soft/3speak-player';
+ *
+ * const player = new Player({ muted: true, loop: true });
+ * player.attach(document.querySelector('video'));
+ * player.load('@author/permlink');
+ * player.on('ready', ({ isVertical }) => console.log('vertical?', isVertical));
+ * ```
+ */
+declare class Player {
+    private config;
+    private api;
+    private platform;
+    private video;
+    private hls;
+    private listeners;
+    private fallbackIndex;
+    private fallbacks;
+    private _ready;
+    private _destroyed;
+    private _audioOnly;
+    private _currentRef;
+    private _resumeSaveTimer;
+    private _observer;
+    private cleanupFns;
+    constructor(config?: PlayerConfig);
+    private log;
+    /**
+     * Subscribe to a player event.
+     * @returns Unsubscribe function
+     */
+    on<T extends keyof PlayerEvents>(event: T, handler: EventHandler<T>): EventUnsubscribe;
+    /** Unsubscribe from a player event. */
+    off<T extends keyof PlayerEvents>(event: T, handler: EventHandler<T>): void;
+    /** Subscribe to a player event, auto-unsubscribe after first call. */
+    once<T extends keyof PlayerEvents>(event: T, handler: EventHandler<T>): EventUnsubscribe;
+    private emit;
+    /**
+     * Attach the player to a <video> element.
+     * Sets required attributes (playsinline, etc.) automatically.
+     */
+    attach(element: HTMLVideoElement): this;
+    /**
+     * Detach from the current video element and clean up HLS.
+     */
+    detach(): this;
+    /**
+     * Load a video by author/permlink (fetches HLS URL from 3Speak API).
+     * @param ref - Either "author/permlink" or "@author/permlink"
+     */
+    load(ref: string): Promise<this>;
+    /**
+     * Load a video from a direct VideoSource.
+     */
+    load(source: VideoSource): Promise<this>;
+    play(): Promise<void>;
+    pause(): void;
+    togglePlay(): void;
+    seek(time: number): void;
+    /** Set muted state */
+    setMuted(muted: boolean): void;
+    /** Set volume (0-1) */
+    setVolume(volume: number): void;
+    /** Set loop mode */
+    setLoop(loop: boolean): void;
+    /** Set playback rate */
+    setPlaybackRate(rate: number): void;
+    /** Toggle Picture-in-Picture mode */
+    togglePip(): Promise<void>;
+    /** Toggle fullscreen mode */
+    toggleFullscreen(): Promise<void>;
+    /** Get available quality levels (hls.js only, empty for native HLS) */
+    getQualities(): QualityLevel[];
+    /** Set quality level (-1 for auto, hls.js only) */
+    setQuality(index: number): void;
+    /** Get current quality level index (-1 = auto, hls.js only) */
+    getCurrentQuality(): number;
+    /**
+     * Get thumbnail at a given time. Currently returns the poster image.
+     * Reserved for future sprite sheet support.
+     */
+    getThumbnailAt(_time: number): string | null;
+    /** Set audio-only mode (hides video, keeps audio playing) */
+    setAudioOnly(enabled: boolean): void;
+    /** Enable auto-pause when video scrolls out of viewport */
+    enableAutopause(): void;
+    /** Disable auto-pause on scroll out */
+    disableAutopause(): void;
+    /** Clear saved resume position for a video ref. Clears current video if no ref given. */
+    clearResumePosition(ref?: string): void;
+    /** Get current player state snapshot */
+    getState(): PlayerState;
+    /** Whether the player has loaded metadata and is ready to play */
+    get ready(): boolean;
+    /** Whether this player instance has been destroyed */
+    get destroyed(): boolean;
+    /** The underlying <video> element (if attached) */
+    get element(): HTMLVideoElement | null;
+    /** Access the 3Speak API client */
+    get apiClient(): ThreeSpeakApi;
+    /**
+     * Destroy the player and release all resources.
+     * Cannot be used after this.
+     */
+    destroy(): void;
+    private loadSource;
+    private tryFallback;
+    private destroyHls;
+    private setupAutopause;
+    private destroyAutopause;
+    private saveResumePosition;
+    private restoreResumePosition;
+    private bindVideoEvents;
+}
+
+/**
+ * Manages a pool of Player instances for feed/shorts-style UIs.
+ *
+ * Handles:
+ * - Creating/recycling players for visible videos
+ * - Pausing all except the active player
+ * - Manifest prefetching for upcoming videos on iOS
+ * - Cleaning up off-screen players
+ *
+ * @example
+ * ```js
+ * const pool = new PlayerPool({ muted: true, loop: true });
+ *
+ * // Add videos as they enter the viewport
+ * pool.add('vid-1', videoElement1, { url: 'https://...' });
+ * pool.add('vid-2', videoElement2, { url: 'https://...' });
+ *
+ * // Activate the current video (pauses all others)
+ * pool.activate('vid-1');
+ *
+ * // Remove when scrolled out of range
+ * pool.remove('vid-2');
+ *
+ * // Clean up
+ * pool.destroy();
+ * ```
+ */
+declare class PlayerPool {
+    private players;
+    private activeId;
+    private config;
+    private api;
+    private platform;
+    constructor(config?: PlayerConfig);
+    /**
+     * Add a player to the pool.
+     * @param id - Unique identifier for this video slot
+     * @param element - The <video> element to attach to
+     * @param source - Video source (optional — can call load() later)
+     */
+    add(id: string, element: HTMLVideoElement, source?: VideoSource): Player;
+    /**
+     * Add a player by 3Speak author/permlink (auto-fetches HLS URL).
+     */
+    addByRef(id: string, element: HTMLVideoElement, author: string, permlink: string): Promise<Player>;
+    /**
+     * Get a player by id.
+     */
+    get(id: string): Player | undefined;
+    /**
+     * Remove a player from the pool and destroy it.
+     */
+    remove(id: string): void;
+    /**
+     * Activate a player (play it, pause all others).
+     */
+    activate(id: string): void;
+    /** Pause all players. */
+    pauseAll(): void;
+    /** Set muted state on all players. */
+    setAllMuted(muted: boolean): void;
+    /** Set loop on all players. */
+    setAllLoop(loop: boolean): void;
+    /** Get the currently active player. */
+    getActive(): Player | undefined;
+    /** Get the active player's id. */
+    get activePlayerId(): string | null;
+    /** Number of players in the pool. */
+    get size(): number;
+    /** All player ids in the pool. */
+    get ids(): string[];
+    /**
+     * Prefetch an HLS manifest (warms CDN, ~1-5KB).
+     * Especially useful on iOS where we can't preload actual video data.
+     */
+    prefetch(hlsUrl: string): Promise<void>;
+    /**
+     * Prefetch a manifest by author/permlink.
+     */
+    prefetchByRef(author: string, permlink: string): Promise<void>;
+    /**
+     * Retain only the given ids, destroy all others.
+     * Useful for keeping a sliding window of players around the current index.
+     */
+    retainOnly(ids: Set<string> | string[]): void;
+    /**
+     * Destroy all players and the pool.
+     */
+    destroy(): void;
+}
+
+/**
+ * Detect platform capabilities for HLS playback strategy.
+ * Results are cached after first call.
+ */
+declare function detectPlatform(): PlatformInfo;
+/**
+ * Detect whether the browser allows autoplay.
+ * @param muted - Test muted autoplay (default: true). Unmuted autoplay is blocked on most browsers.
+ * @returns Promise resolving to true if autoplay is allowed.
+ */
+declare function canAutoplay(muted?: boolean): Promise<boolean>;
+
+export { type EventHandler, type EventUnsubscribe, type PlatformInfo, Player, type PlayerConfig, type PlayerEvents, PlayerPool, type PlayerState, type QualityLevel, ThreeSpeakApi, type VideoMetadata, type VideoSource, canAutoplay, detectPlatform, metadataToSource };