Video files in Confluence: Problems with the multimedia macro and tips

Videos are also becoming more important in internal communication. They are often indispensable for technical documentation. Employees want to share tutorials and demos with each other. During on-boarding, instructions help new colleagues train for the job on their own. Confluence or a Confluence-based intranet with Linchpin is the ideal platform to centrally provide such content within a company. It works great with web videos, but there are still occasional problems with uploaded video files.

Ideal solution: Widget Connector

Confluence generally supports multimedia formats and videos incredibly well. The best and simplest way to add a video to a page is to use an online video such as from YouTube. The link address must be copied and pasted in the desired position in the editing mode. The Widget Connector in Confluence Editor will automatically render a placeholder. The video dimensions can also be customized by clicking the Widget Connector and then the "Edit" button. Once the page has been saved, Confluence produces the familiar YouTube player with the video ready to go. Vimeo and MySpace videos are also supported.

Integrating videos with the multimedia macro: simple in theory

Mind you, not every team will upload their videos with instructions, tutorials, etc. to a YouTube channel, or won't want to do so for various reasons. The material exists locally in a file format. For cases like this, Confluence offers the multimedia macro. Videos are uploaded as attachments and then inserted together with a simple player using the macro. The macro configuration can be set so that videos start automatically once the page is loaded (Autoplay).

There are problems with certain constellations, however, which Atlassian apparently has not vigorously sought to solve - for example, displaying comments for the relevant (closed) issue in the manufacturer's public Jira instance.

Problems are hard to reproduce in practice

In many cases, everything works fine, but not in all cases. Sometimes, videos won't scale or aren’t displayed at all. Or the controls for the player are missing or don't exist. Some videos start automatically even though Autoplay has not been activated. This is annoying because the feature is supplied natively with Confluence and is officially supported.

We have tested this feature in several configurations. We would like to show you the results in a nice overview table but unfortunately cannot provide you with this. The problems are not easy to reproduce. With the same configuration and browser version, the result is correct in one case and not in another. To the best of our knowledge, the problems are due to file format issues.

This is unsatisfactory, but we must make do with a feature that does not always deliver what it is supposed to. The following tips may help in a jam.


Use Chrome
Configurations with the Firefox browser seem to cause more problems for the multimedia macro. But the problems in Firefox cannot be reproduced. The Confluence page with the integrated MP4 video in Firefox version 39 displays correctly on my colleague's Mac, yet with the same browser version on my Mac, the video does not scale (it displays only a section that looks like a picture) and there are no player controls. Chrome proved itself to be less prone to errors in our tests. If you can, switch to Chrome.

Manually restore the original resolution
As mentioned before, the multimedia macro sometimes does not scale videos. If only a preview section but no player control elements are visible, it might help to set the video resolution back to the original format and add a few pixels to the height setting in the macro settings. If the uploaded video is 1,280×720 pixels, set the width to 1,280 pixels and the height to 730 Pixels. The control elements (play, time bar) may now be visible. (If this workaround works, you should use lower resolution videos such as 640×360 so that your pages are not broken by oversized videos.)

Work with unlisted YouTube videos instead of attachments
YouTube lets you upload videos that are unlisted. This means only people who have the link to a video can view it. It is not listed in the YouTube channel and cannot be found by searching for it (cannot be viewed publicly). However, it can be embedded like any other video on external sites and can even be inserted via Widget Connector in Confluence. We frequently use this option without any problems. (You can find more information about YouTube privacy settings here.)

The status quo is undesirable, and it's a shame that we cannot offer you up-to-date instructions on how to insert uploaded videos correctly in Confluence. We hope Atlassian takes the matter up again and stays on it, so that this key function receives optimum support in the future.

We are your Confluence partner!

Do you have any questions about Confluence? Are you thinking about implementing Confluence or do you want to optimize or expand an existing system? We are one of the largest Atlassian experts worldwide with experience from hundreds of Confluence projects and will gladly help you with everything you need to implement it successfully: evaluation, licensing, customization, scaling, hosting, plugin development.  Feel free to contact us with no obligation.

LINCHPIN: 100% Social Intranet with Confluence
Enterprise Wikis: Criteria and important topics in the evaluation of wiki software

Diesen Beitrag auf Deutsch lesen.

Forget Less and Ensure Quality with didit Checklists for Atlassian Cloud Forget Less and Ensure Quality with didit Checklists for Atlassian Cloud Forget Less and Ensure Quality with didit Checklists for Atlassian Cloud
Our blog articles reflect the situation at the time of writing and are not updated. It is therefore possible that the contents are outdated and no longer correspond to the latest developments. We do not accept any liability for this.

Leave a Reply