Channel Editor

From MythTV Official Wiki
Jump to: navigation, search


This page describes version 2.21 of a screen based MythTV Channel editor released 28 Feb 2018.

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. In addition to the powerful edit facilities, the data can be exported to a CSV file for manipulation with a spreadsheet and then and re-imported.

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. Version 2.20 allowed export and import of data to a CSV file for use with a spreadsheet.

What does it do?

It will:

- Extract channel data for all sources from a backend.

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

- Allow channels to be sorted for viewing 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 CSV file for editing via a spreadsheet or 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 0.27, with 0.28-pre and 29 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!


A suggested setup for channel editor is:

Create a fresh directory to hold the files:

 mkdir chedit
 cd chedit

you will need three files;

  • the perl script.
  • the API interfacing module
  • tutorial.diags if you wish to run the tutorial below.

The three files can be found on github: Note that the suffixes for the code files are .pl and .pm respectively.

The module 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"'

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 and of are:

   #!/usr/bin/perl -w will need to be executable.

chmod +x 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 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. You will be asked to select the spoof file if the filename is blank or the file is missing.

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

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.
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)
  I  channel matching rule following an import
  U  last change can be undone
  M  this channel has been modified.

ChannelName view

This shows ChannelName instead of ServiceId


Shows XMLTVID instead of ServiceId

Extra View

If the --extra parameter is specified, an additional menu item is shown. It provides a column setup which replaces ServiceID 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.


View -> Multiplexes shows a listing of sources and multiplexes.

Show Log

Shows the log. This shows statistics after imports but is also a developer support tool.

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 17 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 not possible to change --extra data.

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 for source 1) or a whole multiplex (eg 1:6 for source 1, multiplex 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. The text is case insensitive.

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

The Channel Editor allows data to be exported and re-imported to or from a CSV file. This allows editing using the powerful facilities of a spreadsheet such as Libre Office Calc.

The columns exported are: ChanId, Callsign, ChanNum, ChannelName, CommFree, FrequencyId, MplexId, ServiceId, SourceId, UseEIT, Visible and XMLTVID.

On import, any row starting with # is treated as a comment and is ignored – such rows are inserted near the head of the file to show program version and to identify columns which will not be changed on import.

The order of the columns is unimportant. The header must be the first non-comment row, but the order of other rows is unimportant.

There are two scenarios for export and import:

a) Export, edit data using a spreadsheet and import again. Matching of rows is then best achieved using ChanId (channel identifier) in which case 100% matching can be expected. Rule 0 only is used.

b) Export, rescan the backend, then import. In this case, the new ChanId’s will probably be different and more subtle rules need applying. Seven rules seeking unique combinations of ServiceId, Source, FrequencyId, Channel Number and Callsign are used. See rules 1 to 7.

A rule is satisfied if there is only one channel in the CSV file and only one in the database which match.

The rules are:

 Rule 0: Chanid,                          Direct matching – use after spreadsheet edit - NOT after a channel rescan
 Rule 1: ServiceId,                       UK rule
 Rule 2: FreqId:ServiceId0,               USA rule
 Rule 3: ServiceId (ServiceId != ChanNo), UK rule
 Rule 4: ServiceId (ServiceId = ChanNo),  UK rule
 Rule 5: Callsign,                        General
 Rule 6: ChanNo:CallSign,                 General
 Rule 7: Src:FreqId:CallSign              General

Following an import, the rule used for each channel will be shown in the I column of the flags. If matching is not possible, a Q (query) will appear in this column. These can be identified by sorting by import rule. Such queries will need to be resolved by hand.


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

2. 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 to a csv file BEFORE the rescan and a run with an import AFTER the rescan will recover many or all of the settings.

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


In the UK, ServiceIds are believed to be unique across the country and provide a good basis for matching. In the USA they are only unique to the multiplex.

Matching is thus an inexact process and no surefire rules exist for fully matching complex configurations. The author would appreciate feedback, especially outside UK/USA, preferably with a postmortem and a copy of the CSV file in any cases where matching might be improved. See help>version for the email address.

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 to a csv file will be invited before update if relevant changes have been made. The 'undo' stack will be cleared on database update.



It was unfortunate that Atlas changed licensing rules during the beta testing stage of version 2 of 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


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 XMLTV

This allows selection of the MythTV source, the XMLTV file and its type. In the case of Schedules Direct 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 near the head of the script

Show Matches

This option shows the database callsigns against the callsigns and XMLTVIDs from the file. Matching ones are shown on the same row. This is a sample. Note that 'Channel 4+1' can be matched with the simple built in matching rules, but matching 'Challenge' is more difficult.

  CallSign              Row  File_CallSign                     XMLTVID 

  BBC TWO               15   BBC Two                           17154               
  Challenge             16                                                        
                        17   Challenge TV                      21793               
  Channel 4             18   Channel 4                         17155               
  Channel 4+1           19   CHANNEL 4 (PLUS 1 HOUR)           56892       


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 Challenge in the database on row 16 with Challenge TV on row 17 then entering 16:17 will do this and refresh the display.


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 channels.match 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.

Author suspects that you may need different versions of tv_grab_sd_json.conf for this if you have two or more sources (eg satellite and terrestrial).


The help menu gives access to this wiki.

The diagnostics option generates a file holding diagnostic information. The filename can be selected but the default name is of the form chedit<datestamp>.diags

If not in 'spoof' mode it also includes a copy of API data from the backend so the file can be used in 'spoof' mode by the author if necessary. 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.  Prevents crashes with large configurations.

Changes in Version 2.20

CSV export/import
New matching rules for CSV import.
ServiceId extracted from backend
Bugfix – crash after deleting channels when updating database.
Tutorial file has ServiceIds added.
Font size change in view menu

Changes in 2.21 released 28 Feb 2018

Bugfix:  ask user if csv file needed before database save - now correctly triggered.
Allow user to specify files for CSV import/export, for diagnostics and spoof files.
Bugfix in 'create SD source files'.
Improved XMLTV callsign matching.


Start the channel editor in 'spoofing' mode with

./ -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.

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. B will toggle bold font and + or - change font size.

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, to create a custom set of columns, to view the log and to change font size.

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 here recently changed name to BBC ONE Lon and invalidated all BBC One 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. Exporting to a csv file and manipulation with a spreadsheet will be more powerful.


The file tutorial.diags holds enough 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, 29:30, etc..

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 csv file. 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 


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 simulated by restarting the editor. Restart the editor as above and File > Importcsv. Select the csv file and decline to allow matching by ChannelId.

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):


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:

./ --backend

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

./ --backend

To run it in 'live' mode

./ --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.

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 and then start the channel editor from Terminal, as described above.

Files Used

*.csv     - 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.  
*.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     Schedules Direct authentication file.


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. The author would particularly appreciate diagnostic files from TV regions outside UK and USA for testing purposes.

Known Issues

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.

Resolved Issues

These are documented here for the benefit of tk users searching on error messages. They are no longer relevant to chedit2 users.

"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 by limiting the size of data written to a scrollable pane. line 301

"Use of uninitialized value in string eq at /usr/lib/perl5/Tk/ 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

Line 301 of 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.


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 csv file and/or a copy of the sd files (with passwords redacted) may also be prove helpful if relevant.