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.


<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:


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


... 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:


... and an associated JPG file exists as:


... 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:


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


... 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.


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:


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


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


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

<!-- This player would show the contents of "artistA" -->
<div data-wimpyplayer

<!-- This player would show the contents of "artistB" -->
<div data-wimpyplayer

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:


... 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


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:


... 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;



Option Description


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




Returns wimpy.php version




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




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




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 Options

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

Option Description


Enable or disable folder navigation.


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


Sets the default extension used to discover cover art images.


Set's the extensions to recognize as media files.


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


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


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


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


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.


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


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


This option will parse mp3 files for embedded images.*


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.


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


Sets the sort order for files.


Which field to sort on.


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


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.