How To create text-based skins ------------------------------ [ TODO remove this ] You may encounter bracketed phrases in this document. Please ignore them, they are comments for me which will be removed in official release versions. [ TODO move this to manual ] The Skin itself is located in a subdirectory "text2skin" inside the "plugins" directory of your VDR configuration directory. This usually is the video directory, if you didn't specify -c on the commandline. If you did, the subdirectory is located there. Each skin has an own subdirectory there, which holds the skin description file and the needed image files. The skin description file must have the same name as the skin directory, with the extension ".skin" Example (the Skin is called myskin): /video0/plugins/text2skin/ /video0/plugins/text2skin/myskin/ /video0/plugins/text2skin/msykin/msykin.skin /video0/plugins/text2skin/myskin/channeldisplay.png It is important that you understand the limitations of the OSD memory. If there are too many objects with too many colors defined, VDR will throw an error and some areas will not be displayed. For other output devices this limitations may not apply, so if you are planning to design a skin for another output device, feel free to use more colors, but remember that VDR can handle a maximum of 256 areas per object. An object is defined to be a specific area with a specific palette and color depth. Those objects will be referred to as 'backgrounds' later on. Calculate the dimensions of them wisely, since overlapping areas or oversized areas will lead to an error. Also, the widht and height of each area has to be a multiple of four [ TODO may not apply to different output devices ]. Creation of an image -------------------- I used gimp to create some test images displaying things on screen, although I don't know much about image processing :-). To give an advice, I will point out how I created those test images. I've used a template for a menu provided by a community member, tiled it into sections fully covered by the image. That made three images in this case. Then I added a little bit of transparency to the image covering the middle part. I've resized the image so that it's width and height were multiples of four. Now I've added 50% transparency to the top layer of the image. Then I've reduced the colordepth of the image (Image->Mode->Indexed) to 14 colors (of course the image may not be too extensive, but 14 colors can give some nice gradients). That leaves two colors for text and progress bar in the same display. Reduce the number of colors according to the background depth and additional decoration you intend to use. I saved the results to a png file and placed the result into the skin. If you intend to use xpm's, be aware that VDR doesn't know about named colors, so some images GIMP creates will not be read on-the-fly, because GIMP may use some named colors, but VDR only recognizes "None". The Description File Format --------------------------- It is a simple configuration file, consisting of Sections and items. Commentary lines can be added when they are lead in by a '#'. Blank lines will be ignored. A section is placed in '[]' brackets. An item is lead in by an 'Item=object' phrase. Example: Item=Skin,name=Test,version=0.0.1; [Channel] Item=Background,path=channeltop.xpm,x=42,y=350,width=540,height=32,bg=#00FFFFFF; Item=Background,path=channel.png,x=48,y=382,width=528,height=84; Item=ChannelNumberName,x=50,y=355,fg=#FFFFFFFF,bg=#FF1965FF,font=Sml; Item=PresentTime,x=52,y=387,fg=#FFFFFFFF,bg=#7F002254,font=Osd; [Volume] Item=Background,x=10,y=10,width=10,height=100; Item=Volumebar,x=10,y=10,width=10,height=100,bg=#FF000000,fg=#FFFFFFFF; Known Sections -------------- Section: [ChannelSmall] Description: The channel display. It displays the current programme and number only, together with some decoration. Section: [Channel] Description: The channel display. It displays the current programme and number, together with the currently running programme and possibly a timebar and (not implemented yet) channel logo [ TODO remove comment ]. Section: [Volume] Description: The volume display. It displays the volumebar and possibly a mute symbol, along with decorative items. Section: [ReplayMode] Description: The replay modes display. Will be shown if only the replay mode symbol shall be shown. Section: [Replay] Description: [ TODO ] Full replay display. Section: [Message] Description: [ TODO ] Message only display. Section: [Menu] Description: [ TODO ] Full menu. Known Items ----------- Item: Item=Skin Description: This identifies the skin and adds a description to it. Parameters: name, version Item: Item=Background Description: This adds a background area for the specific display. This area will be used to draw anything else, so you have to define a background for everything that will be drawn later on. You can define a background image for that area here, too. That picture has to be the same width and height as the area. If you don't use a background image, the area will be initialized with the bg color (default 0). If an image is present, the background color will replace the color 0 in the images palette, and the foreground color will replace color 1. Parameters: x, y, width, height, bpp, path, bg, fg Item: Item=Text Description: Draws plain text into the given area, using the given foreground color. The background color is ignored, so no initializing rectangle will be drawn. If no width or height are given, the limits are the background areas. Parameters: x, y, text, width, height, fg, font, align Item: Item=Image Description: Draws a plain image into the given area, using background and foreground color (if given) to replace the palette indices 0 and 1. Parameters: x, y, width, height, fg, bg, path Item: Item=DateTime Description: Draws a date and time string into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=Date Description: Draws a date string into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=Time Description: Draws a time string into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=DateTimeF Description: Draws a string expressing some details of the current date and time. What is to be displayed will be decided by the skin author. The paremeter "format" holds a format string according to the manpage of strftime. Parameters: x, y, width, height, fg, font, align, text, format Item: Item=ChannelLogo Description: Draws a logo for the current channel (if present). The logo's filename will be the channel name, and the parameter type gives the file extension. The parameter path can give an additional subdirectory to the skin's directory. Example: Item=ChannelLogo,path=logos/,type=png,...; Parameters: x, y, width, height, fg, bg, path, type Item: Item=ChannelNumberName Description: Draws the channel number and name into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=ChannelNumber Description: Draws the channel number into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=ChannelName Description: Draws the channel name into the given area. Otherwise, see Item=Text Parameters: x, y, width, height, fg, font, align, text Item: Item=Rectangle Description: Draws a filled rectangle into the defined area. Parameters: x, y, width, height, fg Item: Item=Ellipse Description: Draws a filled ellipse or a part of an ellipse into the defined area. Parameters: x, y, width, height, fg Item: Item=Timebar Description: Draws a timebar displaying the progress of the current programme. The area will be filled with the background color (if given) and the bar will be drawn using the foreground color. If width is greater than height, the bar will be drawn horizontally, otherwise vertically. Parameters: x, y, width, height, fg, bg Item: Item=PresentTime Description: Draws the start time of the present programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=PresentTitle Description: Draws the title of the present programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=PresentShortText Description: Draws the short text (or episode name) of the present programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=FollowingTime Description: Draws the start time of the following programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=FollowingTitle Description: Draws the title of the following programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=FollowingShortText Description: Draws the short text (or episode name) of the following programme. Parameters: x, y, width, height, fg, font, align, text Item: Item=SymbolTeletext Description: Draws the specified image into the specified location if the current channel has teletext. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolAudio Description: Draws the specified image into the specified location if the current channel has multiple languages. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolDolby Description: Draws the specified image into the specified location if the current channel has ac3 sound. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolEncrypted Description: Draws the specified image into the specified location if the current channel is encrypted. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolRecording Description: Draws the specified image into the specified location if VDR is currently recording. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolRadio Description: Draws the specified image into the specified location if the current channel is a radio channel. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolPlay Description: Draws the specified image into the specified location if the current replay is playing normally. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolPause Description: Draws the specified image into the specified location if the current replay is paused. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolFastFwd Description: Draws the specified image into the specified location if the current replay is fast forwarding. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolFastRew Description: Draws the specified image into the specified location if the current replay is fast rewinding. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolSlowFwd Description: Draws the specified image into the specified location if the current replay is slow forwarding. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolSlowRew Description: Draws the specified image into the specified location if the current replay is slow rewinding. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolEventRunning Description: Draws the specified image into the specified location if the displayed event (in menu display) is currently running. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolEventTimer Description: Draws the specified image into the specified location if the displayed event (in menu display) will be recorded. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolEventVPS Description: Draws the specified image into the specified location if the displayed event (in menu display) is VPS. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolScrollUp Description: Draws the specified image into the specified location if the current display is scrollable and not at the top of its contents. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=SymbolScrollDown Description: Draws the specified image into the specified location if the current display is scrollable and not at the bottom of its contents. If that is not the case, the alternative image (if given) will be displayed. For details on the image handling, see Item=Background. Parameters: x, y, width, height, path, altpath, fg, bg Item: Item=Language Description: Draws a logo for the current language (currently the only languages VDR knows are "Audio 1" and possibly "Audio 2", regardless of the real language). For more information on how the logo is found, see Item=ChannelLogo. The logo's filename will be the language's name. Parameters: x, y, width, height, path, type, fg, bg Item: Item=Volumebar Description: Draws a volumebar into the specified area. For more details, see Item=Timebar. Parameters: x, y, width, height, fg, bg Item: Item=Mute Description: Draws a mute symbol and/or text (if given) into the specified area. See Item=Text and Item=Background for more on text and image handling. Parameters: x, y, width, height, fg, bg, text, font, align, path Item: Item=Replaybar Description: Draws a progressbar displaying the replay progress into the specified area. For more details, see Item=Timebar. Parameters: x, y, width, height, fg, bg Item: Item=ReplayTitle Description: Draws the title of the current replay. Parameters: x, y, width, height, fg, font, align, text Item: Item=ReplayCurrent Description: Draws the current time in the current replay. Parameters: x, y, width, height, fg, font, align, text Item: Item=ReplayTotal Description: Draws the total length of the current replay. Parameters: x, y, width, height, fg, font, align, text Item: Item=ReplayJump Description: Draws the "Jump:" prompt (if present) of the current replay. Parameters: x, y, width, height, fg, font, align, text Item: Item=MessageStatus Description: Draws the current status message (if present). Parameters: x, y, width, height, fg, font, align, text Item: Item=MessageInfo Description: Draws the current info message (if present). Parameters: x, y, width, height, fg, font, align, text Item: Item=MessageWarning Description: Draws the current warning message (if present). Parameters: x, y, width, height, fg, font, align, text Item: Item=MessageError Description: Draws the current error message (if present). Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuArea Description: Specifies the area in which the menu items will be shown as a list. Parameters: x, y, width, height Item: Item=MenuItem Description: Specifies how one item is drawn in the list of menu items. list. Parameters: [x,] [y,] width, height, fg, bg, font, align Item: Item=MenuCurrent Description: Specifies how the currently selected item is drawn in the list of menu items. list. Parameters: [x,] [y,] width, height, fg, bg, font, align Item: Item=MenuTitle Description: Draws the title line of the displayed menu. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuRed, Item=MenuGreen, Item=MenuYellow, Item=MenuBlue Description: Draws the red, green, yellow or blue (respectively) button. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuText Description: Draws the current menu text in a scrollable text-area. If this item is present, SymbolScrollUp and SymbolScrollDown apply, too. Parameters: x, y, width, height, fg, [bg,] font, [align,] text Item: Item=MenuEventTitle Description: Draws the title of the currently selected event when viewing EPG entries. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventShortText Description: Draws the short text or episode name of the currently selected event when viewing EPG entries. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventDescription Description: Draws the long text of the currently selected event when viewing EPG entries in a scrollable text-area. If this item is present, SymbolScrollUp and SymbolScrollDown apply, too. Parameters: x, y, width, height, fg, [bg,] font, [align,] text Item: Item=MenuEventTime Description: Draws the start time of the currently selected event when viewing EPG entries. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventEndTime Description: Draws the end time of the currently selected event when viewing EPG entries. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventVPSTime Description: Draws the vps time of the currently selected event when viewing EPG entries, if that is different from the start time. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventDate Description: Draws the date of the currently selected event when viewing EPG entries. Parameters: x, y, width, height, fg, font, align, text Item: Item=MenuEventDateTimeF Description: Draws a string expressing some details of the start time of the currently selected event when viewing EPG entries. What is to be displayed will be decided by the skin author. The paremeter "format" holds a format string according to the manpage of strftime. Parameters: x, y, width, height, fg, font, align, text, format Item: Item=MenuRecording Description: Draws the summary of the currently selected recording when browsing recordings in a scrollable text-area. If this item is present, SymbolScrollUp and SymbolScrollDown apply, too. Parameters: x, y, width, height, fg, [bg,] font, [align,] text Known Parameters ---------------- Parameter: x Description: A positive number representing the vertical offset in pixels. Default: MANDATORY Parameter: y Description: A positive number representing the horizontal offset in pixels. Default: MANDATORY Parameter: width Description: A positive number representing the width in pixels. Default: not given (sometimes mandatory) Parameter: height Description: A positive number representing the height in pixels. Default: not given (sometimes mandatory) Parameter: bpp Description: A positive number representing the depth of a background area. Possible values are 1, 2, 3, 4 and 8 mapping to 2, 4, 8, 16 and 256 colors. Default: 4 (16 colors) Parameter: fg Description: A hex quadriplet [ TODO is this word correct?! ] introduced by '#' representing a 32-bit foreground color in the order ARGB. Default: not given Example: #ff000000 Parameter: bg Description: A hex quadriplet [ TODO is this word correct?! ] introduced by '#' representing a 32-bit background color in the order ARGB. Default: not given Parameter: font Description: A string representing one of VDR's skins, possible values are 'Osd', 'Sml' and 'Fix'. Default: Osd Parameter: path Description: A string representing a path- and filename relative to the skin directory. Currently, xpm images and png files (with alphachannel support) can be loaded, but the number of different colors used in the image must not exceed those possible in the corresponding background area. Default: not given Parameter: altpath Description: A string representing a path- and filename relative to the skin directory. This is used for for displaying alternate images i.e. for symbols. For more information, see path=... Default: not given Parameter: text Description: For non-text-items (and for the item "Text" itself), this is the plain text to be displayed. For items that have it's own texts (such as "Date", "PresentTitle" etc.), this is a template that defines how the text is to be displayed. A dollar symbol '$' will be replaced by the original text. Default: not given Example: Item=ReplayCurrent,text=Current: $; would display for example "Current: 0:00:21" instead of only "0:00:21". Parameter: type Description: The string giving the file extensions for logos. Default: not given Parameter: type Description: The format string for a date/time display according to strftime. Default: "" Parameter: align Description: A number describing the text alignment. Possible values are '0' for left aligned, '1' for centered and '2' for right aligned. Default: 0