[Index] [TitleIndex] [WordIndex

We need graphical artists

If you are good with graphics, layouts and stuff, please: we need you to improve Freevo skins and maybe design new ones. If you want to help, read this document and join the developers list. It you don't want to work on the skins, but have other ideas, you can send mockups and likes to the development lists too. If we like it we may implement it.

Why should I read this? I like the current skin.

Freevo supports folder based skins and has an extra xml file for menus with a background image you can use for DVD/VCD/CD, movie submenus and folders containing recordings of different episodes of one tv show. If you like that, keep reading or skip to the examples. :)

Selecting a different skin

You can change skins from within Freevo. Just press d (DISPLAY in your remote) in the main menu. You should get a list of the available skins. Select the one you like and press ENTER (SELECT in your remote).

This skin will not be loaded during the next run. If you want some skin as your default, change your local_conf.py and search for the GUI_XML_FILE (SKIN_XML_FILE for Freevo 1.5.x). You should change the value to the skin name you want.


SKIN_XML_FILE = 'noia'


GUI_XML_FILE = 'noia'

Writing your own skin

Turn on skin debugging

Freevo now has skin debugging mode to make writing and adjusting skins much easier. In your local_conf.py add the following:


When you next start freevo all the skin labels will be displayed allowing you to easily identify the code to the corresponding skin areas.

About the skins

In Freevo, two things can be called skins:

The files are in share/skins/<backend> (or /usr/share/freevo/skins in a default installation). They all have the .fxd extension. We will cover the skins for the main backend, so you should look in share/skins/main. The skins can inherit from each other so that information is not repeated over and over again.

The blue.fxd skin contain all needed information for a skin. All other skins inherit from this one.

Note: the extension .fxd is use for all xml files used by Freevo, so you may see files ended in .fxd that has nothing to do with the skin.

Skin structure

{i} Tip: While you read this document, open some skins in a XML editor with syntax highlight (ie: kate, vi, emacs, ...) then try to match what we say with that document. blue.fxd is the base skin, almost every other skin inherit from it. info.fxd is a more elaborated skin, with different menu styles, information for items and more. barbieri_blue.fxd is my personal skin (Gustavo), it was made to demonstrate as many as possible skin capabilities.

A skin xml contains different elements to make it possible to change the look very easy. First, the skin defines a geometry and maybe inherits from another skin. The skins provided with Freevo uses 800x600. If you use a different resolution, all positions and sizes will be scaled to fit the screen.

<!> IMPORTANT NOTE: one element can point to another referring to its label attribute.

First, we begin the XML document, specify the XML version (and if you want, specify the encoding, the default one is utf-8) and open the root tag:

<?xml version="1.0" ?>

This is needed for all Freevo XML files. Remember that .fxd files can contain other kinds of information. We need to make it clear to Freevo that we're creating a skin. For this, we use the following tag:

  <skin geometry="800x600">

This says we started to specify a skin document. The 'screen'-tag accepts the following attributes:

Using an Icon Set

Now we want to define which icon theme we use with this skin:

    <iconset theme="AquaFusion" />

All icon themes are located in share/icons/themes/.

Setting Skins Variables

We can also set skin variables using the FXD. For example:

    <setvar name="box_under_icon" val="0" />

This sets the box_under_icon value to zero, disabling this feature.

Current variables are:

Before you go any further, you should be familiar with the following tags and their functions:


You may define <color> tags so you don't need to remember values, it's easier to keep it consistent. It's easy to learn: <font label="<label>" value="<color>" />. label is how other elements will refer to this <color>, value is the color in 0xAARRGGBB (ARGB mode, in hexa), 0xRRGGBB (RGB mode, also in hexa, as used in HTML).


      <color label="list bg" value="0xa0333333" />


As simple as <color>, used to avoid typing and keep it consistent. Here's an example:

      <image label="background" filename="barbieri/bg.png" />

This tag as child of other element can have other attributes. For example, in <listing> it can have width, height, x and y and label value is used internally by listing to match some pre-defined names, used by the skin backend.

It can also be a child of layout's <background> tag. There you can refer to a previously declared <image> and specify the geometry.


Rectangles are used to draw a rectangular shape. Rectangles have a bgcolor (background color) that is used to fill the rectangle. The color is used as border color. size specifies the border size (0 disable the border). width, height, x and y specify the geometry and position. radius specifies the border radius, used to create rounded boxes.

   <rectangle bgcolor="selection bg" color="selection border" size="0" x="0" y="0" width="20" height="20" radius="10" />


You need to define a <font> tag to instantiate a font. This font then can be used everywhere in the skin. Its attributes are:

And it can also have one child tag, <shadow>, which specify the font shadow. It has the x and y attributes, that say how many pixels far the shadow will be, the color and visible="<yes|no>".

Another example:

      <font label="info title" name="impact" size="24" color="0xD59215">
         <shadow x="1" y="1" color="0x734F0B" visible="yes"/>

Setting Main Menu Items

Then, let's define the main menu:

      <item label="tv"       name="TV"       icon="tv.png"            />
      <item label="video"    name="Movies"   icon="movies.png"        />
      <item label="audio"    name="Music"    icon="mp3.png"           />
      <item label="image"    name="Images"   icon="images.png"        />
      <item label="games"    name="Games"    icon="package_games.png" />
      <item label="shutdown" name="Shutdown" icon="shutdown.png"      />

The <main> tag handles main menu item's settings. The <item> accept the following attributes:

Note: Icons will be scaled according to the line height, so based on the font size. If you want to simulate zoom effect in icons, you shouldn't give icons from different sizes in icon and outicon, but instead get icon from the same size (canvas) with the contents resized. For example, check share/icons/themes/tuxntosh/mainmenu/54x54/music.png and share/icons/themes/tuxntosh/mainmenu/54x54/out_music.png

Other configurations for main menu, like position, alignment and others are handled like other menus, with <menu type="main"> and <menuset>, except that the main menu can only have one <style>.

Defining your Menus

Now you can define what kind of menus do you want to have using the <menu> tag. Possible types are "all" (delete all other menus from the skin you inherit from), "video", "audio", "image", "games", "tv" and "default" (everything which is not defined). Each menu defines what menuset you want to use for this type using the <style> tag.

blue.fxd only defines "default, but info.fxd for examples defines more different menusets for different types.

Each menu defines a list of styles to use. You can toggle through the styles by pressing d (DISPLAY in your RC) in the menu. For instance, info.fxd has different styles (menusets), so you can, for example, browse your CD's viewing their covers.

Here's an excerpt from info.fxd:

    <menu type="audio">
      <style image="audio menu with info" text="text with info style"/>
      <style text="text with info style"/>

This tells that the Audio Menus will have 2 styles. The first style will be the default and it say it will show listings in image mode with possible a text fallback (for example, when you're browsing through music you may see CD covers, but if you're inside a CD, all items will have the same cover, so there's no sense in viewing the cover, so we fallback to the text menu). The second style is a text view. Both image and text points to <menusets>.

If an image view is defined, you will see a bi-dimensional menu with images (covers if movies/music) and possible the name under it.

If a text view is defined, you will see a one-dimensional menu with item names and possible an icon representing the item's type or some mark to allow you to identify that. For now, if some item doesn't have an icon associated and it's a directory, you will get [ and ] around the name. If it's a playlist, you get PL: before it.

If you define text and image, the menu will use image and when all covers are the same (like a directory containing all mp3 files of a cd) the skin will switch to text view. In style, you don't really define the look, you point to a menuset with the label attribute.

Menu Sets

Now, you must define all menusets your menu needs. As explained above, each <style> reference to a <menuset> with image and text attributes.

A <menuset> can inherit other menuset using the inherits="<other menuset label>". It also has some areas, here called layouts:

Each area may point to a layout. If you're inheriting other menuset, you don't need to set this. Areas may also have their position and geometry, defined as x, y, width and height. You can disable an area by setting visible="no".

<listing> can also have <image> inside them, so you can position your navigation arrows. These images have pre-defined labels: uparrow and downarrow. They're displayed just when needed.

Here's an excerpt from barbieri_blue.fxd:

      <menuset label="audio iconified with info big">
         <screen layout="audio screen" 
                 x="0" y="0" width="800" height="600" />
         <title layout="audio title"
                x="10" y="80" width="623" height="70" />
         <subtitle visible="no" />
         <listing layout="audio list" 
                  x="346" y="151" width="416" height="439">
            <image label="uparrow" x="760" y="171" width="32" height="32" filename="up.png"/>
            <image label="downarrow" x="760" y="538" width="32" height="32" filename="down.png"/>
         <view layout="audio view" x="10" y="171" width="250" height="250" />
         <info layout="audio info" x="10" y="441" width="336" height="150" />


A layout must have a label attribute, so other elements can refer to it. It also may have some children tags:

Layouts used by <screen> doesn't need the content tag, just the background one. <title>, <subtitle>, <listing>, <view> and <info>, the other way, just need the <content>.

<!> <content> is the most important element in Freevo skin. It values and children tags depends on who use it, so pay attention! .

It's attributes are:

The <listing>, <view> and <info> area may contain <item> tags inside content to define different looks for the different types of menu items.

Listing Layouts

For <listing>, the <item> tags may have the type attribute set to:

These define the settings for non-selected items, for the selected you should use the selected variant, just have the type to be one of the described above + selected, ie: audio selected, except from default which become just selected.

Note that if you use different layouts for different menus, you don't need to specify items you know will be not there. For example, you have a <menuset> used only by audio menu. The <layout> of its <listing> doesn't need to define 'game' menus, you just need to define audio related types (dvd, empty_cdrom, audiocd, dir, playlist). But if you will use the same menuset for all menus, you may define all the types.

You can define a rectangle for the listing items (the selection bar). If you like, you could also define a rectangle for the non selected items with a different background, or no selection bar for the selected item and even a transparent background for some kind of items. If you want this selection bar to be also under the icon in text views, you can define the skin variable box_under_icon (take a look in the Setting Skins Variables section).

As example, here is a <layout> to be used by <listing> for text view:

      <layout label="default list">
         <content type="text" spacing="2" align="right" valign="center">
            <!-- Define default item. ALWAYS -->
            <item type="default" font="item" />
            <item type="selected" font="selected">
                <rectangle bgcolor="selection bg" color="selection border" size="1" x="-10" y="-3"
                           width="max+20" height="max+6" radius="10"/>

            <item type="audio" font="audio item" icon="mimetypes/out_audio.png"/>
            <item type="audio selected" font="audio selected" icon="mimetypes/audio.png" />


This will display Audio items without a selection box, but with icon at the right side (because we defined content alignment as "right", and with different icons for selected and non selected items (pay attention to the filenames). All other items will show with a selection box under it, it's defined by <rectangle> tag.

This box will have a "selection border" color 1px border, that begins 10px before the item's limit and ends 10px after the limit in the horizontal direction, the horizontal limit is the one specified by the area (ie <listing>) with x and width in the <menuset>. It also start 3px before and end 3px after the item's limit in the vertical direction, the vertical item's limit is given by the item's height, if in a text menu, it's the font height, if in a image menu, it's the image height, if in a image+text menu, it's the sum of both. The box will have round corners with 10px radius.

This relative box geometry can be confusing, but it's just first impression... Better you try some tests and see the results.

Now, look at another <listing> example, this time for image+text view:

      <layout label="video list">
         <content type="image+text" spacing="-17" align="center" valign="center">

            <item type="default" width="108" height="150" font="item small" 
                  align="center" valign="center"/>
            <item type="selected" width="128" height="177" font="selected small"
                  align="center" valign="center">
               <rectangle bgcolor="list selection bg" color="list selection fg" 
                           size="1" x="-10" y="max-font_h-10" 
                          width="max+20" height="font_h+20" radius="20"/>

            <item type="video" width="108" height="150" font="video item small" 
                  align="center" valign="center"/>
            <item type="video selected" width="128" height="177" font="video selected small"
                  align="center" valign="center">
               <rectangle bgcolor="list selection bg" color="list selection fg"
                          size="1" x="-10" y="max-font_h-10"
                          width="max+20" height="font_h+20" radius="20"/>


It's almost the same, except some settings:

Info Layouts

Info layouts define what info and how these info will show up in the screen. The <item> type attribute is something like those for <listing>, except that you don't have the selected variant. Again, if you will use this layout from a menuset used by just some kind of items, you don't need to define all types, like in the following example, which is used only by audio menu's in barbieri_blue.fxd.

You need to know some formatting tags before looking at the example. They're:

So, here goes the example:

      <layout label="audio info">
         <content x="0" y="0">

            <item type="audio">
               <if expression="title">
                  <if expression="track">
                     <text height="line_height"
                           align="left" font="info title" 
                           mode="hard" expression="track" />
                     <text font="info title"> - </text>
                  <text height="line_height"
                        align="left" font="info title" 
                        mode="hard" expression="title" />
                  <newline />

               <if expression="artist">
                  <text height="line_height" width="75"
                        align="right" font="info label" 
                  <goto_pos x="10" mode="relative" />              
                  <text height="line_height"
                        align="left" font="info value" 
                        mode="hard" expression="artist" />
                  <newline />     

               <if expression="album">
                  <text height="line_height" width="75"
                        align="right" font="info label" 
                  <goto_pos x="10" mode="relative" />              
                  <text height="line_height"
                        align="left" font="info value" 
                        mode="hard" expression="album" />
                  <if expression="year">
                     <text font="info value"> (</text>
                     <text height="line_height"
                           align="left" font="info value" 
                           mode="hard" expression="year" />
                     <text font="info value">)</text>
                  <newline />

            <item type="dir">
               <if expression="name">
                  <text height="line_height"
                        align="right" font="info title" 
                        mode="hard" expression="name" />
                  <newline />

               <if expression="dir">
                  <text height="line_height"
                        align="left" font="info value" 
                        mode="hard" expression="dir" />
                  <newline />     

            <item type="playlist">
               <if expression="len(playlist)>1">
                  <text font="info value" expression="len(playlist)"/>
                  <text font="info value"> musics in this playlist.</text>

               <if expression="len(playlist)==1">
                  <text font="info value">Just one music in this playlist.</text>

               <if expression="len(playlist)==0">
                  <text font="info value">This playlist is empty!</text>


Defining TV settings

TV is just like other menus, the <tv> tag behaves just like <menu>in which you select different <menuset> using the <style> tag. (See Menu Sets section).

As in TV Guide you can move horizontally, you may also define <image> tags with label="leftarrow" and label="rightarrow", just you do for uparrow and downarrow in other <listing>.


         <style text="tv menu"/>
         <style text="tv menu more info"/>

      <menuset label="tv menu">
         <screen layout="tv screen" x="0" y="0" width="800" height="600"/>
         <info   layout="tv info" x="10" y="70" width="780" height="140"/>
         <title  visible="no"/>
         <listing layout="tv listing" x="10" y="220" width="750" height="370">
            <image x="765" y="220" width="32" height="32" label="uparrow"
            <image x="765" y="max-32" width="32" height="32" label="downarrow"
            <image width="16" height="16" label="leftarrow" filename="left.png"/>
            <image width="16" height="16" label="rightarrow" filename="right.png"/>

      <menuset label="tv menu more info" inherits="tv menu">
         <listing height="150"/>
         <info layout="tv info" y="250" height="340"/>

Defining Player settings

Player is just like <menuset>:

         <screen layout="player screen" x="0" y="0" width="800" height="600"/>
         <view layout="player view" x="430" y="230" width="420" height="360"/>
         <info layout="player info" x="-50" y="80" width="600" height="300"/>
         <title visible="no"/>


OK, here some nice cool small examples:

Different background image

You may have a file called skin.fxd in the freevo config directory. In this file you could write:

  <?xml version="1.0" ?>
      <image label="background" filename="my-background"/>

and now you have a different background image for the menu. You could also put this in a folder.fxd and Freevo would use the new background in this folder only. So if you're Star Wars big fan, your Star Wars movie collection can have a different background!

Changing skins

More? OK, maybe you like info.fxd. But you also like the 3rd view skin (detailed info) in the video menu. But you only want that in the folder with all your fxd files pointing to your DVDs. Just create a folder.fxd, inherit from info.fxd, force the skin to 3rd view and set the background to some you want:

<?xml version="1.0" ?>
    <setvar name="force_skin_layout" val="2"/> <!-- this select the 3rd view (detailed info) -->
  <skin include="blue2" geometry="800x600">
    <image label="background" filename="myfavorite_bg.jpg" /> <!-- should be a file called myfavorite_bg.jpg in share/images/ -->

Background images for DVDs or tv show folder

Now something different: you want a background image for a folder or as DVD menu. You don't need a title area, no view or info area, there is this background image. OK, just inherit from the image.fxd (a skin specially designed for this purpose) and redefine the listing area position and the colors (look at share/skins/main/image.fxd for more details). E.g.: I have a nice orange background for my Charlie's Angels DVD. I also have a fxd file for this DVD. I just added skin information to that file:

  <?xml version="1.0" ?>
      The information in this file are from the Internet Movie Database (IMDb).
      Please visit http://www.imdb.com for more information.

    <disc-set title="Charlie's Angels">
    <!-- ... the rest of your FXD, probably you may get this with the Search IMDb plugin -->

    <skin include="image" geometry="800x600">

      <menuset label="bgimage style">
        <listing x="10" y="100" width="300" height="340"/>

      <image label="background" filename="charlies_angels_bg.jpg"/>

      <color label="selected" value="0xffff00"/>
      <color label="item" value="0x000000"/>
      <color label="selection bar" value="0xa0000000"/>

CD-ROM support

Don't put a folder.fxd file on a cd. The format may change.

You always should use the movie fxd file to do that and put this file in some dir accessible by freevo, ie the defined in DIR_MOVIES or MOVIE_DATA_DIR. If you put in MOVIE_DATA_DIR, then when you insert your CD, it will show the information automatically. If you put in DIR_MOVIES it will do the same as MOVIE_DATA_DIR and will show the movie in the dir, even if the disc is not there. When you press ENTER (SELECT in your RC), Freevo will ask you for the Disc.

Write a new skin, including new Python code

If you don't like the current skin at all, you can write your own skin in python and you have all the freedom you want in designing the look of freevo. Please take a look at skin.py to get the needed callbacks your skin needs.

OSD Skins

OSD Skins are used to change the look and feel of some of the dialog boxes displayed in the Freevo frontend and also the play state or the EPG information displayed when viewing a movie or watching TV. To enable the use of OSD skins when viewing a movie or watching TV you need to be running Freevo under X11, have installed the kaa.display package (currently only available from the subversion repository) and using Freevo 1.8.4 (or the latest svn version).

Selecting an OSD Skins

To select the OSD skin to use simple add:

DIALOG_SKIN_XML_FILE='<your chosen skin name>'

to your local_conf.py file. By default the base skin is selected.

Creating/Editing an OSD Skin

Creating a OSD Skin is similiar to writing a menu skin for Freevo, but slightly simpler due to the use of the OSD Designer (see OsdDesigner for more details).

2014-02-15 05:47