Skinning Manual

Kodi includes a new GUI library written from scratch. This library allows you to skin/change everything you see in Kodi, from the images, the sizes and positions of all controls, colours, fonts, and text, through to altering navigation and even adding new functionality.

The skin system is quite complex, and this portion of the manual is dedicated to providing in depth information on how it all works, along with tips to make the experience a little more pleasant.

If you are just getting started with skinning Kodi, then it is suggested that the best way to learn is by modifying one of the many existing skins that are available. The default skin, Confluence, includes almost all the various tricks and features that make the Kodi skinning engine so powerful, so is an ideal place to start. You may wish to start by having a look through the tutorial section on skinning Kodi as well as the "Skinning Kodi" article, and try modifying a window or two by adding a button, or altering the textures or layout.

Anatomy of a Skin
Kodi skins, once installed, are located in userdata addons folder. This is the folder where all skins are placed and listed.

Any additional skins you create, or download from, or be installed via zip, Kodi will load and ask you if you would like to load the skin and also allow you to load them up from within the Appearance Settings. It is suggested that if you want to make your own skin, then starting by copying an existing skins files over into a new folder (let's say skin/myskin) is a good place to start. You can then edit each of the files as you become more familiar with the skinning system.

Each skin folder contains several subdirectorys, and one file:
 * myskin/720p
 * This is a resolution-specific directory. Kodi can run in multiple resolutions, and thus can use different files for some resolutions (as there is a big difference between NTSC at 720x480 pixels and 1080i at 1920x1080 pixels!)


 * myskin/backgrounds
 * optional folder containing the background images used in the skin


 * myskin/colors
 * contains a defaults.xml file which is used to define the colours used in the skin


 * myskin/font
 * This subdirectory contains all fonts used by the skin. you can add/replace fonts here


 * myskin/language
 * contains several subfolders for each language (English/strings.po). you can define strings used in your skin in this file.


 * myskin/media
 * This subdirectory contains all the media files (.png/.gif/.jpg...) You can replace/edit these as you like.


 * myskin/_screenshots
 * place 10 jpeg screenshots (1280x720) of your skin in here. Name them screenshot01.jpg, screenshot02.jpg ect.


 * myskin/sounds
 * put the sounds (.wav files) you're using in the skin in this folder as well as a sounds.xml file which defines what sounds are used where.


 * myskin/addon.xml
 * This contains the information that Kodi uses to find the other files that Kodi requires to describe it's skin. It also contains credits information, and versioning information.


 * myskin/changelog.txt
 * a textfile detailing what has changed in every version of the skin


 * myskin/fanart.jpg
 * a 1280x720 or 1920x1080 jpeg fanart image for your skin


 * myskin/icon.png
 * a 256x256 png image for your skin


 * myskin/LICENSE.txt
 * we recommend to include a Creative Commons license file in your skin: http://creativecommons.org/licenses/

See here for the order in which it looks for skin files.

Skin Themes
All the basic media files for a skin should be compressed into the Textures.xbt file, and placed in the media/ folder. You can use the tool Texturepacker for this. All the images that make up the default skin theme should be in the Textures.xbt file.

In addition to this, Kodi allows other .xbt files in the media/ folder, each one representing a different theme for your skin. For instance, you could tint all your main textures a red colour, and create a new theme package Red.xbt. This gives users more choice in the look of a particular skin, and only the textures change when you change themes – the layout stays the same. If the user has selected a theme, then when a control requires a texture, Kodi will first look in the .xbt file for the texture. It will fall back to the Textures.xbt file if .xbt doesn't contain the image. This means that the theme .xbt files need only contain the changed textures – all other textures will fallback to using Textures.xbt as usual.

A suggested method of creating a theme is as follows:


 * 1) Run Texturepacker.exe on the folder containing the default texture files, to generate Textures.xbt as you would normally do.
 * 2) Identify the textures you wish to have themed and copy them to a separate folder.
 * 3) Create a separate folder for each theme outside of your normal skin work area, and place the altered copies of each of the textures in them.
 * 4) Run Texturepacker.exe on each of the theme folders created in step 3 to create the themed .xbt files (note you can use the -output switch with Texturepacker.exe to name the theme appropriately).
 * 5) Place Textures.xbt and each of the theme .xbt files in the media/ folder of your skin. Kodi will automatically pick them up.

Includes
The other special (and arguably the most important skinning file of all) is includes.xml. This is, as its title suggests, a place from which you can define the default look, size, and positioning of controls, to save you replicating many of the control's attributes throughout the window .xml files. For instance, you can setup the size, and textures used for a button control, thus allowing you to leave those details out in the rest of the skin files, unless of course you want to override the default look or size etc. in a particular window.

This is extremely valuable as it allows you to greatly simplify a lot of the work in building a skin. For one thing, it means that once you have include files setup, many of the default parameters for a different resolution can be done by just altering the parameters within the include file(s) for the different resolution.

You can infact have more than one include file - you can specify the file attribute when including from a different file, allowing you to have an include file dedicated to a particular set of attributes.

The layout of an includes file is as follows.

You'll notice in the above example that we have 4 different types of includes. The first tag basically allows a substitution of the tags underneath it whenever it occurs. For instance, if in a window .xml file you have this:

Then it would substitute the tag for where the include tag is. You can have as many includes as you like, and as many tags can be inside an include - even complete controls, or complete control groups.

The second tag in the example demonstrates how to include from a different file. As there is no include name specified, it will include the contents of the entire file at that point.

The tag is similar to an include, except that it is used in every control of that type - even if you don't specify that the control is to use includes. Thus every buttoncontrol will have the whitetext include in it. Note that you can override this by specifying the tag in the buttoncontrol.

And finally, the tag allows you to define a numeric (floating point) constant by name for use in place of numeric values (, height="" etc.) would otherwise be used. This allows alignment of items using the same position values which can then easily be altered in one place.

Use params in includes
As of Kodi 15.0 Isengard you get is the ability to pass arbitrary parameters to your includes and then use these values anywhere within the include body. Just so you don't have to copy/paste huge chunks of XML anymore in order to change just a value or two. Includes are now roughly equivalent to "procedures" in programming languages. Here's the final syntax that has been included in Kodi.

Include definitions are still written within   tag, usually in includes.xml. But they can now accept parameters:

Here, the first part is called parameter list and is specified using   tags. When it is present, include body that follows it should be enclosed within   tag. At the moment, parameter list is optional and is mainly used for specifying default values for parameters (such as 120 and 225 above), but is otherwise not mandatory.

The above include can be called like this:

This has the exact same effect as if you've written this instead:

and called it (old-style) like this:

only without added benefits.

Any appropriate value can be passed as parameter in the new include call, including $INFO labels, $LOCALIZE, $VARs, constants, etc. Empty string (value="") can also be passed, for example to override a non-empty default value set in the include definition.

Default values are used as replacement when their parameters are not passed in the include call.

$PARAM references can be specified within both tag values and attributes inside include body, and are expanded to either actual value passed (if it was passed), default value (if set) or empty string, in that order.

Parameters without default values (such as id above) are specified for better readability and documentation purposes only, but are otherwise not necessary and can be omitted. This is really a matter of style, and some skinners might prefer writing explicit parameter lists to specify all parameters referenced in the include body. It's a good practice though, as explicit parameter lists might be better utilized in the future versions of Kodi.

If there are no   tags at all,   can be omitted too. This leads to even shorter syntax:

Includes can call other (nested) includes and even pass them exact parameter values that they've got themselves. This is called parameter forwarding.

Here, $PARAM[color] and $PARAM[scrollbarid] will be forwarded to MyOtherControl only if parameters color and scrollbarid have actually been passed to MyControl, otherwise the default values for color and id (if set in MyOtherControl) will be used instead in the body of MyOtherControl. Composite values containing other characters (such as label2) are not considered as "true" forwarding and always override any default value set in the nested include, even when they expand to empty strings.

Variables
Variables are a special kind of include. You can put them in Includes.xml. But usually, to keep them separate, Includes.xml gets extended with a file named Variables.xml. You can extend on the file Includes.xml by adding a line like this: Variables can be used in textures or labels/textbox/buttons ect. Instead of having to include two whole controls with a condition, they allow you to just apply the condition to the actual texture or label. Meaning less controls to maintain ect. The values in the variable are read from top to bottom and the first condition that is met gets used. The last value usually has no condition and it's content acts as a fallback. The following example shows the album label if the player has audio, the year if there is no audio and no fallback is used (because there either is or is not any audio). You can use a variable in a label control like this:

= addon.xml =

= Windows =

Window Structure
= Controls = Controls are the substance of your skin. They define everything from buttons, to text labels, to visualization placement. This portion of the manual will explain each and every control in detail.

Checkmark Control
Used on the Kai Host Dialog. Similar to Radio Button but does not have the button texture, and the checkmark is on the left

Panel Container
= Filling containers with static content =

= Filling containers with dynamic content =

= Conditional_Visibility = Kodi's skinning engine versatility is based upon the fact that the skinner can display and hide portions of the skin using a variety of conditional statements that can be combined to create very user friendly UI implementations. For further information of available variable and how they can be applied.

= Animating Your Skin = The Kodi skinning engine supports animations of any control allowing them to rotate, slide, fade or any combination there-of. Combining animations with conditional statements ensure your skin will have stunning effects that appear as professional as a 1st party product.

= Fonts = Kodi allows you to customize which fonts are displayed onscreen in the User Interface.

= Appendix I: List of Windows =

= Appendix II: List of Boolean Conditions =

= Appendix III: List of Info Labels =

= Appendix IV: List of Built In Functions =

= Appendix V: List of Built In Controls =

= Appendix VI: List of Default Icons =