Author: Luigi Pulcini

WavePlayer has the capability of overriding the WordPress default audio player. This means that, right after installing WavePlayer, all the shortcodes you have already inserted in your post will be replaced with WavePlayer automatically, without any need to re-edit your posts or change anything in your configuration. Of course, we strongly encourage you to deactivate any other audio player plugin, ensuring that there are no conflicts in your configuration and the overriding function works without interferences.

Please also note that when the URL you are using to add a player with any of the following methods corresponds to an audio attachment in your Media library, WavePlayer is capable of retrieving all the metadata stored in the database pertaining to that audio attachment. This guarantees that you can take advantage of all the extra features WavePlayer associate to your internal files (e.g. play statistics, likes, downloads, etc.), even when adding a file using its URL rather than its attachment ID. Although this latter method is always preferred, the capability of retrieving an attachment ID from the URL of the attached file makes the two result practically indistinguishable.

The following examples demonstrate that WavePlayer can override the default WordPress audio player with all the possible audio-related shortcodes or even the RAW URLs typed in your post.

Overriding the audio and playlist shortcodes

The player above is added in the post editor using the following shortcode:

[ audio mp3="https://media.waveplayer.info/wp-content/uploads/2020/04/0203.mp3"][/audio]

Overriding the embed shortcode

The player above is added simply pasting the URL of the audio file directly in the post editor, like this:

[ embed]https://media.waveplayer.info/wp-content/uploads/2020/04/0203.mp3[/embed]

Overriding the inline URL in the text

https://media.waveplayer.info/wp-content/uploads/2020/04/0203.mp3

Starting from version 2.3.1, it is now possible to embed WavePlayer inside other websites using an <embed> element.

WavePlayer 2.3.1 comes already with this capability, but you need to add an embed-attachment.php file to your Child Theme.

When WordPress finds that file in your Theme root folder, it uses it to display an element from your website inside an <iframe>. If you want to read more about this technique, you can refer to this article in the WordPress documentation.

The embed-attachment.php template file

Let’s start with a basic structure of the embed-attachment.php file.

<?php
get_header( 'embed' );
if ( have_posts() ) {
    while ( have_posts() ) {
        the_post();
        echo do_shortcode("[ waveplayer ids='" . get_the_ID() . "']");
    }
} else {
    get_template_part( 'embed', '404' );
}
get_footer( 'embed' );
?>

Compared to the usual single.php, the file embed.php (or, in this case, embed-attachment.php) adds the name ’embed’ to get_header() and get_footer(). We then see the main query looping among all the results. Since this is going to be used on a single attachment post, the query is going to return only one result: the page of the attachment we want to embed inside an external website.

How do we get the right link to be used in the embed element? It is pretty easy. Just go to the Media library and click on the thumbnail of the audio attachment you want to embed. In the right bottom corner, look for the link “View Attachment Page“, right click on it and choose “Copy link address” (or, alternatively, click on it and copy the URL in the address bar of the browser).

Now, it is just a matter of typing the right embed code inside the website where we want to publish our attachment. The embed code looks like this:

<embed height="220" src="https://www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true">

Please note that, in order for this to work, it is important that you add embed=true at the end of the link. You need also to pay attention to the structure of the URL you copied. If the URL already contains some arguments, like the following one:

www.waveplayer.info/?post_type=attachment&p=1614

then you have to add embed=true at the end of the URL prefixing it with an ampersand (&) like this:

www.waveplayer.info/?post_type=attachment&p=1614&embed=true

On the contrary, if your URL is a permalink like this:

www.waveplayer.info/10197133_wedding_by_audiopizza_preview/

you have to prefix embed=true with a question mark (?), like this:

www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true

A simple rule of thumb to better understand whether you need to use a question mark or an ampersand is checking the URL you have before adding the embed argument. If the URL already contains a question mark, then it means you need to add the embed argument prefixing it with an ampersand. If the URL doesn’t contain a question mark, then you need to use that to add the embed argument.

Providing additional arguments

You can also pass additional arguments to the URL you embed, so that you can alter the aspect and the property of your embedded WavePlayer instance. For example, the following example pass the size and the shuffle argument to the embedded player:

www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true&size=large&shuffle

Of course, we have to make some adjustments to the embed-attachment.php file as well, so that we process the additional arguments. The following code retrieves the size and shuffle arguments from the URL and incorporates them into the shortcode:

<?php
$args = array();
if ( isset( $_GET['size']) ) $args[] = "size='$size'";
if ( isset( $_GET['shuffle'] ) ) $args[] = "shuffle='true'";
$args = implode( " ", $args);
get_header( 'embed' );
if ( have_posts() ) {
    while ( have_posts() ) {
        the_post();
        echo do_shortcode("[ waveplayer $args ids='".get_the_ID()."']");
    }
} else {
    get_template_part( 'embed', '404' );
}
get_footer( 'embed' );
?>

By following the example above, you can add as many arguments as you like to the embedded URL, adjusting the WavePlayer instance to your needs.