Spectrum Visualizations and Media Info for Samurize
===================================================

made by Tropics (samurize@only-tropics.de)
idea by torsius


General Notes
-------------
To use this plugin, you also need one of the  following
Audio/Media Players installed:
- WinAmp 2, 3 or 5
- Quintessential Player (QCD) 4.11+
- FooBar2000 0.9
- Windows Media Player 9
- iTunes 4
Make sure the refresh rate and the number of spectrum bands
you use in your Samurize config file are the same as in
the Media Player plugin you use. Anything else would only
degrade performance.
This plugin pack is part of the Samurize Distribution,
so get updates via http://www.samurize.com.


Samurize
--------
The plugin files are SpectrumVis.dll and 
AdvancedMediaPlayerInfo.dll and they should already be in your 
Samurize/plugins directory. The AdvancedMediaPlayerInfo plugin
works only with QCD, FooBar2000, Windows Media Player,
WinAmp 5 and iTunes. The Spectrum plugin works with QCD, 
FooBar2000, iTunes and WinAmp 2/3/5.
Two config files are included for reference, spectrum_vis.ini 
and advmediainfo.ini. The first one is a 18-band spectrum 
analyser, the second one displays advanced track info.


WinAmp 2/5
----------
The spectrum plugin file is WinAmpSamurize.dll. It is installed by
the Samurize installer in your Winamp/plugins directory.
If it is not there, rerun the installer and make sure the
plugin is installed.
To run the plugin, start the plugin selection dialog by
pressing CTRL-K and select it in the list. Start the
plugin with CTRL-SHIFT-K.
The plugin has to be run manually every time you start
WinAmp, or it can be automatically started if you select the
option 'auto-execute visualization plug-in on play' under
'Plugins' in the Preferences dialog.
An info plugin is also included, named gen_samurizeinfo.dll. 
It should already be in your plugins
directory. It is a general purpose plugin and should work
out of the box. You don't have to activate it. See the sample 
config advmediainfo.ini for info how to use. 


Quintessential Player (QCD)
---------------------------
The plugin files, QCDSamurizeInfo.dll and QCDSamurizeVis.dll, 
should be in the /plugins subdirectory of your QCD installation.
QCDSamurizeInfo.dll is a generic plugin, which can serve information
about the currently playing track to Samurize. The sample config 
file advmediainfo.ini demonstrates the use.
The advanced media info plugin has a function 'getPlaylistString',
which takes a 'Format' parameter. For QCD, this parameter has no
use. The current track is returned as it is printed in the
playlist. 
QCDSamurizeVis is the visualization plugin which serves the spectrum
data. For this to work a QCD Visualization Window has to be
visible, and the plugin has to be selected there. It renders a 
Samurize Logo there then. A minimized player will disable the plugin.
The plugins require QCD 4.11 or above.


FooBar2000
----------
The plugin files are foo_info_samurize.dll and foo_vis_samurize2.dll. 
The Samurize installer should have put it in the /components 
subdirectory of your FooBar installation folder.
The advanced media info plugin has a function 'NativePlaylistString',
which takes a 'Format' parameter. It uses the same formatting language
as all of foobars title formatting options. If you never used that,
"%artist% - [%album% / ]%title%" (without the quotes) might be a good
starting point. See foobars help for more info on that language.
Both the formatting parameter and the result string are truncated
to 1024 characters.
For the spectrum visualization, open the Preferences dialog and make 
sure that the visualizations are enabled. The plugin configuration 
should already be available as a subitem there.
The plugin works with FooBar2000 0.9+. 


Windows Media Player
--------------------
The info plugin file is WM9SamurizeInfo.dll. It should be where the
wmplayer.exe is - normally c:\program files\windows media player.
When the Player is running and the info plugin is activated, there is
a small green icon on the right side of the track title, indicating
that a background plugin is running. If it is not, go to options->plugins
and make sure it is listed and activated.


iTunes
------
The info plugin file is iTunesSamurizeInfo.dll, it should already be in
the "plug-ins" subdirectory of your iTunes installation. Although it is
a visual plugin, it does not need to be active to serve the data to
Samurize if you are using the AdvancedMediaPlayerInfo part. 
If you want to use the spectrum, you must activate the plugin via menu
or Ctrl-T.


Advanced Media Info functions getPlaylistString + PlaylistString_Rotate
=======================================================================
The following replace pattern applys:

Pattern   is replaced with                              QCD WA5 iTu WMP FoB
---------------------------------------------------------------------------
%b        line break                                     +   +   +   +   +
%tab      tabulator                                      +   +   +   +   +
%[        begin condition                                +   +   +   +   +
%]        end condition                                  +   +   +   +   +
---------------------------------------------------------------------------
%wp       Track title (as it appears in a playlist)      +   +   -   +   o
%wt       Track info (playlist number, title & artist)   +   +   +   +   +
%min      Minutes component of song length               +   +   +   +   +
%sec      Seconds component of song length (two digits)  +   +   +   +   +
%pm       Current song position (minutes)                +   +   o   +   +
%ps       Current song position (seconds, two digits)    +   +   o   +   +
%prc      Percentage played of current song              +   +   o   +   +
%sr       Song sample rate (eg. 44 kHz)                  +   +   -   -   +
%r        Song bitrate (eg. 128 kbps)                    +   +   +   +   +
%pl       Playlist length (number of tracks)             +   +   -   +   +
%pp       Position of current song in playlist           +   +   -   +   +
%ch       Song channel (Stereo or Mono)                  +   +   -   -   +
%f        Full path to currently playing file            +   +   +   +   +
---------------------------------------------------------------------------
%t        Track title                                    +   +   +   +   +
%ar       Track artist                                   +   +   +   +   +
%c        Track comment                                  -   +   +   -   -
%al       Track album                                    +   +   +   +   +
%y        Track year                                     -   +   +   +   +
%g        Track genre                                    -   +   +   +   +
%nt       Track number                                   +   -   -   -   +
%cmp	  Composer                                       -   -   -   +   +
%e        Encoder                                        -   -   -   -   +
%u        URL                                            -   -   -   o   +
%cpr      Copyright                                      -   -   -   +   +
%oa       Original artist                                -   -   -   +   +

+  Feature is implemented and seems to return the correct value.
o  Feature is unreliable or seems to return bogus information. The plugin
   will try to fill in information but it might not be correct.
-  Feature is not supported by the player. The plugin will replace that
   pattern with an empty string.
   
Conditions
----------
Allows you to skip parts of the pattern if a tag doesn't exist. For example,
%[Album: %al%] does evaluate to an empty string if the currently playing
song does not contain a valid album tag.
Unlimited nesting levels are supported.
   
   
NativePlaylistString
====================
Unlike previous versions, getPlaylistString does no longer allow to
use the players native formatting language (like foobar). Use this
function instead. Consult the foobar webpage for more info
on that language and examples.

   
Album Covers
============
The file AdvancedMediaPlayerInfo.opt should be in your plugins directory.
You can open it with any text editor (like notepad) to edit your options.

Options in [AlbumCover]
-----------------------
not_available: Specify the full path to a png file that should be displayed
  when no album cover could be found.
no_player_running: Specify the full path to a png file that should be
  displayed when no supported audio player is running.
downloading: Specify the full path to a png file that should be displayed
  while the download background process is running.
stream: Specify the full path to a png file that should be displayed
  when playing a livestream for which no ip-dependend image file could
  be found.
global_dir: Specify a path where covers should be searched. It is created
  if it doesn't exist
independent_name: Set to 1 if you want the tag-independent search for
  image files, 0 to disable. See below for details.
autodownload_byalbum: Set to 1 to allow searching the internet for album
  covers using the <album> tag, 0 to disable.
album_skip_words: A list of words, seperated by spaces. When searching
  by album, these words are removed from the query.
autodownload_bytitle: Set to 1 to allow searching the internet for album
  covers using the <title> tag, 0 to disable.
title_skip_words: A list of words, seperated by spaces. When searching
  by title, these words are removed from the query.
linkage: 0, 1 or 2 dependend on the type of meter linkage you want to use.
  0 will never create a meter link
  1 will create a link to the local image file
  2 will create a link to the amazon page for the album
  note that for the images not_available, no_player_running, downloading
  and stream a link is never returned.
download_size: 0, 1 or 2 dependend on the image quality you want. Smaller
  images have less quality, but also need less bandwidth to download.
  0 small images (thumbnails)
  1 medium images
  2 large images
check_online: 0, 1 or 2
  0 do not check online status (always online)
  1 check for existing ras connections (for modem, cable, dsl)
  2 check via ping www.google.com

Exclusion list
--------------
The section [Files] defines an exclusion list. You can specify files or
directory names here to have them excluded from one or more of the
search tasks listed below. The matching is done via simple substring
match, so parts of filenames will also work.
The filename or substring is followed by a = sign and an exclusion id.
The following exclusion ids are defined:
    1: don't search for folder image
    2: don't search for artist - title (local)
    4: don't search for artist - album (local)
    8: don't search for tag independent files
   16: don't search the internet (by album)
   32: don't search the internet (by title)
You can use the sum of some values to exclude the file(s) from more than
one search method. For example, use the id 48 to exclude a file from
both internet download methods.

Search order
------------
The currently playing song is analyzed. If its filename begins with http://
it is a livestream. 
When no extension is given in the following list, the search is
done for jpg, png, gif and bmp files (in that order).
Search order:
- [Local Files only] The file "folder" is searched in the 
  directory where the currently playing file is. 
  This step is skipped for iTunes which does not serve sufficient
  information.  
- The file "<artist tag> - <title tag>" is searched in the current
  directory, the directory above and the cover_global_dir directory.
- The file "<artist tag> - <album tag>" is searched in the current
  directory, the directory above and the global_dir directory.
- [Local Files only] The current directory and the directory above
  are searched for any image file, independent of the mp3 tags. This
  is skipped if the independent_name option is set to 0.
  If a filename contains "cover" or "front" it will be preferred.
  This step is skipped for iTunes which does not serve sufficient
  information.  
- If the autodownload_byalbum option is set, the plugin searches 
  www.amazon.com for an album cover using the album tag of the currently
  playing file. If available, it is downloaded and saved as <album>.png 
  in the global_dir directory. The feature obviously won't work if the 
  playing file does not have a valid album tag.
- If the autodownload_bytitle option is set, the plugin searches
  www.amazon.com for an album cover using the title tag of the currently
  playing file. This algorithm might find single covers for files not
  covered by the above option, but it has also a much bigger propability
  of downloading a cover which is not related to the file at all.
  If available, the image is downloaded and saved as png file to the
  global_dir directory.
- [Livestream only] The ip adress of the livestream is taken, with the dots 
  replaced by underscores. For the livestream url http://205.188.234.4:8028, 
  the file "205_188_234_4" is searched in the directory specified 
  in the global_dir option. 
If none of the above methods do find a valid image, the file specified
in the stream option is returned for livestreams, and the file specified
in the not_available option is returned for local files.
