Media Controls Overview — Media Controls

The 7 Media and Advanced Control Types

video

Embed a video player with native HTML5 controls. Supports MP4, WebM, and external streaming URLs.

audio

Inline audio player with play/pause, volume, and seek. Supports MP3, WAV, OGG.

iframe-viewer

Embed any external URL inside a sandboxed iframe. Configurable sandbox policy.

pdf-viewer

Render a PDF document inline using the browser's native PDF engine.

variable-inspector

Developer tool — displays all current form values and context as formatted JSON. Hide in production.

article

Long-form content block with full markdown support. Ideal for help text, policies, and instructions.

mermaid-diagram

Renders Mermaid.js markup as SVG. Supports flowcharts, sequence diagrams, Gantt charts, and more.

Common Properties

Property	Type	Description
`id`	string	Unique control identifier
`type`	string	Control type name (see above)
`label`	string	Optional label rendered above the control
`width`	string	`full`, `half`, `third`, `quarter`, `two-thirds`
`modeVisibilitySettings`	object	Per-mode visibility flags
`visibilityRule`	string	Expression-based conditional visibility
`settings`	object	Control-specific configuration

Security Considerations

Media controls embed external content inside your form. Apply the least-privilege principle:

Control	Key Security Setting	Recommendation
iframe-viewer	`sandbox`	Always specify the minimum required sandbox permissions. Default: scripts and forms blocked.
pdf-viewer	`src`	Only load PDFs from trusted origins. Avoid user-supplied URLs without server-side validation.
video / audio	`src`	Use signed URLs for private media. Never expose raw S3 URLs in production.
article	Markdown content	Content is sanitised before render. Do not bypass sanitisation with raw HTML in markdown.
mermaid-diagram	`content`	Mermaid markup is safe — it renders SVG with no script execution.

Performance Considerations

Embedding media increases form load time. Follow these guidelines:

Use preload: "none" for video and audio unless autoplay is required.
Prefer lazy-loaded iframes (set loading: "lazy") for below-the-fold embeds.
PDF viewer loads the entire PDF file on mount — use pagination for large documents.
Mermaid diagrams with very large graphs (100+ nodes) may impact render performance.
Use modeVisibilitySettings to hide heavy controls in modes where they are not needed.

Developer-Only Controls

The variable-inspector control is intended for development and debugging only. Always configure it to be hidden in production modes:

{
  "id": "debug-inspector",
  "type": "variable-inspector",
  "modeVisibilitySettings": {
    "edit":    false,
    "view":    false,
    "admin":   false,
    "preview": false,
    "design":  true
  }
}

Next: Video Player →