In this article annex tutorial I will prove two things:

1. that the so-called “hard” XML is easy
2. that the so-called “hard” WinAmp3 is easy

One follows the other so to speak. I've noticed that whenever either XML or WinAmp3 is mentioned, the flock instantly reacts with cries like “oh, that's too difficult for me”, which sometimes makes me wonder: either I am really intelligent, or this community/scene (whatever you prefer) consists of idiots.

So time for a brief intro on WinAmp3 skinning. I'll start off with some words on XML, the language WinAmp3 skins are written in; then I'll discuss a very very basic skin. Phase three will be to get that very basic skin to function and I'll finish with some (general) pointers on how to continue.

phase one: the basics of XML

XML, short for eXtended Markup Language, is a simplified form of SGML, Standard Generalised Markup Language, which has been an industry standard in desktop publishing for over a decade now. Another simplified form of SGML is HTML, the language in which websites are written.

Many find HTML complex already and that's just a simplified form of SGML, so the complexity of that must be enormous to them (note that I have never ever encountered SGML, so I'm might be making all this up). It's what the World Wide Web Committee though anyway, and they come up with all these standards. In order to make pure data more accessible, they've created XML.

It's a very interesting language in that it consists of very little rules which allow for a lot of diversity. Where in HTML you have predefined tags which are supposed to do predefined things (for example: this is <i>italic</i> text will display in a browser as this is italic text), XML is completely open. In XML you don't have predefined tags, you (or rather, the developer) define them yourselve. This means it's a bit of building castles in the sky; unlike HTML, it isn't fixed what an XML file does. It depends on the app that handles it.

Confusing? Let me get on with some examples then. An XML-file consists of two things: a declaration of all elements in the file and the elemements themselve. The declaration (or Document Type Declaration, as the formal term is) defines what kind of elements there are in an XML-file of that type, how they are structured and what kind of data they can contain. Or in other words, it's a sort of template. This DTD-thing is the only “hard” part of XML. I myself have yet to figure out how it exactly works. Luckily, you can omit it, and so I will.

The second thing an XML-file is made up off, are the actual elements and the data they contain. XML is a container format, it does nothing besides packaging data in a readable form. How these elements work is best explained through a sample XML-file:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <article>
     <title>Descending into the Depths of WinAmp3</title>
     <author>craeonics</author>
     <description>
       A look at the inner workings of both XML and WinAmp3's skin format, both
       of which are considered hard by the masses, and neither of which actually 
        are.
     </description>
   </article>

The above could be a way of storing information about tek articles. The first line is what declares the file as an XML-file. version indicates the XML-version (which is usually 1.0), encoding defines the character set used. Encoding is usually of no interest to English speaking people, because it has to do with how special characters like á, è and so on, are encoded in the file. UTF-8 means it's Unicode. I have no idea what standalone means (I have yet to read the XML-specification), but it doesn't really matter, 'cos this is a line you just copy from file to file without changing it.

The rest of the file is more interesting and demonstrates the basic principles of XML. Everything within angled brackets (< and >) defines an element. An element is a container that can contain data. It starts with <element_name> and ends with </element_name>. Everything in between is data in that element. So in the above example, we have an element article, containing an element title, author and description.

For comparison, if this were an .ini-file, it would look like this:

   [article]
   title = Descending into the Depths of WinAmp3
   author = craeonics
   description = A look at the inner workings of both XML and WinAmp3's skin 
     format, both of which are considered hard by the masses, and neither
     of which actually are.

The difference with an .ini-file, however, is that elements in XML-file can be nested (placed inside each other, like title is placed inside article) forever, which is impossible in an .ini-file (well, it can be done, but it will be a big mess because of the lack of a hierarchy in the file).

Alternatively, the above example can also be written as:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <article
     title="Descending into the Depths of WinAmp3" 
     author="craeonics"
     description="A look at the inner workings of both XML and WinAmp3's
         skin format, both of which are considered hard by the masses, and
         neither of which actually are." />

So the elements of article in the first example, have become parameters of article (and are thus placed inside the article tag). There is little difference between an element inside an element and a parameter. Just that an element can only have one parameter of the same kind, while you can have as much elements of the same name as you wish. If I wanted, I could've put in six title elements and it would have caused no problems, but doing so as a parameter would. Thereotically speaking ofcourse. The interchangeablility of parameters and elements all depend on the app that will handle the file.

Two things to note here. First of notice how all parameter values are placed between quotes (highly obnoxious, but required) and secondly, notice the /> at the end. An empty element (meaning: an element with no data (not counting parameters)) can be written as either <element_name></element_name> or <element_name/>.

That's basically all there is to XML (aside from DTD's, which I'll skip). Let's move on to WinAmp3.

phase two: a very basic WinAmp3 skin

The reason for that long and winding story on XML is that WinAmp3 uses XML as its skin format. About time too I'd say. Now take a look at this very basic WinAmp3 skin. It doesn't do anything yet, but you can move it around (and notice how WinAmp3 correctly handles PNG-transparency, you can see through the wings *drool*).

In order to create a WinAmp3 skin, you first hop over to its skin folder and create a new directory. The name of the directory is the name of the skin (in this case beast). Now make an image of how you want your skin to look and save it into this directory. In my case, I drew this insect/beast in Flash and exported it as .png so I could get a nice opaque bitmap without all the Photoshop antialiasing nonsense. I named this image beast.png.

Then create a textfile in this directory named skin.xml. This is the file WinAmp3 will be looking for. Open skin.xml in Notepad and enter the following (replacing the name of the image file (beast.png) with how you named it ofcourse):

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <WinampAbstractionLayer version="0.7">
     <skininfo>
       <name>beast</name>
     </skininfo>

     <include file="../default/xml/studio.xml"/>
     <include file="../default/xml/gamma-presets.xml"/>
     <include file="../default/xml/thinger.xml"/>
     <include file="../default/xml/minibrowser.xml"/>
     <include file="../default/xml/components.xml"/>

     <elements>
       <bitmap id="beast.background" file="beast.png"/>
     </elements>

     <container id="main" name="Shadow of the Beast">
       <layout id="normal" background="beast.background">

       </layout>
     </container>
   </WinampAbstractionLayer>

I'll this discuss it line by line, but first save this and fire up WinAmp3. Right-click on it and got to the skins menu. You'll see your own skin listed. Load it and marvel! In my case, I got the above screenshot and was amazed to see an app properly dealing with .png transparency (I already said that, but I am still baffled). You can't really do anything with it, other than move it around, but it's a good first start. Note that this is the first time I ever made a WinAmp3 skin, so if I get this far with no mistakes whatsoever on my first go, it can't be hard, right?

Okay, so how does it work? The first line: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> defines this file as an XML-file. The XML-standard requires it. No need to modify it, just copy-paste. Now look at the second and last line, <WinampAbstractionLayer version="0.7"> and </WinampAbstractionLayer>. These define the so-called root element, the element in te file which contains all other elements. WinampAbstractionLayer just means WinAmp3 skin. The version="0.7" parameter is there to keep WinAmp happy. I omitted it first, which resulted in WinAmp complaining about this being “a skin in an old format, which might crash this WinAmp3 build”.

Next up is an element called skininfo, containing another element called name. These define information on the skin, in this case its name. Other elements which can be put inside skininfo, are version (version of the skin), comment (a short description), author, email, homepage and screenshot, which is the name of the file to be displayed as preview of the skin.

Then follows something interesting. Seeing WinAmp3 is a menacing task to skin, with loads and loads of windows, controls and what not, you can split things up into separate files to keep it manageable. The include element lets you include another .xml file, which defines a particulart part of the skin. In this case, I opt only to skin the main window and to use the default skin for the other bits. So I include all these default .xml files, which will ensure the rest is skinned as well, be it not by me. Good for lazy skinners like me. The main window is the most flexible one anyway, as far as I can see, other windows are much more restricted to rectangles.

We're still not at the actual layout definition, the placement of all elements. First we define all bitmaps, cursors, colours and what not. This is done in this piece of code:

   <elements>
     <bitmap id="beast.background" file="beast.png"/>
   </elements>

It basically means we can now point to the file beast.png by using the name beast.background. Whatever you name your elements is entirely up to you. I could've called it banana.split and it would still have worked. To define multiple bitmaps (or to define colours, fonts or cursors), you can add multiple <bitmap> elements (or <cursor>, <font> or <color>, but I'll limit this article to what's in this skin).

Finally we reach the part where all the magic happens:

   <container id="main" name="Shadow of the Beast">
     <layout id="normal" background="beast.background">

     </layout>
   </container>

This is the part in which the main window is defined. A container is a grouping mechanism for multiple layouts. Here we have a (required) container with the id main, containing a (required) layout with the id normal. WinAmp will look for a container with the id main, containing a layout element with the id normal in order to draw its main window. A layout is the skin of a window, meaning you can have multiple skins for a window (by having multiple layout elements) by putting them in the same container. For example, a normal mode and a windowshade mode.

See the name of the container? That's the name of window, which WinAmp will display in the context menu if you right-click on it.

Alright, so a layout is the point where we finally see the skin being defined. Like I've said, this is a very simple skin, it doesn't do anything. If you look at the code you'll see why: the layout element is empty. I've only defined its background parameter (which uses the id which was defined in the elements section. In the next section, we'll fill this layout with some buttons and make the skin play files.

phase three: a simple functioning skin

Alright, this will be the exact same skin, but this time functional (be sure to grab the file!). So no new screenshot. Instead, I'll spook you with the full code of the skin.xml and tackle that line by line (well sort of). See if you can make sense of it.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <WinampAbstractionLayer version="0.7">
     <skininfo>
       <name>beast</name>
       <version>2</version>
       <comment>
         Very very basic skin to demonstrate some stuff for a 
         Teknidermy article
       </comment>
       <author>craeonics</author>
       <email>tek@ecliptic.dds.nl</email>
       <homepage>
         http://www.teknidermy.com/issue/9/descending_into_winamp3/
       </homepage>
       <screenshot>screenshot.png</screenshot>
     </skininfo>

     <include file="../default/xml/studio.xml"/>
     <include file="../default/xml/gamma-presets.xml"/>
     <include file="../Default/xml/thinger.xml"/>
     <include file="../default/xml/minibrowser.xml"/>
     <include file="../default/xml/components.xml"/>


     <elements>
       <bitmap id="beast.background" file="empty.png"/>

       <bitmap id="beast.wing.left" file="wing.left.png"/>

       <bitmap id="beast.claw_previous.normal" 
         file="claw_previous.normal.png"/>
       <bitmap id="beast.claw_previous.over" 
         file="claw_previous.over.png"/>
       <bitmap id="beast.claw_previous.down" 
         file="claw_previous.down.png"/>

       <bitmap id="beast.legs" file="legs.png"/>

       <bitmap id="beast.antenna.left" file="antenna.left.png"/>

       <bitmap id="beast.shield_load.normal" 
         file="shield_load.normal.png"/>
       <bitmap id="beast.shield_load.over" 
         file="shield_load.over.png"/>
       <bitmap id="beast.shield_load.down" 
         file="shield_load.down.png"/>

       <bitmap id="beast.shield_stop.normal" 
         file="shield_stop.normal.png"/>
       <bitmap id="beast.shield_stop.over" 
         file="shield_stop.over.png"/>
       <bitmap id="beast.shield_stop.down" 
         file="shield_stop.down.png"/>

       <bitmap id="beast.shield_pause.normal" 
         file="shield_pause.normal.png"/>
       <bitmap id="beast.shield_pause.over" 
         file="shield_pause.over.png"/>
       <bitmap id="beast.shield_pause.down" 
         file="shield_pause.down.png"/>

       <bitmap id="beast.shield_play.normal" 
         file="shield_play.normal.png"/>
       <bitmap id="beast.shield_play.over" 
         file="shield_play.over.png"/>
       <bitmap id="beast.shield_play.down" 
         file="shield_play.down.png"/>

       <bitmap id="beast.wing.right" file="wing.right.png"/>

       <bitmap id="beast.antenna.right" file="antenna.right.png"/>

       <bitmap id="beast.claw_next.normal" 
         file="claw_next.normal.png"/>
       <bitmap id="beast.claw_next.over" 
         file="claw_next.over.png"/>
       <bitmap id="beast.claw_next.down" 
         file="claw_next.down.png"/>
     </elements>


     <container id="main" name="Shadow of the Beast">
       <layout id="normal" background="beast.background">
         <layer x="0" y="40" ghost="0" move="1" 
           image="beast.wing.left"/>

         <button action="PREV"
           x="5" y="189" tooltip="Previous"
           image="beast.claw_previous.normal"
           hoverImage="beast.claw_previous.over"
           downImage="beast.claw_previous.down"
         />

         <layer x="27" y="62" ghost="1" move="1" 
           image="beast.antenna.left"/>

         <layer x="80" y="135" ghost="0" move="1" 
           image="beast.legs"/>

         <button action="EJECT"
           x="160" y="95" tooltip="Load file"
           image="beast.shield_load.normal"
           hoverImage="beast.shield_load.over"
           downImage="beast.shield_load.down"
         />

         <button action="STOP"
           x="35" y="172" tooltip="Stop"
           image="beast.shield_stop.normal"
           hoverImage="beast.shield_stop.over"
           downImage="beast.shield_stop.down"
         />

         <button action="PAUSE"
           x="35" y="167" tooltip="Pause"
           image="beast.shield_pause.normal"
           hoverImage="beast.shield_pause.over"
           downImage="beast.shield_pause.down"
         />

         <button action="PLAY"
           x="37" y="72" tooltip="Play"
           image="beast.shield_play.normal"
           hoverImage="beast.shield_play.over"
           downImage="beast.shield_play.down"
         />

         <layer x="80" y="0" ghost="1" move="0" 
           image="beast.antenna.right"/>

         <layer x="125" y="47" ghost="1" move="0" 
           image="beast.wing.right"/>

         <button action="NEXT"
           x="82" y="159" tooltip="Next"
           image="beast.claw_next.normal"
           hoverImage="beast.claw_next.over"
           downImage="beast.claw_next.down"
         />
       </layout>
     </container>
   </WinampAbstractionLayer>

As usual, we start off with the XML-declaration, follow by the opening tag of the WinampAbstractionLayer container. Then we get the skininfo bit, this time it;'s the full deal. Seeing I'm still way too lazy to do a full skin, I'll stick to the main window again and just include the rest from the default skin.

Then we get the element section, which is similar to the previous skin, be it much more elaborated. This version of the skins is build up of lots of images for every part and this is the section in which they are defined. Note how I try to give each image a logical id. Clear names is always a good idea. Makes the code more readable. Also note the order in which I define the elements. You can define them in every order you like, it doesn't matter, but I opt to define them in the order in which I use them, again for readability.

The container and layout bits are the same as last time, but this time the layout contains more elements. There are two new element types, as can be seen in this short snippet:

   <layer x="0" y="40" ghost="0" move="1" image="beast.wing.left"/>

   <button action="PREV"
     x="5" y="189" tooltip="Previous"
     image="beast.claw_previous.normal"
     hoverImage="beast.claw_previous.over"
     downImage="beast.claw_previous.down"
   />

All elements within a layout are stacked on top of each other when displayed. The first element (at the top of the file) will be at the bottom and each element after that will be drawn upon that. A button is an element that allows you to do thing, a layer is just an image (it can do things, but not in this article).

A layer has a number of parameters. x and y speak for themselves. Their value is the offset against the top left corner of the background image. The background image also defines the maximum area wherein subsequent elements can be displayed. So if I have a background that is 200 pixels wide and I use a layer with x='300', it won't be visible.

The parameter image points to the id of the image to use. This id was defined in the element section. ghost and move define how the layer will interact. If ghost='0' it will intercept all mouseclicks and mouseovers within the entire rectangle of the image. A bit weird, 'cos I thought it would only grab these on the non-transparent bits. What does this mean? It means that if you put a layer on top of a button (I will get to those later), the button will not respond to mouse actions because the layer is intercepting these. If you set ghost='1', the layer will let everything through and the button will function as expected.

A value of move='1' will make it possible to move the window around by clicking and dragging on this layer. And it may come as no surprise that move='0' will mean that you can't drag the skin via this layer. Note that you can't drag the window by dragging this layer if ghost='1', because since the layer is letting all mouse actions through, it won't notice someone is trying to drag. Therefore when ghost='1', move='0'.

A button is more interactive, it will respond to mouseovers and mouseclicks. hoverImage and downImage are the (id's of the) images for these states. tooltip doesn't seem to work yet, but I include it anyway. It's the help message you should get when you hover your mouse over a button for some time, just like in most apps.

All the nitty gritty happens in the action parameter. As you see I've used values of PREV, NEXT, PLAY, PAUSE, STOP and EJECT. This it what makes WinAmp go. So if you give a button the action PLAY, it will play the currently selected song. EJECT is cryptic, but just means "load file".

Some other values for action are CLOSE, MINIMIZE (guess what those do?) and SWITCH. This last one lets you swith between layouts, so you can swithc between a normal window and windowshade mode by making a button with action='SWITCH' and using the additional button parameter param='id', where id is the id of the layout you want to switch to (if you check my skin you'll see there's only one layout (called "normal"), so I didn't boither to use a switch button). So to switch to the layout with the id="shade", it would become something like this then:

   <button action="SWITCH" param="shade"
     x="5" y="189" tooltip="Previous"
     image="beast.switch.normal"
     hoverImage="beast.switch.over"
     downImage="beast.switch.down"
   />

That about all there is in this skin. Note how I've defined the layer with the left wing first, which is followed by the previous button and so on and finish with the next button. This is the stacking I've mentioned: the left wing is in the back and the next button in the front, with the rest in between in the order of their code.

phase four: figure it out yourself!

This should be enough to get you started. There are a number of other display elements other than layout and button, like togglebutton, which is a button which will stay down until you press it again (like the equalizer button and such). slider is used in volume and seek bars, while animatedlayer lets you make animated layers, cool! And there are more elements and I haven't even mentioned scripting yet!

So plenty of stuff to explore. The best way to figure things out is (as always) to disect existing skins and see how they are done. But a reference would be handy. There was such a reference (and I've stolen a lot from it), but it seems to have vanished. Too bad.

I know of two resources on this (other than Nullsoft's developer section): a simple tutorial and a scripting reference. A good skin to disect would be the Simple skin, which is really simple and demonstrates some other methods, like using a region of a bitmap as an element (so you can make one bitmap and grab all your buttons from it by specifying regions), after that take a look at the default skin and more complex one, like Boxor.

Doh, I knew I'd forgotten something. WinAmp3 skins are distributed in .wal format. This is just a renamed zipfile of all the files used in the skin. So if you want to see what's inside a skin, rename the .wal to .zip and unzip the thing. Similarly if you have a skin and want to upload, zip the lot up and change the extension to .wal.

Okay, so this article may have lead to more questions than it has given answers and WinAmp3 skinning may not be as easy as I claimed it was, but it sure as hell isn't difficult or impossible. It's a challenge and we need those if we want skinning to evolve, else we'd be stuck with basic, restricted formats like the one it originally started with.

A final note: this article may seem a bit rushed. Hey, it is. I've been wasting my Easter holiday on putting together Tek Nine and this was just about the last thing that still had to be done, so it's been quick and dirty. Let's hope I've got things ninety percent right this first time and it has been useful to you.

— craeonics, March 31st/April 1st 2002

addendum

Various people have noted that the second skin doesn't seem to work. Well, yes and no. I works fine on my machine, WinXP running WinAmp3 build 466. That screenshot up there is no fake. But I took a peek under 98 and it didn't seem to do anything. The first skin did work, but without the alpha. So it seems alpha is for 2000/XP only.

Two solutions where given (in the comments below). The first one is adding the parameter desktopalpha='1' to the <layout> element. Doesn't seem to do a thing in 98 though.

The other solution is to use the file screenshot.png as background image instead of empty.png. This still does not give you alpha transparency, but the skin will be visible (be it ugly). This is (I guess) because all the buttons and layers are drawn only on top of a visible background pixel when there is no alpha support.

Supa just gave a third solution, which is simply switching on enable desktop alpha in WinAmp's options. That should fix things on XP. I probably forgot about this, because I always switch on stuff like that on my first go and hadn't played with WinAmp3 for a while.