Section 4.28 Video
A video is a natural way to enhance a document when rendered in an electronic format, such as HTML web pages. It might be additional information that is hard to communicate with text (marine invertebrates swimming), a lecture or presentation that augments your text, or even some artistic work, such as a symphony legally hosted on YouTube, when you could never hope to get copyright clearance yourself.
PreTeXt supports videos you own and distribute with your source, videos shared openly on the Internet via stable URLs, and videos available on YouTube. Go straight to to the end of this section to see how easy it is to incorporate a YouTube video.
HTML5 web browsers are able to play video files in three formats, summarized in the following table.
Subsection 4.28.1 Video Element
<video> element is used to embed a video in output formed from HTML. Subsections below describe the different ways to indicate the source of the video. The video may be placed inside a
<figure> or can be a panel of a
<sidebyside>. The former will have a caption, be numbered, and hence can be the target of a cross-reference (
<xref>). The latter is anonymous, but allows for horizontal layout, and combinations with other panels.
Size is controlled by a
@width attribute expressed as a percentage (on the
<video> element when used in a figure, or as part of the
<sidebyside> layout parameters). Height is controlled by giving the aspect ratio with the
@aspect attribute on the
<video> element. The value can be a ratio expressed like
4:3 or a decimal number computed from the width divided by the height, such as
1.333. The default for videos is a 16:9 aspect ratio, which is very common, so you may not need to specify this attribute.
Options include specifying a
@start and an
@end in seconds as integers (no units) if you only want to highlight a key portion of a video. The
@play-at attribute can take the following values
Play in place (the default action).
Play in new window or tab, at 150% width.
Provide the reader the choice of the other two options.
In an educational setting, sometimes the preview images provided by YouTube can be distracting, or for an author-provided video you may wish to provide your own preview image. The
@preview attribute can take on the following values
PreTeXt supplies a Play-button image.
Whatever the video playback provides. This is identical to simply not including
- Path to an image file
Typically, this will be a relative path, starting with
images/. This image will be used as preview for the online version and the print version.
Subsection 4.28.2 Author-Provided Videos
If you own and possess your video content, then you can distribute it with your PreTeXt source, and it can be hosted as part of your HTML output. Then the
@source should be a relative file name that points to the file containing the video. If you are able to provide more than one of the three formats in Table 4.28.1, then you can provide the filename without an extension. If a browser cannot play one format, it may be able to play another. PreTeXt will write the code to make that happen, preferentially in the order of the table (more open formats first!). In other words, you can provide files in more than one format and increase the likelihood that a reader's browser will find a format it can playback.
Subsection 4.28.3 Network-Hosted Videos
If a video is shared openly on the Internet, you can simply provide the full URL for the
@source attribute. All the other attributes are the same as for the author-provided case, above. Read Subsection 4.27.3 for some considerations when authoring a URL, since there are a few gotchas.
You can frequently discover the URL of a video by first playing it, and then using a context menu (e.g. via a right-click) to reveal an option to copy the video's location. However, note that there are various techniques sites use to make such a URL temporary, or otherwise unusable. So do some research about potential uses and test carefully. Our example below is provided from a United States government site.
Subsection 4.28.4 YouTube Videos
For a video hosted at YouTube, find the 11-character identification string in the address of a video you are viewing. It will look something like
hAzdgU_kpGo. Then, instead of the
@source attribute, simply provide this identification string as the
@youtube attribute, such as
That's it. All of the options above are then implemented and realized with YouTube's embedded player.
This can be a great way to incorporate popular or artistic content, legally, which might be difficult or costly to acquire through copyright clearance.
pretext script (Chapter 45) may be used to download the provided preview images for YouTube videos (only). Filenames will be formed from the
@xml:id of the
<video> element. These will be used in static versions of output, such as print. Once custom preview images are implemented for author-hosted video, their static representation will improve.
Additionally, a YouTube playlist can be included in one of two ways. You may set the
@youtube attribute to be a space-separated list of several video IDs (an “itemized” playlist). Alternatively, you may set the
@youtubeplaylist attribute to a YouTube playlist ID (a “named” playlist). At present, a named playlist will not get a thumbnail image from Youtube, and either the “generic” thumbnail will be used or you can supply your own
Make a feature-request if a scheme similar to the one for YouTube, but for some other video-hosting service, would be useful for your project.