Revisions

Currently two revisions of the format exist.

New format (end of 2023, foobar2000 mobile v1.5)

Format extension: .fbskin (same as old format).
Skin files are renamed .zip archives and can be created or extracted using plain zip tools.
Since the payload consists mainly of image files which are already compressed, it is recommended to pack .fbskin files in store mode, for faster loading.
Direct repacking of old format skins is supported, but supported features are a superset of old format features.
Compatible with foobar2000 mobile v1.5 and newer.

Old format

Format extension: .fbskin
Original foobar2000 mobile skin format.
Packed using a proprietary tool.
Compatible with all foobar2000 mobile versions.
Some things may render slightly differently in version 1.5 because of bugs fixed.

Essential changes in new format

Can use classic foobar2000 titleformatting (%fields%, $functions(), etc) in labels to present playing track information.
Individual layout files can reference fonts/colors defined in skindef file, so if the same skin exists in different color schemes, there's no need to specialize ALL layout files.
Can specialize layouts for TV, phone, tablet targets.

Skin definition file

The entrypoint of each skin is a skin definition file (named skindef.txt, or skindef.skindef per old format).
The skin definition file describes the skin, referencing other files in your skin.
Skin definition file lines are formatted as: field: value.
Referenced file names are case-sensitive.

General information fields

skin-format

Valid value: 2 (current revision of the format) If a future incompatible revision is introduced, this will allow old foobar2000 to detect incompatible skins and show a meaningful error message.

name

Name of the skin

author

Name of the skin's author

version

Version of this skin

Images

Please use PNG or WebP lossless for images. JPEG and WebP lossy are supported but discouraged unless size or loading lag is an issue.

Note that your skin doesn't have to define all these images. If missing, they will be taken from either default skin, black or white, whichever better matches your color scheme.

defaultart

Placeholder album art image.

iconplay

Icon for playing item in browse views.

iconpause

Icon for paused item in browse views.

iconfolder, iconfolder-*

Icons for various folder types.

Colors and fonts

Colors are formatted as R,G,B, numbers in 0..255 range. Fonts are formatted as R,G,B;style, where style can be bold or italic

backgroundcol

Background color

highlightcol

Highlighted color; used for iOS navigation buttons

genericfont

Default text style

artistfont, titlefont, albumfont

Artist, title, album text style (how exactly it's applied depends on subskin files)

font-*

You can declare any number of extra fonts in your skin definition, then reference them in subskin files, instead of hardcoding colors in subskins. For an example, default skin uses font-info to control color of codec+bitrate display.

match-system-theme

Optional; indicates that this skin should use system theme colors for non-skinned user interface elements. If not specified, it is assumed that skin with black text on white background uses system white theme, and vice versa. Possible values are: match-system-theme: white, match-system-theme: black, match-system-theme: none. Last one, "none", means that system theme colors should not be used with this skin - for an example, to use actual 000000h background everywhere instead of system theme dark gray color on Android.

Subskin declarations

skin: WWWxHHH-class mysubskin.txt

WWWxHHH - width & height, in virtual units. Coordinates of all objects in referenced txt must be in (0,0) - (WWW, HHH) rectangle.
-class - OPTIONAL device class suffix. Can be -phone, -tablet, -tv. If not set, subskin is treated as -phone.

When loading a skin, foobar2000 must choose the best subskin for the current device or window size. First it searches subskins matching detected device class for one with similar aspect ratio; if there are none for this device class, it searches subskins for other classes, in common sense order (if no specialized TV subskin, looks for tablet, then for phone).

Subskins

Elements

[rectangle]

Fills a rectangle with solid color. Parameters:

color - either R,G,B, or reference to a color/font defined in skindef, such as backgroundcol.
coordinates - Left,Top,Width,Height coordinates of the rectangle.

[albumart]

Album art. Parameters:

coordinates - Left,Top,Width,Height coordinates of the album art rectangle.
which - either main (current track) or next (next track)

[label]

Text label. Parameters:

coordinates - Left,Top,Width,Height coordinates of the label rectangle. Used font size is derived from height of the rectangle.
alignment - left, right or centered
content - Label text, either static text or live formatted playback information. See labels section below for details.

[position]

Interactive seek bar Parameters:

coordinates - Left,Top,Width,Height coordinates of the seek bar rectangle.
knob-image - Image of the seekbar knob.
inactive-image - Image to be drawn to the right size of the knob.
active-image - Image to be drawn to the left side of the knob.

[button]

Interactive button. Parameters:

coordinates - Left,Top,Width,Height coordinates of the button rectangle.
action - What the button does. Possible values: playnpause, play, pause, stop, skipnext, skipback, menu, repeat, shuffle, onetrack, stopaftercurrent
image - Normal button image.
image-hot - Hot button image.
image2 - Alternate button image.
image2-hot - Alternate hot button image.

Conditional evaluation

*if <condition> / *else / *elseif <condition> / *end Toggles rendering of elements in the scope depending on the condition. Condition can be:

playing - is playing (now playing track set) or stopped (no track to show)? Note that playing is also set while paused.
classical - playing and genre=classical?
next - next playing track known?
paused - paused or not?
radio - internet radio or not?
seekable - current track can seek or not?

Condition can be modified with not keyword: *if not paused

Label formatting

Originally labels used a fixed set of [fields] to process playback information. Currently you can just use classic title formatting similar to that of desktop foobar2000, with usual %fields% and $functions().

You can change colors and fonts:

[color-colorname], [font-fontname], [rgb-R,G,B]
Toggle bold and italic style: [b]bold[-b], [i]italic[-i].

Change current information source, for both title formatting and [fields]:

[infosource-nowplaying]
[infosource-nextplaying]
[infosource-nowplaying-static] - same as [infosource-nowplaying], but bypasses dynamic information such as radio track titles - causes station name to be shown in %title%, rather than current track title.

Note that old-format fields explicitly referencing next track bypass this.

Other notable fields:

[streamtitle] - shows title, prefers static title over dynamic track titles, so it shows radio stream name instead of current track name for internet radio. Same output as [inforsource-nowplaying-static][title].

Example skins

Default skin in new format - can be extracted with zip: