How to enable the YouTube API on oEmbed videos

The Problem

Video is a huge part of the web these days and its growing rapidly for all kinds of applications.

Its use on websites is becoming significantly more common and in some cases this can lead to several videos being included on a page.

One of the most common platforms where these videos are uploaded is YouTube. Displaying them on your website adds another great way to communicate with your audience.

Playing a video in elements such as modals, tabs or accordions can lead to users leaving them playing and moving on. But what if there’s another video they want to play?

Having two videos playing over each over is not a great experience or your user needs to find the other video in the page.

The Solution

The solution to this problem is to add a short function to your functions.php file which will perform a find and replace on the embed URL if it’s a YouTube video.

YouTube embeds have an optional flag to enable the YouTube video API via JavaScript. This API can be used to start, stop, mute or pause the video along other features. This communication takes the form of postMessage, where actions can be sent to the iFrame.

When WordPress includes the oEmbed links into the post it includes a query string to let YouTube know it’s an oEmbed. We can then use this for our replacement and include the parameter enablejsapi=1.

function enable_youtube_api_on_embed($html) {
    if (strpos( $html, 'youtube' ) !== false) {
        $html = str_replace('?feature=oembed', '?feature=oembed&enablejsapi=1', $html);
    }
    return $html;
}
add_filter('oembed_result', 'enable_youtube_api_on_embed', 10, 1);

This function will now include the API parameter and allow access to us via JavaScript to perform actions with the video.

Where can it be used?

As we looked at in our example problem this API allows us to perform actions such as stop the video playing.

This is particalarly useful if we have multiple videos on a page or videos included in elements that can be shown or hidden.

Elements such as these could include:

• Accordions
• Modals
• Tabs

If a user starts a video playing in a modal and then closes it without stopping the video, it will keep playing in the background. This isn’t great for the user particularly if they want to play another video.

Therefore, we should handle as part of this, close or toggle event the stopping of the playing video.

Let’s take a look at how we can handle that interaction with the API.

const iframe = document.querySelector('.open-model iframe'); 

iframe.contentWindow.postMessage('{"event":"command","func":"stopVideo","args":""}', '*');

In the code above we’re getting the iframe element from the open modal with the class .open-model.

Now we have this iframe we are going to use contentWindow to interact with the iframes DOM. This interaction now allows us to use postMessage to send a command to the iframe content.

In this case, we’re posting an event:command and the function we’re calling on the API is stopVideo. This YouTube API watches for these commands that in this instance, stops the video playback. Perfect!

Now a user can open a model, start the video playing and as soon as they close the model the video stops. This prevents videos playing in the background improving the user experiance.