§

Plastic Tunes - Read Me file

When words leave off, music begins.  ~Heinrich Heine

§

About the plugin

Plastic Tunes is a "now-playing" plugin for wordpress that allows your blog to collect and display informations about the music you play in your media player. Artists, titles, albums and pretty much any information included in your digital music files. All goes into your database for real-time or later use, ready to be displayed on your sidebar, on a dedicated page or wherever you want. The concept of this plugin, and quite a few lines of code were originally taken from version 0.1 of the muTunes plugin, made by Ken Smith -- although Plastic Tunes grew a lot since then.

 

The changelog

• v. 1.4 Compatible with Wordpress 2.5, and minor fixes and redesign.
• v. 1.3 Plastic Tunes can now be used with the Now Playing plugin for Winamp. For compatibility reasons, AMIP users who update must slightly modify their insert settings. More details below. This version also fixes few potential bugs.
• v. 1.2 Minor fix due to a bug of the widget functionality, where the widget form would not report the values correctly. Now fixed.
• v. 1.1 A management page has been included in the admin area. This is still in a early stage, but allows you to browse all the music items you added so far, delete single records and purge the entire list of music items. Also added an option to skip duplicates when listing all the entries in your list page (this does not apply to the just mentioned management page in the admin area). For duplicates it is meant the same music piece played more than one time and appearing in more locations within the list. With this option on, songs that occur more than once will be inserted in the database just as well, but will not appear in the list as called by <?php plastic_table($user_id);?>. Of the duplicates, only the most recent item will be considered.
• v. 1.0b Just a mistake in the title of the plugin on the WP plugins page, where it said '(next)Plastic Tunes'. Sorry about it, it was a testing leftover. Now it correctly says 'Plastic Tunes'.
• v. 1.0 For sake of logic, efficiency and security, I made few changes in the way the plugin understands what goes on with the player. The callbacks events are slightly different now. You'll have to take care of these changes in your AMIP configurator (see 'How to install the Media Player plugin' section below). This is important since previously in the instructions I had also forgot to indicate the 'duration' variable that is crucial for certain functions of the plugin.
  On a technical side, there's now a new option in the options table of your wordpress DB, called plastic_tunes_player_state, and a obsolete one, that won't be used anymore, plastic_tunes_togglesidebar (note that a plugin like CleanOptions can help you in removing obsolete entries from your wordpress options).
  Reflecting these changes, there are now in the code new comments and explanations, and also a very useful example on how it is possible to customize the title of the sidebar element according to the state of the player. Look for it in the 'Edit the title of your sidebar code here' in the file 'plastic_functions.php' (more in the "further customizations" section below).
• v. 0.99 Corrected the relationship between the sidebar option and the widget. Now when the widget options has no title, it is not only assumed that the title is taken care of in the option page: also the default 'before' and 'after' tags of the widget are not displayed, and are thus expected to be taken care of in the option page too. They should be considered for in the 'title' and 'closing elements' fields. This is done to avoid redundancy of tags such as <h2> or <li> and allow for more customization. The less expert user is not affected by this as long as a title is entered in the widgted options.
• v. 0.98 Plastic Tunes is now widget compatible. For those who run Wordpress 2.2.x or the Widgets plugin with compatible themes, it means it's a lot easier now to show off your listening preferences on the sidebar. Read below for more detailed informations, "how to install" section.
• v. 0.97 Two apostrophes slipped in a SQL query. It broke the insert of the data. Sorry for being such a messy programmer. Hopefully is now all OK.
• v. 0.96 Corrected the time span calculation, now it works properly. Also added a checkbox I forgot in the option page. Never to sing the victory, they say in my falling country.
• v. 0.95 Flood protection is now working. Also I realized that the "Play & Change" callback from the media player wasn't properly working (it caused duplicate entries after stopping and restarting the player). The event to use is now "Change" only. Also I changed the "year" field to accept more than 4 chars, in case of entries like "1998-2003" and smilar. This version is quite a good one, I think (or better, I hope).
• v. 0.94 temporarily removed flood protection. I don't seem to be able to make it work properly. Also I forgot to make the variable %duration% available in the option panel, and the example of customized code for the sidebar was wrong. Both corrected.
• v. 0.93 fixed the flood control function and few other bugs.
• v. 0.90 first public release. I worked a lot before to release this beta, so I just invented a version number I thought proper. Possibly this one is a little optimistic, but hey, it's too late to change it. I never understood the general logic of application numbering anyway.

The features

• Multi-User Capable
• Saves to your Wordpress DB all informations from the music you listen to
• Works with iTunes, Winamp, Foobar2000, QCD, and others.
• Flood Protection
• Password Protection
• Formatting easiness & flexibility
• Widgets compatibility
• The possibility to toggle the state of the sidebar elements according to the state of the media player
• Automatic Google links for Artists and Albums if you need them
• ... and much more

For the future: I'll try to implement a working managing page in the admin area to delete or edit the music entires. There was one but it only showed the list, I never went past that so I temporarily disabled it. If I find a satisfying way to do it, I might put the Amazon functionality mutunes had. I Also I have many ideas on how to further amplify the flexibility of the formatting options, and possibly on how to let the media player talk to the plugin better. Let's hope I don't get bored before to put my hands on it. Please visit this page to make suggestions and comments.

A note on migration

To migrate from muTunes to PlasticTunes keeping the table with all the music entries is not obvious. PlasticTunes uses a different table with slightly different fields, so importing the muTunes table as it is results in a error. Obviously there is a way, probably easy, to import only certain fields via SQL but I am too tired and ignorant to know how right now. Suggestions and help on this are welcome.

 

How to install the wordpress plugin

1. FTP the "plastic_tunes" folder to your "wp-content/plugins" directory.
2. Activate the plugin
3. Customize the options page
4. Load the widget: if your installation is compatible, you can use the widget function to load the infos on the sidebar. Just remember: after you drag and drop the plastic tunes item onto the sidebar (you can do that in the widget page in your admin area), and before you save the changes customize its options by adding a user_id number. Without it the widget won't work and most likely will cause a ugly error. The title of the widget instead is optional, and if entered will override the sidebar title as (and if) indicated on the plastic tunes option page. Be aware that leaving the widget title empty also overrides the tags before and after the widget element, such as <h2> or <li>. In that scenario you are in fact expected to provide them with the 'title' and the 'closing element' fields on the plastic tune option page.
5. If you can't or won't use the widget function, add the following piece of code to your sidebar: <?php plastic_sidebar($user_id); ?>, where $user_id is the number reported in the list in the options page.
6. Add the following piece of code to the template you will use for the entire list of music items: <?php plastic_table($user_id); ?> (see instruction on how to use templates on the Wordpress codex website.)
7. In case you want to further customize the appearance of sidebar and dedicated page elements, read the 'further customizations' section below.

How to install the Media Player plugin

iTunes - AMIP plugin

1. Close iTunes
2. Download and install the latest version of AMIP for iTtunes.
3. Download and install the AMIP Configurator.
4. Download and install the latest version of CURL.
5. Run the AMIP Configurator, entering the following in "Callbacks/Web"
   (customize the parts in bold red and put all the variables on the same line):
   
   NOTE: since version 1.3 the AMIP Callbacks/Web events are once again slightly different.
   Please don't forget to update them in your AMIP configurator.
   
   Change event :

   /exec:(PATH TO curl.exe) -d "uid=USER_ID" -d "pw=PASSWORD_HASH_FROM_SETUP" 
   -d "state=1" -d "artist=&func_ue(%1)" -d "title=&func_ue(%2)" -d "track=%3" -d "album=&func_ue(%4)" 
   -d "year=%5" -d "genre=&func_ue(%7)" -d "duration=%LEN" -d "rating=&func_ue(%itrt)" 
   http://**YOUR_WEBSITE_URL**/wp-content/plugins/plastic_tunes/amip.php

   Play event:

   /exec:(PATH TO curl.exe) -d "uid=USER_ID" -d "pw=PASSWORD_HASH_FROM_SETUP" -d "state=1" 
   http://**YOUR_WEBSITE_URL**/wp-content/plugins/plastic_tunes/amip.php

   Pause, Stop, Exit events:

   /exec:(PATH TO curl.exe) -d "uid=USER_ID" -d "pw=PASSWORD_HASH_FROM_SETUP" -d "state=0" 
   http://**YOUR_WEBSITE_URL**/wp-content/plugins/plastic_tunes/amip.php

WinAmp - AMIP plugin

Use the instructions above for iTunes, but download AMIP for WinAmp.

WinAmp - NowPlaying plugin

Note: The "Now Playing" plugin offers few advantages: it doesn't need other applications in order to work, like curl for AMIP, and it is easier to configure. Theoretically it can also insert more songs at a time into the database instead than one at a time, although this feature has not really been tested with Plastic Tunes yet.
On the downside, Now Playing does not notifies when a song is replayed after being stopped, which causes Plastic Tunes to incorrectly report the player as not playing when it is playing the same song. It is a minor problem, but there are no workarounds so far (v. 1.3).

1. Close Winamp
2. Download and Install the Now Playing plugin
3. Run Winamp and right-click on the Now Playing icon in the taskbar
4. Open the configuration window
5. Where it says "Connections" click "New" and "HTTP Post"
6. Enter the following details:
   
   
   • Url = http://**YOUR_WEBSITE_URL**/wp-content/plugins/plastic_tunes/nowplaying.php
   • Extra Data = uid=USER_ID&pw=PASSWORD_HASH_FROM_SETUP
   • Song history = 1
   • Update Frequency = 1
   • Accepted file types = Audio only
     
     
7. Where it says "Options" enable the plugin and you're set.
   

A note on the OS

Does this means that the whole thing works only with windows? Well, I don't know. There should be, there possibly is, a plugin for a OS X or Linux media player which does the same things as AMIP, or similar enough things to be compatible with a little tweaking on my part. In case you know of its existence, please let me know.

Further customizations

Sidebar

In generating the music items for the sidebar, it may become necessary to display conditionally certain elements around given variables. Say for example that values like "album" or "year" return empty: what happens with characters like a comma, or two brackets, or with entire words, like "from", or "by" that you placed before or after such variables in the option page? They would look rather silly next to a void of values.
At this stage unfortunately the only way out of this problem is to know how to use PHP a little, and to go edit directly the plugin page.
To do so, you must:

• Leave the "Format string:" field empty on the option page
• Edit the plastic_functions.php file in the plugin folder and insert your code where it says "Edit your sidebar code here" and "Edit the title of the sidebar here". A example is provided in that area to get you started.

Please note that whatever you change with the title, you must remember to update the "closing element" field on the option page.
Note: the above works also with the widget. Only remember to leave the 'title' field in the widget options empty too.

 

Index Page

The index page is not as easily customizable as the sidebar, but you do have choices in the option page. You can decide what fields should appear in the table, and whether or not to display redundancies of music items played more than once. Other than this, you can change the CSS file (this is explained on the option page too) to change the apperance of the table. To make more significant customizations, you'll have to manipulate the code in the "plastic_functions.php" file. The function you look for is called "plastic_table".

As above said, to call the table of all the music items from a template you use the tag <?php plastic_table($user_id); ?>, where $user_id is the id number of the user as indicated on the option page..
There are other ways to tell the index page whose user's music should be retrieved:

• You can leave the $user_id empty. You must do it like this <?php plastic_table(''); ?> or like this <?php plastic_table($user_id); ?> (without substituting "$user_id" with a real value) but not like this <?php plastic_table(); ?> (returns a error). Once you have a page with a NULL user, you can:
• Simply call the page, in which case a list of available users who submitted music pieces will show up;
• Or attach the variable to the URI, like this for example: "http://www.mywebsite.com/my_index_page?user_id=3". As you can see, the ways for automation and customization are many.

 

Final considerations

No final considerations. Just let it be said that I worked on this plugin to forget at least for a while about a entangled bunch of rotting feelings and personal things that really messed around my life lately. I can't write on my blog and I can't cope just about anything, so I code and forget. It keeps me busy and focused. Forgetting is rarely a good strategy to overcome problems, but in a blind alley and being too unhappy to find a way out it is a good strategy. Coding helps me, like doing crosswords puzzle helps someone else. yet it works only in moments of significant tragedy or despair, and only by chance and inspiration, which explains why I update my plugins so rarely, or never. I guess life isn't so bad as they say. Peace.

 

§

“it’s all in a day’s work” for corpodibacco.

§