Revision as of 21:22, 22 December 2023

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

• 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.

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,Right,Bottom coordinates of the rectangle.

[albumart]

Album art. Parameters:

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

[label]

Text label. Parameters:

• coordinates - Left,Top,Right,Bottom 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,Right,Bottom 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,Right,Bottom 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 / *end Toggles rendering of elements in the scope depending on the condition. Condition can be:

• playing - is playing or stopped?
• classical - playing and genre=classical?
• next - next playing track known?

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].

Example skins

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

• https://www.foobar2000.org/downloads/Black%20Skin%202023.fbskin
• https://www.foobar2000.org/downloads/White%20Skin%202023.fbskin