Embedding videos and other content in Surreal CMS 5.1


This question is popping up a lot in the forum, so hopefully I can resolve any confusion as to what happened to the media tool in 5.1.

In short, we removed the media tool in favor of the embed tool.

We generally don’t like removing things, but based on usage, an extraordinary number of help requests, and feedback from many users, we felt this was something we needed to do better. Let me explain.

Video Formats

The media tool in 5.0 was based off of TinyMCE’s media plugin. Here’s a screenshot of what it looked like for reference:

To embed a video in such a way that all major browsers would display it, a user had to upload one primary format and then another secondary format. It’s hard enough to get clients to resize an image, much less convert and optimize multiple video formats for their website. (Most just don’t understand why they can’t go from phone to web, and it’s a very complicated thing to explain.)

As of today, the only video format that appears to be compatible among all major browsers is MPEG4/H.264, but iPhones and other popular devices don’t record video in this format, so some type of conversion has to occur, otherwise those video won’t play in every browser.

And what if the format your client uses works in their browser, but not all browsers? :disappointed:

Upload Times

Another big problem was with upload times. Videos are typically quite large, and when you upload one it first gets passed to Surreal (via browser upload) and then we pass it along to your web server (usually via FTP).

Even with just a few megabytes, this can take a long time, and videos are often much larger than a few megabytes. To do it properly, they’d have to go through the upload process twice. This is a terrible UX.

Embedding Is Easier

When we started evaluating this problem, we discovered that most users were using the media tool to simply copy and paste embed code from YouTube and other sources. However, that was hidden behind the Advanced tab in the media modal. Now we’ve made it front and center.

To avoid the aforementioned issues, we strongly recommend using a video hosting service. There are many free and paid solutions available, the most popular being YouTube and Vimeo. Using a proper video hosting service will improve you and your clients’ experience greatly:

  • They’re much easier to use, especially for novice users
  • They handle conversion and optimization for you (no secondary format required)
  • Uploads are much faster
  • Downloads (playbacks) are from a CDN and are much, much faster
  • Videos are optimized for your visitors’ devices
  • Frequent downloads won’t affect your bandwidth or web server’s performance
  • Most providers offer analytics for every video
  • Videos are much easier to embed into the CMS (via copy and paste)

Again, we generally don’t like removing things from the CMS, but in this case the media tool was doing much more harm than good. (One user reported their client didn’t want to use the CMS at all because it was too hard to make a video work!)

The truth is, getting videos to display properly on your website is much more complicated than just uploading and linking to them. Even with the tool available, most clients didn’t do it (or didn’t do it right).


Along with the new embed tool, we’ve added support for over 60 oEmbed providers. This means you don’t even need the embed code. Simply copying and pasting the URL from any YouTube, Vimeo, or similar provider’s page will automatically generate the correct embed code.

Try pasting this link directly into the editor or the embed tool :slight_smile:

I hope that answers any questions about why this decision was made!

New Embed Code (cube icon) method is creating confusion and loss of functionality
Insert Media is missing on 5.1