Preview brand Custom

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.

Beta

Show code
astro
---
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 embed item, 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

KeyWhat it does
TabThe player, its play button, then each control in the bar once it has played.
Space or KPlay and pause.
J and L, or Left and RightBack and forward 10 seconds.
MSound off and on.
FFull screen.
Home, End, 0 to 9The 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

CriterionLevelHow this meets it
2.1.1 KeyboardAEvery control by keyboard, and keys for the common ones.
1.4.2 Audio ControlANothing plays sound by itself; mute is one key.
2.2.2 Pause, Stop, HideAA 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)AABar buttons 38px; the play button 68px.
2.4.7 Focus VisibleAAA ring on the player and on each control.
4.1.2 Name, Role, ValueANames that follow the state; loop is a pressed button.
4.1.3 Status MessagesAAA skip is said without moving the focus.
2.3.3 Animation from InteractionsAAAWith 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

CheckHowResult
Automated (axe-core)WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in darkPassed
Nothing found, light or dark
Narrow screenNo sideways scrolling at 320px wide (WCAG 1.4.10)Passed
No sideways scrolling
Keyboard and what the browser reportsReal key presses on the live example, and the role, name and state given to assistive technologyPassed
16 of 16 checks pass
On paperSomnia’s print check: no overlaps, stranded headings or controls on the pagePassed
No faults on 6 sheets
Screen readerListened to by a person, in VoiceOver and NVDANot 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

WhereFor
Headland YachtingA yacht’s films, in its gallery’s viewer.
Staging sitesThe Media library’s videos.
These docsThe example on this page.

What we saw, and what changed

WhenWhat we sawWhat 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

What we don't know yet

  • No captions track.
  • How much of a clip people watch is not counted.