Linux users: Missed your favorite show? There may still be a way to view it, without annoyances

One of the nice things about free-to-air satellite is that if you try to record the eastern time zone feed of a show and the recording is no good for some reason, you can often find a later time zone feed to watch or record. However, if a channel suddenly “goes dark” with no warning, or if you don’t realize your recording is bad until after any refeeds have already aired, what can you do then?

Many networks put their shows online, on their web sites, so obviously that would be the first place to check. The problem with that is that many of those sites are a pain in the posterior to use. In some cases you have to have a cable company or commercial satellite provider login in order to watch a show, and in any case the stream will most likely be interrupted by annoyances (commercials, and promos for other shows). And, it may require that you have Adobe Flash installed on your system, and fewer systems come with Flash these days because Flash is a dying technology (none too soon, in my opinion). Over a year ago, Adobe itself started telling people to stop using Flash, but apparently many online video sources haven’t heard the message yet. You can still install Flash, but why would you want to? And I don’t know about you, but I find watching a show in a Web browser a less than spectacular experience.

But if you have access to a Linux-based system, there may be a way to avoid many of the annoyances. I will refer you to this article, which tells you how to install a program that will let you download videos from YouTube “and few more similar sites”, but don’t let the word “few” fool you. I am not going to expound on how understated that statement is. What I will say is this, install the program on your favorite Linux-based system (using the instructions in that article, preferably using the curl or wget methods, since you can then use the program’s -U option for updates), and then run it with the --help option and actually read the output. Many of the options won’t make much sense to you at first, but you may see a few that are rather enlightening. If you find a section that makes you think “Wait a minute, it can do that?”, well yes, it probably can.

So here is the procedure to get a missed show. Open up the web page for the network of the show you missed, and if they have a specific link for “full episodes” or something similar, follow that. When you find the thumbnail or link to the episode you missed, right-click on it and copy the link location.

Now run the program, giving that link as the final option on the line. More than likely it will give you one of several responses. If you are lucky, after a small delay it will start downloading the show. When it is finished, you can move the downloaded file to your Videos directory and watch it using whatever software you normally use to watch TV shows (such as Kodi, Plex, or VLC). This is just like watching it in your web browser, except you now also have the option to watch it on your TV. Actually, some would consider it a better experience (often better audio and video quality, and fewer “annoyances”).

If you are not lucky, it will either complain that something about the link isn’t valid, or that it needs you to install additional software, or it will tell you that the video can’t be accessed without a supported provider login. In the latter case, if you do not have a provider login you are out of luck. If you have a provider login (maybe you are visiting your rich uncle that still subscribes to cable, and he’ll let you use his login and password while you’re visiting), again, use the --help option and read everything (particularly the “Authentication Options” section, and the section below it).

If something about the link isn’t valid, it may be that you didn’t copy the correct link from the page, or in rare cases you may need to view the page’s source code to try to find the correct link, which admittedly can be a challenge if you don’t know how to do that. Also, it could be that the site you are trying to access is unsupported. There is support for quite a few sites built in, but not for every single video site out there. The source code for the program is freely available, and it’s written in Python, so if you are a Python programmer maybe you could modify the software to support a particular site of interest.

If it complains that you don’t have ffmpeg or avconf installed, I suggest you install ffmpeg, since it works better with this program. Probably the easiest way to install ffmpeg is to use the FFmpeg Static Build that is appropriate for your operating system and CPU type. Copy the program files (ffmpeg, ffmpeg-10bit, ffprobe, ffserver, and qt-faststart) from the archive into a subdirectory that’s in your system path (/usr/local/sbin is a good choice on most systems), and make them executable. Then try running ffmpeg --help from the Linux command prompt, and if you get the message “Illegal instruction” then you probably installed the wrong version for your system (particularly if it’s running on a Raspberry Pi – on some models you apparently need to use the armel build, and on others the armhf build). If you downloaded the wrong one, just delete the ffmpeg files from wherever you copied them, and start over with the other build.

If, when running the main program it appears as if it is going to work, but then fails with an error message similar to “Failed to resolve hostname” and indicates that the error came from ffmpeg, you probably need to install nscd (the readme.txt file in the FFmpeg static build archive notes that “A limitation of statically linking glibc is the loss of DNS resolution. Installing nscd through your package manager will fix this…”). To do that under Debian, Raspbian, Ubuntu, or similar distributions just do

sudo apt-get install nscd

If you are a Linux command line hater, and are running Ubuntu 16.04 or newer, this article explains how you can install a front-end GUI for the program.

When running the program, if you use one of the subtitle downloading options such as --all-subs, the subtitles will be downloaded in a separate file. In Kodi, if the subtitles file has a .srt extension and the exact same name as the video file except for the extension, Kodi will find and use it. Unfortunately, the subtitles obtained by this program are often in a different format that Kodi doesn’t understand (most I have seen have a .tt extension). You can convert most other subtitle formats to .srt files using a python script named pycaption. Download it and install it using the included script. The usage is:

pycaption original_subtitles_file.ext --srt >

An alternative PHP script that will download video from a few sites not supported by the program mentioned above is described on this page. However, that script is a bit more difficult to use, especially the first time.

Failing all of that, many show pages will provide links to places where you can buy an individual episode, often for a fairly low price. But if you are like me, it really burns you to pay for an episode that you would have been able to watch for free if the PVR software had worked correctly, or if a stupid local broadcaster hadn’t decided to pre-empt the network show you really wanted to see in favor of some crappy locally-produced content. So, I do tend to like to have alternatives, just in case something happens that causes my PVR software to not record a show. Also, if you subscribe to Netflix, Hulu, or a similar service, don’t forget to check them, since they may have the show you missed.

Now, someone is probably going to ask whether the software mentioned in the linked article is legal. Well, here is the thing, I am not a lawyer, and the laws vary throughout countries in North America. What might be unquestionably legal in one jurisdiction might be illegal in another. This is content that is made available on web sites, and if you just watch the show and delete the file afterwards then you are essentially doing more or less the same thing a browser does, just in a more manual manner, but that may or may not matter as far as the law is concerned. Or to put it another way, this software does exactly what a PVR does, except for some web-based content rather than over-the-air TV. But to repeat – I am not a lawyer, so if this is something that concerns you, you should ask your lawyer. Just be aware that the use of this software may or may not be legal where you live, and I assume no responsibility whatsoever if you choose to use it without bothering to verify whether it’s legal to use where you live. That said, it is NOT peer-to-peer software, so the likelihood that you will get in any trouble for using it is probably rather small.

One other thing you need to be aware of is that many videos are huge – some may be multiple gigabytes, which if you have a usage cap on your ISP connection could be bad news for you (although, keep in mind that you are probably downloading fewer “annoyances” than if you watched it in your web browser, so there’s that). Be aware of the size of the files you are watching! Don’t go hog wild and pull in everything you can think of (this also applies to video you watch in your web browser, by the way – quite a bit of it is more data-intensive than you think, particularly if it’s HD content). It’s always better to record a show direct from a satellite or over-the-air channel when possible, because those shows will not impact your ISP usage cap. Software like this should be used only as a last resort, when other options aren’t available.

And, one drawback of this type of software is that, as far as I am aware, there is no way to schedule shows in advance and have new episodes downloaded automatically when they appear. I am sure that the programmers in the crowd could probably write some kind of script for a specific channel that would find the link for the most recent show on a page and download it, if it’s not been previously downloaded, but that’s not something that’s built into this software.


What is a SAT>IP server, and can you use one in North America?

To begin, I suggest you watch this YouTube video. As someone familiar with free-to-air satellite in North America, you may not quite understand it all at first, in particular why there are four cables coming from a single satellite dish. The reason is that this was originally developed for the European market. I’ll try to walk you through the differences but to get the general overview, watch the video first:

In order to understand the need for the four cables from the dish and the four inputs on a SAT>IP server we need to talk for a moment about the differences in LNB’s as used in Europe vs. those used in North America. If you are technically-minded you may want to refer to the Wikipedia page on the Low-noise block downconverter , which I’m using as a source here.  I’m mostly quoting directly from the Wikipedia page for the following tables, with a few minor edits to make things a bit clearer (mostly converting GHz to MHz for consistency).  To start with, these are the specifications for a North American C-band LNB:

  • Local oscillator: 5,150 MHz
  • Frequency: 3,400–4,200 MHz
  • Noise figure: ranges from 25 to 100 kelvins (uses kelvin ratings as opposed to dB rating).
  • Polarization: Linear
Block Local oscillator
freq. range
Polarization Frequency band
13 V Vertical 3,400–4,200 MHz 5,150 MHz 950–1,750 MHz
18 V Horizontal 3,400–4,200 MHz 5,150 MHz 950–1,750 MHz

Note that nowadays most North American satellites use 3,700-4,200 MHz for C-band. A C-band LNB that receives the entire 3,400-4,200 MHz range is usually marketed as a “wideband” model in North America, and is generally only used to receive certain international satellites that are closer to the horizon in the eastern sky. To find the exact intermediate frequency for any given C-band frequency, subtract the C-band frequency from the local oscillator frequency of 5,150 MHz. This does mean that the higher the C-band frequency is, the lower the intermediate frequency will be. Next, these are the these are the specifications for a North American standard linear Ku-band LNB:

  • Local oscillator: 10,750 MHz
  • Frequency: 11,700–12,200 MHz
  • Noise figure: 1 dB typical
  • Polarization: Linear
Block Local oscillator
freq. range
Polarization Frequency band
13 V Vertical 11,700–12,200 MHz 10,750 MHz 950–1,450 MHz
18 V Horizontal 11,700–12,200 MHz 10,750 MHz 950–1,450 MHz

What I want to point out here is that the intermediate frequency range is roughly the same for C-Band and Ku-band, the only difference being that the Ku band has a narrower frequency range. So when we in North America set up a receiver or a tuner for DVB-S or DVB-S2 signals, the only control sent to the LNB is for the voltage, in order to make it switch polarity. The LNB then sends the entire local oscillator bandwidth back to the receiver or tuner, and it is up to the receiver or tuner to pick out the correct frequency, in much the same way that a traditional TV receiver picks out one TV channel out of all those coming in over the antenna or cable.

One other difference between C-Band and Ku-Band is the way you exact intermediate frequency for any given Ku-band frequency. For Ku, you start with the Ku-band frequency and subtract the local oscillator frequency of 10,750 MHz, which is the reverse of the way it’s done for C-band. Don’t ask why, that’s just the way it is!

This brings us to the Universal LNB, or as it’s sometimes referred to in Europe, the “Astra” LNB. As Wikipedia notes:

A Universal LNB has a switchable local oscillator frequency of 9.75/10.60 GHz to provide two modes of operation: low band reception (10.70–11.70 GHz) and high band reception (11.70–12.75 GHz). The local oscillator frequency is switched in response to a 22 kHz signal superimposed on the supply voltage from the connected receiver. Along with the supply voltage level used to switch between polarizations, this enables a Universal LNB to receive both polarizations (Vertical and Horizontal) and the full range of frequencies in the satellite Ku band under the control of the receiver, in four sub-bands.

They do this because Astra uses a wider range of frequencies for Ku, starting at 10,700 MHz as in North America, but ending at 12,750 MHz. If you want the details behind this see the Wikipedia article, but the specs for the Universal LNB used in Europe are as follows:

  • Noise figure: 0.2 dB typical
  • Polarization: Linear
Supply Block Local oscillator
freq. range
Voltage Tone Polarization Frequency band
13 V 0 kHz Vertical 10,700–11,700 MHz, low 9,750 MHz 950–1,950 MHz
18 V 0 kHz Horizontal 10,700–11,700 MHz, low 9,750 MHz 950–1,950 MHz
13 V 22 kHz Vertical 11,700–12,750 MHz, high 10,600 MHz 1,100–2,150 MHz
18 V 22 kHz Horizontal 11,700–12,750 MHz, high 10,600 MHz 1,100–2,150 MHz

Some North American satellite enthusiasts have been using 22 kHz tone switches in their setups for years, probably without knowing the original purpose for them. When we use them here, it’s typically to switch between two LNB’s, such as a C-band and a Ku-band LNB. But in Europe, they were used to switch between the upper and lower half of their expanded Ku band.

It’s not that uncommon to find Universal LNB’s with four coaxial outputs.  Although in most cases the outputs can be individually switched by sending the correct voltage and by the presence of absence of the 22 kHz tone, in many cases they were used in systems where each output would be dedicated to one of the four possible states.  That would make the entire European Ku band on a single Ku satellite available to a satellite distribution system.

A universal LNB can be used in North America if you have a compatible receiver or tuner, but remember that our Ku band only goes up to 12,200 so you won’t find any Ku-band signals above that.

This explains why most SAT>IP servers have four coaxial inputs, typically labelled V/L, V/H, H/L, and H/H. The letter before the slash is the polarity (Vertical or Horizontal) and the letter after the slash is the band (L=10,700–11,700 MHz, H=11,700–12,750 MHz). These would typically be connected to a quad output LNB that is pointed at a single satellite.

So, this fits in with the European idea of free-to-air – typically you get all your content from a single Ku-band satellite. Generally speaking, the major reason SAT>IP was developed was so that people didn’t need to run two or four coaxial cables to every receiver in their home.  Instead, the SAT>IP server would stream the desired channels to the various computers and devices on the local network.  If you’re familiar with a HDHomeRun device, it’s similar to that, but for satellite frequencies.

So hopefully now the video at the start of the article makes more sense, if you are one of those who’s never understood the European way of doing things.

The question you may be asking is, could we use a SAT>IP server in North America with our version of Free-To-Air? And my answer to that would be maybe, but in limited circumstances. I don’t know of anyone that’s importing SAT>IP equipment into North America, probably because at the present it would have limited usefulness here. As far as I can tell, SAT>IP servers have no way of dealing with a moveable dish – they expect the dish to be permanently pointed to a single satellite. And beyond that, I don’t know if any of them can be configured for use with a C-Band or linear Ku-band LNB. You can get dual or quad output Universal Ku-band LNB’s in North America, and by doing the math you could perhaps use a dual-output C-band LNB by configuring the server to use an equivalent Ku-band frequency (one that would be converted to the same local oscillator frequency) but you’d still be limited to pointing the dish at a single satellite.

There’s probably no reason you could not have more than one SAT>IP server on the local network, in order to receive signals from multiple satellites (assuming you have more than one satellite dish), but I have no personal experience with such devices so I cannot say that with certainty at this point in time.  And another thing I don’t know is whether you can configure a SAT>IP server with four inputs to use multiple sources from different satellites.  Here in North America it would make a lot more sense to use two of the inputs with a dual output linear Ku-band LNB, and the other two inputs with a dual output C-band LNB or a different dual output linear Ku-band LNB.  There’s no reason either of these scenarios would not be technically possible, but if the software or firmware in the SAT>IP server doesn’t know about C-band or the North American Ku band, it would be a lot more difficult to configure.

There probably are situations a SAT>IP might be useful. If you are primarily interested in a channel or channels from a single satellite, and particularly if in order to receive that satellite you need to position the dish at some distance from your house, it might be worth using SAT>IP to backhaul the signals to your home instead of running a long run of RG-6 or RG-11 cable. You’d need to use server that’s in a waterproof, weather-resistant enclosure, and you might also want to use fiber optic cable for the run, although you’d still need some way to get power to your equipment enclosure. The same is true if you attempt to use some type of WiFi link; you still need power for the equipment at both ends.

I had originally discussed something like this in my article Minisatip: A possible way to extend the distance between a satellite dish and your TVHeadEnd (or other backend) server but at the time I wrote that, I really had no conception of what SAT>IP actually was (not that I consider myself any kind of expert on it now). The difference between what I was taking about in that article and in this one is that in the earlier article the emphasis was on software running on some kind of dedicated computer, whereas here I’m talking about a hardware device specifically built to be a SAT>IP server.

SAT>IP Tuners in TVHeadEnd

SAT>IP Tuners in TVHeadEnd

So where would you get such a hardware device? There is a list of them (and other types of SAT>IP products) at the site. The same site has links to software and hardware that can be used to view the streams. But keep in mind that if you are running a PVR backend, such as a recent version of TVHeadEnd, it may already have the capability to receive and record SAT>IP streams, and to pass on the live streams to your frontend systems. In fact, I believe the newest versions of TVHeadEnd can detect a SAT>IP server on the network and use it as a tuner, in much the same way that it would find and use a HDHomeRun device.  As an aside, TVHeadEnd can also act as a SAT>IP server.

One thing I find especially interesting are the new (and possibly as yet unreleased) SAT>IP LNB units, such as this one from the Danish company TRIAX:

Triax SAT>IP LNBUnder the boot in the above photo there is a standard Ethernet jack:

Underside of Triax SAT>IP LNB with boot removed

I’m not sure if this LNB is available for purchase yet, because I can’t find it offered for sale on any site anywhere in the world, but from the product specifications I’ve read, it appears that this is a combination LNB and SAT>IP server with eight (8) tuners!  So, just by connecting this to the Internet (most likely through some type of power insertion device – the specifications state it is “Powered via 802.3@rev 2012 PoE type 1, class 2” but do not mention whether a power supply is included), you have eight Ku band tuners available from a single satellite, with no need for an additional SAT>IP server.  Now, if only they would build a C-band LNB with similar capabilities!  We could skip the tuner cards (with their buggy driver issues) and we’d never need to worry about RG-6 cable loss, although since underground Cat 5e or Cat 6 is limited to about 100 meters (328 feet) in length (and actually less than that as a practical matter, since packet loss can get rather significant as you approach 100 meters), you probably would want to run fiber optic cable for any extended length.

SAT>IP is an interesting technology and although it’s not yet gained wide acceptance among free-to-air users in North America, the day may come when it is more useful here, particularly for those with fixed dishes permanently parked on one location in the satellite arc. I will caution you that if you decide to order any equipment from overseas in order to experiment with the technology, it will probably not come with a North American-style power supply that plugs into a 120 VAC outlet. Unless you feel like installing a 240 volt outlet for the server, I’d check to make sure it uses a “wall wart” type power supply that can be replaced with one of similar output ratings, but that will plug into a standard USA/Canada power outlet.

The never final, always subject to revision article on how to build a Satellite TV PVR distribution system using Tvheadend


I’ve wanted to write an article to help new users set up a working PVR backend system for our peculiar type of North American free-to-air satellite for quite some time, but have never felt as though I had the all the pieces to do it right. I finally decided that the only way it would ever get written is if I start it, and then add to it as I remember things I had to do, or find out new things I should have done. Therefore, this article should probably never be considered finished – there is always the chance that I will edit it or add to it. And if you leave a comment on the article, I just might incorporate your comments into one of the edits.

First of all, I should probably explain why you would want to build a Satellite TV PVR distribution system using Tvheadend. And actually, it’s probably easier to explain why you wouldn’t want to do this. You probably would not want to do this if:

  • You have a very limited budget for satellite TV and don’t want to invest in any new equipment.
  • You have, or plan to purchase, a standalone satellite TV receiver that will receive all the satellite channels you’d like to receive.
  • You don’t care about recording shows, or your satellite TV receiver gives you a reliable way to record shows.
  • You never want to watch live TV or recordings on any TV’s or devices except for the TV directly connected to your satellite receiver.
  • You never have scheduling conflicts where you cannot watch or record a show you’d like to see because your receiver’s tuner is already in use.
  • You don’t have multiple dishes, or you do have more than one dish but a simple DiSEqC and/or tone switch meets your needs for connecting your dishes.
  • You either don’t care about the types of signals that some find difficult to receive, such as 4:2:2 or 16APSK, or your satellite receiver allows you to receive such signals.
  • Your receiver gives you a reliable way to schedule shows you want to record, and doesn’t make you wish you had a better guide (or any guide at all) to use when scheduling recordings.
  • If you use a regular TV antenna for local channels, your receiver also allows you to watch or record shows from those channels, or you have another way to record shows from those channels.
  • You are under the impression that this type of system will let you pirate signals from subscription satellite TV services. It won’t, particularly in North America. This is only for unencrypted free and legal satellite TV.

If the first item on the above list is true, then you probably should stop reading now. Building a backend system for satellite TV doesn’t need to be super expensive, particularly if you have a local source for gently used desktop computers that are new enough to have PCIe card slots (note the “e”, the older PCI slots won’t work), and there are compromises you can make to bring the cost even lower, but if you are living paycheck to paycheck then this might be a major expenditure for you. The one advantage of standalone free-to-air (FTA) satellite receivers is that they are dirt cheap nowadays, although that usually also means the quality is not that high. But at those prices (sometimes less than $50) you could try a few and still come out ahead.

Otherwise, if any of the other items on the above list is NOT true for you, then you probably will want to read on.

While writing this article I have made the assumption that the reader already has some experience with C-band and/or Ku-band satellite TV, and already has one or more satellite dishes and a satellite TV receiver. Therefore, I will not be explaining some of the essentials of setting up a satellite dish, peaking the dish and LNB for best reception, etc. It would be my recommendation that even if you know you want to do what is described in this article, you at least start out with a cheap standalone free-to-air (FTA) satellite receiver and get your feet wet with that. It is much more difficult to set up and tune a new dish for peak reception if you don’t have a FTA receiver available, so you can see if you’re getting a good signal from your dish(es).


I need to cover this early because there is still a lot of confusion about this. For those of you used to computers and networking, you can think of the backend as roughly analogous to a server, and the frontend as roughly analogous to a client. A better way to describe this is as follows, but please keep in mind that these are generalizations and that certain specific setups may not fit into the mold I am about to describe.

As I wrote in the article, What is the best backend software to use for a Free-To-Air satellite TV system?,

If you use a program like Kodi to watch live or recorded television, you’re probably already familiar with the backend/fronted model. To put is simply, the backend is a server that communicates with the tuners, such as a tuner card or USB-connected tuner, or even a network tuner such as a HDHomeRun. The backend system can sit anywhere on the local network and communicates with one or many frontends. The backend handles streaming live programming, or recording it for viewing at a later time. In contrast, the frontend is run on a computer that often connects to a television set via a HDMI cable. It displays live or recorded programming, and usually gives the user a way to schedule programs for recording and perform some other administrative tasks. Some tasks can be performed from either the backend or frontend, some from the backend only, and some from the frontend only. But generally speaking, the frontend is what the user most commonly interacts with after the initial configuration is finished.

But remember, it is the backend that performs the crucial task of communicating with the tuners, which includes sending any control commands that might be necessary. So, for example, if you have any switches (DiSEqC or 22kHz tone) between the tuner and your LNB’s, the backend will control them. If you have a USALS or DiSEqC controlled motor, the backend will need to deal with that as well.


Note that it is usually possible to run a backend and a frontend on the same computer – you don’t need two computers for the purpose, and if the backend computer has a HDMI output and is in a location close enough to your TV that you can connect a HDMI cable between the two, there’s generally no reason not to run a frontend program on the same system as the backend. Some software installers set up a backend and frontend by default.

In other words, the backend is the “brains” of your setup. The client software, which for most users is Kodi, interacts with the backend. This article is NOT about the client software, however. The only thing I will say here about Kodi is that you should NEVER buy a small box that comes pre-loaded with Kodi at a county fair or from someone on Craigslist, or in some equally questionable situation where the seller can take your money and disappear. These boxes are typically sold with a number of piracy addons included, most of which are unsupported and some of which can be a security risk for that system and for others on your local network. The mere use of those addons can also make you guilty of copyright infringement, which could cause you to incur legal fees or financial penalties, or could get your Internet service shut off. Just because you might know someone who uses such a box and hasn’t yet had any of those issues doesn’t mean it won’t happen to you. The Kodi developers hate these boxes because they say it gives the Kodi project a bad name; of course it must also be said that a few of the Kodi developers are perfectly capable of giving the Kodi project a bad name without any outside help, but that’s a whole other discussion. It’s okay to use a small, inexpensive box for Kodi, but it should be one on which YOU install the operating system (Windows or Ubuntu Linux, for example) and where YOU install Kodi, and and you do NOT install addons from any dicey repositories, or for that matter addons from any source other than the official Kodi repositories.

Most users have only one backend system (in this case it will be the system running Tvheadend), but will have one or more frontend systems, only one of which may be on the same computer as the backend. A frontend system can be a dedicated computer connected to a television receiver, in which case it’s sometimes referred to as a HTPC (Home Theater PC), or simply the Kodi software running on a general purpose computer, a tablet computer, or possibly even a phone. Kodi runs on many different platforms, so it’s possible to have many different types of frontend systems.

The Kodi Wiki has a Live TV and PVR/DVR Setup Guide but unfortunately the information there is not entirely accurate, and in particular it does not at all address the reception of Free-To-Air satellite signals, nor how to get free channel guide data. You may want to read it to get a more complete explanation of the relationship between Kodi and PVR backend software, but when they get into the “nuts and bolts” of how it all works, some of the information is misleading, if only because hardware and software changes over time. And that’s all I will say about frontends for the moment.


There are many possible choices here, but I recommend a standard desktop style computer that contains a motherboard with at least three or four PCIe card slots (again, note the “e”, the older PCI slots aren’t compatible with the newer PCIe cards). You only need one PCIe card slot for each PCIe card you will install, but once you get your first tuner card working successfully there’s at least a chance you will want more sooner or later. Speaking of which, you will need one or more DVB-S2 tuner cards. In North America, if you don’t want to import cards directly from overseas, your choices are for tuner cards are somewhat limited, and you will probably wind up using the ones made by TBS Technologies, only because they are the most readily available.

Let me once again quote from my earlier article (the same one I quoted from above):

Also, you need to be aware of the limitations of various tuners. Some older DVB-S tuners cannot receive DVB-S2 signals, and some DVB-S2 cards cannot receive 16APSK signals (if you really want to receive one of the handful of 16APSK signals on North American satellites, and you are considering the purchase of a TBS tuner card, it is strongly recommended that you purchase one of the “professional” grade models). Some tuner brands do not support their tuners with updated drivers, meaning that people may recommend you use some unofficial driver from a questionable source. Or, if you want to use more than one tuner card from the same manufacturer or of the same model in the same backend system, you may find that’s impossible because the driver programmers apparently never anticipated that someone might like their tuners enough to want to buy a second one (I guess that lets you know what they think of their product). The may be certain tuner models that will not work at all under Linux (you can find lists of DVB-S2 tuners known to work in Linux by following the links on this page, but just because a particular tuner isn’t mentioned does not necessarily mean it won’t work – it may just be that no one ever bothered to add it to the page). Problems caused by tuners or by tuner drivers will likely affect any backend software you might choose to use.

With TBS tuner cards in particular, you need to be careful that they are not sharing interrupts (IRQs) with other hardware devices in your system. Also, if you have a newer model TBS card and find that it will not scan muxes to find channels, try this. If you find that many of your recordings have bad timing information, and it’s not due to a weak signal, it is sometimes possible to fix that by changing a setting in Tvheadend.

If you start asking around about which tuner you should purchase, please keep in mind that the “Linux snobs” (the type that will only point you to man pages and Google when you need help) may prefer a particular piece of hardware, but only because they’ve had enough Linux experience to work around any issues they encounter. Just because they could get a particular tuner to sing and dance doesn’t mean that you can, unless you have a similar level of Linux experience. If you ask in a Linux forum which tuner is best, and make a purchasing decision based on the responses you receive, and you are relatively inexperienced with Linux (or you are simply not a Linux devotee), there is a real good chance that you that you will not be happy with your purchase. One tip, no matter how much they may be recommended by a particular user or group of users, avoid older PCI cards – any tuner cards you purchase now should be PCIe (note the “e”) cards.

Unfortunately, not all PCIe tuner cards are compatible with all motherboards. I’ve had good luck with a MSI motherboard (specifically the model B85M-G43, although I’m sure many other models will work equally well), but when I had tried using the same tuner card in a particular Gigabyte motherboard it would not work. A real Linux expert perhaps could have figured out the reason why, but since I’m not a Linux expert it was a lot easier to just try a different motherboard. Had I known about this thread in the TBS forum, I might have tried the suggestion there to see if I could get it to work.

There are also USB-connected external tuners, and while some users have had no problems using these, several others have reported problems with overheating leading to premature failure. Also, with certain USB-connected tuners there is an extra step of installing firmware, in addition to the drivers, at least when using Linux as the operating system. I’ve never used a USB-connected tuner, but if you decide to try one, I’d at least keep it in a well-ventilated place.

If you want to build a reliable system, I definitely recommend a desktop computer that will accept the PCIe cards. If you choose to “cheap out” and use something smaller, at least please be sure it does not have an ARM-based processor. You can get Tvheadend to run on such systems, but certain things will be more difficult than they should be, and you may also find you have more bad recordings and other weird issues. Note that you don’t need a high-powered gaming computer to run Tvheadend, in fact most of what Tvheadend does will not put much stress on the CPU(s). An older standard desktop model will probably work just fine, as long as it has the PCIe card slots. The computer must be capable of running Linux, so generally speaking, that leaves out boxes that run Android only.

Although there may have been some custom builds of Tvheadend for specific smaller devices, I recommend that new users avoid them. Once you have built your first Tvheadend system and see how it works, then you’re ready for the challenge of installing it on something smaller and with fewer resources, if that’s what floats your boat. But when starting out, you don’t need any additional challenges. Remember, a system that works fine for terrestrial television may not be at all suitable for free-to-air satellite TV reception, due to the difficulty of installing drivers required by the tuner cards, or the difficulty of installing and running additional software required to get program guide data.

At the time I am writing this I suggest using TBS tuner cards. The “consumer grade” ones are fine for most transponders but if you are going to try to receive anything in 16APSK or 32APSK format, I strongly recommend going with a “professional grade” card (this will also be true if you are going to try receiving C-band signals on a 6-foot or smaller dish). Each card will have between one and four tuners, and unless you are restricted in some way as to the number of dishes you can have on your property, you might want to think about getting a quad (four) tuner model. You may find that even four tuners aren’t enough, but if you can afford it I’d at least start out with a quad tuner card. If money is no object, I’d start with the TBS6908 Professional DVB-S2 Quad Tuner PCIe Card. When paired with a 10 foot (or larger) dish and a good LNB you should be able to receive just about any unencrypted service up there. However, many users will opt for a less expensive “consumer grade” model, and that’s fine, just don’t expect great results on “difficult” signals such as 16APSK or 32APSK signals.

Beware of satellite dealers that have old stock they are trying to sell. In some cases the older cards work perfectly fine, but may not receive newer formats (a card that only receives DVB-S, and not DVB-S2 is nearly worthless nowadays). In other cases the cards may be dogs that no one would buy because they never worked that well, or ONLY worked well for extreme Linux geeks that dream in code and talk in a language that you or I would only understand about 10% of, at best. The sort of people who can write their own drivers for tuner cards, in other words. Such people can make some of the more obscure tuner cards sing and dance, figuratively speaking, but their preferred choice for tuner cards may not be the best choice for you if, like most of us, you intend to use the stock drivers provided with the device. I hate saying anything bad about these guys, because I’m sure they are extremely intelligent, but they should probably never give advice to us mere mortals on which tuner cards to buy, because we just want something that works without a lot of fuss, and we don’t want to have to rewrite the tuner driver or poke around in the bowels of Linux to make a tuner card work!

Speaking of tuner card drivers, if you are somewhat more of a Linux expert than I (which isn’t exactly a high standard, since I struggle with Linux), you should be aware that TBS DVB-S2 tuner users may now be able to use open source drivers.


In order to install Tvheadend you will first need to install the Linux operating system. If you don’t plan on using the same computer for both your backend and frontend, I suggest using Ubuntu Server. You do not need a desktop on your backend server. However, if you also want to install Kodi on the same computer, then install regular Ubuntu. In either case you should install a Long-Term Support (LTS) release, so you’re not forced to upgrade the software prematurely.

If you are using TBS tuner cards, I have found it necessary to do this after installing Ubuntu, in order to avoid serious errors while building the drivers (at least this was true under Ubuntu 14.04):

sudo apt-get update
sudo apt-get install linux-headers-`uname -r`
sudo apt-get install make gcc

I’m not sure whether it’s still necessary to do this under Ubuntu 16.04, though it probably couldn’t hurt. Even after that, you may see warnings and other notices while the TBS drivers are compiling, but usually they will still work.

One thing I would like to warn you about is that there are distributions out there called “OpenElec” or “LibreElec.” I most emphatically DO NOT recommend these, unless you simply must have the absolute easiest installation, and you don’t care about the fact that you won’t be able to get to a Linux command prompt easily. And before you say you don’t care about that, please understand there will be consequences, such as not being easily able to get program guide data (and that is doubly true if you also ignored my advice not to use an ARM-based processor). Quoting Robert Cameron in the Tvheadend forum:

… And if you do decide to go with a PVR, for everyone’s sake please ditch LibreELEC: it is a poor excuse for a proper OS and will cause you nothing but problems trying to work around its limitations (such as inability to easily upgrade core components, like a current and proper build of Tvheadend).

If you are installing something for a senior citizen that knows absolutely nothing about computers, doesn’t want to know anything about them, will just accept any limitations they encounter because they don’t know any better, AND you won’t be around to help them at all, then maybe you can make a case for using one of the “-Elec” distributions, but please don’t come crying when you are frustrated as hell because you can’t do anything in Linux. Please use a LTS build of Ubuntu Server or Ubuntu Desktop if you don’t like dealing with problems.

Assuming you have followed the manufacturer’s instructions while installing your tuner card, you will probably find that you need to install drivers for your tuner, and they should have given you the driver software or shown you where to get it online. Once again I will quote from my earlier article:

One downside of using any Linux-based backend is that you may need to install drivers, either to get your tuner to work at all, or to get it to work at peak efficiency. And if you are used to installing drivers in Windows, where it’s more or less a point-and-click type of operation, you may find that the procedure for doing it under Linux is a bit off-putting. For certain tuner brands, it is not very difficult if you can follow instructions (for example, this page explains how to do a TBS driver install under Ubuntu 11.10, 12.04, 12.10 and 13.04 (TBS6921 and other)). But not everyone finds it easy; sometimes there are entire forum threads about driver installation. If you’ve never touched Linux before in your life, then you may want to seek help from an experienced Linux user. Make sure you watch how it’s done and take notes, because you will likely need to do it again if you ever upgrade the Linux kernel on your system (and Ubuntu loves to push kernel updates every so often, so don’t just blindly accept a software update 10 minutes before you have something scheduled to record!). This bash script can help simplify the task of rebuilding the TBS drivers after a kernel update.

Note that the bash script mentioned in the previous paragraph is for building the standard closed-source TBS tuner drivers. If you choose to use the open source drivers, you’re probably enough of a Linux expert to know how to rebuild them without needing a script (but if you happen to find one, please let me know in the comments!).

After you have installed the drivers and rebooted the system, you can discover whether your tuner cards are being recognized by the operating system by using either or both of these two commands:

dmesg | grep -i dvb
ls -l /dev/dvb

If you have installed TBS Tuner cards, before you go any further please read these articles, which will help you avoid some pitfalls down the road:

At the very least, TBS card owners should read the first article in the above list now, and keep the others in mind for future reference.

Also, if you are using a version of Ubuntu newer than 14.04, it may have come with the package unattended-upgrades installed by default.  With the default settings, this package will install certain types of updates automatically, including Linux kernel updates.  The problem with that is that if you have received a kernel update and then reboot the system for any reason, and you have not reinstalled the TBS drivers since the update was installed, it will use the new kernel and you will not have any tuners available (so you will not be able to view channels, and scheduled recordings might be missed).  And if you ssh into the system it will print *** System restart required *** in your terminal window, which might cause you to reboot the system without thinking about the fact that you then need to reinstall the drivers.  To avoid this problem, you may wish to disable unattended upgrades.  The easiest way to do this is to edit the file /etc/apt/apt.conf.d/50unattended-upgrades and comment out the lines that are allowing the upgrades, such as these:

// “${distro_id}:${distro_codename}”;
// “${distro_id}:${distro_codename}-security”;
// “${distro_id}ESM:${distro_codename}”;

If any of these lines do not have the // characters at the start, place them there and save the file. Note you will probably need to use sudo to edit this file, for example sudo nano /etc/apt/apt.conf.d/50unattended-upgrades. See this page for more information on disabling unattended upgrades, though I do not recommend the “Method Three” shown there.

Once you have installed the tuner drivers and verified that the operating system can detect them, it is time to install Tvheadend. Before we go any further, I should point out that Tvheadend is an evolving program, and as with many programs, when newer versions are released, configuration options may change, and often new options are added. In most cases, if you see a new option and you don’t know what it’s for, you can safely leave it at the default setting. While writing this article I am using Tvheadend 4.0.9, which is the current stable version. There have long been rumors of an upcoming 4.2 release, but it hasn’t happened yet and when it is released, it will probably be some time before I get around to installing it. When it does appear, I’m sure the interface will be changed up in some ways. I have heard, for example, that there will be a configuration wizard that will make configuration easier. While I hope that’s true, I have my doubts about it including a setup for North American free-to-air satellite channels. My guess is that we in North America will need to skip the wizard, and use the manual configuration as I will explain here. I hope I’m wrong about that; it would be great if this process were easier.

The installation instructions for installing Tvheadend under Ubuntu are here. You will need to choose a repository, and I suggest either the “stable” or “unstable” repositories. In the case of Tvheadend, “unstable” isn’t all that unstable, compared to what that means in some other software projects. Many people run the unstable version to get the latest software improvements, but that is entirely up to you. If you have very little familiarity with Linux, then it’s probably best to stick to the stable version. I am currently running the stable version (4.0.9) as I write this.


There are many videos and web pages on configuring Tvheadend, and many of them will confuse you more than help you, especially if it’s your first exposure to Tvheadend. That is because they were either based on old versions of Tvheadend, which had a somewhat different interface, or because they assume that Tvheadend is running on an OpenElec or LibreElec system, which as mentioned above is not recommended. Or, they may have been intended for terrestrial TV viewers, which has a slightly different configuration, or for the European version of free-to-air satellite, which is different in many ways from what we have in North America (for a decent explanation of the differences, there is a Wikipedia article on Free-To-Air – just skip to the section on North America and read that entire section).

Setting up Tvheadend for the North American style of Free-To-Air satellite is in some ways similar to configuring it for over-the-air reception using an ATSC tuner, but there are some important differences. In most cases setup will be a lot more manual because you will need to enter in the details for each satellite and each transponder manually.

There are a couple of terms that Tvheadend uses that may confuse you during configuration. One is “Networks”, and the other is “Muxes”. These easiest way to think about these is as follows:

A “Network” in most cases will be associated with a single satellite, whether you have one or more LNB’s (or LNB outputs, in the case of dual or quad output LNB’s) receiving from that satellite. So for example, if you have two dishes and one is pointed at Galaxy 19 and the other at AMC 21, you would make two networks and call them “Galaxy 19” or “G19”, and “AMC 21” or just “A21”. The name is not important, so use something meaningful to you, and in most cases that will be the satellite name. You could also use positions, such as “97W” and “125W”. The point is, the word “Network” has nothing to do with what we think of as a television network, instead it is all the sources that have the same transponders available. So, if for some reason you have two dishes aimed at the same satellite and they could receive the same channels, those would be under the same “Network”. On the other hand, if you have a moveable dish, you could have several “Networks” associated with that dish. This will become more clear as we look at the configuration.

A “Mux”, when associated with free-to-air satellite, is the same thing as a transponder, which (if you’re not too nit-picky) is the same thing as a specific frequency allocation on a satellite. When a Mux is created and scanned, it should show all the active services (TV, radio, and data channels) available on the transponder, which will be on a specific frequency on the satellite. To use a specific example, as I write this, on AMC 21, Ku band, there is a transponder, or “Mux” in Tvheadend terminology, at 12180 V that contains several PBS channels. In that case, you can think of all the channels on the 12180 frequency as the “Mux”. When used in relation to terrestrial TV, a “Mux” is a single physical channel on a specific frequency, which may have several virtual channels. So whether on satellite or terrestrial TV, a “Mux” is a single frequency that may contain one or more TV and/or radio channels. In Europe things can get a bit more confusing, because they can duplicate transponders across multiple satellites, but we don’t see that here in North America.

I should also mention tuners. Generally speaking it is best to have one tuner input on your backend for each LNB output you have out on a dish. But if some satellites are infrequently viewed, it would be wasteful to dedicate a single tuner to the LNB associated with that satellite. Tvheadend does support the use of 4-input DiSEqC switches, at least with TBS tuner cards. As far as I can tell, even though Tvheadend supposedly supports them, either Tvheadend or the TBS cards, I’m not sure which, have some problem controlling 22kHz tone switches. I didn’t spend much time trying to make them work, since DiSEqC switches are relatively inexpensive.

If you have a card or cards with multiple tuners (for example, if you obtained a quad tuner card), then I would suggest using fixed rather than moveable dishes if your situation allows. While Tvheadend can in theory control a dish positioner motor, I’ve not yet seen it work in practice, and I’ve never personally attempted to do it. But feel free to try; if you can get it to work, please leave a comment and let us know what you had to do. The same goes for using any type of switch other than a standard 4-input DiSEqC switch. Remember that even if Tvheadend is capable of sending the correct signals to a switch, it is also up to the tuner card and its drivers to make sure the switching signal gets sent, so what works in one installation might not work in another if different tuner cards or drivers are used.

Note that you can buy LNB’s with dual (or, more rarely, quad) outputs. By hooking each output of a LNB to a separate tuner input (either directly or through a DiSEqC switch), you can watch or record shows from different transponders (or muxes, as Tvheadend calls them) on the same satellite at the same time. Note that you can watch or record as many simultaneous channels as you like from the same transponder (mux), because the LNB and tuner card can receive a full transponder stream, and Tvheadend breaks out the channels as necessary. It’s only when you want to watch or record from two different transponders (a.k.a. muxes, a.k.a. frequencies) on the same satellite that you’d need multiple LNB outputs connected to different tuner inputs.

The more dishes, LNB outputs, and tuner inputs you have available, the more likely it is that you’ll be able to avoid scheduling conflicts, where you want to watch or record a show, but no free tuner is available because all the tuners associated with that dish are already in use.


Once Tvheadend is installed, you access its configuration pages via a web browser. The address will be port 9981 at the backend’s IP address, so if for example the backend is at you’d use in your browser’s address bar to access Tvheadend’s web interface. If Tvheadend is running on the same machine you’re using, then you can use to access it.

You will see tabs across the top of the page, and the first place you will want to go is the Configuration tab. Click on that and it will expose a new row of tabs. You need to understand this about Tvheadend, it does not expose options until a previous selection indicates you need them. So if, right after installation, you were to try to discover where you configure a DiSEqC switch, you’ll never find it because you haven’t indicated to Tvheadend that you have a DiSEqC switch, therefore it will not show you that option.

In the second row of tabs, choose DVB Inputs. This will expose a third row, which is where most of the initial configuration will be done. First, choose the TV adapters tab. You should see a list of your available tuners. If you don’t, something is probably wrong – either your tuner card is not being detected by Linux, or you don’t have the correct drivers properly installed. You will need to resolve that before continuing on. Note that if you ever come here and the tuners have disappeared, it probably means you applied a Linux kernel update and forgot to rebuild the tuner card drivers. Just rebuild and reinstall the drivers, and all should be fine again (we hope).

Now go to the Networks tab. Create one network for each UNIQUE tuner input. In other words, if you have four satellite dishes and each has a single-output LNB and your are feeding all four LNB’s into discrete tuner inputs, then you will want to have four networks. If you have two satellite dishes and each has a dual-output LNB and you are feeding all four LNB outputs into discrete tuner inputs, you will only need two networks, because two of your tuners can receive duplicate programming. To possibly simplify this, if none of your satellite dishes are moveable (or if you always leave your moveable dishes parked on the same satellite) then you need to create one network for each satellite you can receive, and that’s probably a good rule to follow even if one or more of your dishes are moveable. Also, C and Ku band LNB’s should be on separate networks, and if you receive both the C and Ku bands from the same satellite, use different network names to reflect that (you could add “-C” or “-Ku” to the name).

To create a network, click the Add button, then in the window that appears select DVB-S Network in the dropdown (don’t worry if it’s DVB-S2, in this window DVB-S covers it).
Adding a DVB-S networkIn the next window that appears, give the network a name (again, I recommend you give it the name of the satellite, or the orbital position, whichever works for you, with the “-C or “-Ku” suffix if you receive both) and UNCHECK “Network Discovery”. Leave everything else at the default for now. Then click “Create”. Repeat as necessary for each unique tuner input/satellite you can receive.

Add a DVB-S networkYou may have noticed during the Network creation process that you could have selected a pre-defined mux. You could do that, but I don’t recommend it because pre-defined mux lists are often inaccurate, and sometimes don’t distinguish between C-band and Ku-band. So if you try to use those in North America, you will likely wind up with a list of outdated or inaccurate muxes and will wind up having to delete them manually. It’s your system; you can try the pre-defined mux setting if you like, but don’t say I didn’t warn you. You may also have noticed that you can select an orbital position, but you would only need to do that if you were going to try to control a moveable dish. For a fixed-position dish, it matters not whether you select anything there.

When you have configured your networks, go back to the TV adapters tab. This is where things get a little tricky. The first thing I will say is that you need to enable each tuner by checking the “Enabled” checkbox associated with each tuner as shown in the following screenshot, and also you need to click “Save” each time you make a configuration change (I can’t tell you how many times I have forgotten to click “Save”, and then wondered why something wasn’t working). Also, most configuration pages will have settings that don’t need to be changed, in which case leaving them at the defaults is fine.

At this point I’m going to quote from a previous article that covers this topic, but please note that the images are from a slightly older version of Tvheadend, so may not correspond exactly to what you’ll see. In some cases you’ll see additional options or settings, but this covers the ones you need to change:

There are a few things that North American users should be aware of. For one thing, Tvheadend assumes you’ll be using a Universal LNB, which is not something used all that often in this part of the world. Here, you are much more likely to be using a standard (Ku band) LNB, or even a C band LNB. But when you are setting up the TV adapters, you won’t find an option for those. The trick is that you need to select “Advanced” in the SatConfig dropdown, then save it, and then you will notice that in the left hand menu tree, additional options are exposed. This is how Tvheadend seems to work; it doesn’t show you options that are not applicable to your existing configuration, so as you make the configuration more complex, more options are exposed.

TV Adapters settingsSo once you have selected the Advanced setting and clicked Save, you can expand the tree view an additional level and click on Advanced, where you will select the number of orbital positions that each tuner has access to, which is 1 if you are connecting a tuner directly to an LNB. If you are connecting to a 4 port DiSEqC then it’s 4, as shown here:Orbital Postions settingAfter you save that, then you can configure settings for each of your orbital positions, including LNB type. In North America you will probably want to select either “C-band” or “Circular 10750”. You would use the latter for any standard Ku band LNB that has a LO Frequency of 10750 MHz, even if it’s not circularly polarized. Keep in mind that this type of software (or at least the satellite tuning portion) is much more widely used in Europe and other places outside North America, and they are much more likely to be using a circularly polarized LNB than we are here.

I’m going to interrupt my quoting here to note a few things. First, just to show how much some screens can change between versions, the above screenshot was from a 3.9 version of Tvheadend. By the time we got to version 4.0.9. that “Parameters” section on the right hand side had expanded to include many more options (mostly to support moveable dishes, or so it appears) but at this point you would likely still only need to set the number of orbital positions. After you get things working on a single satellite, then if you have a moveable dish you can come back and try to configure those settings: Baby steps, as the saying goes:

New Advanced ParametersAlso, when looking at the screenshot below, the setting for Ku in North America is now “Ku 10750” rather than “Circular 10750”. And, please note the “Name” and “Networks” dropdowns in the screenshot below. I find it easiest to use the satellite name in the Name field, and then select the network corresponding with the satellite that will be received by this tuner and switch combination. So in my configuration, which does not include any moveable dishes, the “Name” and “Networks” are always the same. However, if I were trying to control a moveable dish, I would likely select a “Name” associated with the dish (such as “C-Band moveable”) and then under “Networks” select all the networks (satellites) that dish is capable of receiving. Also for a moveable dish, I’d need to select a “Rotor Type”, which for most users would probably be “USALS”. Again, please bear in mind I have never tried to use a moveable dish with Tvheadend, so the parts about the moveable dish are just conjecture on my part. Continuing on with the quote…

Tvheadend Orbital Position Settings showing C-Band LNB and Generic switch type selectedIf you are using a standard DiSEqC and/or 22 kHz tone switch, then select “Generic” for the switch type. For a four port DiSEqC switch, you would use the “Committed” dropdown and select the port there. Tvheadend uses AA, AB, BA, BB port descriptors, which correspond to DiSEqC switch ports 1, 2, 3, and 4 respectively. I had no problem using a standard 4 port DiSEqC switch (well, except that it turned out that the brand new DiSEqC switch had a bad port 4, but that’s obviously not the fault of Tvheadend or the tuner). In the screenshot below, DiSEqC port 2 (AB) is selected. Settings for any types of switches you don’t have should just be left at the default settings.

Tvheadend Generic Switch Settings showing showing DiSEqC port 2 (AB) selectedOne other consideration for North America is that it is extremely rare for the free-to-air signals to include Electronic Program Guide data. Therefore, it would be a good idea to go to Configuration | Channel / EPG | EPG Grabber and in the Over-The-Air Grabbers section, uncheck all the grabber selections. None of those will work in North America anyway, so there’s no sense burning up CPU cycles checking for EPG data that will never appear. I will have a bit more to say about getting EPG data later in this article.

Disable the Over-The-Air GrabbersI have updated the above screenshot because in addition to disabling all the grabbers, you also want to make sure that the “Force initial EPG scan at startup” box is unchecked and that all the “Over-the-air Cron multi-line” entries are removed or commented out. It’s probably worth emphasizing that Tvheadend was designed primarily for use in other parts of the world, where commercial free-to-air services are available. We don’t have anything at all like that in North America, so there are many parts of the Tvheadend interface that simply aren’t applicable to us. An example is the “CAs” tab in the above screenshot; there is no reason to ever go into that tab here in North America.

After you get your tuner(s) configured and enabled, you will want to try creating a mux and scanning it. To do this, find a reference that shows available satellite channels, such as Sathint, or check in your favorite satellite forum. Let’s say you wanted to add the PBS channels on AMC-21. You could first go to Sathint’s North & South America page and select AMC-21. On that page you would find that the main PBS feeds are on 12180 V, that the symbol rate is 30000, that the FEC is 3/4 and if you mouse over the little arrow just to the right of “3/4” you will see that it is a DVB-S2, 8PSK signal.

Sathint exampleThis is the information you will need to create a mux. Note that both the frequency and the symbol rate in such listings are expressed in short form, in other words they should rightly read 12180000 and 30000000. Many receivers and software programs will accept the shorthand version, but Tvheadend does not.

So to create a mux, click the Muxes tab, then click the Add button. A window will pop up asking you to pick a network, in this case you’d pick AMC-21 or 125W, assuming you followed my advice to name the network after the satellite. After picking the network, you will then see the following window which should be filled in as shown here:
Sample MUX settingsYou want to check the “Enabled” box. Set the EPG Scan to “Disable” because North American channels do not contain EPG data, so why make all your hardware search continuously for something that will never be found? Set the Scan Status to PEND because you want it to scan the mux to find channels. Set the Delivery System to DVBS2 because it is a DVB-S2 mux. Set the Frequency to 12180000 and the Symbol Rate to 30000000; don’t forget the extra three zeroes at the end or it won’t work. The “Polarisation” (U.K./Canadian spelling there!) is Vertical, so pick V. The modulation is 8PSK, which Tvheadend presents as PSK/8 for some reason. The FEC is 3/4. The Rolloff can almost always be left set to AUTO. The other settings can be left at the defaults.

Try not to use AUTO for any setting other than Rolloff; Tvheadend is not very good at auto-detecting settings, particularly with 8PSK and higher signals. With QPSK signals it will often detect the FEC if you leave that set to AUTO, but if you know the FEC it’s always better to put it in. But, please be aware that data you find online isn’t always accurate; on a few occasions I’ve found channel listings containing incorrect FEC information.

Note: This guide was written using Tvheadend 4.0.9, but if you are setting up Tvheadend 4.2 or later there are some new checkboxes you need to know about, that you can only see if you are using the “Expert” view level.  The screenshot below shows an unconfigured mux, but does show the locations of the new checkboxes.  In North America you are probably going to need to check both of these.  If you don’t, some or all services on a mux may not scan in, or later on when you attempt to watch a channel on that mux, you may get “No input source available for subscription” errors or other errors.

UNCONFIGURED Add Mux screen showing new checkboxes in Tvheadend 4.2

When you click “Create” it should create the Mux and then if all goes well, a few seconds later it will start scanning the Mux to find channels. Watch the two columns labelled “Scan Status” and “Scan Result”, when the “Scan Status” returns to “IDLE” and the “Scan Result” is OK, that means it has successfully scanned the transponder. If it actually found any services (potential channels), the number found will be listed in the “# Services” column.

If, instead of OK, you see the word FAIL for the scan result, that means either the mux or the tuner were not configured properly, or the tuner didn’t detect any signal (or the signal strength was too low). Or it could be a timeout issue – if you are using a TBS card, see Tvheadend users, if your TBS card will not scan muxes to find channels, try this. Remember that satellite signals can come and go without any advance warning, and in particular remember that transponders that are active on weekdays sometimes are taken down on the weekends. If your first attempt to scan a mux is a failure, just try another. If you also have a satellite receiver, temporarily connect it to the dish and make sure the transponder you’re trying to receive is actually there.

Assuming the mux scanned correctly, go to the Services page and you should see the newly-scanned services. You might want to sort the list by Mux to find them easily, if other muxes have been previously scanned.
Example Services pageThere is one thing that is set by default that really should be changed in North America, but before I go into that I want to point out something in the above screenshot. Note at the lower right-hand corner of the screenshot there is a small button with two caret symbols (^) on it. If you click that, it will open a debugging window at the bottom of the screen that shows you what Tvheadend is doing in the background. For example, if you open that window before you scan a mux for channels, it will show you which tuner it’s using and other information that could possibly be useful in determining why a scan fails. If you open it while importing program guide data, it will show you statistics on what it’s imported and whether it encountered any problems. This can be quite useful when you are trying to diagnose a problem.

But getting back to the problem, in the Automatic Checking column in the above screenshot, note that it says “Auto Check Enabled”. What this means is that every so often, Tvheadend will check for the service presence, in other words, it will look to see if that service is still there. If it’s not found, this field will change to “Missing In PAT/SDT” and then you won’t be able to tune it in or watch it, because Tvheadend believes it no longer exists. The problem in North America is that services can disappear for a time, for any of several reasons. One is that some feed channels (channels that send feeds of smaller network or syndicated programs) often stop uplinking to their transponders on weekends, to save energy when nothing’s being transmitted. Another very common one, especially in Canada and the northern United States, is a huge snowstorm that dumps so much snow on the dish that reception is severely impeded. And, if you use a moveable dish, you will of course have no service from the satellites the dish isn’t pointed at. This type of check may make sense in sunny Spain, but not in North America. Fortunately this check can be disabled for any or all services, but unfortunately it’s a pain in the ass to do it because you have to do it for each individual service.

There are two ways to disable this check, and I will tell you about both of them because this is common to other parts of the Tvheadend interface. The first is to highlight a service and click Edit. A window will pop up and you can pick “Auto Check Disabled” from the dropdown. This is also how you can undo the “Missing in PAT/SDT” designation if it somehow gets set. Make the change and click Save, then repeat for each service that has Auto Check Enabled.
Setting Auto Check to DisabledThe second method is on the services page itself, you can click or double-click on the words “Auto Check Enabled” and a dropdown should appear right there, with the same options shown in the dropdown above. Select “Auto Check Disabled” and then (this is important) click SOMEWHERE ELSE in the window to make the dropdown disappear (this could be a double click on the next item you want to change). A small red triangle will appear next to the changed item; this means it is a pending change that has not yet been saved! You can work your way down the list of “Auto Check Enabled” services and change each to “Auto Check Disabled” but after the last item make sure you click somewhere else to make the dropdown go away and the small red triangle appear., Then, BEFORE YOU LEAVE THE PAGE, click the “Save” button (which is just above the “Play” column heading on the left hand side of the screen). The page should reload and all the red triangles should have disappeared. Only now are your changes saved! If you forget and leave the page before clicking Save, you get to make all the changes over again. I wish there were a way to make “Auto Check Disabled” the default, because I do not want Tvheadend making the decision that a service is no longer available and locking it out. In North America, that’s generally a really bad idea!

The two methods of making configuration changes that I have mentioned above work on several of the pages in Tvheadend, but you always have to remember to click Save before leaving or refreshing a window or page, otherwise your changes will be lost!

Once you have disabled all the Auto Checks, what you want to do next is map the valid services to Channels. You can always delete a channel you don’t want later, so if in doubt it doesn’t hurt to map it. Sometimes the Service ID numbers and/or the Service Names will give you some clue as to which are viewable channels, but if you like you can just try mapping all the services. Highlight the ones you want, in the same way you’d highlight files for copying in your computer’s file browser. When you have highlighted one or more services, the “Map All” button shown in the screenshot above will change to “Map Selected”. So when you have highlighted the ones you want, click on “Map Selected”, and you’ll then see a popup window that looks like this:

Map services optionsIn most cases you’ll simply click the Map button. Most of the other options would make more sense in other parts of the world, but will only cause problems if you use them in North America. The one exception to that is the “Include encrypted services” option. Once in a great while a satellite channel will be marked as encrypted when it really isn’t. If you see something that indicates you should be able to receive a channel, but it’s indicated as being Encrypted in the services list, you can try checking the “Include encrypted services” box to map the channel anyway.

To see the channels that have been successfully mapped, go to the Channel/EPG tab (in the second row of tabs) and select the Channels tab in the bottom row. You should see a list of all the channels that have been successfully mapped. You can highlight any channel and use the Delete button to delete any channel you don’t want (this does not delete the service in the services list, only the mapped channel) and you can use the Edit button to edit the data for channels. In most cases you will want to edit channels you plan to watch regularly. As was the case with changing the Auto Check settings in Services, there are two ways to do this, but probably the best way when you are first starting out is to highlight a channel and then press the Edit button. You will see a dialog box that looks something like this:

Edit channel windowBefore editing the channel, though, you may want to try actually viewing it using your frontend software. If you are using Kodi, you will need to enable and configure the Tvheadend PVR addon first. Go to this page and skip down to section 5, “Connecting Kodi to Tvheadend” and follow the instructions there. After you do that, go to the TV settings (System-Settings-TV) and in the General section make sure “Synchronise channel groups with backend(s)” and “Use channel order from backends” are selected (you will have to set the “Settings Level” to “Advanced” or “Expert” to check and, if necessary, change those options). If you have an older version of Kodi, you may have to go to the “Live TV” section and make sure it is enabled; but that no longer seems to be necessary in the latest versions of Kodi.

Once you have configured the PVR addon you can go to TV in Kodi’s main menu, and under Channels you should see your newly added channels. They may have strange names at this point, but you should try watching each, first to see if there is really a channel there, and second to try to determine which channel it is. Sometimes you will know from online listings which channels are which, but in other cases the only way to know is by watching for a while and looking for a channel identifier.

In the above image, we have shown the Edit channel dialog for PBS “HD01”, which you might determine is an eastern time zone feed for PBS. So for now, we can make the following edits to the channel. The most important at this point are the channel name and number.

The channel name should ideally be one that identifies the channel, in this case “PBS East” would be a good choice. The channel number should be any non-zero number; it will be used to order the channels in Kodi. The numbers do not have to be contiguous; it’s perfectly okay to group channels into blocks of numbers and leave some unused channel numbers in between, but you should try not to leave any enabled channel un-numbered or duplicate any channel numbers. Neither Tvheadend nor Kodi will complain if you do, but channels may not be in the order you expect if you do that.

The “EPG Source” field will be very important when you are setting up your program guide, but you probably aren’t ready to deal with that quite yet. You’ll most likely want to first get all your muxes and channels entered.

There is a field for a “User Icon”. There are two places you can store channel icons, one is in Tvheadend and the other is on the frontend systems where Kodi is being run. In my opinion it is better to store them on the frontend systems. I tried doing it in Tvheadend and had some weird issues as a result, such as Kodi freezing up when I attempted to exit the program. Such issues may or may not have been fixed in newer versions of Tvheadend and/or Kodi. In any case, you don’t need to add channel icons right now. When you are ready to do so, my suggestion is that you store them on the frontends running Kodi and then go to Kodi’s TV settings (System-Settings-TV) and in the Menu/OSD section, set the “Folder with channel icons” to the path where your channel icons are stored. But feel free to try doing it in Tvheadend if you like; if it works for you and doesn’t cause any problems then use that if you prefer.

In some places in Tvheadend you may see a reference to “picons” – these are small, generally low resolution channel icons that often appear blurry in Kodi. In Europe and other parts of the world people often download archives of picons that correspond to the channels available from their satellite provider. Kodi doesn’t care what size icon you use (nor what aspect ratio it is, even though their Wiki indicates otherwise); if it is too small it will upscale it and it will look bad, whereas if it is too large Kodi will reduce it to fit and it will be very clear. Therefore, if you have a choice between a large icon or a small one, larger is often better (within reason – you don’t need one that fills half the screen on your computer’s display). Since we don’t have packages of “picons” corresponding to the channels available on North American C- and Ku-band satellite, and since I wouldn’t touch them if we did, I suggest you use your favorite search engine’s image search feature to find channel logos. You can also try LyngSat Logo, but be careful because some of their logos are too small to display clearly in parts of Kodi. Another thing to beware of is logos that don’t contrast well with Kodi’s dark background. If you have any experience with programs like Photoshop or The Gimp, you will probably find yourself wanting to modify a few logos slightly to make them look better in Kodi.

One additional point about storing the icons in Kodi is that they should be in PNG format, and should be named exactly the same as the channel name you gave the channel in the “Edit Channel” window. So for example, if you you have an icon for PBS East, it should be named PBS East.png. Yes, that means you will need to duplicate icons if you use the same icon for more than one channel (for example, even if you use the same icon for PBS East and PBS West, you’ll need two files, PBS East.png and PBS West.png). I would guess that icons in JPEG format (with a .jpg extension) might also work, but I have never tried it because I don’t care for JPEG artifacts.

Enough about icons. One other thing you may wish to do, which might help your frontend systems work a little easier, in in Tvheadend’s configuration select the Configuration tab on the top row of tabs, then the Stream tab on the second row, and the Stream Profiles tab on the third row. Then select the “pass” (MPEG-TS Pass-through) stream profile. Make sure all the checkboxes are checked next to these items:

  • Rewrite PMT:
  • Rewrite PAT:
  • Rewrite SDT:
  • Rewrite EIT:

The result should look something like this:

Pass-through stream profileThe reason for doing this is when you are streaming a channel to your frontend, with these boxes checked it will only send information about that specific channel, and not about all the channels in the MUX (if there is more than one). When information about multiple channels is sent, it might confuse your frontend, resulting in no video or audio. The only reason for not checking all these boxes would be if Tvheadend is running on a very underpowered system, which it probably isn’t if you followed my advice to use a desktop computer system when installing Tvheadend. It does take a little bit of CPU power to do these rewrites, but generally speaking, not enough that you’d ever notice.


Once you have configured Tvheadend, and have added all your muxes and channels, you will probably want to have the EPG populated so you can schedule programs to record. In North America, there is a company that offers paid schedule listings, and occasionally some of their proponents stoop to implying that it is somehow illegal or immoral to get program listings for free. It is neither, as long as you are using them for your own personal use (disclaimer: I am not an attorney, and I am not giving you legal advice). No one has ever gotten in trouble for using free listings in Tvheadend, and I would be shocked beyond belief if anyone ever does. Honestly, it pisses me off when a company or their supporters attempt to imply that you are a bad person for not purchasing their product, when you know their only reason for saying that is because they want to make money.

At this writing the easiest way to get free EPG listings for the USA and Canada is to use a program called zap2xml. That link takes you to a page of instructions for setup and use under Windows or Linux, and download links. You will probably want to run the Linux version on your backend system. Some time back I created an article containing additional hints and instructions, titled Some hints for getting free-to-air satellite channels into the Electronic Program Guide in Kodi (or another frontend). That article was not my best work; it’s been edited a few times and I may completely rewrite it some day, but if you are having problems figuring out how to use zap2xml or how to get Tvheadend to use the generated listings, that article may give you the clues you need to make it work.

Some other guides out there may mention a program called mc2xml. This program used Microsoft’s listing service, and many months ago Microsoft made some changes that rendered mc2xml inoperable. At that time, many users switched to zap2xml. The only problem some users have with zap2xml is that it is a Perl script, and therefore your system must have Perl installed. Ubuntu includes Perl in its operating system. However, if you ignored my advice above and decided to use a machine with an ARM-based processor, or if you are running one of the distributions ending in -Elec rather than Ubuntu, you may find that Perl isn’t installed and there’s no way to install it, or that there is no way to run a Perl script. Or, you may find that the tv-grab-file script used by Tvheadend won’t run because you don’t have the Bash shell installed, which is another thing that’s installed with Ubuntu. Or, you might discover you have no way to set up a cron job to get your schedule data automatically in the middle of the night. It’s usually possible to work around these issues one way or another, with considerable effort (and the article mentioned in the previous paragraph will give you some hints), but if you are not running Ubuntu you will likely find that setting up the EPG is a much more difficult process.


Occasionally you may want to tune in a channel that requires “special handling”. For example, one major U.S. provider uses six discrete audio channels to send 5.1 audio, and no standalone satellite receivers can decode it properly. But Tvheadend can, with a little coaxing. See the article, Fixing the audio on live TV from a certain network (which shall remain nameless) in Tvheadend for information.

Also, if you are using low-powered computers for your frontend systems, they may not be capable of playing back certain high-bitrate channels in real time. However, you can record shows from such channels, and play them back on equipment with more CPU power (such as your desktop computer), or you can convert the recording to a format that has lower CPU/GPU requirements for playback. Here’s an example of the latter approach: How to play video recorded from high-bitrate 4:2:2 sources on low-power systems


If you have a TV Antenna, I will just mention two ways you can add over the air channels to your backend. One is to use a tuner card that picks up ATSC Channels (be sure it receives ATSC, and not DVB-T or some other format that’s not used in most of North America) such as a TBS6704 ATSC/Clear QAM Quad Tuner PCIe Card. That card’s tuners should appear in your tuner list, just like any other tuner.

Another option is to use a HDHomeRun device, such as a HDHomeRun Dual (model HDHR3-US or possibly the newer model HDHR4-2US, also known as the HDHomeRun CONNECT). These have two independent ATSC tuners, which can be fed from the same antenna using a splitter, or from two different antennas, which may be useful as explained in the next paragraph. However, buying a HDHomeRun can be confusing because there are several models, and not all of them will work for this application. Also, Silicon Dust (the makers of the HDHomeRun) are now trying to push users toward their DVR product, so I don’t know if newer models will work as well with Tvheadend. The HDHomeRun Dual connects to your antenna(s) and also to your local network via an Ethernet jack. It can therefore be placed near where the antenna’s cable enters the house, as long as there’s an Internet connection and a power source there, and after a reboot Tvheadend will probably just find it on the network and show it in its tuner list, assuming you are using a recent version of Tvheadend.

Note that if you search on the Internet you will find several older guides that will tell you that you need to install extra software, such as drivers, to use a HDHomeRun device with Tvheadend. That may have been true at one time, but it no longer appears to be necessary to install any additional software if you are using Ubuntu 14.04 and Tvheadend 4.0.9 or newer.

You only need to set up one ATSC network for over-the-air channels, unless you have multiple antennas pointing in different directions, feeding different tuner inputs. For example, if you are in between two major cities and receive strong signals from both, you could put up two TV antennas, each pointed at a different city’s transmitters, and feed each antenna into a different tuner input. You would then create two ATSC networks in Tvheadend, so that Tvheadend could select which antenna to use for the best reception on any channel.


If you keep in mind that much of the information out there regarding Tvheadend is geared toward users in the Eastern hemisphere, and that settings that are useful in other parts of the world don’t apply to us in North America, then you may find reading the official documentation for Tvheadend helpful. It will tell you about some features of the program that I haven’t covered here. Probably the best place to start is the Tvheadend Wiki and the Tvheadend User Guide.


Please leave a comment if you spot any errors or omissions, or have anything useful to add!

Fixing the audio on live TV from a certain network (which shall remain nameless) in TVHeadend

266px-Pavo_cristatus_(male)_-feathers-8aThis is a followup to a previous article, Fixing the audio on recorded programs from a certain network (which shall remain nameless). In that article, which you may want to read first for some additional background information, I showed you how to fix the audio on previously-recorded programs. In this article, I’ll show you how to do it in real time, assuming you are using TVHeadend (version 3.9.2100 or later) as your PVR backend software. This is useful for both watching live TV, and for when you are recording a program but want to begin watching the recording before the program has ended.

My note about ffmpeg from the previous article also applies here:

Note: For this to work, you must have a version of ffmpeg from (link is to download page) or, if you are a Linux user but do not feel comfortable attempting to build software from source, then you may be better off using a static build such as is offered at this site (technically this is an unofficial build, so use at your own risk, but as I write this the packages offered in the deb repositories are older versions that don’t work as well for this purpose, and produce files that don’t play well on underpowered systems). Please note that some Linux distributions, notably some versions of Debian and Ubuntu and their derivatives, provide a package called ffmpeg in their repositories that is not true ffmpeg, but instead is a transitional package for libav. The syntax shown above will not work with the transitional package version; you need true ffmpeg for this to work! For the reason this sad situation exists, see The FFmpeg/Libav situation or for a slightly more technical view, FFmpeg versus Libav.

Another possible way to get the real ffmpeg installed on Ubuntu and some derivative systems is explained in the article, How To Install FFmpeg 2.6.1 On Ubuntu 15.04, Ubuntu 14.10, Ubuntu 14.04 And Derivative Systems from the site.

This assumes that you have already scanned in the relevant channels from either the Ku-band side of AMC-1 or the C-band side of AMC-18 and that you have assigned them channel numbers in TVHeadend’s web interface. If you are in the habit of occasionally renumbering your channels as you add new ones or remove ones that are no longer functional, then I suggest you give those channels high numbers that will not be changed (starting with 1000 or even 10000, for example). The reason is that if you change the numbering of those original channels, this will stop working until you make the necessary adjustments. In any case, you need to note the channel numbers assigned to those channels, as they will be needed in one of the steps here.

The first thing you have to do, if you have not done it already, is to create an IPTV network. In TVHeadend’s web interface, go to Configuration > DVB Inputs > Networks and create a new IPTV Network:

Select IPTV network from the dropdownConfigure the new network as shown here:

Give the network a name, and uncheck The Network Name can be anything you like; I just called it IPTV to make it easy to recognize.  I also unchecked “Network Discovery” because it seems that you can’t automatically scan the channels anyway, so I didn’t want TVHeadend trying to do something in the background that would fail.

The above only has to be done once, no matter how many channels you add.  The next thing you need to do is add a Mux.  In TVHeadend’s web interface, go to Configuration > DVB Inputs > Muxes and create a new Mux, selecting the IPTV network from the dropdown:

Choose the IPTV network from the dropdown.Configure the new Mux as shown here:

Add Mux 2The full URL should be in this form (this is all one line):

In FFMPEG Version 2.x:
pipe:///usr/local/bin/ffmpeg -loglevel fatal -i -c copy -filter_complex [0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5 -c:a eac3 -f mpegts pipe:1

In FFMPEG Version 3.0 and later (only when using eac3 as the output codec):
pipe:///usr/local/bin/ffmpeg -loglevel fatal -i -c copy -filter_complex [0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5 -c:a eac3 -mpegts_flags system_b -f mpegts pipe:1

      • The above line assumes that ffmpeg is located in the /usr/local/bin directory on your system – if that’s not the case, and there’s a good chance it isn’t depending on which instructions you followed when you installed ffmpeg, you must change the path to point to the actual location of ffmpeg (you can enter “which ffmpeg” from the Linux command line to find the correct path).
      • Replace CHANNEL_NUMBER with the channel number of the original channel – this is why I suggested that you assign those channels high channel numbers, so you would not want or need to renumber them later.
      • Note that this converts the audio to eac3, which Kodi will generally play as true 5.1 audio, depending on its audio settings and the ability of your AV receiver to handle encoded audio (in some Kodi skins it’s erroneously reported as 7.1, but it’s really 5.1). If that doesn’t work for some reason, you can try changing the -c:a option from eac3 to ac3 or if it still doesn’t work, you can try mp2 as a last resort (but you may only get 2-channel stereo if you use mp2). When using ffmpeg 3.0 or later and specifying the eac3 codec, the -mpegts_flags system_b option must be included, or you may get no audio at all!
      • The above line converts the audio stream only.  All other streams are copied verbatim, which means that video, closed captions (if available) and anything else in the original stream should also be available in the converted stream (although closed captions seem to be iffy; in my experience that stream often has missing characters or is not present at all).

Be sure to give the Mux a name of your choosing – it makes it a lot easier to work with in the subsequent steps.  Short and simple is better here, for example just the network name and time zone.  It only needs to be unique and recognizable.

After adding your Mux, you can look in the Services tab to make sure it got added, but don’t try to map the service from there because it won’t work (at least I could never get it to work).  Instead, go to Configuration > Channels / EPG > Channels and click the Add button or link (in the bar just above the channel list).  You can then add the channel from this dialog box:

Add ChannelMake sure the “Enabled” box is checked.  For the Name, enter the channel name as you want it to appear in your channel list and guide in Kodi.  For the Number, give it the channel number you want it to use.  In the Services dropdown, select the correct service from the list; it will be in the format Network Name/Mux Name/Service01.  Note you may also see a listing of the form Network Name/Mux Name/{PMT:####} or something similar in the dropdown, but don’t use that one because it won’t work.  Use the one that ends in Service01.

If you have figured out how to add channels to the Electronic Program Guide, then you should also select the correct EPG Source from the dropdown.  Do not check the “Auto EPG Channel” box.  Then click the “Create” button.

If you want to add more channels (for different time zones, etc.) then just repeat the above process, starting with adding a new Mux.

You should be able to play your added channel(s) just like any other satellite channels in Kodi (or whatever you use to play video from the backend).  Note that because this is piping a stream through ffmpeg in real time, there may be a short delay (a few seconds at most) before the stream starts playing if you are trying to watch Live TV.  Unfortunately, this short delay apparently sometimes causes Kodi to ignore the video stream, but only when trying to play Live TV.   My guess is that because the video doesn’t arrive quickly enough, Kodi thinks you’re playing a radio or other audio-only channel and ignores  the video stream.  If this happens, you can stop the playback and try again, or you can start recording the channel, wait several seconds, and then start playing the recording.  I have never seen this problem occur when playing a recording, probably because recordings tend to start playing almost immediately. You only see it when you attempt to play the live stream directly, and even then it will only happen a certain (hopefully small) percentage of the time.

Speaking of recording,  if you want to record from the channel, you do that in the normal manner, just as you would for any other channel.  There’s no need to do any type of post-processing, unless you do that for reasons other than to fix the audio.

EDIT: If you are using Tvheadend 4.3 or newer and you get an error such as “iptv: libav: Could not open input ‘pipe:///usr/bin/ffmpeg … (blah, blah) … ‘: Protocol not found”, you probably need to uncheck the box “Use A/V Library” in the IPTV network settings, and/or select “Do not use” in the dropdown for the “Use A/V Library” setting in your Mux settings – see this thread in the Tvheadend forum for details.

EDIT: If it doesn’t work or suddenly stops working, check that you haven’t inadvertently blocked TVHeadEnd from accessing itself in the Access Entries tab in TVHeadend’s web interface.  At one point we tried changing the Network prefix values away from the default to something more specific to the local network.  Everything else on the network could still access the backend, but it caused these channels to fail with an error message “No input source available for subscription” because TVHeadEnd could no longer access itself.  Strange…

On my TVHeadend backend, I’ve found that ffmpeg does not add significantly to the CPU usage as long as you are only converting audio.  I think converting video would be an entirely different story, and I doubt you could do that in real time unless you have a very high-powered backend system (and maybe not even then), but feel free to try if you have that need.

Custom MPEG-TS Input (TVHeadend Wiki)

Getting bad satellite recordings in TVHeadEnd? Here’s a possible fix

I was perusing the TBS forum recently and discovered that there’s a problem that can occur, notably with certain TBS cards but possibly with others as well, that can result in semi-corrupted recordings. The .ts file that contains the recording actually contains the entire program, and can usually be repaired by chopping off a few megabytes at the start of the file, but as it sits on the TVHeadEnd server it’s not easily playable for one or both of two reasons:

  • It reports the wrong length (time) for the recoding – for example a one hour program may appear to be of a much greater length (several hours long), and/or
  • The video and audio are out of sync by a second or two, where this is not usually the case.

In Kodi, you can generally play such a recording from the start, but skipping around within the program may be problematic or impossible.

The possible fix for this is to set a “Skip Initial Bytes” setting for each tuner, as described in this post on the TBS forum.  The conversation there appears to be about a specific TBS card (the TBS6905) but I have heard of this problem happening with other cards as well.  As best I can understand the problem, the card starts sending a virtual firehose stream of data before the buffers are ready to receive it, and some data gets lost at the start, corrupting the file.  By skipping some initial bytes, you get only the “good” data once everything has had time to initialize.  That’s probably a gross oversimplification, but that’s what I got out of that thread.

The place to change the setting is here:

Configuration | DVB Inputs | TV adapters, in the “Advanced Settings” section

You might think the number of bytes skipped is quite high, but since even a 30 minute recording can contain several gigabytes of data, that number is actually insignificant.  The original poster in the thread states that “The 18800000 setting is a bit arbitrary; I chose it because it is more than 1 Meg and is the ‘Input Buffer (Bytes)’ value x 1000. If the issue persists I may try an even higher value.”  Feel free to experiment with lower or higher values; I personally think I’d start with something lower such as 188000 (10 times the Input Buffer) and then if that doesn’t resolve the issue, go up to 1880000. And if that still doesn’t always fix the problem, then go to the 18800000 value.  But, it’s entirely up to you.  And remember that if you have more than one tuner, you have to add this setting for each affected tuner.

The thread also notes, “If the new value doesn’t appear after you change it and click save, refresh the page in your browser, then navigate back to the TV adapters tab.”

If TVHeadEnd is creating these types of bad recordings on your backend server, I’d suggest this fix is at least worth a try, since you can easily reverse it if it turns out to not have any effect.

What if you already have a bad recording and want to fix it?

While the above advice may help you prevent future bad recordings, it will not help you fix an already recorded program that has bad timing information. Usually ffmpeg can fix the timing issues, so I have used this script to fix existing recordings:

# If calling from Tvheadend, invoke using path/to/scriptname "%b"
# Then $1=%b in this script
# Extension of converted file must be same as original file (.ts)!
cd /home/hts/recordings
/usr/bin/ionice -c 3 /usr/bin/nice -n 20 /usr/local/bin/ffmpeg -loglevel quiet -i "$1" -c copy -f mpegts "converted-$1" &> /dev/null
mv -f "converted-$1" "$1"

The line that starts with /usr is a long line, so you may need to copy the above script and paste it into a text editor to see it correctly. Note that you must run this as the hts user (or whatever user the Tvheadend service runs as) to avoid permissions issues (you can do sudo su hts to temporarily become the hts user). And you must check all the paths shown in this script to make sure they are valid for your system, and change them accordingly if they are not.

The first (non-comment) line changed the working directory to the directory where Tvheadend stores its recordings. The second line uses ffmpeg to convert the file – it simply copies all the audio, video, and data information but it does fix the timing information in most cases. The “/usr/bin/ionice -c 3 /usr/bin/nice -n 20” at the beginning of the line is to set this process to the lowest priority, so that if you are actively recording any channels at the time, it won’t steal CPU power or disk I/O from that activity. The final line moves the converted file over the original. You must move it over the original, not copy it, because Tvheadend will lose track of the recording if you try to copy it over. This script does not save a backup of the original file, so if you want one, copy the original file to a safe location prior to running this script.

To use the script, find the filename of the bad recording (you could do ls /home/hts/recordings) and then, as the hts user, just run the script with the filename as an argument. Note that it is also possible to call the script as a Post-processor command in a Digital Video Recorder Profile in Tvheadend, so that the script will run automatically when a program finishes recording (in case you have a channel that frequently gives you bad recordings, and you can’t use the method shown at the top of the page). See the comments at the top of the script for information.

If you are running on a system that doesn’t have the bash shell, this script will probably run just was well under whatever shell you have, although minor tweaking may be required. At the very least, you will need to change the #!/bin/bash line at the top. And, this assumes you have ffmpeg installed on your system – run which ffmpeg from the command line, and if ffmpeg is present then it will show the correct path to ffmpeg. If you don’t have ffmpeg installed and it isn’t available in your Linux distribution’s repository, then I suggest using a static build of ffmpeg, since it is much easier to install than trying to compile it from scratch. Just copy the ffmpeg program (and any of the others you may want) from the downloaded archive to the /usr/local/bin directory, and make sure the ownership and permissions are set correctly (should be owned by root, and executable by everyone). I use Midnight Commander (mc) to do these types of operations, but to each their own.

Obviously, the fix shown at the top of this article is a lot easier to implement than using ffmpeg to fix a bad recording once it’s already recorded (plus, using that method, you can start watching the show while it is still being recorded without issues) but some tuners may not have the “Skip Initial Bytes” setting, or changing it may not work for some tuners. In my experience it almost always works for TBS tuners (unless you are having a problem with low signal strength or quality), so try the “Skip Initial Bytes” setting first if it is available to you!

How to play video recorded from high-bitrate 4:2:2 sources on low-power systems

In a previous post, I told you about Fixing the audio on recorded programs from a certain network (which shall remain nameless). The technique for doing that involved the use of the ffmpeg software, and I suggest you read that article because it gives some information near the end of the article on how to obtain a correct version of ffmpeg. The technique I am about to discuss also uses ffmpeg.

If you are running a PVR/backend system such as TVHeadEnd, you may have tried recording programs from certain high-bitrate 4:2:2 feeds, and then found that they simply would not play back on your home theater PC device, particularly if you are using something low-powered like a single-board computer. You might get sound only, with a black picture (and maybe a few flashes of green or some other color), or the video just might play really slowly for a few seconds and then start breaking up. The solution to this is to use ffmpeg to convert the recorded program after you have finished recording it. This means you can’t watch the program live, but you can view it later.

When I first ran across this problem, I found a nice GUI-based program that could do the conversion, but it also took a ridiculous amount of time (about 8 hours to convert an hour of video). But also, it not only converted the video, but also the audio, which destroyed any hope of hearing surround sound. I then figured out that it was actually using ffmpeng to do that conversion, and that by running ffmpeg with only the necessary options I could cut the processing time down to around one-quarter of the time taken by the GUI-based program (or around twice the original running time of the program), plus I could set it to pass the audio and any subtitle streams unchanged. The line I used looks like this:

ffmpeg -loglevel quiet -y -i “original_recording.ts” -c copy -c:v libx264 -b:v 16711680 -pix_fmt yuv420p “converted_program.ts”

(The above is a single line, even if it does not display as such here.)

The -b:v 16711680 option sets the bitrate for the conversion and is the same as the one used by the GUI-based program. In my case it seems to produce a file that’s somewhere around half the size of the original. The video quality is still excellent. By the way, the -y option tells it to overwrite any existing file with the name you specify for the converted program file; if you want it to prompt you when there’s a file name conflict then leave that option out. The above line assumes you are converting a transport stream (.ts) file, if not, then change the extensions accordingly.

If the resulting file is still a little too “fat” for your equipment, then you can try reducing the -b:v value, with a corresponding loss of quality. The GUI-based program could use -b:v 7325135 and still considered that “high” quality, while -b:v 4229320 was considered somewhere between “high” and “standard” quality. Of course, you could go even lower, particularly if you will be playing the recording back on a much smaller screen. And, I do not think those numbers are in any way magic, and there is no reason you couldn’t stick with even decimal or hexadecimal numbers for your trials, so for example you could use 16777216, 8388608, 4194304, or 2097152 (corresponding to 0x1000000, 0x800000, 0x400000, and 0x200000 in hexadecimal) as your -b:v trial values. You just need to find that sweet spot where the video is of the best possible quality that will play without problems on your equipment.

There are many other options you can use with ffmpeg, including ones that will reduce the screen size in case you are watching on an older computer or tablet, or something else that does not have a 1080p screen, but I just wanted to show a simple conversion using the fewest number of options.

I will note that ffmpeg has a tendency to gobble up as much available CPU time as it can get while converting video. If you fear that it will steal needed CPU cycles from other programs (such as your backend software), you can use nice to keep it in check. For example, if you use:

nice -n 20 ffmpeg […options…]

It will cause ffmpeg to run at the lowest possible priority and give up CPU cycles to any other program that needs them. Nice can take values from -20 to + 20, with the higher the number indication how “nice” the program will be to other programs. Negative values will raise the priority of the program higher than normal, while positive values will give it lower priority than most other programs.

Similarly, you can use ionice to keep ffmpeg from hogging access to your storage devices. If you use:

ionice -c 3 ffmpeg […options…]

That will cause ffmpeg to give preference to any other program that needs access to your storage devices. You might want to use this if ffmpeg will run at the same time your backend software is recording programs to your hard drive. And yes, you can use both ionice and nice together:

ionice -c 3 nice -n 20 ffmpeg […options…]

Note that if you are running this from a shell script then you may need to specify the full paths to all the programs used, like this:

/usr/bin/ionice -c 3 /usr/bin/nice -n 20 /usr/local/bin/ffmpeg […options…]

The paths shown above are valid for most Debian/Ubuntu based systems. To find out where these programs are located on your system, you can use the which command. For example:

$ which ffmpeg

Fixing the audio on recorded programs from a certain network (which shall remain nameless)

This bird has no relevance to anything in this article, I just thought it was a nice picture (Source: Public Domain

This bird has no relevance to anything in this article, I just thought it was a nice picture 😉 (Source: Public Domain

I have said that I won’t mention any specific channels or networks you can receive in North America by name (with specific exceptions), but if you receive channels from either the Ku-band side of AMC-1 or the C-band side of AMC-18 you have probably encountered some channels with split up audio, where various channels are sent on different streams. The most common format on those channels seems to be:

Stream 1: Left and right front
Stream 2: Center (on left channel) and low frequency (on right channel)
Stream 3: Left and right rear
Stream 4: Described video (when used, on left) and mono (on right channel)

If you have recorded a program from one of those channels as a .ts file, then ffmpeg can convert it to real 5.1 audio, keeping all other streams including video as is, and usually in under five minutes unless you have a underpowered computer:

In FFMPEG Version 2.x:
ffmpeg -i "original program filename.ts" -c copy -filter_complex '[0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5' -c:a eac3 "converted program filename.ts"

In FFMPEG Version 3.0 and later (only when using eac3 as the output codec):
ffmpeg -i "original program filename.ts" -c copy -filter_complex '[0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5' -c:a eac3 -mpegts_flags system_b "converted program filename.ts"

The above is all one line, even if it appears otherwise in this blog. This discards stream 4, and maps the other three to 5.1 audio. Note that this converts the audio to eac3, which Kodi will generally play as true 5.1 audio, depending on its audio settings and the ability of your AV receiver to handle encoded audio. If that doesn’t work for some reason, you can try changing the -c:a option from eac3 to ac3 or mp2 (and omit the -mpegts_flags system_b option if using ffmpeg version 3.0 or later, since that option is only needed when using the eac3 codec), but in my experience Kodi treats mp2 audio as stereo only.

Note that although the above example lines attempt to copy all non-audio streams verbatim, including ATSC closed captions, I have noticed that closed captions don’t fare well after passing through ffmpeg. In some cases they are missing altogether, and in other cases they are just garbled or missing characters. I don’t know why this happens and I don’t have any solution for the problem at this time.

Some backend programs, such as TVHeadEnd, give you the option to run a Post-Processor Command when a recording is finished, so with such a backend it may be possible to do this conversion automatically. Note, however, that ffmpeg by default sends a lot of output to stderr, which can cause issues in some systems (or just send a lot of unnecessary email to the system administrator), particularly if you are trying to run ffmpeg from a script. Once you know you have it working, you can suppress this output by using the -loglevel quiet switch, like this:

In FFMPEG Version 2.x:
ffmpeg -loglevel quiet -i "original program filename.ts" -c copy -filter_complex '[0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5' -c:a eac3 "converted program filename.ts"

In FFMPEG Version 3.0 and later (only when using eac3 as the output codec):
ffmpeg -loglevel quiet -i "original program filename.ts" -c copy -filter_complex '[0:1][0:2][0:3]amerge=inputs=3,pan=5.1|FL=c0|FR=c1|FC=c2|LFE=c3|BL=c4|BR=c5' -c:a eac3 -mpegts_flags system_b "converted program filename.ts"

If you would like to have logging, but only when something goes terribly wrong, use -loglevel fatal instead of -loglevel quiet.

Note: For this to work, you must have a version of ffmpeg from (link is to download page) or, if you are a Linux user but do not feel comfortable attempting to build software from source, then you may be better off using a static build such as is offered at this site (technically this is an unofficial build, so use at your own risk, but as I write this the packages offered in the deb repositories are older versions that don’t work as well for this purpose, and produce files that don’t play well on underpowered systems). Please note that some Linux distributions, notably some versions of Debian and Ubuntu and their derivatives, provide a package called ffmpeg in their repositories that is not true ffmpeg, but instead is a transitional package for libav. The syntax shown above will not work with the transitional package version; you need true ffmpeg for this to work! For the reason this sad situation exists, see The FFmpeg/Libav situation or for a slightly more technical view, FFmpeg versus Libav.

Another possible way to get the real ffmpeg installed on Ubuntu and some derivative systems is explained in the article, How To Install FFmpeg 2.6.1 On Ubuntu 15.04, Ubuntu 14.10, Ubuntu 14.04 And Derivative Systems from the site.

I am not adverse to libav or a companion package called avconv for this process, I just don’t know if either of those can be used for this purpose, or if so, what the correct syntax would be. If anyone knows, please feel free to leave a comment.

There is a followup to this article: Fixing the audio on live TV from a certain network (which shall remain nameless) in TVHeadend. This discusses how to do the audio conversion in real time, so that you can view live TV with proper audio, or begin watching a recorded program before it has completely finished recording.

You may also be interested in this article:
How to play video recorded from high-bitrate 4:2:2 sources on low-power systems