<dl8-video>

The <dl8-video> element is a video player that can playback all kinds of different video content in VR as well as on desktop and mobile. From an API standpoint the element tries to mirror the native video element as closely as possible. Video sources are described by child elements <source> with an URI and a type (see MDN Docs for more information)

 <dl8-video title="Example Video" author="Jane Doe" format="STEREO_180_LR"
            poster="example.jpg" display-mode="inline" loop>
    <source src="example.mp4" type="video/mp4" />
    <source src="example.webm" type="video/webm" />
 </dl8-video>

Defines the mono or stereo format the video is provided in. Delight VR supports all common stereo/mono 360/180 equirectangular and spherical formats, as well as 2D flat video and stereoscopic 3D flat video.

• STEREO_180_LR: A 180 degree stereo equirectangular mapping, left and right eye being side by side.
• STEREO_180_LR_SPHERICAL: A 180 degree stereo spherical mapping, left and right eye being side by side.
• STEREO_180_TB: A 180 degree stereo equirectangular mapping, left and right eye being on top and bottom respectively.
• STEREO_180_TB_SPHERICAL: A 180 degree stereo spherical mapping, left and right eye being on top and bottom respectively.
• STEREO_360_TB: A 360 degree stereo equirectangular mapping, left and right eye being on top and bottom respectively.
• STEREO_360_LR: A 360 degree stereo equirectangular mapping, left and right eye being side by side.
• MONO_360: A 360 degree mono equirectangular mapping.
• MONO_FLAT: A monoscopic 2D flat video.
• STEREO_FLAT_LR: A stereoscopic 3D flat video, left and right eye being side by side. The pixel aspect ratio follows the video aspect ratio.
• STEREO_FLAT_LR_SQUARE: A stereoscopic 3D flat video, left and right eye being side by side. The pixel aspect ratio is square (1:1).
• STEREO_FLAT_TB: A stereoscopic 3D flat video, left and right eye being on top and bottom respectively. The pixel aspect ratio follows the video aspect ratio.
• STEREO_FLAT_TB_SQUARE: A stereoscopic 3D flat video, left and right eye being on top and bottom respectively. The pixel aspect ratio is square (1:1).

On top of that Delight VR supports custom fisheye distortions. To configure these custom distortions you first have to define the format with the following meta tag:

 <meta name="dl8-custom-format" content='{"name": "MY_CUSTOM_FORMAT","base":"STEREO_FISHEYE_LR","params":{"fov": 180, "magnification": 1.0 }}'>

The name then can be used on all relevant elements (format=”MY_CUSTOM_FORMAT”). The “base” attribute controls where the custom format extends its base functionality from. At the time of writing “STEREO_FISHEYE_LR” is the only custom base format. The most common use case is VR180 camera output (two side-by-side mounted wide-angle fisheye lenses) from live streaming cameras that output the raw feed and don’t encode the video in equirectangular. The base format has “fov” (field of view) and “magnification” as params.

A Boolean attribute; if specified, we will, upon reaching the end of the video, automatically seek back to the start.

A Boolean attribute; if specified the 3d hud for controlling videos in VR is disabled.

A Boolean attribute which indicates the default setting of the audio contained in the video. If set, the audio will be initially silenced. Its default value is false, meaning that the audio will be played when the video is played. Note that this attribute is deliberately unsupported on iOS devices. See Safari Developer Library for further details.

Setting this attribute to “auto” (the default) informs the browser that video data should be prefetched when the page loads so that an optimal playback experience can be guaranteed once the user hits play. Note that this is only a preload hint for the browser. Each browser will interpret this hint as it sees fit. Some mobile browsers for example won’t prefetch any data to save bandwidth.

Setting to “metadata” only prefetches important metadata like duration and dimensions but not the actual video content.

Setting the attribute to “none” won’t prefetch any data before hitting play. Choose this option if minimum server traffic as well as conservation of your users bandwidth is more important in your use case than an optimal playback experience.

Specifies the frames per second that the video should playback. To avoid over- or undersampling please set this to the framerate of the video file. Setting a lower fps value may improve playback performance. The default is 30.

Specify the CORS settings for the video. See the MDN documentation for more information on possible values and implications.

Add this attribute with an URL as a value to the dl8-video element if your content is hosted on a different server but you want to fallback in case the users browser doesn’t support cross origin video (IE, Safari). Once the player encounters the CORS issue it will automatically redirect to that fallback URL and auto-open the Delight VR player on there. Therefore the URL should point to a special page where Delight VR is embedded and the videos are hosted from the same domain, if possible. If you don’t specify this attribute the user will just be presented with a message that CORS Video is not supported on Safari/IE. See the video caveats section for more information on CORS issues with videos.

This attribute determines what happens if the CORS fallback is triggered. If the boolean attribute “cors-fallback-redirect-confirmation” is set a confirmation prompt will be shown to the user asking him to confirm the redirect to the fallback URL. If nothing is set (the default) or the attribute is set to false the user will be automatically redirected.

You can prevent autostart of the CORS fallback source by setting this attribute.

To define multiple qualities for your video you can add sources with different encodings and dimensions to the video element and flag them with the attribute “quality” like so:

 <dl8-video format="STEREO_180_LR">
    <source src="example-4k.mp4" type="video/mp4" quality="4k" />
    <source src="example-4k.webm" type="video/webm" quality="4k" />
    <source src="example-1080p.mp4" type="video/mp4" quality="1080p" />
    <source src="example-720p.mp4" type="video/mp4" quality="720p" />
 </dl8-video>

The quality strings are freely definable and appear directly in the UI. Note that you can have multiple alternative sources for one quality like the “4k” quality in the example above. Also note that the order of qualities in the UI is dictated by the order of sources inside the video element; with the first source in the video element with its respective quality selected by default.

Additionally you can specify the “fps” and the “format” attributes for each source individually.

In general all notes on compatibility from regular HTML5 video elements also apply for the dl8-video element since it uses the in-built element internally (see caniuse.com for more information).

Regarding video encoding consider using the h.264 and webm video codecs because of their wide reaching support across browsers. For maximum compatibility provide both variants.

For maximum mobile compatibility you should provide videos with a maximum resolution of 1920×1080. In general it is wise to use dimensions that are power of two and don’t have extremely stretched aspect ratios (i.e. 2048×2048 for stereo over/under, or 2048×1024 for mono 360).

To use adaptive streaming you must provide at least one adaptive streaming <source> element on your <dl8-video> or <dl8-cinema> element. Depending on whether you want to use MPEG-DASH or HLS you would add different sources pointing to the manifest files:

For MPEG-DASH you provide an .mpd manifest file and set the type attribute to “application/dash+xml”.

For example:

<source src="path/to/your/dash.mpd" type="application/dash+xml" />

For HLS you provide an .m3u8 HLS playlist file and set the type attribute to “application/x-mpegurl”

For example:

<source src="path/to/your/hls.m3u8" type="application/x-mpegurl" />

We recommend to use MPEG-DASH and HLS streams if you want to go for maximum compatibility. Especially iOS/Safari do not support MPEG-DASH as of writing. Therefore you can add an HLS and MPEG-DASH source.

Be aware that the Cross-Origin issues on Safari and IE apply for adaptive streaming sources as well. (See also: Cross origin fallback).

Complete example (If you want to support both MPEG-DASH and HLS):

 <dl8-video format="STEREO_180_LR">
    <source src="path/to/your/dash.mpd" type="application/dash+xml" />
    <source src="path/to/your/hls.m3u8" type="application/x-mpegurl" />
 </dl8-video>

To provide spatial audio playback in VR Delight VR supports the AmbiX Ambisonics format. AmbiX is based on first order ambisonics (FOA) which stores four spherical harmonics coefficients into 4 audio channels of a 5.1 audio source. For more information on how to produce, author and encode VR video with AmbiX audio please refer to our feature page.

To enable spatial audio via AmbiX just add the audio-format=”ambix” parameter to your AmbiX video source.

For example:

<dl8-video format="STEREO_360_TB">
    <source src="path/to/your/ambisonics-video.mp4" type="video/mp4" audio-format="ambix" />
    <source src="path/to/your/fallback-video-for-ios.mp4" type="video/mp4" />
</dl8-video>

Note that currently iOS is not able to decode video sources with multi-channel audio. If you want maximum compatibility between all platforms you therefore have to provide a fallback video source with a regular stereo track.

Delight VR is able to show preview thumbnails when the user hovers over the seeking bar on mobile, desktop as well as in VR. These give the user a rough overview of the content and can avoid unnecessary seeking. The player supports setting up preview thumbnails through sprite sheets as <dl8-video> sub elements.

The first step is to setup a proper workflow for generating preview thumbnails from your videos. This is either done by your existing encoding service or manually by you.

After generating the thumbnails use declarative markup inside your <dl8-video> element to enable seeking previews. We use sprite sheets (a grid layout of multiple preview thumbnails) to save bandwidth and increase performance. Additionally to support longer video content each video can have multiple sprite sheets. To simplify the markup it is assumed that each thumbnail is sampled equidistant from the video. Here is a complete sample markup that uses three 5×5 sprite sheets that have an aspect ratio of 16 by 9:

<dl8-video format="STEREO_360_TB">
    <source src="example.mp4" type="video/mp4" />
    <dl8-video-preview-sprite frame-aspect="16:9">
        <dl8-video-preview-sprite-sheet src="S0.jpg" columns="5" rows="5" frames="25"></dl8-video-preview-sprite-sheet>
        <dl8-video-preview-sprite-sheet src="S1.jpg" columns="5" rows="5" frames="25"></dl8-video-preview-sprite-sheet>
        <dl8-video-preview-sprite-sheet src="S2.jpg" columns="5" rows="5" frames="11"></dl8-video-preview-sprite-sheet>
    </dl8-video-preview-sprite>
</dl8-video>

The default frame-aspect is “16:9”. The values colums=”5″, rows=”5″ and frames=”25″ are also the defaults. Note that columns*rows doesn’t have to equal frames. This enables sprite sheets that aren’t fully filled. This is especially important at the end of a thumbnail sequence.
Of course you can just use single thumbnail images instead of sprite sheets. For this you would need to set colums=”1″, rows=”1″ and frames=”1″ for each thumbnail.

We offer an event API that is similar to the media events API (https://developer.mozilla.org/en/docs/Web/Guide/Events/Media_events) of the native HTML5 video element. To register for these events you need to call addEventListener on an <dl8-video> element that you’ve queried beforehand.

For example:

var element = document.querySelector("dl8-video") 
element.addEventListener('play', function() { console.log("play") })

To control video playback via Javascript Delight VR offers the following APIs on the element.

Start playback:

var element = document.querySelector("dl8-video") 
element.play()

Pause playback:

var element = document.querySelector("dl8-video") 
element.pause()

Seek video:

var element = document.querySelector("dl8-video") 
element.seek(t) // t is a number that represents the seeking time in seconds

Furthermore we export playback status properties from the underlying video element that help you programmatically control the playback flow in your application.

Get the video duration:

var element = document.querySelector("dl8-video") 
console.log("duration", element.duration)

Get the current playback time:

var element = document.querySelector("dl8-video") 
console.log("currentTime", element.currentTime)

• Imprecise tracking on Android: On Android mobile chrome browsers < 50 users have to navigate to chrome://flags/#enable-experimental-web-platform-features and enable that setting to work around a bug in Android Chrome < 50, which had issues with tracking precise head orientations based on gyro data.
• Cross origin issue on Safari and IE: Videos do not work on iOS and OSX Safari as well as Internet Explorer when the media file ist hosted on a different domain. See this post on Apple Developer Forums for a detailed discussion. We currently support a custom specified fallback URL that is presented to the user in that case. See the “cors-fallback-url” description for more details.
• h.264 and Chromium: Currently the special WebVR enabled Chromium build that can be downloaded here can’t playback .mp4 videos with h.264 encoding. This is due to licensing issues with the codec and the free open source Chromium project. This issue will be resolved once WebVR lands in Chrome. For now try to always provide .webm encoded videos as alternative sources with your video elements as they will playback in Chromium.
• NPOT video textures in Chrome/Android: Currently there is an issue with video textures in Chrome on Android that are non power of two. Here video data is not decoded/sampled correctly which results in low resolution and/or pixelated appearance. For maximum compatibility and best VRAM usage try to keep video resolution at power of two sizes like 2048×2048 or 4096×2048.
• IE11 video resolution: The h.264 video decoder used in Internet Explorer 11 decodes a maximum resolution of 1920×1088 pixels. Videos bigger than that throw an error.