Tuesday, May 14, 2013

Linking to external video (and audio)* in EPUB3

I forget when I first saw the option in the iBooks settings panel, but I know it was a long time ago. Enticingly, it said Online Content, and had an On/Off switch. And underneath was a short explanation: “Allow books to access publisher's content from the Internet.”

EPUB used to be a strictly closed affair; all of its content had to live within the EPUB package itself. But in EPUB3 an exception was made to allow remote access for audio and video elements only. These two things together could only mean one thing: that remote video was now possible in an ebook, at least on the iPad.

Why is it important to be able to access remote video and audio files? For starters, keeping your audio and video out of the EPUB can make your EPUB a lot smaller and much more agile. It will download much more quickly. On the other hand, in order to see that video, your reader is still going to have to download it at some point, and they might even do it multiple times, which can be a drag on your server.

Another reason to host video or audio remotely is to give access to multiple formats of the file. EPUB3 has the capability of looking through a series of links and only using the one that works best in a given ereader. Including multiple versions of a video file in an EPUB file would result in unnecessary bloat. (Of course, this is a bit of a moot point in a world in which video and audio in EPUB mostly works in iBooks, but that is changing with Readium, and surely with newer ereaders. The fact that there is no agreed upon codec for video is also an important factor.)

Finally, if the video is hosted remotely, that means you can update it at any time. Note, however, that you must be careful to maintain the same link that exists in the EPUB file.

The code

So how do you do it? I've tried a bunch of different techniques in the last few months, but couldn't make it work. Today, while reading Matt Garrish and Markus Gylling's EPUB 3 Best Practices, I discovered that they have figured it out. It's not complicated at all, I should have figured it out too :)

The code is very straightforward and not that much different from embedding video files right in an EPUB document.

1. First, in the HTML document (mine's called outvideo.xhtml), create the video element as usual, obviously using the proper URL for the src attribute:

<video controls="controls" poster="image/poster.jpg" width="384" height="276">
<source src="http://www.elizabethcastro.com/epub/examples/catbox.mp4" />
<source src="http://www.elizabethcastro.com/epub/examples/catbox.wvm" />

Although the controls attribute isn't required, I recommend it. Otherwise, your reader won't be able to start (or stop) your video. Also note that I was playing around with WebM video, but wasn't really able to get it to work. But I haven't given up yet.

2. In the content.opf file, you have to do two things: list your video in the manifest as if you'd included it in the EPUB document, and then declare that the HTML file that contains the video points to an external resource.

a. First, we'll manifest the video.

<item id="vid" href="http://www.elizabethcastro.com/epub/examples/catbox.mp4" media-type="video/quicktime" />

b. Next, in the manifest of the HTML file that contains the video, declare that you're using an external resource:

<item id="outvideo" href="outvideo.xhtml" media-type="application/xhtml+xml" properties="remote-resources" />

And that's all there is to it. What does it look like?

If your reader has the Online Content option in iBook preferences Off, all they'll see is the poster image:

Online Content Off

If your reader has Online Content On, they'll be asked if they want to access your online content. It's good that they have a choice, since they may want to wait to download videos until they have wifi available.

Access online content?

Finally, once they click the Allow button, the video will download and become available.

External video - working

Keep in mind again, that if they no longer have connection to the Internet, the video will stop being available (even if they never close the book or leave iBooks)

External resources - no internet

It works in Readium too:

Online content in Readium

You can download the example file here.

*Update: Yes, audio works too. Don't forget to use mime-type audio/mpeg when declaring audio file in content.opf file. And making sure your file paths match the actual file locations helps too :) Thanks to Alberto Pettarin for help troubleshooting.


  1. Thank you for this great article.
    It was really helpful.

    Can i use youtube urls as remote resource in epub3?


    1. I don't think so, since you can't link to an actual video file, only to YouTube's container.

    2. what about iframe to embed youtube video in epub?

    3. Didn't work the last time I tried it.

  2. As I wrote you on Twitter, also external audio files work. You need to make sure the server passes the correct MIME type (e.g., "audio/mpeg" for an MP3 file).

    For the benefit of your readers, a sample EPUB 3 file can be downloaded from:


    -- AlPe

  3. Liz, I can't thank you enough for posting this. I've been trying to solve this problem for months and I finally got it to work with your help!

    Thanks for making this such a beautiful day!


  4. Youpi, thank you. Your blog is a great place for finding answers to epub makers beginners. Bravo.

  5. Liz--thank you for all your posts. Do you know if you can link video that has been placed on facebook?

  6. if you have get parametters in the url, it does not work ?

  7. Hi Liz, Have you tried something similar for remote font resources? For example the Google Font Library. I'm trying to make this work on my end, but I'm unable to get the manifest correct and passing epub check. Any help is much appreciated! Thanks.


  8. This was very helpful, but I wasn't able to enable embedding of external images. I could do videos...but not a simple img element. The external image would just never render...I'd always get the AltText. Does the above not work for image types? (due to security perhaps?). Any help is appreciated.

    1. Nope, it only works for external video and audio. Sorry!

  9. Liz, thank you. Suppose one wanted to verify the user's right to access the video or audio content, is there a way to pass parameters from the client and run a script on the server that checks that a customer number is valid?

  10. Hi Liz, I am trying to stream a external video in epub 2, do you think it will work? and if yes, could you help me in doing that.

  11. Hi LIz: Great article, thanks for sharing. I was able to finally get this to work following your directions. I have run across one strange side effect though, was wondering if you've seen or heard about it. I'm playing a Vimeo video, and the URL has a parameter after the .mp4, like this http://player.vimeo.com/xxx.mp4?s=#######. If I put this as-is in the manifest, iBooks won't play it, it draws a line through the play button like in your no-network example above. However, this is only on iBooks for iOS. It plays in iBooks on my Mac fine. And in Readium on Windows and Mac it is fine. Only iOS seems to have the issue. If I strip the s=#### off the link in the manifest, iOS will then play it just fine. But then my epub won't validate. :) Any ideas on what it might be or what I could try? Thanks in advance. -ken

    1. Curious. Does it have an ampersand? Maybe it needs to be encoded.

    2. Thanks for the quick reply. Doesn't have anything but letters and numbers. Here's an example of what I have in the manifest:

      And then here's the corresponding video tag in the xhtml document:

      I'll keep playing around with it, and see if I can figure out why it does this. If I do, I'll be sure to post a reply back for others. Thanks again for taking the time to write back! Have a great day. -ken

    3. Oops. Looks like I cannot embed html into the replies...

  12. Hi...pretty much a newbie in search of answers...in my case the source of audio is on the android device itself..how do i link it? what i have in mind is that there are a few hundred stanzas in Gautami font and i need to play the corresponding audio for each one of them...thanks in advance

  13. Hi Liz, your site is invaluable to a newbie like me. This topic is similar to a search I've been doing with no luck, though, so I hope I'm not stepping too far out of bounds. Is there a way to link to an external PDF and website URL from with an ePub3 document? I can't seem to find a good answer to this either way. Thanks again.

    1. Sure, just use a regular link to the PDF file.

  14. Hi Liz,
    Can iBooks also access remote content that is not video or audio? My search says no, but is there some workaround you are aware of?

  15. Hi Liz , I developed fixed layout epub, i have 2 opposite page each one have audio tag , but if played the two run together , how fixed it? , when play one, pause other in the opposite page. thank you very much.

  16. Hello Liz,

    Thanks for a nice blog and it helps me alot. I followed this and am able to load remote urls, I also want to load youtube videos, I tried following your instructions but it does not work. I also saw at some places that youtube videos have media-type as "application/x-shockwave-flash" I tried that as well but its not working either. Please let me know what I am missing.

    Dilawer Hussain


More of my books