Difference between revisions of "Channel Editor"

Revision as of 16:37, 27 March 2017

Introduction

This page describes version 2 of a screen based MythTV Channel editor.

It is a perl script using the API interface which will allow channel data to be easily displayed, sorted and changed. It can be run on the backend or from another computer with access to the backend.

A tutorial is included for user familiarisation.

Version 2 was developed following extensive user feedback from version one. Not only has functionality been increased but the user interface has been improved.

What does it do?

It will:

- Extract channel data for all sources from a backend.

- Display channel data - ChannelId, Channel number, source, multiplex, CallSign and XMLTVID as well as the visible, CommFree and EIT flags. A further parameter can be extracted, shown and modified.

- Allow channels to be sorted in various ways.

- Allow the columns of data to be selected for display.

- Allow channels to be edited, either singly or in bulk.

- All changes are held in memory - it needs a specific database update instruction before the backend is changed.

- Allow 'Undo' for changes.

- Export the state of channels to a file for re-import so the same settings can be re-applied after a later rescan.

- Allow import of XMLTVID data from UK Altas, Radio Times (both now in question!) or Schedules Direct files.

- Allow running in demo mode with no changes to the database.

- Allow 'spoofing' with alien data from a file rather than reading the backend. This was developed as a support tool but also supports the tutorial below.

The script uses the MythTV API interface and has been tested with both 0.27 and 0.28-pre with UK DVB-T and DVB-S data and with US cable and 'over the air' ATSC data. All tests have been in a Linux environment, though there are successful reports of use with OSX.

Before trying it with your own precious database you will probably wish to try it out with artificial data and a safe step by step tutorial. This shows the features of the editor with a subset of data 'pruned' and modified from a UK system. It will not interact with your database!

Setup

A suggested setup for channel editor is:

Create a fresh directory to hold the files:

 mkdir chedit
 cd chedit

you will need three files;

• chedit2.pl the perl script.

• scan_database.pm the API interfacing module

• tutorial.diags if you wish to run the tutorial below.

Note that the suffixes for the code files are .pl and .pm respectively.

The module scan_database.pm is fully described in Perl_API_examples and can be placed anywhere in the perl 'path' though all files placed in one directory should work. If necessary, the path can be listed with:

perl -e 'print join ("\n", @INC), "\n"'

The three files can be found on github: https://github.com/PBrady43/Channel-Editor

You can either extract these using git (if familiar) or copy and paste then into your favoured editor (hint: Use 'raw' before copy).

Please check that the very first lines of chedit2.pl and of scan_database.pm are:

   #!/usr/bin/perl -w

chedit2.pl will need to be executable.

chmod +x chedit2.pl

scan_database.pm only needs read permissions.

You may also need to install perl-tk and libwww-perl. In a Ubuntu environment:

sudo apt-get install perl-tk
sudo apt-get install libwww-perl

If not running in a Linux environment please note the comments below.

Command line options

chedit2.pl has command-line options as follows:

--backend specify backend address:port number (but it may well find that itself!)

--demo The editor is run in demonstration mode. The backend will not be changed, even if the update option is selected. --demo is default

--nodemo Run in 'live' mode - database WILL be changed if update option is chosen. --demo is default

--spoof <filename> reads data from <filename> rather than your backend. A support option and enables the tutorial.

--extra <parameter> specifies an additional field to extract from the database for display and editing.

Viewing data

Keyboard input

With all screens, the view can be modified with keystrokes.

Cursor down:         down one line
Cursor up:           up one line

Shift+cursor down:   down 10 lines
Shift+cursor up:     up 10 lines

Page down:           next page
Page up:             previous page

Shift+Page down:     down 10 pages
Shift+Page up        up 10 pages

Home:                show start of data
End:                 show end of data

+                    bigger font
-                    smaller font
b                    toggle bold/normal font

Prior to version 2.09 (4 March 2017) scrolling was achieved with a scroll bar on the right.

Default Columns

The default channel view displays columns:

Row number for referencing purposes
Channel Id - the database reference in MythTV
Channel Number
Source and multiplex.
FrequencyId
A set of flags which are:
  D channel will be deleted
  V channel visible
  E  UseEIT flag
  C  Commflag
  d  duplicated callsign or channel number (if visible)
  Q  there is a match query following an import
  U  last change can be undone
  M  this channel has been modified.
CallSign
XMLTVID

ChannelName view

This shows ChannelName instead of XMLTVID

Extra View

If the --extra parameter is specified, an additional menu item is shown. It provides a column setup which replaces XMLTVID with the values of the --extra parameter.

Custom Columns

If the items do not fit comfortably on the screen or a different set of columns is required then use of View-> Define Custom Columns will bring up a window allowing the desired columns to be selected. Choose each in turn followed by 'ok' then finish with a final 'ok'.

The default view can be restored with View -> Show default columns, and the newly defined column selection again with View -> Show Custom Columns.

All columns have dynamic widths so the display will adjust as necessary. They are right aligned if all values are numeric, left otherwise.

Multiplexes

View -> Multiplexes shows a listing of multiplexes.

Show Log

Shows the log. This is primarily of interest to the developer.

Sort menu

The sort menu allows the order in which the channels are displayed to be changed.

Note that the channel list includes the row number which is exploited in the edit menus.

If none of the 14 pre-defined orders suit then a custom rule can be generated in much the same way as with the columns.

Other sort options include a reverse sort and a filter which only shows channels which include a supplied text in CallSign, ChannelName, XMLTVID or the --extra parameter..

Edit Menu

The edit menu items allow changing parameters of single channel, or changing parameters of a bulk set of channels. It is possible to change --extra data, but this powerful option should be used with caution. Whilst the flags such is Visible and UseEit are easily reversible, that may not be the case with other parameters.

Single Channel

After selecting the row, this option puts up a window allowing fields for the particular channel to be altered. Alter the fields and select ok or cancel. The box will accept any text starting with 'f' for false or 't' for true in the case of UseEIT and Visible. Visible will also accept 'd' for delete.

Bulk by row range

This allows selection by a single row or a set of rows as displayed by the current sort. Enter a single row as the number or a range as first:last. eg 25:27 will select rows 25,26 and 27.

With the three bulk edit options, boolean values can be set or cleared, text and numeric values can be 'set'.

Numeric values can also be incremented by a fixed value. eg to add 1000 to ChanNum put the value 1000 and 'add'. Negative values will decrement.

Bulk by Source:mpx

This allows selection of a whole source (eg 1) or a whole multiplex (eg 1:6).

Bulk by callsign

This allows selection of channels by content of the CallSign. eg bbc will pick out all CallSigns with 'bbc' in the name.

Edit Undo

Edit -> Undo will reverse the most recent change. The channels which will be affected have the 'U' flag set.

Edit -> Undo all will clear all changes. The channels which will be affected have the 'M' flag set.

Note that the 'undo' items are held in a stack which is cleared after a database save.

File Menu

Exporting and Importing

Having marked all the channels as desired the database can be updated (if not in demo mode!!), but before doing so it may be wise to 'export' the settings made to a file for later use. The file is called channels.export.

The file can then be 'imported' after a channel re-scan to re-impose your settings on the new channel configuration.

The editor will read the channels.export file and attempt to match the channels - the matching rules are probably of little interest to the user (provided they work!) but are:

1. CallSign matches and is unique in the file and unique in the database.
2. Channel number and CallSign both match and the combination is unique in the file and also unique in the database. 
3. Source, frequencyid and callsign all match and the combination is unique in the file and also unique in the database.

If callsign had been changed then three further rules are also applied but using the original callsign.

If any channel cannot be matched then it will be left unchanged but have Q (for query) flag set. These can be identified by sorting by query. Such queries will need to be resolved by hand.

When they are edited the 'Q' flag will clear.

As with all edits, you can 'undo' an import.

Notes:

1. It is advisable to import on reading the database and export again before updating it. This will keep the database and the export file in step. You will be prompted as necessary.

2. A major matching parameter is CallSign and if this is changed, the 'old' name is retained and exported. On import the 'old' name is noted and used to attempt matching.

3. If the --extra calling parameter is used then the --extra values are NOT written to the export file, nor will they be changed on import.

4. Even if you have no history of using the channel editor and are facing a channel rescan, then a run with no edits but an export BEFORE the rescan and a run with an import AFTER the rescan will recover many of the settings.

5. The format of the export file changed between chedit.pl and chedit2.pl to include the additional parameters. chedit2.pl will accept an export file generated with chedit.pl but not the converse.

Updating Database

This option will seek confirmation that a database backup is available then modify the database with the changes made. Database changes will only be made in nodemo mode. Export will be invited before update. The 'undo' stack will be cleared on database update.

XMLTV Menu

Concepts

It was unfortunate that Atlas changed licensing rules during the beta testing stage of version 2 of chedit2.pl and the usefulness of the XMLTV code as provided was then questionable. However, the code has not been ripped out and code to handle Schedules Direct data is included in version 2.01 (8 July 2016). Please contact the author if data for other regions is of interest

Undeterred:

There is a particular problem with XMLTVID data in the UK but the issue may well be prevalent elsewhere. The grabbers produce files which give a correlation between callsign and XMLTVID and it has been necessary to manually insert the IDs into the database either individually with a channel editor or by hand crafted sql statements.

Unfortunately, there are many regional variations and whilst a human may easy decide that BBC ONE London is appropriate for him/her rather that BBC ONE Wales, Scotland etc, automation of this is tricky.

Comparing callsigns in the database with those in the file by 'folding' to lower case, dropping spaces, colons and brackets, and changing 'plus' to '+' does part of the job, but others will need merging manually. eg 'BBC ONE Lon' in the database needs matching with 'BBC ONE London' in the file for those in the London area.

The XMLTV menu thus has five options:

Import

This allows selection of the MythTV source, the XMLTV file and its type. In the case of tv_grab_sd_json the XMLTV file which gives a match between XMLTVID and CallSign is generated with:

tv_grab_sd_json --config-file ~/.xmltv/tv_grab_sd_json.conf  --output /tmp/sd.xml

It attempts matching and displays the database callsigns alongside the matching file callsigns and xmltvid. If previous manual matches have been saved then these can be re-applied. Further manual matching is then possible before finally 'committing' the XMLTVIDs to the image in memory of the database.

I have had a request to match against ChannelName in the database instead of CallSign. This is not a common requirement but if you wish to do this then locate and edit the variable $XMLTVname in the script chedit2.pl

Show Matches

This option shows the database callsigns with the callsigns and XMLTVIDs from the file. Matching ones are shown on the same row. This is a sample of a mis-match:

  CallSign              Row  File_CallSign                        XMLTVID 

                         56  BBC London 94.9                      london.radio.bbc.co.uk
  BBC NEWS               57                                                           
                         58  BBC News Channel                     news.bbc.co.uk      

Merge

If matching is incomplete, items can be manually matched with this option. Any channels in the left column (those in the database) without a match can be linked to those on the right (from the file). eg to match BBC NEWS in the database on row 57 with BBC News Channel on row 58 then entering 57:58 will do this and alter the display.

Commit

Once the matching is completed, the commit option will copy the XMLTVIDs to the main image of the database. The main database in the backend will not be changed at this stage though, and the commit can be undone. Any manual merges which have been made can be written to a file and re-used next time.

Create Source files

At least with Schedules Direct, it is normally necessary to hand-craft source files to indicate whether channels should be included or excluded from the scan. This option automates that task.

It reads a configuration file such as ~/.xmltv/tv_grab_sd_json.conf to extract the authentication lines at the start, and generates a file SOURCENAME.xmltv for each source in the database. The files are created on the working directory.

The .xmltv files include the authentication lines followed by lines like channel=12345 for channels which are visible, have UseEIT false and have a value for XMLTVID.

These files need copying to ~/.mythtv once scrutinised.

Help

The help menu gives access to this wiki.

The diagnostics option generates a file with a name of the form chedit<datestamp>.diags holding diagnostic information. If not in 'spoof' mode it also includes a copy of API data from the backend. The file should also be created on unexpected error.

Changes from Version 1

Version 2 has had a major rewrite to make improvements following user feedback.

The main window can now be re-sized.

ChannelName and FrequencyId are now shown.

Any field from the database can be accessed and changed, rather than just the ability to hide, show or delete a channel as in version 1.

Dynamic width columns and 'custom columns' have been introduced.

The format of 'export' files has changed to reflect the additional fields which might be changed. Version 1 files can still be imported though.

Import/export now uses FrequencyId rather than Frequency - it covers more cases.

More flags are introduced.

Undo is now unlimited, rather than just allowing the last few edits to be reversed.

XMLTV data can now be imported, matched and committed but as yet only UK specific formats are catered for.

Cosmetic changed include the separation of view and sort, radio buttons showing the last sort and a 'prettier' custom sort mechanism.

Help is now external - the help menu launches a browser to open the wiki page. This avoids the previous clumsy display.

To see version 1 documentation, view history and 'roll back' this wiki page to 18 Jan 2016.

Version 2.01 8 July 2016

More rational handling of windows - warning about just using 'return' key added.

Schedules Direct added to XMLTV menu.

Generate Schedules Direct SOURCE.xmltv files

Filter added to sort menu.

Version 2.09 (4 March 2017) - vertical scroll bar abolished; replaced by up/down keys, page/up/Down and home/end.

Tutorial

Start the channel editor in 'spoofing' mode with

./chedit2.pl -sp tutorial.diags

This will start the editor in demonstration mode and read the file tutorial.diags to show the (artificial) tutorial data rather than looking for data on your backend.

If it complains that the libwww-perl module needs loading and if using ubuntu try

sudo apt-get install libwww-perl

Any other modules??

Assuming that all required modules are available, it should show a 75% size screen window with columns of channel data and a reminder that you are in demo mode. There is also a demo reminder top right of the screen. Click on 'OK' in the reminder box. If prompted to read an export file, decline at this point.

Note that this wiki page can be opened with help>open wiki and that the windows can be resized for comfortable viewing.

A main channel view will be shown. See above for the meaning of the columns and flags. Scroll the display by using the cursor up/down and page up/down keys. These can be made to jump ten times further by holding down the shift key. Home/End will place you at the start/end of the list.

Early versions used a scroll bar at the right - this has been abolished because it hit resource limits with large channel configurations..

Try the various sort options. If you don't like any of them you can try defining a custom sort option by selecting the fields in turn then finally 'ok'.

Via the view menu it should be possible to list the multiplexes with frequencies and channel counts, and to create a custom set of columns.

Editing demo

The crux of the software is the ability to perform edits quickly and efficiently. A few examples are given here. If an error is made then it can be undone with

 Edit -> undo
 Edit -> Undo all

Sort the channels by duplicate callsigns and note the duplicates sorted at the head of the screen.

Duplication of callsigns is advantageous if the channels are on different sources since the scheduler is then free to select either channel for a recording. In our tutorial, that is not the case. Three channels are duplicated between multiplexes 1 and 7 and this data simulates a distant interfering transmitter which is subject to fading. Examination of View -> multiplexes and published data shows multiplex 7 to be the rogue (just pretend here!!). Eliminate all channels from multiplex 7.

 Edit -> Bulk by source:multiplex,  choose 1:7, delete, set, ok.

Note the D (deleted), U (can be undone) and M (modified) flags appear and d, the duplicate flag is cleared. The display order is not changed as the channels would be lost 'visually'.

Sort again by duplicate callsigns and see that now only ITV4 is duplicated (channel numbers 24 and 792). 792 was introduced during a channel re-alignment and gave a 'please retune' reminder. There are a multitude of ways of deleting or hiding this channel such as:

 Edit -> bulk by row range, 1, delete, set, ok.
 Edit -> bulk by row range, 1, visible, clear, ok.
 Edit -> Single channel, row 1, change 'visible' to false or delete, ok

Since BBC THREE no longer exists (except via internet) let's kill that off similarly. As it is unique, you could also do:

 Edit -> bulk by callsign, bbc three, delete, set, ok.

BBC ONE recently changed name to BBC ONE Lon and invalidated all recording rules. The callsign can be changed easily once we sort by ChannelId (or ChannelNumber).

 Edit -> single channel -> row 0, change the name and ok.

Author believes this would have retrieve the recording rules but it might also have been necessary to change ChannelName which is used in manual recording rules.

Let's hide all 'adult' channels in one swoop.

 Edit -> bulk by callsign, adult, visible, clear, ok.

Finally, let's clear all EIT flags because we are about to set XMLTVIDs:

 Edit -> Bulk by source:multiplex,  choose 1, UseEIT, clear.

The bulk options can also be used to change Visible, UseEIT, the XMLTVID, channel number and the extra fields and also delete a channel. Numeric fields such as channel number can also be incremented (or decremented if a negative value is given). This powerful bulk option needs to be used responsibly.

UK satellite users seem to have a need to shuffle channel numbers and it could be that this simple addition does not fully meet their need. Feedback please..

XMLTVID demo

The file tutorial.diags holds information to satisfy the code.

Select XMLTVID -> Import. 

Choose Source 1, Tutorial, and accept the tutorial.diags.  

This will generate the 'matching' list. The process will be fast with the demo because the data is compact, but with real-life data expect it to take tens of seconds.

You should see that many channels have been matched, but that important ones like BBC1 and ITV1 have not - they require manual intervention. Try this:

XMLTV -> merge, 11:12 and confirm.

Other matches are 15:16, 22:23, 29:30, 31:32, 32:34, 38:39, 33:34, 46:47, and 59:60.

When all are matched then use XMLTVID -> Commit to write to the main (in memory) database.

If you allow writing of the matches to a file (called channels.matches) then this can be used at the next XMLTV import (with this tutorial!). The matched callsigns will again be re-matched.

Export Data and Update Database

At this stage you may be ready to update your database (apart from the fact that we are in demo mode) but before doing so it will be helpful to export your hard work so it can be re-instated after a channel re-scan in Mythtv.

 File -> Export

This will write a file called channels.export. Now do

 File -> Update Database

This will do nothing apart from making a few proud claims - the software does not even know where your database is! The log with the changes should be shown.

and finally

 File => Exit 

Import

Imagine that you had previously made changes to the database and you have lost them all with a channel scan. In our tutorial this is the same as restarting the editor. Restart the editor as above but this time it will note that an export file is present. Allow it to 'import' it.

All your changes should be re-applied and in a real-world situation, an update database should reinstate the database.

Real World Use

In order to run the editor against your own database in safe demo mode (so the backend will NOT be changed):

./chedit2.pl

The script searches for a config.xml file in the likely places to get the IP address, but if it cannot find it then it will be necessary to specify it with the --backend parameter eg:

./chedit2.pl --backend 192.168.1.65

If a port number other than 6544 is required then it can be added with:

./chedit2.pl --backend 192.168.1.65:1234

To run it in 'live' mode

./chedit2.pl --nodemo

Note that this WILL update the database if you choose the 'update database' option.

Please DO ensure that you have a robust backup strategy or are prepared to re-scan channels before using the --nodemo option.

When running in 'real' mode it is advisable to read the export file when loading the editor and write it again BEFORE a database update. This will keep the two in step. You will, however, be prompted.

Use when adopting Schedules Direct

chedit 2 was used in the UK by the author to clear UseUIT flags, to clear out old Atlas data, to insert Schedules Direct XMLTV ids into the database, and to generate the necessary source files:

1. Clear all UseEIT flags.    Edit > Bulk source:multiplex > 1 . UseEIT > clear
2. Reset all previous (experimental) Atlas XMLTVIDs.  Edit > Bulk source:multiplex > 1 > 'space' in box > set.   See note:
3. Generate a file showing the mapping between XMLTVID and CallSign:

tv_grab_sd_json --config-file ~/.xmltv/tv_grab_sd_json.conf  --output /tmp/sd.xml

4.  Import that with XMLTV > Import > source 1 > /tmp/sd.xml   be patient!
5.  Scan down the list and pick out the failed matches.  Match them manually with XMLTV > match.
6.  Commit and allow it to generate a file holding your changes for next time.
7.  Generate the SOURCE.xmltv files with XMLTV > Create Source Files 
7.  File > Export - for future use
8.  File > save to update the database.
9.  Copy the source file(s) to ~/.mythtv

Note: There appears to be a bug in 0.27.4 with the API whereby writing a blank value for XMLTVID is ignored. Suggest put a space instead.

Other platforms

OS X with MacPorts

From Apple, OS X is lacking several of the software packages that this script depends on. The MacPorts project can provide the necessary dependencies:

sudo port install xorg-server p5.24-tk

Edit the first line of the script so that it uses the MacPorts version of Perl. Make it look so:

#!/opt/local/bin/perl5.24 -w
# was #!/usr/bin/perl -w

From Applications > MacPorts, start X11.app and then start the channel editor from Terminal, as described above.

Files Used

channels.export - holds a copy of database settings which can be imported for the next edit.
channels.matches - holds a copy of manual matches of callsign to xmltv channel names.  
chedit<timestamp>.diags  - file generated on error or when manually triggered.  
           It holds information on sources and channels, a trace of user actions and any error messages.  
           No passwords or other sensitive data is included.
config.xml  - to extract address of backend.
~/.xmltv/tv_grab_sd_json.conf

Problems

Developing and testing this application with two sets of UK data and two sets of USA data (thank you all!!) has shown that TV cultures are both very rich and very diverse. If the code does not behave sanely the help>diagnostics facility has been included to assist investigation.

This should generate a file chedit'timestamp'.diags which hopefully contains all the information necessary for the author to 'spoof' your system and reproduce the fault.

The file should also be produced if the code throws an error. Please submit the file with any reports of problems.

Known Issues

"X Error of failed request: BadAlloc (insufficient resources for operation)"

This crash message is produced with some operating environments with configurations having several hundred or thousands of channels. Exact limits depend on the environment and some simply fail to display channel data. Version 2.09 (4 March 2017) fixes this.

Pane.pm line 301

"Use of uninitialized value in string eq at /usr/lib/perl5/Tk/Pane.pm line 301"

The exact path may vary depending on your configuration.

This error is eliminated with versions 2.09 of the code by removal of the the scroll bar. With previous versions it was triggered by single clicking on the right scroll bar and resulted in spurious messages to the terminal. It may have been a bug in the way Pane was called, but can be eliminated by a change to Pane.pm.

Line 301 of Pane.pm reads:-

if(defined($ch) && $ch->manager eq 'grid') {

Change it to:-

my $fix=$ch->manager if defined($ch);
if(defined($fix) && $fix eq 'grid') {

focusPtr out of sync

"TkFocusKeyEvent found dispPtr->focusPtr out of sync: expected ??, got .dialogbox2.bottom.button"

This error message to the terminal is believed to have been caused by keyboard input whilst no input box had focus. The error message is found in routine tkFocus.c. Version 2.09 resolves this since it traps all keyboard input.

Unable to set XMLTVID to blank

Changes to the database are made via the UpdateDBChannel API call. As of MythTV 0.27 this does not support changing XMLTVID to a blank value (ie a zero length string); other changes to a channel will be accepted but the XMLTVID change ignored. It can be used to set it to a a single space.

Support

This editor comes with no warranty, but the author can be contacted via PhilB on the MythTV forum. A diagnostic file (whether triggered automatically or manually) is most helpful in understanding any problems. A channels.export file and/or a copy of the xmltv file may also be prove helpful.