WordPressAudioPlayer

Summary: Embed the WordPress Audio Player (Standalone version), by Martin Laine, to play MP3s.
Version: 2012-09-05 (uses WordPress Audio Player version 2)
Prerequisites: None
Status: Beta
Maintainer: Jess Harpur
Categories: Media, Audio

Users: (view / edit)

Questions answered by this recipe

  • How can I embed Martin Laine's Standalone WordPress Audio Player in my pages?

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

As the name implies, the WordPress Audio Player was created as a plugin for the WordPress blogging platform. Martin Laine, the developer, also makes available a standalone version which can be embedded in any webpage. This recipe facilitates embedding the standalone player in PmWiki pages using markup.

Player Demo Page

You can see the player in action here: http://jharps.co.uk/playerdemo/index.html

Installation

The package has the following structure and content:

 WPap/
 |- cookbook/
 |  `- wpap/
 |     |- ReadMe.txt		Recipe information
 |     |- License.txt		Recipe license
 |     `- wpap.php		The recipe
 |
 `- pub/
    `- wpap/
       |- audio-player.js	Javascript for the player
       |- player.swf		The player itself
       |- wpap.cfg		Jess's preferred settings
       `- MP3s/			Place mp3 files in this folder
       				if you want the player to access
       				them using the simplest markup
       				(see Quick Start)

1. Download the ZIPΔ and extract the contents of the cookbook and pub folders into the cookbook and pub folders of your wiki.

2. Insert the following line into your local configuration file, usually pmwiki/local/config.php:

 include_once("$FarmD/cookbook/wpap/wpap.php");

Quick Start

This recipe can be used 'out of the box', no configuration necessary. Simply put the mp3 file you want to play in the pub/wpap/MP3s/ folder, then use the following markup (replacing 'Sample.mp3' with the name of your mp3 file):

 (:wpap |Sample.mp3|| :)

 [Please note: All three pipe (|) characters are required.]

The above markup will embed the player on your page using this recipe's default configuration. The player will display the Artist and Track Title from the ID3 Tags in the mp3 (you might have to click the Play button first).

Configuration

You can alter the appearance and behaviour of the player in two ways; globally, which affects all instances of the player, or only for a particular instance of the player. This section explains how to set global options. Configuring a single instance of the player is covered in the Usage section (see below).

Global options can be changed from the default in two ways. Firstly, to use the player's built-in default configuration (see this page: http://wpaudioplayer.com/standalone/), insert the following line before the include_once line in congig.php, so it looks like this:

 $wpap_width = "290";
 include_once("$FarmD/cookbook/wpap/wpap.php");

 [You can replace the 290 with the desired width of the player in pixels.]

Secondly, you can create your own configuration file and place it in the pub/wpap/ folder. It must be named: user.cfg

The format of user.cfg must follow that of the wpap.cfg file, which can be found in the pub/wpap/ folder. If the recipe finds a file named user.cfg in the pub/wpap/ folder, it will be used instead of the wpap.cfg file.

The only configuration item that is obligatory in the user.cfg file is the width setting. The other items do not need to be present, and those that are not specified will be set to the player's built-in default. It is important that the user.cfg file contains only one @ character, which must be on the line immediately before the width setting (the first item). Eg:

 @
 width: "500",
 autostart: "no"

 [Note that each item: "value" line must be terminated with a comma, EXCEPT the last line.]

You can change the default location for mp3 files by inserting the following line before the include_once line in config.php, so it looks like this:

 $wpap_DefaultMp3Url = "http://yoursite.com/path/to/default/MP3sFolder/";
 include_once("$FarmD/cookbook/wpap/wpap.php");

 [Please note: the trailing forward slash (/) is required.]
 [Also, I sincerely hope that I don't need to point out that you
  should replace the url in the above example with a 'real' one!]

Usage

There are two versions of the Markup for WordPressAudioPlayer - standard and extended. The standard version takes the following form (square brackets indicate optional items):

 (:wpap [playerID]|target mp3 file(s)|[track title(s)]|[artist(s)] :)

playerID:

A decimal number. Please note that this is NOT optional when two or more players are used on the same page. Each player must have a unique ID.

target mp3 file(s):

If the mp3 file(s) are located in the pub/wpap/MP3s/ folder then this item needs only to list the file name(s), as a comma separated list. This also applies if $wpap_DefaultMp3Url has been set in config.php. If the files are located elsewhere, then the full url to each file is required.

track title(s):

If there are no ID3 tags in the mp3 file(s), or you want to override them, you can insert a comma separated list of track titles which corresponds to the target mp3 file(s) list.
artist(s): Similarly, you can insert a comma separated list of artists.

Please note: Do not use a pipe (|) character as part of the title or artist name. Likewise, do not use the :) combination!


Some Usage Examples:

 1.
 (:wpap |http://dl.dropbox.com/u/6596363/WPap/Sample.mp3|| :)
Loads the player with Sample.mp3 from my Dropbox account, and attempts to display the ID3 tags in the file. You can use the above markup in your PmWiki pages to test the installation of the recipe. You will probably find that the player plays the track but fails to display the ID3 tags. That's an issue with the player, not this recipe.
To display the correct track/artist details, adjust the markup like this:
 (:wpap |http://dl.dropbox.com/u/6596363/WPap/Sample.mp3|Agitar Los Gránulos De Salsa|k u: l i: :)
(If you like that track, there are more available at the k u: l i: SoundCloud page: http://soundcloud.com/k-u-l-i)
 2.
 (:wpap |Sample.mp3|Our Song|My Favourite Artist :)
Loads the player with a file named Sample.mp3 (from the default folder), and forces it to display 'Our Song' and 'My Favourite Artist' instead of any ID3 tags within the file.
 3.
 (:wpap |Sample.mp3,Sample 2.mp3,Sample 3.mp3|| :)
Loads the player with the three mp3 files listed (from the default folder), and uses their ID3 tags for the display.
 4.
 (:wpap |Sample.mp3, Sample2.mp3, Sample3.mp3|Song1,Song2,Song3|Artist1,Artist2,Artist3 :)
Loads the player with the three mp3 files listed (from the default folder), and overrides any ID3 tags, displaying instead the track titles and artists as listed.
 5.
 (:wpap 1|Sample.mp3|| :)
 (:wpap 2|Another.mp3|| :)
Loads two instances of the player, each containing a different mp3 file. Note that each player has been given a unique playerID (before the first pipe (|) character). There does not appear to be a limit on the number of players which can be used on a page.




Extended Markup

The second form of markup - wpapx: - allows players to be configured individually, by adding configuration data after an additional pipe character in the markup. The additional configuration data must take the form of a list of comma separated key:'value' pairs. An example of a key:'value' pair is:

 width:'250'

Note that the 'value' part must be enclosed in single quotes. Do not use "double quotes".

Example usage:

 (:wpapx |Sample.mp3|||animation:'yes', volslider:'FF0000' :)
Loads the player with Sample.mp3 (from the default folder), displays ID3 tag info from the file, animates the player, and sets the volume indicator to display in red, overriding the default settings.

The list of configuration options, and their default settings, can be found at the WordPress Audio Player (Standalone version) webpage: http://wpaudioplayer.com/standalone/

Notes

2012-09-05: I'm fairly new to PmWiki and programming in PHP. This is my first recipe, so please be gentle with me if something doesn't work as expected! Jess Harpur

Change log / Release notes

2012-09-05:

Optimised code.
Updated documentation.

2012-09-03:

Added configuration option to change default location of MP3s.
Added extended markup to cater for configuration of individual players.
Bug fixes.
Updated documentation.

2012-09-01:

Initial release

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

Comments

See discussion at WordPressAudioPlayer-Talk?

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.