How to customize the info templates of the info bar, playlist row and sticky player

Infobar and Playlist templates

WavePlayer allows you to personalize the information displayed in the info bar and each playlist row. If you want to customize the info templates, you can go to the Settings > WavePlayer page on the Dashboard of your WordPress installation. In the Placeholders tab, you will find three text areas that you can customize using plain text or HTML syntax, together with audio tags and special placeholders, as explained below.

Each audio tag or placeholder you want to display in the Infobar or the Playlist must be listed in the respective text area, surrounded by the ‘%’ character.

For example, if you want to show the title of a track, you can use the %title% audio tag.

Please refer to the following lists of audio tags and special placeholders to learn what you can show in the Infobar and the Playlist of your players.

Audio Tags

Depending on the format of the audio tracks you upload on your website, the file may include one or more tags containing the audio track’s information. For an MP3 file, those tags are called ID3 tags and you can edit them with several different media players (such as iTunes, Windows Media Players) or other specialized applications. If you edit a file’s tags prior to its upload, WordPress can grab all of them and save the information in the database for future reference.

This is a list of the most common audio tags you can usually find in an MP3 audio file:

%album%, %artist%, %bitrate%, %bitrate_mode%, %channelmode%, %channels%, %compression_ratio%, %dataformat%, %encoder_options%, %file%, %fileformat%, %filesize%, %genre%, %length%, %length_formatted%, %lossless%, %mime_type%, %sample_rate%, %title%, %year%.

Special placeholders

In addition to the previous audio tags, WavePlayer allows you to customize the Infobar and each playlist row using the following placeholders. When rendering a player instance, WavePlayer will replace each placeholder with the respective piece of information, icon or buttons, depending on the placeholder you use.

This is a list of the placeholders you can use:

%likes%: a like button and a counter of the total likes for a given track,
%downloads%: a download button and a counter of the total downloads for a given track,
%cart%: a cart button (an active WooCommerce installation is required),
%play_count%: a counter of the total playbacks for a given track,
%runtime%: a counter of the total time a given track has been listened to,
%share%: a share button allowing to share a track on Facebook, Twitter or LinkedIn
%genres%: a list of all the terms of the Music Genres categories the track is associated with
%separator%: a visual divider to push all the placeholders inserted after it to the right side of the container

NOTE: a like button can only be used by your logged in users and registers their likes on your website independently from any other social network.

Custom metadata

In addition to the default metadata WordPress automatically extracts from the audio files and store in the attachment metadata structure of each audio attachment, you can create any other custom metadata to use with your placeholders. For example, if you add a metadata called external_url, you can add it to the infobar or the playlist row simply using the %external_url% placeholder.

WavePlayer 2 introduced a waveplayer_add_track_info filter hook that allows you to add any custom value to any track object. In the following example, the callback function your_custom_track_filter is associated to the filter waveplayer_add_track_info. The callback function receives three parameters: $track is the track object; $track_id is the ID of the audio attachment in your media library; $post_id is the ID of the post or page that contains the instance of the player loading the track.

function your_custom_track_filter( $track, $track_id, $post_id) {
    
    // do something here to generate the value you want to assign
    // to the 'your_custom_meta_key' placeholder
    
    $track['your_custom_meta_key'] = $your_custom_meta_value;
    return $track;
}
add_filter( 'waveplayer_add_track_info', 'your_custom_track_filter', 10, 3);

When WavePlayer finishes loading all the default information into the track object, it invokes the filter so that you can add as many custom values as you like. In the example above, the your_custom_track_filter function uses the input parameters to retrieve the custom information your_custom_meta_value that you want to add to the your_custom_meta_key placeholder.

Simply adding the code above to the functions.php file of your theme/child theme, a new your_custom_meta_key placeholder will be available for you to use anywhere in the Info Bar or the Playlist Row templates.

Custom placeholders

In addition to the built-in placeholders, it is possible to add custom placeholders that do not correspond to any specific information in the audio track metadata. For example, custom placeholders can be used to add a custom button that triggers a custom event, to which a custom callback function can be attached (you can read the article about how to add a loop toggle button). When doing so, one or more attributes – described in the following section – should be provided, otherwise, the simple addition of the placeholder would not be able to output anything.

Consider the following placeholder:

%custom_placeholder{"event":"myCustomEvent","icon":"fa-bullseye"}%

In that definition, the name of the placeholder is arbitrary and totally irrelevant, so long as it doesn’t conflict with a factory placeholder or an existing meta value. The event property instructs WavePlayer to trigger a myCustomEvent event whenever the placeholder is clicked. Finally, the icon property tells the placeholder to use the fa-bullseye icon from FontAwesome.

Now that we have a custom icon triggering a myCustomEvent event when clicked, we only need to add a callback to that event. We do that by simply adding the following code to the Custom JS box in the Advanced section of the WavePlayer settings.

$('.waveplayer').on('myCustomEvent', (event) => {
    alert('This is a custom button triggering a custom event that you can then intercept and associate to any script.\n\nThe current track is ' + event.detail.track.title + ' by ' + event.detail.track.artist )
});

As you can see, a custom even always carries the track currently being played in the event.detail.track object. This way every track property can be used in the event callback, as it is shown in the example above.

Placeholder attributes

The placeholder functionality comes with a list of attributes that help you get the best result for your design. This is a comprehensive list of attributes currently available in WavePlayer.