ARIA labels on custom video and audio player controls
If your media player is custom-built, every button needs an accessible name.
What this signal tests
We detect whether your video or audio uses native HTML controls (the browser's built-in play/pause/volume UI) or a custom JavaScript player. For custom players, we check that every interactive control has a role attribute (such as button or slider) plus an accessible name via aria-label or aria-labelledby. Sliders also need aria-valuenow, aria-valuemin, and aria-valuemax. Native players pass automatically.
Why it matters for your visibility in AI
Custom video players often render as unlabeled <div> or <svg> elements wired up with JavaScript click handlers. To a screen reader, that's silence; to an accessibility-tree crawler, that's a hole in the page. Many AI agents now interact with web pages through the accessibility tree (the same API screen readers use), which means an unlabeled play button is literally invisible to them. They cannot trigger it, cannot caption it, cannot describe it in a transcript of the page. For agents that drive headless browsers (ChatGPT Atlas, Perplexity Comet, Claude for Chrome, Operator), unlabeled media controls cause tool-call failures: the agent can see something is there but cannot identify what action it triggers. Native <video controls> sidesteps the issue entirely because the browser provides accessible names. If you must ship custom controls, every button needs aria-label.
Pass criteria at a glance
| Criterion | Passes when |
|---|---|
| Native controls used OR >=95% custom control elements have accessible names. |
How we test it
We look for custom player indicators: <video> elements without the controls attribute surrounded by clickable elements, or known custom-player class names like vjs-, plyr-, jwplayer. For each interactive control element inside such a player, we check for role attribute and accessible name. We pass if either the player uses native controls or 95 percent of custom controls have accessible names.
Show technical detection method
Detect custom player (video without controls, surrounding clickable elements, known player class names); for each interactive control require role + accessible name.
If your site fails: how to fix it
- Prefer native <video controls> and <audio controls> wherever you can. The browser provides accessible names, keyboard support, and platform-consistent UI for free.
- If you must use a custom player, add role="button" plus aria-label to every clickable control: <button aria-label="Play"><svg>...</svg></button>. Update aria-label on state change (Play becomes Pause).
- For sliders (progress bar, volume), use role="slider" with aria-valuenow, aria-valuemin, aria-valuemax, and aria-label or aria-valuetext for context.
- If you use Plyr, Video.js, or JW Player, make sure you are on a recent version. All three ship accessible controls by default in modern releases.
- Test with a screen reader (VoiceOver on Mac, NVDA on Windows). If you cannot operate the player by keyboard alone with announced labels, AI accessibility-tree agents will not be able to either.
Quick facts
| Maturity | ESTABLISHED |
|---|---|
| Weight | low |
| Category | Multimodal |
Primary sources
Related signals
Frequently asked questions
Do AI agents actually use the accessibility tree?
Increasingly yes. Anthropic's computer use, OpenAI's Operator, and several agent frameworks rely on the accessibility tree (rather than pixel-level vision) as the primary way to identify and interact with UI controls. Unlabeled buttons are unreachable to them, even though humans can see them.
What is wrong with native browser controls? My design team wants custom styling.
Modern native controls accept significant CSS customisation via ::-webkit-media-controls and -moz-* pseudo-elements. You can often achieve the design without giving up accessibility. Where native is impossible, replicate the accessibility surface exactly: roles, labels, keyboard handlers, focus indicators.
Does this matter for autoplaying background video with no controls?
Less so, because there are no controls for an agent to find. But you should still mark such a video as decorative (aria-hidden="true") so it does not confuse the accessibility tree. Background video is often a decorative choice that doesn't need to be exposed to agents.
Run your own scan
Run a free scan and see how your site grades across all 155 AI-readiness signals.