MediaFrame

Recorded media

Supply a media element and the state confirmed by your application. This example uses a local, silent training recording. Its adapter waits for decoding before supplying a capture time.

<MediaFrame
  label="Pump station recording"
  state={frame.state}
  capturedAt={frame.capturedAt}
  source="Camera 12"
  retained={frame.retained}
  detail={frame.detail}
  actions={
    <Button onClick={captureFrame} disabled={!canCapture}>
      Capture frame
    </Button>
  }
>
  {media}
</MediaFrame>

capturedAt is the displayed frame's capture time in epoch milliseconds. Keep the requested review position, confirmed frame time, receipt time and application reference time separate. MediaFrame displays the supplied values without advancing a clock or inferring freshness.

States

Every state has a readable text badge: live, delayed, paused, recorded, reconnecting, and unavailable. These examples show the display contract independently of a connection.

Set retained when old imagery remains visible while waiting for a new frame. The previous capture time stays visible beside an explicit retained-frame label. Reconnecting and unavailable states always disclose that a current frame is unavailable, including when children still contain old imagery.

capturedAt={null} and invalid dates display “Capture time unknown.” A fractional millisecond, such as a video's mediaTime, is a valid capture time. A supplied latencyMs of null, a negative value or a nonfinite number displays “Latency unknown.” Zero latency is valid. Omitting latency hides that field.

Media and actions

The media surface defaults to 16:9. aspectRatio is width divided by height; invalid values use 16:9. Direct image, video and canvas children fit within that surface without cropping. A custom media wrapper owns its own sizing.

The application owns decoding, network connections, play/pause, seeking, error handling, snapshot capture and source changes. It also supplies accessible media descriptions and captions where needed. actions accepts existing controls, including their disabled states and permission explanations. A capture action should report success only after a current decoded frame was captured successfully.

The FacilityMonitoring recipe provides a native video adapter. It reports requested position and confirmed frame time separately, ignores events from retired sources and rejects snapshots while loading, seeking, buffering, ended, errored or outside its 0.25-second synchronization tolerance. That tolerance is an example integration decision.

Props

The forwarded ref targets the root div. Native div attributes are supported, and the visible label names its region. MediaFrame has no disabled or asChild mode: supplied actions own their interaction and the named media region keeps its structure.

Accessibility

• The visible label names the media region.
• All states, retained imagery, unavailable frames and unknown values have text descriptions.
• Capture times show the date and time to the second in UTC (2026-10-02 14:03:09 UTC, design call DC-4); the time element keeps the exact instant, milliseconds included, in its machine-readable dateTime.
• Latency keeps its exact value, groups its digits in the application's locale and keeps ms with the last digits.
• Supplied actions retain their own keyboard and focus behavior. Metadata updates add no focus targets or automatic announcements.
• The application supplies media alternatives, captions and any appropriate status announcements.

Manifest entry

<MediaFrame label="Pump camera" state="recorded" capturedAt={confirmedFrameTime} source="CAM-12" detail="Training footage"><video muted playsInline src={recordingUrl} /></MediaFrame>

{
  "description": "Named media surface with supplied freshness state, capture time and retained-frame disclosure.",
  "props": {
    "label": {
      "type": "string",
      "required": true
    },
    "state": {
      "type": "enum",
      "values": [
        "live",
        "delayed",
        "paused",
        "recorded",
        "reconnecting",
        "unavailable"
      ],
      "required": true,
      "description": "Caller-supplied state. Reconnecting and unavailable always disclose that a current frame is unavailable."
    },
    "capturedAt": {
      "type": "number",
      "required": true,
      "description": "Actual supplied frame capture time in epoch milliseconds, or null (fractional milliseconds allowed). Shown as YYYY-MM-DD HH:MM:SS UTC; the time element keeps the exact ISO instant in dateTime. Invalid dates and null display an unknown capture time."
    },
    "source": {
      "type": "string",
      "description": "Readable source identity; does not initiate a connection."
    },
    "latencyMs": {
      "type": "number",
      "description": "Supplied nonnegative latency in milliseconds, or null for unknown. Invalid values display unknown; omitted values are hidden."
    },
    "retained": {
      "type": "boolean",
      "default": false,
      "description": "Explicitly labels imagery as a retained frame that is not current."
    },
    "detail": {
      "type": "string",
      "description": "Persistent application explanation of the media state."
    },
    "aspectRatio": {
      "type": "number",
      "default": 1.7777777777777777,
      "description": "Media width divided by height; defaults to 16/9. Nonpositive or nonfinite ratios fall back to 16/9."
    },
    "children": {
      "type": "node",
      "description": "Application-owned media, image, canvas or fallback. Direct media children fit within the aspect-ratio surface without cropping."
    },
    "actions": {
      "type": "node",
      "description": "Application-supplied accessible actions. Availability, permissions and outcomes remain with the caller."
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "PlaybackControls",
    "Button",
    "AttachmentPreview",
    "Inspector"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<MediaFrame label=\"Pump camera\" state=\"recorded\" capturedAt={confirmedFrameTime} source=\"CAM-12\" detail=\"Training footage\"><video muted playsInline src={recordingUrl} /></MediaFrame>"
}