Getting Started

The examples are only working on a webserver or a local webserver like MAMP or XAMPP since V1.4.3.

Include necessary files in your HTML document

First of all include all necessary files in the head part of your HTML document.
When you have a responsive website, you can also include jquery.fullwidthAudioPlayer-responsive.css file, so the player becomes responsive on mobile devices.

Include the CSS file:

<link rel="stylesheet" type="text/css" href="css/jquery.fullwidthAudioPlayer.css">
Include the Javascript files:
<script src="js/jquery.min.js" type="text/javascript"></script>
<script src="js/jquery-ui.js" type="text/javascript"></script>
<script src="//connect.soundcloud.com/sdk/sdk-3.1.2.js" type="text/javascript"></script>
<script src="js/jquery.fullwidthAudioPlayer.min.js" type="text/javascript"></script>
If you already include jquery in your page, you do not need to another one. Please use jQuery 1.6 or higher! jQuery UI Sortable is only required when you enable the sortable option.

Call the Plugin

Create a div element anywhere in your HTML document. This element can be empty or hold your default playlist.

<div id="fap"></div>
After that extend the already created Javascript block with the following code:
$(document).ready(function(){
  $('#fap').fullwidthAudioPlayer();
});

Since V2.0.1 - Using tracks from SoundCloud

In order to use tracks from SoundCloud, you have to register a SoundCloud app and copy the Client ID in the soundCloudClientID option.

$('#fap').fullwidthAudioPlayer({soundCloudClientID: 'your-sc-client-id'});

Check out the preview page to see the different techniques for adding tracks to the player!

Using the options to customize the player

You can customize the player with a lot of options, e.g. changing some colors:

$(document).ready(function(){
  $('#fap').fullwidthAudioPlayer({wrapperColor: '#000000', fillColor: '#ffffff'});
});

Option Explanation Default Value
wrapperPosition The position of the wrapper that holds the player - 'top', 'bottom' 'popup' or ID of an element. 'bottom'
mainPosition The alignment of the player - 'left', 'center' or 'right' 'center'
wrapperColor The background color of the wrapper '#f0f0f0'
mainColor The main color for the UI '#3c3c3c'
fillColor The background color for the UI buttons '#e3e3e3'
metaColor The color for some meta elements like the text under the track title '#666666'
strokeColor The color for the strokes '#e0e0e0'
twitterText The text for the twitter link 'Share on Twitter'
facebookText The text for the facebook link 'Share on Facebook'
height The height for the player without playlist 70
playlistHeight The height for the playlist 210
opened Player is opened from beginning (true) or closed (false) true
volume Enable/ disable volume bar true
playlist Enable/ disable visual playlist true
autoLoad Starts loading the track when soundmanager is ready and autoPlay is disabled true
autoPlay Starts playing as soon as the player is ready false
playNextWhenFinished Plays the next track when current one has finished true
keyboard Enable/disable the keyboard shortcuts true
socials Show/hide social links true
xmlPath The path to the XML file that holds your playlist ''
xmlPlaylist ID of the playlist which should be loaded into player from the XML file ''
Since V1.3:
popupUrl
The URL of the popout.html 'popup.html'
Since V1.3:
autoPopup
Pop out the player in a Pop-Up Window automatically false
Since V1.3:
randomize
Randomize default playlist false
Since V1.3:
shuffle
Show/hide the shuffle button true
Since V1.3.1:
sortable
Make playlist sortable via Drag&Drag false
Since V1.3.1:
base64
Set this to true when you would like to use the base64_encode() PHP function, to hide the MP3 URL false
Since V1.4.2:
hideOnMobile
Hide the player on all mobile devices false
Since V1.5:
loopPlaylist
When end of playlist has been reached, start from beginning true
Since V1.5:
storePlaylist
Stores the playlist in the browser, so when the user come back to the site, he will see the same playlist since the last time. You also need to include the amplify.min.js in your document, when setting this option to true. false
Since V1.5:
layout
The layout for the player, can be fullwidth or boxed. 'fullwidth'
Since V1.6:
keepClosedOnceClosed
Keeps the player closed, once the user closed it. false
Since V1.6.1:
animatePageOnPlayerTop
Moves the whole page down when the player is at the top, so the player does not overlap anything from the page. false
Since V1.6.1:
openLabel
The label for opening the playlist. +
Since V1.6.1:
closeLabel
The label for closing the playlist. ×
Since V1.6.1:
openPlayerOnTrackPlay
Opens the player when a track starts playing. false
Since V1.6.1:
popup
Enable the pop-up player button. true
Since V1.6.1:
selectedIndex
Sets the start track by index when the player is created. 0
Since V2.0.0:
htmlURL
Sets the URL to the file containing all relevant HTML. 'html/fwap.html'
Since V2.0.0:
loadingText
Sets the loading text. 'Loading Playlist'
Since V2.0.0:
popupTitle
Sets the title of the popup player. 'Fullwidth Audio Player'
Since V2.0.0:
popupBlockerText
Sets the text for popup blocker. 'Pop-Up Music Player can not be opened. Your browser is blocking Pop-Ups. Please allow Pop-Ups for this site to use the Music Player.'
Since V2.0.0:
howlOptions
Sets some custom options for howl (audio library) https://github.com/goldfire/howler.js#core. {}
Since V2.0.0:
debug
Makes some logs in the console. false
Since V2.0.1:
soundCloudClientID
You need to register an own soundcloud app and enter your client ID to avoid rate limits https://developers.soundcloud.com/docs/api/rate-limits#play-requests. ''

Web Audio vs HTML5 Audio

You can decide if you want to use Web Audio or HTML5 Audio. The player is using the howlerjs audio library. You can set any howlerjs options with help of the howlOptions. That way you can also enable the HTML5 audio, but depending on your requirements you have to decide for an audio API wisely.

Default: html5 = false (Web Audio is used)

  • Buffering is working
  • Large audio files need to be loaded fully to start playing
html5 = true (Web Audio is NOT used)
  • The next track will not be played automatically on mobile devices
  • Adding a SoundCloud Track from an in-page element does not play it directly, you have to click on Play Button in the player
  • No buffering

$('#fap').fullwidthAudioPlayer({howlOptions: {html5: true}});

Using Pop-Up Player

NOTE! On mobile devices the Pop-Up feature does not work, the player will be added at the top automatically!

Using the Pop-Up feature is very simple. First of all you only need to include these files in the main window - in my example it's the example_popup.html.

<script src="js/jquery.min.js" type="text/javascript"></script>
<script src="js/jquery.fullwidthAudioPlayer.js" type="text/javascript"></script>
If you would like to use another folder structure, you have to adjust the file includes in the popup.html. You do not need to edit any code in there. The plugin options, you set in the main window, will be send to the pop-up window.

So just set up your music player in the main window like explained in the above instrctions. You only have to adjust the wrapperPosition option:
$('#fap').fullwidthAudioPlayer({wrapperPosition: 'popup'});
If you would like to place the popup.html in a different folder, you need to set the URL of it in the options too:
$('#fap').fullwidthAudioPlayer({wrapperPosition: 'popup', popupUrl: 'myFolder/popout.html'});
You can also pop out the Pop-Up window automatically, but browsers with a Pop-Up Blocker will prevent the opening. This means the user have to allow Pop-Ups for your site.
$('#fap').fullwidthAudioPlayer({wrapperPosition: 'popup', popupUrl: 'myFolder/popout.html', autoPopup: true});

Once again you do not need to edit any code in the popout.html. You set your default playlist in the main window, which will be only loaded into the Pop-Up Player when autoPopup is set to true.

I recommend to take a look in the examples folder. There you find a proper solution how to use the Pop-Up feature.

Customizations

Using base64 to hide the track URL

If you want to hide the track URL in your document, you have to set the base64 option to true. For example you are using following code:

HTML/PHP code:
<a href="<?php echo base64_encode("TRACK_URL.mp3"); ?>" class="fap-single-track">Track Title</a>
Javascript code:
$(document).ready(function(){
  $('#fap').fullwidthAudioPlayer({base64: true});
});

Upgrading

To Version 2.0.1

  • Update jquery.fullwidthAudioPlayer.min.js, jquery.fullwidthAudioPlayer.css andfwap.html

To Version 2.0.0

  • Font Awesome is not required anymore. The audio player now is using an own font set.
  • Update jquery.fullwidthAudioPlayer.min.js, jquery.fullwidthAudioPlayer.css andpopup.html
  • Add fwap.html to your directory and set the correct URL to it in the options.
  • Update Soundcloud SDK: //connect.soundcloud.com/sdk/sdk-3.1.2.js

To Version 1.6

  • Include font-awesome 4.0.3: http://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css
  • Replace the jquery.fullwidthAudioPlayer.min.js, jquery.fullwidthAudioPlayer.css, jquery.fullwidthAudioPlayer-responsive.css andpopup.html with yours.

To Version 1.5.21

  • You have to include the soundmanager2-nodebug-jsmin.js in your document again.
  • Copy also the swf folder in your diretory.
  • Add the soundmanager settings javascript block:
    soundManager.url = 'swf/';
    soundManager.flashVersion = 9;
    soundManager.useHTML5Audio = true;
    soundManager.debugMode = false;
  • Replace the jquery.fullwidthAudioPlayer.min.js and popup.html with yours.

To Version 1.5

  • Use data-autoenqueue for enqueueing tracks, the fap-enqueue-track class does not exist anymore
  • Replace the jquery.fullwidthAudioPlayer.min.js, jquery.fullwidthAudioPlayer.css and popup.html with yours.

To Version 1.4.3

  • You do not need to include any soundmanager files by yourself, the soundcloud sdk (https://connect.soundcloud.com/sdk.js) loads these files by default. So remove any soundmanager script and css includes.
  • Remove also the soundmanager settings script block:
    soundManager.url = 'swf/';
    soundManager.flashVersion = 9;
    soundManager.useHTML5Audio = true;
    soundManager.debugMode = false;

To Version 1.4.1

Replace the jquery.fullwidthAudioPlayer.min.js and jquery.fullwidthAudioPlayer.css with yours. Copy also the images folder with the fwap folder in your directory.
You need to set also another soundmanager property:
soundManager.debugMode = false;

To Version 1.4

Replace the jquery.fullwidthAudioPlayer.min.js and jquery.fullwidthAudioPlayer.css with yours. You can also include an additional CSS file to make the player responsive.

To Version 1.3

Replace the jquery.fullwidthAudioPlayer.min.js and jquery.fullwidthAudioPlayer.css. Add also the popup.html in your folder. If you would like to use the new Pop-Up feature, please read the instructions for it!

To Version 1.2

Just replace the jquery.fullwidthAudioPlayer.min.js. That's it!



© 2013 | radykal.de