image-to-pixel 3.0.1 → 3.2.0

package/lib/editor/timeline-preview.js

@@ -0,0 +1,142 @@
+import { h, nextId } from './dom.js';
+import { seekTo, videoReady } from '../core/video/frames.js';
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+/** Account for the slider thumb's inset and sample the middle of the hovered frame. */
+export function timelineFrameAt(clientX, { left, width }, duration, fps) {
+  const inset = Math.min(7, width / 2);
+  const fraction = clamp((clientX - left - inset) / Math.max(1, width - inset * 2), 0, 1);
+  const count = Math.max(1, Math.ceil(duration * fps - 1e-6));
+  const index = Math.min(count - 1, Math.floor(fraction * duration * fps));
+  return { index, time: index / fps, seekTime: Math.max(0, Math.min((index + 0.5) / fps, duration - 1e-4)) };
+}
+
+export function timelineTime(time) {
+  const total = Math.max(0, Math.round(time * 100));
+  const hours = Math.floor(total / 360000), minutes = Math.floor(total / 6000) % 60;
+  const seconds = String(Math.floor(total / 100) % 60).padStart(2, '0');
+  return `${hours ? `${hours}:${String(minutes).padStart(2, '0')}` : minutes}:${seconds}.${String(total % 100).padStart(2, '0')}`;
+}
+
+/** A shared player-style hover preview for the playback and interval timelines. */
+export function createTimelinePreview(app) {
+  const canvas = h('canvas', { hidden: true, 'aria-label': 'Frame at hovered time' });
+  const hint = h('span', { text: 'Loading frame...' });
+  const time = h('span.num.itp-timeline-time');
+  const el = h('div.itp-timeline-preview', { id: nextId('itp-timeline'), role: 'tooltip', hidden: true },
+    h('div.itp-timeline-image', {}, canvas, hint), time);
+  let request = null, session = null, timer = null, idleTimer = null;
+
+  function release(s) {
+    s.video.pause(); s.video.removeAttribute('src'); s.video.load(); s.cache.clear();
+  }
+
+  function dispose() {
+    if (!session) return;
+    session.disposed = true;
+    if (!session.running) release(session);
+    session = null;
+  }
+
+  function hide() {
+    el.hidden = true; request = null; clearTimeout(timer); clearTimeout(idleTimer);
+    idleTimer = setTimeout(dispose, 10000);
+  }
+
+  function reset() { hide(); clearTimeout(idleTimer); dispose(); }
+
+  function position(target, clientX) {
+    const host = el.parentElement.getBoundingClientRect(), track = target.getBoundingClientRect();
+    const width = Math.min(180, Math.max(1, host.width - 16));
+    el.style.width = `${width}px`;
+    el.style.left = `${clamp(clientX - host.left - width / 2, 8, Math.max(8, host.width - width - 8))}px`;
+    el.style.bottom = `${host.bottom - track.top + 10}px`;
+  }
+
+  function paint(frame) {
+    canvas.width = frame.width; canvas.height = frame.height;
+    const ctx = canvas.getContext('2d'); ctx.imageSmoothingEnabled = false;
+    ctx.drawImage(frame, 0, 0);
+    canvas.hidden = false; hint.hidden = true;
+  }
+
+  function thumbnail(frame) {
+    const scale = Math.min(1, 168 / frame.width, 104 / frame.height);
+    const c = h('canvas', { width: Math.max(1, Math.round(frame.width * scale)), height: Math.max(1, Math.round(frame.height * scale)) });
+    const ctx = c.getContext('2d'); ctx.imageSmoothingEnabled = false;
+    ctx.drawImage(frame, 0, 0, c.width, c.height);
+    return c;
+  }
+
+  async function render(s) {
+    if (s.running || s.failed) return;
+    s.running = true;
+    try {
+      await s.ready;
+      while (!s.disposed && request?.item === s.item) {
+        const current = request;
+        let frame = s.cache.get(current.key);
+        if (!frame) {
+          // Never seek the main video's decoder: hover must not affect playback or selection.
+          await seekTo(s.video, current.seekTime);
+          if (s.disposed) break;
+          if (request?.key !== current.key) continue;
+          const result = await app.engine.process(s.video, current.settings);
+          if (s.disposed) break;
+          frame = thumbnail(result.toCanvas(1));
+          s.cache.set(current.key, frame);
+          if (s.cache.size > 32) s.cache.delete(s.cache.keys().next().value);
+        }
+        if (request?.key === current.key && app.current === s.item) { paint(frame); break; }
+      }
+    } catch {
+      if (!s.disposed) {
+        s.failed = true;
+        if (request?.item === s.item) { canvas.hidden = true; hint.hidden = false; hint.textContent = 'Preview unavailable'; }
+      }
+    } finally {
+      s.running = false;
+      if (s.disposed) release(s);
+    }
+  }
+
+  function load() {
+    if (!request || !app.engine) return;
+    if (session?.item !== request.item) {
+      dispose();
+      const video = h('video', { muted: true, playsInline: true, preload: 'auto', crossOrigin: 'anonymous' });
+      video.muted = true; video.src = request.item.source.currentSrc || request.item.source.src;
+      session = { item: request.item, video, cache: new Map(), running: false, disposed: false, failed: false,
+        ready: videoReady(video, { timeout: 10000 }) };
+    }
+    render(session);
+  }
+
+  function bind(target, { getFrame } = {}) {
+    target.setAttribute('aria-describedby', el.id);
+    target.addEventListener('pointermove', e => {
+      const item = app.current;
+      if (e.pointerType === 'touch' || item?.type !== 'video' || !Number.isFinite(item.duration) || item.duration <= 0) { hide(); return; }
+      clearTimeout(idleTimer);
+      const fps = item.fps || 30;
+      const frame = timelineFrameAt(e.clientX, target.getBoundingClientRect(), item.duration, fps);
+      const { export: ignored, ...visual } = app.store.settings;
+      const key = `${fps}/${frame.index}/${JSON.stringify(visual)}`;
+      const previous = request;
+      request = { item, key, ...frame, settings: app.store.settings };
+      position(target, e.clientX); el.hidden = false; time.textContent = timelineTime(frame.time);
+      const cached = getFrame?.(frame.index) || (session?.item === item && session.cache.get(key));
+      if (cached) { clearTimeout(timer); paint(cached); return; }
+      if (previous?.item === item && previous.key === key) return;
+      canvas.hidden = true; hint.hidden = false; hint.textContent = session?.failed ? 'Preview unavailable' : 'Loading frame...';
+      clearTimeout(timer); timer = setTimeout(load, 80);
+    });
+    target.addEventListener('pointerleave', hide);
+    target.addEventListener('pointercancel', hide);
+    target.addEventListener('blur', hide);
+  }
+
+  window.addEventListener('resize', hide);
+  return { el, bind, hide, reset };
+}

package/lib/editor/workspace.js

@@ -0,0 +1,62 @@
+// The saved workspace: every open file (its bytes, name and own settings) plus the shared settings,
+// kept in this browser's IndexedDB. Nothing is uploaded. One workspace per browser profile.
+
+const DB = 'image-to-pixel';
+const STORE = 'workspace';
+const KEY = 'current';
+const VERSION = 1;
+
+function open() {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === 'undefined') { reject(new Error('This browser has no IndexedDB')); return; }
+    const req = indexedDB.open(DB, 1);
+    req.onupgradeneeded = () => { if (!req.result.objectStoreNames.contains(STORE)) req.result.createObjectStore(STORE); };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+async function run(mode, fn) {
+  const db = await open();
+  try {
+    return await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, mode);
+      const req = fn(tx.objectStore(STORE));
+      tx.oncomplete = () => resolve(req && req.result);
+      tx.onerror = () => reject(tx.error || (req && req.error));
+      tx.onabort = () => reject(tx.error || new Error('Saving was cancelled'));
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Save the workspace.
+ * @param {{ shared: object, current: number, items: { name: string, type: 'image'|'video', file: Blob, own: object|null }[] }} ws
+ * @returns {Promise<number>} total bytes of the saved files
+ */
+export async function saveWorkspace(ws) {
+  const record = { version: VERSION, savedAt: Date.now(), ...ws };
+  await run('readwrite', s => s.put(record, KEY));
+  return ws.items.reduce((a, it) => a + (it.file ? it.file.size : 0), 0);
+}
+
+/** The saved workspace, or null. */
+export async function loadWorkspace() {
+  try {
+    const rec = await run('readonly', s => s.get(KEY));
+    return rec && rec.version === VERSION && Array.isArray(rec.items) ? rec : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+export async function forgetWorkspace() {
+  await run('readwrite', s => s.delete(KEY));
+}
+
+/** True when the error means the browser ran out of storage for us. */
+export const isQuotaError = e => !!e && (e.name === 'QuotaExceededError' || /quota|space/i.test(e.message || ''));
+
+export const fmtBytes = n => (n >= 1e9 ? `${(n / 1e9).toFixed(1)} GB` : n >= 1e6 ? `${(n / 1e6).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1e3))} KB`);

package/lib/index.js

@@ -1,31 +1,31 @@
-// image-to-pixel core: no UI. Works in browsers (WebGL 2 via ShaderMate, CPU fallback) and,
-// for { width, height, data } inputs, in Node on the CPU.
-
-export { createPixelator, pixelate, makeResult } from './core/engine.js';
-export {
-  DEFAULTS, DITHER_METHODS, SETTINGS_VERSION, MAX_SIZE, LEGACY_DITHER,
-  defaultSettings, normalizeSettings, mergeSettings, resolveSize, ditherKind, cropRect, ASPECTS,
-  encodeSettings, decodeSettings, compactSettings, settingsToJSON, settingsFromJSON,
-} from './core/settings.js';
-export { makePlan } from './core/plan.js';
-export { runCPU } from './core/cpu/pipeline.js';
-export { PALETTES, getPalette } from './core/palette/builtin.js';
-export { parsePalette, toGPL, toHexFile, toPaletteJSON } from './core/palette/parse.js';
-export { extractPalette } from './core/palette/extract.js';
-export { fetchLospec, lospecSlug } from './core/palette/lospec.js';
-export { thresholdMap, parseMatrix, bayer } from './core/dither/matrices.js';
-export { KERNELS } from './core/dither/kernels.js';
-export { PRESETS, getPreset } from './core/presets.js';
-export { parseColor, toHex, oklab } from './core/color.js';
-export { toFrame, loadImage } from './core/source.js';
-export { upscale, resizeNearest, uniqueColors, detectGrid, hasTransparency } from './core/export/scale.js';
-export { toCanvas, downloadBlob } from './core/export/canvas.js';
-export { encodePNG } from './core/export/png.js';
-export { encodeGIF } from './core/export/gif.js';
-export { createZip } from './core/export/zip.js';
-export { packSpriteSheet, buildTileset } from './core/export/sheet.js';
-export { forEachFrame, estimateFps, seekTo, frameTimes, videoReady, mediaError, sniffVideoCodec } from './core/video/frames.js';
-
-/* global __ITP_VERSION__ */
-// The build replaces __ITP_VERSION__ with package.json's version; unbundled source reports 'dev'.
-export const VERSION = typeof __ITP_VERSION__ === 'string' ? __ITP_VERSION__ : 'dev';
+// image-to-pixel core: no UI. Works in browsers (WebGL 2 via ShaderMate, CPU fallback) and,
+// for { width, height, data } inputs, in Node on the CPU.
+
+export { createPixelator, pixelate, makeResult } from './core/engine.js';
+export {
+  DEFAULTS, DITHER_METHODS, SETTINGS_VERSION, MAX_SIZE, LEGACY_DITHER,
+  defaultSettings, normalizeSettings, mergeSettings, resolveSize, ditherKind, cropRect, ASPECTS,
+  encodeSettings, decodeSettings, compactSettings, settingsToJSON, settingsFromJSON,
+} from './core/settings.js';
+export { makePlan } from './core/plan.js';
+export { runCPU } from './core/cpu/pipeline.js';
+export { PALETTES, getPalette } from './core/palette/builtin.js';
+export { parsePalette, toGPL, toHexFile, toPaletteJSON } from './core/palette/parse.js';
+export { extractPalette } from './core/palette/extract.js';
+export { fetchLospec, lospecSlug } from './core/palette/lospec.js';
+export { thresholdMap, parseMatrix, bayer } from './core/dither/matrices.js';
+export { KERNELS } from './core/dither/kernels.js';
+export { PRESETS, getPreset } from './core/presets.js';
+export { parseColor, toHex, oklab } from './core/color.js';
+export { toFrame, loadImage } from './core/source.js';
+export { upscale, resizeNearest, uniqueColors, detectGrid, hasTransparency } from './core/export/scale.js';
+export { toCanvas, downloadBlob } from './core/export/canvas.js';
+export { encodePNG } from './core/export/png.js';
+export { encodeGIF } from './core/export/gif.js';
+export { createZip } from './core/export/zip.js';
+export { packSpriteSheet, buildTileset } from './core/export/sheet.js';
+export { forEachFrame, estimateFps, seekTo, frameTimes, videoReady, mediaError, sniffVideoCodec } from './core/video/frames.js';
+
+/* global __ITP_VERSION__ */
+// The build replaces __ITP_VERSION__ with package.json's version; unbundled source reports 'dev'.
+export const VERSION = typeof __ITP_VERSION__ === 'string' ? __ITP_VERSION__ : 'dev';

package/lib/video.js

@@ -1,92 +1,122 @@
-// image-to-pixel/video: encode processed frames to MP4 (H.264) or WebM (VP9/VP8) with WebCodecs.
-// The muxers are this project's own (lib/core/video/mux-*.js): MIT, no dependencies.
-
-import { createMp4Muxer } from './core/video/mux-mp4.js';
-import { createWebmMuxer } from './core/video/mux-webm.js';
-import { upscale } from './core/export/scale.js';
-
-export { forEachFrame, estimateFps, seekTo, frameTimes, videoReady } from './core/video/frames.js';
-export { createMp4Muxer, createWebmMuxer };
-
-const AVC = ['avc1.640033', 'avc1.4d0033', 'avc1.42003e', 'avc1.640028', 'avc1.42001f'];
-const VP = [['vp09.00.10.08', 'vp9'], ['vp8', 'vp8']];
-
-/** Which formats this browser can encode. */
-export async function videoSupport(width = 640, height = 480) {
-  const out = { mp4: false, webm: false, webcodecs: typeof VideoEncoder !== 'undefined' };
-  if (out.webcodecs) {
-    for (const codec of AVC) if ((await VideoEncoder.isConfigSupported({ codec, width, height }).catch(() => ({}))).supported) { out.mp4 = true; break; }
-    for (const [codec] of VP) if ((await VideoEncoder.isConfigSupported({ codec, width, height }).catch(() => ({}))).supported) { out.webm = true; break; }
-  }
-  return out;
-}
-
-const even = n => n + (n & 1);
-
-/**
- * Start an encoder; add frames one at a time (so a long clip never sits in memory), then finish().
- * @param {{ format: 'mp4' | 'webm', fps: number, width: number, height: number, scale?: number, bitrate?: number }} opts
- *   width/height: size of the frames you will add (before scaling)
- */
-export async function createVideoEncoder(opts) {
-  const scale = Math.max(1, Math.round(opts.scale || 1));
-  const W = even(opts.width * scale), H = even(opts.height * scale);
-  const fps = opts.fps || 30;
-  const bitrate = opts.bitrate || Math.min(20e6, Math.max(2e6, W * H * fps * 0.15));
-  if (typeof VideoEncoder === 'undefined') throw new Error('This browser has no WebCodecs VideoEncoder. Export a GIF or PNG sequence instead.');
-
-  let codec = null, muxCodec = null;
-  const list = opts.format === 'mp4' ? AVC.map(c => [c, 'avc']) : VP;
-  for (const [c, m] of list) {
-    const ok = await VideoEncoder.isConfigSupported({ codec: c, width: W, height: H, bitrate, framerate: fps }).catch(() => ({}));
-    if (ok.supported) { codec = c; muxCodec = m; break; }
-  }
-  if (!codec) throw new Error(`No ${opts.format.toUpperCase()} encoder available in this browser at ${W}×${H}.`);
-
-  const muxer = opts.format === 'mp4'
-    ? createMp4Muxer({ width: W, height: H })
-    : createWebmMuxer({ width: W, height: H, codec: muxCodec, fps });
-
-  let error = null;
-  const encoder = new VideoEncoder({
-    output: (chunk, meta) => muxer.addChunk(chunk, meta),
-    error: e => { error = e; },
-  });
-  // avc.format 'avc': length-prefixed NAL units plus a decoder config record, which MP4 needs
-  encoder.configure({ codec, width: W, height: H, bitrate, framerate: fps, latencyMode: 'quality', ...(opts.format === 'mp4' ? { avc: { format: 'avc' } } : {}) });
-
-  const canvas = new OffscreenCanvas(W, H);
-  const ctx = canvas.getContext('2d');
-  let i = 0;
-  const frameUs = 1e6 / fps;
-
-  return {
-    width: W, height: H, codec,
-    /** @param {{ width, height, data }} img */
-    async add(img) {
-      if (error) throw error;
-      const up = scale > 1 ? upscale(img, scale) : img;
-      ctx.fillStyle = '#000'; ctx.fillRect(0, 0, W, H);
-      ctx.putImageData(new ImageData(new Uint8ClampedArray(up.data), up.width, up.height), 0, 0);
-      const frame = new VideoFrame(canvas, { timestamp: Math.round(i * frameUs), duration: Math.round(frameUs) });
-      encoder.encode(frame, { keyFrame: i % Math.max(1, Math.round(fps * 2)) === 0 });
-      frame.close();
-      i++;
-      if (encoder.encodeQueueSize > 8) await new Promise(r => setTimeout(r, 0));
-    },
-    /** @returns {Promise<Blob>} */
-    async finish() {
-      await encoder.flush();
-      if (error) throw error;
-      encoder.close();
-      return new Blob([muxer.finish()], { type: opts.format === 'mp4' ? 'video/mp4' : 'video/webm' });
-    },
-  };
-}
-
-/** Convenience: encode an array of frames in one go. */
-export async function encodeVideo(frames, opts) {
-  const enc = await createVideoEncoder({ ...opts, width: frames[0].width, height: frames[0].height });
-  for (const f of frames) await enc.add(f);
-  return enc.finish();
-}
+// image-to-pixel/video: encode processed frames to MP4 (H.264) or WebM (VP9/VP8) with WebCodecs,
+// optionally with the source's soundtrack (AAC or Opus in MP4, Opus in WebM).
+// The muxers are this project's own (lib/core/video/mux-*.js): MIT, no dependencies.
+
+import { createMp4Muxer } from './core/video/mux-mp4.js';
+import { createWebmMuxer } from './core/video/mux-webm.js';
+import { decodeAudio, encodeAudio, audioCodecSupported, findAudioConfig } from './core/video/audio.js';
+import { upscale } from './core/export/scale.js';
+
+export { forEachFrame, estimateFps, seekTo, frameTimes, videoReady } from './core/video/frames.js';
+export { createMp4Muxer, createWebmMuxer, decodeAudio, encodeAudio, audioCodecSupported, findAudioConfig };
+
+const AVC = ['avc1.640033', 'avc1.4d0033', 'avc1.42003e', 'avc1.640028', 'avc1.42001f'];
+const VP = [['vp09.00.10.08', 'vp9'], ['vp8', 'vp8']];
+
+/** Which formats this browser can encode. `aac` / `opus`: audio for MP4 (either) and WebM (Opus). */
+export async function videoSupport(width = 640, height = 480) {
+  const out = { mp4: false, webm: false, webcodecs: typeof VideoEncoder !== 'undefined', aac: false, opus: false };
+  if (out.webcodecs) {
+    for (const codec of AVC) if ((await VideoEncoder.isConfigSupported({ codec, width, height }).catch(() => ({}))).supported) { out.mp4 = true; break; }
+    for (const [codec] of VP) if ((await VideoEncoder.isConfigSupported({ codec, width, height }).catch(() => ({}))).supported) { out.webm = true; break; }
+  }
+  out.aac = await audioCodecSupported('aac');
+  out.opus = await audioCodecSupported('opus');
+  return out;
+}
+
+const even = n => n + (n & 1);
+
+/** The audio codec and encoder config for a container, or null when the browser can't encode a suitable one. */
+async function pickAudio(format, pcm, bitrate) {
+  const order = format === 'mp4' ? ['aac', 'opus'] : ['opus'];   // WebM only holds Opus (or Vorbis)
+  for (const codec of order) {
+    const config = await findAudioConfig(codec, pcm.sampleRate, pcm.numberOfChannels, bitrate);
+    if (config) return { codec, config };
+  }
+  return null;
+}
+
+/**
+ * Start an encoder; add frames one at a time (so a long clip never sits in memory), then finish().
+ * @param {{ format: 'mp4' | 'webm', fps: number, width: number, height: number, scale?: number, bitrate?: number,
+ *           audio?: { sampleRate: number, numberOfChannels: number, channels: Float32Array[] } | null,
+ *           audioBitrate?: number }} opts
+ *   width/height: size of the frames you will add (before scaling)
+ *   audio: PCM to add as a soundtrack, e.g. from decodeAudio(file, { start, end }). It is cut to the
+ *          video's length. When the browser can't encode audio the video is still made, without it
+ *          (check `encoder.audioCodec`).
+ */
+export async function createVideoEncoder(opts) {
+  const scale = Math.max(1, Math.round(opts.scale || 1));
+  const W = even(opts.width * scale), H = even(opts.height * scale);
+  const fps = opts.fps || 30;
+  const bitrate = opts.bitrate || Math.min(20e6, Math.max(2e6, W * H * fps * 0.15));
+  if (typeof VideoEncoder === 'undefined') throw new Error('This browser has no WebCodecs VideoEncoder. Export a GIF or PNG sequence instead.');
+
+  let codec = null, muxCodec = null;
+  const list = opts.format === 'mp4' ? AVC.map(c => [c, 'avc']) : VP;
+  for (const [c, m] of list) {
+    const ok = await VideoEncoder.isConfigSupported({ codec: c, width: W, height: H, bitrate, framerate: fps }).catch(() => ({}));
+    if (ok.supported) { codec = c; muxCodec = m; break; }
+  }
+  if (!codec) throw new Error(`No ${opts.format.toUpperCase()} encoder available in this browser at ${W}×${H}.`);
+
+  const pcm = opts.audio && opts.audio.channels && opts.audio.channels.length ? opts.audio : null;
+  const picked = pcm ? await pickAudio(opts.format, pcm, opts.audioBitrate || 128000) : null;
+  const audioCodec = picked ? picked.codec : null;
+  const audioTrack = picked ? { codec: audioCodec, sampleRate: picked.config.sampleRate, numberOfChannels: picked.config.numberOfChannels, bitrate: picked.config.bitrate || 128000 } : null;
+
+  const muxer = opts.format === 'mp4'
+    ? createMp4Muxer({ width: W, height: H, audio: audioTrack })
+    : createWebmMuxer({ width: W, height: H, codec: muxCodec, fps, audio: audioTrack });
+
+  let error = null;
+  const encoder = new VideoEncoder({
+    output: (chunk, meta) => muxer.addChunk(chunk, meta),
+    error: e => { error = e; },
+  });
+  // avc.format 'avc': length-prefixed NAL units plus a decoder config record, which MP4 needs
+  encoder.configure({ codec, width: W, height: H, bitrate, framerate: fps, latencyMode: 'quality', ...(opts.format === 'mp4' ? { avc: { format: 'avc' } } : {}) });
+
+  const canvas = new OffscreenCanvas(W, H);
+  const ctx = canvas.getContext('2d');
+  let i = 0;
+  const frameUs = 1e6 / fps;
+
+  return {
+    width: W, height: H, codec,
+    /** 'aac' or 'opus' when the soundtrack will be included, null otherwise. */
+    audioCodec,
+    /** @param {{ width, height, data }} img */
+    async add(img) {
+      if (error) throw error;
+      const up = scale > 1 ? upscale(img, scale) : img;
+      ctx.fillStyle = '#000'; ctx.fillRect(0, 0, W, H);
+      ctx.putImageData(new ImageData(new Uint8ClampedArray(up.data), up.width, up.height), 0, 0);
+      const frame = new VideoFrame(canvas, { timestamp: Math.round(i * frameUs), duration: Math.round(frameUs) });
+      encoder.encode(frame, { keyFrame: i % Math.max(1, Math.round(fps * 2)) === 0 });
+      frame.close();
+      i++;
+      if (encoder.encodeQueueSize > 8) await new Promise(r => setTimeout(r, 0));
+    },
+    /** @returns {Promise<Blob>} */
+    async finish() {
+      await encoder.flush();
+      if (error) throw error;
+      encoder.close();
+      if (audioCodec && i > 0) {
+        // the soundtrack ends with the last frame
+        await encodeAudio(pcm, { config: picked.config, maxDuration: i / fps, onChunk: (chunk, meta) => muxer.addAudioChunk(chunk, meta) });
+      }
+      return new Blob([muxer.finish()], { type: opts.format === 'mp4' ? 'video/mp4' : 'video/webm' });
+    },
+  };
+}
+
+/** Convenience: encode an array of frames in one go. */
+export async function encodeVideo(frames, opts) {
+  const enc = await createVideoEncoder({ ...opts, width: frames[0].width, height: frames[0].height });
+  for (const f of frames) await enc.add(f);
+  return enc.finish();
+}