Using the Jamroom 4 Play Script
The Jamroom Play script (play.php) can be utilized to generate many different types of playlists, depending on parameters that get passed to the play.php script. Normally, the play.php script is used to generate media player "playlist" files such as M3U, XSPF and ASF files. These files are in turn sent to the users audio player (such as iTunes, Windows Media Player, Winamp, etc.), which in turn plays the audio or video files that are part of the generated playlist.
The play.php script also supports some additional parameters that can be passed to the script that can be used in more advanced situations, such as:
- Creating a "master" playlist of all of your artists audio files
- Create a "self-updating" Radio Station playing a particular genre
- Creating a playlist for a group of artists
- Creating/modifying custom playlist formats
- and more...
The key to creating these additional playlists is to manipulate the input parameters to achieve the desired playlist.
Usage
The Jamroom Play script is called directly from your browser window:
play.php?mode=song_hifi&band_id=all&song_id=all&type=mp3
This example would play all mp3 files for all artists found in your Jamroom. As you can see, it's very simple, and a link to the play.php script can be embedded in any Jamroom template where you would like to make a dynamic playlist available.
Available Parameters
The following parameters are used by the play.php script:
| Parameter |
Required |
Default |
Description |
| mode |
no |
"song_hifi" |
The "mode" parameter tells Jamroom the media mode of the playlist generated. Valid "modes" include:
- song_hifi
- song_lofi
- radio
- video *
* only available with Jamroom Power Pack
|
| band_id |
yes |
n/a |
The band_id parameter tells Jamroom the id(s) of the artist profile(s) you would like to include in the playlist. The band_id can be:
- A single band_id - i.e. "&band_id=5"
- A group of band_id's - i.e. "&band_id[]=5&band_id[]=19" (note the square brackets)
- The special keyword "all" which means all band_ids in your Jamroom
|
| song_id |
yes* |
n/a |
The song_id parameter tells Jamroom the id(s) of the audio files(s) you would like to include in the playlist. The song_id can be:
- A single song_id - i.e. "&song_id=325"
- A group of song_id's - i.e. "&song_id[]=43&song_id[]=159" (note the square brackets)
- The special keyword "all" which means all song_ids in your Jamroom
- A text string, in which case Jamroom will attempt to use the string as the name of an Album, and only include audio files that are part of the album - i.e. "&song_id=Album+Name"
* the song_id is required for the "song_hifi" and "song_lofi" modes, and is ignored in other modes.
|
| id |
yes* |
n/a |
The "id" parameter tells Jamroom the Radio Station id you want to play. It must be a number - i.e. "&id=25".
* This parameter is only used when "mode" is set to "radio", otherwise it is ignored.
|
| video_id |
yes* |
n/a |
The video_id parameter tells Jamroom the id(s) of the video files(s) you would like to include in the playlist. The video_id can be:
- A single video_id - i.e. "&video_id=351"
- A group of video_id's - i.e. "&video_id[]=47&video_id[]=93" (note the square brackets)
- The special keyword "all" which means all videos_ids in your Jamroom
* the video_id is required for the "video" mode, and is ignored in other modes.
|
| type |
no |
n/a |
The "type" parameter tells Jamroom the type of playlist to create. Valid parameter values are:
- "ogg", "mp3" or "mid" - this will produce an M3U playlist
- "mov" - will create an .smi (SMIL) playlist
- "wma" - will create a WAX playlist
- "wmv", "mpg" or "mpeg" - will create an ASX playlist
- "xspf" - will create an XSPF XML playlist for use by the Jamroom Flash Player
|
| genre |
no |
n/a |
The "genre" parameter is only available in "song_hifi" and "song_lofi" modes. If given, the "genre" parameter tells Jamroom to only retrieve songs for a specific genre. This is most commonly used with the "band_id=all" and "song_id=all" parameters to create a playlist of all songs in a given genre. Example:
play.php?mode=song_hifi&band_id=all&song_id=all&genre=Hard+Rock&type=mp3
Please Note: the given genre must be urlencoded - see the Jamroom.net Urlencode Tool.
|
| quota_id |
no |
n/a |
The "quota_id" parameter is only available in the "song_hifi" and "song_lofi" modes. If given, the quota_id will restrict the playlist to including only songs from the given quota_id. Example:
play.php?mode=song_hifi&band_id=all&song_id=all"a_id=5&type=mp3
|
| limit |
no |
n/a |
The "limit" parameter is used for limiting the number of entries in the playlist to a specific limit. If you have thousands of songs in your Jamroom, this can be used to make sure the playlist only sends out a (maximum) of 10 entries. Example:
play.php?mode=song_hifi&band_id=all&song_id=all&limit=10&type=mp3
|
| random |
no |
0 |
If the optional "random" parameter is given, the playlist will be randomized before being sent to the listener. Example:
play.php?mode=song_hifi&band_id=all&song_id=all&limit=50&type=mp3&random=1
|
| repeat |
no |
"no" |
If the "repeat" parameter is given, and the "type" is WMA, then the WAX playlist that is created will include a "repeat" tag to make the remote player auto-repeat the playlist after it is finished. |
Example URLs
Here are some examples of different URLs you can construct and link to in your Jamroom:
- Create a master playlist of all artists, all songs in "hifi" mode:
play.php?mode=song_hifi&band_id=all&song_id=all&type=mp3
- Create a Playlist of only Windows Media Audio files, for Artists in Jamroom Quota ID "10", limiting to 40 results, with randomization:
play.php?mode=song_hifi&band_id=all&song_id=all"a_id=10&type=wma&limit=40&random=1
- Create a playlist of HIFI MP3 files, in the "rock" genre:
play.php?mode=song_hifi&band_id=all&song_id=all&genre=Rock&type=mp3
- Create a Video Playlist of all artists in Jamroom Quota ID 6:
play.php?mode=video&band_id=all&video_id=all"a_id=6
As you can see, the play.php script is very versatile, and likely can be used to replace some of your "System" Radio Stations. Using the play.php script is easier to use when you want your playlists to be dynamic, and automatically update as new media items are added to your Jamroom
Creating Custom Playlist Formats with the Play.php script
Jamroom 4.3 supports the ability for Jamroom Admins to create custom playlist formats using the play.php file. Users can either customize current playlist formats (i.e. xspf, smi, wax, m3u, etc.), or create their own playlist format. The files for creating/editing custom playlist formats can be found in the jamroom/include/plugins/jrPlaylist/ directory. In this directory, you will see two types of files: format.php and format.default.tpl, where "format" is the playlist format name (i.e., xspf.php and xspf.default.tpl). If you would lik to customize one of the current playlist formats, simply create a new template called format.tpl (replacing "format" with the playlist format you are editing, i.e. xspf.tpl if you want to customize XSPF playlists), and Jamroom will automatically use that template to construct your playlists instead of the default (format.default.tpl) template. After you have created the new template, you can copy and paste the content of the default template to your new template, and begin customizing it to suit your or your player's needs.
Each media item included in the playlist will be outputted to the $_MEDIA Smarty template array. You will need to use a Smarty {foreach}{/foreach} loop to loop through each of the elements (or media items) in the array. All general template variables (i.e. {$JAMROOM_URL}, {$JAMROOM_DIR}, {$_USER}, etc.) are also available in your custom playlist format.
Not only can Jamroom Admins customize current playlist formats, but, with some PHP knowledge, they can also create new playlist formats to meet there needs. There are two steps to creating a new playlist format:
- Create your playlist format .php file, named format.php, where "format" is the name of your new format. Your new playlist format name can be a maxiumum of four (4) characters long. Your format.php file must contain the following two functions: jrPlaylist_format_headers() and jrPlaylist_format_process(). The first function defines the headers that will be sent for the playlist, while the second function will process each of the media items to be included in the playlist.
- Create your playlists default playlist format template, modeled after the name format.default.tpl or format.tpl
After you have created your new playlist format's PHP and template files, you can then use add &format=xxxx to your play.php files, or add the format="xxxx" parameter to your jr_flash_player functions, (where xxxx is your playlist format's name), and the playlists generated will be in your new desired format!
 |
It is highly recommended that you look through the xspf.php and xspf.default.tpl files when looking to create your own playlist formats. You can copy and paste them to your new files and use them as a basis to build your new playlist formats from! |
|
