How to write a Bemused skin

Introduction

You can customise the way Bemused looks with skins. A skin consists of an image file (in PNG format) and accompanying description, with which you can specify the following aspects of the "Control" view: You can also specify the foreground, background and selected item colours for the "Browse" view. Skins are fairly easy to write; this page aims to give an introduction to the process.

Elements of a skin

A skin can either be for Bemused's "full-screen" mode, or its "in window" mode. You should try to provide both, so the user can choose the size they prefer. The names of skin files must conform to the following format: [Name of skin] is the name that will be displayed to the user when installing or uninstalling the skin. Note that it can include spaces.

Skins are installed by simply sending them to the phone, running Bemused and selecting "Install skin" from the settings.

Format of a skin image file

The following picture illustrates the different elements of a skin image file:

The image consists of the background (at the top), followed by extra information about the buttons, volume slider, shuffle and repeat. The size of the background depends on whether the skin is full-screen or not. For an in-window skin, the background will be 176 x 144 pixels big. For a full-screen skin, it will be 176 x 188 pixels big. The total size of the image also depends on the size of the buttons and other elements. Don't worry if the image is too big; it will be cropped to the size of the window.

As you can see, the elements below the background image represent the buttons in "focused" and "pressed" states. Note that there is some unused space to the right and the bottom of the image. Below the two rows of buttons is the final row of controls, which contains the volume slider, the volume slider mask, and repeat and shuffle images.

Unlike all the other elements of a skin image, the volume slider has a mask as well. This means that you can make sliders which are partly transparent. The mask is the same size as the slider, and there's only one thing to know about it: black represents transparency. Any other colour represents opacity.

Note that all of these elements can be any size you like (within the limits of screen size). Bemused will calculate their size and position from the values specified in the skin description file. It's very important to get these values exactly right; being one pixel off can make a big difference.

Format of a skin description file

A skin description file consists of a list of attributes and parameters. The format of these is:

[attribute]: [parameter 1] [parameter 2] ... [new line]

Attribute names are not case-sensitive. Only decimal numbers (ie. not hexadecimal) can be used for parameters. Colour parameters are 3 numbers in the range 0-255. For example, red would be specified by "255 0 0".

The following attributes can be used:

Font numbers are mapped to fonts using the following scheme:
  1. Title font (largest)
  2. Dense font (smallest)
  3. Legend font (second smallest)
  4. Annotation font
  5. Symbol font
  6. Normal font (second largest)
Note that, if an attribute isn't specified in a skin description file, Bemused will use the default value. However, you shouldn't rely on this, as the defaults may change in the future.

Tips

And finally... good luck!