The video directive embeds video in multiple formats on a page.


The general format of the video directive is:

.. ``video``:: unique_id

   + --- Content area ---
   | one or more references to video files or URL's
   + --------------------

For an alternative to embed directly to youtube, use the YouTube and Vimeo directive.

Required Arguments

unique id

A unique identifier after a space and the :: in the video directive. Valid identifiers must not contain spaces. You should also avoid the characters `` ` , ``,, :, and *.

content area

The video directive must contain at least one line of content.

The content can be either a file reference to a video, or a url to a video resource, one line per video.

You can specify as many video sources as you need. One in .mov format and another in .webm format is generally enough to cover most browsers. The first format that works is the one that is played.

Optional Arguments


Boolean. If present, include the usual set of video controls:

  • Play, Pause, Rewind, and Fast Forward.

If not present, the video will automatically play when the page is loaded.


Boolean. If present, the video will loop continuously. Default is false.


Boolean. If present, load the video in the background when the page loads. Default is false. The video will begin to download when ‘play’ is pressed.


String. Define a thumbnail for the video.

The string parameter defines the path to the image that should serve as the thumbnail:


Relative paths are relative to the current file location.

If :thumb: is used, then the thumbnail image is displayed until the reader clicks on the thumbnail. Clicking on the thumbnail will cause the full video to appear at full size on the page.

If the :thumb: directive is not present, then the video will appear on the page in its full size.

Languages supported


Sphinx configuration options

No directive specific configuration options exist.



Known limitations



.. video:: video-ex1
   :thumb: /_images/whileloop.png

Logs and Grading

Video directives are not tied to the grading interface. Interactions are logged in the database: each time a video is played, it is logged.

  • If you have logged-in users, you can have a log of who has played it.

  • If login is not required, a log of how many times it has been played is retained.

You have attempted of activities on this page