Thursday, April 7, 2016

Email Notifications for Kodi / OpenELC (Part 2)


Getting it

The Difference Engine can be found at;

It's written in Python 3, and has been tested on Mac OSX using Pyzo (which comes with Python 3.4) and on Debian 7.9.  It should probably work on any other Linux system.  And it should probably work on Windows, assuming you have Python 3 installed.  It probably won't work on OSX natively, since it ships with Python 2.7.

Use git to clone the repository.  Alternatively, if you aren't using git and don't want to install it... you can just download the main script ( and the stylesheet template (stylesheet.css).  You'll also need to download the example config file, and modify it for your own settings (more on that later).

Running the Difference Engine

Run 'python3' from your command line or whatever your python environment uses.  The first time it runs, will try and create a new sqlite database, and populate it with data from your Kodi / OpenELEC media player.  Depending on the size of your library, this could take a long time.  At the moment, in order to help me with debugging, it spews out quite a lot of information so you'll know it's working busily.

Once the initial database has been created and populated, subsequent runs should be much faster.  Though, if you turn on the option to query the TVDB this can slow things down.


There is an example config file in the github repository.  Download it, rename it to thediffer.conf and fill in the appropriate details.  Some basics around the configuration;

  1. Scan days -- this is the number of days the differ will scan back to, looking for updates.  Generally, this depends on how frequently you schedule it to run.  If you run it daily, set the scan days to 1.  If you run it weekly, set the scan days to 7 (and so on).  The update option determines whether you want to issue Kodi with an update command before commencing with the scan (to make sure the media library is up-to-date).
  2. Email -- Set this option to True if you want to receive an email.  If left at False, it will simply dump out an html file (which you can either email using another app, or present using a webserver).  If set to True, make sure to fill in the details of your email provider
  3. TVDB -- if set to True, the differ will call the TVDB API, to find an IMDB identifier and (where available) use that to create live hyperlinks in the html.  You'll need a TVDB account for this to work.  It's a nice option, but completely unecessary.
  4. Styles -- modify this if you want to change the look of the emails.

Sunday, April 3, 2016

Email Notifications for Kodi / OpenELC (Part 1)

To jump straight to the installation and usage instructions, check out Part 2.

For quite some time now, I've been wanting to have an email notification system for new content that appears on my Kodi / OpenELEC based media player.  Most people seem to be happy to use the notification system in either SABnzbd (for when they download a piece of content) or in Sickrage/Sickbeard/Sonarr/Couchpotato, etc... for when the downloaded media gets picked up.

The problem with this approach is twofold;

  • Firstly, shock, horror... but there's a stack of content on my media player that ISN'T downloaded.  I manually rip content from DVD/BluRay and then load it myself.  And while I don't need to be notified that this new content has been added to the media library (afterall, I did it myself)... it's nice to be able to notify other family members.
  • Secondly, most of these notification systems send a new notification for every single piece of new content.  If you added 24 new episodes of a TV series that you just ripped from DVD, you can expect to receive 24 new email notifications... one for each episode.
What I really wanted is a sort of "daily digest" that shows all the content being added on a given day... neatly put together and summarised.

The Difference Engine


My first attempt was based around using a bash script to scan the hard drive of my NAS, looking for any new files.  If they looked like media files, I'd then dump them into a file and email the results.  The problem is that timestamps, I found, aren't always a reliable indicator of whether a file is actually "new" or not.  So instead, I started maintaining a list of existing content in a SQLite database.  The script would then scan for any media content, check to see if it was in the database already.  If not, it was deemed to be "new" and would go in the daily digest.

I called the script "The Difference Engine" since it checked each day to see if there were any "differences" in the media content.


Although my first script mostly worked, it lacked any kind of sophistication.  Plus, the script needed to run on the same server that stored all the media content -- which I decided was potentially a Bad Idea (TM).  So for my second attempt, I re-wrote the script from scratch.  This time, it called Kodi's built-in API to find new content.

Again, since Kodi doesn't always reliably report content as being new (eg, if you hose your library and re-install it), I used the same approach of storing data in a SQLite database.  The script, written in bash, would query Kodi (using curl) and then try and interpret the json that was returned (using jq).

It mostly worked.  But after spending plenty of time on Stack Exchange asking a myriad of questions, it became pretty apparent that trying to parse json strings in bash was a pretty dumb idea.  Bash is really, really useful for scripting and automating various system admin tasks.... but as a general purpose programming language -- not so great.


So after resisting it for a long time, I decided to try and teach myself python.  So far, all my attempts at learning python have been completely hopeless.  I'm not a programmer, and the little bit of programming knowledge I have seems to be completely at odds with a lot python paradigms.  But I'm reliably informed that python is awesome and incredibly productive.  So over the last week, with some time off work, and a specific project in mind (ie, an updated version of the differ), I put my mind to my first python application.

A big shout out to Pyzo which is a pretty simple and functional IDE that can be installed on Windows and OSX with minimal fuss.  Not only does it work pretty nicely, but it's pretty self-contained.  So it allowed me to install python3 on my MacBook without messing with any of the existing python libraries.

Now... on to the end result.