Audio Waveform 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:
							
                            
                            
                            
                            
                            
                            
                            
                            

< body > setup

Create HTML markup for the player into BODY section of the page:
                            
                        
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 awp_player;  
                                jQuery(document).ready(function($) {
                                    
                                    var settings = {
                                    instanceName:"default2",
                                    sourcePath:"",
                                    playlistList:"#awp-playlist-list",
                                    activePlaylist:"playlist-audio1",
                                    activeItem:0,
                                    volume:0.5,
                                    autoPlay:true,
                                    drawWaveWithoutLoad:false,
                                    randomPlay:false,
                                    loopingOn:true,
                                    autoAdvanceToNextMedia:true,
                                    mediaEndAction:"loop",
                                    soundCloudAppId:"6d5131010ae3b3953fc7d881c38bc555",
                                    gDriveAppId:"AIzaSyB0Rw9B0WgjWQUYoxRi_rwpwr5E0ZxXuXs",
                                    useKeyboardNavigationForPlayback:true,
                                    usePlaylistScroll:true,
                                    playlistScrollOrientation:"vertical",
                                    playlistScrollTheme:"light",
                                    useDownload:true,
                                    facebookAppId:"644413448983338",
                                    useNumbersInPlaylist: true,
                                    numberTitleSeparator: ".  ",
                                    artistTitleSeparator: " - ",
                                    playlistItemContent:"title",
                                    wavesurfer:{
                                        waveColor: '#F444D9',
                                        progressColor: '#33FDFF',
                                        barWidth: 3,
                                        cursorColor: '#ffffff',
                                        cursorWidth: 1,
                                        height: 100,
                                    }
                                };

                                awp_player = $("#awp-wrapper").awp(settings);

                                });

                            </script>

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.
drawWaveWithoutLoad true / false. With this option set to true, you can load waveform from peak file (if peak file pre exist / has already been created), without start to load audio. Then later audio can be started when user presses play, or using api.
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.
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
useKeyboardNavigationForPlayback true / false. Keyboard navigation for media (left arrow = previous media, right arrow = next media, space = toggle playback, m = toggle mute)
facebookAppId Facebook application id, required if social sharing is being used, 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)
playlistItemContent title, thumb (string). Creates title and/or thumb in playlist items. Enter one or both separated by comma.
wavesurfer https://wavesurfer-js.org/
waveColor The fill color of the waveform after the cursor.
progressColor The fill color of the part of the waveform behind the cursor.
barWidth Width of the bars in pixels (0 default)
cursorColor The fill color of the cursor indicating the playhead position.
cursorWidth Measured in pixels.
height The height of the waveform. Measured in pixels.

Player markup #top

Player markup is shown in How to Install section.
This is minimum required markup for the player:
                            
awp-wrapper is element in your page in which you will place the player.
awp-waveform is element in which waveform will be drawn.

Playlist

Playlist is optional.
To remove the playlist, remove this element completely:
                            
...
Then there will be no visible playlist in the page.

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

                            
  • Parameter Required Description
    data-type yes audio
    data-mp3 yes path to mp3 file
    data-artist artist name
    data-title song title
    data-description song description
    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
    data-peak-load path to optional waveform load image. If we dont have peak file already created and we load the player on browser that does not support Web Audio API (like old Internet Explorer versions), then if we provide load and progress backup images, we can still have waveform visible for the audio.
    Check wavesurfer section for more info.
    data-peak-progress path to optional waveform progress image. Same as data-peak-load.
    data-peak-dir Optional path where peak files are going to be saved. Default it 'peaks' folder in plugin directory. Use locate_directory.php file from includes folder to get path to the directory you want to use as peak folder. Place locate_directory.php in desired location and run it in web browser to get directory path.




    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="path/to/custom/share/path"
    data-share (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
    data-remote maybe If you get this message in browser console:
    No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin ... is therefore not allowed access.
    Add data-remote attribute to tell player to download the mp3 file first to your server after which peak file is going to be created from that downloaded file and afterwards, downloaded file is going to be deleted. This download process is only going to happen once until peak file is created. Note that it may take a while to download the file if the file is large.
    data-peak-dir Optional path where peak files are going to be saved. Default it 'peaks' folder in plugin directory. Use locate_directory.php file from includes folder to get path to the directory you want to use as peak folder. Place locate_directory.php in desired location and run it in web browser to get directory path.




    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="path/to/custom/share/path"
    data-share (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
    data-remote maybe If you get this message in browser console:
    No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin ... is therefore not allowed access.
    Add data-remote attribute to tell player to download the mp3 file first to your server after which peak file is going to be created from that downloaded file and afterwards, downloaded file is going to be deleted. This download process is only going to happen once until peak file is created. Note that it may take a while to download the file if the file is large.
    data-peak-dir Optional path where peak files are going to be saved. Default it 'peaks' folder in plugin directory. Use locate_directory.php file from includes folder to get path to the directory you want to use as peak folder. Place locate_directory.php in desired location and run it in web browser to get directory path.




    Reading mp3 files from directories - #top

    Folder playlist example:

                                
    Parameter Required Description
    data-type yes folder
    data-path yes absolute folder path or relative folder path to the plugin root directory.
    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="path/to/custom/share/path"
    data-share (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
    data-peak-dir Optional path where peak files are going to be saved. Default it 'peaks' folder in plugin directory. Use locate_directory.php file from includes folder to get path to the directory you want to use as peak folder. Place locate_directory.php in desired location and run it in web browser to get directory path.

    Folder organization

    You need to have following organization when loading files from folders:
    Example: data-path="../media/audio/1/"
    Inside directory named "1" we have mp3 and thumb files which need to be named the same!
    So you end up with this structure:
    song_01.mp3
    song_02.mp3
    song_03.mp3
    song_01.jpg
    song_02.jpg
    song_03.jpg


    Reading files on localhost

    1. path relative to the includes directory where folder_parser.php file is located
    data-path="../media/audio/1/"
    2. path absolute
    data-path="C:\xampp\htdocs\xampp\js\awp\_PREVIEW\content\media\audio\1"

    Reading files online

    1. path relative to the includes directory where folder_parser.php file is located
    data-path="../media/audio/1/"
    2. path absolute
    Use locate_directory.php file from includes directory and place it on your server in the same location where mp3 files are located and open it in browser to get desired folder location.
    data-path="/home/interact/public_html/awp/media/audio/1"
    If you have problems with absolute path try adding data-dir-url attribute in plalyist item with absolute path to the folder:
    data-path="/home/interact/public_html/awp/media/audio/1" data-dir-url="http://www.your-domain.net/awp/media/audio/1/"





    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="path/to/custom/share/path"
    data-share (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
    data-remote maybe If you get this message in browser console:
    No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin ... is therefore not allowed access.
    Add data-remote attribute to tell player to download the mp3 file first to your server after which peak file is going to be created from that downloaded file and afterwards, downloaded file is going to be deleted. This download process is only going to happen once until peak file is created. Note that it may take a while to download the file if the file is large.
    data-peak-dir Optional path where peak files are going to be saved. Default it 'peaks' folder in plugin directory. Use locate_directory.php file from includes folder to get path to the directory you want to use as peak folder. Place locate_directory.php in desired location and run it in web browser to get directory path.

    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






    Mixed media - #top

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




    Callbacks #top

    Parameter Description
    awpSetupDone (instance, instanceName) Called when component setup is finished and is ready to use API. Returns player instance, instanceName.
    awpPlaylistEnd (instance, instanceName) Called on playlist end. Returns player instance, instanceName.
    awpPlaylistStartLoad (instance, instanceName) Called when playlist load starts. Returns player instance, instanceName.
    awpPlaylistEndLoad (instance, instanceName) Called when playlist load ends. Returns player instance, instanceName.
    awpItemTriggered (instance, instanceName, counter) Called when new media is triggered. Returns player instance, instanceName, media counter.
    awpMediaStart (instance, instanceName, counter) Called when media starts. Returns player instance, instanceName, media counter.
    awpMediaPlay (instance, instanceName, counter) Called when media is played. Returns player instance, instanceName, media counter.
    awpMediaPause (instance, instanceName, counter) Called when media is paused. Returns player instance, instanceName, media counter.
    awpMediaEnd (instance, instanceName, counter) Called when media ends. Returns player instance, instanceName, media counter.
    awpPlaylistItemEnabled (instance, instanceName, target, counter) Called on playlist item enable. Returns player instance, instanceName, playlist item (target), media counter.
    awpPlaylistItemDisabled (instance, instanceName, target, counter) Called on playlist item disable. Returns player instance, instanceName, playlist item (target), media counter.
    awpPlaylistItemClick (instance, instanceName, target, counter) Called on playlist item click. Returns player instance, instanceName, playlist item (target), media counter.
    awpPlaylistItemRollover (instance, instanceName, target, counter) Called on playlist item mouseenter. Returns player instance, instanceName, playlist item (target), media counter.
    awpPlaylistItemRollout (instance, instanceName, target, counter) Called on playlist item mouseleave. Returns player instance, instanceName, playlist item (target), media counter.
    awpMediaEmpty (instance, instanceName) Called when active media gets removed (no active media). Returns player instance, instanceName.
    awpPlaylistEmpty (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.
    awpCleanMedia (instance, instanceName) Called when active media is destroyed. Returns player instance, instanceName.
    awpDestroyPlaylist (instance, instanceName) Called when active playlist is destroyed. Returns player instance, instanceName.
    awpVolumeChange (instance, instanceName, volume) called on volume change. Returns player instance, instanceName, volume.
    awpFilterChange (instance, instanceName) called after filter playlist items. Returns player instance, instanceName.

    API methods #top

    Parameter Description
    loadPlayMedia():void Call play after peaks have been drawn from peak file using drawWaveWithoutLoad:true in settings. Note that peak file is required to exist!
    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 awp-playlist-list
    inputAudio(data):void Play sound without creating any playlist data.
    data.mp3: mp3 audio path (required)
    data.title: song title (required for peak file)
    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
    getVolume():Number Get volume (0-1)
    setVolume(val:Number):void Set volume (0-1)
    toggleMute():void Toggle mute
    seek(value:Number):void Seek media:
    value: (time in seconds)
    getCurrentTime():Number Get current time
    getDuration():Number Get duration
    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
    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
    toggleInteraction():Object Toggle wavesurfer mouse interaction on the wave (wave seeking).

    Example of API is located in api.html demo.

    Using Wavesurfer #top

    Plugin used to create waveform: https://wavesurfer-js.org/

    Wavesurfer is set with following option in this plugin: backend: MediaElement

    This is required for audio to start playing immediatelly, while the wave is going to be drawn after the file has been downloaded (which can take a while on large files).

    After the wave file is created, plugin will save wave peak file in peaks folder (with the title of the audio file), and the next time same audio is loaded, it will just load this peak file (which is small in size) and draw wavefrom from that file, so waveform is going to be available immediatelly from second time any audio is used.

    Note that for peak file creation, which names are generated from audio titles, some characters are not allowed!
    Check details in new.js file: if(data.title)data.title = AWPUtils.checkKey(data.title);

    There is a wave image backup option available:
    If we dont have peak file already created and we load the player on browser that does not support Web Audio API (like old Internet Explorer versions), then if we provide load and progress backup images, we can still have waveform visible for the audio.

    Example of load and progress backup images provide with data-peak-load and data-peak-progress:
                                

  • To create load and progress backup images, use image_wave_create folder from plugin package. Place mp3 files inside 'mp3' directory and run php-waveform-png.php file online, after which load and progress backup images are going to be created in 'wave' directory. Note that it may take a while to create image waves if mp3 files are large.

    Inside php-waveform-png.php file, you can set waveform width, height, load and progress colors.

    Plugin used in this image wave creation is https://github.com/afreiday/php-waveform-png (slightly modified)


    Other notes:

    1. Because mp3 decoding is expensive, very large tracks might crash on memory exhaustion, but it depends on the computer where the decoding is done. http://stackoverflow.com/questions/20261158/html5-web-audio-api-wavesurfer-js-crashes-on-large-mp3-files

    2. Wavesurfer files are modified by me, which means you need to use those files provided with the plugin in following order:
                                
                                
                                
                                
                                
                                
                                
                                
    Changes are listed in ___changes.txt file in wavesurfer directory.

    Social sharing #top

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

    Troubleshooting #top

    Loading remote files like Podcast, Soundcloud, Google Drive

    If you get this message in browser console when trying to load remote audio files:
    No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin ... is therefore not allowed access.

    Add data-remote attribute to tell player to download the mp3 file first to your server after which peak file is going to be created from that downloaded file and afterwards, downloaded file is going to be deleted. This download process is only going to happen once until peak file is created. Note that it may take a while to download the file if the file is large.
                            
    In my testing, this was required for Podcast, Google Drive, but not for Soundcloud.


    If you get this message in browser console when trying to load remote audio files over https:
    Unable to find the wrapper “https” - did you forget to enable it when you configured PHP?

    In the php.ini file you should add this lines if not exists:
    extension=php_openssl.dll
    allow_url_fopen = On
    Restart your server, and your done.


    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