MP3 Audio Player Plugin

Contents

1. How to use the MP3 Audio Player Plugin + Shortcodes

2. PODCAST: How to setup your first podcast player

3. PODCAST: Automatically fetch/import new episodes based on your Podcast RSS Feed

4. How to add audio directly in a post

5. How to add Buy Now / Add To Cart button with WooCommerce

6. How to update MP3 Audio Player Pro ?

7. Using dynamic custom fields (eg: ACF, JetEngine, Metabox, etc.)

8. Supported Audio Streaming Providers

9. How to use Google Analytics

1. How to use the MP3 Audio Player Plugin + Shortcodes

VIDEO TUTORIAL OVERVIEW

This video will teach you how to use the plugin in 7 quick chapters:
1) 00:12 Install the Plugin
2) 00:32 Create a Playlist & Uploads Tracks
3) 03:44 Add Player using Shortcode
4) 06:57 Add Player using Elementor
5) 10:41 Add Player using Gutenburg
6) 11:27 Customize Color & Settings
7) 12:57 Difference between Free vs Pro


**********
Hey Podcasters! Read this article if you are setting up a podcast first.
**********

DISPLAYING THE PLAYER ON A WORDPRESS PAGE

There are multiple ways to display the player on a page.

1) Elementor : MP3 Audio Player Widget

If you use Elementor Page Builder, you can use Elementor Widget called Sonaar MP3 Audio Player. We have developed a custom Elementor widget called Sonaar MP3 Audio Player that you can find in the Elementor Widget panel. That is the best recommend way to use our player. You can learn more and download Elementor here


2) Elementor : Button Widget

If you use MP3 Audio Pro & Elementor, you can also use the native Elementor Button widget to launch the sticky audio player:


3) Gutenburg Block

Use Gutenburg block editor. The gutenburg block is called MP3 Player by Sonaar. The Pro version adds all the styling options you need to customize the look and feel of your player without any custom CSS code.


4) Shortcodes

An easy way to display or control the audio player on your website is by using shortcode.

We have 2 different shortcodes with many attributes for each of them.

[sonaar_audioplayer] // This is our main shortcode
[sonaar_ts] // This is an optional shortcode used to generate clickable links in your text content to control the player


Player Widget Shortcode: 

[sonaar_audioplayer albums="YOUR_PLAYLIST_ID"]

To add this shortcode, whether you manually copy/paste it in your text content, or generate it with our shortcode generation tool. To generate the shortcode, make sure you are using the classic editor and click the music note icon.

If you have previously created a playlist post in WP-Admin > MP3 Player > Add Playlist, select 'Predefined playlist' in the dropdown, then select the playlist you want.

Once the shortcode has been generated, you can always change the attributes directly in the shortcode text without having to generate a new shortcode. For example, if you want to show the playlist, use show_playlist="true". If you want to remove the soundwave timeline, set hide_timeline="true".

Advanced Users: There is also a more advanced way to add a player without having to create a playlist and by specifying the audio source URL directly. To built a playlist on-the-fly without creating a playlist, select Audio URL Inputs (Advanced) in the Playlist type dropdown (see screenshot: https://d.pr/i/iLjqnz) You will have the ability to add mutliple audio URLs with their track titles directly in the shortcode. Just remember to separates the URL or track titles by || character which is used as a delimiter.

If you want to build something dynamic with custom fields, see our audio_meta_key attributes below.

Shortcode Attributes:

player_layout Choose the player layout. Value: skin_float_tracklist or skin_boxed_tracklist. Default is skin_float_tracklist. eg: player_layout="skin_boxed_tracklist"
albums The Post ID of your playlist post you want to assign to the player. Value: IDs separated by a comma or "all" for all posts. To find out your album ID, see screenshot: https://d.pr/i/KH79f2
eg: albums="55, 57," or albums="all"
category [PRO] Specify the category ID of your post category. Value: category IDs separated by a comma or 'all' for all posts. eg: category="57, 60" or category="all"
audio_meta_field [PRO] If you are using a custom field for your audio URL (eg: you are using JetEngine, ACF, Metabox, etc...), specify the metakey ID of your audio URL. eg: audio_meta_field="my_audio_url_metakey_id"
repeater_meta_field [PRO] If you are using a dynamic repeater group to generate multiple tracks in a post, specify the metakey ID of your repeater group. You must also use audio_meta_field attribute to specify your audio URL (see above). eg: repeater_meta_field="my_repeater_group_metakey_id" audio_meta_field="my_audio_url_metakey_id"
posts_per_page [PRO] Specify the number of posts to load in the player. Value: integer. eg: posts_per_page="5"
play-latest When set to true, the player will automatically takes the latest published playlist posts in WP-Admin > MP3 Player > All Playlists. Value: true or false. eg: play-latest="true"
feed Set audio URLs delimited by || character. Eg: feed="https://yourdomain.com/01.mp3 || https://yourdomain.com/02.mp3"  --  See this article for supported streaming providers.
feed_title If you have used the feed attribute, you will want to use feed_title to set your track title names. Delimited by || character. Eg: feed_title="Title 01 || Title 02" .
feed_img
show_playlist Display the tracklist or not. Value: true or false. eg: show_playlist="true"
display_control_artwork Display play buttons in the playlist artwork image. Value: true or false. eg: display_control_artwork="true"
hide_artwork Hide your album cover image. Value: true or false. eg: hide_artwork="true"
hide_timeline Remove progress bar and controls. Value: true or false. eg: hide_timeline="true"
hide_control_under Remove controls but keep progress bar. Value: true or false. eg: hide_control_under="true"
reverse_tracklist [PRO] Reverse the tracklist order. eg: reverse_tracklist="true". Value: true or false. eg: reverse_tracklist="true"
hide_progress [PRO] Remove progress bar, keep controls. Value: true or false. eg: hide_progress="true"
hide_times [PRO] Remove time and durations beside the progress bar. Value: true or false. eg: hide_times="true"
hide_album_title [PRO] Remove album title in the TRACKLIST. Apply only to Floated Player. Value true or false. eg: hidhide_album_title_player_title="true"
hide_player_title [PRO] Remove album title ABOVE the Soundwave Bar in the player. Value true or false. eg: hide_player_title="true"
hide_track_title [PRO] Remove Track Title above the Soundwave Bar. Value: true or false. eg: hide_track_title="true"
progressbar_inline [PRO] Display Prev/Play/Next button inline with the progress bar. Value: true or false. eg: progressbar_inline="true"
show_meta_duration [PRO] we will calculate the sum of each track's duration and will display the total amount of the duration in the player. Value: true or false. eg: show_meta_duration="true"
show_publish_date [PRO] We will display the published date of the current Playlist/Episode that is being played within the player. Value: true or false. eg: show_publish_date="true"
show_tracks_count [PRO] Sometimes its useful to let your visitor knows how many tracks contains the playlist. We will show this label in the player. Value: true or false. eg: show_tracks_count="true"
show_skip_bt [PRO] A listener just missed something in your track? Add a 15 seconds backward button so he can quickly catch-up. Same thing if he want to quickly skip a segment or two. Value: true or false. eg: show_skip_bt="true"
show_shuffle_bt [PRO] Allow the ability to shuffle the tracks randomly within the Playlist. Value: true or false. eg: show_shuffle_bt="true"
show_speed_bt [PRO] A speed rate button gives your user the ability to change the playback speed from 0.5x, 1x, 1.2x, 1.5x and 2x. Value: true or false. eg: show_speed_bt="true" 
show_volume_bt [PRO] We will add a volume control in the player so the user may adjust the volume level. The volume level is retained in its browser session. Value: true or false
strip_html_track_desc [PRO] We will remove HTML tags in your track description to prevent unwanted styling. Value: true or false. eg: strip_html_track_desc="true"
track_desc_lenght [PRO] Specify the amount of words a track description can contains. We will display [...] once it reaches this max amount. Value: integer. Default is 55. eg: track_desc_lenght="55" 
hide_trackdesc [PRO] We will hide the description in the tracklist but we will keep an info icon so people can reach it. Value: true or false. eg: hide_trackdesc="true"
show_cat_description [PRO] We will show the category description set in MP3 Player > Podcast Show. Apply to Podcast only.  Value: true or false. eg: show_cat_description="true"
album_store_position [PRO] Apply to boxed player only. Show external link buttons direcly in the boxed player instead of below the playlist. Value: "top". eg: album_store_position="top"
show_track_market Display your track’s store icons beside each of your track. Value: true or false. eg: show_track_market="true"
show_album_market Display your playlist’s store icons below your playlist. Value: true or false. eg: show_album_market="true"
store_title_text Change Available Now by any string. Value: String. Default: “Available Now”. eg: store_title_text="Listen On"
wave_color Specify the color of your waveform to bypass the plugin setting’s color. Value: hexa color. eg: wave_color="#E81538"
wave_progress_color Specify the color of your progress bar over your waveform to bypass the plugin setting’s color. Value: hexa color. eg: wave_progress_color="#FFBCC6"
titletag_playlist Heading tag above the playlist for SEO purpose. Value: h1, h2, h3, h4, h5, h6, div, span, p. eg: titletag_soundwave="h3"
titletag_soundwave Heading tag of the title above the soundwave for SEO purpose. Value: h1, h2, h3, h4, h5, h6, div, span, p.  eg: titletag_soundwave="h4"
sticky_player [PRO] Enable sticky player. Value: true or false. eg: sticky_player="true"
track_artwork [PRO] Display thumbnail images beside each of your track in the playlist. Value: true or false. eg: track_artwork="true"
scrollbar [PRO] Enable scrollbar within tracklist. Value: true or false. eg: scrollbar="true"
shuffle [PRO] Enable shuffle. Value: true or false. eg: shuffle="true"
notrackskip [PRO] If set to true, player will stop when current track has completed to prevent play next track automatically. Value: true or false. Default false.
no_loop_tracklist [PRO] If set to true, player will stop when current playlist has completed to prevent playlist to restart automatically. Value: true or false. Default false. eg: no_loop_tracklist="true"
id Optional attribute used to set unique ID so we can target this player for the sonaar_ts shortcode. View shortcode sonaar_ts below for usage. Value: Alphanumeric value, no special character, no space. eg: id="my_featured_player". 


A final example would be something like this:

[sonaar_audioplayer albums="6" sticky_player="true" hide_artwork="false" show_playlist="true" show_track_market="true" show_album_market="true" wave_color="#000000" wave_progress_color="#CCCCCC"][/sonaar_audioplayer]


Text Shortcode for Text Links, Chapters and more [PRO only]

[sonaar_ts]Play Now[/sonaar_ts]

When using this shortcode, the text within the shortcode will be converted into a clickable action link.

If you don't specify any attribute just like the example above, we will try to play the first audio player widget found above this shortcode. If there is no player found on the page, we will try to play the tracks set in our tracklist custom fields set for the current page.

You can also use the following attributes:

Shortcode Attributes:

widget_idSpecify the player widget id to be targeted. eg: widget_id="my_featured_player". To set a player ID on your player's instance when using sonaar_audioplayer shortcode, use the id attribute.
post_idSpecify the playlist post ID to be targeted. This will launch the sticky player, eg: post_id="55"
timeSpecify the starting time stamp. Useful to create chapters and table of content. eg: time="2:27". this will start the player at time 2:27.
track_idSpecify the track number to be targeted. eg: track_id="4"

Final example would be something like this:

[sonaar_ts]Play Now[/sonaar_ts]
Chapter 01: The Introduction[sonaar_ts time:"2:27"]2:27[/sonaar_ts]
Play the [sonaar_ts post_id="55" time:"2:27"]Episode 02 in the Sticky Player[/sonaar_ts]


5) Using Javascript API

You can use some javascript code to call the STICKY Footer player and its functions. The code below only belong to the STICKY player.

IRON.sonaar.player.play()
IRON.sonaar.player.pause()
IRON.sonaar.player.setPlayerAndPlay({ id:"1218"})
IRON.sonaar.player.setPlayerAndPlay({ id:"1218", trackid:"0"})

id:"1218" is the post ID of your playlist post type you want to play. To find out your post ID, see screenshot: https://d.pr/i/KH79f2

trackid:"0" would be the first track of the playlist, trackid:"1" the second track, trackid:"2" the third track.

Here is a list of all attributes parameters available: "id", "trackid", "shuffle","soundwave" and "notrackskip".


sonaar_ts_shortcode({id:"", widget_id:"", trackid:", time:""}) //eq: params = "{ id:'19', time: '0:10'}"<span></span>

id:"1218" is the post ID of your playlist post type you want to play. To find out your post ID, see screenshot: https://d.pr/i/KH79f2

widget_id:"my_featured_player" would target the player ID my_featured_player set in your DOM.

time:"10:00" would start the player at 10 minutes.

trackid:"1" would be the first track of the playlist, trackid:"2" the second track, trackid:"3" the third track.

------------------------------------------------------------------------------------------------------------------------------------------------------------

If you want to trigger click on the NON sticky player (aka free player), you can use this JS code:

jQuery('[data-albums="75"]').find('li:nth-child(2) .audio-track').trigger( "click" );


MANAGE OVERALL SETTINGS AND COLORS:

To manage the color and font settings, go to WP-Admin > MP3 Player > Settings.

USING SAME LAYOUTS/TEMPLATES AS THE DEMO PAGE

The player's layouts you see in the examples of our demo page is a Sonaar's pro feature and are styled with Elementor. You must use Elementor in order to skin them exactly like this along with our Pro Version. Elementor plugin is free.

To use the same design than in our examples:

1. Make sure Elementor Page Builder plugin is installed and activated. To install it, go to WP-Admin > Plugins > Add New and search for Elementor.

2. Go to Templates > Saved Templates and click the Import Templates button. See screenshot: https://d.pr/i/saZbBO

3. Import the file called "elementor-templates-for-mp3-audio-player-pro.zip". You can download it here

4. Your imported template will now be displayed in your Templates list.

5. To use and insert templates into the page builder, read this article from Elementor Documentation: https://docs.elementor.com/article/60-library


Tips & Tricks Code Snippets:

Enable No Track Skip attribute on all player of your website automatically

Add this to your theme's child function.php

add_filter( 'srp_track_skip_attribute', 'your_prefix_function_callback', 10, 1);
function your_prefix_function_callback($arg) {
    return "on";
}




2. PODCAST: How to setup your first podcast player

Using MP3 Audio Player for Podcasting is awesome. Here are some quick step to get you started.

  1. Enable Podcast by going to MP3 Player > Settings.





  2. Choose Boxed Player in the Player Layout



  3. If you use the PRO version, you can enable some useful podcast control buttons



  4. Go to Tools / Import tab and click Import Your Existing Podcast Episodes



  5. Enter your RSS Link URL provided by your Podcast Distributor. We will import all your episode included in the feed. If you have many many episodes, you may have to run this several times because your server might time out. Don't worry, it will resume automatically.



  6. Check your Imported Episode in MP3 Player > All Episodes


  7. To display a player containing all your episodes, you can use Gutenberg Block, Elementor Widget or our shortcode and attributes. To learn more on how to display a player, see this article

  8. If you are using the pro version and have an active license, you have the option to import the episodes that your RSS feed contains at a chosen interval. Learn More


If you have questions or feedback, let us know by opening a support ticket and we will gladly help you out.

3. PODCAST: Automatically fetch/import new episodes based on your Podcast RSS Feed

If you are using the pro version and have an active license, you have the option to import the episodes that your RSS feed contains at a chosen interval . To do this, you need to set up a recurring timer also known as a "cron job".

Follow these steps:

1. Install WP Crontrol plugin and activate it.

2. If you have not already created a show in WP-Admin > MP3 Player > Podcast Show, do it now.

3. Go to WP-Admin > Tools > Cron Events > Add New

4. Use these settings:


Hook name:

sonaar_podcast_import

(very important to have the exact same hook name)


Arguments: 

[{"cat_id":"262","feed_url":"https://yourpodcasthosting.com/rss.xml"}]

5. Replace the number 262 by your Podcast Show ID. Keep the double quotes!
To find out your podcast show ID, go to WP-Admin > MP3 Player > Podcast Show > Edit your Show.
See screenshot: https://d.pr/i/roXIYC 

6. Replace 'https://yourpodcasthosting.com/rss.xmlby your own RSS URL. Keep the double quotes!

7. Set your next run and its recurrence (important!). We recommend Twice Daily or on Once Daily. You don't want to run the cron job too often because it can slow down your website.

8. Click Add Event.

* If you want to force the cron job to run now, you can always manually trigger it by hover the cron title and click RUN NOW. See screenshot https://d.pr/i/IPJ80c

* If your new episodes do not import, make sure they are NOT already present in WP-Admin > Podcast Episodes and also that they are NOT in your trash. See screenshot https://d.pr/i/9mpX8B

4. How to add audio directly in a post

Adding audio in any kind of post without creating a playlist is pretty easy.

1) Install and Activate MP3 Audio Player Pro by Sonaar.

2) Go to WP-Admin > MP3 Player > Settings and enable the post type you want. See screenshot: https://d.pr/i/nV2mNo

3) Edit your post and now you will be able to upload/insert a track. See screenshot: https://d.pr/i/GJbWAq

4) Add the player anywhere in the post. You can use either our Elementor Widget MP3 Player, Gutenburg block or simply use the shortcode below:

[sonaar_audioplayer]

View all shortcode attributes available here


5. How to add Buy Now / Add To Cart button with WooCommerce

Displaying audio players in a WooCommerce product is pretty easy using our MP3 Audio Player Pro with WooCommerce edition.

STEP 1

1) Install and Activate MP3 Audio Player Pro by Sonaar with WooCommerce edition (https://d.pr/i/Wsm2qB)

2) Go to WP-Admin > MP3 Player > Settings and enable Product. See screenshot: https://d.pr/i/nV2mNo

3) Edit a WooCommerce product and now you will be able to upload/insert a track. See screenshot: https://d.pr/i/GJbWAq

4) Adjust the WooCommerce setting within our player to your needs. see screenshot: https://d.pr/i/h0jFku The options you see on this screen are pretty self-explanatory.

5) You can adjust the player setting to be display in your shop loop page, or in your product detail page here: https://d.pr/i/b0ctkv 
If you want to use a custom shortcode player for the product detail page, enable Custom Shortcode https://d.pr/i/xZolaD

For ever product that has tracks uploaded, you have the ability to show/hide an add to cart / buy now button beside your player's track: https://d.pr/i/RW2ii1

6. How to update MP3 Audio Player Pro ?

In order to update your plugin, you must have an active subscription at sonaar.io.

First of all, like any themes, plugins, or WordPress updates, we recommend testing on a staging environment first and have a backup copy of your existing site before the update in case something wrong happens. You can check with your hosting provider to make sure they have backup retention enabled.

Automatic Update

1) The best way to update your plugin is to go to WP-Admin > Dashboard > Updates. Select the plugin and click "Update".

2) Once the plugin is updated,  update the Free version as well, if there is any update available.

3) Make sure to clear your browser cache, website cache, and server cache if you use any (eg: CloudFlare, CDN, Varnish).

4) If something wrong after the update, in 99% of the case the issue is because caches have not cleared properly (see step 3 above).

* If you are using a WP Multisite or multi-network and/or you can't see the plugin update, you must update the plugin manually. See below.

Manual Update

1. Login at sonaar.io/login and go to My Account > Licence Keys > and click View Details and Download and re-download the plugin file on your computer.

2. Go to Wp-Admin > Plugins and deactivate the Pro plugin.

3. Delete the Pro plugin. (Yeah, it sounds scary, but don't worry. You must delete the current plugin before re-uploading the new plugin. Don't worry, you wont lose anything).

4. Go to WP-Admin > Plugins > Add New and Upload the plugin zip file.

5. Activate the plugin by clicking the "Activate button".

6. Make sure to clear your browser cache, website cache, and server cache if you use any  (eg: CloudFlare, CDN, Varnish).

7. If something wrong after the update, in 99% of the case the issue is because caches have not cleared properly (see step 3 above).


7. Using dynamic custom fields (eg: ACF, JetEngine, Metabox, etc.)

Since version 3.2, MP3 Audio Player Pro supports dynamic custom fields for Advanced Custom Field, Jet Engine, Metabox, CMB2, etc..)

To display a dynamic player on a specific post, you must set your audio URL custom field ID. If you are using multiple tracks and using a group repeater, you must also specify the repeater group custom field ID.

You can specify the custom field ID by using our shortcode attributes, or use our Elementor widget which have an option to set your custom fields.

Important note: As we speak, the track title, album name, artist name, and other tags are fetched automatically through the ID3 tags of the MP3 file. To fetch the ID3 tag, your MP3 file must be located on the same URL of your website otherwise this will not work for security reasons.

Using Shortcode

If your player will contain only 1 track:

[sonaar_audioplayer audio_meta_field="my_audio_url_metakey_id"]

If your player will contain multiple tracks and are using a group repeater:

[sonaar_audioplayer repeater_meta_field="my_repeater_group_metakey_id" audio_meta_field="my_audio_url_metakey_id"]

For a complete list of shortcode attributes available, see this article.

Using Elementor Widget

In the example below, we see that we have created a custom post type using JetEngine. 

1) We have created one repeater group with custom field ID called '"audio-repeat", and a text custom field for the audio source URLs called "tracks".

2) We have created a dynamic single post template for this custom post type (Using Elementor Pro's theme builder).

3) We have added the MP3 Audio Player Elementor widget. In the widget, we have set the "Source" as "Current Post".

For the Audio Source Metakey ID, we have binded it to the item's repeater field ID. For the Repeater Group Metakey ID, we have binded it to the Metafield ID which represent the Repeater Group.



8. Supported Audio Streaming Providers

You can play audio files that are hosted either on your own server or on external and streaming servers. We support a lot of them, but some providers have restrictions. 

We have tested all of the following:

- Local .MP3 file
- Local .M4A file
- Icecast
- Libsyn
- Stitcher
- Shoutcast
- Acast
- Amazon S3
- FMStream.org- Podbean
- SoundCloud Podcasts
- Buzzsprout
- Simplecast
- Spreaker
- Audioboom
- CastBox
- Pippa.io
- Anchor
- Cloudup
- Google Drive / Dropbox (not recommended because it's very slow to load because of their security and permission checks)

You cannot stream directly from the services below:
x Spotify
x SoundCloud Music
x Apple Podcast
x Google Podcast
x YouTube
x MixCloud

We also support a lot of other providers that are not listed here but we have not tested all of them. If you have a provider that is not listed here and is supported. let us know so we can add it to this list.

9. How to use Google Analytics

Starting from version 3.1, MP3 Audio Player Pro allows you to connect the players to your Google Analytics so you will have the ability to view real-time and past events of a number of plays and downloads right into your Google Analytics reports.

In this tutorial, we assume you have already created your Google Analytics account and you have entered your Tracking code in WP-Admin > MP3 Player > Stats & Report > Tracking Code

 

In Google Analytics, you can now see real-time events, as well as past events of plays and downloads for each playlist but also for each track.

Realtime View:

To view real-time events, a.k.a. "what is being played on your website right now", go to Realtime > Events > Events (Last 30 min)

Here you can see that the Playlist (or Podcast Show) called Dr. Death | S1: Dr.Duntsch has been played 4 times during the last 30 minutes, and there was 1 download for the Playlist called Epigram.

If you click that Playlist name, you will see which specific tracks have been played or downloaded:

Above you can see that 2 tracks of the Dr Death | S1 have been played 2 times each during the past 30 minutes.


Overall View

If you want to see all stats for a certain periode of time, go to Behavior > Events > Top Events

Above, you can see that during the period of December 21 to December 22, there have been 31 total events that include both play and downloads. Between these numbers, you can see that Dr.Death Playlist has been played 11 times and 1 person has downloaded a track in the Epigram Playlist.

If you click on each playlist, you will see details of which track have been played or downloaded.


Most Played Track

If you wish to view top most played or downloaded tracks, click Event Label.

An important notion in GA is that Event Category = Playlist Names, Event Label = Track Names and Event Action = Type of the event such as a Play or a Download.

Save Report to Dashboard

Google Analytics can be customized is hundreds of ways and sometimes it can be an overwhelming task just to set up the reports. We recommend you add your favorite widget table to your Analytic Dashboard for quick access.

Watch Video to learn how to save a widget to GA Dashboard