feat: batch video upscaling with folder upload, directory save, and result comparison (#1051)

* feat: support batch video upscaling with folder upload and directory save

- Add multi-file selection and entire folder upload (webkitdirectory)
- Support drag & drop of both files and folders via FileSystemEntry API
- Add save directory picker using File System Access API (showDirectoryPicker)
- Process videos sequentially with per-file progress and status tracking
- Add right-side result list with click-to-compare functionality
- Add per-video duration and total batch duration display
- Add retry button for failed items with error detail display
- Remove auto-play on comparison viewer load
- Fix worker error handling: handle "error" command to reject stale promises
- Fix event listener accumulation in video comparison (AbortController)
- Fix XSS risk by escaping HTML in all innerHTML injections
- Fix URL revocation timing in download to prevent large file truncation
- Extract writeToSaveDirectory and truncateName helpers to reduce duplication
- Add Usage Guide panel explaining single/multiple/folder upload options

Files changed:
  docs/upscaler/index.html  (+1110/-181)
  docs/upscaler/upscaler.js (+110)

* fix: prevent auto-play and resource consumption during upscaling

- Set preload="metadata" on preview and comparison video elements
- Explicitly pause preview video after setting src in showVideoPreview
- Remove preview video seek sync from batch processing progress callbacks
  (was causing continuous decode during upscaling, wasting GPU resources)
- Remove preview video seek sync from retry progress callback
- All videos now require manual play; no background resource usage

* fix: improve upscaled video quality with higher bitrate and codec support

- Raise base bitrate from 2.5 Mbps (25e5) to 8 Mbps (8e6) for standard and
  firefox processors, preventing quality loss when source videos have high
  bitrates (e.g. 720p @ 16.7 Mbps was producing 1440p @ 10 Mbps, smaller
  than the original file)
- Double the bitrate for mediabunny processor (X.n1 * 2) to account for the
  4x pixel increase from 2x upscaling
- Add H.264 Level 5.1 (avc1.640033) and Level 5.2 (avc1.640034) codecs to
  the fallback lists, since Level 4.0 (avc1.640028, ~24.6 Mbps) cannot
  support the higher bitrates for 1440p+ outputs
- Add latencyMode: "quality" to VideoEncoder configs for both standard and
  firefox processors, prioritizing encoding quality over latency (suitable
  for offline processing)

* feat: add video data comparison panel for original vs upscaled metrics

- Add a comparison data table below the file info bar showing 6 metrics:
  Resolution, File Size, Duration, Est. Bitrate, Pixels, Process Time
- Display per-metric change percentage with color-coded indicators:
  green (↑) for improvements, red (↓) for regressions, gray for neutral
- Estimated bitrate calculated from file size × 8 / video duration
- Table renders after both original and upscaled video metadata loads
- Auto-hide panel on reset

* fix: make video data comparison panel full-width and responsive

- Move comparison data table from inside the left column to the full-width
  area below the left/right layout, so it is no longer constrained by the
  comparison viewer column width
- Remove table-fixed colgroup and overflow-x-auto that caused horizontal
  scrolling on smaller screens
- Table now uses w-full auto-layout, displaying all 4 columns (Metric,
  Original, Upscaled, Change) without requiring horizontal scrolling

---------

Co-authored-by: rionzhao <rionzhao@tencent.com>

assets/ts/artplayer-plugin-ads.d.ts

@@ -0,0 +1,52 @@
+interface Option {
+  /**
+   * 广告源文本，支持视频链接、图片链接、HTML文本
+   */
+  source: string
+
+  /**
+   * 知名广告的类型：'video' | 'image' | 'html'
+   */
+  type: 'video' | 'image' | 'html'
+
+  /**
+   * 广告必看的时长，单位为秒
+   */
+  playDuration?: number
+
+  /**
+   * 广告总的时长，单位为秒
+   */
+  totalDuration?: number
+
+  /**
+   * 视频广告是否默认静音
+   */
+  muted?: boolean
+}
+
+interface Ads {
+  name: 'artplayerPluginAds'
+
+  /**
+   * 跳过广告
+   */
+  skip: () => void
+
+  /**
+   * 暂停广告
+   */
+  pause: () => void
+
+  /**
+   * 播放广告
+   */
+  play: () => void
+}
+
+declare const artplayerPluginAds: (option: Option) => (art: Artplayer) => Ads
+
+export default artplayerPluginAds
+
+export = artplayerPluginAds
+export as namespace artplayerPluginAds;

assets/ts/artplayer-plugin-ambilight.d.ts

@@ -0,0 +1,20 @@
+interface Option {
+  blur?: string
+  opacity?: number
+  frequency?: number
+  zIndex?: number
+  duration?: number
+}
+
+interface Result {
+  name: 'artplayerPluginAmbilight'
+  start: () => void
+  stop: () => void
+}
+
+declare const artplayerPluginAmbilight: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginAmbilight
+
+export = artplayerPluginAmbilight
+export as namespace artplayerPluginAmbilight;

assets/ts/artplayer-plugin-asr.d.ts

@@ -0,0 +1,26 @@
+interface AudioChunk {
+  pcm: ArrayBuffer
+  wav: ArrayBuffer
+}
+
+interface AsrPluginOption {
+  length?: number
+  interval?: number
+  sampleRate?: number
+  autoHideTimeout?: number
+  onAudioChunk?: (chunk: AudioChunk) => void | Promise<void>
+}
+
+interface AsrPluginInstance {
+  name: 'artplayerPluginAsr'
+  stop: () => void
+  hide: () => void
+  append: (subtitle: string) => void
+}
+
+declare function artplayerPluginAsr(option?: AsrPluginOption): (art: Artplayer) => AsrPluginInstance
+
+export default artplayerPluginAsr
+
+export = artplayerPluginAsr
+export as namespace artplayerPluginAsr;

assets/ts/artplayer-plugin-audio-track.d.ts

@@ -0,0 +1,40 @@
+interface Option {
+  /**
+   * Audio track URL
+   */
+  url: string
+
+  /**
+   * Time offset in seconds between video and audio
+   * Positive value means audio plays ahead of video
+   * Negative value means audio plays behind video
+   * @default 0
+   */
+  offset?: number
+
+  /**
+   * Synchronization threshold in seconds
+   * @default 0.3
+   */
+  sync?: number
+}
+
+interface Result {
+  name: 'artplayerPluginAudioTrack'
+  /**
+   * The audio element
+   */
+  audio: HTMLAudioElement
+
+  /**
+   * Update option
+   */
+  update: (option: Option) => void
+}
+
+declare const artplayerPluginAudioTrack: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginAudioTrack
+
+export = artplayerPluginAudioTrack
+export as namespace artplayerPluginAudioTrack;

assets/ts/artplayer-plugin-auto-thumbnail.d.ts

@@ -0,0 +1,17 @@
+interface Option {
+  url?: string
+  width?: number
+  number?: number
+  scale?: number
+}
+
+interface Result {
+  name: 'artplayerPluginAutoThumbnail'
+}
+
+declare const artplayerPluginAutoThumbnail: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginAutoThumbnail
+
+export = artplayerPluginAutoThumbnail
+export as namespace artplayerPluginAutoThumbnail;

assets/ts/artplayer-plugin-chapter.d.ts

@@ -0,0 +1,21 @@
+type Chapters = {
+  start: number
+  end: number
+  title: string
+}[]
+
+interface Option {
+  chapters?: Chapters
+}
+
+interface Result {
+  name: 'artplayerPluginChapter'
+  update: (option: Option) => void
+}
+
+declare const artplayerPluginChapter: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginChapter
+
+export = artplayerPluginChapter
+export as namespace artplayerPluginChapter;

assets/ts/artplayer-plugin-chromecast.d.ts

@@ -0,0 +1,17 @@
+interface Option {
+  url?: string
+  sdk?: string
+  icon?: string
+  mimeType?: string
+}
+
+interface Chromecast {
+  name: 'artplayerPluginChromecast'
+}
+
+declare const artplayerPluginChromecast: (option: Option) => (art: Artplayer) => Chromecast
+
+export default artplayerPluginChromecast
+
+export = artplayerPluginChromecast
+export as namespace artplayerPluginChromecast;

assets/ts/artplayer-plugin-danmuku-mask.d.ts

@@ -0,0 +1,25 @@
+interface Option {
+  solutionPath?: string
+  modelSelection?: number
+  smoothSegmentation?: boolean
+  minDetectionConfidence?: number
+  minTrackingConfidence?: number
+  selfieMode?: boolean
+  drawContour?: boolean
+  foregroundThreshold?: number
+  opacity?: number
+  maskBlurAmount?: number
+}
+
+interface Result {
+  name: 'artplayerPluginDanmukuMask'
+  start: () => Promise<void>
+  stop: () => void
+}
+
+declare const artplayerPluginDanmukuMask: (option?: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginDanmukuMask
+
+export = artplayerPluginDanmukuMask
+export as namespace artplayerPluginDanmukuMask;

assets/ts/artplayer-plugin-danmuku.d.ts

@@ -0,0 +1,259 @@
+export type Mode = 0 | 1 | 2
+export type Danmuku
+  = | Danmu[]
+    | string // URL
+    | (() => Promise<Danmu[]>)
+    | Promise<Danmu[]>
+
+export interface Slider {
+  min?: number
+  max?: number
+  steps?: {
+    name?: string
+    value?: number | string
+    show?: boolean
+  }[]
+}
+
+export interface Danmu {
+  /**
+   * 弹幕文本
+   */
+  text: string
+
+  /**
+   * 弹幕发送模式: 0: 滚动，1: 顶部，2: 底部
+   */
+  mode?: Mode
+
+  /**
+   * 弹幕颜色
+   */
+  color?: string
+
+  /**
+   * 弹幕出现的时间，单位为秒
+   */
+  time?: number
+
+  /**
+   * 弹幕是否有描边, 默认为 false
+   */
+  border?: boolean
+
+  /**
+   * 弹幕自定义样式
+   */
+  style?: Partial<CSSStyleDeclaration>
+}
+
+export interface Option {
+  /**
+   * 弹幕数据: 函数，数组，Promise，URL
+   */
+  danmuku: Danmuku
+
+  /**
+   * 弹幕持续时间，范围在[1 ~ 10]
+   */
+  speed?: number
+
+  /**
+   * 弹幕上下边距，支持像素数字和百分比
+   */
+  margin?: [number | `${number}%`, number | `${number}%`]
+
+  /**
+   * 弹幕透明度，范围在[0 ~ 1]
+   */
+  opacity?: number
+
+  /**
+   * 默认弹幕颜色，可以被单独弹幕项覆盖
+   */
+  color?: string
+
+  /**
+   * 弹幕模式: 0: 滚动，1: 顶部，2: 底部
+   */
+  mode?: Mode
+
+  /**
+   * 弹幕可见的模式
+   */
+  modes?: Mode[]
+
+  /**
+   * 弹幕字体大小，支持像素数字和百分比
+   */
+  fontSize?: number | `${number}%`
+
+  /**
+   * 弹幕是否防重叠
+   */
+  antiOverlap?: boolean
+
+  /**
+   * 是否同步播放速度
+   */
+  synchronousPlayback?: boolean
+
+  /**
+   * 弹幕发射器挂载点, 默认为播放器控制栏中部
+   */
+  mount?: HTMLDivElement | string
+
+  /**
+   * 是否开启弹幕热度图
+   */
+  heatmap?:
+    | boolean
+    | {
+      xMin?: number
+      xMax?: number
+      yMin?: number
+      yMax?: number
+      scale?: number
+      opacity?: number
+      minHeight?: number
+      sampling?: number
+      smoothing?: number
+      flattening?: number
+    }
+
+  /**
+   * 当播放器宽度小于此值时，弹幕发射器置于播放器底部
+   */
+  width?: number
+
+  /**
+   * 热力图数据
+   */
+  points?: { time: number, value: number }[]
+
+  /**
+   * 弹幕载入前的过滤器，只支持返回布尔值
+   */
+  filter?: (danmu: Danmu) => boolean
+
+  /**
+   * 弹幕发送前的过滤器，支持返回 Promise
+   */
+  beforeEmit?: (danmu: Danmu) => boolean | Promise<boolean>
+
+  /**
+   * 弹幕显示前的过滤器，支持返回 Promise
+   */
+  beforeVisible?: (danmu: Danmu) => boolean | Promise<boolean>
+
+  /**
+   * 弹幕是否可见
+   */
+  visible?: boolean
+
+  /**
+   * 是否开启弹幕发射器
+   */
+  emitter?: boolean
+
+  /**
+   * 弹幕输入框最大长度, 范围在[1 ~ 1000]
+   */
+  maxLength?: number
+
+  /**
+   * 输入框锁定时间，范围在[1 ~ 60]
+   */
+  lockTime?: number
+
+  /**
+   * 弹幕主题，只在自定义挂载时生效
+   */
+  theme?: 'light' | 'dark'
+
+  /**
+   * 不透明度配置项
+   */
+  OPACITY?: Slider
+
+  /**
+   * 弹幕速度配置项
+   */
+  SPEED?: Slider
+
+  /**
+   * 显示区域配置项
+   */
+  MARGIN?: Slider
+
+  /**
+   * 弹幕字号配置项
+   */
+  FONT_SIZE?: Slider
+
+  /**
+   * 颜色列表配置项
+   */
+  COLOR?: string[]
+}
+
+export interface Result {
+  name: 'artplayerPluginDanmuku'
+
+  /**
+   * 发送一条实时弹幕
+   */
+  emit: (danmu: Danmu) => Result
+
+  /**
+   * 重载弹幕源，或者切换新弹幕
+   */
+  load: (danmuku?: Danmuku) => Promise<Result>
+
+  /**
+   * 实时改变弹幕配置
+   */
+  config: (option: Option) => Result
+
+  /**
+   * 隐藏弹幕层
+   */
+  hide: () => Result
+
+  /**
+   * 显示弹幕层
+   */
+  show: () => Result
+
+  /**
+   * 挂载弹幕输入框
+   */
+  mount: (el?: HTMLDivElement | string) => void
+
+  /**
+   * 重置弹幕
+   */
+  reset: () => Result
+
+  /**
+   * 弹幕配置
+   */
+  option: Option
+
+  /**
+   * 是否隐藏弹幕层
+   */
+  isHide: boolean
+
+  /**
+   * 是否弹幕层停止状态
+   */
+  isStop: boolean
+}
+
+declare const artplayerPluginDanmuku: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginDanmuku
+
+export = artplayerPluginDanmuku
+export as namespace artplayerPluginDanmuku;

assets/ts/artplayer-plugin-dash-control.d.ts

@@ -0,0 +1,17 @@
+interface Config {
+  control?: boolean
+  setting?: boolean
+  title?: string
+  auto?: string
+  getName?: (level: object) => string
+}
+
+declare const artplayerPluginDashControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => {
+  name: 'artplayerPluginDashControl'
+  update: () => void
+}
+
+export default artplayerPluginDashControl
+
+export = artplayerPluginDashControl
+export as namespace artplayerPluginDashControl;

assets/ts/artplayer-plugin-document-pip.d.ts

@@ -0,0 +1,22 @@
+interface Option {
+  width?: number
+  height?: number
+  placeholder?: string
+  fallbackToVideoPiP?: boolean
+}
+
+interface Result {
+  name: 'artplayerPluginDocumentPip'
+  isSupported: boolean
+  isActive: boolean
+  open: () => void
+  close: () => void
+  toggle: () => void
+}
+
+declare const artplayerPluginDocumentPip: (option: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginDocumentPip
+
+export = artplayerPluginDocumentPip
+export as namespace artplayerPluginDocumentPip;

assets/ts/artplayer-plugin-hls-control.d.ts

@@ -0,0 +1,17 @@
+interface Config {
+  control?: boolean
+  setting?: boolean
+  title?: string
+  auto?: string
+  getName?: (level: object) => string
+}
+
+declare const artplayerPluginHlsControl: (option: { quality?: Config, audio?: Config }) => (art: Artplayer) => {
+  name: 'artplayerPluginHlsControl'
+  update: () => void
+}
+
+export default artplayerPluginHlsControl
+
+export = artplayerPluginHlsControl
+export as namespace artplayerPluginHlsControl;

assets/ts/artplayer-plugin-jassub.d.ts

@@ -0,0 +1,38 @@
+export interface JassubOption {
+  workerUrl: string
+  wasmUrl: string
+  modernWasmUrl: string
+  subUrl?: string
+  subContent?: string
+  timeOffset?: number
+  debug?: boolean
+  prescaleFactor?: number
+  prescaleHeightLimit?: number
+  maxRenderHeight?: number
+  fonts?: string[] | Uint8Array[]
+  availableFonts?: Record<string, Uint8Array | string>
+  fallbackFont?: string
+  useLocalFonts?: boolean
+  libassMemoryLimit?: number
+  libassGlyphLimit?: number
+  [key: string]: any
+}
+
+export interface JassubInstance {
+  resize: (force?: boolean, width?: number, height?: number, top?: number, left?: number) => Promise<void>
+  setVideo: (video: HTMLVideoElement) => Promise<void>
+  destroy: () => Promise<void>
+  [key: string]: any
+}
+
+interface Result {
+  name: 'artplayerPluginJassub'
+  instance: JassubInstance
+}
+
+declare const artplayerPluginJassub: (option: JassubOption) => (art: Artplayer) => Result
+
+export default artplayerPluginJassub
+
+export = artplayerPluginJassub
+export as namespace artplayerPluginJassub;

assets/ts/artplayer-plugin-multiple-subtitles.d.ts

@@ -0,0 +1,16 @@
+declare const artplayerPluginMultipleSubtitles: (option: {
+  subtitles: {
+    url?: string
+    name?: string
+    type?: 'vtt' | 'srt' | 'ass'
+    encoding?: string
+    onParser?: (...args: object[]) => object
+  }[]
+}) => (art: Artplayer) => {
+  name: 'multipleSubtitles'
+}
+
+export default artplayerPluginMultipleSubtitles
+
+export = artplayerPluginMultipleSubtitles
+export as namespace artplayerPluginMultipleSubtitles;

assets/ts/artplayer-plugin-vast.d.ts

@@ -0,0 +1,36 @@
+declare global {
+  interface Window {
+    artplayerPluginVast?: typeof artplayerPluginVast
+  }
+}
+
+type PlayUrlFn = (url: string, config?: any) => void
+type PlayResFn = (res: string, config?: any) => void
+
+interface VastPluginContext {
+  art: Artplayer
+  ima: any
+  imaPlayer: Player | null
+  playUrl: PlayUrlFn
+  playRes: PlayResFn
+  init: () => Player
+  adsRenderingSettings: any
+  playerOptions: PlayerOptions
+  container: HTMLDivElement | null
+}
+
+export type ArtplayerPluginVastOption = (params: VastPluginContext) => void | Promise<void>
+
+export interface ArtplayerPluginVastInstance {
+  name: 'artplayerPluginVast'
+  destroy?: () => void
+}
+
+declare function artplayerPluginVast(
+  option: ArtplayerPluginVastOption,
+): (art: Artplayer) => ArtplayerPluginVastInstance
+
+export default artplayerPluginVast
+
+export = artplayerPluginVast
+export as namespace artplayerPluginVast;

assets/ts/artplayer-plugin-vtt-thumbnail.d.ts

@@ -0,0 +1,10 @@
+declare const artplayerPluginVttThumbnail: (option: { vtt?: string, style?: Partial<CSSStyleDeclaration> }) => (
+  art: Artplayer,
+) => {
+  name: 'artplayerPluginVttThumbnail'
+}
+
+export default artplayerPluginVttThumbnail
+
+export = artplayerPluginVttThumbnail
+export as namespace artplayerPluginVttThumbnail;

assets/ts/artplayer-plugin-websr.d.ts

@@ -0,0 +1,20 @@
+interface Option {
+  compare?: boolean
+  networkSize?: 'small' | 'medium' | 'large'
+  weightsBaseUrl?: string
+  workerUrl?: string
+  videoScale?: number
+}
+
+interface Result {
+  name: 'artplayerPluginWebsr'
+  upscaler: any
+  update: (option: Option) => void
+}
+
+declare const artplayerPluginWebsr: (option?: Option) => (art: Artplayer) => Result
+
+export default artplayerPluginWebsr
+
+export = artplayerPluginWebsr
+export as namespace artplayerPluginWebsr;

assets/ts/artplayer-proxy-canvas.d.ts

@@ -0,0 +1,10 @@
+type Option = (ctx: CanvasRenderingContext2D, video: HTMLVideoElement) => void
+
+type Result = HTMLCanvasElement
+
+declare const artplayerProxyCanvas: (option?: Option) => (art: Artplayer) => Result
+
+export default artplayerProxyCanvas
+
+export = artplayerProxyCanvas
+export as namespace artplayerProxyCanvas;

assets/ts/artplayer-proxy-mediabunny.d.ts

@@ -0,0 +1,109 @@
+interface Option {
+  m3u8?: {
+    quality?: {
+      control?: boolean
+      setting?: boolean
+      title?: string
+      auto?: string
+      getName?: (level: {
+        id: number
+        index: number
+        name: null | string
+        height: number
+        bitrate: number
+      }) => string
+    }
+    audio?: {
+      control?: boolean
+      setting?: boolean
+      title?: string
+      auto?: string
+      getName?: (track: {
+        id: number
+        index: number
+        name: null | string
+        lang: string
+        language: string
+        bitrate: number
+      }) => string
+    }
+  }
+
+  /**
+   * Timeout for loading media in milliseconds
+   * @default 0
+   */
+  loadTimeout?: number
+
+  /**
+   * Interval for timeupdate events in milliseconds
+   * @default 250
+   */
+  timeupdateInterval?: number
+
+  /**
+   * Audio-video synchronization tolerance in seconds
+   * @default 0.12
+   */
+  avSyncTolerance?: number
+
+  /**
+   * Whether to drop late video frames
+   * @default false
+   */
+  dropLateFrames?: boolean
+
+  /**
+   * Poster image URL
+   */
+  poster?: string
+
+  /**
+   * Media source (URL, Blob, or ReadableStream)
+   */
+  source?: string | Blob | ReadableStream<Uint8Array>
+
+  /**
+   * Check if server supports range requests before loading
+   * @default false
+   */
+  preflightRange?: boolean
+
+  /**
+   * Initial volume (0-1)
+   * @default 0.7
+   */
+  volume?: number
+
+  /**
+   * Initial muted state
+   * @default false
+   */
+  muted?: boolean
+
+  /**
+   * Autoplay
+   * @default false
+   */
+  autoplay?: boolean
+
+  /**
+   * Loop playback
+   * @default false
+   */
+  loop?: boolean
+
+  /**
+   * Cross-origin setting
+   */
+  crossOrigin?: string
+}
+
+type Result = HTMLCanvasElement
+
+declare const artplayerProxyMediabunny: (option?: Option) => (art: Artplayer) => Result
+
+export default artplayerProxyMediabunny
+
+export = artplayerProxyMediabunny
+export as namespace artplayerProxyMediabunny;

assets/ts/artplayer-tool-iframe.d.ts

@@ -0,0 +1,32 @@
+interface Message {
+  type: string
+  data: any
+  id?: number
+}
+
+declare class ArtplayerToolIframe {
+  constructor(option: { iframe: HTMLIFrameElement, url: string })
+
+  static iframe: boolean
+  static postMessage(message: Message): void
+  static onMessage(event: MessageEvent & { data: Message }): void
+  static inject(): void
+
+  readonly promises: Record<number, { resove: (...args: any[]) => any, reject: (...args: any[]) => any }>
+  readonly injected: boolean
+  readonly destroyed: boolean
+  readonly $iframe: HTMLIFrameElement
+  readonly url: string
+  readonly messageCallback: (...args: any[]) => any
+
+  onMessage(event: MessageEvent & { data: Message }): void
+  postMessage(message: Message): Promise<any>
+  commit<T extends (...args: any[]) => any>(callback: T): Promise<ReturnType<T>>
+  message(callback: (...args: any[]) => any): void
+  destroy(): void
+}
+
+export default ArtplayerToolIframe
+
+export = artplayerToolIframe
+export as namespace artplayerToolIframe;