WordPress Documentation

Documentation for the WordPress version, API and overall implementation.

Getting Started

Plasmic Audio Player, a powerful, responsive, and extremely customizable, versatile player with playlist support with .mp3, Shoutcast, and Icecast supported formats, seamlessly running on all major browsers and mobile devices, including iPhone, iPad, iOS, Android, MAC, and Windows, elevating your website's audio experience to a whole new level.

It is built using EcmaScript6 using the latest JavaScript and CSS standards. The 3D sphere and particles use Three.js and WebGL shaders running exclusively on the device's GPU. It is very important to note that each instance will add its own sphere that has to be rendered by the GPU, if you want to add multiple instances the best thing is to add them in separate sections of the page where they are not visible all at the same time this way the GPU will only render the sphere that is visible in the viewport.

Please note that Plasmic Audio Player is compatible with any WordPress theme and it has no dependencies.

Installation

After purchasing the plugin from CodeCanyon, inside the main zip file you will find installable plugin fwdpap.zip.

Installation steps

  • 1. In your WordPress Admin Dashboard, go to Plugins > Add New.
  • 2. Upload the fwdpap.zip plugin file that you downloaded from CodeCanyon.
  • 3. Click on install now.
  • 4. If successful, click Activate Plugin to activate it, or Return to Plugin Installer.

Update

Uninstall and delete the current installed version, doing this will not remove any of the settings or playlists, install the new version by following the steps from the installation section above, and if you are using a cache plugin clear the browser cache with it to make sure the old files are not used.

Usage

The plugin is constructed of three sections, the preset manager which is used to modify the player functionality, the playlist manager wich is used to create playlists and add manage tracks and the CSS editor which is used to update surten CSS aspects of the plugin like the player font.

I have created a video tutorial, I encourage you to watch it from start to end.

Presets

Frist step is to select the preset that you want to use, you can see them all live in the examples here, just select the preset that you want and if you want to modify some of the preset functionlity just modify the option/options that you want, they are self explanatory and have an explanation, don't forget to update the preset.

Playlists

Next step is to create your own playlist by clicking on the Add new playlist button and give it a name.

After this is done you can add as many tracks as you want, it is a simple process, if you are confused please watch this video tutorial.

Shortcode

After the preset and playlist are done use the shortcode generator to add the player in your page, post or custom post.

Resources

This section contains useful resorces and information about the plugin usage and it's features.

Shoutcast and Icecast

Plase note that only Shoutcast Version 2.0 or higher and Icecast Version 2.0 or higher are supported.

If you have a SSL web site and want to play a Shoutcast or Icecast stream from a non secure HTTP server you will need a proxy cors server, I explain this in detail here in this video tutorial. Please note this video tutorial was recorded for a different audio player but the same applies to Plasmic Audio Player, so please watch it from start to end.

Once you have the server address set track type to shoutcast or icecast depending on which platform are you using.

To play directly the stream without geting the artwork image and current playing title set the track type to .mp3, I explain in detail in this this video tutorial the difference between a server and a stream please make sure you understand it.

Google Analytics

Please watch this video tutorial for more details, the video tutorial is for the JavaScript version but it works exactly the same for the WordPress plugin, the google analytics measurment ID is added in the player preset Google analytics tracking code.

Custom definitions

  • track_url - the track source.
  • info - the artist and title, if they are not avialble this parameter will not be sent.

Cloud storage

Plasmic Audio Player can play audio/.mp3 from any cloud storage platform like Google Drive or Amazon S3, you will need to get the .mp3 URL/path not the .mp3 sharrable link the acatual .mp3 URL/path, each platform has it's own way to deliver, below it is explained Google Drive and Dropbox. Depending of which platform you will use you need a similar approach.

Google Drive:

For this method I've created a video tutorial here please watch it.

https://www.googleapis.com/drive/v3/files/[file_id]?alt=media&key=[api_key]&v=[.mp3]

Example of working .mp3 file https://www.googleapis.com/drive/v3/files/0B4Au_agYmWFZNHNtZTlXUm1UUUE?alt=media&key=AIzaSyBsJ8HRNI4iHUqpszDtx3Ijq3ZKoXLUx-E&v=.mp3 and mp3 file https://www.googleapis.com/drive/v3/files/0B4Au_agYmWFZVG0zc2pzalVCVjg?alt=media&key=AIzaSyBsJ8HRNI4iHUqpszDtx3Ijq3ZKoXLUx-E&v=.mp3 .

Dropbox:

Copy the drop box video or audio link, then replace www.dropbox.com with dl.dropboxusercontent.com. Thus the URL: https://www.dropbox.com/s/abcd/file.mp3?dl=0&mt=.mp3 will become: https://dl.dropboxusercontent.com/s/acbd/file.mp3?dl=0&mt=.mp3 .

API - Application Programming Interface

This section is for developers that want to use the plugin API. The following lists represent all the public API methods and event listeners that can be used from the player externally.

You can access the player instances by their order in the page with the fwdpap name with its order after it, starting from 0. For example if you have 2 instances their names are fwdpap0 and fwdpap1. Here is an example how to use the API in the WordPress editor or in a code section of your page:

<script type="text/javascript">
addEvents();

function addEvents(){
    if (!window.fwdpap0){
        setTimeout(addEvents, 100);
    }else{
        fwdpap0.addEventListener(FWDPAP.PLAY, onPlay);
		fwdpap0.addEventListener(FWDPAP.LIKE, onLike);
		console.log("player ready");
    }
}

function onPlay(e){
    console.log("play - ", e);
}

function playNextTrack(){
    fwdpap0.playNext();
}

// Listen for the LIKE event.
function onLike(e){
	console.log(e)
}
</script>

<!-- Add a button -->
<button onclick="playNextTrack()">Play next video</button>

Methods

Methods are functions that can be called via the API to execute certain actions.

JavaScript methods look like fwdpap0.methodName( /* arguments */ ), please note that fwdpap0 is the player instance name, if you are using multiple players don't forget to set the instance unique for each instance like this fwdpap1, fwdpap2, fwdpap3, etc... depending on how many players are added.

play

.play()

Play the audio/.mp3.

pause

.pause()

Pause the audio/.mp3.

stop

.stop()

Stop the audio/.mp3 and the loading.

playNext

.playNext()

Play the next audio/.mp3 in the playlist.

playPrev

.playPrev()

Play the previous audio/.mp3 in the playlist.

playShuffle

.playShuffle()

Play shuffle audio/.mp3 in the playlist.

playTrack

.playTrack(id:Number)

Play audio/.mp3 in the playlist based on id.

Parameters

  • id (Number) - the id of the track to play in the playlist (counting starts from 0).

setVolume

.setVolume(volume:Number, updateController:Boolean)

Set the audio/.mp3 volume.

Parameters

  • volume (Number) - the volume from 0 to 1 where 1 is the maximum volume.
  • updateController (Boolean) - update the volume scrubber.

setPlaybackRate

.setPlaybackRate(rate:Number)

Set the audio/.mp3 playbackrate speed.

Parameters

  • rate (Number) - the playbackrate speed from 0.5 to 3 where 1 is the default.

getPlaybackRate

.getPlaybackRate():Number

Returns the current playback rate speed.

startToScrub

.startToScrub()

Notifiy the player that an audio/.mp3 scurb starts.

stopToScrub

.stopToScrub()

Notifiy the player that an audio/.mp3 scurb finished.

scrubbAtTime

.scrubbAtTime(duration:String)

Scrub the audio/.mp3 to a specific time.

Parameters

  • duration (String) - duration at which to scrub the audio/.mp3 [hours:minuts:seconds], ex: 00:10:25.

scrub

.scrub(percent:Number)

Scrub the audio/.mp3 to a specific percent.

Parameters

  • percent (Number) - percent at which to scrub the audio/.mp3 from 0 to 1 where 0.5 is 50 percent.

getCurrentTime

.getCurrentTime():String

Returns the current in fromat [hours:minuts:seconds], ex: 00:10:25.

getDuration

.getDuration():String

Returns the audio/.mp3 duration in format [hours:minuts:seconds], ex: 00:10:25.

destroy

.destroy():Void

Destory the player instance and remove it from DOM.

Events

Plasmic Audio Player has many events, they are added via the addEventListener method add accessed via the instance name.

The events must be registered when the API is ready.

// API.
addEvents();

function addEvents(){
	if (!window.fwdpap0){
		setTimeout(addEvents, 100);
	}else{
		fwdpap0.addEventListener(FWDPAP.PLAY, onPlay);
		console.log("player ready");
	}
}

function onPlay(e){
	console.log("play - ", e);
}

FWDPAP.SHOW_CONTROLS

FWDPAP.SHOW_CONTROLS

Dispatched when the controls are showed.

FWDPAP.HIDE_CONTROLS

FWDPAP.HIDE_CONTROLS

Dispatched when the controls are hidden.

FWDPAP.UPDATE_VOLUME

FWDPAP.UPDATE_VOLUME

Dispatched when the volume is changed.

Parameters

  • volume (Number) - the current volume.

FWDPAP.UPDATE_PLAYBACK_SPEED

FWDPAP.UPDATE_PLAYBACK_SPEED

Dispatched when the playback rate is changed.

Parameters

  • playbackRate (Number) - the current playbackrate speed.

FWDPAP.PLAY_COMPLETE

FWDPAP.PLAY_COMPLETE

Dispatched when the audio/.mp3 has finished to play.

FWDPAP.PAUSE

FWDPAP.PAUSE

Dispatched when the audio/.mp3 is paused.

FWDPAP.PLAY

FWDPAP.PLAY

Dispatched when the audio/.mp3 plays.

FWDPAP.STOP

FWDPAP.STOP

Dispatched when the audio/.mp3 is stopped.

FWDPAP.UPDATE_TIME

FWDPAP.UPDATE_TIME

Dispatched when the audio/.mp3 is playing and the time is updated.

Parameters

  • curTime (String) - the current time in format [hours:minuts:seconds], ex: 00:10:25.
  • totalTime (String) - the current time in format [hours:minuts:seconds], ex: 00:10:25.

FWDPAP.UPDATE

FWDPAP.UPDATE

Dispatched when the audio/.mp3 playing.

Parameters

  • percent (Number) - the current percent played from 0 to 1.

FWDPAP.LIKE

FWDPAP.LIKE

Dispatched when like button is clicked.

Parameters

  • id (Number) - the current playing playlist track id starting from 0.
  • playlistItem (Object) - an object with detailed information about the liked track.

Notes

I worked on this plugin for about an year, it was a challange to bring the 3D world and WebGL in a real project, I will continue to improve it and add new features.

For me this is more than a job, it is my passion, I love to create innovative tools that my clients can benefit from. @Tibi - FWD.

For support and customizations please write to me directly at this email.

© Copyright FWDesign