Files
orca/src/shared/plugins/media/plugin-theme-video-rules.ts
T
Neil b0dd73e7aa feat(plugins): play a looping video behind app themes (#39450)
App themes may set background.videoPath: a muted, looping MP4 or WebM (H.264
recommended, VP9 or AV1; one video track, no audio; <= 60 s, 8 MB, 2.3 MP)
played over the required static background.path. Main checks it from container
headers without decoding and serves it on the orca-plugin-image slot
theme-<i>-video; images stay static-only. The renderer reveals it on its first
frame, keeps the still on any failure or a decoded size past the limits, plays
it only while main reports the window focused, shown and not minimized and no
dialog is open, and omits it under prefers-reduced-motion.

Animated WebP was measured and declined: software-decoded every frame, it cost
11-23 points of CPU vs 3-10 for the same loop as video.

Implements #38363 proposed by @dohaidang.
2026-11-07 03:32:14 -08:00

50 lines
2.3 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type { PluginVideoCodec, PluginVideoInfo } from './plugin-video-format'
/** Limits for an app theme's background video. Why video, not animated images: an animated WebP
* is decoded in software every frame and cost two to four times the CPU of the same loop as
* video. Why these codecs: Chromium can decode them everywhere, in software if need be; HEVC has
* no software decoder, so it fails on machines without one in hardware. */
export const PLUGIN_THEME_VIDEO_RULE = {
codecs: ['h264', 'vp9', 'av1'] satisfies readonly PluginVideoCodec[],
// Why: a 30-second 960×540 loop is 1.5 to 2.6 MB; the cap leaves room for longer or sharper loops.
maxBytes: 8 * 1024 * 1024,
maxDurationMs: 60_000,
minWidth: 640,
minHeight: 360,
// Why: bounds each frame's decode and upload; it is stretched to cover the window anyway.
maxPixels: 1920 * 1200
} as const
const CODEC_NAMES: Record<PluginVideoCodec, string> = {
h264: 'H.264',
hevc: 'HEVC',
vp8: 'VP8',
vp9: 'VP9',
av1: 'AV1'
}
const ALLOWED_CODECS: readonly PluginVideoCodec[] = PLUGIN_THEME_VIDEO_RULE.codecs
/** Null when a video fits the theme background rules, else why not. */
export function pluginThemeVideoRuleError(info: PluginVideoInfo, bytes: number): string | null {
const rule = PLUGIN_THEME_VIDEO_RULE
if (!ALLOWED_CODECS.includes(info.codec)) {
return `video codec must be H.264 (recommended), VP9 or AV1, not ${CODEC_NAMES[info.codec]}`
}
if (bytes > rule.maxBytes) {
return `video must be at most ${rule.maxBytes / 1024 / 1024} MB`
}
if (info.durationMs > rule.maxDurationMs) {
return `video must be at most ${rule.maxDurationMs / 1000} seconds`
}
if (info.width < rule.minWidth || info.height < rule.minHeight) {
return `video must be at least ${rule.minWidth}×${rule.minHeight}`
}
if (info.width * info.height > rule.maxPixels) {
return `video must be at most ${rule.maxPixels.toLocaleString('en-US')} pixels`
}
return null
}
export const PLUGIN_THEME_VIDEO_RULE_TEXT = `H.264 MP4 (recommended: decoded in hardware everywhere) or VP9 or AV1 WebM; at least ${PLUGIN_THEME_VIDEO_RULE.minWidth}×${PLUGIN_THEME_VIDEO_RULE.minHeight}, at most ${PLUGIN_THEME_VIDEO_RULE.maxPixels.toLocaleString('en-US')} pixels, ${PLUGIN_THEME_VIDEO_RULE.maxDurationMs / 1000} seconds and ${PLUGIN_THEME_VIDEO_RULE.maxBytes / 1024 / 1024} MB. No audio track.`