

                           Amarok Plugin v1.2

                  Copyright (C) 2000 by Christer Sundin
                        mailto:christer@sundin.nu


Introduction

Amarok is a WinAmp general plugin that adds sub-song or "bookmark"
functionality to all music formats that support seeking. The principal
features of the plugin are:

* You can add bookmarks to any song that is seekable
* The bookmarks can also be used for timed display of lyrics
* Compatible with Amarok Player track lists (.trk)
* Integrates well with WinAmp (the window is skinnable and dockable)
* Able to show subsongs for the TFMX, Oldsk00l and Unpack plugins

This plugin was inspired by Mike Oldfield's album "Amarok". The CD is just
over an hour long, with *one* track, and I always thought it was a pain
to fast-forward to my favourite part - at 42 minutes and 22 seconds =).

Requirements

To use AmarokPlug you need an x86 Win32 platform (Windows 95/98/NT/etc),
WinAmp v2.5 or later, and input plugins that support seeking.

Installation

Just copy the plugin file "gen_amarok.dll" to your WinAmp plugin
directory, usually "C:\Program Files\WinAmp\Plugins". Uninstalling
is just as easy: Delete the file "gen_amarok.dll"  =)

Instructions

* Adding and deleting subtracks

There are several ways to add a new subtrack:

+ Right-click on a track or on a subtrack in the list, and select "Insert"
  in the context menu that appears. The new subtrack will be inserted immedi-
  ately after the selected track/subtrack.
+ Press the [Ins] key. The new subtrack will be inserted immediately after
  the selected track/subtrack.
+ Click on the "Add" button at the bottom of the window. If the song is
  playing, the new subtrack will have the time indicated by the current
  song position. If WinAmp isn't playing, the subtrack will be inserted
  immediately after the selected line in the list.

To delete a subtrack, do one of the following:

+ Right-click on the subtrack and select "Delete" in the menu.
+ Select the subtrack (using the mouse or the Up/Down keys) and press the
  [Del] key.

* Playing subtracks

You can start playing a subtrack by double-clicking on it in the list, or
by selecting it and then pressing the [Return] key. You can also use the
context menu and select either "Play" or "Repeat". The "Repeat" feature
"toggles" on or off, which means it stays on until you select "Repeat"
once more.

* Configuration

These are the options available in the configuration dialog:

"Save track lists automatically"   If checked, Amarok saves changes to
                                   track list files without prompting.

"Popup if bookmarks are found"     If the Amarok window is closed, it will
                                   popup its window when it finds a track
                                   file for the new song.

"Show time for subtracks"          If unchecked, Amarok won't show subtrack
                                   times in its window.

"Show track name in the list"      If unchecked, Amarok will only display
                                   the subtracks (and not the name) of the
                                   current song.

"Always show track name"           If checked, Amarok will always display
                                   the song name *above* the list (which
                                   then will be slightly smaller).

"Bookmark directory"               Here you can specify the directory in
                                   which Amarok will load and save track
                                   list files. The default directory is
                                   "Bookmarks" under the WinAmp directory.

"Hot key"                          Here you can choose a "hot key" that can
                                   be used to toggle the Amarok window.
                                   Note: This hot key only works if the
                                   WinAmp main window has the input focus.

* Closing/opening the window

If you close the Amarok window, there are three ways to make it appear
again:

1) Enter WinAmp preferences, go to "General plugins", select "gen_amarok"
   and click "Config".

2) Use the hotkey defined in Amaroks configuration dialog. This hotkey
   is disabled by default, since I have no way of knowing which keys
   aren't already used by WinAmp itself. I personally use "Alt-A" :)

3) Turn on the Amarok option "Popup if bookmarks are found". Now
   Amarok will open its window whenever it finds bookmarks for the
   currently playing song.

* Docking the window to WinAmp

You can dock the Amarok window to any of WinAmp's windows. Please note that
this feature is not quite perfect. The main problem is that once Amarok is
docked, its position will always follow that of WinAmp's main window (even
if you have docked Amarok to another of WinAmp's windows).

The track list files

The track list (*.trk) files are ordinary text files that contain sub-song
information about a CD or a song. Files saved by the Amarok plugin will only
contain information about *one song*, but it can read files saved by the
Amarok Player. Such files describe an entire CD, and the plugin will only
use the info for the currently playing song. However, the plugin reads the
entire file, so if you make changes to the track file and save it, no info
will be lost.

A bunch of track list files can be downloaded from my web page. These are
mainly for Mike Oldfield albums, but others will be added later. If you do
track lists for other albums, please send them to me so other people might
find them!

In the future I might add the ability to Amarok to automatically download
track info from my webpage...

Skins

Just like WinAmp, the Amarok plugin supports custom skins. I have already
drawn Amarok skins for my favourite WinAmp skins, and they can be found on
my web page "http://www.sundin.nu".

If you would like to draw your own skin, you can easily figure out the layout
from one of my skins. Tip: You can use the playlist editor skin (PLEdit.bmp)
as a starting point for the Amarok skin (Amarok.bmp).

Limitations

There are still a couple of limitations in the Amarok plugin. They are:

* If you are using a 256 colour display, the Amarok window will *not* look
  good. I never got that to work, but if you want me to fix it I'll give it
  another go.

* The serial number that the Amarok Player stores in the .trk files can't be
  used for matching slightly different pressings of the same CD. Therefore
  the Amarok player also uses CDDB ID, but the matching algorithm can (and
  will) be improved.

Fineprint

This software is distributed as is, without warranty of any kind, neither
expressed nor implied, including fitness for a particular purpose. The author
shall not be held liable for any loss of data or revenue or any other direct
or indirect damage caused by this software.

This means that even if this program actually does what is expected of it,
the author takes no responsibility. Or something =)

Revision history

1.2   * Shows entire CD:s in the list
      * Improved the skin format
      * Fixed several bugs and quirks

1.1   * Input plugins can now send subsong names to Amarok
      * Fixed a bug that sometimes interfered with the WinAmp repeat function
      * Fixed a problem in the input plugin communication
      * Fixed the "Play first subtrack" menu option

Copyright and credits

The Amarok plugin was developed by Christer Sundin <christer@sundin.nu>
and it's based on the Amarok Player by Gran Wallgren <gweronimo@yahoo.com>.

This software may be used and redistributed free of charge, for non-
commercial use only, provided that all files are copied unchanged.

For other use, please contact the author.

News and updates will be posted on http://www.sundin.nu

