AudioScrobbler Winamp Plug-in Readme

Welcome to the AudioScrobbler Winamp Plug-in!

For up-to-date information go to www.audioscrobbler.com

Contents

1. What Can it Do
2. What Do I Need
3. Installation
4. Uninstallation
5. How To Use It
6. Config
7. Bugs?
8. Credits
9. Version History

What Can it Do?

The AudioScrobbler Winamp Plug-in enables you to participate in the AudioScrobbler Project, a web site endeavouring to become your personal music advisor.

While you are playing your songs in Winamp, AudioScrobbler monitors in the background. When you have played a song for a certain amount of time, AudioScrobbler will send details of the song to the AudioScrobbler server where it is added to your total. After a couple of days, AudioScrobbler will begin to match you with other users that have a similar taste in music to you.

What Do I Need?

You need Winamp version 5.x (not Winamp3) and an Internet connection. Since the amount of data sent to the AudioScrobbler server is very small, a humble modem is more than enough. Even if you only have intermittent internet access, AudioScrobbler will keep a local cache of your played songs while your are offline. When you next connect to the internet, it will send the song cache so you never miss a song. Winamp will run on any computer with Windows 95, 98, NT, 2000 or XP.

Installation

1. Double click on the file AudioScrobbler plugin installer (if you do not have it download it) and follow the instructions on the screen..
2. Select in which directory to install the AudioScrobbler Winamp Plug-in. You should install it in the Winamp\Plugins directory; the installer defaults this directory to C:\Program Files\Winamp\Plugins automatically, so you should only have to change this if you installed Winamp somewhere else. Click on Next >.
3. Select plugin version - If you have Winamp 5 and you have the Media Library installed and enabled you should choose the Media Library version of the plugin. This version is the most likely to read your audio file tags correctly. If you don't have Media Library installed you should choose the General plugin version although it is unlikely to work with specialised file types such as APE/FLAC/MPC. When you have selected which version, click on Next >.
4. Now you are ready to use the AudioScrobbler Winamp Plug-in. Read about how to use it below. 

Uninstallation

To remove the AudioScrobbler Winamp Plug-in go to the directory where you installed the it - normally C:\Program Files\Winamp\Plugins\ and delete the ml_audioscrobbler.dll/gen_audioscrobbler.dll and audioscrobbler.99.cache files. If you do not know where the Winamp directory is search for ml_audioscrobbler.dll or winamp.exe.

How to Use it

The first time you run Winamp after AudioScrobbler has been installed, you will be presented with the AudioScrobbler config dialog. When you have entered your username and password and ensured the plugin is enabled (see below), AudioScrobbler will begin to monitor Winamp for playing songs.

When a new song is played, AudioScrobbler knows about it. When a song has played for 50% of the track time, AudioScrobbler will try and send details of that song to the AudioScrobbler server to be added to your total. If the server is not available, either because your internet connection is down or because the server is down, AudioScrobbler will save the song information in a local cache file. AudioScrobbler will continue to save song information into this cache file until the server becomes available again, at which point it will send the entire contents of the cache file (i.e. all the songs which haven't been sent so far) to the server. If this is successful it will send to the server direct from then on.

AudioScrobbler will continue doing this in the background. In fact once AudioScrobbler has been installed and configured you can pretty much forget about it except for checking the website regularly for your current statistics.

AudioScrobbler Config

The AudioScrobbler Config dialog is the nerve centre of the plugin. All the configuration for the plugin is done here and it is split into several different areas.

Note: To get to the config dialog after the plugin has been installed, press CTRL+P in Winamp to bring up the Winamp config dialog. Select General from the Plugins list on the left and the double-click on the AudioScrobbler entry.

Scrobbler Authentication
Here you need to enter your AudioScrobbler username and password which you created when you signed up. If you haven't signed up for an AudioScrobbler account you need to do so here. If you have forgotten your username or password, you can retrieve them here.

Preferences
These values are basically user defined preferences to control how AudioScrobbler works.

• Enable Plugin - This enables/disables the plugin. If the plugin is disabled no songs will be submitted or cached.
• Show Upgrade Message - When enabled, this will show a message when you start Winamp if your plugin is out of date.
• Force Connection - The plugin attempts to automatically detect if you have a connection to the internet configured - it usually does a pretty good job of this by itself. By setting this tick box on, this tells the plugin to try to connect even if it thinks there is no connection available. Please note that if you are using a dial-up connection and you set this to be on, the plugin will cause the modem to dial-up if you are not already connected.
• Include/Exclude Dirs - Clicking on this button brings up the Include/Exclude dirs dialog. Using this dialog you can define a list of directories which the plugin will include or exclude from submission. For example, if you choose C:\Music as your directory and choose Include, only files whose filename starts C:\Music will be submitted. If you choose C:\Music and C:\OtherMusic as your directories and choose Exclude, all music will be submitted EXCEPT files which begin C:\Music or C:\OtherMusic. You can define as many directories as you like.

Use Proxy Server
Here you can enter details of a proxy server if you use one. However, AudioScrobbler will try and use your Internet Explorer connection settings by default so if you already have IE set to use a proxy, you needn't enable this.

Use Proxy Authentication
If you use a proxy server which requires authentication then you will almost certainly need to use this option. If you already have Internet Explorer set up to use a proxy, you will need to check this box and fill in your username and password. Please note that it is quite alright to enable this option without enabling Use Proxy Server assuming Internet Explorer is set to use a proxy.

Submission Stats

• Cached Files - This is a read only value which describes the number of songs which are currently in the local cache waiting to be sent and the total cache size. If this value is quite large ( > 20 ), it may be symptom that your internet connection or the AudioScrobbler server is having problems. This field will also show the status of the sending of the cache file when appropriate.
• Playback State - Winamp's current playback state as detected by AudioScrobbler. If the state is 'Playing', this will also show how long until the song is submitted or whether it has been submitted already.
• Submit Interval - The interval is a value sent from the AudioScrobbler server to the plugin to prevent the server being overloaded. It is the time in seconds since the last submission was sent that the plugin should wait before sending a new one. High values here (400 or more) would indicate that the AudioScrobbler server is currently quite busy.
  
• Conn. Status - This is whether or not the plugin is currently connected to the server. This is mostly for diagnostics, and it should normally say 'Connected'. If it says 'Wating for handshake' or 'Handshake in progress' for any longer than a minute or two the server is probably down. Please note that the plugin only tries to reconnect to the server periodically and the longer the connection is down, the longer the interval between connection attempts. The plugin checks at 1, 2, 4, 8, 16 minutes etc up to a maximum of every two hours. While the connection down, your submissions will be cached locally.
  
• Last Response - The last response received by the plugin from the AudioScrobbler server. Usually this value should be 'OK' - if it is anything else (such as 'FAILED') it means that the plugin encountered an error on the last submission. Check the log file for more details if logging is enabled. A status of 'Not Connected' indicates the plugin could not connect to the internet, while a state of 'Waiting For Handshake' indicates the plugin is attempting the create an initial connection to the server. If the 'Wait For Handshake' message is shown for more than a few minutes there is probably something wrong.
• Last Message - Any further message from the AudioScrobbler Server.

Last Submitted Tracks
As the name suggests, this is a list of the last 5 tracks which AudioScrobbler has sent to the server since Winamp was started. The list always shows the most recent submission as 1. with the older submissions following in order after that. Please note that this list only shows files which have been played in this session. Files in the cache from previous playback sessions will not show here.

Bugs?

AudioScrobbler is constantly being refined and a few bugs may hide somewhere despite our vigorous testing... 

If you find any bugs, or have brilliant ideas and suggestions go to the audioscrobbler forums at http://www.audioscrobbler.com/forums/.

Credits

The AudioScrobbler Winamp Plug-in was developed by James Spibey (spib).

You can check for updated versions here.

Version History

1.1.10-beta [17/08/05]

• Laurie (lozzd) - fix re-handshake code which re-handshaked to wrong URL (didn't meet protocol specs)

1.1.9 Beta 3

• Bug - Plugin wouldn't load settings on Windows 95
• Bug - Player pauses for 5 seconds when cannot determine track length
• Bug - Handshaking in 945098734s.
• Bug - -1 Song lengths under some circumstances
• Change - Add support for Global Hotkeys for enable/disable and show config
• Change - Can include/exclude directories individually now (+ bugfixes)
• Change - Clearer handshake status messages
• Change - If the current song length cannot be determined (because Player won't tell me), the song is submitted after the default of 240s. If the song is less than 240s long, the submission won't take place. Best I can do under the circumstances I'm afraid.
• Change - On HTTP Error drop connection and force a fresh handshake

1.1.8 [21/10/2004]

• Don't submit new songs until the cache has been cleared
• Sends cache chunks less often (every 30 secs) to prevent server rejecting it
• Cache is now limited to 1000 tracks
• Fix for cache not sending until Winamp restarted.
• Can operate as either a general or Media Library plugin. The Media Library version is much more reliable but it requires Winamp 5
• Can disable Upgrade message if required
• Better error messages in Config dialog when tracks are invalid
• Improved proxy handling
• Better handling of errors during server downtime
• New Installer
• Tidied Config Dialog, removed logging option, added clear password button
• If using Proxy Authentication, 'Proxy-Connection: Keep-Alive' added to connection

1.1.7 [25/04/2004]

• Unsupported file type errors should be fixed
• Only files which are TAGGED get submitted as specified in the protocol (guessing from filenames is not done)
• Errors display only into config dialog and log - no more messageboxes
• Cache submissions are logged to file
• Server errors causing new handshake are logged to file
• Minimum submit time is now 50% or 240s rather than 120s
• Make sure last submission is properley deleted from memory
• Fixed CD Submissions
• Added ability to exclude or include files in certain directory paths
• Password can be cleared using the config dialog
• Allow users to force the plugin to try to connect even if no internet connection is detected.

1.1.6 [05/03/2004]

• Always ignore HTTP streams
• Better detection of Artist & Album info

1.1.5 [23/01/2004]

• Fix for info fields not cleared between submissions

1.1.4 [03/01/2004]

• Support for v1.1 Protocol
• Fix UTF-8 encoding (thanks Case!)
• Ignore HTTP Streams on by default
• Send Cache in small pieces (10 submissions max by default)
• Server responses logged to file by default

1.1.3 [17/07/2003]

• Maximum time before submit is now 120 seconds.
• Fix for folks with system time set before Jan 2003.
• If modem is installed but not used, plugin will try other connections methods rather than reporting no connections available.
• Fixed crashbug when storing cache file.

1.1.2 [29/06/2003]

• Tightening of caching code.

1.1.1 [08/06/2003]

• Bugfix for crash caused by some HTTP streams

1.1.0 [23/05/2003]

• Added Proxy / Proxy Authentication Support
• Added option to ignore HTTP streams
• Config Dialog is modeless now so you can keep it open all the time
• More useless info added to config dialog
• Fixed crashbug under some OS (thanks wertherman)
• Enabling/Disabling plugin doesn't block submissions now
• Fix for bug 732818 (Track titles are cut on some tracks)
• Fix for bug 734180 (Cached files not shown in the Last 5 Submitted)
• Should fix problems with config dialog not showing
• Properly identifies unsupported files now
• Removed ID3 option in config dialog
• Log file max size works now
• Fix for bug 735171 (Doesn't cache failed submission)
• UTF-8 Bug fixes
• Fix for bug 735635 (Wrong info submitted if playlist changes)
• Loads of work done detecting internet connection state for dial-up users

1.0.4 [02/05/2003]

• Fixes to better cope with server outages
• Error messages are more useful, but a bit annoying so added Config option to disable error messages

1.0.3 [30/04/2003]

• Will work if the internet isn't connected when winamp first starts
• Fix for bug 730342 (Plugin doesn't submit CD tracks)
• Fix for bug 729650 (Caches forever after a FAILED response)
• Config dialog updates stats in real time

1.0.2 [19/04/2003]

• Changed "Use ID3 Tags" to "Force use of ID3v1 tags"

1.0.1 [18/04/2003]

• List of last 5 submitted songs on config dialog - Songs are now submitted after 50% or 180 seconds, whichever comes first - Send cache even when not playing
• Various data logging improvements
• UTF8 encode the track data before it is sent
• Config dialog displayed on new installation
• Option to use ID3 tags for track data

1.0.0 [14/04/2003]

• Control Centre integrated into plugin
• Auto-update feature removed (excess bloat)
• UTF8 encode the track data before it is sent
• Config dialog displayed on new installation
• Option to use ID3 tags for track data
• Changed logging to default to DEBUG_FLOW
• Added hidden registry option to change log level
• Added option to write debug as XML (mostly for my own amusement)
• Removed PrivateHTTPStreams option from config dialog seeing as we
• don't send the path info anymore

0.9.9 [10/04/03]

• Final change before 1.0
• Stopped plugin from submitting names of videos, avoiding various "adult" titles appearing on the site. (wa2.9 does videos)
  

0.9.3 [11/02/03]

• Decided not to store filename or media type, to avoid possible incriminating data regarding peoples music collections
  

0.9.2 [10/02/03]

• 0.9.0 and 0.9.1 never submitted filename, this one does
  

0.9.0 [10/02/03]

• Added option to keep HTTP streams private
• Reduced time-to-submission to 50% of song length
• Additional error handling

0.8.5 [02/01/03]

• Communicates directly with new servers
• Removed unnecessary encryption. (Password still secure)

0.8.1 [05/12/02]

• All HTTP communications are now threaded
• Plugin now writes significant events to logfile
• Option to specify maximum size of logfile
• Option to disable the plugin
• Fixed and tested the offline caching, it should work now!

0.7.1 [02/12/02]

• Wrote my own XOR encrypt/decrypt function in C++ and PHP.
• ALL client-server communication now encrypted
• Plugin will not submit if winamp instances>1 (using semaphores)
• Offline caching is now encrypted
• Server side fix for duplicate/hasty submissions
• Remove read-only flag on cache file before deletion attempt

0.6.5 [26/11/02]

• Hasty fix to 0.6 that caused double submission of all songs
• Rewritten offline caching. Songs played offline are now updated when you connect

0.6.0 [25/11/02]

• Control Centre now handles updates properly
• Password security - MD5 digests are used vs. cleartext

0.5.0 [23/11/02] (unreleased)

• completely new architecture
• stability should be acceptable - i learnt about memory management
• Control Centre now handles client updates
• offline caching removed as it was buggy

0.4.0 [20/11/02] (unreleased)

• minor changes to try and fix stability

0.3.0 [19/11/02] (unreleased)

• resolved failed submissions where & or # appeared in path
• fixed some random bugs and glitches
• updated installer to warn to close winamp
• installer creates start-menu shortcut to readme

0.2.5 [17/11/02]

• comes with an installer (nulsoft)
• you must listen to half the song before submission
• stability is getting better

0.2.0 [16/11/02]

• doesn't crash if you are offline :)
• caches offline submissions for later in plain text file
• fixed bug regarding ' in song name
• plugin reports date and time of client instead of using server time
• plugin reports soundex hash for artist/song
• code cleaned up

0.1.0 [07/11/02]

• server time is used to timestamp submissions
• only works if you are online
• submits playlist text to server
• initial release, testing with me and paul
• no installer, need some MFC DLLs installed to use