Files
hyperframes/packages/core/src/previewProxyBox.ts
T
Miguel Ángel 2f0ade1815 fix(core): at full quality a 4K clip plays a copy at the size the preview shows it (#7723)
* fix(core): at full quality a 4K clip plays a copy at the size the preview shows it

* fix(core): names carry the copy rule, not comments

* fix(core): a clip whose copy fails is left held as it was, so its decoder is still freed when idle

* fix(core): the copy hold lives with the copy code, keeping core inside its size budget
2026-11-14 08:09:33 +00:00

86 lines
3.0 KiB
TypeScript

/** Query parameter carrying the largest box, in device pixels, a preview shows a proxied video at. */
export const PREVIEW_PROXY_BOX_PARAM = "hf-proxy-box";
export const PREVIEW_PROXY_LIGHT_PARAM = "hf-proxy-light";
export const PREVIEW_PROXY_RETRY_PARAM = "hf-proxy-retry";
export const PREVIEW_PROXY_STILL_PARAM = "hf-proxy-still";
export const PREVIEW_PROXY_PROGRESS_HEADER = "X-HF-Proxy-Progress";
export const PREVIEW_PROXY_PRIORITY_HEADER = "X-HF-Proxy-Priority";
export type PreviewProxyBox = { width: number; height: number };
// 256 * 2^(k/4), even: nearby boxes share one cached copy, and a rung overshoots by at most ~19%.
const RUNGS = [
256, 304, 362, 430, 512, 608, 724, 862, 1024, 1218, 1448, 1722, 2048, 2436, 2896, 3444, 4096,
4870, 5792, 6888, 8192,
];
function rungAtLeast(pixels: number): number | null {
if (!(pixels > 0)) return null;
return RUNGS.find((rung) => rung >= pixels) ?? null;
}
/** Rounds a shown box up to the size ladder; null when it is empty or larger than any rung. */
export function quantizePreviewProxyBox(width: number, height: number): PreviewProxyBox | null {
const w = rungAtLeast(width);
const h = rungAtLeast(height);
return w && h ? { width: w, height: h } : null;
}
export function formatPreviewProxyBox(box: PreviewProxyBox): string {
return `${box.width}x${box.height}`;
}
/** Accepts only ladder rungs, so a client cannot make one cached copy per pixel. */
export function parsePreviewProxyBox(raw: string): PreviewProxyBox | null {
const match = /^(\d{3,4})x(\d{3,4})$/.exec(raw);
if (!match) return null;
const width = Number(match[1]);
const height = Number(match[2]);
return RUNGS.includes(width) && RUNGS.includes(height) ? { width, height } : null;
}
export const PREVIEW_QUALITY_LEVELS = [1, 0.5, 0.25, 0.125] as const;
export type PreviewQuality = (typeof PREVIEW_QUALITY_LEVELS)[number];
export function isPreviewQuality(value: unknown): value is PreviewQuality {
return PREVIEW_QUALITY_LEVELS.some((level) => level === value);
}
export type PreviewSourceFacts = {
width: number;
height: number;
bitDepth: number;
bitrate: number;
codec?: string;
frameRate?: number;
variableFrameRate?: boolean;
};
export const HEAVY_PIXEL_SHARE = 0.5;
export const HEAVY_BITRATE = 40_000_000;
export function scalePreviewProxyBox(box: PreviewProxyBox, level: PreviewQuality): PreviewProxyBox {
return quantizePreviewProxyBox(box.width * level, box.height * level) ?? box;
}
export function isOversizedForPreview(facts: PreviewSourceFacts, box: PreviewProxyBox): boolean {
return box.width * box.height <= HEAVY_PIXEL_SHARE * facts.width * facts.height;
}
export function isHeavyForPreview(facts: PreviewSourceFacts, copyBox: PreviewProxyBox): boolean {
return (
isOversizedForPreview(facts, copyBox) || facts.bitDepth > 8 || facts.bitrate >= HEAVY_BITRATE
);
}
export function wantsLighterCopy(
facts: PreviewSourceFacts,
box: PreviewProxyBox,
level: PreviewQuality,
): boolean {
return level < 1 ? isHeavyForPreview(facts, box) : isOversizedForPreview(facts, box);
}