HTML5 Audio Player with Playlist


Thank you for purchasing our component. If you have any questions that are beyond the scope of this help file, please feel free to email us via our Envato profile page contact form here.

How to Install

< head > setup

Include the following javascript and css code into HEAD section of the page:
							<link rel="stylesheet" type="text/css" href="css/jquery.mCustomScrollbar.css" media="all" />
							<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
							<link rel="stylesheet" type="text/css" href="css/hap_playlist_selector.css" />
							
							<script type="text/javascript" src="js/jquery-1.12.0.min.js"></script>
                            <script type="text/javascript" src="js/jquery.mCustomScrollbar.concat.min.js"></script>
							<script type="text/javascript" src="js/new.js"></script>

< body > setup

Create HTML markup for the player into BODY section of the page:
                            
                        
Artist Name - Song Title

0:00

/

0:00

Include playlist which is going to be loaded into BODY section of the page.
Audio playlist example:
                            

Activation

Activate the plugin once the document is ready by placing this into HEAD section of the page:
Note: player needs to be activated AFTER the parent html container in which player is placed has been made visible in css! (display:block for example)
                            <script type="text/javascript">
        
                                var hap_player;  
                                jQuery(document).ready(function($) {
                                    
                                    var settings = {
                                        playlistList:"#hap-playlist-list",
                                        activePlaylist:"playlist-audio1",
                                        activeItem:0,
                                        volume:0.5,
                                        autoPlay:false,
                                        usePlaylistScroll:true,
                                        useNumbersInPlaylist: true
                                    };

                                    hap_player = $("#hap-wrapper").hap(settings);

                                });

                            </script>
More settings are available, these are just some basic ones.

Configuration #top

Parameter Description
instanceName Unique identifier for player api (instance name must be unique for each instance!).
sourcePath The root location path where all plugin files are located.
playlistList Selector for element which holds list of playlists that can be loaded in the player on start or by request using api method loadMedia.
activePlaylist active playlist to start with from playlistList element.
Leave empty for no playlist loaded.
Check working with playlist section for more info.
activeItem active playlist item to start with.
Enter number, -1 = no playlist item loaded, 0 = first playlist item, 1 = second playlist item.. etc;
Check working with playlist section for more info.
volume 0-1 (number)
autoPlay true / false. Defaults to false on mobile.
preload auto/metadata/none. html5 preload media attribute
randomPlay true / false. Randomize playback in playlist.
loopingOn true / false. On playlist end (last item in playlist) rewind to beginning
autoAdvanceToNextMedia true / false (false = loop current song)
mediaEndAction loop/rewind/stop. Applies if 'Auto advance to next media' is false.
youtubeAppId Youtube application id, tutorial here: https://www.youtube.com/watch?v=pJSkp719HeE
soundCloudAppId SoundCloud application id, register here: http://soundcloud.com/you/apps/new and enter Client ID.
gDriveAppId Google drive api key, register here: https://console.developers.google.com create new project, enable Google Drive API, create Credentials, API key, enter referrer (your domain, you can also use 'http://localhost' referrer for local testing).
usePlaylistScroll true / false. Use playlist scroll
playlistScrollOrientation vertical / horizontal. Scroll plugin used: http://manos.malihu.gr/jquery-custom-content-scroller/
playlistScrollTheme string. Scroll themes from here: http://manos.malihu.gr/repository/custom-scrollbar/demo/examples/scrollbar_themes_demo.html
useTooltips true / false. Use tooltips on buttons. Defaults to false on mobile.
useKeyboardNavigationForPlayback true / false. Keyboard navigation for media (left arrow = previous media, right arrow = next media, space = toggle playback, m = toggle mute)
useDownload true / false
autoReuseDownloadMail true / false. For media download on mobile. Save and reuse user email after first input.
useShare true / false
Supported sharing sites are Facebook, Twitter, Tumblr, Google Plus.
If you would like to modify sharing content look into HAPShareManager object.
facebookAppId Facebook application id, create new application here: https://developers.facebook.com/apps and enter App ID
useNumbersInPlaylist true / false. Use numbers in front of title in playlist.
numberTitleSeparator Separator between number and title in playlist
artistTitleSeparator Separator between artist and title in playlist (title in playlist consist of artist + title, if both are available)
useTitleScroll true / false. Auto scroll song title.
titleScrollSpeed Song title scroll speed (number)
titleScrollSeparator Separator between repeated song titles
sortableTracks true / false. Sortable tracks in playlist. Defaults to false on mobile. Requires jquery ui and touch-punch.
playlistItemContent title, thumb (string). Creates title and/or thumb in playlist items. Enter one or both separated by comma.
continousPlayback true / false. Option for continous playback across different pages by remembering playback position using localStorage (remembers active playlist, active item, played time).
continousKey/td> Unique identifier for localStorage continous playback (string, no spacing!).

Player markup #top

Player markup is shown in How to Install section.
This is minimum required markup for the player:
                            
<div id="hap-wrapper"> is element in your page in which you will place the player.

Playlist

Playlist is optional.
To remove the playlist, remove this element completely:
                            
...

Working with playlist #top

This section explains how to load a playlist on start (using activePlaylist, activeItem options)

Audio playlist example:
                             
To load this playlist on start use this settings:
                            activePlaylist:"playlist-audio1",
                            activeItem:0,
Soundcloud playlist example:
                            
To load this playlist on start use this settings:
                            activePlaylist:"playlist-soundcloud1",
                            activeItem:0,

Working with media #top

Self hosted audio files - #top

Player support self hosted mp3 audio files.

Playlist item example

Minimal:
                            
  • Full:
                                
  • Parameter Required Description
    data-type yes audio
    data-mp3 yes path to mp3 file
    data-artist artist name
    data-title song title
    data-thumb path to thumb image
    data-download download path
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share share url link
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: http://www.w3schools.com/tags/av_prop_playbackrate.asp




    Soundcloud - #top

    Soundcloud requires API key, register here: http://soundcloud.com/you/apps/new and enter Client ID in settings: soundCloudAppId

    Soundcloud playlist examples

    track set:
                                
    user tracks:
                                
    single track:
                                
    user likes:
                                
    group:
                                
    Parameter Required Description
    data-type yes soundcloud
    data-path yes soundcloud url
    data-limit number of results to retrieve
    data-artist overwrite artist name
    data-title overwrite song title
    data-thumb overwrite thumb image
    data-thumb-quality default thumb quality is large. Set different thumb quality: https://developers.soundcloud.com/docs/api/reference#artwork_url
    example: data-thumb-quality="t300x300.jpg"
    data-thumb-default default thumb path for items that do not have thumb set
    data-download custom download path or make track downloadable, if track is downloadable by Soundcloud.
    data-download="path/to/custom/download/path"
    data-download (make track downloadable)
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share custom share url link or share soundcloud url.
    data-share="enter/path/to/custom/share/path"
    adding empty data-share attribute will share soundcloud url
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: http://www.w3schools.com/tags/av_prop_playbackrate.asp




    Podcast - #top

    Podcast playlist example

                                
    Parameter Required Description
    data-type yes podcast
    data-path yes podcast url
    data-limit number of results to retrieve
    data-artist overwrite artist name
    data-title overwrite song title
    data-thumb overwrite thumb image
    data-thumb-default default thumb path for items that do not have thumb set
    data-download custom download path or make track downloadable.
    data-download="path/to/custom/download/path"
    data-download (make track downloadable)
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share custom share url link or share podcast url.
    data-share="enter/path/to/custom/share/path"
    adding empty data-share attribute will share podcast url
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: http://www.w3schools.com/tags/av_prop_playbackrate.asp




    Youtube - #top

    Using Youtube

    Youtube requires API key which needs to be entered in settings: youtubeAppId
    Go here for the API key: https://console.developers.google.com
    Tutorial on how to create Youtube API key: https://www.youtube.com/watch?v=pJSkp719HeE

    Youtube playlist examples

    single videos:
                                
    playlist:
                                
    Parameter Required Description
    data-type yes youtube_single/youtube_playlist
    data-path yes youtube single video id / youtube playlist id
    data-limit number of results to retrieve
    data-artist overwrite artist name
    data-title overwrite song title
    data-thumb overwrite thumb image
    data-thumb-default default thumb path for items that do not have thumb set
    data-download custom download path
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share custom share url link or share youtube url.
    data-share="enter/path/to/custom/share/path"
    adding empty data-share attribute will share youtube url
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: https://developers.google.com/youtube/iframe_api_reference#Playback_controls




    Reading mp3 files from directories - #top

    Using folders with id3 tags requires following script in head tag:
    							<script type="text/javascript" src="js/jsmediatags.min.js.js"></script>
    Folder playlist example:
                                
    Parameter Required Description
    data-type yes folder
    data-path yes absolute folder path or relative folder path to the plugin "includes" directory (where folder_parser.php file is located)
    data-limit number of results to retrieve
    data-id3 get id3 tags from files
    data-download custom download path or dowload file.
    data-download="path/to/custom/download/path"
    data-download (download file)
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share custom share url link or share file url
    data-share="enter/path/to/custom/share/path"
    adding empty data-share attribute will share file url
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: http://www.w3schools.com/tags/av_prop_playbackrate.asp

    Folder organization

    You need to have following organization when loading files from folders:
    Example: data-path="../mp3-dir/audio1"
    We are going to place mp3 files and image thumbnails in 'audio1' directory.
    Equivalent mp3 and thumb files need to be named the same!
    So you end up with this structure in your folder:
    song1.mp3
    song1.jpg
    other_song.mp3
    other_song.jpg
    some_other_song.mp3
    some_other_song.jpg

    Accepted extensions for image thumbnails are jpg, jpeg, png, gif.

    How to get folder location?

    1. path relative to the includes directory (where folder_parser.php is located)
    Example: data-path="../mp3-dir/audio1"
    2. path absolute
    Use locate_directory.php file from includes directory and place it in audio1 directory and open it in browser to get desired folder location.
    Example: data-path="/home/interact/public_html/tst/mp3-dir/audio1"




    Reading google drive folders - #top

    Google drive folder playlist example:

                                
    Parameter Required Description
    data-type yes gdrive-folder
    data-path yes google drive folder ID
    data-download custom download path or dowload file.
    data-download="path/to/custom/download/path"
    data-download (download file)
    data-link playlist item url link
    data-target blank/parent, http://www.w3schools.com/tags/att_a_target.asp
    data-share custom share url link or share file url
    data-share="enter/path/to/custom/share/path"
    adding empty data-share attribute will share file url
    data-start media start time in seconds
    data-end media end time in seconds
    data-playback-rate media playback speed: http://www.w3schools.com/tags/av_prop_playbackrate.asp

    Folder organization

    You need to have following organization when loading files from google drive folders:
    Make sure your folder only has mp3 files inside, or in case your playlist uses thumbnails as well, then your google drive folder needs to have both mp3 files and image thumbnails inside (jpg, jpeg, png format).

    mp3 and thumbnail files inside google drive folder need to be named the same and there needs to be the same number of files (for example 5 mp3 files and 5 image files)!

    So you end up with this structure:
    google drive folder files:
    song_01.mp3
    song_02.mp3
    song_03.mp3
    song_01.jpg
    song_02.jpg
    song_03.jpg





    Playlist from XML source - #top

    Playlist can be loaded from XML file.
    Only important rule is that XML playlist markup is exactly the same as the playlist markup in HTML!
    So you can just copy playlist markup from HTML and paste it in xml file.

    XML playlist example

                                
    Example of XML playlist file is provided in xml directory.



    Playlist from database - #top

    Database playlist example

                                
    Parameter Required Description
    data-type yes database_data/database_html
    data-path yes database name
    data-table yes database table name
    data-range retrieve results from number + number of results to retrieve
    example: data-range="5,10" (start at 5, retrieve 10 results)
    data-limit number of results to retrieve
    example: data-limit="10"

    Example of sql playlists is provided in the package in source directory (audio_data.sql, audio_html.sql, mixed_data.sql).
    Database access data needs to be provided inside plugin root/includes/db_data.php file:
    $hostname = 'localhost';
    $username = 'database_username_here';
    $password = 'database_user_password_here';





    Mixed media - #top

    It is possible to mix different media type in the same playlist.
    Example of mixed playlist:
    
                                




    Callbacks #top

    Parameter Description
    hapSetupDone (instance, instanceName) Called when component setup is finished and is ready to use API. Returns player instance, instanceName.
    hapPlaylistEnd (instance, instanceName) Called on playlist end. Returns player instance, instanceName.
    hapPlaylistStartLoad (instance, instanceName) Called when playlist load starts. Returns player instance, instanceName.
    hapPlaylistEndLoad (instance, instanceName) Called when playlist load ends. Returns player instance, instanceName.
    hapItemTriggered (instance, instanceName, counter) Called when new media is triggered. Returns player instance, instanceName, media counter.
    hapMediaStart (instance, instanceName, counter) Called when media starts. Returns player instance, instanceName, media counter.
    hapMediaPlay (instance, instanceName, counter) Called when media is played. Returns player instance, instanceName, media counter.
    hapMediaPause (instance, instanceName, counter) Called when media is paused. Returns player instance, instanceName, media counter.
    hapMediaEnd (instance, instanceName, counter) Called when media ends. Returns player instance, instanceName, media counter.
    hapPlaylistItemEnabled (instance, instanceName, target, counter) Called on playlist item enable. Returns player instance, instanceName, playlist item (target), media counter.
    hapPlaylistItemDisabled (instance, instanceName, target, counter) Called on playlist item disable. Returns player instance, instanceName, playlist item (target), media counter.
    hapPlaylistItemClick (instance, instanceName, target, counter) Called on playlist item click. Returns player instance, instanceName, playlist item (target), media counter.
    hapPlaylistItemRollover (instance, instanceName, target, counter) Called on playlist item mouseenter. Returns player instance, instanceName, playlist item (target), media counter.
    hapPlaylistItemRollout (instance, instanceName, target, counter) Called on playlist item mouseleave. Returns player instance, instanceName, playlist item (target), media counter.
    hapMediaEmpty (instance, instanceName) Called when active media gets removed (no active media). Returns player instance, instanceName.
    hapPlaylistEmpty (instance, instanceName) Called when playlist becomes empty (no items in playlist after new playlist has been created or last playlist item removed from playlist, NOT after destroyPlaylist!). Returns player instance, instanceName.
    hapCleanMedia (instance, instanceName) Called when active media is destroyed. Returns player instance, instanceName.
    hapDestroyPlaylist (instance, instanceName) Called when active playlist is destroyed. Returns player instance, instanceName.
    hapPlaybackRateChange (instance, instanceName, rate) Called on playback rate change. Returns player instance, instanceName, playback rate.
    hapVolumeChange (instance, instanceName, volume) called on volume change. Returns player instance, instanceName, volume.
    hapProgressChange (instance, instanceName, percent) called on progress change. Returns player instance, instanceName, percent.
    //commented out for performance reason
    hapFilterChange (instance, instanceName) called after filter playlist items. Returns player instance, instanceName.
    hapSeeked (instance, instanceName, target, id) called on media seek. Returns player instance, instanceName. Not available for Youtube!

    API methods #top

    Parameter Description
    playMedia():void Play active media
    pauseMedia():void Pause active media
    togglePlayback():void Toggle active media playback
    nextMedia():void Play next media
    previousMedia():void Play previous media
    destroyMedia():void Destroy active media (use this method to destroy any playing music when you want to remove the player from the page or similar)
    destroyPlaylist():void Destroy active playlist
    loadMedia(value):void Load media:
    value: track title as String or Number (for numbers, counting starts from zero)
    loadPlaylist(value:String):void Load playlist:
    value: playlist ul 'id' attribute from hap-playlist-list
    inputAudio(data):void Play sound without creating any playlist data.
    data.mp3: mp3 audio path (required)
    data.title: song title
    addTrack(format:String, track:String/Array, playit:Boolean, position:int):void Add track(s) to playlist:
    format: type of track, html/data (required)
    track: track or array of tracks (String/Array) (required)
    playit: automatically play track after add
    position: position to insert tracks (counting starts from 0, leave out parameter for the end append)
    removeTrack(value:String/int):void remove track from current playlist
    value: track title (String) / int (counting starts from 0).
    sort(type:String, reverse:Boolean):void Sort playlist items (this also changes playback order!)
    type: title, random (required)
    reverse: title ascending / title descending
    setAutoPlay(val:Boolean):void Set autoplay
    setTitle(val:String):void Set song title
    getVolume():Number Get volume (0-1)
    setVolume(val:Number):void Set volume (0-1)
    toggleMute():void Toggle mute
    seek(value:Number, direct:Boolean):void Seek media:
    value: (time in seconds / percent)
    direct: (default true: time, false: percent)
    getCurrentTime():Number Get current time
    getDuration():Number Get duration
    getLoadProgress():Number Get load progress (0-1)
    toggleRandom(value):void Toggle random play
    value: true/false/void (toggle)
    toggleLoop(value):void Toggle playlist loop
    value: true/false/void (toggle)
    setPlaybackRate(value:Number):void Set playback rate:
    audio: http://www.w3schools.com/tags/av_prop_playbackrate.asp
    youtube: https://developers.google.com/youtube/iframe_api_reference#Playback_controls
    download(path:String, title:String):void download file:
    path: file download path (required)
    title: file title
    initScroll():void init playlist scroll
    destroyScroll(value):void Destroy playlist scroll
    getPlaylistLength():int Return number of items in playlist.
    getInstanceName():String Return instance name
    getMediaPlaying():Boolean Return media playing or paused
    getPlaylistTransition():Boolean Return playlist loading (is playlist loading)
    getPlaylistLoaded():Boolean Return playlist loaded (finished loading)
    getSetupDone():Boolean Return component setup finished (API can be used)
    getActiveItemId():int Return active item id in playlist (counting starts from 0)
    getPlaylistData():Array Return playlist data for active playlist
    getCurrMediaData():Object Return media data for active media
    getSettings():Object Return instance settings

    Example of API is located in api.html demo.

    Special features #top

    Add hap-click-locked to playlist holder to prevent click on playlist items:
                                
    Add hap-hover-locked to playlist holder to prevent hover events on playlist items:
                                




    Add hap-vertical to volume seekbar to make volume vertical
       
                                  
    Note: This just tells the code to calculate volume on y axis, nothing to do with css volume styling!

    Add hap-toggle-mute to player volume to toggle mute on click
       
                                




    Any html content placed within hap-playlist-item node will be copied inside newly generated playlist item:
       
                                
  • Social sharing #top

    Supported sharing sites are Facebook, Twitter, Tumblr, Google Plus
       
                                
    To add new sharing site add hap-share-item class and data-type attribute, for example:
       
                                
    Then add new sharing code in HAPShareManager object in new.js file.

    Troubleshooting #top

    Self hosted audio mp3 doesnt play

    If you have trouble playing audio on your server in some browsers, and you get an errors in developer console similar to these:
    HTTP "Content-Type" of "audio/mpeg" is not supported. Load of media resource ... failed.

    This is a mime type problem. You need to add following lines in your .htaccess file on your server.
    AddType audio/mpeg .mp3

    More details: http://voice.firefallpro.com/2012/03/html5-audio-video-mime-types.html


    Autoplay on mobile

    autoPlay is automatically set to false on mobile.
    This means when you set autoPlay:true in settings, it will be true on desktop, but on mobiles it will be false.
    AutoPlay doesnt work on IOS, and possibly some other mobile OS out there: User Control of Downloads Over Cellular Networks


    Volume on mobile

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


    Playlist Admin Manager #top

    Requirements and usage

    1.
    Requires server connection (xampp/mamp or online testing)
    Requires php 5.6 or above (mysqlnd and fileinfo extensions enabled which can be done in cPanel on most servers)

    2.
    Admin folders need to be located in plugin root, like in the following picture (they already come packaged this way):


    3.
    Using cPanel or phpMyAdmin create new database and user and password with assigned access to that database and enter them in 'admin/libs/config.php' file.
    define ('DB_HOST','localhost');
    define ('DB_USER','username_here');
    define ('DB_PASS','user_password_here');
    define ('DB_NAME','database_name_here');

    4.
    Run admin by opening index.php file in 'admin/index.php'

    Video tutorials on how to use playlist admin:
    https://www.youtube.com/watch?v=jIrPbxZ-oEk
    https://www.youtube.com/watch?v=rXrwTdCddYw