Streaming Detections

Use an appendable detection source when predictions arrive after playback has started. This fits uploaded videos, live inference, webcam sessions, and server-sent inference results.

import {
  createMediaSession,
  DetectionFrameRetentionMode,
  type DetectionFrame,
} from "supervision";

const session = await createMediaSession({
  container,
  media: file,
  detections: {
    appendable: {
      datasetId: "upload-1",
      retention: {
        mode: DetectionFrameRetentionMode.PersistAll,
      },
    },
    playbackGate: {
      enabled: true,
      requiredAheadSeconds: 2,
    },
  },
  normalize: { stream: true },
  renderer: {
    autoPlay: true,
  },
});

for await (const frames of streamInferenceFrames(file)) {
  await session.appendDetectionFrames(frames);
}
Copy

Appending Results

Append semantic frames in batches. The batch can contain one frame or many frames:

async function appendInferenceResult(frame: DetectionFrame) {
  await session.appendDetectionFrames([frame]);
}
Copy

Appending detections outside the current hot window does not force the renderer to reload the active window. The session tracks source ranges and refreshes when the relevant playback range changes.

Retention Modes

For finite files, use PersistAll so seeking and replay do not require recomputing predictions.

For long-running streams, use a rolling retention window:

retention: {
  mode: DetectionFrameRetentionMode.PersistWindow,
  windowSeconds: 300,
}
Copy

Use MemoryOnly for fully ephemeral streams:

retention: {
  mode: DetectionFrameRetentionMode.MemoryOnly,
  windowSeconds: 60,
}
Copy

Loading State

Subscribe to session state to show buffering or processing UI:

session.subscribe((state) => {
  playButton.disabled = state.playbackBlocked;

  for (const activity of state.activities) {
    console.log(activity.kind, activity.label, activity.progress);
  }
});
Copy

playbackBlocked means playback should wait. presentationBlocked means the visual frame may still be preparing even if playback can continue.