# 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