All the ways to serve videos from Confluence Data Center
Context
You may find yourself in a Confluence-powered knowledge base article management scenario. Teammates may want to know the options to serve video content. There are a couple of requirements and restrictions that you have to consider when proposing any option. Those are:
Size and format: Some of the videos may be larger than the configured size limit for attachments in Confluence. The main format is MP4, but you may also need to support other formats.
Privacy: Most videos should be protected from being accessed by anyone other than the intended audience. Public video services such as Youtube or Vimeo may not be accepted.
There is a third consideration that could be taken as nice to have:
Tracking: Some people will be interested in having insights into how their audience uses the Knowledge Base (KB) service.
Option 1: Attach videos to any page and use the Multimedia Macro
This option relies on Confluence's out-of-the-box features. In short, we must upload a video file as an attachment to any page. Afterward, in the page we want to display the video, we include the multimedia macro to embed the attached video.
The video doesn’t need to be attached to the same page from where we want to display it, as the multimedia macro configuration parameters enable us to indicate the name of the page from where look for the video.
Behind the scenes, the multimedia macro uses HTML5
<video> tag, so that the type of video the people can see will depend on the video formats their browser support with that HTML5 <video> tag. Whether a certain format is supported depends on the browser.This option doesn’t fully cover the requirement of Size and Format, as it’s based on attachments.
Option 2: Embed online videos
An alternative to using attachments is embedding videos hosted in external storage systems. In short, embedding a video implies that the file isn’t stored in the Confluence server but in a separate (and maybe distant) storage that has to be accessible through HTTP(S) protocol. Confluence will just provide a player from which the video is streamed (that is, the content is sent in a continuous stream of data and played as it arrives).
This option may not fully cover the requirement of Privacy, as some of the video hosting services have a Public setting as default (anyone can see the video) or the option to share videos privately only with a small set of viewers.
Regarding embedded videos, we can identify several scenarios.
Option 2.1: Video hosting services
Many providers offer online video hosting services (for example, Youtube, Vimeo, and many others). Usually, all these services include the visualization part. That is, they don’t just provide a link to the video file but instead a link to a webpage that already contains the logic to detect your browser and to determine how they should play the video, based on what is available on the viewer's device.
To visualize these videos on Confluence, we have mainly two options:
Option 2.1.1: Using the Widget Connector Macro
This option is based on an out-of-the-box feature. The Widget Connector macro, in summary, provides the ability to embed online videos and other multimedia content from the most popular video hosting services on a Confluence page. This macro only works with a specific list of supported services.
Behind the scenes, what the Widget Connector macro does is translate the public URL to the embed link, applying a specific template for each of the above-mentioned services, and inserts that link in a HTML iframe element.
Option 2.1.2: Using an iframe
Most of those online video hosting services provide a snippet of code (usually called “embed code”) that helps display the video on a website. This embed code is, in summary, a HTML code using an
<iframe> element.1<iframe width="560" height="315" src="https://www.youtube.com/embed/UFNXKDbFczM" 2title="YouTube video player" frameborder="0" 3allow="accelerometer; autoplay; clipboard-write; 4encrypted-media; gyroscope; picture-in-picture" allowfullscreen>5</iframe>Youtube embed video
For security reasons, HTML macros are disabled by default in Server/Data Center and not available in Cloud (because they can make your Confluence site vulnerable to cross-site scripting attacks),
Instead of enabling the out-of-the-box HTML Macro, it’s recommended to use a Marketplace app providing an enhanced, secure HTML macro.
- To see some suggestions for Data Center/Server editions: How to serve videos from Confluence Data Center | Annex | Marketplace apps for HTML Macro | Data Center
Option 2.2: Custom video storage
An alternative to those popular video hosting services would be to create your own.
To replicate the same functionality that the video hosting services provide (for example, including the viewer) may bring too much complexity to the task. Instead, what we’ll try to do in the following sections will be much simpler.
In summary, we need to configure an external storage service to host our videos and provide them access through HTTP(S) protocol. To visualize the video, we’ll rely on HTML5 so that we delegate the visualization part to the default browser capabilities.
Find below the piece of code (simplified as much as possible) that would do the job:
1<video controls="controls">2 <source src="http://someserver.com/shuttle.mp4" type="video/mp4">3 Your browser does not support the HTML5 Video element.4</video>- As the browser will be the viewer, we need to consider which video formats are supported: HTML5 video
- To know how well your browser supports HTML5, go to this website: The HTML5 test - How well does your browser support HTML5?
Option 2.2.1: Using Confluence HTML macro
Again, we fall into the same security issues than Option 2.1.2 | Using an iframe. And again, it is not recommended. Instead, try to use one of the following options.
Option 2.2.2: Using Marketplace security enhanced HTML macro app
A more secure alternative to enable the HTML Macro in Confluence is to rely on one of the Marketplace vendors that provide an enhanced HTML macro functionality.
- To see some suggestions for Data Center/Server editions: How to serve videos from Confluence Data Center | Annex | Marketplace apps for HTML Macro | Data Center
Option 2.2.3: Using custom HTML5 user macro
If you want to provide just the HTML5 <video> functionality but prevent users from adding any other HTML code in your Confluence pages, writing your own macro would be the option.
You’ll need to be a System Administrator to create and manage custom macros.
A simple example of a custom macro doing the job could be this:
1## Macro title: HTML5 Video2## Macro has a body: N3##4## @param width:title=Width|type=string|required=false|desc=Video width5## @param height:title=Height|type=string|required=false|desc=Video height6## @param src:title=Source|type=string|required=true|desc=Video URL7#set ( $last3 = $paramsrc.length() - 3 )8#set ( $extension = $paramsrc.substring($last3) )9#set ( $path = $paramsrc )1011#if ( $paramOverride )12 #set ( $extension = $paramOverride )13#end1415#if ( $extension == "m4v" )16 #set ( $mimetype = "video/mp4" )17#else18 #set ( $mimetype = "video/" + $extension )19#end2021<video controls="controls" 22 #if ($paramwidth) width="$paramwidth" #end23 #if ($paramheight) height="$paramheight" #end24 src="$path">25 <source type="$mimetype" src="$path" />26</video>27<p>28 <strong>Download video:</strong> <a href="$path">$extension format</a>29</p>How does this work?
When editing a page, we look for the custom macro we created (in this example, it is HTML5 Video) as we’d look for a normal, out-of-the-box macro.
When configuring the parameters,
Source is the main parameter to be configured.For this example, we simply deploy an Nginx web server and upload some MP4 videos to make them available through HTTP URLs. These URLs are the source that we need to include in the macro configuration.
When saving the page, that’s the result.
- More info about how to write custom macros: Writing User Macros | Confluence Data Center and Server 7.19 | Atlassian Documentation
Security considerations
We don’t want to give free access to our video hosting server. Any video HTTP URL should be restricted, as we only want to enable access to those videos through our Confluence instance.
Following the example above, if we protect the URLs with Basic Authentication, we have to add some Javascript code to our User Macro to do the authentication. See below an example that uses
fetch to add an Authorization header for Basic Authentication and retrieve the video in streaming:1## Macro title: HTML5 Video2## Macro has a body: N3##4## @param width:title=Width|type=string|required=false|desc=Video width5## @param height:title=Height|type=string|required=false|desc=Video height6## @param src:title=Source|type=string|required=true|desc=Video URL7#set ( $last3 = $paramsrc.length() - 3 )8#set ( $extension = $paramsrc.substring($last3) )9#set ( $path = $paramsrc )1011#if ( $paramOverride )12 #set ( $extension = $paramOverride )13#end1415#if ( $extension == "m4v" )16 #set ( $mimetype = "video/mp4" )17#else18 #set ( $mimetype = "video/" + $extension )19#end2021<video crossOrigin= "use-credentials" controls="controls" 22 #if ($paramwidth) width="$paramwidth" #end23 #if ($paramheight) height="$paramheight" #end>24 <source type="$mimetype" id="my-video" />25</video>2627<p>28 <strong>Download video:</strong> <a href="$path">$extension format</a>29</p>3031<script>32var url = "$path";3334async function init() {35 36const videoSource = document.getElementById("my-video");37 const mediaResponse = await fetch(url, {38 headers: {39 "Authorization": "Basic dHJpY2t5Om5pY2tlbA=="40 }41 });4243 const reader = mediaResponse.body.getReader();4445 const stream = new ReadableStream({46 start(controller) {47 return pump();48 function pump() {49 return reader.read().then(({ done, value }) => {50 // When no more data needs to be consumed, close the stream51 if (done) {52 controller.close();53 return;54 }55 // Enqueue the next data chunk into our target stream56 controller.enqueue(value);57 return pump();58 });59 }60 }61 });6263 const blob = await new Response(stream).blob();6465 if (blob) {66 videoSource.src = URL.createObjectURL(blob);6768 // Load the new resource69 videoSource.parentElement.load();7071 console.info("Ready!", videoSource.src);72 } else {73 console.warn("Can not load");74 }75}7677init();78</script>If your custom video hosting server accepts a more secure mechanism than Basic Authentication, we recommend you use the corresponding Authentication type in the Authorization header.
In case you see a CORS (Cross-Origin Resource Sharing) error when trying to view the video from the Confluence page, you have to review your server documentation and configure what’s required to enable CORS (usually, add the header Access-Control-Allow-Origin to allow access to your Confluence domain).
Option 3: Marketplace video app
A variety of Marketplace apps are available to help with video storage in Confluence: Search for apps | Atlassian Marketplace
Most of the apps have been created as of 2021, so there may be limited reviews and feedback for performance and capability.
Other similar workarounds serving video content from Atlassian products
Atlassian released, in July 2021, the last version of the app Training for Jira. This app gives access to Atlassian Training content to Jira users, including videos.
When you install Training for Jira, every user will gain access to training videos from Jira’s Apps menu. They’ll learn:
- Basic terminology and concepts
- How to use Jira to get work done
- How to build reports in Jira
Learn from Atlassian University courses to gain confidence with the tools your team uses every day. Topics include:
- Get Going with Jira Team-managed Projects
- Jira Reporting Basics
- Jira and Confluence Together
Get training for popular Atlassian Marketplace apps. Topics include:
- A Tempo Timesheets Primer
- Intro to Zephyr for Jira Test Cases
- Easy Agile User Story Map
Behind the scenes, the videos are currently in MP4 format (but will migrate to SCORM format soon) and hosted in an external 3rd party e-learning service.
There are already internal discussions around building the Confluence version of the app, but there is not an official roadmap for now.
Finally, uploading custom training content is being discussed but not yet on the roadmap.
Annex | Marketplace apps for HTML Macro | Data Center
Cloud / Data Center / Server
Highlights:
- Embed custom HTML within your Confluence pages with the HTML macro
- Transform XML content from external pages or uploaded files into sophisticated HTML with the XSLT macro
- Set up profiles and app links so users can quickly and safely bring in content from external sources and sites
- Write HTML code directly in the macro body — or import it from a page attachment or outside URL
- Make dynamic on-the-fly edits and regex substitutions with helpful Find-and-Replace features
- Clean up invalid code with a built-in HTML syntax checker
- Enable or disable Javascript use in all HTML macros
- XSLT 3.0 support
- Check out the Data Center version of this app — tested for performance, reliability, and scalability
Data Center / Server
Safely embed a source URL or write custom HTML to include additional material in your Confluence pages. With iframes for Confluence, you can:
- Embed secure iframes into your Confluence pages
- Insert external URLs to add webpages, documents, surveys, charts
- Use the Secure HTML macro to run your HTML code safely
- Attach videos, maps, charts, etc., by adding embedded code from the source page
- Set up frame dimensions using px, em, or %
- Apply Style, ID, and Class attributes to your iframe
- Administrators can configure which sandbox restrictions are allowed in each macro type
- Administrators can Allowlist or Blocklist URLs, domains, or IP addresses that can be used in the Iframe macro
Note: Secure HTML Macro does not work in Internet Explorer.
Was this content helpful?
Connect, share, or get additional help
Atlassian Community