avbridge 1.0.0

package/dist/player-BBwbCkdL.d.ts

@@ -0,0 +1,365 @@
+/**
+ * Core types shared across avbridge modules.
+ *
+ * The four main concepts:
+ * - {@link MediaInput} — what the user gives us (File / Blob / URL / bytes).
+ * - {@link MediaContext} — what we learned about it from probing.
+ * - {@link Classification} — which playback strategy we picked.
+ * - {@link PlaybackSession} — the running playback, returned by a strategy.
+ */
+/**
+ * Anything we accept as a media source. We do not accept arbitrary
+ * `ReadableStream`s in v1 because we need random access for seeking.
+ */
+type MediaInput = File | Blob | string | URL | ArrayBuffer | Uint8Array;
+/** Container format families we know about. */
+type ContainerKind = "mp4" | "mov" | "mkv" | "webm" | "avi" | "asf" | "flv" | "ogg" | "wav" | "mp3" | "flac" | "adts" | "mpegts" | "unknown";
+/** Video codec families. Strings, not enums, so plugins can extend. */
+type VideoCodec = "h264" | "h265" | "vp8" | "vp9" | "av1" | "mpeg4" | "wmv3" | "vc1" | "rv40" | "mpeg2" | "mpeg1" | "theora" | (string & {});
+/** Audio codec families. */
+type AudioCodec = "aac" | "mp3" | "opus" | "vorbis" | "flac" | "pcm" | "ac3" | "eac3" | "wmav2" | "wmapro" | "alac" | (string & {});
+interface VideoTrackInfo {
+    id: number;
+    codec: VideoCodec;
+    /** Codec-private profile string when known (e.g. "High", "Main 10"). */
+    profile?: string;
+    level?: number;
+    width: number;
+    height: number;
+    /** Pixel format string in ffmpeg style (e.g. "yuv420p", "yuv420p10le"). */
+    pixelFormat?: string;
+    /** Frames per second, when known. */
+    fps?: number;
+    bitDepth?: number;
+    /** RFC 6381 codec string for `MediaSource.isTypeSupported`, when computable. */
+    codecString?: string;
+}
+interface AudioTrackInfo {
+    id: number;
+    codec: AudioCodec;
+    channels: number;
+    sampleRate: number;
+    language?: string;
+    codecString?: string;
+}
+interface SubtitleTrackInfo {
+    id: number;
+    /** "vtt" | "srt" | "ass" | "pgs" | "embedded" */
+    format: string;
+    language?: string;
+    /** Set if this is a sidecar file rather than embedded in the container. */
+    sidecarUrl?: string;
+}
+/**
+ * Everything the probe layer learned about a source.
+ * This is the input to the classification engine.
+ */
+interface MediaContext {
+    source: MediaInput;
+    /** Stable display name for diagnostics, if we have one. */
+    name?: string;
+    byteLength?: number;
+    container: ContainerKind;
+    videoTracks: VideoTrackInfo[];
+    audioTracks: AudioTrackInfo[];
+    subtitleTracks: SubtitleTrackInfo[];
+    /** Which probe backend produced this context, for diagnostics. */
+    probedBy: "mediabunny" | "libav" | "sniff";
+    /** Total duration in seconds, if known. */
+    duration?: number;
+}
+/**
+ * The four playback strategies, ordered from lightest to heaviest:
+ * - `"native"` — direct `<video>` playback (zero overhead)
+ * - `"remux"` — repackage to fragmented MP4 via MSE (preserves hardware decode)
+ * - `"hybrid"` — libav.js demux + WebCodecs hardware decode (for AVI/ASF/FLV with modern codecs)
+ * - `"fallback"` — full WASM software decode via libav.js (universal, CPU-intensive)
+ */
+type StrategyName = "native" | "remux" | "hybrid" | "fallback";
+/**
+ * Classification outcome from the rules engine. Determines which strategy to use:
+ * - `NATIVE` — browser plays this directly
+ * - `REMUX_CANDIDATE` — codecs are native, container needs repackaging
+ * - `HYBRID_CANDIDATE` — container needs libav demux, codecs are hardware-decodable
+ * - `FALLBACK_REQUIRED` — codec has no browser decoder, WASM decode needed
+ * - `RISKY_NATIVE` — might work natively but may stall (e.g. Hi10P, 4K120)
+ */
+type StrategyClass = "NATIVE" | "REMUX_CANDIDATE" | "HYBRID_CANDIDATE" | "FALLBACK_REQUIRED" | "RISKY_NATIVE";
+interface Classification {
+    class: StrategyClass;
+    strategy: StrategyName;
+    reason: string;
+    /**
+     * Ordered list of strategies to try if the primary fails or stalls.
+     * The player pops from the front on each escalation.
+     */
+    fallbackChain?: StrategyName[];
+}
+/**
+ * A live playback session created by a strategy. The {@link UnifiedPlayer}
+ * delegates user-facing controls to whichever session is currently active.
+ */
+interface PlaybackSession {
+    readonly strategy: StrategyName;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): Promise<void>;
+    setAudioTrack(id: number): Promise<void>;
+    setSubtitleTrack(id: number | null): Promise<void>;
+    /** Tear down everything: revoke object URLs, close decoders, etc. */
+    destroy(): Promise<void>;
+    /** Strategy-specific runtime stats merged into Diagnostics. */
+    getRuntimeStats(): Record<string, unknown>;
+    /** Current playback position in seconds. Used to capture position before strategy switch. */
+    getCurrentTime(): number;
+    /** Register a callback for unrecoverable errors that should trigger escalation. */
+    onFatalError?(handler: (reason: string) => void): void;
+}
+interface DiagnosticsSnapshot {
+    container: ContainerKind | "unknown";
+    videoCodec?: VideoCodec;
+    audioCodec?: AudioCodec;
+    width?: number;
+    height?: number;
+    fps?: number;
+    duration?: number;
+    strategy: StrategyName | "pending";
+    strategyClass: StrategyClass | "pending";
+    reason: string;
+    probedBy?: "mediabunny" | "libav" | "sniff";
+    /**
+     * Where the source is coming from. `"blob"` means File / Blob /
+     * ArrayBuffer / Uint8Array (in-memory). `"url"` means an HTTP/HTTPS URL
+     * being streamed via Range requests.
+     */
+    sourceType?: "blob" | "url";
+    /**
+     * Transport used to read the source. `"memory"` for in-memory blobs;
+     * `"http-range"` for URL sources streamed via HTTP Range requests.
+     */
+    transport?: "memory" | "http-range";
+    /**
+     * For URL sources, true if the server supports HTTP Range requests
+     * (the only mode we accept — see `attachLibavHttpReader`). Always true
+     * when `transport === "http-range"` because we fail fast otherwise.
+     */
+    rangeSupported?: boolean;
+    runtime?: Record<string, unknown>;
+    strategyHistory?: Array<{
+        strategy: StrategyName;
+        reason: string;
+        at: number;
+    }>;
+}
+/** §8.2 plugin interface, kept structurally identical to the design doc. */
+interface Plugin {
+    name: string;
+    canHandle(context: MediaContext): boolean;
+    /** Returns a session if it claims the context, otherwise throws. */
+    execute(context: MediaContext, target: HTMLVideoElement): Promise<PlaybackSession>;
+}
+/** Player creation options. */
+interface CreatePlayerOptions {
+    source: MediaInput;
+    target: HTMLVideoElement;
+    /**
+     * Optional explicit subtitle list. The player otherwise tries to discover
+     * sidecar files via the FileSystemDirectoryHandle (when supplied), or pulls
+     * embedded subtitle tracks if the container exposes them.
+     */
+    subtitles?: Array<{
+        url: string;
+        language?: string;
+        format?: "vtt" | "srt";
+    }>;
+    /**
+     * Optional directory handle for sidecar discovery. When the source is a
+     * `File` selected from this directory, sibling `*.srt`/`*.vtt` files are
+     * picked up automatically.
+     */
+    directory?: FileSystemDirectoryHandle;
+    /**
+     * Override the strategy decision. Useful for diagnostics and tests.
+     */
+    forceStrategy?: StrategyName;
+    /** Inject extra plugins; they take priority over built-ins. */
+    plugins?: Plugin[];
+    /**
+     * When true (default), the player automatically escalates to the next
+     * strategy in the fallback chain on failure or stall.
+     */
+    autoEscalate?: boolean;
+}
+/** Events emitted by {@link UnifiedPlayer}. Strongly typed. */
+interface PlayerEventMap {
+    strategy: {
+        strategy: StrategyName;
+        reason: string;
+    };
+    strategychange: {
+        from: StrategyName;
+        to: StrategyName;
+        reason: string;
+        currentTime: number;
+    };
+    tracks: {
+        video: VideoTrackInfo[];
+        audio: AudioTrackInfo[];
+        subtitle: SubtitleTrackInfo[];
+    };
+    error: Error;
+    timeupdate: {
+        currentTime: number;
+    };
+    ended: void;
+    ready: void;
+}
+type PlayerEventName = keyof PlayerEventMap;
+/** Generic listener type re-exported for player.on overloads. */
+type Listener<T> = (payload: T) => void;
+/** Target output format for conversion functions. */
+type OutputFormat = "mp4" | "webm" | "mkv";
+/** Options for standalone conversion functions ({@link remux}, transcode). */
+interface ConvertOptions {
+    /** Target container format. Default: `"mp4"`. */
+    outputFormat?: OutputFormat;
+    /** AbortSignal to cancel the operation. */
+    signal?: AbortSignal;
+    /** Called periodically with progress information. */
+    onProgress?: (info: ProgressInfo) => void;
+    /** When true, reject on any uncertain codec/container combo. Default: `false` (best-effort). */
+    strict?: boolean;
+}
+/** Progress information passed to {@link ConvertOptions.onProgress}. */
+interface ProgressInfo {
+    /** Estimated completion percentage, 0–100. */
+    percent: number;
+    /** Total bytes written to the output so far. */
+    bytesWritten: number;
+}
+/** Quality preset for transcode. */
+type TranscodeQuality = "low" | "medium" | "high" | "very-high";
+/** Modern video codecs supported as transcode targets. */
+type OutputVideoCodec = "h264" | "h265" | "vp9" | "av1";
+/** Modern audio codecs supported as transcode targets. */
+type OutputAudioCodec = "aac" | "opus" | "flac";
+/**
+ * Hardware acceleration hint for WebCodecs encoders.
+ * - `"no-preference"` (default) — let the browser pick
+ * - `"prefer-hardware"` — faster, may produce slightly lower quality at low bitrates
+ * - `"prefer-software"` — better quality at low bitrates, slower; recommended for archival
+ */
+type HardwareAccelerationHint = "no-preference" | "prefer-hardware" | "prefer-software";
+/** Options for {@link transcode}. Extends {@link ConvertOptions} with codec/quality. */
+interface TranscodeOptions extends ConvertOptions {
+    /** Target video codec. Default: `"h264"` for mp4/mkv, `"vp9"` for webm. */
+    videoCodec?: OutputVideoCodec;
+    /** Target audio codec. Default: `"aac"` for mp4/mkv, `"opus"` for webm. */
+    audioCodec?: OutputAudioCodec;
+    /** Quality preset. Default: `"medium"`. Maps to mediabunny `Quality` levels. */
+    quality?: TranscodeQuality;
+    /** Explicit video bitrate in bits per second. Overrides `quality`. */
+    videoBitrate?: number;
+    /** Explicit audio bitrate in bits per second. Overrides `quality`. */
+    audioBitrate?: number;
+    /** Target output width in pixels. Height is auto-deduced if not set. */
+    width?: number;
+    /** Target output height in pixels. Width is auto-deduced if not set. */
+    height?: number;
+    /** Target output frame rate. */
+    frameRate?: number;
+    /** Drop the video track entirely (audio-only output). */
+    dropVideo?: boolean;
+    /** Drop the audio track entirely (silent output). */
+    dropAudio?: boolean;
+    /**
+     * Hardware acceleration hint for the WebCodecs video encoder. Default: `"no-preference"`.
+     * Set to `"prefer-software"` for archival-quality encodes at low bitrates;
+     * `"prefer-hardware"` for fast batch transcoding where speed matters more than the last
+     * few percent of quality.
+     */
+    hardwareAcceleration?: HardwareAccelerationHint;
+}
+/** Result of a standalone conversion ({@link remux} or transcode). */
+interface ConvertResult {
+    /** The converted file as a Blob, ready for download or further processing. */
+    blob: Blob;
+    /** Full MIME type string, e.g. `"video/mp4"`. */
+    mimeType: string;
+    /** Container format name: `"mp4"`, `"webm"`, or `"mkv"`. */
+    container: OutputFormat;
+    /** Video codec in the output, if present. */
+    videoCodec?: string;
+    /** Audio codec in the output, if present. */
+    audioCodec?: string;
+    /** Duration in seconds, if known. */
+    duration?: number;
+    /** Suggested filename for download. */
+    filename?: string;
+    /**
+     * Diagnostic notes about how the conversion ran. Currently records
+     * automatic retry of WebCodecs encoder failures (a known headless
+     * Chromium first-call init bug for the H.264 encoder).
+     */
+    notes?: string[];
+}
+
+declare class UnifiedPlayer {
+    private readonly options;
+    private readonly registry;
+    private emitter;
+    private session;
+    private diag;
+    private timeupdateInterval;
+    private mediaContext;
+    private classification;
+    private stallTimer;
+    private lastProgressTime;
+    private lastProgressPosition;
+    private errorListener;
+    private switchingPromise;
+    /**
+     * @internal Use {@link createPlayer} or {@link UnifiedPlayer.create} instead.
+     */
+    private constructor();
+    static create(options: CreatePlayerOptions): Promise<UnifiedPlayer>;
+    private bootstrap;
+    /**
+     * Try to start a session with the given strategy. On failure, walk the
+     * fallback chain. Throws only if all strategies are exhausted.
+     */
+    private startSession;
+    private escalate;
+    private doEscalate;
+    private attachSupervisor;
+    private clearSupervisor;
+    /** Manually switch to a different playback strategy. Preserves current position and play/pause state. Concurrent calls are serialized. */
+    setStrategy(strategy: StrategyName, reason?: string): Promise<void>;
+    private doSetStrategy;
+    private startTimeupdateLoop;
+    /** Subscribe to a player event. Returns an unsubscribe function. Sticky events (strategy, ready, tracks) replay for late subscribers. */
+    on<K extends PlayerEventName>(event: K, fn: Listener<PlayerEventMap[K]>): () => void;
+    /** Remove a previously registered event listener. */
+    off<K extends PlayerEventName>(event: K, fn: Listener<PlayerEventMap[K]>): void;
+    /** Begin or resume playback. Throws if the player is not ready. */
+    play(): Promise<void>;
+    /** Pause playback. No-op if the player is not ready or already paused. */
+    pause(): void;
+    /** Seek to the given time in seconds. Throws if the player is not ready. */
+    seek(time: number): Promise<void>;
+    /** Switch the active audio track by track ID. Throws if the player is not ready. */
+    setAudioTrack(id: number): Promise<void>;
+    /** Switch the active subtitle track by track ID, or pass `null` to disable subtitles. */
+    setSubtitleTrack(id: number | null): Promise<void>;
+    /** Return a snapshot of current diagnostics: container, codecs, strategy, runtime stats, and strategy history. */
+    getDiagnostics(): DiagnosticsSnapshot;
+    /** Return the total duration in seconds, or `NaN` if unknown. */
+    getDuration(): number;
+    /** Return the current playback position in seconds. */
+    getCurrentTime(): number;
+    /** Tear down the player: stop timers, destroy the active session, remove all event listeners. The player is unusable after this call. */
+    destroy(): Promise<void>;
+}
+declare function createPlayer(options: CreatePlayerOptions): Promise<UnifiedPlayer>;
+
+export { type AudioCodec as A, type Classification as C, type DiagnosticsSnapshot as D, type HardwareAccelerationHint as H, type MediaContext as M, type OutputAudioCodec as O, type PlaybackSession as P, type StrategyClass as S, type TranscodeOptions as T, UnifiedPlayer as U, type VideoCodec as V, type MediaInput as a, type ConvertOptions as b, type ConvertResult as c, type AudioTrackInfo as d, type ContainerKind as e, type CreatePlayerOptions as f, type OutputFormat as g, type OutputVideoCodec as h, type PlayerEventMap as i, type PlayerEventName as j, type Plugin as k, type ProgressInfo as l, type StrategyName as m, type SubtitleTrackInfo as n, type TranscodeQuality as o, type VideoTrackInfo as p, createPlayer as q };

package/dist/source-SC6ZEQYR.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var chunkY5FYF5KG_cjs = require('./chunk-Y5FYF5KG.cjs');
+
+
+
+Object.defineProperty(exports, "isInMemorySource", {
+  enumerable: true,
+  get: function () { return chunkY5FYF5KG_cjs.isInMemorySource; }
+});
+Object.defineProperty(exports, "normalizeSource", {
+  enumerable: true,
+  get: function () { return chunkY5FYF5KG_cjs.normalizeSource; }
+});
+Object.defineProperty(exports, "sniffContainer", {
+  enumerable: true,
+  get: function () { return chunkY5FYF5KG_cjs.sniffContainer; }
+});
+Object.defineProperty(exports, "sniffContainerFromBytes", {
+  enumerable: true,
+  get: function () { return chunkY5FYF5KG_cjs.sniffContainerFromBytes; }
+});
+Object.defineProperty(exports, "sniffNormalizedSource", {
+  enumerable: true,
+  get: function () { return chunkY5FYF5KG_cjs.sniffNormalizedSource; }
+});
+//# sourceMappingURL=source-SC6ZEQYR.cjs.map
+//# sourceMappingURL=source-SC6ZEQYR.cjs.map

package/dist/source-SC6ZEQYR.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"source-SC6ZEQYR.cjs"}

package/dist/source-ZFS4H7J3.js

@@ -0,0 +1,3 @@
+export { isInMemorySource, normalizeSource, sniffContainer, sniffContainerFromBytes, sniffNormalizedSource } from './chunk-PQTZS7OA.js';
+//# sourceMappingURL=source-ZFS4H7J3.js.map
+//# sourceMappingURL=source-ZFS4H7J3.js.map

package/dist/source-ZFS4H7J3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"source-ZFS4H7J3.js"}

package/dist/variant-routing-GOHB2RZN.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkNZU7W256_cjs = require('./chunk-NZU7W256.cjs');
+
+
+
+Object.defineProperty(exports, "pickLibavVariant", {
+  enumerable: true,
+  get: function () { return chunkNZU7W256_cjs.pickLibavVariant; }
+});
+//# sourceMappingURL=variant-routing-GOHB2RZN.cjs.map
+//# sourceMappingURL=variant-routing-GOHB2RZN.cjs.map

package/dist/variant-routing-GOHB2RZN.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"variant-routing-GOHB2RZN.cjs"}

package/dist/variant-routing-JOBWXYKD.js

@@ -0,0 +1,3 @@
+export { pickLibavVariant } from './chunk-J5MCMN3S.js';
+//# sourceMappingURL=variant-routing-JOBWXYKD.js.map
+//# sourceMappingURL=variant-routing-JOBWXYKD.js.map

package/dist/variant-routing-JOBWXYKD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"variant-routing-JOBWXYKD.js"}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "avbridge",
+  "version": "1.0.0",
+  "description": "Play and convert arbitrary video files in the browser. Native, remux, hybrid, fallback, and transcode — one API.",
+  "license": "MIT",
+  "author": "Keishi Hattori",
+  "homepage": "https://github.com/keishi/avbridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keishi/avbridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/keishi/avbridge/issues"
+  },
+  "keywords": [
+    "media-player",
+    "video",
+    "audio",
+    "browser",
+    "transcode",
+    "remux",
+    "webcodecs",
+    "mse",
+    "mediabunny",
+    "avi",
+    "mkv",
+    "wmv",
+    "divx",
+    "mpegts",
+    "libav",
+    "wasm",
+    "web-component"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/element.js",
+    "./dist/element.cjs"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./element": {
+      "types": "./dist/element.d.ts",
+      "import": "./dist/element.js",
+      "require": "./dist/element.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "predemo": "node scripts/copy-libav.mjs",
+    "demo": "vite",
+    "predemo:build": "node scripts/copy-libav.mjs",
+    "demo:build": "vite build",
+    "build:libav": "./scripts/build-libav.sh",
+    "test:playback": "node scripts/playback-test.mjs",
+    "test:convert": "node scripts/convert-test.mjs",
+    "test:element": "node scripts/element-test.mjs",
+    "test:url-streaming": "node scripts/url-streaming-test.mjs",
+    "fixtures": "node scripts/generate-fixtures.mjs",
+    "audit:bundle": "node scripts/bundle-audit.mjs"
+  },
+  "dependencies": {
+    "mediabunny": "^1.40.1"
+  },
+  "optionalDependencies": {
+    "@libav.js/types": "^6.8.8",
+    "@libav.js/variant-webcodecs": "^6.8.8",
+    "libavjs-webcodecs-bridge": "^0.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "jsdom": "^24.0.0",
+    "puppeteer": "^24.40.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vitest": "^1.5.0"
+  }
+}

package/src/classify/index.ts

@@ -0,0 +1 @@
+export { classifyContext as classify } from "./rules.js";