MP3 Audio Player Plugin

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";
}