MV: User Guide

• First Time
• Indicators
• File Overview
• View Presentation Window
• View Features Window
• Inputs Manager
• Favourite Manager
• More on MHW
• More on XMLTV
• More on Saved Enigma Cache
• Input Definitions File
• Channel Icons
• Alias Manager
• Misc Menu
• Autoscan To Fill EPG Data
• More On IMDB
• Miscellaneous (EPG Language Filter, Post download/MHW scripts)

The First Time

• To run the plugin, press the blue button on your dreambox remote (on some images it's the yellow button) and select 'MV' from the list.
• Press 1-9 to get a different view on the EPG data.
• The 'HELP button on your remote will give you info on how the controls work and tell you a lot about what exactly MV can do. There are different help screens for the graphical and list views, and for edit mode.
• The DREAM button will show the main menu.

Indicators

• H: the display has been hidden with the TV button, press any button (excepting volume control buttons) to restore MV
• U: MV has found one or more channels that it doesn't know what to do with: you should go to the alias manager menu and decide what to do with them
• D: a download is taking place
• X: one or more XMLTV files are being converted to the (faster, smaller) EPGUI format.
• M: a MHW scan is taking place
• F: MV has found one or more favourite programs which have their notify flag set. Look at the Favourites list to clear the flag (press 8 on the remote).
• E: indicates 'Edit View Geometry' mode
• C: has two meanings. Either MV is switching around channels to fill the Enigma EPG cache and MHW files with EPG data, or new EPG data is available from the Enigma cache. In the second case, the indicator will go out when any button is pressed on the remote.
• L: EPG data is being loaded
• S: EPG data (from the enigma cache) is being saved
• <: the view window is at the left of the data sample. If left cursor is pressed, new data will be loaded and the sample window shifted.
• >: the view window is at the right of the data sample. If right cursor is pressed, new data will be loaded and the sample window shifted.

File Overview

Config

This is a binary file in which MV keeps all the configuration options. I don't recommend trying to edit it by hand :-)

Details Cache

Location: configured in input menu
Default: /var/mnt/usb/mv if available, otherwise /var/tmp/mv Configured: inputs dialog

When MV reads data from all it's inputs, it can store the descriptions on external media so that memory is not filled, but descriptions can still be rapidly accessed.

Language File

This file contains most of the (non-error) textual messages which MV presents to the user. Different language files are contained in the archive, and one is selected by the user on install.

After install, MV uses the enigma GUI language setting to try and pick a file. If it cannot, it defaults to the English file (i.e. uses the filename 'lang.txt.en').

Skin File

Currently, only for loading (non-channel) MV icons into the active skin.

Icon Map

This file maps channel names in the User Bouquet to names of icons in the icons/ subdirectory. Please read the notes in the file for more details on format.

Input Definitions

Location: /var/tuxbox/config/mv/inputs.txt
Configured: location is fixed

The input definitions file defines the possible inputs which may be selected by the user in the inputs dialog. See here for more info. Edit with care!

Favourite Definitions

When MV reads in programs, it matches them against the definitions found in this file to decide if it should draw the users attention to the program.

Each line of this file is a definition of one favourite. The fields on each line are separated by a single space.

See here for a description of each field.

multiepg

A binary file used to read MHW EPG data from a transport stream.

Downloaded files

When MV downloads files, it keeps more recent ones to prevent repeated (slow) download. This is called a cache.

multiepg output

When mhwepg runs, all it's output goes here. If you're having problems with using MHW, it's worth looking here.

MV text log

Some error messages don't in principle stop you using MV, but would be annoying if they popped up all the time in a message box. MV puts those types of texts in this log file. At the time of writing, it's only certain problems with file downloads.

Post-download Script

Is run after every succesful download, with as argument the downloaded file path. It's stderr/stdout goes to /var/tmp/mv.log.

Post-MHW Script

Is run after every MHW scan, with as argument the path to the scanned data. It's output goes to /var/tmp/mv.log.

View Presentation Window

The only thing worth mentioning are 'Channel One' and 'Channel Two'. MV alternates the colours of program boxes between these two to improve readability. If you don't like the alternating effect, just set them the same.

View Features Window

• Next View: when you leave MV, the setting for Next View determines which view it will start in next time you start it up.
• Empty Channels: when checked, all channels from the User Bouquet will be shown in this view, even when they have no EPG data. This is useful to allow browsing of the bouquet (especially in conjunction with the VIDEO key) and for use with the 'single channel scan'.
• Force Cursor: when not not checked the cursor will jump over channels when it cannot find a program to focus on.
• Start Channel: Playing indicates that when the plugin starts up it will try and center the view on the playing channel. Top indicates that the plugin will start with the first channel of the user-bouquet.
• H. Sep, V. Sep: whether to include horizontal and/or vertical separators between programs.
• Sat. Pos. whether to include the satellite orbital position in channel headers.
• Elapsed Bar: the elapsed bar appears above programs showing what proportion of a program is finished and what proportion is remaining.
• Centre Title: (program box options): whether to centre the title of the program in the program box. NOTE: this will slow down display time fractionally.

Inputs Manager

Pre and Post: indicate the amount of seconds into the past and future that MV will read data into memory for. Lowering these values will result in lower memory usage by the plugin, but you will not be able to browse so far into the past/future.

There are three 'windows' to consider.
(a) <----------------------------->
(b)   <--------->
(c)      <---->

Firstly, (a) is the period for which data is available, which may be several days. When MV starts up, it loads in an amount of data (b). The reason it doesn't load in all data is to reduce memory requirements and increase speed. When you use the daybar, you're moving window (b) around within window (a). When you change the Pre and Post figures, you change the size of window (b). When you use the cursor keys to scroll around, you're moving the visible window (c) within the loaded data (b).

Storage Dir: this is the base directory in which MV stores all data it collects. It should preferably not in flash memory, to save space.

Tmp Detail Store: MV keeps a special cache of all descriptions it sees. It's location can be separately configured because e.g. if you include the program descriptions in the program box access will be faster if the Tmp Detail Store is in flash memory.

Auto Dirs: the first time MV runs it tries to set sensible values for the two directories above, dependent on the user's system. If Auto is checked, it will do the same every time it starts up. The principle usable of this is for image makers so that they can provide a tailored config for MV, without making assumptions about the user's storage options.
I recommend disabling this option once you have decided on your storage location.

Max Channels: indicates the number of channels which will be accepted from each inputs. The main purpose of this is to stop you crashing your dreambox by accidentally reading in thousands of programs from the 'All services' bouquet e.g. on Astra 19.2.

Auto Update: when new data is available as a result of the Enigma cache signalling, automatically reload all data (same as 0 button on remote), the current view is not a list view.

Note: auto-reload does not occur for MHW or download completion because:

• most times the new data is in the future
• if you have a very fast internet connection and download EPG data, you may get a flicker as MV starts up, download completes, and the screen is redrawn with the new data

Important:

• if a source is downloaded, or read via MHW, the data will not be immediately visible in MV. You should see the 'D' or 'M' indicator light up when data is read. Once it goes out, you need to press '0' or the daybar to see the new data.
• most extra sources you add will name their channels slightly differently than your user-bouquet, so you will probably need to go to the alias manager to map the channel names.

An exception to the Post value is view 6. On this view, all enigma cache data is always displayed, in addition to data read from any other source.

Favourites Manager

This shows a list of defined favourites. When editing or creating favourites, the edit window shows:

• Title Strings
  comma-separated list of substrings to match against program titles that are read in. Notes:
  
  • the match is case-insensitive (hello will match hello or Hello) and uses substrings: (hell will match hello and hellfire).
  • the order of the title strings is only important when 'All, In Order' is selected for Title Boolean.
• Title Boolean
  
  • Any Of (0): one of the title strings must match
  • All Of (1): all of the title strings must be found somewhere in the program's title
  • All, In Order(2): all of the title strings must be found in the programs title in the order that they occur in the title strings (though they may be separated by other text).
  • None Of (3): none of the title strings must be present in the programs's title
• Descr Strings
  comma separated list of strings to match against program descripions that are read in.
• Descr Boolean
  as for Title Boolean
• Channel Words
  comma separated list of strings to match against the channel a program is showing on. The program's channel name must match one of the channel words.
• Hours
  two hours-of-the-day between which, or not between which, the program must occur.
• Time Specifier
  
  • Between (0): the program must start between the hours specified
  • Outside of (1): the program should not start between the hours specified
• Notify Flag
  Whether the indicator should be shown when this program is found.

You can also create new favourite definitions by pressing SHIFT-GREEN when a program is selected with the cursor or in a list view.

More About MHW and OTV

If you want to use MV to read MHW data, here's a from-the-start tuturial.

Following is the more advanced stuff.

If you wish to read MHW EPG data for use with MV, do the following:

• Make sure you have mhwepg installed on your dreambox. This is the third-party binary that can actually read the data into a file. It must be in /bin or /var/bin. You can find it here: http://www.tech-sources.com/~download/pli/mv/mhwepg (many thanks to PLi).
• Select one of the MHW entries in the input menu. If you can't find an entry for your situation, you'll need to add en entry to the input definitions file.
• Switch to a channel carrying MHW data, either before or after entering MV. If the Transport Stream ID matches the one in the Input Definitions file, mhwepg will be activated to read the data, and again when the file gets older than the 'days' field in the Input Definitions file.

You can run multiepg 'manually' (i.e. before the inputs.txt file dictates that it needs refreshing) by pressing TV on the current channel, or after marking a channel with the cursor.

If you are having problems with mhwepg, you can see the output that it produces in /var/tmp/mhwepg.out.

More On XMLTV

Because of the large size and inefficiency of XMLTV files, all XMLTV files are converted to EPGUI automatically (in the background) the first time they are encountered. HOWEVER: this is not a solution for enormous XMLTV files because the whole XMLTV file has to be read into memory to parse it before conversion can take place, so the dream box will probably crash.

Self-generated

Once you have a file, you need to setup a regular job to copy the data to your dreambox (probably via FTP). Place the data in STORAGEDIR/myxmltv/tv.xmltv. (you can set STORAGEDIR in the Input Menu).

Now go to the Input Menu (press the DREAM button on the remote), add another input by checking one of the checkbox on the left, then select MyXMLTV as an input with the selector next to the checkbox.

If the file is encoded with latin text, you need to change the inputs.txt file, see below.

From a Server

Here's an example if you want to grab an XMLTV file from a server, and the file has a fixed name:

MYTVsource x l f 0 mydir 3 mydata .xmltv http://theserver.com/datadir

'x' means the data is XMLTV format. 'l' means the character encoding of the file is latin. 'f' means the file has a fixed name, in this case 'mydata.xmltv'. The 0 means that the times in the files are GMT (zero offset). The file will be grabbed from http://theserver.com/datadir/mydata.xmltv and placed in STORAGEDIR/mydir/mydata.xmltv for reading. Once the file in STORAGEDIR/mydir/mydata.xmmltv is more than 3 days old, it will be pulled from the server again. STORAGEDIR is configured in the inputs menu.

Have a look in the default file created by MV for some more examples: /var/tuxbox/config/mv/inputs.txt.

More On Saved Enigma Cache

While the cache is being saved, the 'S' indicator will light up.

Input Definitions File

• Name: the name which will appear for selection in the input menu
• Format: the format of the source.
  • c: cache: this source is the Dreambox's own EPG data store
  • s: cache: this source is a saved copy of the Enigma EPG cache from the last time MV exited.
  • e:: EPGUI: this source is one of more files containing data in Luca Spallared's EPGUI format
  • x:: XMLTV: this source is one or more files containing data in XMLTV format.
• Encoding: the character encoding of program titles and descriptions.
  • u: UTF
  • l: Latin1
• Type:
  • f: fixed: the source always has the same name
  • r: rotating: the source's name is PREFIX-DATE-AFFIX. For example, is the prefix is 'tv-' and the affix is '.xmltv' then data for 20040303 is stored in a file named tv-20040303.xmltv.
  This field has no effect on inputs of format 'c' or 's'.
• Offset To GMT: how many hours to subtract or add to the times in the file to get to GMT. From there, MV converts the times to localtime. XMLTV times already have the offset to GMT specified, so this value is usually 0 for those. This field has no effect on inputs of 'c' (enigma cache), the calculation is done automatically. For inputs of format 's' (saved enigma cache), this field indicates the elapsed time in seconds between refreshes of the the saved cache file.
• LocalDir: the subdirectory of the storage dir (configured in the inputs menu) where the data file is to be stored on the dreambox
• Days:
  • For a remote rotating (see above) source: the number of days ahead MV should download data for
  • For a TSID (see below) source: the maximum age of the data file before MV should refresh at.
  • For a saved Enigma EPG cache source: the number of days ahead of data to save to file
• Prefix: what the start of filenames should look like
• Affix: what the end of filenames should look like
• RemoteLocation: if MV should retrieve data itself, the location should be specified here. The first 5 characters of the RemoteLocation indicate where the data should be obtained.
  • http: the data should be downloaded from the given URL. Note: this must be the URL of a directory (not a file) containing files matching the specification earlier in the inputs line
  • tsid: the rest of this location is a comma-separated list of Transport Stream IDs for which MHW data is transmitted. When MV is used on a channel matching one of the TSIDs, it will use multiepg to try and take EPG data from the DVB stream.
  Has no effect with inputs of type 'c' or 's'.

Channel Icons

• Channel icons can be enabled in the feature menu, on a per-view basis.
• The icons must be installed in /var/tuxbox/config/mv/icons/ (it can be a symlink, though this may slow down loading).
• There is an XML file in /var/tuxbox/config/mv/icons.esml which maps channel names to icon names.
• To turn off all icons, just don't install the images or the icons.esml file.
• Be careful not to delete icons named mv.xxx.png, they're used for other things in MV.
• By selecting only the icons for channels which are in your bouquet, you can speed up loading times.
• Many entries are commented out of icons.esml, just because I don't view those channels so they don't interest me. Have a look there before you start hunting the web for PNGs :-)
• If you wish to add your own icons, just copy them to the icons directory, add one or more entries in icons.esml and restart your dreambox. Important: the icons must be PNGs and in most cases you will need to convert the files using either pngquant (recommended):

  pngquant 64 src.png

  or the ImageMagick 'convert' program:

  convert SRCFILE -type Palette +matte TARGETFILE.png

• Please feel free to send me more icons (sized between 32x32 and 40x40) and User Bouquet names they correspond to. PLEASE TEST THEM FIRST, you want me to be adding great new features to MV, not messing around with images, right ?
• you can find some more icons in icons/unused in the tar.gz file. There are some websites with icon packs too (e.g. samurize.com).

Alias Manager

The list of channels on the right are the channels from your current UserBouquet, plus the special entries 'UNKNOWN' and 'IGNORE'.

When you enter the window, on the left are channels which MV has found which it doesn't know what to do with. If you press OK, you can select what MV should do next time it reads the channel name (from any source).

• IGNORE: ignore all data from this channel
• A channel name: take data from the channel name on the left as being data for the selected channel name on the right
• UNKNOWN: return a previously selected or IGNORED channel to the UNKNOWN list.

You should IGNORE all channels you're not interested in as this will improve startup times.

The buttons on this screen select which type of channels are displayed on the left (unknown, ignored or mapped). Green exits.

Misc Menu

• The Timer Start Offset is subtracted from the program start time when a recording is set
• The Timer End Offset is added to the program end time when a recording is set
• The View Offset is the time (seconds) within the sample window that the view window starts at. e.g. if 'Pre' in the Input Menu is set to 3600 and the View Offset is set to 1800, the user can scroll an hour back into the past (-3600) and the plugin starts up with the left hand side of the window half an hour into the past (-3600 + 1800 = -1800).
• The Aspect Ratio selector is only relevant if your enigma Aspect Ratio setting is '16:9'. It allows you to ensure, that MV always starts up with the same aspect ratio, independent of the aspect ratio of the current broadcast.

More On IMDB

If there is a single match returned, the details will be displayed.

If there is more than one match, a list of the possibilites will be displayed. Press OK to select one and see the extra film data.

The server is maintained by Bjorn Hijmans, many thanks to him for that.

Autoscan To Fill EPG Data

• it is efficient:
  • only channels with data for one or less programs are included
  • the minimal necessary number of channels are visited, taking into account that program data for all channels on a Transport Stream can be acquired all at once
  • the minimal amount of satellite switching is done.
  • the scan moves onto the next channel as soon as Enigma indicates it has acquired data or the multiepg binary exits.
• the EPG can be used while the scan is in progress. Pressing '0' will load any extra data gathered so far.
• the plugin will return to the originally playing channel when the scan is complete (unless it is interrupted).
• TV will scan the playing channel, or the channel under the cursor if there is one
• RADIO will scan only bouquet-channels on the current satellite. A one-channel scan will also always fill MHW data, if it's a configure MHW channel, even if the refresh time on the data file has not yet expired.
• TEXT will also switch between satellites to acquire the necessary data
• you can exit the plugin while the scan is in progress (unless an MHW scan is taking place)
• you can stop the scan at any time with the TV, RADIO or TEXT buttons; the plugin will return to playing the original channel from before the scan started (unless an MHW scan is taking place)
• the 'C' indicator at the top of the screen indicates when a scan is in progress.

Miscellaneous

• EPG Language Filter
  [currently only enigma cache]
  When reading program titles and desciptions, MV will look for text based on the OSD (On Screen Display) language which the user has configured. If it finds such text, it will use only that text. If it doesn't find such text, it will use all text it has found. As a practical example, if your OSD language is Norwegian, MV will show you only the Norwegian text for any Kiosk EPG data it has from the Enigma EPG Cache.