I am giving H5P a link to some media file – but it doesn’t work. Why?

Are you really giving H5P a link to some media file? The emphasis is on file here. But let’s roll back a little.

When you insert media into H5P content, you often have two options at least: You can upload a file or paste a URL to some resource. The latter is what we are dealing with here. That URL needs to point to a media file directly. A URL to a page that merely hosts the medium or returns the medium for download without revealing the real source are not enough.

H5P editor showing the audio upload widget. It asks to upload an audio file or to enter a URL to the audio source

These will, for instance, not work:

URLs that point to the file directly will work. They usually end with the file extension of the medium, e.g. .mp4 for a video. Often sites such as Google Drive or YouTube deliberately do not reveal the direct link to the files, but if you’re lucky, the site that you’re using for hosting the medium does.

Need an example? Have a closer look at the PeerTube instance that I mentioned above. It allows you to retrieve a download link (https://ebildungslabor.video/download/streaming-playlists/hls/videos/2a4b23c5-692a-4194-86fe-347448d690c2-1080-fragmented.mp4), that link ends on .mp4, and you can use it in Interactive Video. You will need to check the respective hosting site for such an option.


There were at least two lies in my text above. Or simplifications. Let’s have a look at these.

Simplification #1: URLs that point to the file directly will work

This is not always true. How could it be any other way? One reason that this may not work is that H5P limits the use of media types to certain extensions. By default, those are:

  • audio: .ogg, .mp3, .m4a, and .wav
  • video: .webm and .mp4

On top of that, even if H5P accepts a file type, H5P doesn’t play media itself. Your browser does. Or the browser of other users. And unfortunately, some browsers can handle one format while others can’t. A common problem are videos in WebM format. While e.g. Chrome, its relatives Chromium and Edge and Opera, and also Firefox handle WebM just fine, Safari had (and some versions still have) trouble with it. But there’s nothing that H5P could do here.

Oh, and of course, the server that hosts the medium may simply be down or the file has been deleted, or the server imposes other restrictions, or …

Simplification #2: That URL needs to point to a media file directly

There are exceptions to that rule. Of course. You can throw a YouTube link like https://www.youtube.com/watch?v=zqLEO5tIuYs at H5P and it will work just fine. Why is that? The URL doesn’t end with .mp4 or .webm!

That works, because on the one hand YouTube offers an interface to access and control the video without revealing the direct link to the file, and on the other hand H5P implements a handler for that interface. It’s YouTube hosting and playing the video, but H5P can embed the footage and call “play” or “pause” and so on.

The same concept currently works for videos hosted on Panopto or Vimeo. And in theory, one could even create (and maintain) more handlers for more services if they offer a feasible API, but that’s something someone needs to fine the time/money for …