@pictor-sdk/video-android 0.1.0

package/src/thumbnailProvider.ts

@@ -0,0 +1,163 @@
+import {
+  createThumbnailPolicy,
+  thumbnailKey,
+  type MediaSource,
+  type AbortLike,
+  type Thumbnail,
+  type ThumbnailProvider,
+  type ThumbnailRequest,
+} from '@pictor-sdk/video-core'
+import { requireNative } from './player'
+
+/**
+ * `ThumbnailProvider` over Media3's retriever, with the core policy on top.
+ *
+ * The division is the point: `@pictor-sdk/video-core` owns deduplication, the
+ * bounded cache and visible-range ordering, all of which are pure; this file
+ * owns the part that needs a codec. A host that writes its own provider — for a
+ * remote thumbnail service, say — reuses the policy and replaces only this.
+ *
+ * Results arrive as base64 JPEG rather than as a native image handle. A strip
+ * thumbnail is a few kilobytes and it is drawn by React Native's own image
+ * pipeline, so there is nothing here to leak and no ownership to transfer. The
+ * `AHardwareBuffer` lesson applies to full-resolution frames at 30 per second,
+ * not to a 64-pixel square that changes when the user scrolls.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+export interface AndroidThumbnailOptions {
+  /**
+   * How many decoded thumbnails to keep.
+   *
+   * 240 covers several screens of a dense strip at 64 px — enough that
+   * scrolling back does not re-decode, bounded enough that a long project
+   * cannot grow without limit.
+   */
+  capacity?: number
+  /** How often to check whether a decode has finished, in milliseconds. */
+  pollMs?: number
+}
+
+const DEFAULT_CAPACITY = 240
+const DEFAULT_POLL_MS = 16
+
+/** @experimental */
+export function createAndroidThumbnailProvider(
+  options: AndroidThumbnailOptions = {},
+): ThumbnailProvider {
+  const policy = createThumbnailPolicy<string>({
+    capacity: options.capacity ?? DEFAULT_CAPACITY,
+  })
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS
+  /** Tokens in flight, by request key, so a cancel can reach the native side. */
+  const tokens = new Map<string, number>()
+
+  function uriOf(source: MediaSource): string {
+    if (typeof source === 'string') return source
+    if (source && typeof source === 'object' && 'uri' in source) {
+      const uri = (source as { uri?: unknown }).uri
+      if (typeof uri === 'string') return uri
+    }
+    throw new Error(
+      `@pictor-sdk/video-android: a thumbnail source is not a URI. Normalise host media to { kind: 'uri', uri } first. Received: ${JSON.stringify(source)}`,
+    )
+  }
+
+  return {
+    async request(request: ThumbnailRequest, signal?: AbortLike): Promise<Thumbnail | null> {
+      const key = thumbnailKey(request)
+      const cached = policy.get(request)
+      if (cached !== undefined) {
+        return { image: cached, sourceTimeUs: request.sourceTimeUs, size: { width: 0, height: 0 } }
+      }
+      if (signal?.aborted) return null
+
+      const native = requireNative()
+      policy.begin(request)
+      const token = native.thumbnailRequest(
+        uriOf(request.source),
+        request.sourceTimeUs,
+        request.widthPx,
+      )
+      tokens.set(key, token)
+
+      const stop = () => {
+        native.thumbnailCancel(token)
+        tokens.delete(key)
+        policy.cancel(request)
+      }
+      signal?.addEventListener('abort', stop, { once: true })
+
+      try {
+        // Poll rather than await a bridged Promise: the native side is a token
+        // API precisely so a request can be abandoned, and a Promise that
+        // cannot be cancelled would decode frames nobody will see.
+        for (;;) {
+          if (signal?.aborted) return null
+          const data = native.thumbnailTake(token)
+          if (data !== null && data !== undefined) {
+            tokens.delete(key)
+            const evicted = policy.store(request, `data:image/jpeg;base64,${data}`)
+            // Base64 strings are garbage-collected; eviction is bookkeeping
+            // rather than disposal, and the returned values are ignored on
+            // purpose. A provider handing back native images would dispose here.
+            void evicted
+            return {
+              image: policy.get(request)!,
+              sourceTimeUs: request.sourceTimeUs,
+              size: { width: request.widthPx, height: 0 },
+            }
+          }
+          const error = native.thumbnailError(token)
+          if (error !== null && error !== undefined) {
+            tokens.delete(key)
+            policy.cancel(request)
+            return null
+          }
+          if (!native.thumbnailRunning(token)) {
+            // Neither a result nor an error, and not running: the frame could
+            // not be produced. A source can legitimately have no frame at a
+            // time — past the end of a variable-rate clip, for instance.
+            tokens.delete(key)
+            policy.cancel(request)
+            return null
+          }
+          await new Promise<void>((resolve) => setTimeout(() => resolve(), pollMs))
+        }
+      } finally {
+        signal?.removeEventListener('abort', stop)
+      }
+    },
+
+    releaseSource(source: MediaSource) {
+      policy.evictSource(source)
+      requireNative().thumbnailReleaseSource(uriOf(source))
+    },
+
+    release() {
+      for (const token of tokens.values()) requireNative().thumbnailCancel(token)
+      tokens.clear()
+      policy.clear()
+      requireNative().thumbnailReleaseAll()
+    },
+  }
+}
+
+/** Decode counters, for gates and diagnostics. @experimental */
+export function thumbnailCounters(): {
+  decoded: number
+  cancelled: number
+  failed: number
+  running: number
+  retrievers: number
+} {
+  return requireNative().thumbnailCounters() as {
+    decoded: number
+    cancelled: number
+    failed: number
+    running: number
+    retrievers: number
+  }
+}

package/src/tracePhases.ts

@@ -0,0 +1,217 @@
+import type { TraceEvent } from './previewTrace'
+
+/**
+ * The offset, segmented by the marks a gate put in the run.
+ *
+ * ## Why a whole-run summary is not enough
+ *
+ * `summariseOffsets` answers "how bad did it get", and a gate needs "where".
+ * Measured on a Pixel 7, a run whose worst excursion was 266 ms spent every
+ * moment between its transitions inside ±40 ms: the whole-run worst described
+ * three settling transients and nothing else, and a single number cannot tell
+ * that from a steady 266 ms error. They are not the same defect and they do not
+ * have the same fix.
+ *
+ * So a run is cut at its marks, and each segment is summarised on its own. The
+ * gate verdict is still the run's worst — this localises a failure, it does not
+ * soften one.
+ *
+ * ## Fresh and stale are reported, never traded
+ *
+ * A stale presented frame is what a person actually sees, so its offset is real
+ * and is counted in `worstAbsUs`. But a stale frame's offset grows purely
+ * because audio advanced while the picture did not, which is a different fault
+ * from two clocks disagreeing — so `freshWorstAbsUs` is reported beside it
+ * rather than instead of it. Neither is allowed to stand alone: quoting only
+ * the fresh figure is how a run with a nine-second frozen picture passes a
+ * synchronisation gate.
+ *
+ * @experimental
+ */
+export interface PhaseSummary {
+  /** The mark that opened this segment, or `'start'` before the first one. */
+  label: string
+  index: number
+  /** Samples in the segment, whatever their state. */
+  samples: number
+  /** Samples with both players playing — the only ones an offset means anything for. */
+  playingSamples: number
+  /** Of those, the ones whose presented frame had advanced. */
+  freshPlayingSamples: number
+  stalePlayingSamples: number
+  /** The longest unbroken run of stale samples, in samples. */
+  longestStaleRun: number
+  minUs: number
+  maxUs: number
+  meanUs: number
+  /** Worst absolute offset over every playing sample, stale included. */
+  worstAbsUs: number
+  /** Worst over fresh samples only. Reported beside `worstAbsUs`, never instead. */
+  freshWorstAbsUs: number
+  /** Playing samples outside the tolerance. */
+  overToleranceSamples: number
+  /**
+   * How long the segment took to come inside tolerance and stay there.
+   *
+   * `-1` when it never did, which is the difference between a transient and a
+   * failure that happens to start at a transition. Measured from the segment's
+   * first playing sample, so it is a settling time rather than a wall clock.
+   */
+  settledAfterUs: number
+}
+
+/** @experimental */
+export interface PhaseReport {
+  toleranceUs: number
+  phases: PhaseSummary[]
+  /** The run's worst, over every phase. This is the gate. */
+  worstAbsUs: number
+  freshWorstAbsUs: number
+  overToleranceSamples: number
+  /** Whether every playing sample in the run was inside tolerance. */
+  pass: boolean
+}
+
+/**
+ * The prefix a gate's own marks carry.
+ *
+ * Every mark is recorded as a `mark` event carrying its label, and the trace is
+ * also full of system events — holds, releases, drift corrections, transport
+ * transitions. Cutting on "not a sample" would start a new phase at every one
+ * of those, and cutting on every mark would let an ad-hoc label reshape a gate's
+ * phases. So only marks whose label carries this prefix cut the run.
+ *
+ * @experimental
+ */
+export const PHASE_MARK_PREFIX = 'phase:'
+
+function num(v: unknown): number {
+  return typeof v === 'number' ? v : Number(v)
+}
+
+function empty(label: string, index: number): PhaseSummary {
+  return {
+    label,
+    index,
+    samples: 0,
+    playingSamples: 0,
+    freshPlayingSamples: 0,
+    stalePlayingSamples: 0,
+    longestStaleRun: 0,
+    minUs: 0,
+    maxUs: 0,
+    meanUs: 0,
+    worstAbsUs: 0,
+    freshWorstAbsUs: 0,
+    overToleranceSamples: 0,
+    settledAfterUs: 0,
+  }
+}
+
+/**
+ * Summarise a drained run, cut at its mark events.
+ *
+ * @experimental
+ */
+export function summarisePhases(
+  events: readonly TraceEvent[],
+  toleranceUs: number,
+): PhaseReport {
+  const phases: PhaseSummary[] = []
+  let current = empty('start', 0)
+  // Accumulators kept outside the summary so the published shape stays plain
+  // data — a gate serialises this straight into a log line.
+  let sum = 0
+  let staleRun = 0
+  let firstPlayingNs = 0
+  let lastOverNs = 0
+  let sawPlaying = false
+  let stillOver = false
+
+  const close = () => {
+    current.meanUs = current.playingSamples > 0 ? Math.round(sum / current.playingSamples) : 0
+    /*
+      Settling is measured to the *last* excursion, not the first return.
+
+      A transient that goes out, comes back and goes out again has not settled
+      at the first return, and reporting that would turn the worst case into the
+      best-looking number available. -1 for a phase still outside tolerance at
+      its final sample: that is not a transient at all.
+    */
+    current.settledAfterUs =
+      current.overToleranceSamples === 0
+        ? 0
+        : stillOver
+          ? -1
+          : Math.round((lastOverNs - firstPlayingNs) / 1000)
+    phases.push(current)
+    sum = 0
+    staleRun = 0
+    firstPlayingNs = 0
+    lastOverNs = 0
+    sawPlaying = false
+    stillOver = false
+  }
+
+  for (const e of events) {
+    if (e.type !== 'sample') {
+      const label = e.type === 'mark' ? String(e.v.label ?? '') : ''
+      if (label.startsWith(PHASE_MARK_PREFIX)) {
+        close()
+        current = empty(label.slice(PHASE_MARK_PREFIX.length), phases.length)
+      }
+      continue
+    }
+    current.samples += 1
+    if (e.v.videoPlaying !== true || e.v.audioPlaying !== true) {
+      staleRun = 0
+      continue
+    }
+    const offset = num(e.v.offsetUs)
+    if (!Number.isFinite(offset)) continue
+    current.playingSamples += 1
+    if (!sawPlaying) {
+      sawPlaying = true
+      firstPlayingNs = num(e.atNs)
+    }
+    sum += offset
+    if (current.playingSamples === 1) {
+      current.minUs = offset
+      current.maxUs = offset
+    } else {
+      current.minUs = Math.min(current.minUs, offset)
+      current.maxUs = Math.max(current.maxUs, offset)
+    }
+    const abs = Math.abs(offset)
+    if (abs > current.worstAbsUs) current.worstAbsUs = abs
+    if (abs > toleranceUs) {
+      current.overToleranceSamples += 1
+      lastOverNs = num(e.atNs)
+      stillOver = true
+    } else {
+      stillOver = false
+    }
+    if (e.v.pfFresh === true) {
+      current.freshPlayingSamples += 1
+      if (abs > current.freshWorstAbsUs) current.freshWorstAbsUs = abs
+      staleRun = 0
+    } else {
+      current.stalePlayingSamples += 1
+      staleRun += 1
+      if (staleRun > current.longestStaleRun) current.longestStaleRun = staleRun
+    }
+  }
+  close()
+
+  const worstAbsUs = phases.reduce((w, p) => Math.max(w, p.worstAbsUs), 0)
+  const freshWorstAbsUs = phases.reduce((w, p) => Math.max(w, p.freshWorstAbsUs), 0)
+  const overToleranceSamples = phases.reduce((n, p) => n + p.overToleranceSamples, 0)
+  return {
+    toleranceUs,
+    phases,
+    worstAbsUs,
+    freshWorstAbsUs,
+    overToleranceSamples,
+    pass: overToleranceSamples === 0,
+  }
+}

package/src/useCompositionPlayback.ts

@@ -0,0 +1,327 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  playIntent,
+  playlistOf,
+  projectDuration,
+  type PlayIntent,
+  type UnsupportedSource,
+  type VideoProject,
+} from '@pictor-sdk/video-core'
+import {
+  compositionSpikeSpec,
+  type CompositionSpikeState,
+  spikePause,
+  spikePlay,
+  spikeRelease,
+  spikeSeek,
+  spikeStart,
+  spikeState,
+} from './compositionSpike'
+import { createPlaybackLifecycle, type PlaybackLifecycle } from './playbackLifecycle'
+import type { Media3Playback } from './useMedia3Playback'
+
+/**
+ * The preview, on one clock.
+ *
+ * ## What this replaces
+ *
+ * Two players kept in step: a video player and a separate player for the
+ * prepared audio mix, with a drift check correcting between them. That
+ * architecture was measured to its limit and could not hold synchronisation
+ * across a clip seam — the correction is a seek, a seek costs a decode, and a
+ * decode at the moment of a seam is what the correction was trying to cover.
+ *
+ * A `CompositionPlayer` has one clock, one playback thread and one audio graph.
+ * The prepared mix becomes an audio-only sequence beside the video sequence, so
+ * the two cannot drift: there is nothing to drift against.
+ *
+ * ## What it does not fix
+ *
+ * The clip seam still costs a picture. Media3 tears down the video decoder at
+ * an item boundary and builds another, and for 119 to 168 ms nothing reaches
+ * the renderer while the clock runs on — the audio is continuous and the
+ * picture holds. That behaviour was watched on a device and accepted for v1;
+ * see `docs/research/preview-acceptance.md` for what was accepted and what was
+ * explicitly not.
+ *
+ * ## Why the same contract
+ *
+ * It returns {@link Media3Playback}, unchanged. The editor, the transport and
+ * the gates were all written against it, and swapping the engine underneath is
+ * a smaller and more reviewable change than rewriting every caller to a shape
+ * that would end up equivalent.
+ *
+ * @experimental
+ */
+export interface UseCompositionPlaybackOptions {
+  project: VideoProject
+  /** Timeline time the host wants shown. */
+  playheadUs: number
+  /**
+   * The prepared audio program, from `usePreviewAudio`.
+   *
+   * Null while it is being prepared, after it has failed, and — legitimately —
+   * when the document has no audio at all.
+   *
+   * Those are different situations and the hook has to tell them apart. A
+   * document *with* audio waits: building the composition without its sound
+   * would play a silent preview and gain the music a second later, which is two
+   * timelines to anyone watching. A document *without* audio has nothing to
+   * wait for, and refusing to build would leave the picture dead.
+   */
+  mix: { uri: string; durationUs: number } | null
+  /** Turns a document source into something the player can open. */
+  resolveSource: (source: { kind: string; uri?: string }) => string | null
+  /** @see UseMedia3PlaybackOptions.surfaceGeneration */
+  surfaceGeneration?: number
+  enabled?: boolean
+}
+
+/** How often the composition's state is read, in milliseconds. */
+const POLL_MS = 100
+
+/**
+ * What a composition knows about itself.
+ *
+ * Deliberately not `Media3State`. That type is the shape the video player's
+ * native state comes back in — forty fields about queue depth, anchors, native
+ * heap and window indices — and a composition has none of them. Synthesising
+ * one would be inventing forty numbers to satisfy a type, and a reader would
+ * have no way to tell the invented ones from the measured ones.
+ *
+ * @experimental
+ */
+export interface CompositionPlaybackState {
+  playing: boolean
+  ready: boolean
+  buffering: boolean
+  ended: boolean
+  released: boolean
+  /** Project time, which for a single composition is the only time there is. */
+  positionUs: number
+  durationUs: number
+  /** The presentation size, or 0 while nothing has been measured. */
+  width: number
+  height: number
+  error: string | null
+}
+
+function composedState(snapshot: CompositionSpikeState): CompositionPlaybackState {
+  const playbackState = snapshot.playbackState ?? 1
+  return {
+    playing: snapshot.playing === true,
+    ready: playbackState === 3,
+    buffering: playbackState === 2,
+    ended: playbackState === 4,
+    // `released` counts releases; a positive count with nothing attached is the
+    // released state this means.
+    released: snapshot.attached !== true && (snapshot.released ?? 0) > 0,
+    positionUs: snapshot.positionUs ?? 0,
+    durationUs: snapshot.durationUs ?? 0,
+    /*
+      Zero, and honestly so.
+
+      A composition renders into the presentation surface at the size the host
+      gave it; it does not report a decoded size the way the video player did.
+      The host already knows the size it asked for, and a fabricated number here
+      would be worse than none.
+    */
+    width: 0,
+    height: 0,
+    error: snapshot.error ?? null,
+  }
+}
+
+/** @experimental */
+export type CompositionPlayback = Omit<Media3Playback, 'state'> & {
+  state: CompositionPlaybackState | null
+}
+
+/** @experimental */
+export function useCompositionPlayback(
+  options: UseCompositionPlaybackOptions,
+): CompositionPlayback {
+  const { project, mix, enabled = true } = options
+  const surfaceGeneration = options.surfaceGeneration ?? 0
+  const resolveSource = useRef(options.resolveSource)
+  resolveSource.current = options.resolveSource
+
+  const [state, setState] = useState<CompositionPlaybackState | null>(null)
+  const [playing, setPlaying] = useState(false)
+  const playheadRef = useRef(options.playheadUs)
+  playheadRef.current = options.playheadUs
+
+  const playlist = useMemo(() => playlistOf(project), [project])
+  const items = playlist.items
+  const durationUs = useMemo(() => projectDuration(project), [project])
+
+  /*
+    What the composition is made of, as a string.
+
+    Every edit makes a new project object and most of them — a selection, a
+    playhead move — change nothing the player should be playing. The mix is part
+    of it: a rebuilt mix is a different composition even when the video is
+    identical, and starting the old one would play the sound the user just
+    changed.
+  */
+  // A document with audio has a mix to wait for; one without does not.
+  const needsMix = project.audio.length > 0
+  const signature = useMemo(() => {
+    if (needsMix && mix === null) return ''
+    const parts = items.map(
+      (i) => `${JSON.stringify(i.source)}|${i.startUs}|${i.endUs}|${i.speed}|${i.muted}`,
+    )
+    const sound = mix === null ? 'silent' : `${mix.uri}:${mix.durationUs}`
+    return `${parts.join(';')}#${playlist.unsupported.length}@${sound}`
+  }, [items, playlist.unsupported.length, mix, needsMix])
+
+  const [unsupported, setUnsupported] = useState<readonly UnsupportedSource[]>([])
+  const lastSeekRef = useRef<Media3Playback['lastSeek']>(null)
+
+  /*
+    This screen's ownership, unchanged from the path it replaces.
+
+    The player outlives any screen: leaving the editor while playing left the
+    sound running, and backgrounding did the same. One lifecycle per hook
+    instance, and a screen mounted later starts from nothing.
+  */
+  const lifecycleRef = useRef<PlaybackLifecycle | null>(null)
+  if (lifecycleRef.current === null) {
+    lifecycleRef.current = createPlaybackLifecycle({
+      pause: () => void spikePause(),
+      release: () => void spikeRelease(),
+    })
+  }
+  const lifecycle = lifecycleRef.current
+  const [lifecycleEpoch, setLifecycleEpoch] = useState(lifecycle.epoch)
+
+  const loaded = useRef('')
+  useEffect(() => {
+    if (!enabled || signature === '') return
+    if (surfaceGeneration === 0) return
+    if (loaded.current === signature) return
+    /*
+      An empty URI is a composition with no audio sequence, which the adapter
+      builds and plays. It is not a missing mix — that case never reaches here,
+      because the signature is empty until one exists.
+    */
+    const { spec, unsupported: refused } = compositionSpikeSpec(
+      project,
+      mix ?? { uri: '', durationUs: 0 },
+      (s) => resolveSource.current(s),
+    )
+    setUnsupported(
+      refused.map((reason) => ({ clipId: reason.split(':')[0] ?? '', reason }) as UnsupportedSource),
+    )
+    if (spec.items.length === 0) return
+    const started = spikeStart(spec) as { ok?: boolean }
+    // A refusal is not a load. Recording it as one is what left an editor
+    // waiting for an edit the person had already made.
+    if (started.ok === true) loaded.current = signature
+  }, [enabled, signature, surfaceGeneration, project, mix])
+
+  useEffect(() => {
+    return () => {
+      lifecycle.teardown('unmount')
+    }
+  }, [lifecycle])
+
+  useEffect(() => {
+    if (!enabled) return
+    // Captured now and checked on every tick: an interval is not cleared the
+    // instant a screen goes, and a poll landing afterwards must not write into
+    // one that is no longer there.
+    const epoch = lifecycle.epoch
+    const id = setInterval(() => {
+      if (!lifecycle.accepts(epoch)) return
+      const next = composedState(spikeState())
+      /*
+        Only a change of meaning re-renders.
+
+        Replacing the state object every tick re-renders the editor ten times a
+        second to move a line, and at ten hertz the line moves visibly in steps.
+        A host that wants the position drives it from `positionUs()`.
+      */
+      setState((previous: CompositionPlaybackState | null) =>
+        previous !== null &&
+        previous.playing === next.playing &&
+        previous.ready === next.ready &&
+        previous.buffering === next.buffering &&
+        previous.ended === next.ended &&
+        previous.released === next.released &&
+        previous.error === next.error
+          ? previous
+          : next,
+      )
+      setPlaying(next.playing)
+    }, POLL_MS)
+    return () => clearInterval(id)
+  }, [enabled, lifecycle, lifecycleEpoch])
+
+  const seek = useCallback((timeUs: number) => {
+    const at = Math.max(0, Math.round(timeUs))
+    lastSeekRef.current = { globalUs: at, windowIndex: 0, localUs: at }
+    spikeSeek(at)
+  }, [])
+
+  const positionUs = useCallback((): number | null => {
+    const snapshot = spikeState()
+    if (!snapshot.attached) return null
+    const at = snapshot.positionUs
+    return typeof at === 'number' ? at : null
+  }, [])
+
+  const play = useCallback((): PlayIntent => {
+    const snapshot = spikeState()
+    const intent = playIntent({
+      positionUs: typeof snapshot.positionUs === 'number' ? snapshot.positionUs : 0,
+      durationUs,
+      playbackState: typeof snapshot.playbackState === 'number' ? snapshot.playbackState : 1,
+      ended: snapshot.playbackState === 4,
+    })
+    if (intent.seekToUs !== null) seek(intent.seekToUs)
+    if (!intent.play) return intent
+    // Refused once the screen has given the player back: a late press from a
+    // control that has not unmounted yet must not start a released player.
+    if (lifecycle.released) return intent
+    spikePlay()
+    setPlaying(true)
+    return intent
+  }, [durationUs, lifecycle, seek])
+
+  useEffect(() => {
+    setLifecycleEpoch(lifecycle.epoch)
+  }, [lifecycle, surfaceGeneration])
+
+  return {
+    playing,
+    play,
+    get lastSeek() {
+      return lastSeekRef.current
+    },
+    positionUs,
+    effectiveRate: 1,
+    pause: useCallback(() => {
+      spikePause()
+      setPlaying(false)
+    }, []),
+    /*
+      Rate is the document's, not the transport's.
+
+      Clip speed is compiled into the composition and into the mix, and a
+      preview-wide rate on top of it would be a second speed nobody asked for.
+      The contract keeps the method; this path has nothing to do with it.
+    */
+    setRate: useCallback(() => {}, []),
+    seek,
+    state,
+    items,
+    unsupported,
+    divergenceUs: 0,
+    lifecycle,
+    // One player, so there is no half to stall: the recovery this reported was
+    // the video player running while the audio player had stopped, or the
+    // reverse. @see docs/research/preview-acceptance.md
+    stall: null,
+  }
+}