WordPress supports natively lots of embeds from external services, like Vimeo or Youtube, and more recently Spotify and Rdio.

In real life, if you paste a link from a supported service onto the post content area, WordPress will do the magic of transforming that link into html to support the requested service.

But, what happens when you collect that link on a custom field?

Vimeo video link metabox
Vimeo video link custom field

WordPress core magic won’t run over a custom field, leaving to you the responsibility of transforming the link into the proper html, in this case, into the Vimeo player.

In this post I’ll cover some aspects related with Vimeo oEmbed api, WordPress oEmbed filters and I even mention Froogaloop (what?!)…


WordPress comes with a very useful function wp_oembed_get which allows you to use the already developed core process to fetch the oEmbed information for the input url. This is awesome as you don’t need to deal with all the bits of each service oEmbed api.

 $embed_code = wp_oembed_get( $url, $args );

But, for some services like Vimeo, you need more than what is provided by the core, since WordPress only accepts as $args the height and width of the iframe, which is insufficient if you need to tweak a little bit the Vimeo iframe (Vimeo accepts the following api parameters: autopause, autoplay, badge, byline, color, loop, player_id, portrait and title).

A real example:

$embed_args = array(
    'title' => 0,
    'byline' => 0,
    'portrait' => 0,
    'color' => 'eb145b',
    'width' => '1048',
    'height' => '589',
    'player_id' => 'my_player',
$iframe = wp_oembed_get( $url , $embed_args );

 “Play it, Sam” or how to tweak Vimeo embed?

After some investigation and reading I figured it out. Turns out WordPress has two super useful filters that  will make our day in this situation: oembed_fetch_url and oembed_result.

The first one, oembed_fetch_url, allows us to manipulate the url that will query Vimeo API – this is the place where we’ll re-introduce the oEmbed $args neglected by WordPress.

The second filter, oembed_result, will allow us to manipulate the result from Vimeo API response, the ideal place to introduce the player_id on the iframe, needed to control the Vimeo player with JavaScript (using Froogaloop for example).

So, to complete our real example, we need to add two filters to get a tweaked iframe html:

add_filter( 'oembed_fetch_url','add_param_oembed_fetch_url', 10, 3);
add_filter( 'oembed_result', 'add_player_id_to_iframe', 10, 3);

/** add extra parameters to vimeo request api (oEmbed) */
function add_param_oembed_fetch_url( $provider, $url, $args) {
    // unset args that WP is already taking care
    $newargs = $args;
    unset( $newargs['discover'] );
    unset( $newargs['width'] );
    unset( $newargs['height'] );

    // build the query url
    $parameters = urlencode( http_build_query( $newargs ) );

    return $provider . '&'. $parameters;

/** add player id to iframe id on vimeo */
function add_player_id_to_iframe( $html, $url, $args ) {
    if( isset( $args['player_id'] ) ) {
        $html = str_replace( '<iframe', '<iframe id="'. $args['player_id'] .'"', $html );
    return $html;

I gave here an example with Vimeo, but this process can be used to other services like youtube. Enjoy!