API Reference

interface PlayerOpts {
  /** Key server URL including the /keys path (e.g., "https://your-worker.workers.dev/keys") */
  keyServerUrl: string

  /** Returns a Bearer token for key server auth (called per key request) */
  keyServerAuth?: () => Promise<string>

  /** Passthrough config to hls.js (loader and fLoader are reserved) */
  hlsConfig?: Record<string, unknown>

  /** Custom key URI parser. Return null to use default parsing. */
  parseKeyUri?: (uri: string) => { contentId: string; epoch?: number } | null

  /** Lease configuration for opt-in key revocation */
  lease?: {
    leaseEndpoint: string
    requestedTtlMs?: number      // default: 300_000 (5 min)
    renewalFraction?: number     // default: 0.75
    minRenewalBufferMs?: number  // default: 30_000 ms
  }
}

interface BlindcastPlayer {
  /** Load and play an HLS manifest */
  load(manifestUrl: string): void

  /** Destroy the player and release all resources */
  destroy(): void

  /** Subscribe to a player event. Returns an unsubscribe function. */
  on<E extends PlayerEvent>(event: E, handler: PlayerEventMap[E]): () => void

  /** Get a snapshot of current playback metrics */
  getMetrics(): PlaybackMetrics

  /** The underlying video element */
  readonly videoElement: HTMLVideoElement
}

interface PlaybackMetrics {
  timeToFirstFrame: number   // ms from load() to first frame
  avgDecryptTime: number     // ms per segment decryption
  avgFragLoadTime: number    // ms per fragment download
  avgKeyFetchTime: number    // ms per key server request
  keyFetchCount: number      // total key requests
  qualitySwitches: number    // ABR level changes
  fragmentsLoaded: number    // total segments loaded
  stallCount: number         // buffer stall events
}