Overview

The Audio Player is a simple player written in Javascript, leveraging soundManager2‘s robust sound playing capabilities, to provide a crisp, clean solution to managing and playing audio tracks.

Requirements

If you are implementing the player on a ONESite hosted network, you already have everything you need! However, if you would like to make use of it on an external website, you will need the following:

  • soundManager2: Due to Cross-Domain policy restrictions, you will need to host soundManager2 somewhere on your own domain, and include it before you try to initialise the audio player. Please note that this is a fork of the original Sound Manager, maintained by ONESite. The source code can be found here: github.com/cthos/SoundManager2
  • jQuery: The audio player was built using jQuery v1.5.2. Newer versions are likely to work, but are not officially supported at this time.

Optional

  • jQuery UI: If jQuery UI is not detected by the audio player, it will attempt to load it from our CDN (fast1.onesite.com). However, this will probably change the order in which CSS is loaded, and may result in odd display cascading.

Installation

Before attempting to initialize the audio player, you will need to include the following Javascript on your page (including the requirements above, if you are using a non-hosted solution). 

<script type='text/javascript' src='http://fast1.onesite.com/resources/scripts/soundManager2/soundmanager2-nodebug-jsmin.js?ver=f4275'></script>
<script type='text/javascript' src='http://fast1.onesite.com/resources/scripts/classes/audio/Player.min.js?ver=f4275'></script>

Please note that if you are using a non-hosted solution, replace the sound manager url with your own copy of soundManager2.

Using ONESITE.audioPlayer

Loading the audio player is simple, and only requires 2 lines of javascript:

// This creates a new instance of the audioPlayer
var myPlayer = new ONESITE.audioPlayer();

// This tells it to build its interface in an html element with id "myAudioDiv".
// Note that 'myAudioDiv' can also be a jQuery object: $('#audioDiv');
myPlayer.init('myAudioDiv');

Important Note : If you are using your own version of soundManager2, you will need to pass a second parameter to init of {url: ‘/path/to/soundmanager/flash/files/’}. This is just an alias to soundManager.url so that documentation applies to this property too.

You’re done! But, what fun is an audio player with nothing to play?

Adding Songs to the Playlist

Once you have a working copy of the player, you’ll need to add songs to its playlist. This is accessed through the ‘play’ method.

The following example shows how to add a song to the audio player’s queue. Please see the method documentation for more information on the configuration object and properties.

myPlayer.play({
    url: 'http://mydomain.com/mysong.mp3',
    title: 'My New Song',
    element: 'mySongDiv',
    galleryName: 'My Best Album Yet',
    image: 'http://placehold.it/70x70'
},
true
);

After that, it is a simple matter to begin playing: 

myPlayer.playQueue();

What if I want to jump to a song that is already in the queue, programatically?

// It is really easy:
sound.play({
        title: 'My New Song'
    },
    {
        seek: true
    }
);

What about playing a song immediately that is not in the queue?

Just change the options parameter to boolean false. This will make the player stop what it is playing and play the new song right then. This will add the song to the queue at the position you were already at, so it is usually best to queue the file, and then seek to its position.

myPlayer.play({
    url: 'http://mydomain.com/mysong.mp3',
    title: 'My New Song',
    element: 'mySongDiv',
    galleryName: 'My Best Album Yet',
    image: 'http://placehold.it/70x70'
},
false
);

Default Behavior

Back Button

  • When a single song is queued, and the back button is pressed it will replay that song.
  • When multiple songs are queued, the back button will go to the previous song in the queue and will not replay the current song.

Next Button

  • In all instances if there are queued songs which have not been played, the next button will move onto the next song.
  • If the loopQueue option is set to true and the queue is empty, the next button will reset the entire queue and begin from the beginning.
  • However if loopQueue is false, the next button will do nothing if the queue is empty.

Advanced Configuration Options

.init(element, config)

element

This can be a string, at which point it is interpreted as an ID, otherwise, it should be a jQuery object.

config

A javascript object, with the following parameter possible:

  • defaultImage – The Default gallery image for the full view.
  • disableCSS – Tells the player not to load its default CSS
  • theme – What player theme to load. ‘mini’ is the only value (untested)
  • url – Where to find soundmanager2’s flash files. Due to same-domain policy you’ll need it on a non-onesite domain
  • buildTemplate – Tells the player to load the player html via ajax to a controller action (Experimental, use at your own risk, probably only works with ONESite Hosted accounts)
  • markTime – If this is set (in milliseconds) to a time, it will fire a jQuery event ONESITE.audioPlayer.triggerTime on each song that is played when that timer is hit. Typically used to keep track of if a user has listened to a certain amount of a song.
  • loopQueue – Tells the audio player that the queue needs to be looped after it reaches the end. This defaults to false

.play(song, options)

song

A javascript object accepting the following parameters:

  • url – URL of the song to play (Required)
  • image – the Gallery image to display
  • title – The title of the playing audio file
  • element – If passed this will have a class added to it of ‘oneAudioPlayer-playing’
  • serverUrl – Pass this in order to make akamai streaming function. Do not pass in the protocol, just pass in the server with the application name on the end. E.G. ‘c02912.edgecfs.com/ondemand’. It can also be used for regular RTMP, in which case, do send in the entire url: “rtmp://myserver.com/file_to_serve.mp3”
  • useAkamai – Tells the player that this song is hosted on an Akamai network.
  • isSecure – If the file is served by Akamai secure streaming, this will generate a token for you. Please note that this will only work on a ONESite hosted solution, and requires token/Akamai.min.js to function.
  • galleryName – This will populate the Gallery name section with whatever string you pass it.
  • galleryLink – If you would like the gallery title to link to a url, pass it here.
options

If Options is Boolean

  • true – Add this file to the end of the queue, and do not play it immediately.
  • false – Play this file immediately, and insert it into the queue at the current position.

If Options is an Object

  • queue : Whether or not to queue the file, same as the boolean option.
  • seek : Try to find a file in the queue with the same title, and play it.

Other Methods

.playQueue()

This can be called to move the player to the next song programatically, but this is handled in the interface automatically.

.playPrevious()

This will move the current song back to the song playing before this one. This is also handled by the interface.