Wimpy SQL for MySQL

Version 1.0.52

Available at http://www.wimpyplayer.com
©2002-2009 plaino


- Set up
- Quick Start Guide
- Running a customized Wimpy MP3 Player off of the MySQL database
- Making a custom query through a customized Wimpy MP3 Player
- Troubleshooting


Wimpy SQL is a MySQL MP3 database administration utility.  Wimpy SQL extracts ID3 information from each MP3 file and puts the ID3 information into a MySQL database. Plus it's a cool network MP3 player too :)

This package includes the 15 day trial version of Wimpy MP3 Player, which displays "DEMO" within the player and will expire 15 days after initial installation . To remove the expiration, you will need to purchase a license for Wimpy MP3 Player for PHP.



  • A great user interface + MP3 player
  • Add, modify and delete database entries.
  • Create playlists
  • Export XML based playlists (Wimpy XML playlist format)
  • Generate a web-based MP3 player based on a playlist
  • Automatically retrieve cover art (requires an Amazon Web Services developer account)
  • Search database
  • Remove MP3s from disk
  • Recursively scan directories for MP3 files and cover art.

The way it works is that you upload MP3 files, then use Wimpy SQL to scan through the contents of your MP3 directory to automatically add each MP3 file to your database. The MP3 files can be above or below the public html root and they can also be located on different drives.

Wimpy SQL will scan through a given directory that contains MP3 files, which should be organized in sub directories, and. automatically add each MP3 file to your database.

Once the files have been added to the database, you can "view" the database by Artist or Genre or search your database. You can create customizable playlists to organize collections and generate a web-based player based on a playlist.





Set up

1. Download and unzip wimpySQL.zip package to your local machine..

Click here to download the Wimpy SQL for MySQL - PHP file.


2. Edit the configuration file.

Open wimpy.swl.configs.php in a text editor.and set the following variables for your desired or existing setup:


If you've purchased a license for Wimpy MP3 Player, enter your registration code here.


MySQL database name -- If the database does not exist, Wimpy will try to create it.


Admin user (full privileges)


Admin password

The rest of the options do not need to be edited, but can be if so desired.

Save the config file.


3. Upload all of the wimpySQL.

Wimpy SQL needs ot be located in a publically available area.


Here is a list of the files and folders that should be in your Wimpy MP3 Player installation folder:

+ getid3

The getid3 library, which is a part of the standard Wimpy MP3 download package

- coverart_fallback.jpg

This will get copied and renamed to folders that do not contain a "coverart.jpg" file

- index.php

The Wimpy SQL home page

- myWimpy.php

Used when the Playlist Tool "Make Player" is selected. You can create a new one with the online Customizer tool.

- skin_makePlayer.xml

Default skin for "myWimpy.php"

- skin_makePlayer_bkgd.jpg

Default skin's background graphic

- wimpy.sql.common.php

Settings that are common to both admin and public users.

- wimpy.sql.configs.php

Configs file

- wimpy.sql.coverart.php

Cover art handler functions

- wimpy.sql.directory.php

Directory reading functions

- wimpy.sql.filer.php

File processing functions

- wimpy.sql.install.php

Installation functions.

- wimpy.sql.php

Used as the "public" Wimpy (specify this file for "Wimpy Script" when using the Customizer tool)

- wimpy.sql.skin.xml

The skin used for the Wimpy Player that is loaded into wimpy.sql.swf.

- wimpy.sql.sql.swf

The primary Wimpy SQL controller.

- wimpy.sql.users.php

User functions

- wimpy.swf

Wimpy MP3 Player is loaded into wimpy.sql.swf so you can play tracks. (The demo or standard version will work)


4.  Pull up the Wimpy SQL home page (index.php)..







Quick Start Guide

Login in as an "Admin"

  1. Click the "login" button and enter the same Admin username and password you set for $user and $pwd for your MySQL database.

    NOTE: The password is hashed using md5 in transit from Flash to PHP.

  2. The login button should now have a green outline and should now be labeled "Admin." Click this button again to access the admin panel within Wimpy SQL.
  3. Since this is the first time accessing Wimpy SQL, the MySQL database has not been configured. Wimpy SQL will run through a series of checks to ensure that all the MySQL settings defined in wimpy.sql.configs.php are set up properly.
  4. Once the checks are validated, you should see "No Tables Found" and a big button that says "INSTALL" -- click the "INSTALL" button.

Adding items to the database.

  1. Log in as an Admin.
  2. Once you see "Installation OK" in green letters, you will notice a new button labeled "Import Files." Click this button to import files.
  3. Navigate to the directory that contains your mp3 files using the [+] directory name, the [ ../ Back ] button or the "Drive" drop down.
  4. Once you've opened the directory that contains your mp3 files, click the "Process Current View" button. All of the files and sub directories will get loaded into the "Files to process" window. Wimpy SQL should start processing the items loaded in the "Files to process" window, if it appears that the items are not being processed, click the rectangular "play" button next to the Files to Process window to start processing the files and folders. Wimpy SQL will recursively scan through all the directories that are loaded in the "Files to Process" window -- looking for mp3 files.
  5. If only one directory is displayed in the current view, you may need to open that directory.
  6. When using Wimpy SQL for the first time, it is best to only process a couple files or a single directory. Processing times vary depending on network speed and server performance. If you elected to use the "Amazon Cover Art" option, processing time will likely double.
  7. Once all of the files and folders have been processed, close the admin panel (click the little "x" in the upper right-hand corner of the panel).


Seeing the newly added items.

  1. The "Artists" accordion menu should be open in the main Wimpy SQL interface. If not, click on the "Artist" bar to the left.
  2. Click on the item labeled "[ ALL ]." This will load the "startup" listings.
  3. By default, each time Wimpy SQL is started up the following occurs:
    • 50 random tracks are loaded into the main playlist.
    • 15 random albums are loaded into the scrolling album view.
    • All genres will load up in the "Genres" accordion list.
    • All artists will load up in the "Artists" accordion list.
    • All playlists created by administrators will load up in the "Playlist" accordion list.

    These lists are derived based on the ID3 contents of your MP3 files.


Playlist Tools

  1. Log in as either an Admin or a regular user
  2. Click the "Playlist Tools" button.
  3. Once the playlist tools menu is open, click "New" and enter a name for the playlist.
  4. Drag and drop a cover image from the cover area on top of the new playlist name in the list. Or click on a couple items in the main playlist view and drag them on top of the new playlist name. (you can ctrl click to select a couple items or shift-click to select a range of items).
  5. When dragging items onto a playlist item, Wimpy SQL will highlight the item with a solid green line to indicate which playlist the album or items will go into.
  6. After releasing items "into" a playlist, you can see the new contents of the playlist by clicking the playlist name.
  7. If you have a playlist already open, and you drag an item from the album area to the main playlist view(the big playlist that shows all the songs) the main playlist view will automatically update, and the new tracks will be added to the bottom of the main playlist view.
  8. Next Click the Playlist tools button again and select "Make Player"

    - Wimpy SQL will pop open a new window that contains a standard Wimpy MP3 Player that is running off of the newly created playlist.

    HINT: After doing a "Make Playlist" use your browser to "save as" the HTML page. You can use the resulting HTML page anywhere on your site.


User Administration

  1. Log in as Admin
  2. Click the [ Admin ] button.
  3. In the Admin panel, click the [ Manage Users ] button. The "Edit User" dialog will open.
  4. Enter the information into the dialog. The minimum information needed is a User Name and Password.

    - Click the [ Update / Add User ] button.
    - The new user shows up in the list and is now ready to use.

    "Super Users" gives the user Admin privileges.

    "Listener Only" gives users the ability to access the Playlist Tools menu to create and modify their own playlists.




Running a customized Wimpy MP3 Player off of the MySQL database

The example "myWimpy.php" file is provided as a simple example, and must be located in the same folder as wimpy.sql.php in order to work. By using the Customizer Tool at wimpyplayer.com, you will be able to create a "myWimpy.php" file that you can put in different locations around your site. Plus you can set your own skin, and adjust other options as desired.

When using the Customizer Tool, use the following settings:

For: Wimpy Script
Set this to the URL to "wimpy.sql.php"

For: Using MySQL database
Click the checkbox for this option so that Wimpy knows to handle requests in the proper way.

For Prevent Local Caching
  - If your database lists file locations as system paths: - Checked.
  - If your database lists files as public URLs you can leave this un-checked.

Do not use:

Embedded playlist
Encrypt HTML
Force XML playlist (forceXMLplaylist)
Play Icecast stream (icecast)
Startup folder (startDir)

The remainder of the options can be set at your discretion.

Upload the resulting "myWimpy.php" to your server and enter a query as:




Making a custom query through a customized Wimpy MP3 Player

To query a playlist, we send a "query string" into myWimpy:php. A query string includes a ? followed by any number of "value pairs." Each value pair is seperated by a & symbol. When making a query with Wimpy only two value pairs are needed. The first value pair is queryWhere, the second value pair is queryValue.

FYI: The reason we call each one a "pair" is because each word (variable) has an associated value. In other words, queryWhere will have a unique value, so the varialbe queryWhere and it's associated value constitute a "pair."


This is the column name (or kind of data) that you would like to search ON .



You can use any one of the following column names (or kinds of data) to search on:

  • filepath
  • artist
  • album
  • title
  • track
  • comments
  • genre
  • seconds
  • filesize
  • bitrate
  • visual
  • myid
  • filetype
  • basename
  • add_date
  • year
  • votes
  • plays
  • rating
  • time
  • price
  • alt1
  • alt2
  • alt3



This is the value that you would like to search FOR .All the rows that contain the value defined for queryValue will be returned as a playlist to Wimpy using the SIFT playlist format.



To complete the "query string," we put the two value pairs together by seperating them with an ampersand (&).



What you see above is a complete "query string." We can send the query string into myWimpy.php by simply adding it to the end of myWimpy.php. The ? symbol is used to deliniate between the file name and the query string. If the ? is not included, the browser will not know how to differentiate between the the "query string" and the URL to the file. The end result is that without the ? youre browser will issue an error.

Here is what the final URL, including a "query string" looks like:



Entering a URL like the xample above will cause Wimpy to load one file. The file that has the "myid" value of "28."



Requesting multiple values

To request multiple values, seperate each value with a "pipe" character.



Here are a couple more query string examples:

Example 1
To request a single item based on the "myid" column:


Example 2
To request multiple items based on the "myid" column


Example 3
To request all rows that have "Mike Gieson" in the artist column:


Example 4
To request an item based on the value defined in the "basename" column:


You may have noticed that in example 3 queryValue the "space" character was replaced with %20 -- this is the "URL encoded" equivelant of a space character, and it's probably a good idea to URL encode your queryValue, since often times there are apostrophes and weirdo characters in artist names / album names (and other values). Weirdo characters could potentially choke either PHP, MySQL or Flash, so by URL encoding the request, errors will be minimized.

You may also have noticed that lower case letters were used for queryValue. MySQL is case insensative when it fetches rows, so you do not have to worry about using the proper uppercase / lowercase combination.

When making a query, be aware that in order for a result to be returned, the value must match the entire value. In other words, lets say row 3 has "Mike Gieson" in the artist field. If you sent in a query as queryValue=mike, then nothing would be returned. The only way to return row 3 based on the artist field is to match the exact value of that particular field. As mentioned earlier, the match does not have to be case sensative, but all of the characters must match.






If the playlist does not populate, double check to make sure that you have not manually edited the HTML / PHP code that the Customizer tool ouput. Use the Customizer tool again to make any modifications to the file.

Access wimpy.sql.php directly with your web browser to see if you get any errors.



Oftern times there is a username and password mis-configuration in the wimpy.sql.configs.php file. accessing wimpy.sql.php directly will display errors if there is an issue with the config settings, or any issue connecting to the database.

Double check your configs.

Check to make sure that the "public user" defined in wimpy.sql.php has enough priveledges to access the database you've defined in the configs.

Try accessing wimpy.sql.php with a query string.



If the result looks like:


It could be that you are not using a proper queryWhere or a proper queryValue. Doulbe check that your using the proper information.

If your getting something similar to:

&item0=28|http%3A%2F%2Fmercury%2Fwimpy_build%2Ftest%2Fwimpy_mp3 ...

This is good,, double check myWimpy.php for any modifications you may have done. (Or you may want to use the Customizer tool again). You can refer to the "myWimpy.php" file that came in the MySQL connection script package -- upload it to the same folder as wimpy.swf and give it another whirl.

When using the Customizer tool:

Be sure that you are setting "Wimpy Script" to wimpy.sql.php

Double check that none of the following options are used:

Do not use:

Embedded playlist
Encrypt HTML
Force XML playlist (forceXMLplaylist)
Play Icecast stream (icecast)
Startup folder (startDir)

If you're using a wimpyConfigs.xml file.

Try removing the wimpyConfigs.xml file and just get things running through standard HTML. Once things are working with standard HTML, you can go back and work out how to set up the wimpyConfigs.xml later.

Browser caching is a big problem.

Often times you get things set up wrong at first, then make some adjustments and nothing changes and things still don't work. So you try to make other changes and nothing is working. In reality the problem was corrected when you made the first change, but your browser did not retrieve the latest update to the page you modified because the page was cached locally. This can drive you bonkers. Always, always, always empty the browser cache after making a change.

Sometimes i will put a number or word on the page that i am editing, and after each change, i change the number or word, so that when i refresh the page, I can see if the number or word has changed, if the unmber or word hasn't changed, I know that the browser is still using the file in the cache and not the new file.

I recommend using FireFox during development, there are tons of great "plugins" that **really** empty the cache and ensure that you have the latest HTML. Plus the default "clear cache" works just great (unlike Safari or Internet Explorer).




© 2006 Plaino. www.wimpyplayer.com