“MP3 Sticky Player” Documentation by FWDesign

“MP3 Sticky Player”

Created: 29/04/2018 Version 5.6
By:© FWD (FUTURE WEB DESIGN)
Email: tibi_diablo@yahoo.com

Thank you for purchasing our script. If you have any questions that are beyond the scope of this help file, please feel free to email via our email. Thanks so much!

Table of Contents

  1. IMPORTANT NOTES - read this before anything else
  2. Preparing the audio / video files
  3. Shoutcast & Icecast setup.
  4. How to install MP3 Sticky Player into your html page
  5. Constructor parameters
  6. Playlists setup
  7. Starting / stopping a track at a specified time
  8. API specifications
  9. Setup private tracks.
  10. Encrypt video path.
  11. Sources and Credits

A) IMPORTANT NOTES - make sure you read this! - top

Please note that the MP3 Sticky Player installation and configuration is not complicated but because it has a lot of customizable settings it might seem complicated, please go through the entire documentation before trying to install it into your own page. Basically what it must be done is to copy some html code from the examples we provided and paste it into your own html page and of course add your own audio file.

When using mp3 files located on your server with relative paths you must add all folders that contains mp3 in the content folder, this is extremely important in order for all features to work correctly.

The server is character case sensitive so make sure that the MP3 Sticky Player settings are identical to those from the provided examples.

Some of the features will not work local like the share button or loading xml playlist file, this is normal behavior because most browser does not allow this, once uploaded on the server it will function properly.

When an error occurs a red info box with the error description will appear over the MP3 Sticky Player, please note that this box is there to help you understand the problem, for example if a mp3 file is not found the box will appear and inform you about the problem. The box can be closed when clicked or touched.

When testing local on IE7/IE8 or on an older browser that dose not support HTML5 audio it will not work because the flash (.swf) file is trying to comunicate with the browser and this is not allowed, of course it will work fine when tested online.

If you are not using Youtube set useYoutube:no in the contructor, this way the youtube API will not be loaded because there is no need for it.

The MP3 Sticky Player skin is constructed from .png images, only a few settings for changing colors are possible like changing the playlist or title track color. If you want a different skin the .png files must be modified. The skin is really flexible this is allowing to skin the MP3 Sticky Player as you like. We have a great designer so if you need a custom skin please contact us!

To use Soundcloud an API key from SoundCloud is required this can be done by register you SoundCloud api key here for free athttp://soundcloud.com/you/apps/new , after a key is provided it has to be passed inside the contructor like this soundCloudAPIKey:"your_api_key". Please note that I've provided one but it is possible that it will not work, the API is updated regularly so if loading a SoundCloud playlist or track will not work a new API key is required.

B) Preparing the audio / video files - top

Currently all browsers except Opera have .mp3 or .mp4 support (this applies to desktop), on a mobile device all browsers have .mp3 / mp4 support. On a browser that does not have .mp3 / mp4 support the player will use flash. The good news is that the player will work only with .mp3 / mp4 files there is no need to use other audio formats.

HLS / m3u8 live streaming files.

MSP can play HLS / m3u8 files, the connection URL has to be passed as the data-path value in the playlist where you want to use it, example below

		
  • 
			
    HLS / LIVE STREAMING / m3u8 - http://radiom2o-lh.akamaihd.net/i/RadioM2o_Live_1@42518/master.m3u8
    
		
    •

    Google drive files.

    To get the track path mp3 or mp4 open your google drive page go to Disc – My drive.

    Right click on get shareable link the like on screenshot: get video id 1 get video id 2 and use that video ID to create google drive video URL.

    This is final URL how google drive video URL should look:https://drive.google.com/uc?export=download&id=videoID

    Replace videoID with the id taken from the previous step and use it as the video source:https://drive.google.com/uc?export=download&id=0B4Au_agYmWFZQWdHdHN3OVJLX0E

    C) Shoutcast & Icecast setup. - top

    If you don't want RAP to display the current playing stong title from the radio station just add the mp3 radio stream like this : http://95.141.24.224:80/;.mp3. Adding the ;.mp3 at the end of the address will force the server to serve the mp3 stream instead of the http web page. Doing it this way the current song title will not be displayed. Please see below:

    		
  • 
			
    SHOUTCAST EXAMPLE - it really works :) - http://mp3.trb-stream.net/;.mp3
    
		
    •

    To get the current song title from the stream displayed the data-path of the track has to be set to the stream URL ex http://server:port/ and specify if the stream is shoutcast or icecast this way RAP will know how to parse the data from the radio station. Please see below:

    		
  • 
			
    SHOUTCAST EXAMPLE
    
		
    • 
		
  • 
			
    ICECAST EXAMPLE
    
		
    •

    D) How to install MP3 Sticky Player into your html page - top

    This is a small tutorial about how to install MSP into your page. MSP can be added inside a web page and positioned at the top or bottom, MSP will adapt its width based on the maxWidth property specified in the constructor, the height is set based on the controller height plus playlist height.

    In the download files there is a start folder and in this folder there are html files starting with the label "skin", each of this examples have exactly the same structure with different constructor settings you can use one of them to copy and paste the required html code based on skin that you need, I will use the skin-minimal-dark.html as an example for this tutorial.

    The skin is created using png images, if you want a custom skin please contact us. If you want to create a skin of your own modify the ones we already provided.

    This is how the player is installed in a HTML page, please read the Constructor parameters section to understand the MP3 Sticky Player properties

    E) Constructor parameters - top

    Please open any of the .html files provided with a text editor as reference.

    These parameters represents the possible setting for the MP3 Sticky Player they are all visible in the below image and described below.

    //-- main settings --//

    //-- controller settings --//

    //-- playlists window settings --//

    //-- playlist settings --// //-- search bar settings --// //-- opener settings --// //-- password window --// //-- popup settings --//

    F) Playlists setup - top

    Open with a text editor one of the html files files starting with the label "skin" as reference.

    Setting up the playlist window is simple, an ul tag must be added in the body tag, this ul tag must have an unique id that is passed as a value to the MSP constructor as follows playlistsId"unique-id", in the examples provided the id is "playlists" but it can be have any value as long as it is unique.

    To add/remove a playlist an li tags must be added/removed inside the playlists ul tag, this is illustrated below. MSP supports unlimited playlists but at least one playlist is required!.

    There are five playlist type as follow: HTML, YOUTUBE, PODCAST, XML, SOUNDCLOUD, and OFFICIAL.FM playlist . Each of this type of playlists are explained in detail below.

    SoundCloud playlist.

    To add/remove this type of playlist in the playlists add or remove the code from below into the playlists ul tag. The data-source represents the url of a SoundCloud playlist. The other attributes are self explanatory.

    			
  • 
				
    Title: My playlist 3
    
				
    Type: SOUNDCLOUD
    
				
    Description: This playlist is created using a SoundCloud playlist URL.
    
			
    •

    YOUTUBE playlist.

    To add/remove this type of playlist in the playlists add or remove the code from below into the playlists ul tag. The data-source represents the url of a Youtube playlist, please note that you only have to add the list=... parameter from the youtube playlist URL. The other attributes are self explanatory.

    			
  • 
				
    Title: My playlist 5
    
				
    Type: YOUTUBE PLAYLIST
    
				
    Description: This playlist is created using a YOUTUBE playlist.
    
			
    •

    OFFICIAL.FM playlist.

    To add/remove this type of playlist in the playlists add or remove the code from below into the playlists ul tag. The data-source represents the custom string plus the the playlist id. An official.fm playlist url looks something like this "http://www.official.fm/playlists/yrOG?from=homepage&track_id=MjH0", what you need to get from the url is the playlist id showed in bold and add it after the special string like this official.fm/yrOG.

    			
  • 
				
    Title: My playlist 5
    
				
    Type: OFFICIAL.FM
    
				
    Description: This playlist is created using a OFFICIAL.FM playlist URL.
    
			
    •

    HTML playlist & MIXED playlists.

    To add/remove this type of playlist in the playlists add or remove the code from the below image into the playlists ul tag. The data-source represents the id of the playlist ul element. The other attributes are self explanatory.

    			
  • 
				
    Title: My playlist 1
    
				
    Type: HTML
    
				
    Description: This playlist is created using html elements.

    • To construct this type of playlist add the code from the below image inside the body HTML element. The code sample is self explanatory. To add/remove tracks add/remove li HTML elements with the data-path attribute, the data-path attribute can also contain a link to a soundcloud track, mp4 video or youtube video. If you don't need a thumbnail or duration remove the data-thumbpath and data-duration attributes. The data-buy-url attribute represents the track buy url or a javascript function that is called when the buy button is clicked, if you don't want a buy button remove this attribute. The data-downloadable attribute allows the track to be downloaded with a download button, if you don't need this feature remove this attribute.

    FOLDER playlist.

    To add/remove this type of playlist add or remove the code from below into the playlists ul tag.The data-source represents path of the mp3's folder (please note that this type of playlist can only be loaded form the same domain on which the html page resides, also the foler path must be relative to the path of the "proxyFolderPath.php", what this means is that your mp3's folder must be in the same folder or subfolder with the "proxyFolderPath.php" file ). The other attributes are self explanatory.

    When adding the folder path to the data-source attribute a special string must be added before it, this string value is folder:, so for example if the mp3's folder path is myFolder the final string must look like this folder:myFolder. For a folder with a mp3's subfolder ex: myFolder/myMP3Folder the final string must look like this folder:myFolder/myMP3Folder .

    		
  • 
			
    Title: My playlist 6
    
			
    Type: GENERATE FROM FOLDER
    
			
    Description: This playlist is created from a folder of mp3 files.

    • XML playlist.

    To add/remove this type of playlist in the playlists add or remove the code from below into the playlists ul tag. The data-source represents the path of the XML file. Please note that the XML path must be absolute, ex: http://www.domain.com/xmlFile.xml. The other attributes are self explanatory. Please note that the XML file does not allow special characters like "&", if you need to use this type of character numeric characters are required, a useful table with all this special characters can be found at this url.

    		
  • 
			
    Title: My playlist 4
    
			
    Type: XML
    
			
    Description: This playlist is created using a XML file.

    • To construct this type of playlist create an XML file with the same structure as the one from below (a sample XML file is included in the content folder). The code sample is self explanatory. To add/remove tracks add/remove li elements with the data-path attribute. If you don't need a thumbnail or duration remove the data-thumbpath and data-duration attributes.


    PODCAST playlist.

    To add/remove this type of playlist in the playlists add or remove the code from below into the playlists ul tag. The data-source represents the path of the PODCAST url.

    		
  • 
			
    Title: My playlist 2
    
			
    Type: PODCAST
    
			
    Description: This playlist is created using a podcast URL.
    
		
    •


    G) Starting / stopping a track at a specified time - top

    It is possible to start or stop a track at a specified time, please note this is only possible in a HTML or XML playlist. In the example below there are two parameters data-start-at-time and data-stop-at-time, this two parameters values are strings in the format hours:minutes:seconds so for example to start a track at second 10 set data-start-at-time="00:00:10" and to stop it at second 30 set data-stop-at-time="00:00:30". Both features are optional, if not needed remove them from the playlist entry.

    		
  • >
			
    MP4 - Nirvana - Girls (Dj Dima House & Samsonoff Remix).
    
		
    •


    H) API specifications - top

    Inside the donwload files there is HTML file called API-example.html, in this file I have added all events and methods for reference, open the page source to see them. Full reference below. Please note that the properties are read only and they can only be written in the consturctor for more info about this please read the Constructor parameters section.

    Public methods:

    Function Method Description

    addTrack

    		 addTrack(source:String, title:String, thumbPath:String, duration:String, addAtTheBegginngOfPlaylist:Boolean, download:Boolean, buy:String):void This method allows to add a track in the current playlist at runtime....
    • source: the mp3 file relative or absolute path or the youtube video URL or the mp4 video relative or absolute path.
    • title: the track title.
    • thumbPath: the track thumbnail relative or absolute path, if you don't want a thumbnail just set this to "".
    • duration: the track duraton with this format hours:minutes:seconds for example (00:06:14).
    • addAtTheBegginngOfPlaylist: this can be true or false, it allows to add the track at the beggining or end of the playlist.
    • download: this can be yes or no, it allows to download or not the track.
    • buy: this can be URL that will be opened when the buy button is clicked or a javascript function that you can call when the buy button is clicked, for example buyCustomFunction(), if you don't need a buy button just set this to "". Ex:window['player1'].addTrack("content/mp3/01.mp3", "New added track - new added artist", "content/thumbnails/brian.jpg", "05:45", true, true, "myFunction()");

    popup

    		 popup():void Pop-up playler in a new window.

    loadPlaylist

    		 loadPlaylist(playlistId):void Load a playlist based on id, the playlist count starts from 0.

    showPlayer

    		 showPlayer():void Show the entire player.

    hidePlayer

    		 hidePlayer():void Hide the entire player.

    showCategories

    		 showCategories():void Show the playlist selector window.

    showPlaylist

    		 showPlaylist():void Show the playlist.

    hidePlaylist

    		 hidePlaylist():void Hide the playlist.

    share

    		 share():void Share current track on facebook.

    getCurrentTime

    		 getCurrentTime():String Returns the track current time.

    getDuration

    		 getDuration():String Returns the total track duration.

    setVolume

    		 setVolume( Number ):void Set the audio volume, this method accepts a parameter that represents a number between 0 (audio mute state) and 1 (audio maximum volume).

    scrub

    		 scrub( Number ):void Notify instance to scrub (set the audio position), this method accepts a parameter that represents a number between 0 (audio start position) and 1 (audio end position).

    playSpecificTrack

    		 playSpecificTrack(categoryId, trackId):void Play a specific cat based on the category id and track id, both parameters counting is starting from 0.

    stop

    		 stop():void Stops the playback and the loading process if the loading process has started.

    play

    		 play():void Start / play playback.

    pause

    		 pause():void Pause the playback.

    playPrev

    		 playPrev():void Play previous track.

    playNext

    		 playNext():void Play next track.

    playShuffle

    		 playShuffle():void Play shuffle track.

    getIsAPIReady

    		 getIsAPIReady():Boolean Returns the API state, true if ready, false if not.

    getCatId

    		 getCatId():Number Returns the current category id, the counting starts form 0.

    getTrackId

    		 getTrackId():Number Returns the current track id, the counting starts form 0.

    getTrackTitle

    		 getTrackTitle():String Returns the current track title.

    setPlaybackRate

    		tsetPlaybackRate(rate):void Set the playback rate / speed, the rate argument can be a number betweem 0.5 and 3 where 1 is normal rate /speed .

    scrubbAtTime

    		 scrubbAtTime(time):void Scrub at a specified time in format hour:minutes:seconds for example 00:01:30.

    Event listeners:

    Event Prefix Description

    ready

    		 FWDStickyAudioPlayer.READY Dispatched when the MP3 Sticky Player instance API is actually available.

    start

    		 FWDStickyAudioPlayer.START Dispatched when the MP3 playing has started.

    popup

    		 FWDStickyAudioPlayer.POPUP Dispatched when the player is pop-uped in a new window.

    error

    		 FWDStickyAudioPlayer.ERROR Dispatched when the MP3 Sticky Player instance can't load or play the audio file, this event has a property of type string that represents the error message.

    startToLoadPlaylist

    		 FWDStickyAudioPlayer.START_TO_LOAD_PLAYLIST Dispatched when the playlist loading has started.

    playlistLoadCompleteHandler

    		 FWDStickyAudioPlayer.LOAD_PLAYLIST_COMPLETE Dispatched when the playlist loading is complete.

    stop

    		 FWDStickyAudioPlayer.STOP Dispatched when the MP3 Sticky Player instance is stopped.

    play

    		 FWDStickyAudioPlayer.PLAY Dispatched when the MP3 Sticky Player instance playback start to play.

    pause

    		 FWDStickyAudioPlayer.PAUSE Dispatched when the MP3 Sticky Player instance playback is paused.

    update

    		 FWDStickyAudioPlayer.UPDATE Dispatched when the MP3 Sticky Player instance is playing and it's position is changing (useful to update a custom scrub bar), this event has a property of type number between 0 (audio start position) and 1 (audio end position).

    updateTime

    		 FWDStickyAudioPlayer.UPDATE_TIME Dispatched when the MP3 Sticky Player instance current duration is changing. This event has two properties of type string curTime and totalTime.

    playComplete

    		 FWDStickyAudioPlayer.PLAY_COMPLETE Dispatched when the MP3 Sticky Player instance playback has reached the end of the audio file.

    I) Setup private tracks. - top

    To set a track private there is a paramter data-is-private that has to be set to "yes". The global password for all tracks is set in the contructor privatePassword:"428c841430ea18a70f7b06525d4b748a". If you want to use a unique password for a track there is a parameter data-private-track-password that has to be set to a unique encrypted password. this is showed below.

    		
  • 
				
    
					
    
						
    PRIVATE track EXAMPLE
    
						
    Support for private tracks.
    
					
    	
				
    
				
    
					
    
						
    MP3 STICKY PLAYER
    
						
    Each track can contain a detailed description, the description can be formatted with CSS as you like. The description window and description button can be disabled individually for each track or globally for all tracks.
    
						
    For more information about this please follow this link
    
					
    
				
    
			
    •

    To encrypt the track password there is a tool I have created that will encrypt the password at this link, enter your desired password in the input field then click on the Encrypt passowrd button, after this the encrypted password can be copied and pasted when needed. The default password is Melinda.


    J) Encrypt track path. - top

    To encrypt the track path I have created a tool that will encrypt the track path at this link, enter the track path (this applies all track / audio paths) in the input field then click on the Encrypt media button, once this is done copy the encrypted track path and paste it as the track source parameter.this is showed below. In this example content/mp3/01.mp3 is encrypted to encrypt:Y29udGVudC9tcDMvMDEubXAz .

    			
  • 
				
    MP3 - MACKLEMORE & RYAN LEWIS vs MAJOR LAZER  can't hold us remix (ft swappi and 1st klase)
    
			
    •


    K) Sources and Credits - top

    This component was made by Tibi from FWD (FWDesign) FUTURE WEB DESIGN, for more information and support contact us at tibi_diablo@yahoo.com

    Once again, thank you so much for purchasing this item. As I said at the beginning, I'd be glad to help you if you have any questions regarding this MP3 Sticky Player and I'll do my best to assist.

    FWDesign

    Go To Table of Contents