Automatic Playlists

 

With this feature you can manage what is displayed within a player by simply managing the files and folders on your server via FTP  -- and you don't have to touch the player's HTML code to add or remove tracks.

NOTE: Automatic Playlists only work if your server supports PHP scripting because Automatic playlists rely on server-side scripting (PHP) to automatically detect media files playlists and sub-folders.

By default, Wimpy runs in "automatic playlist" mode -- displaying the media files in the WImpy Installation Folder.

 

Automatic Playlists Outide the Wimpy Folder

You can leverage the automatic playlist feature for folders outside the main Wimpy installation folder by simply placing a copy of the wimpy.php file into your other folder, then targetting that wimpy.php file for the "media" option.

Example

<div data-wimpyplayer data-media="/other/folder/wimpy.php"></div>

If you're using the getid3 option to automatically get the ID3 information from media files, you'll have to copy the entire wimpy.getid3 folder to the same location as the wimpy.php file as well.

Managing Automatic Playlists with Customizer

You can incorporate these "other" folders that have a wimpy.php file in them with Customizer. To do so, you'll add a new "location" to the Playlist Manager Panel. See the tutorial titled "Automatic Playlists " on the tutorials page.

 

About the Wimpy PHP File

The PHP script used to enable "automatic playlists"  is named "wimpy.php", which is included in the Wimpy download package.

It is used to discover:
- Media Files
- Sub-Folders
- Cover Art Images
- XML Playlists

It also enables folder/sub-folder navigation within Wimpy. In other words, when Wimpy is running off of wimpy.php, Wimpy acts as a browser for the folder that the wimpy.php file is located within.

It generates Wimpy formatted XML playlists "on the fly" -- allowing you to focus on organizing and updating your media on the server without having to modify any HTML code on your pages.

 

 

 

Cover Art

By default Wimpy is set up to detect JPG or PNG files for:
- Media files
- XML playlists and s
- Sub-folders.

For media files and XML playlists, Wimpy looks for files that have the same "base name". If a matching file is found, the image will be available for display within the player.

Media File Example

If a media file is located here:

/media/song1.mp3

... and a JPG image has an identical "base name", but with a "jpg" extension as:

/media/song1.jpg

... then the JPG file will be used as the cover art for the MP3 file.

 

XML Playlist Example

Likewise if an XML playlist is located here:

/media/playlist.xml

... and an associated JPG file exists as:

/media/playlist.jpg

... then the playlist.jpg file will be used as the cover art for the playlist.

 

Sub-folders are handled a little bit different. What we do is put a file named "coverart.jpg" into the sub-folder.

Sub-Folder Example

 

If a sub-folder resides here:

/media/some_folder/

... and a "coverart.jpg" file exists within it as:

/media/some_folder/coverart.jpg

... then the "coverart.jpg" file will be used as the cover art for the sub-folder.

NOTE: You can change the default file Wimpy looks for from "coverart.jpg" to "whatever.png" by manually editing the wimpy.php configuration options.

Navigation

Wimpy is set up to display the media files in one folder at a time. When sub-folders exist in a given folder, these sub-folders appear within the player as links. Clicking on a sub-folder in the player will reveal the contents of the sub-folder. Using the "back" button on the player causes Wimpy to make a new request to load the contents of the parent folder.

If XML playlists exist in a folder, the playlists will appear within Wimpy the same as a sub-folder. Clicking on an XML playlist will open it. Clicking the "back" button in the player will return to the original folder list.

XML playlists can be established to mimic the navigational features of automatic playlists. See "Playlists Within Playlists".

Wimpy can also be configured to automatically traverse all sub-folders. To do so, change the "$findAllMedia" option to TRUE within the "wimpy.php" file.

 

Targeting Sub-folders Directly

You can also target sub-folders directly. For example, if you have a copy of the wimpy.php file located here:

http://www/media/wimpy.php

... and in the "media" folder you have some sub-folders like:

http://www/media/artistA
http://www/media/artistB
http://www/media/artistC

... then you can target these sub-folders directly using the "d" directive as:

http://www/media/wimpy.php?d=http://www/media/artistA
http://www/media/wimpy.php?d=http://www/media/artistB
http://www/media/wimpy.php?d=http://www/media/artistC

Here's how things would appear in a player instance:

<!-- This player would show the contents of "artistA" -->
<div data-wimpyplayer
data-media="http://www/media/wimpy.php?d=http://www/media/artistA"></div>

<!-- This player would show the contents of "artistB" -->
<div data-wimpyplayer
data-media="http://www/media/wimpy.php?d=http://www/media/artistB"></div>

IMPORTANT When using the "d" directive, you can only target folders that are sub-folders of the folder that wimpy.php resides within. You can not target external folders, only local folders.

For example if wimpy is located here:

http://www/media/wimpy.php

... then you can not target any folder outside of the "media" folder. So this would NOT work:

<!-- This will not work because "somewhere" is not a sub-folder of "media".
Since wimpy.php is located within the "media" folder, it can only target
the contents of "media" or sub-folders of "media"
-->
<div data-wimpyplayer
data-media="http://www/media/wimpy.php?d=http://www/somewhere/else"></div>

 

Creating XML Playlists with wimpy.php

You can save a lot of server CPU cycles by caching playlists to XML files. Simply enter the URL to wimpy.php in a browser. The result will be an XML file that you can save to your local PC, then upload to your server.

Then use the "media" option and set the media option to the URL to the playlist file.

Manually Sorting with Quirksmode

Quirksmode allows you to set the order of the files manually. With quirksmode enabled, rename files and folders by prefixing the file/folder names with ## + dot as:

01.ccc.mp3
02.zzz.mp3
03.aaa.mp3

... Then the items will appear in the playlist based on the order of the ##'s. Wimpy will eliminate the ## + dot in the playlist when viewed in the player.

To enable quirks mode, open the wimpy.php file with a code editor and change the following line that reads as:

$quirksmode = false;

... to read as:

$quirksmode = true;

 

Wimpy PHP API

Option Description

d

Returns XML playlist for URL provided. NOTE: Can only return sub-folders. External folders are prohibited.

wimpy.php?d=http://www/path/to/folder

.

v

Returns wimpy.php version

wimpy.php?v

 

o

Returns "ok". A means to ping wimpy.php to see if it exists.

wimpy.php?o

 

i

Instructs wimpy.php to extract ID3 data from files and incorporate into the returned playlist.

wimpy.php?i&d=http://www/path/to/folder

 

jj

Returns image associated with media file. This may return a physical file, if a physical file can not be found, then wimpy.php will attempt to extract the image from the MP3 file via the getid3 library (if it exists).

wimpy.php?jj=http://www/path/to/file.mp3

 

Wimpy PHP Options

There are a number of options within wimpy.php that you can set manually to customize how it behaves functions.

Option Description

allowFolderNavigation

Enable or disable folder navigation.

playlistKind

Sets the kind of playlist to generate. Wimpy can parse numerous types of playlists including simple text-based lists and JSON playlists.

defaultVisualExt

Sets the default extension used to discover cover art images.

media_types

Set's the extensions to recognize as media files.

hide_keywords

A comma-delimited list of key words to ignore when reading file names.

httpOption

Sets whether HTTP or secure HTTPS should be used in the URL to media files.

hide_folders

A comma-delimited list of folder names to ignore when reading folders.

hide_files

A comma-delimited list of folder names to ignore when looking for files.

findAllMedia

When set to true, all media within sub-folders will be traversed and the resulting list will be a gigantic list of all media files in all sub-folders.

coverartBasename

The file to look for within sub-folders to represent the cover art for the entire folder.

getID3info

When set to true, ID3 meta data will be extracted from media files.*

getID3image

This option will parse mp3 files for embedded images.*

quirksmode

If not using the getID3 library, sets titles using the filename, but only shows text "between the dots" example: 01.MyTrack.mp3 would display as "MyTrack". This allows for files to be manually sorted within the folder.

See this page for more information.

shuffle

Randomizes the file list order. (Does not randomize folder lists.) NOTE: The player also has sorting options, so this option is kind of redundant.

sortOrder

Sets the sort order for files.

sortIndex

Which field to sort on.

urlStyle

Sets how URLs are represented. Using either the "from the root" method, or a fully qualified URL.

allowCrossDomainAccess

Allows this script to be called from another domain (or local file system).

 

 

 

 

* Wimpy.php depends on the GetID3 library (included in the Wimpy download package) to extract cover art images. And because this process is processor intensive, this feature must be manually enabled by editing the wimpy.php file directly and setting the "$getID3image" variable to TRUE.