Wordpress Audio Filter

Thank you for purchase. If you have any questions that are beyond the scope of this help file, please feel free to send a message on the link. Thanks so much!

• codecanyon.net/user/Tean

How to install

Make sure you extract downloaded file from codecanyon, inside you will find file named: 'apwaf.zip'. This is the plugin file you upload in wordpress panel!

Activate plugin

After you install plugin you will have to activate your license to start using the plugin.

To activate license you need to create account on the following link, where you will provide your PURCHASE CODE, and get TOKEN in return which you will then enter in plugin section to activate the plugin.

Instructions how to register

Access control panel here

This is made to make sure customers use the license on a single project (as per Envato rules) and to help customers owning many licenses to easily track on which server licenses are being used.

How to update

After you create a player and a playlist and generate shortcode in Shortcode section shortcode will look like this:
[apwaf player_id="PLAYER_ID" playlist_id="PLAYLIST_ID"] [apwaf player_id="1" playlist_id="1"]

playlist_id can contain multiple playlist id's. This means that multiple playlists will be loaded at once in the player.

You can also load all playlists with "all" in shortcode:

How to add songs to playlist?

Inside Playlist manager -> Create new playlist -> Then go to Edit playlist section. Inside you will have following options to add songs.

1. You can add single songs.

2. You can upload multiple songs at once from WordPress media libaray.

3. You can upload folder of songs. There are 2 ways to do this:

a) Plugin creates waf-file-dir folder inside WordPress uploads directory which will be used for reading audio files. If this folder is not present in your WordPress uploads directory you can create it manually. Place your folder with songs inside waf-file-dir and enter folder name in field:

b) Place folder on some custom location your server and enter full url to your folder:

To get full url to your folder use locate_directory.php file located in (documentation / misc directory in plugin package). Copy this file to your custom directory, right click and open it in browser. You will get full url which you then enter in field:

Note: when adding songs over folder, its possible to read song genre(s) from ID3 tags and save them as filter automatically. For more info check ID3 tags genre filter section.

If you dont want to show all songs on start, you can use pagination. This is advised if you have many songs so not all songs are loaded on start which would slow the player load. Different kind of pagination type exist.

Pagination options are located in Edit player / Pagination tab:

Audio wavefrom is automatically created when you add songs to playlist inside Playlist manager / Edit playlist.

You can adjust look af the waveform inside Edit player / Waveform tab:

Waveform style

Here are couple of waveform examples, to create such waveforms use following settings:

Settings:

waveBarWidth: 5,
waveBarRadius: 3,
waveBarGap: 5,
    

Settings:

waveBarWidth: 1,
waveBarRadius: 0,
waveBarGap: 5
    

Settings:

waveBarWidth: 0,
waveBarRadius: 0,
waveBarGap: 0,
    

Filter layout can be pill style. In this layout text filters (like Artist) are shown in pill style.

Adjust settings for this layout in Player manager / Edit player / Filters tab:

Filter layout can be pill style with text dropdowns. In this layout text filters (like Artist) are shown in dropdown style.

Adjust settings for this layout in Player manager / Edit player / Filters tab:

Filter layout can be dropdown style. All filters are shown in dropdown accordion style.

Adjust settings for this layout in Player manager / Edit player / Filters tab:

Filter are created inside Filter menu:

Then each song can "hook" to these filters in Edit playlist when you add songs to playlist:

Filter types

Filters can be text based (example keywords, genres etc..) single or 2 level with categories, number based (example song duration, sales count, bpm etc..), radio (one choice from multiple options), boolean type true / false (example is song on sale, is song looped etc..), date filter (filter songs by created date).

Example, create text filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

This is a text filter with categories (2 level).

Example, create text filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Example, create number filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Number filter which has ranges defined:

Example, create number filter with range in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

true / false filter

Example, create boolean filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Single choice from multiple options

Example, create radio filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Create star rating (1-5)

Example, create rating filter in Filter section:

Then each song can "hook" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Rating filter works as following: There can only be single rating value from 1-5. If you want to select songs with rating 4 and above, you select 4 and 5 star rating in the filter dropdown.

Some filters are automatically created from song properties (artist, duration, date). This saves the step of creating filter manually and only requires song data to be added once.

Automatic filters options are available in Filter section:

Data for automatic filters (artist, duration, date) is set in Playlist manager / Edit playlist when you add or edit songs in filters tab:

Notes

1. Filters with no values in songs are hidden. For example, you have defined text filter:

Example, you have created a text filter with some values in Filter section:

But if no songs "hooks" to this filter in Playlist manager / Edit playlist when you add or edit songs in filters tab, then this filter will be hidden from the main menu when gallery displays in the web page. This is valid for all filters, for example, if no songs have date set, Date filter will not be shown.

When adding songs to playlist over folder, its possible to read song genre(s) from ID3 tags and save them as filter automatically.

Inside Playlist manager / Edit playlist, choose Add folder and choose Genres settings:

New filter or add to exisiting

If you choose to create a new filter, all genres from your songs will be added as new filter.

If you choose to add to existing fillter, you can choose from exisiting text filters. Note that when gernes are added to filter, they can only be added as top level, which means no sub genres can be created.

So you can have for example:

Rock
Jazz
Instrumental
...

But you cant create filter with sub genres which looks like this:

Rock
	Modern Rock
	Classic Rock
Jazz
	Vocal Jazz
	Jazz Funk
	Cool Jazz
Instrumental
...

Managing genres in ID3 tags

In ID3 editor you can add multiple genres per songs, just separate them with desired separator (we used semicolon in our example) if you want to assign multiple genres per song.

Song can have tags generated from all text filters including artist filters.

Enable this feature in Edit Player / Filters section:

You can also link these tags to specific url, example:

You have the following text filter created (note Filter url link option):

And you "hook" to this filter to some song in Playlist manager / Edit playlist when you add or edit songs in filters tab:

This means song tags drums and guitar attached to this song will have these links created:

Maybe you can use this on your website to set some permalinks.

You can specify which filters are shown on the page with filter_id in shortcode. This can be done in Shortcodes section:

Note that some filters may still be hidden from display if no song contains this filter as explained in filter section

Lyrics can be activated by pressing microphone icon when song is playing. This means lyrics is only available for active playing song.

Add lyrics to song by uploading lyrics lrc file in Edit Playlist / Add Song dialog:

Note: if you have trouble uploading lrc file use txt extension.

Lyrics need to follow standard rules for formatting https://en.wikipedia.org/wiki/LRC_(file_format)

Example of lyrics file is located in plugin package / lyrics directory.

Keyboard controls options are located in Edit player / Keyboard tab:

Any number of icons can be added to each song. Icons can be image, SVG, or Font Awesome.

These icons can be set to any url in Edit Playlist / Add Song dialog:

If you use Font Awesome in icons make sure you activate Font Awesome CSS in Global settings:

Function call on icon click

If you want to call a function when some icon is clicked do the following.

Add icon in song with chosen id attribute.

Note that url and target are optional attributes in custom playlist icons and dont need to be used. You can just use an icon to trigger javascript function.

Add javascript code to listen for icon click:

 <script>
document.addEventListener('click', e => {
   if (e.target.closest('#unique-id-here')) {
       alert('function is called')

       //get song data
        var data = e.target.closest('.waf-music').media
        console.log(data)
   }
})
 </script>

Icon color

If you want to change icon colors you can target them with following css:

.waf-playlist-icon{
	color:#aaaaaa;
}

Once you use filters or use song search field, you can generate link to the gallery containing all selected filters. To access this use the button Copy filters and you will get something like this, which you can then use to access selected filters.

?waf-instance=player1&waf-scroll-to-player=1&waf-filter-id-5=100,300&waf-filter-id-0=4,63.93&waf-filter-id-artist=Tim McMorris

Songs can be sorted in the gallery in the following ways:

You can also sort songs on player start automatically inside Playlist manager / Edit Playlist:

Note:

Sorting songs by Plays requires song to have statistics data activated.

Sorting by Date requires songs to have date set.

User can save current playlist in the gallery by clicking Save playlist button. This will save current selected songs to a new playlist in Playlist manager.

Activate Social sharing in Edit Player / Social sharing tab:

Change player colors

You can change player colors in Edit Player / colors tab. This will include dynamic css for player colors.

If you do not want to include dynamic css for player colors (and you want to style player with your own CSS) you can turn this option off in Global settings:

To have access to Google analytics and get Google analytics tracking ID, follow these instructions: https://support.google.com/analytics/answer/1008080

Activate analytics in Edit Player / Google Analytics tab:

Following events will be displayed inside your Google Analytics panel / Events section:

Song played 
Song paused
Song ended
Song downloaded

To activate song statistics go to Edit Player / Statistics tab:

Once you activate statistics, you can track song statistics in Statistics plugin menu.

Sticky player can be shown on page bottom when song is playing.

Activate sticky player in Global settings:

Player instance ID is generated automatically starting from 0 for every new player in page. For example, if you add one player in page instance_id will be 0.

You can also manually add instance_id in shortcode (then the player will use this as ID), example (This player will have instance_id 5):

This is usefull if you have multiple players in page and you want to control them with javascript or css. By adding instance_id you can target each player in page.

Using same player in page multiple times

If you want to reuse the same player (you have created) in the page more than once, usedifferent instance_id in shortcode. For example, if you have this shortcode and you want to duplicate player in page:

You need to set instance_id:

Target player with CSS or javascript

To target player with CSS use: waf-wrapper + INSTANCE_ID (for example #waf-wrapper0).

#waf-wrapper0{
	max-width:500px;	
}

To target player with javascript use: waf_player + INSTANCE_ID (for example window.waf_player0 or just waf_player0).

waf_player0.playMedia(); //Play current media

You can display list of playlists in frontend, click on each playlist thumbnail will load new playlist in the player.

apwaf_playlist_display shortcode will create playlist thumbnail and title for each playlist specified in this shortcode. Playlist thumbnail and title come from playlist general options:

2 shortcodes are required for this feature, one for playlists to display, another for the player.

Shortcode parameters:

Example shows 3 playlists with ID (1,2,3) in player ID (5):

How to batch rename all songs in playlist to make them usable on another domain?

Go to Edit playlist / Playlist options / Maintenance tab where you can rename all url in current playlist:

Available callbacks:

    waf_playerID.on('setupDone', function(e, data){

        //called when plugin has been instantiated and is ready to use api, returns (instance, instanceName)

    }).on('soundStart', function(e, data){

        //called on song start, returns (instance, instanceName, media)

    }).on('soundPlay', function(e, data){

        //called on song play, returns (instance, instanceName, media)

    }).on('soundPause', function(e, data){

        //called on song pause, returns (instance, instanceName, media)

    }).on('soundEnd', function(e, data){

        //called on song end, returns (instance, instanceName, media)

    }).on('soundError', function(e, data){

        //called on song error, returns (instance, instanceName, media, error)

    }).on('filterClear', function(e, data){

        //called when all filters have been removed, returns (instance, instanceName)

    }).on('playlistSave', function(e, data){

	    //called when save playlist has been instantiated, returns (instance, instanceName)

	})

    

Song statistics callbacks:

    player.on('downloadCount', function(e, data){

	    //called when download has been instantiated, returns (instance, instanceName, media)

	}).on('playCount', function(e, data){

	    //called on song is played, returns (instance, instanceName, media)

	})
    

waf_playerID is constructed from waf_player + ID.

ID is generated automatically starting from 0 for every new player you place in page. For example, if you add one player in page, ID will be 0 (so it becomes waf_player0).

You can also manually add instance_id in shortcode (then the plugin will use this as ID), example (This player will have ID 1):

How to use Callbacks in wordpress text editor:

<script>
addWafEvents();
function addWafEvents(){
	if(!window.waf_player5){
		setTimeout(addWafEvents,100);
	}else{
		waf_player5.on('soundStart', function(e, data){
	        console.log('soundStart');
	    });
	}
}
</script>
    

How to use returned parameters:

waf_player5.on('soundStart', function(e, data){
    //called on song start, returns (instance, instanceName, media)

    console.log(data.instance);
    console.log(data.instanceName);
    console.log(data.media);

    //get song current time
    data.instance.getCurrentTime();

    //get song duration
    data.instance.getDuration();

});
    

Following api methods are included:

waf_playerID.playMedia(); //Play current media

waf_playerID.pauseMedia(); //Pause current media

waf_playerID.togglePlayback(); //Toggle current media (pause/play)

waf_playerID.nextMedia(); //Play next media

waf_playerID.previousMedia(); //Play previous media

/* set volume (0-1) */
----------------------------------
waf_playerID.setVolume(0); //Set volume (0)
waf_playerID.setVolume(0.5); //Set volume (0.5)
waf_playerID.setVolume(1); //Set volume (1)

waf_playerID.toggleMute();//toggle mute

waf_playerID.setPlaybackRate(0.5); //Set playback rate (0.5)
waf_playerID.setPlaybackRate(1); //Set playback rate (1)
waf_playerID.setPlaybackRate(2); //Set playback rate (2)

/* seek (seconds) */
--------------------------

waf_playerID.seekTo(0); //seek (0)
waf_playerID.seekTo(15); //seek (15)

waf_playerID.seekBackward(value); //seek value seconds backwards
waf_playerID.seekForward(value); //seek value seconds forward


/* load playlist on demand */
--------------------------

waf_playerID.destroyMedia(); //Destroy current playing song

waf_playerID.clearPlaylist();//destroy current playlist (remove all songs)

waf_playerID.loadPlaylist(type, url);//load new playlist
type = playlist_id (load WordPress playlist id, used for WordPress version), json (load new json file, used for javascript version)
url = playlist id, json url



waf_playerID.getCurrentTime();//get current time in seconds

waf_playerID.getDuration();//get duration in seconds

waf_playerID.getCurrMediaData();//get current song data (title, audio url..)

waf_playerID.getMediaPlaying();//get media playing


waf_playerID.closeLyrics();//close lyrics

waf_playerID.toggleFixedPlayer();// open / close fixed player


    

waf_playerID is constructed from waf_player + ID.

ID is generated automatically starting from 0 for every new player you place in page. For example, if you add one player in page, ID will be 0 (so it becomes waf_player0).

You can also manually add instance_id in shortcode (then the plugin will use this as ID), example (This player will have ID 1):

How to use api methods in wordpress post?

Use following code examples in post area.

Toggle playback:

<a onclick="togglePlayback();return false;" href="#">Toggle playback </a>
 <script>
    function togglePlayback(){   
        window.waf_player5.togglePlayback(); return false;  
    };
 </script>

Set volume:

<a onclick="setVolume(0.5);return false;" href="#">set volume </a>
 <script>
    function setVolume(val){   
         window.waf_player5.setVolume(val); return false;  
    };
 </script>

Load playlist by playlist ID.

<a onclick="loadPlaylist(PLAYLIST_ID);return false;" href="#">Load playlist </a>
<script type="text/javascript">
    function loadPlaylist(id){   
         window.waf_player5.loadPlaylist('playlist_id', id); return false;  
    };
</script>   
    

Autoplay

Volume on mobile

Volume cannot control the on Apple IOS with javascript, you have to use the physical button on the actual phone: Volume Control in JavaScript

Plugin does not work as expected

If the plugin does not work as expected, try the following tests to see if it makes a difference and what could be causing an issue:

1. Update to latest plugin files available on Codecanyon

2. Switch to default Wordpress theme

3. Check for errors in browser developer console (Chrome F12 key, Console tab)

4. Try to deactivate any 3rd party plugins (the ones that not come with Wordpress)

5. If you still have issues after you have done all changes above, you can send a message at http://codecanyon.net/user/Tean#contact , provide a link to your live page, and a temporary user and password for your wordpress admin panel so we can have a look.