@banou/media-player 0.6.2 → 0.7.0

package/src/lib/engine/picture-in-picture.ts

@@ -0,0 +1,250 @@
+/**
+ * Picture in picture with the subtitles burned in.
+ *
+ * The window takes a video element and nothing else, so subtitles painted on a canvas over the video
+ * cannot come along. Each frame is composited with the subtitle canvas onto an offscreen canvas, and
+ * `captureStream()` backs a hidden mirror element, which is the one that enters the window. The
+ * original element keeps playing and stays the only audio source.
+ */
+
+const DEFAULT_MAX_WIDTH = 1280
+/** The frame callback fires only for presented frames, so a paused video needs its own repaint. */
+const PAUSED_REPAINT_INTERVAL = 250
+
+export type PictureInPictureOptions = {
+  video: HTMLVideoElement
+  /** The subtitle canvas. jassub sizes it to the video's content rect, so it maps 1:1. */
+  canvas: HTMLCanvasElement
+  maxWidth?: number
+  /** Where the hidden mirror is mounted. It must be in the document. Defaults to the video's parent. */
+  container?: HTMLElement
+  /**
+   * Toggle used when compositing is unavailable or fails. The React layer passes the player store's
+   * own action, which handles Safari and exits fullscreen first; the default here does neither.
+   */
+  fallback?: () => Promise<void>
+}
+
+export type PictureInPictureController = {
+  toggle: () => Promise<void>
+  destroy: () => void
+}
+
+type Session = {
+  composite: HTMLCanvasElement
+  context: CanvasRenderingContext2D
+  stream: MediaStream
+  mirror: HTMLVideoElement
+}
+
+const supportsCompositing = () =>
+  typeof HTMLCanvasElement !== 'undefined' &&
+  'captureStream' in HTMLCanvasElement.prototype &&
+  typeof document !== 'undefined' &&
+  document.pictureInPictureEnabled
+
+/** Takes over the document's Media Session play/pause handlers while a session is open. */
+export const createPictureInPicture = (options: PictureInPictureOptions): PictureInPictureController => {
+  const { video, canvas, maxWidth = DEFAULT_MAX_WIDTH } = options
+
+  let session: Session | undefined
+  let handle: number | undefined
+  let pausedRepaint: ReturnType<typeof setInterval> | undefined
+  let syncing = false
+  // Nothing can tell a session is being built until `enter` resolves, so without this a second click
+  // starts a second pipeline whose timer and mirror are then unreachable.
+  let entering = false
+  let destroyed = false
+
+  const active = () => !!session && document.pictureInPictureElement === session.mirror
+
+  const draw = (composite: HTMLCanvasElement, context: CanvasRenderingContext2D) => {
+    context.drawImage(video, 0, 0, composite.width, composite.height)
+    // drawImage throws on a zero-sized source, which the canvas is until jassub has painted
+    if (canvas.width > 0 && canvas.height > 0) {
+      context.drawImage(canvas, 0, 0, composite.width, composite.height)
+    }
+  }
+
+  const paint = () => {
+    if (session) draw(session.composite, session.context)
+  }
+
+  const useFrameCallback = 'requestVideoFrameCallback' in video
+
+  const loop = () => {
+    paint()
+    schedule()
+  }
+
+  const schedule = () => {
+    if (destroyed || !session) return
+    handle = useFrameCallback ? video.requestVideoFrameCallback(loop) : requestAnimationFrame(loop)
+  }
+
+  const stopLoop = () => {
+    if (handle !== undefined) {
+      if (useFrameCallback) video.cancelVideoFrameCallback(handle)
+      else cancelAnimationFrame(handle)
+    }
+    if (pausedRepaint !== undefined) clearInterval(pausedRepaint)
+    handle = undefined
+    pausedRepaint = undefined
+  }
+
+  const publishState = () => {
+    if (!('mediaSession' in navigator)) return
+    navigator.mediaSession.playbackState = video.paused ? 'paused' : 'playing'
+  }
+
+  const onMirrorPlay = () => {
+    if (syncing || !video.paused) return
+    void video.play().catch(() => {})
+  }
+
+  // Reached on a browser whose window controls pause the mirror directly instead of going through the
+  // Media Session. Forward the intent, then put the mirror back to work.
+  const onMirrorPause = () => {
+    if (syncing) return
+    if (!video.paused) video.pause()
+    syncing = true
+    void session?.mirror.play().catch(() => {}).finally(() => { syncing = false })
+  }
+
+  const onVideoPlay = () => {
+    publishState()
+    void session?.mirror.play().catch(() => {})
+  }
+
+  /**
+   * NEVER pause the mirror. A paused element stops rendering its MediaStream, so the window freezes on
+   * its last frame: measured at 0 of 57,600 pixels moving on a seek. Transport state travels through
+   * the Media Session instead, which is what the window reads for its button.
+   */
+  const onVideoPause = () => {
+    publishState()
+  }
+
+  const mediaSessionActions: [MediaSessionAction, MediaSessionActionHandler][] = [
+    ['play', () => { void video.play().catch(() => {}) }],
+    ['pause', () => video.pause()],
+  ]
+
+  const bindMediaSession = (bind: boolean) => {
+    if (!('mediaSession' in navigator)) return
+    for (const [action, handler] of mediaSessionActions) {
+      try {
+        navigator.mediaSession.setActionHandler(action, bind ? handler : null)
+      } catch {
+        // an action the browser does not know is not worth surfacing
+      }
+    }
+  }
+
+  const teardown = () => {
+    stopLoop()
+    bindMediaSession(false)
+    video.removeEventListener('play', onVideoPlay)
+    video.removeEventListener('pause', onVideoPause)
+    if (!session) return
+    const { stream, mirror } = session
+    mirror.removeEventListener('play', onMirrorPlay)
+    mirror.removeEventListener('pause', onMirrorPause)
+    mirror.removeEventListener('leavepictureinpicture', onLeave)
+    for (const track of stream.getTracks()) track.stop()
+    mirror.remove()
+    session = undefined
+  }
+
+  const onLeave = () => teardown()
+
+  const fallback = options.fallback ?? (async () => {
+    if (document.pictureInPictureElement === video) await document.exitPictureInPicture()
+    else await video.requestPictureInPicture()
+  })
+
+  const enter = async () => {
+    // Sized off the intrinsic dimensions, never the layout, so a resize cannot resize a canvas that a
+    // MediaStream is already capturing.
+    const width = Math.min(video.videoWidth || maxWidth, maxWidth)
+    const height = Math.round(width * ((video.videoHeight || 9) / (video.videoWidth || 16)))
+
+    const composite = document.createElement('canvas')
+    composite.width = width
+    composite.height = height
+    // The alpha channel is unused but has to stay: with `{ alpha: false }` Chrome's captureStream
+    // delivers the first frame and then nothing, with the track still "live" and no error anywhere.
+    const context = composite.getContext('2d')
+    if (!context) throw new Error('the picture in picture composite has no 2d context')
+
+    const mirror = document.createElement('video')
+    mirror.muted = true
+    mirror.playsInline = true
+    mirror.style.cssText = 'position:fixed;width:1px;height:1px;opacity:0;pointer-events:none;left:-1px;top:-1px'
+
+    // one frame before the capture starts, so the stream has content from its first moment
+    draw(composite, context)
+
+    session = { composite, context, stream: composite.captureStream(), mirror }
+    mirror.srcObject = session.stream
+    ;(options.container ?? video.parentElement ?? document.body).appendChild(mirror)
+
+    schedule()
+    pausedRepaint = setInterval(() => { if (video.paused) paint() }, PAUSED_REPAINT_INTERVAL)
+    void mirror.play().catch(() => {})
+
+    // requestPictureInPicture rejects while readyState is 0, and the wait is short enough that the
+    // click's transient user activation survives it.
+    if (mirror.readyState === 0) {
+      await new Promise<void>((resolve) => {
+        const done = () => { clearTimeout(timer); resolve() }
+        const timer = setTimeout(done, 1000)
+        mirror.addEventListener('loadedmetadata', done, { once: true })
+      })
+    }
+
+    mirror.addEventListener('play', onMirrorPlay)
+    mirror.addEventListener('pause', onMirrorPause)
+    mirror.addEventListener('leavepictureinpicture', onLeave)
+    video.addEventListener('play', onVideoPlay)
+    video.addEventListener('pause', onVideoPause)
+    bindMediaSession(true)
+    publishState()
+
+    await mirror.requestPictureInPicture()
+  }
+
+  const toggle = async () => {
+    if (destroyed || entering) return
+    if (active()) {
+      await document.exitPictureInPicture().catch(() => {})
+      return
+    }
+    if (!supportsCompositing()) {
+      await fallback()
+      return
+    }
+    // another element, including our own last mirror, may still hold the single slot
+    if (document.pictureInPictureElement) await document.exitPictureInPicture().catch(() => {})
+
+    entering = true
+    try {
+      await enter()
+    } catch (error) {
+      console.warn('subtitle compositing for picture in picture failed, falling back', error)
+      teardown()
+      await fallback().catch(() => {})
+    } finally {
+      entering = false
+    }
+  }
+
+  return {
+    toggle,
+    destroy: () => {
+      destroyed = true
+      if (active()) void document.exitPictureInPicture().catch(() => {})
+      teardown()
+    },
+  }
+}

package/src/lib/engine/playback.ts

@@ -0,0 +1,352 @@
+import type { AudioStream } from 'libav-wasm/build/worker'
+
+import { makeRemuxer } from 'libav-wasm'
+
+import { getTimeRanges, updateSourceBuffer } from './source-buffer'
+import { createSubtitleRenderer } from './subtitles'
+import type { SubtitleStream } from './subtitles'
+
+export type { AudioStream }
+
+/** A keyframe index entry: the byte offset a keyframe starts at, and the time it plays at. */
+export type MediaIndex = { pos: number, timestamp: number }
+
+export type PlaybackOptions = {
+  videoElement: HTMLVideoElement
+  canvasElement: HTMLCanvasElement
+  read: (offset: number, size: number) => Promise<ArrayBuffer>
+  length: number
+  /** serves BOTH `libav.wasm` and `libav-jspi.wasm`; libav-wasm picks one on `WebAssembly.Suspending` */
+  publicPath: string
+  libavWorkerUrl: string
+  jassubWorkerUrl: string
+  jassubWasmUrl: string
+  /** jassub's non-SIMD build; without it subtitles fail rather than degrade on Safari before 16.4 */
+  jassubLegacyWasmUrl?: string
+  defaultFontUrl?: string
+  bufferSize?: number
+  audioStreamIndex?: number
+  onReady?: () => void
+  onError?: (error: unknown) => void
+  onRecovered?: () => void
+  onSeek?: (fraction: number) => void
+  onSubtitleStreams?: (streams: SubtitleStream[]) => void
+  onAudioStreams?: (streams: AudioStream[], selected: number) => void
+}
+
+export type PlaybackController = {
+  destroy: () => void
+  selectSubtitleStream: (streamIndex: number | undefined) => void
+  /** Keyframe index of the input, which is what maps a downloaded byte range onto the timeline. */
+  indexes: MediaIndex[]
+  duration: number
+  videoMimeType: string
+  audioMimeType: string
+}
+
+// ~20s behind and ~60s ahead of the playhead, refilled when the forward buffer dips under 30s
+const PRE_EVICT = -20
+const POST_EVICT = 60
+const BUFFER_TARGET = 30
+// the tighter window used after the browser refuses an append
+const PRE_EVICT_TIGHT = -5
+const POST_EVICT_TIGHT = 20
+const MAX_APPEND_ATTEMPTS = 5
+const SOURCE_OPEN_TIMEOUT = 15_000
+// how far past the playhead a range may start and still count as the one holding it
+const BOUNDARY_SLACK = 1
+export const DEFAULT_BUFFER_SIZE = 2_500_000
+
+// destroy() only terminates after a round trip into the wasm, so terminate on our own clock too
+export const terminateRemuxer = (remuxer: { worker: Worker, destroy: () => Promise<void> }) => {
+  const { worker } = remuxer
+  const bail = setTimeout(() => worker.terminate(), 2_000)
+  void remuxer
+    .destroy()
+    .catch(() => {})
+    .finally(() => {
+      clearTimeout(bail)
+      worker.terminate()
+    })
+}
+
+export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackController> => {
+  const {
+    videoElement, canvasElement, read, length, publicPath, libavWorkerUrl,
+    jassubWorkerUrl, jassubWasmUrl, jassubLegacyWasmUrl, defaultFontUrl, bufferSize = DEFAULT_BUFFER_SIZE,
+    audioStreamIndex, onReady, onError, onRecovered, onSeek, onSubtitleStreams,
+    onAudioStreams,
+  } = options
+
+  const remuxer = await makeRemuxer({
+    publicPath,
+    workerUrl: libavWorkerUrl,
+    workerOptions: { type: 'module' },
+    bufferSize,
+    length,
+    audioStreamIndex,
+    read,
+  })
+
+  const teardown: (() => void)[] = []
+  let destroyed = false
+  const runTeardown = () => {
+    if (destroyed) return
+    destroyed = true
+    for (const step of [...teardown].reverse()) {
+      try { step() } catch {}
+    }
+  }
+  teardown.push(() => terminateRemuxer(remuxer))
+
+  try {
+    const metadata = await remuxer.init()
+
+    const audioStreams = metadata.audioStreams ?? []
+    const selectedAudio = audioStreams.some((s) => s.streamIndex === audioStreamIndex)
+      ? audioStreamIndex!
+      : audioStreams[0]?.streamIndex ?? -1
+    onAudioStreams?.(audioStreams, selectedAudio)
+
+    const subtitles = createSubtitleRenderer({
+      video: videoElement,
+      canvas: canvasElement,
+      workerUrl: jassubWorkerUrl,
+      wasmUrl: jassubWasmUrl,
+      legacyWasmUrl: jassubLegacyWasmUrl,
+      defaultFontUrl,
+      onStreams: onSubtitleStreams,
+    })
+    teardown.push(() => subtitles.destroy())
+    if (metadata.attachments?.length) subtitles.pushAttachments(metadata.attachments)
+
+    // an unparseable codec is an empty string, which isTypeSupported would accept as audio-only
+    if (!metadata.info.output.videoMimeType) throw new Error('The video codec in this file could not be identified')
+    const codecs = [metadata.info.output.videoMimeType, metadata.info.output.audioMimeType].filter(Boolean).join(',')
+    const mime = `video/mp4; codecs="${codecs}"`
+    if (!MediaSource.isTypeSupported(mime)) throw new Error(`This browser cannot play the codecs in this file: ${codecs}`)
+
+    const mediaSource = new MediaSource()
+    const mediaSourceUrl = URL.createObjectURL(mediaSource)
+    teardown.push(() => URL.revokeObjectURL(mediaSourceUrl))
+    videoElement.src = mediaSourceUrl
+
+    const sourceBuffer = await new Promise<SourceBuffer>((resolve, reject) => {
+      const timeout = setTimeout(() => { cleanup(); reject(new Error('The MediaSource never opened')) }, SOURCE_OPEN_TIMEOUT)
+      const cleanup = () => {
+        clearTimeout(timeout)
+        mediaSource.removeEventListener('sourceopen', onSourceOpen)
+        mediaSource.removeEventListener('sourceclose', onFail)
+        mediaSource.removeEventListener('error', onFail)
+      }
+      const onSourceOpen = () => {
+        try {
+          const sb = mediaSource.addSourceBuffer(mime)
+          sb.mode = 'segments'
+          const duration = metadata.info.input.duration
+          if (Number.isFinite(duration) && duration > 0) mediaSource.duration = duration
+          cleanup()
+          resolve(sb)
+        } catch (error) {
+          cleanup()
+          reject(error)
+        }
+      }
+      const onFail = () => { cleanup(); reject(new Error('The MediaSource closed before a SourceBuffer could be created')) }
+      mediaSource.addEventListener('sourceopen', onSourceOpen, { once: true })
+      mediaSource.addEventListener('sourceclose', onFail, { once: true })
+      mediaSource.addEventListener('error', onFail, { once: true })
+    })
+
+    const { appendBuffer, unbufferRange, updateTimestampOffset, endOfStream } = updateSourceBuffer(sourceBuffer, mediaSource)
+    await appendBuffer(metadata.data)
+    if (metadata.subtitles?.length) subtitles.pushFragments(metadata.subtitles)
+    onReady?.()
+
+    let reading = false
+    let seeking = false
+    let finished = false
+    // libav aborts the running task when a new one starts, so both flags need a generation token
+    let readGeneration = 0
+    let seekGeneration = 0
+    let pending: ArrayBuffer | null = null
+    let pendingAttempts = 0
+    let lastAppendedEnd = 0
+    let outstandingError = false
+    // where the remuxer was last positioned, which is the floor of what it can still read forward from
+    let lastSeekPosition = 0
+
+    // 'Cancelled' covers both an aborted task and a read that gave up, so it is only noise mid-seek
+    const reportError = (error: unknown, aborted: boolean) => {
+      const cancelled = (error as Error)?.message === 'Cancelled'
+      if (aborted && cancelled) return
+      console.error(error)
+      if (outstandingError) return
+      outstandingError = true
+      onError?.(cancelled ? new Error('Reading the video file failed', { cause: error }) : error)
+    }
+
+    const evict = async (tight = false) => {
+      const ct = videoElement.currentTime
+      const pre = tight ? PRE_EVICT_TIGHT : PRE_EVICT
+      const post = tight ? POST_EVICT_TIGHT : POST_EVICT
+      for (const { start, end } of getTimeRanges(sourceBuffer)) {
+        if (start < ct + pre) await unbufferRange(start, ct + pre)
+        if (end > ct + post) await unbufferRange(ct + post, end)
+      }
+    }
+
+    // The ceiling on the furthest buffered end stops a backward-seek hole becoming a runaway, and the
+    // slack covers a first segment that starts just after zero from audio priming.
+    const needsData = () => {
+      const ranges = getTimeRanges(sourceBuffer)
+      if (!ranges.length) return true
+      const ct = videoElement.currentTime
+      // never read past what evict() keeps
+      if (Math.max(...ranges.map((r) => r.end)) >= ct + POST_EVICT) return false
+      const range = ranges.find((r) => r.start <= ct + BOUNDARY_SLACK && ct < r.end)
+      return !range || range.end < ct + BUFFER_TARGET
+    }
+
+    const playheadRange = () => {
+      const ct = videoElement.currentTime
+      return getTimeRanges(sourceBuffer).find((r) => r.start <= ct + BOUNDARY_SLACK && ct < r.end)
+    }
+
+    // the end may only be signalled once the playhead's own range covers it
+    const atEnd = () => {
+      const range = playheadRange()
+      return !!range && range.end >= lastAppendedEnd - 0.1
+    }
+    const trackAppendedEnd = () => {
+      const ends = getTimeRanges(sourceBuffer).map((r) => r.end)
+      if (ends.length) lastAppendedEnd = Math.max(lastAppendedEnd, ...ends)
+    }
+
+    const seekTo = async (time: number) => {
+      seeking = true
+      pending = null
+      pendingAttempts = 0
+      lastSeekPosition = time
+      const generation = ++seekGeneration
+      try {
+        const { data, pts, subtitles: fragments } = await remuxer.seek(time)
+        if (destroyed || generation !== seekGeneration) return
+        if (fragments?.length) subtitles.pushFragments(fragments)
+        await updateTimestampOffset(pts)
+        if (destroyed || generation !== seekGeneration) return
+        if (data.byteLength) {
+          await appendBuffer(data)
+          trackAppendedEnd()
+        }
+      } catch (error) {
+        reportError(error, destroyed || generation !== seekGeneration)
+      } finally {
+        if (generation === seekGeneration) seeking = false
+      }
+    }
+
+    const flushPending = async () => {
+      const segment = pending
+      if (!segment) return
+      try {
+        await appendBuffer(segment)
+        trackAppendedEnd()
+        if (pending === segment) {
+          pending = null
+          pendingAttempts = 0
+        }
+      } catch (error) {
+        if (pending !== segment) return
+        // Chrome refuses appends past a per-element video budget of roughly 150MB
+        if ((error as DOMException)?.name === 'QuotaExceededError') {
+          const evicted = await evict(true).then(() => true, () => false)
+          if (pending !== segment) return
+          if (evicted) {
+            // Reads only move forward, so restart at the far edge of what was kept rather than at
+            // the playhead, which would walk straight back into the same refusal.
+            finished = false
+            await seekTo(playheadRange()?.end ?? videoElement.currentTime)
+            return
+          }
+        }
+        pendingAttempts += 1
+        if (pendingAttempts < MAX_APPEND_ATTEMPTS) return
+        pending = null
+        throw error
+      }
+    }
+
+    const pump = async () => {
+      if (reading || seeking || destroyed) return
+      if (!pending && (finished || !needsData())) return
+      const generation = ++readGeneration
+      const seekAtStart = seekGeneration
+      const stale = () => destroyed || generation !== readGeneration || seekAtStart !== seekGeneration
+      reading = true
+      try {
+        if (!pending) {
+          const { data, subtitles: fragments, finished: done } = await remuxer.read()
+          if (stale()) return
+          if (done) finished = true
+          if (fragments?.length) subtitles.pushFragments(fragments)
+          if (!data.byteLength) return
+          pending = data
+          pendingAttempts = 0
+        }
+        await flushPending()
+        if (!stale() && outstandingError) {
+          outstandingError = false
+          onRecovered?.()
+        }
+      } catch (error) {
+        reportError(error, stale())
+      } finally {
+        if (generation === readGeneration) reading = false
+      }
+    }
+
+    /**
+     * A remuxer seek is expensive out of proportion to what it looks like: libav tears down and rebuilds
+     * BOTH the input and the output context and re-runs write_header, because the fragmented mp4 muxer
+     * cannot rewind. Skipping it when the target is already playable is most of what a seek costs.
+     *
+     * Both conditions are needed. Buffered alone is not enough: landing before the last remuxer position
+     * means the reader is somewhere ahead, so the gap between here and it can never be filled without a
+     * seek, and playback would stall at the end of this range instead. At or after it, the bytes from
+     * here to the read cursor are contiguous and reading simply carries on.
+     */
+    const alreadyPlayable = (time: number) => time >= lastSeekPosition && !!playheadRange()
+
+    const onSeeking = () => {
+      const time = videoElement.currentTime
+      const duration = metadata.info.input.duration || videoElement.duration
+      if (duration > 0) onSeek?.(Math.min(Math.max(time / duration, 0), 1))
+      if (alreadyPlayable(time)) return
+      finished = false
+      void seekTo(time)
+    }
+    videoElement.addEventListener('seeking', onSeeking)
+    teardown.push(() => videoElement.removeEventListener('seeking', onSeeking))
+
+    const interval = setInterval(() => {
+      evict().catch(() => {})
+      pump().catch((error) => reportError(error, false))
+      // every remove() puts the MediaSource back to 'open', so the end has to be re-armed
+      if (finished && !pending && atEnd() && mediaSource.readyState === 'open') endOfStream().catch(() => {})
+    }, 100)
+    teardown.push(() => clearInterval(interval))
+
+    return {
+      destroy: runTeardown,
+      selectSubtitleStream: (streamIndex: number | undefined) => subtitles.selectStream(streamIndex),
+      indexes: metadata.indexes ?? [],
+      duration: metadata.info.input.duration,
+      videoMimeType: metadata.info.output.videoMimeType,
+      audioMimeType: metadata.info.output.audioMimeType,
+    }
+  } catch (error) {
+    runTeardown()
+    throw error
+  }
+}

package/src/lib/engine/source-buffer.ts

@@ -0,0 +1,61 @@
+// appendBuffer, remove and timestampOffset must never overlap an in-flight update, so every op
+// goes through one chain
+
+export type TimeRange = { index: number, start: number, end: number }
+
+export const getTimeRanges = (sourceBuffer: SourceBuffer): TimeRange[] =>
+  Array(sourceBuffer.buffered.length)
+    .fill(undefined)
+    .map((_, index) => ({
+      index,
+      start: sourceBuffer.buffered.start(index),
+      end: sourceBuffer.buffered.end(index),
+    }))
+
+const waitForUpdate = (sourceBuffer: SourceBuffer) =>
+  new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      sourceBuffer.removeEventListener('updateend', onEnd)
+      sourceBuffer.removeEventListener('abort', onEnd)
+      sourceBuffer.removeEventListener('error', onError)
+    }
+    const onEnd = () => { cleanup(); resolve() }
+    const onError = (ev: Event) => { cleanup(); reject(new Error('The browser rejected a media segment', { cause: ev })) }
+    sourceBuffer.addEventListener('updateend', onEnd, { once: true })
+    sourceBuffer.addEventListener('abort', onEnd, { once: true })
+    sourceBuffer.addEventListener('error', onError, { once: true })
+  })
+
+export const updateSourceBuffer = (sourceBuffer: SourceBuffer, mediaSource: MediaSource) => {
+  let chain: Promise<unknown> = Promise.resolve()
+  const enqueue = <T>(task: () => Promise<T>): Promise<T> => {
+    const run = chain.then(task, task)
+    chain = run.catch(() => {})
+    return run as Promise<T>
+  }
+
+  const appendBuffer = (buffer: ArrayBuffer | Uint8Array) =>
+    enqueue(() => {
+      sourceBuffer.appendBuffer(buffer as BufferSource)
+      return waitForUpdate(sourceBuffer)
+    })
+
+  const unbufferRange = (start: number, end: number) =>
+    enqueue(() => {
+      if (start >= end) return Promise.resolve()
+      sourceBuffer.remove(start, end)
+      return waitForUpdate(sourceBuffer)
+    })
+
+  const updateTimestampOffset = (timestampOffset: number) =>
+    enqueue(async () => { sourceBuffer.timestampOffset = timestampOffset })
+
+  // endOfStream throws mid-update and is undone by the next remove(), so the caller re-arms it
+  const endOfStream = () =>
+    enqueue(async () => {
+      if (mediaSource.readyState !== 'open' || sourceBuffer.updating) return
+      try { mediaSource.endOfStream() } catch {}
+    })
+
+  return { appendBuffer, unbufferRange, updateTimestampOffset, endOfStream }
+}