E-Phonic MP3 Player Documentation

E-Phonic MP3 Player Documentation

  • Installation
  • Implementation
  • Adding your mp3 files
  • Parameter overview
  • Javascript API
  • Registration
  • Security
  • Skinning documentation (beta)

    Installation

    First, extract 'mp3player.zip' somewhere on your hard disk.
    The contents of this zipfile is basically the default setup, so when you open the 'example_nobius.html' you will see a working example of the MP3 player.
    If you upload all files to your website you should have the example working online already!

    Implementation

    For implementation of the MP3 Player in a HTML file, we use the popular SWFObject javascript. (swfobject.js)
    This script also makes it easy to pass parameters to the MP3 Player.

    In the head of the page we include the SWFObject script: 
    <script src="swfobject.js" type="text/javascript"></script>
    If you want to use the Javascript API to control the player you should also include the ep_player.js script: 
    <script src="ep_player.js" type="text/javascript"></script>
    In the body of the page we include the MP3 Player code:
    First we set the alternative content for people who don't have javascript turned on or have an old Flash Player. 
    <div id="flashcontent">
	To use the <a href="http://www.e-phonic.com/mp3player/" target="_blank">E-Phonic MP3 Player</a>
	you will need <a href="http://www.adobe.com/products/flashplayer/" target="_blank">Adobe Flash Player 9</a> 
	or better and a Javascript enabled browser.
</div>
    Now we set the Flash Movie and its parameters.
    <script type="text/javascript">
	// <![CDATA[

	var so = new SWFObject("ep_player.swf", "ep_player", "269", "226", "9", "#FFFFFF");
	so.addVariable("skin", "skins/nobius_blue/skin.xml");
	so.addVariable("playlist", "playlist.xml");
	so.addVariable("autoplay", "false");
	so.addVariable("shuffle", "false");
	so.addVariable("buffertime", "1");
	so.write("flashcontent");

	// ]]>
</script>

    Adding your mp3 files

    There are two ways of loading MP3 files. You can load a playlist or just load a single MP3 file.

    Loading a playlist

    To add your mp3 files, open 'playlist.xml' in a plain-text editor like Notepad.
    You will see: 

    <?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns = "http://xspf.org/ns/0/">
  <trackList>
  
    <track>
      <location>mp3/demo.mp3</location>
      <title>MP3 Player!</title>
      <creator>E-Phonic</creator>
    </track>
    
  </trackList>
</playlist>

    To add your mp3-files just add a new track to the trackList node.
    Please note that the 'location' value can be a relative path or a absolute path to the mp3-file like shown below. 

    <?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns = "http://xspf.org/ns/0/">
  <trackList>

    <track>
      <location>mp3/demo.mp3</location>
      <title>MP3 Player!</title>
      <creator>E-Phonic</creator>
    </track>
 
    <track>
      <location>mp3/mymp3.mp3</location>
      <title>My song 1</title>
      <creator>Me</creator>
    </track>

    <track>
      <location>http://www.mywebsite.com/mp3files/mymp3.mp3</location>
      <title>My song 2</title>
      <creator>Me</creator>
    </track>
 
    </trackList>
</playlist>
    Loading a single MP3 file

    To load a single MP3 file, replace the 'playlist' parameter in your html with the 'file' parameter as shown below.

    so.addVariable("file", "<location>http://www.yourwebiste.com/song.mp3</location><creator>Song Creator</creator><title>Song Title</title>");

    Parameter overview

    These parameters can be added to the SWFObject of your player.

    playlist The playlist you want to load
    so.addVariable("playlist", "playlist.xml");
    file The MP3 file, creator and title you want to load
    so.addVariable("file", "<location>http://www.yourwebiste.com/song.mp3</location><creator>Song Creator</creator><title>Song Title</title>");
    playlistxml An xml string containing a playlist
    so.addVariable("playlistxml", "<track><location>song.mp3</location><creator>Song Creator 1</creator><title>Song Title 1</title></track><track><location>song.mp3</location><creator>Song Creator 2</creator><title>Song Title 2</title></track>");
    autoplay Start playing on load (true or false)
    so.addVariable("autoplay", "false");
    shuffle Shuffle playlist (true or false)
    so.addVariable("shuffle", "false");
    repeat Repeat playlist (true or false)
    so.addVariable("repeat", "false");
    buffertime The time to preload a MP3 file before it starts playing (time in seconds)
    so.addVariable("buffertime", "1");
    volume The initial volume of the player.
    so.addVariable("volume", "50");
    mute Tells the player to mute on load.
    so.addVariable("mute", "false");
    key Your registration key
    so.addVariable("key", "YOURREGKEY");

    If you use more than one domain name, you can use multiple keys like this:
    so.addVariable("key", "YOURREGKEY1, YOURREGKEY2");
    notifyonevent Enables the player to call the 'EP_eventHandler' javascript function when the status of the player changes. (play, stop, pause, ...)
    The new event name will be passed as a string. See 'example_js_control.html' for an example implementation.
    so.addVariable("notifyonevent", "true");

    Javascript API

    There are several functions of the player that can be controlled by Javascript.
    If you want to use the Javascript API to control the player you should include the ep_player.js script to the head of your page: 
    <script src="ep_player.js" type="text/javascript"></script>
    For an example implementation, please check the example_js_control.html file that is included in the zip-file.

    To test your javascript calls on the local file system make sure you add the following parameter to your SWFObject:

    so.addParam("allowscriptaccess", "always");

    When calling one of the functions you should pass the instance name of the player so it knows what player to control.
    The instance name of the player is defined in your SWFObject (red text). 
    var so = new SWFObject("ep_player.swf", "ep_player", "269", "226", "9", "#FFFFFF");
    EP_play("ep_player");

    		 Starts playing the current MP3 file
    EP_pause("ep_player");

    		 Pauses the current MP3 file
    EP_stop("ep_player");

    		 Stops the current MP3 file
    EP_prev("ep_player");

    		 Loads the previous track in the playlist.
    EP_next("ep_player");

    		 Loads the next track in the playlist.
    EP_loadMP3("ep_player", "<location>http://www.yourwebiste.com/song.mp3</location><creator>Song Creator</creator><title>Song Title</title>");

    		 Loads a new MP3 file.
    EP_loadPlayList("ep_player", "myplaylist.xml");

    		 Loads a new playlist file.
    EP_playIndex("ep_player", 3);

    		 Loads a the specified item from the playlist.

    Registration

    You can remove the E-Phonic icon and the 'unregistered' text from the MP3 Player by obtaining a registration key from the E-Phonic website for only €14.99.
    The registration key will only work on your website.

    Register your player now for only €14,99 per website!

    After you register, you will receive your key on your PayPal email address.
    To complete the registration, you'll have to add the key parameter to your SWFObject code in your html.

    so.addVariable("key", "YOURUNIQUEKEY");
    So you get: 

    <script type="text/javascript">
	// <![CDATA[

	var so = new SWFObject("ep_player.swf", "ep_player", "269", "226", "9", "#FFFFFF");
	so.addVariable("skin", "skins/nobius_blue/skin.xml");
	so.addVariable("playlist", "playlist.xml");
	so.addVariable("autoplay", "false");
	so.addVariable("shuffle", "false");
	so.addVariable("buffertime", "1");
	so.addVariable("key", "YOURUNIQUEKEY");
	so.write("flashcontent");

	// ]]>
</script>
    To remove the E-Phonic icon from your interface, please remove the ephonic_icon tag from your skin.xml file.

    If your player isn't registered after this, please check the following points:

  • Clear your browser cache and check again.
  • Make sure that you are using the correct version of the swfobject.js. Version 1.5 or better is required.
  • Is your MP3 Player located inside a form tag?
    This is often used in ASP.NET sites and there currently is a bug in Flash Player that generates an error in this situation.
    Please use the following workaround to fix the error.

    Add an empty form tag (shown in red) just after the form tag the MP3 Player is in.
    Example code: 
    <form name="aspnetForm" method="post" action="Default.aspx" id="aspnetForm">
<form></form>
	
// FLASH PLAYER CODE

</form>

    Security

    For security reasons, a Macromedia Flash movie playing in a web browser is not allowed to access data that resides outside the exact web domain from which the SWF originated.
    However, these files can be loaded and accessed by the MP3 Player correctly if a crossdomain.xml file is placed on that domain.
    This way the MP3 Player knows it is allowed to load these files.

    MP3 files loaded from another domain without a crossdomain.xml file can't show spectrum visualizations because of this reason.
    In this case only the 'peak' visualization works.

    To fix this problem, use a crossdomain.xml file.
    Please read more about this at Adobe.com:
    http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_14213