Auto adds an mp3 audio player to pages / posts that you make a playlist on. Can be customised into themes.
Contributors: simon.ward
Donate link:
Tags: mp3, audio, player, music, jplayer, integration, music player, mp3 player, playlist, media, jquery, javascript, plugin, shortcode, css, post, page, sidebar
Requires at least: 2.8
Tested up to: 3.0.1
Stable tag: 1.3.4
Version 1.3.4 adds a set of template tags for sidebar/header players etc, new shortcode options including centering and download setting, and a smaller player size option.
Features:
The player can be added to the most recent post on the post index (that has a playlist), or using template tags it can be put in sidebars/headers etc, fed a playlist, appear on archive pages, and set a stylesheet. Player has sliders, loader bar, status info, and optional download button.
Making a Playlist
Add tracks on page/post edit screens using the custom fields (below the content box), as follows:
In the left box of a new custom-field enter:
mp3
Write the filename or URI* of the mp3 into the right box and hit 'Add custom field'.
Repeat the above to add more tracks, and hit the 'update/publish' button when you're done.
*Use a full URI when the mp3 is not in either a) the library or b) from the default folder/uri. You'll need to set the default folder that you want to use on the settings page.
Adding a Title
Add titles in the right box, before the filename (or uri), separate with an @ sign, eg:
Title@filename
Adding aCaption
Add the caption in the left hand box after 'mp3', separate with a dot, eg.
mp3.Caption
You can blank out a library caption (or a caption that's been carried over from a previous track) by using just the dot (ie. 'mp3.')
Play Order
To control the playlist order number the left hand boxes, eg:
1 mp3
2 mp3.Caption
3 mp3.Another Caption
Shortcode
Using the shortcode is optional, it lets you position the player within the content rather than at the top of it, and has 4 optional attributes for controlling the position (pos), download setting (dload), autoplay (play), and show playlist (list) on each page. The shortcode is:
[mp3-jplayer]
The attributes are:
pos: left, right, rel (or none), rel-C, rel-R, absolute
dload: true, false
play: true, false
list: true, false
for example
[mp3-jplayer play="true" pos="rel-C" dload="true"]
Template Tags
Quick example: Make the player move to sidebar on the posts index and play 5 random tracks from your library
Put this in index.php before the posts loop starts:
<?php if ( function_exists('mp3j_flag') ) { mp3j_flag(); } ?>
Put this in sidebar.php somewhere below the opening div(s):
<?php
if ( function_exists( 'mp3j_grab_library' ) ) {
$lib = mp3j_grab_library();
$files = $lib['filenames'];
shuffle( $files );
$files = array_slice( $files, 0, 5 );
mp3j_set_meta( $files );
mp3j_put( 'feed' );
}
?>
To use the smaller player stylesheet on the above example put this in header.php above wp_head():
<?php
if ( function_exists('mp3j_addscripts') ) {
if ( is_home() ) {
mp3j_addscripts('/wp-content/plugins/mp3-jplayer/css/mp3jplayer-blu-sidebar.css');
}
}
?>
Tag Details
Note: there's an admin option to ignore the tags which needs to be unticked when you want to use them!
mp3j_addscripts( $style )
Forces the player's javascript/CSS to be loaded and allows you to change stylesheet. Scripts aren't automatically enqueued on archive pages and any singular that has no playlist of it's own. When used this tag must be placed above wp_head().
$style can be either a uri to a stylesheet, or 'styleA', 'styleB', 'styleC', 'styleD' to use one of the included. Defaults to admin setting if not specified.
mp3j_flag( $set )
Tells the plugin to ignore content and shortcodes and to wait for an mp3j_put tag. The flag tag can be anywhere and can be used more than once.
$set can be either 1 (set the flag) or 0 (unset the flag), and is 1 if not specified.
mp3j_grab_library( $format )
returns an array of all the mp3's in the library with their 'filenames', 'urls', 'titles', 'excerpts', and 'descriptions'. Can be used anywhere.
$format can be either 1 (gives back the above fields in indexed arrays) or 0 (gives back the arrays as returned from the select query), defaults to 1.
mp3j_set_meta( $tracks, $captions )
Sets an on-the-fly playlist for the mp3j_put tag to pick up. Can be used anywhere to create a playlist. The arrays you feed in go through the same sorting/filtering routine as if the tracks had been pulled from a page or post, and still respond to the admin settings like 'hide file extension' or 'play in alphabetical order'.
$tracks must be an indexed array of any mix of either filenames (from default folder or library) or full uri's, and can include a prefixed title using an '@' as a separator same as the fields do. As the admin settings are still applied, if 'always use library titles..' is ticked and it's a library 'filename' that you're using then any corresponding caption in the $captions array won't make it through, to get control of titles and captions for library files use their 'urls' in the $tracks array.
$captions is an optional array, the indexes should correspond to the indexes of their files in the $tracks array.
mp3j_put( $mode, $position, $dload, $autoplay, $playlist )
Puts the player on the page (but only if mp3j_flag is set and what you're asking it to play results in some tracks!). Can be used multiple times and must be within the <body></body> section of a page.
$mode can be: A post id to grab tracks from; 'first' to pick up the tracks from the first content encountered that had a playlist (see note below); 'feed' to pick up an alternative playlist created with mp3j_set_meta; or not set ('') to pick up tracks from any current id;
$pos can be 'left', 'right' for float; 'none', 'rel-C', 'rel-R' for relative position; or 'absolute'). Defaults to admin setting
$dload - show download button, 'true' or 'false'. defaults to admin setting.
$autoplay - 'true' or 'false'. defaults to admin setting.
$playlist - start with playlist showing, 'true' or 'false'. defaults to admin setting.
Note on 'first': Typically you'd use this on an index page when the player is in the sidebar (ie. when the put tag comes after the loop has run) and you want to play the most recent tracks post. If there is no first id to collect (when no posts have a playlist) the player would not be added, to set a backup use another put tag directly underneath the first with $mode set to some id you want to pick up tracks from, or set to 'feed' to pick up an alternative playlist you've created using mp3j_set_meta.
Another note on 'first': Because it actually waits for the content and has a look for tracks, it won't do anything if the put tag using 'first' is above the loop. To get header players to play the first post with tracks you either have to put the put-tag in a div after the loop and css absolute position it, or query the upcoming posts and use the id.
mp3j_debug($info)
Prints some info and variables from the plugin to the browser's source view (CTRL+U or Page->view source) about what content and tags appeared on the page that just ran. Can be used more than once to get info at different points in page. Can be useful for debugging when customising templates.
$info can be 'vars' to see info only or 'all' to also see meta and library arrays (a potentially long list), defaults to vars.
Best to use function_exists() to make sure the tags exist before running them, eg:
<?php if ( function_exists('mp3j_addscripts') ) { mp3j_addscripts('styleD'); } ?>
Running them without checking when the plugin is not activated will throw an error.
To install using Wordpress:
To Install manually:
/wp-content/plugins directory on the server.Yes from this version 1.3.4 if you use template tags. It's not a widget yet so you can't do it from the admin area currently.
It's not anymore, it was going to be for testing a default install without needing to know any mp3's. So you could activate, go to a page and use 'test' as the filename and it would play that file from my domain, but a)i forgot to mention it, and b)it's prob not that useful. On fresh install it's now set to the root of your domain.