Using video headers in WordPress

Following the trend of using large videos as a design element, WordPress added support for video headers in version 4.7. Also the new Twenty Seventeen theme was released to show this feature.

The use of video has been part of the some projects I have done. With HTML5 video became easy to integrate. Except it didn't. To play video reliably there are a lot of factors that brake video playback. So here are some aspects to take into account when using a video header in WordPress.

Use the right video format

WordPress supports two video formats: MP4 and MOV.

Only use MP4, because is it supported by almost all systems. MOV is the Apple QuickTime movie format. This is supported on all Apple devices. On other platforms your mileage will vary. So you cannot rely on it.

In the past, MP4 was not supported by all browsers. This is no longer the case. Some Linux user may experience issues (they have to install the right Gstreamer plugin). But you have to use the right codecs: H264 for video and AAC for audio. Other codecs can cause problems.

I recommend HandBrake to convert videos into the correct format. It is free and available for Windows, Mac and Linux. HandBrake will generate a file with a m4v extension. You can just rename it to mp4. It is a convention HandBrake uses for MP4 Video, but it is the same format.

Use the right size

WordPress only allows one file to be used as a video. So you cannot use different resolutions for different devices. You will have to decide which resolution you want to use. Of course, the higher the resolution (thus the quality), the larger the file size will get.

I recommend 960 by 540 pixels.

In HandBrake this is the "iPhone & iPod Touch" preset. The "iPad" preset uses a resolution of 1280 by 720 pixels, which is also a good option. The "Regular" presets use 1920 by 1080 pixels, but older systems may be unable to play these resolutions. These different resolutions are the same for "AppleTV" presets (generation 1, 2, 3). In projects I have used HD videos (1280x720), but some visitors started to complain that videos took too long to start and didn't play smoothly. This can be a problem for people in rural areas that have limited access to high bandwidth connections.

The Twenty Seventeen theme recommends a resolution of 2000 by 1200 pixels, which is a bit too high for my taste. In HandBrake you can lower the video quality by setting the RF value higher to get a smaller file size. Or just use a lower resolution. WordPress has a upload limit of 8MB for videos.

Set video quality

WordPress actually only shows videos to devices with a screen width of 900 pixels or higher. Mobile devices will generally get a header image and visitors on desktop/laptop a video. This leads to the situation that for example an iPad will load an image in portrait mode and a video in landscape mode, because the resolution is 1024 by 768 pixels. Retina devices like the iPad 3/4 have a physical screen size of 2048 by 1536 pixels, but CSS and JavaScript will still use 1024 by 768 pixels as the screen resolution.

You can change the video settings by using a filter if you want to prevent this. Of course, the resolution is not a 100% reliable way to detect a device category. For example, the iPad Pro is a tablet, but it has a higher resolution than most laptops. Visit to see what I mean.

function my_video_settings( $settings ) {
  $settings['minWidth']  = 1280;
  $settings['minHeight'] = 720;
  return $settings;
add_filter( 'header_video_settings', 'my_video_settings' );


WordPress will try to automatically start the video. But this will not always work. Therefor a play/pause button is shown. Desktop PC/Laptops do support autoplay. On mobile devices and tablets it depends. iOS 10 supports autoplay, but iOS 9 not. Chrome 53 on Android also supports autoplay. But both platforms require the video to be muted.

Silence is golden

If you use a silent video, you should also remove the audio, or else you are just wasting bandwidth. In HandBrake you can remove the audio stream.

Remove audio stream from video

You can also do this on the command line with FFmpeg.

ffmpeg -i input.mp4 -c:v copy -an -movflags faststart output.mp4

If you can't be bothered with getting the video settings right, you also can use YouTube. It is supported out of the box.

Of course, just because you can use video headers in WordPress, does not mean you have to.