interface FfprobeRunResult { status: number | null; stdout: string | Buffer; stderr: string | Buffer; /** Spawn-level failure (covers both `NodeJS.ErrnoException` and * `ExecFileException`); only `code === "ENOENT"` is ever inspected. */ error?: { code?: string | number | null | undefined; }; } /** Injectable ffprobe runner. May be synchronous (tests) or async (the * default `execFile`-based runner below), so cold scans can run many probes * concurrently off the event loop. */ type FfprobeRunner = (command: string, args: string[], options?: { timeout?: number; maxBuffer?: number; }) => FfprobeRunResult | Promise; /** * One reusable answer to "what codec is this asset, and is it browser-hostile?", * built on top of `mediaMetadata.ts`'s ffprobe-backed prober so studio-server * probes each asset once instead of running a second prober. */ interface AssetCodecFacts { codecName: string; browserHostile: boolean; /** Coarse `canPlayType()` input; `null` when not applicable (safe codec) or * when no representative mime exists (ProRes: browsers never decode it, so * the runtime always proxies rather than probing `canPlayType`). */ representativeMime: string | null; /** Source carries an alpha channel (ffprobe pix_fmt). Alpha sources use a * VP8/WebM proxy so their transparency is preserved across Chromium builds. */ hasAlpha: boolean; } /** Server-root-relative URL pathname -> that asset's codec facts. */ type MediaCodecMap = Record; interface BrowserHostileCodec { /** Coarse `canPlayType()` input; `null` when no representative mime exists * (ProRes: browsers never decode it, so the runtime always proxies rather * than probing `canPlayType`). */ representativeMime: string | null; /** * Whether the server may transcode before any browser asks. True only where * no cross-platform decode exists, so some client is sure to need the * substitute; false where the first `?hf-proxy=` request can do it lazily. */ prewarm: boolean; } /** * Browser-hostile codec table v1. One exported constant so extending it is a * one-line change. `ffprobe` cannot emit exact RFC 6381 codec strings, so * these `representativeMime` values are deliberately coarse (a false * positive costs one proxy transcode, never correctness; a false negative is * rescued by the runtime's reactive zero-videoWidth swap). */ declare const BROWSER_HOSTILE_CODECS: Record; /** The pre-warm gate: true only for codecs with no cross-platform browser * decode, so some client will ask. See `BrowserHostileCodec.prewarm`. */ declare function shouldPrewarmProxy(facts: AssetCodecFacts): boolean; /** Snapshot of this process's pre-warm demand counters. */ declare function mediaProxyDemand(): { prewarmsRequested: number; proxyRequests: number; }; /** * One proxy asked for before any browser wanted it. "Requested", not * "started": a warm cache makes `resolveProxy` a no-op and this counter cannot * see that, so it is an upper bound on transcodes, not a measure of CPU. The * number it does answer exactly is the one that decides policy — a nonzero * count beside `proxyRequests: 0` means nothing ever redeemed the pre-warm. * * The per-asset line is debug-only: a composition with fifty hostile clips * would otherwise print fifty JSON lines into a clack-formatted terminal on * every re-render. The exit summary carries the same numbers unconditionally. */ declare function recordProxyPrewarm(): void; /** One proxy resolved for a browser that asked, counted on the path that calls * `resolveProxy` so it shares a unit with `prewarmsRequested`. A 304 does not * count; an unconditional Range refill still does, so read it as zero versus * nonzero. Never logged per event, only in the exit summary. */ declare function recordProxyRequest(): void; type ProxyVariant = "h264" | "vp8"; type ProxyVariantRequest = ProxyVariant | "auto"; declare const PROXY_VARIANT_CONFIG: Record; declare function isProxyVariant(value: string): value is ProxyVariant; declare function isProxyVariantRequest(value: string): value is ProxyVariantRequest; declare function proxyVariantFor(facts: AssetCodecFacts): ProxyVariant; declare function resolveProxyVariantRequest(request: ProxyVariantRequest, facts: AssetCodecFacts): ProxyVariant | null; type MediaProxyIneligibilityReason = "browser_safe_codec" | "unknown_codec"; type MediaProxyEligibility = { eligible: true; } | { eligible: false; reason: MediaProxyIneligibilityReason; }; /** Single policy gate shared by proactive scans and on-demand proxy routes. */ declare function decideMediaProxyEligibility(facts: AssetCodecFacts | null): MediaProxyEligibility; /** * Probe a single video asset. Best-effort: ffprobe missing, erroring, or * finding no video stream resolves to `null` (asset omitted by the caller), * never a throw. Async so a pool of probes runs concurrently (the default * runner is `execFile`-based). */ declare function probeAssetCodec(filePath: string, runner?: FfprobeRunner): Promise; interface CachedAssetProbe { mtimeMs: number; size: number; facts: AssetCodecFacts | null; } /** Per (path, mtime) probe cache. Construct one per project/server lifetime * and reuse it across scans; a fresh instance defeats the caching benefit. */ type MediaCodecProbeCache = Map; declare function createMediaCodecProbeCache(): MediaCodecProbeCache; /** Structurally compatible with `packages/lint/src/hevcPreviewLint.ts`'s * (unexported) `HtmlSourceLike`. */ interface HtmlSourceLike { html: string; compSrcPath?: string; } interface ScanProjectMediaCodecMapOptions { /** Persisted across calls by the caller for the mtime-cache benefit; * defaults to a shared module-level cache when omitted. */ cache?: MediaCodecProbeCache; runner?: FfprobeRunner; } /** * Scans a project's composition HTML for local `