MythTV-indicator

From MythTV Official Wiki
Jump to: navigation, search


Author R.D. Vaughan - As of Jan 2nd, 2015 this code will no longer be supported by the original developer (R.D. Vaughan). Anyone interested in picking up support is welcome. All code is in python so can be easily added to your development environment.
Description MythTV-Indicator is a Gnome 3 and Unity panel indicator supplying Recording, Scheduled program and Job Queue information.
This indicator has been successfully tested on the following Debian distributions supporting Gnome 3:
Ubuntu 11.04 and higher
Ubuntu Gnome Shell Remix 12.04 and higher
Debian 7 "Wheezy" Gnome 3 desktop and higher
Linux Mint 13 "Maya" - Cinnamon Edition desktop and higher
A package for Arch Linux has been created
Supports Version24.png  Version25.png  Version26.png Version27.png 


Features

  • Supports MythTV version 0.24 and higher
  • Auto configuration attempts to detect your MythTV backend version and configures the indicator accordingly
  • Gnome 3 and Unity panel icons indicating MythTV's state:
    • Recording with a HH:MM counting down until the recording ends
    • Idle (Nothing is being recorded)
    • The MythTV backend is unavailable
    • Job Queue status
  • Preferences GUI pop-up allows you to change the default settings
  • Four alternate themes for the metadata details pop-up
    • Three different theme sizes all include artwork (when available)
    • A text only theme that displays program meta data
  • Notifications
    • When a recording starts or stops
    • When the MythTV backend is started or stopped
    • When a Job is queued, starts, completes or fails
  • If you have MythTV v0.25 or higher installed, no other components of MythTV needs be installed on your client machine as the Service API's provide all required access to your Backend server
  • A Launchpad PPA for easy installation, updates and clean removal. The PPA includes both 32 and 64bit for Debian based distributions supporting Gnome 3 and Unity desktops
  • An option to include MiroBridge downloaded videos with notifications and a metadata details pop-up
  • An option to start the MythTV Frontend from the indicator's drop down menu

Prerequisites

  • A debian based Gnome 3 or Unity desktop (see tested distributions at the top of this wiki page)
  • The MythTV-Indicator PPA added as a 3rd party application source. See: Adding the PPA and Indicator install
  • If a theme with artwork is chosen then the artwork must already exist on your MythTV Backend server
  • When used with MythTV v0.24 the MythTV python bindings must be installed on the PC running the indicator

Installation

Adding the PPA and Indicator install

The MythTV Indicator Launchpad PPA is located at PPA UPDATE: As of Sept, 19th, 2014 the PPA debs for Ubuntu 14.04 and experimental 14.10 have been added.

To add the MythTV Indicator PPA as a 3rd Party source and install the Indicator, type the following in a terminal session. You will need root access:

sudo add-apt-repository ppa:r-d-vaughan/mythtv-indicator
sudo apt-get update
sudo apt-get install mythtv-indicator

Specifically for Debian 7 "Wheezy" add the MythTV Indicator PPA as a 3rd Party source and install the Indicator, by typing the following in a terminal session. You will need root access:

su root
echo "deb http://ppa.launchpad.net/r-d-vaughan/mythtv-indicator/ubuntu precise main #MythTV-indicator" >> /etc/apt/sources.list
echo "deb-src http://ppa.launchpad.net/r-d-vaughan/mythtv-indicator/ubuntu precise main #MythTV-indicator Source" >> /etc/apt/sources.list
gpg --keyserver keyserver.ubuntu.com --recv-key FEB573EB54BB4483
gpg -a --export FEB573EB54BB4483 | apt-key add -
apt-get update
apt-get install mythtv-indicator
exit

Launching the Indicator

On a Gnome 3 desktop launch the indicator by clicking the Gnome menu "Accessories->MythTV-Indicator".

On the Unity desktop launch the indicator by pressing the "Home"/Super key and the Unity Dash search will appear. Type "mythtv-indicator" as your search text then click on the MythTV Indicator icon.

Alternately, in a terminal session type the following and press enter:

mythtv-indicator

Note: Ubuntu 11.04 users can safely ignore the message: Gtk-Message: Failed to load module "canberra-gtk-module"

The first time the indicator is started it will attempt to auto configure itself. This can take several seconds (less then a minute). If the auto configuration was successful an icon will be added to your Gnome 3 or Unity panel. If not successful the MythTV backend down icon will appear and a notification message saying that you need to manually configure through the "Preferences" pop-up.

If the auto configuration process failed the Preferences pop-up "General Settings" tab contains a dialogue that allows you to select your MythTV version and test your settings. See Preferences.

To have the Indicator started at logon time, click the "Auto start indicator" check box on the "General Options" tab in the Preferences pop-up then click the "OK" button.

Channel Icons

If you have MythTV v0.25 or higher installed, your channel icons will be displayed in notifications and the metadata details pop-up as long as you have icons associated with your channels. See: Channel Icons

If you are using MythTV v0.24 follow these (optional) steps to have your channel icons displayed in notifications and the metadata details pop-up.

  • On your Master backend put all your channel icon image files in a single directory
  • Using "mythtv-setup" application, create a new storage group called "Channels" and enter the full directory path to the channel icons directory
  • Each Channel needs to be associated with an icon image file (normal MythTV Channel/icon configuration; see: Channel Icons)

Preferences

In most cases you would only need to use Preferences to turn on the "Auto start indicator" option. Your preference changes will only be saved if you click the "OK" button. When the "OK" button is clicked a small delay may occur before the pop-up window disappears.

Preferences pop-up with the Gtk+3 Blapple theme

General Options tab

Auto start indicator

When checked the Indicator will be automatically started at logon time. Default: No Auto start.

Selecting your MythTV version

You must have a MythTV Backend running v0.24 or higher and accessible locally or over your network. Check the appropriate MythTV version.

Hostname or IP Address and Status Port

These entry fields are only available when MythTV v0.25 or higher is checked. Their values must match your Master Backend settings in the "mythtv-settings" program. Settings are located in General->Host Address Backend Setup. Look for "Local Backend" the IP address and Status port settings.

Alternately you can click the "Find compatible Backend settings" button to attempt to auto configure the proper settings. A message dialogue will be displayed indicating success or failure. If successful the IP address and status port fields will be populated. The attempt to find your backend settings can take several seconds (less then a minute).

Test Settings

When the "Test Settings" button is clicked your settings will be checked to see if a MythTV backend connection can be established. A message dialogue will be displayed indicating success or failure.

Find compatible Backend settings

When the "Find compatible Backend settings" button is clicked a series of tests are performed to see if a compatible MythTV Backend can be found. The first successful connection will be used. The Backend connection attempts are performed in this order:

  • Use SSDP to discovery a UPnP MythTV backend server on the local network (MythTV 0.25 and higher)
  • A connection attempt to a UPnP MythTV backend server using the defaults "localhost" and port "6544" settings (MythTV 0.25 and higher)
  • Check if the MythTV python bindings are installed, configured and can connect to a MythTV Backend (MythTV 0.24+fixes)

Note: The timeout for the MythTV 0.25 backends connection attempts are a maximum of 10 seconds each.

If a compatible MythTV Backend is found then the appropriate settings are initialized and a success pop-up is displayed.

Select icon theme

This setting specifies the panel icon display.

Example Theme name Comment
Mi icon hhmm.jpg Icon and count down (HH:MM) until recording ends The count down only appears when MythTV is recording
Mi icon only.jpg Icon only

Menu Options tab

When checked the "Include a MythTV Frontend launch button in the Menu" option adds the menu item "Launch Frontend" to the indicator's dropdown menu. When clicked the menu item will use the values in "Script Location" and "Script arguments" to launch the MythTV Frontend. You need the MythTV Frontend installed locally for this menu item to work.

Use the "Test Frontend Launch Settings" button to test whether your "Script Location" and "Script arguments" values work as expected.

When checked the "Include results from a command line in the menu..." option adds the STDOUT results from executing "Script Location" with "Script arguments" as a menu item. The results will be truncated if greater than 40 characters.
The "Script Location" value can be any executable that returns text to STDOUT. If the "Script Location" value has a ".log" or ".txt" extension the contents of that file is read and displayed in the menu item.

This setting allows you to save desktop panel space while providing quick access to a limited amount of information. For example the indicator's author uses this option to display daily bandwidth usage statistics from a personal script that returns text to STDOUT formatted as "Cap: 4.12GB 10.1%".

If checked this option will be executed every 60 seconds.

Use the "Test Command Line Settings" button to test whether your "Script Location" with "Script arguments" values work as expected. The script results will be displayed in a dialogue box as it would appear on the indicator menu or error results if the script failed.

When checked the "Include Job Queue Details launch button in the Menu" option adds the menu item "JobQ: Q-#, R-#, C-#, F-#". The "#" displays the number of "Q"ueued, "R"unning, "C"ompleted and "F"ailed jobs. E.g. "JobQ: Q-0, R-2, C-4, F-1". By default this option is enabled.

Job Queue panel icons

When the "Include Job Queue Details launch button in the Menu" option is checked the following icons will display on the panel when there is job queue activity.

Example Indicates Comment
Mi icon failed.jpg A job has failed Click on the Job Queue menu item to see details about the failed job. By doing this the failed icon will also be turned off.
Mi icon failed recording.jpg A job has failed and MythTV is recording. Click on the Job Queue menu item to see details about the failed job. By doing this the failed icon will also be turned off.
Mi icon started.jpg A job has started Click on the Job Queue menu item to see details about the started job.
Mi icon started recording.jpg A job has started and MythTV is recording. Click on the Job Queue menu item to see details about the started job.
Mi icon queued.jpg A job has been queued Click on the Job Queue menu item to see details about the queued job.
Mi icon queued recording.jpg A job has been queued and MythTV is recording. Click on the Job Queue menu item to see details about the queued job.

Artwork tab

When the "Display Artwork in the Details pop-up (when available)" option is checked the metadata details pop-up will include artwork. If not checked no cover, fan art or channel icons will be included with the metadata details pop-up window. The default configuration is artwork enabled with a medium theme.

When the Display artwork option is checked one of three sizes themes can be selected. The cover art examples shows the relative sizes of the themes. Click any one of the radio buttons to select a specific theme size.

Metadata Details pop-up window sizes Width x Height:

No artwork 546x232px Small 650x342px Medium 982x488px Large 1229x591px
No artwork theme
Small theme
Medium theme
Large theme

Notifications tab

When checked a notification will be displayed when the described event occurs.
Default: All notification are enabled except Job Finishes and Queued.

  • A Recording Starts
  • A Recording Ends
  • The MythTV Backend starts or stops
  • When a Job Fails
  • When a Job Starts
  • When a Job Finishes
  • When a Job is Queued
Notification example

Details Pop-up tab

Specify the number of hours of Scheduled recordings that will be included in the metadata Details pop-up. Default: Next 48 hours of Scheduled recordings.

Miro tab

If you have MiroBridge and Miro installed on your MythTV backend you can include notifications and detail pop-ups of Miro videos.

  • Check "Include a Miro video Details pop-up launch button in the Menu" to add the menu item.
    • Limit the number of Miro videos that will be displayed in the metadata details pop-up. The most recent downloaded videos are displayed first. This field is only enabled if the Miro menu item is checked. Default: 99 (all).
    • Check "Display Notifications when new Miro videos are download" will enable notifications to be displayed when a new Miro video has been downloaded by MiroBridge. This field is only enabled if the Miro menu item is checked.

Metatdata Details Pop-Up

Clicking on the indicator's menu items "Recording", "Next", "Miro" or "All Details", will display a metadata Details pop-up in the theme style specified in the Preferences Artwork tab. One program's worth of metadata is displayed at a time. To view each of the program details use the following keystrokes or the mouse scroll wheel per the chart below.

Action Result
Scroll Wheel down Display next program
Scroll Wheel back Display previous program
Press PgDn key Display next program
Press PgUp key Display previous program
Press Right arrow key Display next program
Press Left arrow key Display previous program
Press Down arrow key Display next program
Press Up arrow key Display previous program
Press Esc key Exit the metadata Details pop-up

Job Queue Details Pop-Up

Clicking on the indicator's menu item "JobQ: Q-#, R-#, C-#, F-#", will display a Job Queue Details pop-up in a scrollable list containing all Job Queue entries. The list is ordered with the most recent jobs first but within a subcategory of "Failed", "Started", "Completed" and "Queued". This display supports the following keystrokes or the mouse scroll wheel.

Action Result
Scroll Wheel down Scroll down the job queue list
Scroll Wheel back Scroll up the job queue list
Press PgDn key Page down the job queue list
Press PgUp key Page up the job queue list
Press Esc key Exit the Job Queue Details pop-up

Gtk+3 Desktop Theme

With Ubuntu 11.04 the MythTV Indicator metadata Details pop-up will use the default Gtk+3 theme unless an alternate is installed. Your Gtk+2 desktop theme will be ignored as the indicator is developed using Gtk+3.
A number of Gtk+3 themes can be found at GNOME-LOOK.ORG. Most to these themes include both Gtk+2 and Gtk+3 themes so your desktop will be consistent across Gtk+2 and Gtk+3 applications. After installing and selecting the new theme you may need to reboot/logout before it can be seen.

On Gnome3 or Ubuntu 11.10 and higher Unity desktops, Gtk+3 themes are already installed. The indicator will use whatever theme is selected for the desktop.
You can find additional Gnome 3 themes at Softpedia Themes.
Follow these instructions to add and change Desktop themes in Ubuntu 11.10. How to Install GNOME Themes in Ubuntu 11.10.

Indicator Created Directories

The indicator will always create a "~/.mythtv/mythtv-indicator" directory to store a log, cached data and image files. The log is recreated with each reboot managed by the indicator itself. The data and image file cache is maintained automatically including removal of redundant image files and data.
The following files/directories all reside in "~/.mythtv/mythtv-indicator"

File name Comments
indicator.log Log for information and critical messages. Valuable for troubleshooting. Log re-created with each reboot.
cache/settings.pickle Contains a copy of the Indicator preference settings. The list is refreshed when the Indicator starts and when preferences are changed. The persistent settings are stored as a dconf scheme.
cache/coverart_dirlist.pickle Contains a list of all the image files found in the Coverart storage group. The list is refreshed once every hour and when preferences are changed.
cache/fanart_dirlist.pickle Contains a list of all the image files found in the Fanart storage group. The list is refreshed once every hour and when preferences are changed.
cache/details.pickle Contains the metadata details of Recording, Scheduled and Miro videos. The data is refreshed once every 60 seconds and when preferences are changed.
cache/menu.pickle Contains the details displayed in the indicator menu and notifications. The data is refreshed once every 60 seconds and when preferences are changed.
cache/jobqueue.pickle Contains the Job Queue details displayed in the indicator menu and notifications. The data is refreshed once every 60 seconds and when preferences are changed.
cache/images Is a cache directory containing Channel icons and artwork image files. The image files are added or removed as required once every 60 seconds and when preferences are changed.

Troubleshooting

  • Check the "~/.mythtv/mythtv-indicator/indicator.log" for any messages that may help in analyzing an issue
  • If auto configuration did not find a MythTV master backend server:
    • For a MythTV v0.24 installation you can verify that the python bindings are properly installed on the PC where the Indicator is installed by typing "mythpython --version" in a terminal session then hit enter.
      The response should include something like:
      "bindings version: 0.24.X.X".
    • For a MythTV v0.25 or higher installation:
      • If your Backend is started at boot time, sometimes it cannot be detected. Apparently the network was not ready when the Backend was making itself know as a UPnP server. A simple Backend stop and restart will allow auto configuration to work. ONLY auto configuration is effected by this situation. Once configured the indicator will work properly even if the Backend is not known as a UPnP server.
      • You can verify if the Service API's are working with a Web browser and the URL (replace "master_backends_IP_address" with your backend's IP address):
        "http://master_backends_IP_address:6544/Myth/GetHostName"
        A successful response should be XML, for example: "<QString>mythtv-Master</QString>"
  • NOTE: Ubuntu 11.04 users that start the indicator in a terminal session can safely ignore this message:
    Gtk-Message: Failed to load module "canberra-gtk-module"

Known Issues

  • In Ubuntu 11.10 and 12.04 the Indicator works with the Gnome3 Classic and Classic (no effects) desktops but the panel icons display as a broken image. The rest of the indicator's functionality works as expected. This is why those desktops are not included in the supported version list.
  • The GTK+3 themes HighContrast, HighContrastInverse, LowContrast and Oceanic Dark all show overlapping text when navigating in the Details pop-up window

Removing the Indicator

  • If you wish to completely remove all traces of the MythTV Indicator perform the following steps:
    • In preferences uncheck the "Auto start indicator" and click "OK". This will remove the "~/.config/autostart/mythtv-indicator-autostart.desktop" file.
    • From a terminal session type:
      sudo apt-get purge mythtv-indicator
    • From a terminal session type:
      rm -r ~/.mythtv/mythtv-indicator
    • Remove the mythtv-indicator PPA from your 3rd party source list

Reporting Bugs

You can post questions on the MythTV user mailing list or report MythTV-Indicator bugs at MythTV-Indicator Bug tracking

Translations

If you wish to translate the MythTV-Indicator into other languages, please visit the MythTV-Indicator Translations for further instructions. Your submission will be added to the PPA's debs.

Porting to a non-Debian distro

UPDATE:Arch Linux has a port

If you want to port the indicator to a non-Debian distributions the source is available at Launchpad code. The dependancies are defined by Debian so their names may be different in your distro. There may be additional dependancies that are part of base Ubuntu 11.04 and higher install that are not included in this list:

  • python (>= 2.7)
  • Gtk+ 3 python libraries
  • python-support (>= 0.90.0)
  • gir1.2-gtk-3.0
  • gir1.2-gdkpixbuf-2.0
  • gir1.2-appindicator3-0.1
  • gir1.2-notify-0.7
  • python-lxml
  • python-simplejson
  • python-dateutil
  • python-imaging

I have tried to see if this indicator will work with a Fedora 17 Gnome 3 desktop but currently cannot find all the RPM dependancies. Specifically for "gir1.2-appindicator3-0.1" and "gir1.2-notify-0.7".

Credits

  • Douglas Peale for inspiration from his Gnome2 MythTV panel applet Mythstatus.py
  • Lorenzo Carbonell for his My Weather Indicator which the MythTV Indicator is directly modelled after. Reviewing Lorenzo's indicator code substantially reduced development time.
  • Robert McNamara for making me aware of the powerful MythTV Service APIs and for putting up with my requests for additional Service APIs.
  • Raymond Wagner for developing the Python bindings including adding new bindings when requested. Also for putting up with my questions on how to use the python bindings to their best effect.