Remote Resources

Summary

Avoiding hosting resources outside the EPUB container whenever possible.

Techniques

Host all resources in the EPUB container.
Provide alternative ways to access remote resources when they must be hosted remotely.

Examples

Example 1 — Link to alternative audio

A link is provided after the audio element so users can try opening the audio file in a browser if their reading system blocks access to remote resources.

<audio src="https://example.org/audio/war_of_the_worlds.mp3" …>
   …
</audio>
<p>
   <a href="https://example.org/audio/war_of_the_worlds.mp3">
      Listen in browser
   </a>
</p>

Example 2 — Fallback fonts

Fallback system fonts are specified in case the remote font is not available.

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

body {
   font-family: 'Roboto', Arial, sans-serif;
}

Frequently Asked Questions

Should an alternative link to the remote file be inside the audio or video element?

Fallback content inside the audio and video elements is only accessible to users when the reading system does not support the element (e.g., in an EPUB 2 reading system because there was no video element in XHTML 1.1).

<audio …>
   <p>Sorry, your reading system does not support
      the audio element. The audio file cannot be
      played.</p>
</audio>

Content inside the elements is not accessible if the reading system cannot download a resource or play the provided format. In these cases, the reading system displays its own error message (i.e., it does not display the internal fallback content).

While it might seem helpful to provide a link to the web-hosted file inside the element, since it gives users with older reading systems access, it limits the availability in other situations. If a modern reading system cannot access the file, for example, a link anyone can access allows provides greater flexibility.

Never place accessible alternatives, such as transcripts, inside these elements.

Can I host my remote audio/video on YouTube?

Yes and no.

If you want to link users out to an audio or video file on the web, you can host it on any site you want. There are no restrictions in EPUB on where external hyperlinks can go.

If you are trying to embed a YouTube page in the EPUB via the HTML iframe element, then the answer is no. For security reasons, EPUB does not allow the embedding of web pages directly in a publication. The exemption that allows publishers to host remote video files outside the EPUB container only applies to video files; it does not apply to web pages that embed videos.

Explanation

Although the issues with remote resources are primarily usability ones — they affect all users equally — they are not exclusively so. This section reviews how to include remote resources in an EPUB as well as how to mitigate both the usability and accessibility issues that can arise.

Note

EPUB 2 did not allow remote resources. The guidance in this section does not apply to that version of the EPUB format.

Resources allowed remotely

EPUB 3 only allows you to host four types of resources outside of the EPUB container (i.e, the zip file that contains the publication):

Audio
Video
Resources retrieved by scripts (e.g., using the JavaScript XmlHttpRequest and Fetch APIs).
Fonts

In the case of audio and video, the exemption only applies to files with a corresponding media type (e.g., audio/mp3 for an MP3 file). You cannot reference an HTML page that embeds an audio or video player (e.g., YouTube).

Do not confuse remote resources with external hyperlinks. A remote resource is one that is brought into the publication as opposed to a hyperlink that sends users out to the web. The audio and video elements allow you to embed audio and video resources regardless of where the referenced file is located, for example, while a hyperlink to YouTube will send a user to that web site.

Identifying remote resources

Although remote resources are not included in the EPUB container, you still must list them as publication resources in the EPUB manifest. The full URL to the resource goes in the manifest entry's href attribute.

In addition, the EPUB content document that references the remote resource must have a properties attribute with the value "remote-resources" (this property allows reading systems to, for example, selectively enable remote access only for files that need it).

The following example shows the manifest entries for a remote MP3 file and the XHTML file that embeds the audio (the file c01.xhtml would contain an audio element as depicted in example 1).

<package …>
   …
   <manifest>
      <item id="audio01"
            href="https://example.org/audio/war_of_the_worlds.mp3"
            media-type="audio/mp3"/>
      
      <item id="c01"
            href="xhtml/c01.xhtml"
            media-type="application/xhtml+xml"
            properties="remote-resources"/>
      …
   </manifest>
   …
</package>

When adding remote resource URLs to the manifest, be aware that you must escape any ampersands (&) in the string. For example, if the URL has a query string with multiple parameters, you will have to encode each ampersand using the & entity as in the following example.

Font URL:
https://fonts.googleapis.com/css2?family=Roboto&display=swap

Manifest encoding:
<item id="font01"
      href="https://fonts.googleapis.com/css2?family=Roboto&amp;display=swap"
      media-type="font/ttf"

Usability considerations

The most common reason for hosting resources remotely is due to their size. If a publication has several videos amounting to a few gigabytes of data, it may not be feasible to distribute such a publication. Vendors could reject the publication due to size restrictions, and even if they accept such large publications, users have to wait for all the data to download before they can begin reading, even if they have no interest in watching the videos.

Hosting resources remotely is a way around size restrictions and defers the downloading of some resources until they are needed, but it also comes with some serious usability issues — users will need a device with an active internet connection and a reading system that does not block access to the internet. Just because you have a tablet with an internet connection, for example, does not mean that the reading system will allow publications to retrieve resources from the web, as these could present security issues.

Fonts are one of the best candidates for remote hosting as users will typically not notice their absence. When fonts are not available, the reading system automatically falls back to the next available font. The publication text may not appear as nicely as intended, but its readability generally does not suffer (with one exception detailed in the next section on accessibility concerns).

Before hosting audio and video outside the EPUB container, consider the user experience when they are not available. If they are critical to understanding the text, users without access will miss essential information.

To mitigate some support and connectivity issues in reading systems, try offering users a way to link directly to the audio or video file (refer to example 1. This may allow users to circumvent their reading system to try opening the content directly in a browser.

Script data hosted outside the EPUB container is the most problematic type of remote resource from a usability perspective. Not only is support for scripting not universal in EPUB, but reading systems that support scripting may not support the APIs that allow you to call external data. In other words, a reading system that might allow remote audio and video might not allow remote script calls.

For remote data calls, consider embedding a default data set if the external scripting call is only to get the latest version of the data. This will at least allow users to interact with the scripted content rather than have a non-working application in their publication.