path: root/README

This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Louis Braun <louis DOT braun AT gmx DOT de>

Project's homepage:          http://projects.vdr-developer.org/projects/skin-nopacity/

Latest version available at: http://projects.vdr-developer.org/projects/skin-nopacity/files

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
See the file COPYING for more information.

Requirements
------------

- VDR version >= 1.7.34

- Installed ImageMagick for displaying png/jpg Icons, Channel Logos and EPG Images

- for scaling the video picture to fit into the VDR menu window please use 
  softhddevice plugin revision 87c1c7be (2013-01-01) or newer.

- epgsearch Git since commit ba7c6277 (2013-01-03) to correctly replace the schedules
  menu with epgsearch

- Installed libCurl and libXML2 for displaying RSS Feeds

Description
-----------

"nOpacity" is a highly customizable native true color skin for the Video Disc Recorder.

Installation 
------------

After "normal" Plugin installation you have to care about the paths for the
used Icons, the channel logos and epg images. The following paths can be set
at startup:

-i path, --iconpath=path
    Path to the icons (Default: <ResourceDirectory>/plugins/skinnopacity/icons/)

-l path, --logopath=path
    Path to the logos (Default: <ResourceDirectory>/plugins/skinnopacity/logos/)

-e path, --epgimages=path
    Path to the epgimages (Default: <CacheDirectory>/plugins/skinnopacity/epgimages/)

ResourceDirectory and CacheDirectory are taken from your VDR configuration (make.config
or vdr.pc). 

During a "make install" the Icons are automatically copied from <SkinSourceDirectory>/icons/
to the default path. Included Theme files are also copied from  <SkinSourceDirectory>/themes/
to <ConfigDirectory>/themes/ 
    
I recommend to use channel logos from https://github.com/3PO/Senderlogos
To download them just change in the directory you want to place the logos
and do a:
git clone https://github.com/3PO/Senderlogos.git logos
An update of the logos can then be done with a "git pull" just inside this
directory.

If directories for channel logos, icons or epg images are set via startup 
parameters, images are searched first in these directories. If the image
is not available, an additional search in the according default directory
will be performed.
With this it is possible to use user images and images provided by a
package maintainer or distributor in parallel.

For S2-6400 Users: Disable High Level OSD, otherwise the plugin will not be
loaded because lack of true color support

For Xine-Plugin Users: Set "Blend scaled Auto" as OSD display mode to achieve
an suitable true color OSD.

For Xineliboutput Users: Start vdr-sxfe with the --hud option enabled

Usage
-----

After installation first activate then skin in the VDR OSD menu. nOpacity scales to 
every screen resolution, but in lower resolutions than 1920 * 1080 it may be necessary
to change some default settings for dimensions and font sizes to achieve the best result
(see "setup options" below).

nOpacity respects the OSD settings for OSD top, left, width and height. If these values
are not set to top&left: 0, width&height: 100, you'll get a border around every displayed
skin element. Additionally you are able to configure an individual border for almost every
displayed skin element (channel switching, recordings, volume, audio tracks) in the 
skin setup. Only the menu uses the full screen if not configured differently in the 
OSD settings.  

As already mentioned, font sizes are customizable via the skins setup menu. The skin 
calculates the font sizes for the used screen resolution individually. The value
for the different font sizes in the setup options is always the delta to the calculated
(default) values. If you set a value for a font size of -2 for instance, the default
font size is decreased by 2, analogue the font size will be increased by setting a 
positive value.

As described in "installation", you should use a special channel logo pack with transparent
channel logos. In this logo pack all files are named only with lower case letters. 
nOpacity uses the channel name CONVERTED TO LOWER CASE LETTERS to search for an 
appropriate channel logo. With this, approximately 90% of the channel logos should work 
immediately after placing the channel logos in the correct place. So if you have to change
the name of a channel logo (may be by inserting a space or a hyphen) so that it fits to
the channel name, only use lower case letters, and not the name of the channel with upper 
and lower letters as displayed inside VDR.
Additional hint: some channels have slashes in their name (in germany nick/comedy for instance).
In this example, as a dirty hack just create a folder in your channel logo directory named 
"nick" and place an image named "comedy.png" inside this folder.

RSS Feeds
---------

nOpacity supports the display of RSS Feeds in the VDR menu and standalone. Displaying the
RSS Feed in the VDR menu is disabled per default because on slow machines it could slow down
the VDR menu. If you like, enable it in the RSS Feed setup. 
On VDR startup nOpacity tries to load the RSS config file "rssfeeds.conf" from the plugin 
config directory. In this file rss feeds can be set up per line in the following format:

[rssfeedname1]   rssfeedurl1
[rssfeedname2]   rssfeedurl2
...              ...

An example for this file is located in the plugin source directory under "conf". This file is
not automatically copied to the plugin config directory by a "make install", it has to be
copied manually, because otherwise an update of the plugin would destroy your customizations.

If no rssfeeds.conf can be located during startup, only one default rss feed ("Tagesschau") 
will be used.

Each rss feed configured in this file can be selected in the plugin setup for the values
"RSS Feed 1" to "RSS Feed 5". Per default "RSS Feed 1" points to the first feed from the
config file, "RSS Feed 2" up to "RSS Feed 5" are empty.

The standalone RSS Feed can be activated (and if active dectivated) with the svdrp command:

svdrpsend plug skinnopacity STANDALONEFEED

RSS Feed 1 is displayed at startup. If one or more of the fields "RSS Feed 2" to "RSS Feed 5" 
are activated, it can be toggled through these feeds via svdrp with the command:

svdrpsend plug skinnopacity NEXTFEED

With the command

svdrpsend plug skinnopacity NEXTMESG

you can switch to the next message in the current feed.

Just configure this commands for one of your remote control buttons to easily toggle between
the different feeds or switch to the next message inside a feed.

Themes and theme specific Icons
-------------------------------

nOpacity is fully themable. Examples for theme files with all possible color settings are
included in <SkinSourceDirectory>/themes/. As already mentioned these themes are automatically
copied during a "make install" into the VDR themes directory and can be choosed in VDRs
OSD setup menu.

Beside colors also the icons and images shown in the different menus are theme dependend. 
Icons and images are first looked up in <IconPath>/<ThemeName>/. If there is no appropriate
icon found, <IconPath>/ is used. With that it is possible to use specific icons for every
different theme.

Two types of icons are used:
    - statically named icons for standard main and setup menu entries, recording folders, 
      active timers and other menu decorations.
    - icons for plugins with a main menu entry: if a plugin has a main menu entry, the icon
      has to be named as the plugin name so that the appropriate icon will be shown in the
      main menu.


Customizing, Skin Setup Options
-------------------------------

* General Options (only non self-explanatory options are described)

- Font: Used Font, all Fonts installed on your system are shown

* VDR menu: Common Settings:

- Number of Default Menu Entries: Number of menu items for the default menu view.
- Adjust Font Size - Default Menu Item
- Adjustment of narrow menus: the narrow menus (main, schedules, channels, timers,
  setup) can either be adjusted left or right.
- Scale Video size to fit into menu window: no / yes / auto: with "auto" the video  window is resized when the detailed EPG Window is displayed in Schedules and
  Recordings menu to be completely visible.
- Header Height (% of OSD Height): Default: 7%
- Header Icon Size (Square Header Menu Icons)
- Footer Height (% of OSD Height): Default: 7%
- Rounded Corners for menu items and buttons
  - Radius of rounded corners: if rounded corners are used, radius in px.
- Fade-In Time in ms (Zero for switching off fading): Default 0, active fading
  for main menu caused sometimes trouble in some special setups. Activate on
  own risk ;)
- Menu Items Scrolling Speed
- Menu Items Scrolling Delay in s: period which menu element has to be selected
  till scrolling starts
- Adjust Font Size - Header
- Adjust Font Size - Date
- Adjust Font Size - Color Buttons: Font for color buttons
- Adjust Font Size - Messages  
- Adjust Font Size - Detail View Text: Font for detailed EPG & recordings view text
- Adjust Font Size - Detail View Header: Font for Header date/time and short text 
- Adjust Font Size - Detail View Header Large: Font for detailed EPG & recordings 
  view title

* VDR Menu: Main and Setup Menu

- Use narrow main menu: display main menu in narrow or standard style
  - Width (Percent of OSD Width): if displayed narrow, width of this menu
- Use narrow setup menu: display setup menu in narrow or standard style
  - Width (Percent of OSD Width): if displayed narrow, width of this menu
- Use menu icons
  - Icon Size (Square): if icons are used, size of the icons. Even if no icons
    are used, the height of the menu items is determinated by this value.
- Display Disk Usage: Display Disk Usage in Main Menu
  - Size (square, Percent of OSD Width)
  - Adjust Font Size - free
  - Adjust Font Size - percent
- Display Timers: Display active Tiers in Main Menu
  - Width of Timers (Percent of OSD Width)
  - Channel Logo Width (at the top of the timers displayed in main menu)
  - Channel Logo Height (at the top of the timers displayed in main menu)
  - Adjust Font Size - Header
  - Adjust Font Size - Title
- Show Timer Conflicts
- Header Logo Width: Default 104px
- Header Logo Height: Default 78px
- Adjust Font Size - Menu Items

* VDR Menu: Schedules Menu

- Use narrow menu: display menu in narrow or standard style
  - Width (Percent of OSD Width): if displayed narrow, width of this menu
- Channel Logo Width (Menu Buttons): width of channel logos shown in scheduling
  "what's on" and "what's next" menus and channels menu. 
- Channel Logo Height (Menu Buttons): height of channel logos shown in scheduling
  "what's on" and "what's next" menus and channels menu. This size determinates 
  the number of menu entries in schedules and channels menu.
- EPG Window Fade-In Time in ms (Zero for switching off fading)
- EPG Window Display Delay in s: period which schedules menu element has to be
  selected till fade in of epg window starts
- EPG Window Scroll Delay in s: period which epg window has to be opened till 
  window text starts to scroll
- Height of EPG Info Window (Percent of OSD Height): Height of text window which
  is shown for schedules menu elements
- Display Reruns in detailed EPG View: via epgsearch service
  - Number of reruns to display: Default 5
  - Use Subtitle for reruns
- Display additional EPG Pictures in detailed EPG View: if set to yes, additional
  EPG pictures will be shown at the end of the detailed EPG view. The pictures have
  to be named as eventid_number.jpg with number from 1 to 9.
  - Number of EPG pictures to display
- Detail EPG View Logo Width: Default 260px
- Detail EPG View Logo Height: Default 200px
- Detail EPG View EPG Image Width: Default 210px
- Detail EPG View EPG Image Height: Default 160px
- Detail EPG View additional EPG Image Width: Default: 525 px
- Detail EPG View additional EPG Image Height: Default: 400 px
- Adjust Font Size - Menu Item
- Adjust Font Size - Menu Item Small
- Adjust Font Size - EPG Info Window

* VDR Menu: Channels Menu

- Use narrow menu: display menu in narrow or standard style
  - Width (Percent of OSD Width): if displayed narrow, width of this menu
- Adjust Font Size - Menu Item
- Adjust Font Size - Menu Item Small

* VDR Menu: Recordings Menu

- Use narrow menu: display menu in narrow or standard style
  - Width (Percent of OSD Width): if displayed narrow, width of this menu
- Display additional EPG Pictures in detailed recording View: if set to yes, additional
  pictures will be shown at the end of the detailed recording view. All jpegs in the
  recording directory will be used.
  - Number of EPG pictures to display
- Folder Icon Size: size of the folder image used in recordings list
- Adjust Font Size - Menu Item
- Adjust Font Size - Menu Item Small
  
* Channel Switching:

- Fade-In Time in ms (Zero for switching off fading): Default 300ms
- Height of Channel Display (% of OSD Height): Default 25%
- Left & Right Border Width: Default 15px
- Bottom Border Height: Default 15px
- Channel Logo Position: left / right / do not display. If set to "do not display",
  the whole screen width is used for channel display.
  - Channel Logo Width: Default 260px
  - Channel Logo Height: Default 200px
  - Channel Logo Border: Default 15px
- Display Signal Strength & Quality: Set this to Zero if you want to disable the
  display of signal strength & quality (for instance if your dvb drivers does not
  deliver this values)
- Screen Resolution Icon Size: Default 100px
- Status Icon Size: Default 64px
- Adjust Font Size - Header: Font for Channel / Channelgroup Name
- Adjust Font Size - Date
- Adjust Font Size - EPG Text
- Adjust Font Size - EPG Infotext

* Replay:

- Fade-In Time in ms (Zero for switching off fading)
- Height of Replay Display (% of OSD Height)
- Left & Right Border Width
- Bottom Border Height
- Adjust Font Size - Header
- Adjust Font Size - Text

* Audio Tracks:

- Fade-In Time in ms (Zero for switching off fading)
- Width of Tracks Display (% of OSD Height)
- Height of Tracks Display (% of OSD Height)
- Position (0: bot. center, 1: bot. left, ... , 7: bot. right): The following 
  positions are possible, starting at bottom middle:
  0: bottom center
  1: bottom left
  2: middle left
  3: top left
  4: top middle
  5: top right
  6: middle right
  7: bottom right
- Border Top / Bottom
- Border Left / Right
- Adjust Font Size - Header
- Adjust Font Size - Buttons

* Messages:

- Fade-In Time in ms (Zero for switching off fading): Default 300ms
- Width of Message Display (% of OSD Height): Default 90%
- Height of Message Display (% of OSD Height): Default 10%
- Bottom Border Height: Default 10px
  Remark: with different sizes and a large value for the bottom border height you
  are able to achieve a positioning for the messages box analogue to the positioning 
  of the audio tracks display.
- Adjust Font Size

* Volume Display:

- Fade-In Time in ms (Zero for switching off fading): Default 300ms
- Width of Volume Display (% of OSD Height): Default 40%
- Height of Volume Display (% of OSD Height): Default 10%
- Bottom Border Height: Default 10px
  Remark: the volume display is always positioned in the center of the screen,
  with bottom border it can be moved to the top.
- Adjust Font Size

* RSS Feeds:

- Display RSS Feed
  - Height of RSS Feed Line (Percent of OSD Height): Default 5%
  - Adjust Font Size
- Height of standalone RSS Feed (Percent of OSD Height): Default 7%
- Standalone RSS Feed Position: bottom / top
- Adjust Font Size of standalone Feed
- RSS Feed 1: First feed in rssfeeds.conf
- RSS Feed 2 - 5: Optional feeds which can be selected via svdrp
- Scrolling Speed: slow / medium / fast
- Scrolling Delay in s: Default 3 s