Introducing TvTumbler

Well I’ve been promising this long enough – An XBMC Addon that will download TV Shows automatically.TvTumbler logo

I’ve actually been working on this on-and-off for a few months now, but I have so little free time these days, progress has been extremely slow.

The project pulls *very* heavily from my experience with Sickbeard. The target here is to put together a system that ‘just works’, and doesn’t require continuous tweaks as Sickbeard does. To this end, the plan is currently:

  • Only free, open, feeders (‘providers’ in SB terminology).
  • Multiple different types of sources: Currently only torrents are implemented, but I’ve put in the basics for other types also (e.g. Video-On-Demand sites, like iPlayer, Hulu, etc. and download sites like
  • An integrated torrent client. Using libtorrent in Gotham is proving quite difficult, so I’m relying on Transmission for now. I’ll fix this in time.
  • Low resource usage. Sickbeard did a *lot* of background downloading, refreshing, updating etc.. I have eliminated all of that here. There will be a small cost in terms of what we can display (e.g. banners and schedules and such), but I think it’s worth it. XBMC has many many addons which do a far better job of this kind of thing.
  • Take out much of the functionality that doesn’t-quite-work (or isn’t really needed) in Sickbeard: e.g. Season pack downloads. Backlog. Notifications. Metadata downloads. Mass updates. (Most) Post-Processing.
    (Note: I do plan to implement Backlog in the future, but using a very different technique. *cough* dns *cough* Everything else I’ve taken out is handled better by other XBMC addons)
  • Scraping. Anyone who uses my fork of sickbeard will know that I’ve removed any instance of it that I can. I’ll be completely avoiding it here.
  • Automatic fixing of ‘Scene’ numbering. Don’t get me wrong, Scene numbering is great, and it makes a *lot* more sense than numbering. But XBMC (for the most part) uses thetvdb numbering, so we’re stuck with it. The addon will automatically convert between the two.

If you’re curious, have a look at the github link above. You can even install it and try it out if you like.

Please note that this is currently Pre-Alpha. It has bad bugs (which will occasionally require a restart of XBMC to fix), and some significant missing functionality. Of course we are delighted when anyone tries this out, but for the present the target market is developers and people who don’t mind poking around in logs and code.

Installation Instructions:

  • Download the latest service.tvtumbler zip from
  • In XBMC: System → Settings → Addons → Install from zip file, and browse for the zip file you’ve just downloaded.
  • Install transmission (this is a temporary requirement until libtorrent is implemented). Set it up so that it puts completed downloads somewhere that XBMC can access them (this means a network share if it’s not running on the XBMC machine), and so that it stops seeding when it reaches a specific ratio (typically I recommend >1.1).
  • In the Addon settings → Feeders: Enable at least one.
  • In the Addon settings → Transmission: Enable it, and set all required settings. The Download Dir is where XMBC will look for completed downloads.
  • Open the Addon through either ‘Video Addons’ or ‘Programs’. Select the ‘Shows’ button, and follow some shows (use the context menu to select quality).
  • And read the notes here: they’re likely to be much more current than the above.

Please post any issues on the github issue tracker, and include an XBMC debug log.

Want to help out?

  • Can you code? Have a look at the XBMC code on github (especially the XBMC gui, this needs a lot of work), or perhaps the (soon to be released) web interface. If you can do either, the XBMC gui is the priority (as I have little or no XBMC gui experience, and I can do web in my sleep). But drop me a line before you do anything, as there are extensive dev changes afoot (the addon will soon be split into 3).
  • The system has ongoing maintenance and hosting costs (yes, there’s a considerable server component to this). All contributions are welcome. Bitcoin: 15Vh5ZiQpXuymRf46JAELnZPNbLaTKLduc.


  1. #1 by rhys on September 22, 2013 - 10:53 am

    Could Work Bricky that nice idea cant wait to see it once bug are out


    • #2 by Bricky on September 23, 2013 - 3:49 pm

      Thanks Rhys,

      It’ll be quite a while before all the bugs are gone, but it’s quite usable and functional at the moment. I use it myself of course, and, surprisingly, a bunch of others do too (surprising b/c this blog post is the only “public” announcement I’ve made to date about it, and google hasn’t even picked it up yet).

      Anyone interested in doing any testing should download the latest zip from the repository here. Installation is very straightforward (it’s the same as for any xbmc addon).

      Any issues can go in the github issue tracker, or, I guess here in the comments is ok for now.


  2. #3 by Niels on September 24, 2013 - 11:55 am

    It’s a brilliant solution, works on both Windows and Linux (Ubuntu) without a hassle (I did have to install Transmission on Windows, but hopefully Libtorrent will get implemented soon). This is what I’d been looking for when I started using SickBeard. For now a bit basic, but at least just keeping up with shows is pretty much carefree now.

    Would be nice if downloaded files get put in same folder as the other files of the same show but I guess just the same folder where the series library is located suffices. Although I’m a bit confused about that, seems to me that downloads are moved to Transmission’s download location and not the Download Dir set in TVTumbler settings (might be caused by the Windows port of Transmission though). Will have to wait for a new show to confirm this.

    But thanks a million anyhow, keep up the good work!

  3. #4 by Bricky on September 24, 2013 - 12:15 pm

    Thanks for the vote of confidence Niels – appreciate it!

    I’ll get the libtorrent thing sorted in time. It’ll take a bit of work, and I think it’s more important to put the time into other basic (and more needed) functionality like adding shows and such.

    I’m curious about what you say about the downloaded files and where they go. If everything is working as it should, then new downloads should go into the correct folder for the show (with a separate subfolder for each season). The path is pulled from your XBMC video library, and assuming that XBMC has write access to it, it will move the videos there after download.

    Maybe this is just confusion over the settings:
    – General -> “Directory for New TV Shows”: you can ignore this for now, it has no effect.
    – Transmission -> Download Dir: this is the directory where XBMC expects to *find* the downloaded torrent when it’s finished downloading. It will copy the files from there into your video library.

    Granted – this could be clearer in the settings. I’ll come up with a better description/label for these settings in time.

    Thanks again!

    • #5 by Niels on September 24, 2013 - 1:25 pm

      It’s as you said, I thought that XBMC could tell Transmission which folder to save files to (so that it would just dump all shows in one folder). Transmission and XBMC had different download locations set up and TVTumbler reported downloads failing. After writing the comment I matched the download-location settings and tried downloading an episode again. Everything works perfectly fine now. I’ll be keeping an eye on your site as I’ve been doing for the last 6 months. Cheers!

  4. #6 by Bricky on September 24, 2013 - 2:09 pm

    Niels :

    It’s as you said, I thought that XBMC could tell Transmission which folder to save files to (so that it would just dump all shows in one folder).

    That was my hope initially also. But it wouldn’t work if transmission is on a different computer to XBMC (which it often will be). Hence the setup as it is currently.

    Obviously libtorrent won’t have any of these problems :)

  5. #7 by Karl on October 1, 2013 - 11:28 am

    Nice work Bricky! I have been following SickBeard, with some success, and found this new add-on. I have just installed it and all appears to be going ok.

    I was wondering, as you mention that “(Most) Post-Processing” has been removed, will it still move and rename files from the transmission incoming folder to the correct show folder?

    Also glad to see additional feeders as ezRSS has been blocked by all ISPs here in the UK :(

    Keep up the good work old chap!

    • #8 by Bricky on October 1, 2013 - 12:32 pm

      Hi Karl,

      Great that it’s working for you! Keep in mind that this isn’t even alpha yet, it definitely has bugs, and will certainly break on occasion (necessitating a restart of xbmc quite often).

      Regarding post-processing: yes, it will copy the file to the correct show/season folder, rename it to something appropriate, and add it to your XBMC library. But that’s all. No metadata, fanart downloads, subtitle downloads, running scripts, etc. All this kind of thing is unneeded overhead, and anyway XBMC does most of automatically when needed.

      Also, FYI: I’ll add the fallbacks I have in SB for ezrss soon. It makes it pretty much bullet proof (for now at least), even for the unfortunate virgin/sky users in the UK. I also have plans to add a dns based service (which should be essentially unblockable), more on this in time.

  6. #9 by cr08 on October 2, 2013 - 2:31 am

    Hi there. Nice to see this come around and surprised no one has tackled it earlier (having the downloader more integrated into XBMC). Likewise, I have been quite annoyed at the excessive background downloading Sickbeard does for what is really unnecessary in most cases. Definitely going to give it a solid go and report any bugs I happen to come across. Keep up the great work.

  7. #10 by Nickodemus on October 2, 2013 - 8:40 am

    I’ve tried installing it as per the instructions to see how it worked, if it worked and if I’d like to continue using it. Sadly, I can’t get it to work. It won’t download, I can’t really find any logs on anything to find out why, either. I’ve previously used CP, SB and SABnzbd, but it felt extremely clunky. Any help possible?

  8. #11 by Bricky on October 2, 2013 - 12:35 pm

    @cr08: thanks for the input, looking forward to hearing how it goes.

    @Nickodemus: if you want to post up a debug log and give some details about which shows you followed/feeders you enabled etc., then we might be able to help.

    But, I get the feeling that you missed the note about this being pre-alpha. Alpha means it has bugs, pre-alpha means it has bad bugs and missing functionality :)

    So, for the present, the intended audience here is developers and people who don’t mind poking around a little in logs and code. I’ll make this a little more explicit in the post above shortly (it’s already very clear on the github page).

    As soon as this is ready for some general use, I’ll be posting about it on the XBMC forums and so on.

    Thank you nonetheless for your input. Appreciate the time you spent on this. :)

    • #12 by Nickodemus on October 2, 2013 - 3:41 pm

      Ahh, alright, thanks. I thought it might have the basic functionality so it’d work somewhat out of the box for just downloading automatically. I’m looking forward to seeing it get proper functionality, looks extremely promising. :>

  9. #13 by ColForben on October 2, 2013 - 7:43 pm

    Great plugin- is there any logging facility to be able to get some insight into what the plugin is doing/has done?

    • #14 by Bricky on October 2, 2013 - 8:06 pm

      Xbmc log is your best bet. Turn on debug logging and you’ll get lots of status info.
      Ultimately most of this will go into the (currently disabled) status screen in the addon.

  10. #15 by Nelson on October 4, 2013 - 7:21 pm

    This looks great. I look forward to trying it out once other torrent clients are supported. Transmission unfortunately is Mac and Unix varieties only right now.

  11. #17 by cr08 on October 8, 2013 - 3:20 am

    Wasn’t sure whether to post this here or on github as it constitutes more or less a ‘feature request’. But I guess it is going here. Couple things though:

    >> Specific resolution choice vs HD/SD. Although being more TV focused I don’t think there’d be many releases higher than 720 out there (too much extra work to deinterlace 1080i to p, 1080i releases are nearly nonexistant outside of raws). You might better know the availability of different release resolutions to go on this.
    >> Some form of ‘batch edit’ mode. Manually enabling and choosing resolutions of each individual show can be tasking. And in my case of having something close to 50 active shows listed, it is going to be a decent task. Thinking along the lines of SB: A batch edit mode, a ‘default setting’ option, etc.. Just something to keep in mind for later.

    So far things seem to be going as well as expected for this stage of development. Initial run on a few shows ran without a hitch. Sent downloads to transmission, transmission downloaded to its own folder, tvtumbler moved to the dedicated tv folder and XBMC displayed as normal with metadata.

    • #18 by Bricky on October 8, 2013 - 9:48 am

      Thanks, appreciate the feedback! (and here or github is fine, for now it doesn’t really matter)

      >> Resolutions: This is just laziness for now. The software identifies a full range of qualities (see here). It’s not 100% reliable, but it’s generally fairly accurate. I’ve reduced it to just SD & HD in the gui to simplify the ui, but I’ll expand it out to greater options in time.

      >> Batch edit: this isn’t an immediate priority in XBMC (where the gui is very restricted), but I do plan to add a web interface with this type of thing (it won’t be for a while yet though).
      I sympathise btw, I had about 20 shows to follow (with XBMC running on a Pi), and it was a very slow task to enable them all!

      Thanks again for the input!

  12. #19 by ColForben on October 10, 2013 - 6:58 pm

    OK- I’m still a bit unclear as to how the completed downloads are supposed to get moved to another location, and where that location is specified. also, it appears to be continually downloading the same shows over and over again, especially if I delete them after viewing.

    • #20 by Bricky on October 10, 2013 - 7:07 pm

      The addon will move (actually copy) the downloads into your library after they’ve downloaded. This is why you need to have a properly configured library (which uses the tvdb numbering system).

      And yes, it’ll re-download something if you delete it (up to a week after its air date). No way around that for the present.

  13. #21 by Manav Seth on October 17, 2013 - 1:34 pm

    Hey, this is a great tool. Was just wondering, can this be configured to automatically download shows using icefilms? And made to work with Plex instead of XMBC?


  14. #22 by Ricky on October 17, 2013 - 8:54 pm

    TVTumbler: Transmission Unable to Connect

    I wanted to share my installation experience with you as this may not be apparent to some windows users. I installed TVTumbler on windows on the same machine as Transmission and got the error “TVTumbler: Transmission Unable to Connect”.
    I followed the installation instructions and installed Transmission, started transmission and started a local session in transmission. I installed TVTumbler and went through the configuration in XBMC. Immediately after I saved my configuration, I received the error “TVTumbler: Transmission Unable to Connect”. To get Transmission to work with TVTumbler in Windows I changed the remote setting in Transmission. To change the remote settings in Transmission go to Edit>preferences>Remote and allow remote access. Once I made the changes, TV Tumbler was able to connect to Transmission.

    BTW- thanks for creating this software. I have been searching for something like this and i am looking forward to seeing it grow.

  15. #23 by Bricky on October 18, 2013 - 1:00 pm

    @Manav: no icefilms support yet, but assuming I can find an api (and I’m pretty sure there is one), I do plan to add it. Also looking into adding more legal download sources (iTunes, Amazon, etc. and of course iPlayer for uk users).

    Plex is a maybe, but it won’t be for some time yet (unless someone else decides to take it on).

    @Ricky: Didn’t realise that this wasn’t the default! Thanks!

    @all: bug reports are very welcome indeed (provided you can include a debug log, and you’re willing to answer a few questions).

  16. #24 by Mr. Smith on November 3, 2013 - 6:05 pm

    I’v been looking for such a thing for quite a while. It actually works quite smoothly. Nice job.
    But of course, I wouldn’t be writing if I only had nice things to say. People seldom do :)
    What about a feature allowing downloading of all episodes starting from the last one in the library, and not only the new ones? This would use something else than rss feeds, obviously.

    Ever thought of it ?

    • #25 by Bricky on November 3, 2013 - 6:13 pm

      Very soon now :)

      If you’ve been using this for a while you’ve probably noticed that the rss feeds are not the only ‘feeders’ – there’s a magical process called the backlogger that runs every once in a while and picks up anything they missed. So the backend for this is already in place – the only thing outstanding is the gui for it.

      You’ve probably also noticed that i suck at gui though … :)

      Anyway, hang tight, this is in the pipeline :)

      • #26 by Mr. Smith on November 5, 2013 - 7:36 pm

        Great news!

        I had a look at the Seems promising.
        Are you planning to make the variable BACKLOGGER_END_DAYS_AGO accessible to the user?
        The next step for me is to refresh my python knowledge and get the whole magnet link story straight.
        Oh…and forget about the gui. Who needs it? XBMC is too slow on the pi anyway. You’ll just work faster if you focus on the back-end :)

      • #27 by Bricky on November 6, 2013 - 2:21 pm

        Can’t do backlog without a gui really – very few people would want it to be automatic, there must be some kind of manual trigger (i.e. something like browse for show -> season -> click ‘Download missing episodes’, or similar).

        And yup, I think I’ll shorten that to about 2 days, but make it configurable.

  17. #28 by BW on November 14, 2013 - 2:40 am

    I haven’t had a chance to try this out (not sure I have the expertise), but I’m excited to follow it’s progress. Still using Sick Beard and its ok but something integrated into XBMC would be phenomenal. Someone mentioned earlier about being able to select specific resolutions – I would second that request. I like Sick Beards ability to specify Web-DL or 720p Bluray and also exclude certain words (to avoid certain releases or formats) but its such a pain to get the files into XBMC. Sounds like TVTumbler is going to be much easier and more convenient.

    • #29 by Bricky on November 14, 2013 - 9:15 am

      Hi BW,

      I think the likelihood now is that we’ll have:
      – ANY (which means literally any quality)
      – SD (which includes SD TV, DVD, 480p, 576p etc.)
      – 720 (which includes HD TV 720 rips, 720p, bluray/hddvd 720 rips, and probably 1080i)
      – 1080 (which includes 1080p, and bluray/hddvd 1080 rips)

      And a setting to favour higher or lower qualities (where multiple matches are available).

      SD, 720, and 1080 are basically what XBMC groups the qualities as, and it makes sense to mirror those.

      Of course there’s an argument that we should have a much larger range of qualities, but if we go that route, then we’ll pay quite dearly with the success rate when actually searching for episodes/qualities (which currently runs at > 99%). And how many people in the world actually really care whether something is web.dl as opposed to bluray?

      Also, I’d encourage you to try it if you’re interested. It’s certainly no more complex than SB to set up, and you’ll get a much higher success rate (albeit without a backlog for now).

  18. #30 by Ebi on November 23, 2013 - 6:11 pm

    Cool idea. I was wondering if you will make a Plex version of your plugin?

    • #31 by Bricky on November 23, 2013 - 6:46 pm

      Hi Ebi,

      Ebi :

      Cool idea. I was wondering if you will make a Plex version of your plugin?

      Probably in your interest to read the comments above then :)

  19. #32 by Alex on November 24, 2013 - 4:16 pm

    Seems promising! A few questions tho
    Could this work on android? Or a raspi? With that, you could easily replace a HTPC: XBMC running all the time, Tvtumbler downloading shows that’d be automatically indexed by XBMC.
    But, the main question: Could we use private trackers w/ it ?
    Or, at least if you don’t wanna bother with implementing them, looking for the work that mr-orange has already done with his fork of sb, or, at least, allowing us to use custom RSS providers ?

    Thanks !

  20. #33 by Bricky on November 24, 2013 - 6:02 pm

    @all: in future, if I don’t bother to respond to your comment, it’s because you’re asking something (or lots of things) that is answered above. If you can’t be bothered to read at least the blog post, then I’m afraid I can’t be bothered to respond to your questions either :)

  21. #34 by Dan on December 1, 2013 - 5:11 pm

    Hey, can this download the previous episodes or just future ones as they are released?

    • #35 by Bricky on December 2, 2013 - 1:17 pm

      Hey Dan,
      Right now, it’ll do as-released and up to 30 days back (automatically).
      Soon I’ll be adding the facility to go back as far as you want (but it’ll something you tell it to do manually, not automatic).
      It’s next on the todo list after the web interface (which is almost ready now).

  22. #36 by chris on February 27, 2014 - 9:23 pm

    any work on this? i see the latest comment is a good 4 months old. it seems like an awesome idea. i am currently scripting a solution for my self but really like the simplicity of this setup.

    • #37 by Bricky on February 28, 2014 - 6:27 am

      Hi chris,

      TvTumbler is alive and well. This was just the blog post introducing it.

      You have the option of running the ‘stable’ version (which is linked in the article above), or the dev version (which you’ll need to download and install yourself. The dev version has the distinct advantage that it supports the web interface (which you’ll also need to install yourself).

      If you’re a developer, any contributions would be appreciated.

  23. #38 by bodangren on February 28, 2014 - 7:21 am

    Thanks for the work! I have been looking for a replacement for Sickbeard and recently moved over to NZBDrone, but TVTumbler is so great that it’s integrated into the XBMC system. I hope that I can get into the code and propose a patch or two.


  24. #39 by aerjot on March 7, 2014 - 5:15 pm

    doesn’t work on gotham unfortunately because of the “new” dependiences :(

    • #40 by Bricky on March 7, 2014 - 5:18 pm

      Really? Disappointed about that.
      I actually developed it on Gotham (and had to do several tweaks to get it to work on both). Haven’t worked on it in a few weeks though, and I guess my Gotham is probably a bit old.
      What are the dependencies? What errors are you getting?

      • #41 by aerjot on March 11, 2014 - 5:49 pm

        it worked just fine on frodo, but gotham is kinda different. maybe it’s just because I’m using openELEC. could you be so kind to instruct me how should I get you any type of useful log from openELEC/xbmc enviroment?

      • #42 by Phuriousgeorge on May 9, 2014 - 2:37 am

        appears the dependency missing is script.module.feedparser version 5.1.2

  25. #43 by Mr. Smith on March 11, 2014 - 4:31 pm

    Been using this for a little while now (xmbc 13 running on arch/raspberry pi). I like it a lot. You’re right though, there are problems with animes. It bothers me. Let’s fix it.

  26. #44 by Fro on April 2, 2014 - 8:16 pm

    look forward to checking this out, if you have a paypal account id donate using that.

  27. #45 by aerjot on May 4, 2014 - 4:54 pm

    Mr. Smith – how come it works on xbmc 13 for you? which beta? I’ve had problem with getting it to work because of the dependiences issue since first beta of gotham.

    Bricky – please don’t give up the development of this plugin, I will surely consider a donation.

  28. #46 by Mr. Smith on May 9, 2014 - 6:08 pm

    Aerjot, xbmc-rpb-git 13 (20140403 nightly)
    To be honnest, I stopped using it, because of this anime limitation. I second your wish about Bricky’s involvement though. If this project was active, I’d go back to it in no time.

  29. #47 by Ben Hesp on May 17, 2014 - 11:28 pm

    Folks, if anyone else is getting the “dependencies not met” error trying to install the addon on gotham, see fix here:

  30. #48 by TvFanatic on June 3, 2014 - 3:20 pm

    Is it possible to add an option to not add a Season folder within the Show’s folder? In other words, just copy it to the Show’s folder instead of adding an additional Season folder?


  31. #49 by jonc on June 25, 2014 - 1:30 am

    Even in Alpha this is great and within a few days happily updating my NAS ..

  32. #50 by Adam Cunningham on July 25, 2014 - 9:29 pm

    I run OpenELEC on a Raspberry Pi. I’ve recently updated to OpenELEC 4.0.7 and TvTumbler no longer works. Should it still be working with this setup? If not, are there plans to get it running on this version of OpenELEC? Your add-on is awesome and I’d hate to lose it. Thanks!

  33. #51 by jonc on August 18, 2014 - 12:21 am

    It is not OpenELEC that is the issue, it is Gotham that is the problem (read above)

    Still working just fine here, I am so happy with it.

  34. #52 by jonc on October 17, 2014 - 12:11 am

    congratulations on 12 months of TVTumbler

  35. #53 by Maiklas on January 4, 2015 - 6:24 am

    I modified the git-master (0.1.0) to enable a feed that was disabled as redundant; now it might be the only working feed now after the great disturbance in the Force in December of 2014. I also modified it to allow specifying “1080p” as an option for each show in the interface. It is presently working. It finds and queues torrents. The 1080p option did work when there were feeds that had 1080p. (If the working feeds don’t have 1080p, then specifying 1080p obviously won’t be productive.) I tested under XBMC 13.2. If you want a copy of this customized plugin, PM me at the Kodi forum:

    By the way, I rather prefer Trakt+Flexget, simply because Trakt has next/previous week buttons on its calendar, but a few days ago Trakt upgraded their website and removed nearly all functionality, so Trakt is not a good option at present.

    • #54 by Ero on April 27, 2015 - 9:25 pm

      Thank you for the effort.keep it up

  36. #55 by StefWill on October 16, 2015 - 5:49 am

    Any chance of getting this working on Kodi?

(will not be published)