Skip to content


Repository files navigation



Open-Source Hypervideo Framework

Build Status Code Coverage Downloads per month (NPM)


⚠️ The master branch currently represents an alpha pre-release. Features and syntax are subject to change at any time, so please don’t use it in production. Unless you’re some kind of daredevil.


Hypervideo: online video annotated with time-based links and other widgets.

Hypervideo opens up a world of immersive storytelling, such as choose-your-own-story films, which boast high audience engagement, and video hotspots which trigger an action, such as jumping to a chapter marker, learning more about a topic, or buying a product/service.

Most hypervideo offerings are proprietary, requiring recurring payments and vendor lock-in to use. This hinders cash-strapped visual artists, and silos metadata that could be useful in search and beyond. RedBlue enables more people to produce hypervideo by democratizing the technology behind it. We author an open specification, HVML (Hypervideo Markup Language), which aims to be the HTML of video.

In conjunction, we develop this, the RedBlue JavaScript player, which brings the immersive features of HVML to any website—conveniently implemented as a Web Component (i.e. Custom Element).


“Choose Your Own Story” video experiences

Choice-based narratives are implemented using the developing HTML5 Media Source Extensions API, which means all current implementations are experimental.

So far, it has the best support in Blink-based browsers such as Google Chrome, which is being used as the reference implementation for this project.

Gecko-based browsers such as Mozilla Firefox have limited support (behind an about:config flag), but work is being done to catch up to Blink.

Internet Explorer introduces support in version 11 on Windows 8, but for MP4 videos only, which are of secondary concern to WebM in this project and not currently supported.

This is not yet integrated into the Custom Element, but a prototype demoing this functionality is available for Chrome Desktop.


A preliminary version of hotspots are implemented for YouTube embeds. See the Developer Guide.


  • yarn add redblue or
  • npm install redblue

Note that RedBlue is not yet feature-complete, so only an alpha version has been published to NPM.


Import the RedBlue video player Custom Element. (This requires ES6 support to work directly in the browser; otherwise the source code can be transpiled to ES5.)

<script type="module">
  import RedBlueVideo from './guide/modules/redblue-video-omni.js';
  customElements.define(, RedBlueVideo );

Include an HVML code block as a child of <redblue-video>. HVML can be represented as either XML or JSON-LD. When using the XML serialization, set the boolean hidden attribute to true to prevent the browser from rendering the metadata.

  <hvml xmlns="" hidden="hidden"></hvml>

Populate the HVML data. RedBlue will render the appropriate video embed code and user interface. For an explanation of what this code does, see the Developer Guide.

<redblue-video id="redblue-youtube-xml" aspect-ratio="16:9" debug="debug">
  <hvml xmlns="" xmlns:xlink="" xmlns:css="" xml:lang="en-US" hidden="hidden">
    <video type="personal" xml:id="ep-23">
      <title>Overnight Dance Party at the Museum of Fine Arts Boston</title>
      <description type="xhtml">
        <div xmlns="">
          <p>Full Facebook Live stream:</p>
          <p>#mfaNOW #mfaLateNites</p>
      <showing scope="release" type="internet" admission="private">
        <venue type="site">
          <entity site="">YouTube</entity>
          <title>Overnight Dance Party at the Museum of Fine Arts Boston | Hugh’s Vlog | #mfaNOW #mfaLateNites</title>
        <choice xml:id="full-stream">
          <name>Go to: <code style="font-family: inherit; font-weight: bold;"></code> for the full stream</name>
          <goto on="duration" xlink:actuate="onRequest" xlink:href="" width="70%" height="13%" css:font-size="calc(384 / 150 * 1vw)" css:font-family="'Noto Sans CJK JP', 'Noto Sans CJK', 'Noto Sans', sans-serif" css:white-space="nowrap" css:overflow="hidden">
            <animate starttime="517.292107" endtime="518.872131" startx="14.9%" starty="-15%" endx="15%" endy="10%"></animate>
            <animate starttime="523.373882" endtime="524.873404" startx="14.9%" starty="10%" endx="15%" endy="-15%"></animate>


As this is alpha software, we are not currently accepting Pull Requests, but you are welcome to test it out and offer feedback by posting it to Issues, or by tweeting @RedBlueVideo.

Known Issues

  • Limited browser support
  • Choice-based narratives not in master
  • Hotspot animations do not respond to pauses or timeline seeking within their trigger range


RedBlue Video is a small-time operation headed by Hugh Guiney, a senior UX developer (Twitter: @LordPancreas & @HughxDev, GitHub: @HughxDev), with help from his brother Austin, a CS undergrad (Twitter: @SenorKoffey, GitHub: @pyreking).