Video player
Plays a clip someone chose to watch. One play button on the poster; the controls arrive when it plays. The gallery's viewer uses it for films.
Show code
---
import VideoPlayer from '@somnia/core/components/VideoPlayer.astro';
---
<VideoPlayer src="/about/md-home.mp4" poster="/about/md-home-poster.jpg" title="At work in the studio" /> When to use it
- A clip that shows something: a walk through, a yacht under way, a product in use.
- A film in a gallery, beside its photographs.
Use something else when:
- It is atmosphere behind a heading: a video hero, silent, with a pause button.
- The film lives on another site: the gallery's
embeditem, which loads that site's own player only when its slide is shown.
How it works
- Before it plays: the poster, one play button in the middle, and the clip's length in the corner. Nothing else to read or reach.
- Once it has played: a bar along the bottom with play, back and forward 10 seconds, the time, a scrubber, speed (1×, 1.25×, 1.5×, 2×, 0.5×), loop, sound, picture in picture (where the browser has it) and full screen. It fades while the clip plays and the pointer is still, and comes back when the pointer moves or a control has the focus.
- Click or tap the picture to play or pause. Double-click the left or right third to skip 10 seconds, the middle third for full screen.
- Keys, when the player has the focus: Space or K to play and pause, J and L or the arrows to skip, M for sound, F for full screen, Home and End, 0 to 9 to jump to that tenth.
- Only one player plays at a time: starting one pauses the others.
- On phones the bar drops speed, loop and picture in picture, to leave room for the rest.
Autoplay
In the gallery's viewer a clip starts, muted, when its slide is shown, unless the visitor prefers reduced motion or is saving data. Sound is always the visitor's choice. On a page, nothing plays until play is pressed.
Do and don't
Do
- Give it a poster: a frame that says what the clip is
- Give it a title, which names the player and its play button
- If people speak in it, burn the captions into the picture for now (see below)
Don't
- Start a clip with sound
- Put the only copy of an instruction in a video
- Leave the poster out: the frame is then whatever the clip opens on, often black
Accessibility
What it does for you
- The player is a group named "Video:" and its title, with its keys; the play button is named "Play" and the title.
- Before it plays there is one button. The bar isn’t there to be reached until the first play.
- Every control is a button with a name that says what it does now: Play becomes Pause, Mute becomes "Turn sound on"; loop says whether it is on.
- The scrubber is a slider that says the time, "0:10 of 0:21", and takes the arrow keys.
- A skip is said: "Forward 10 seconds, 0:10".
- The bar fades only while the clip plays and nothing in it has the focus.
- Nothing starts with sound. Autoplay, where asked for, is muted, and never with reduced motion or data saving.
What you need to do
- A title, which names the player.
- A poster.
- If anyone speaks in the clip, captions. The player can’t show a captions track yet (see below), so burn them into the picture or put a transcript beside it.
- If the picture carries meaning the sound doesn’t, say it in words on the page.
Keyboard
| Key | What it does |
|---|---|
| Tab | The player, its play button, then each control in the bar once it has played. |
| Space or K | Play and pause. |
| J and L, or Left and Right | Back and forward 10 seconds. |
| M | Sound off and on. |
| F | Full screen. |
| Home, End, 0 to 9 | The start, the end, that tenth of the clip. |
What a screen reader is told
- "Video: At work in the studio", with its keys, as a group.
- "Play At work in the studio, button".
- Each control by what a press will do.
- The position as a time when the scrubber has the focus.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 2.1.1 Keyboard | A | Every control by keyboard, and keys for the common ones. |
| 1.4.2 Audio Control | A | Nothing plays sound by itself; mute is one key. |
| 2.2.2 Pause, Stop, Hide | A | A clip on a page doesn’t start until asked. In the viewer it starts muted and pauses with one key. |
| 2.5.8 Target Size (Minimum) | AA | Bar buttons 38px; the play button 68px. |
| 2.4.7 Focus Visible | AA | A ring on the player and on each control. |
| 4.1.2 Name, Role, Value | A | Names that follow the state; loop is a pressed button. |
| 4.1.3 Status Messages | AA | A skip is said without moving the focus. |
| 2.3.3 Animation from Interactions | AAA | With reduced motion the skip flash and the button’s growth are off. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 16 of 16 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 16 checks made with the keyboard, on the example at the top of this page:
- Passed The player is a group named "Video:" and its title; its play button is named "Play" and the title
- Passed Nothing plays until asked
- Passed Before it plays, Tab reaches the player and its play button and nothing else in it
- Passed Before it plays the bar is not shown, and the clip’s length is
- Passed Enter on the play button plays the clip; the bar arrives and the focus moves to the player
- Passed Space and K play and pause
- Passed L and J skip forward and back 10 seconds, and say so
- Passed M turns the sound off and on, and the button’s name follows
- Passed 5 jumps to halfway and Home to the start
- Passed Once it has played, Tab goes through the bar: play, back, forward, the scrubber, speed, loop, sound, then full screen
- Passed The scrubber is a slider that says the time, and Right moves the clip on
- Passed Loop says whether it is on, and speed says its setting
- Passed The bar stays while one of its controls has the focus, though the clip plays
- Passed The play button is 68px with its mark in the middle; the bar’s buttons are at least 24px
- Passed Keyboard focus shows a ring on the player and on its play button
- Passed With reduced motion the play button doesn’t grow and a skip doesn’t flash
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- No captions. The player has no way to show a captions track (WCAG 1.2.2). Until it has, a clip with speech needs its captions in the picture. The clips in use have no speech.
- The single-letter keys work only while the player has the focus, so they don’t fire while someone types elsewhere. Not tried with speech input.
- The bar is white on a dark gradient over the picture; over a white frame at the very foot of a clip its contrast has not been measured.
Evidence
Where it's used
| Where | For |
|---|---|
| Headland Yachting | A yacht’s films, in its gallery’s viewer. |
| Staging sites | The Media library’s videos. |
| These docs | The example on this page. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| The play button was an 88px see-through ring whose mark sat right of centre, and it shared the frame with a full bar of controls before anything had played. | A 68px white disc with its mark centred; the bar arrives with the first play, and the clip’s length shows in the corner (1.88.0). | |
| With no poster the example opened on a black frame. | The example has a poster, and the page says to give one (1.88.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- Understanding WCAG 2.2: Audio Control: Sound that plays by itself for more than three seconds must be stoppable; better that it doesn’t start.
What we don't know yet
- No captions track.
- How much of a clip people watch is not counted.