Standalone Walkthrough: Mac OS X

You should probably be using version 1.1; 1.0 hasn't seen any development is a very long time.

Rather than describe the general case and leave it to you to figure out how it applies to your situation, we will walk through a very specific setup, watch the system work, and then discuss how you can change it to match your specific situation.

The hope is to avoid common pitfalls and work through a setup known to work to try and head off possible problems and build some understanding.

ATTENTION: This walkthrough is specific to the version being shown below, which, as of this writing, is 1.0.3. If you try to go through this walkthrough, but substitute some other version for the versions shown below, it very well may not work.

If you're going through this walkthrough, you should perhaps copy-paste the commands below. Do not substitute what you think may be the "latest version" here.

To start, open a new terminal window. You should be in your home directory, but to make sure you are, type cd ~.

➜  ~ cd ~

Create a new directory and cd into it:

➜  ~ mkdir telly-tutorial
➜  ~ cd telly-tutorial

Download the latest release:

➜  telly-tutorial curl -fLO https://github.com/tellytv/telly/releases/download/v1.0.3/telly-1.0.3.darwin-amd64.tar.gz

Uncompress the archive and cd into the new directory:

➜  telly-tutorial tar -xvf telly-1.0.3.darwin-amd64.tar.gz
x telly-1.0.3.darwin-amd64/
x telly-1.0.3.darwin-amd64/LICENSE
x telly-1.0.3.darwin-amd64/NOTICE
x telly-1.0.3.darwin-amd64/telly
➜  telly-tutorial cd telly-1.0.3.darwin-amd64
➜  telly-1.0.3.darwin-amd64

And run telly:

➜  telly-1.0.3.darwin-amd64 ./telly
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
WARN[0000] using default m3u option, 'iptv.m3u'. launch telly with the --iptv.playlist=yourfile.m3u option to change this!
PANI[0000] error getting m3u                             error="open iptv.m3u: no such file or directory"

Note: telly will often produce more output than will be shown here; typically the material elided here will be error messages that would only serve as clutter here.

There's our first error. Telly requires an M3U playlist from your iptv provider. In this example we will be using an Iris account.

Your playlist URL is going to be something like this: http://irislinks.net:83/get.php?username=REDACTED&password=REDACTED&type=m3u_plus&output=ts

From here, substitute your IPTV M3U URL wherever you see "<IPTV_M3U_URL>"

Now run telly again

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL>
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 0 channels

Telly read the playlist, but found no channels. This is because the standard filtering behavior is to exclude things that match the default filter, and the default filter matches everything.

The --filter.regex-inclusive flag will flip that behavior so that telly will include everything that matches the filter. Add that flag and run telly again, but before you do so you'll have to quit telly. You'll probably have to do that after every telly command from here on. Quit telly by typing control-C.

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL> --filter.regex-inclusive
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 8015 channels
WARN[0000] telly has loaded more than 420 channels. Plex does not deal well with more than this amount and will more than likely hang when trying to fetch channels. You have been warned!

You can see that now telly is including all the channels from the playlist. Your channel count will probably differ from the above.

Let's add a basic filter. At this point, the things you enter will be different from the values here, unless you're also using IrisTV, because your playlist will contain different channels with different names.

Let’s look at the last few lines in the playlist:

➜  telly-1.0.3.darwin-amd64 curl -fL "<IPTV_M3U_URL>" | tail

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1638k  100 1638k    0     0  1493k      0  0:00:01  0:00:01 --:--:-- 1494k
#EXTINF:-1 tvg-id="" tvg-name="AFG: SHAMSHAD" tvg-logo="http://picon.helixhosting.ninja/26944.png" group-title="AFGHANISTAN",AFG: SHAMSHAD
http://irislinks.net:83/live/REDACTED/REDACTED/263016.ts
#EXTINF:-1 tvg-id="" tvg-name="AFG: SROOD" tvg-logo="http://picon.helixhosting.ninja/26943.png" group-title="AFGHANISTAN",AFG: SROOD
http://irislinks.net:83/live/REDACTED/REDACTED/263015.ts
#EXTINF:-1 tvg-id="" tvg-name="AFG: TAMADON TV" tvg-logo="http://picon.helixhosting.ninja/26942.png" group-title="AFGHANISTAN",AFG: TAMADON TV
http://irislinks.net:83/live/REDACTED/REDACTED/263014.ts
#EXTINF:-1 tvg-id="" tvg-name="AFG: TOLO" tvg-logo="http://picon.helixhosting.ninja/26941.png" group-title="AFGHANISTAN",AFG: TOLO
http://irislinks.net:83/live/REDACTED/REDACTED/263013.ts
#EXTINF:-1 tvg-id="" tvg-name="AFG: TOLO NEWS" tvg-logo="http://picon.helixhosting.ninja/26940.png" group-title="AFGHANISTAN",AFG: TOLO NEWS
http://irislinks.net:83/live/REDACTED/REDACTED/263012.ts

By default, telly is going to run the filter on the "tvg-name" field.

The filter is specified as a "regular expression". Teaching regular expressions is out of scope for this tutorial, but in a nutshell, a regular expression [or regex] is a recipe for matching text.
For example, the regex "AFG: TOLO NEWS" matches one channel above; one channel's name contains "AFG: TOLO NEWS".
"AFG: TOLO" matches two.
"AFG: " matches five. And so on.

One place to learn more about regex is Regex One.

Let's add a filter to bring in those two "TOLO" channels. Of course, in your case, there will probably be different channels listed, so put something in the filter that matches more than one channel, if possible.

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL> --filter.regex-inclusive --filter.regex="AFG: TOLO"
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 2 channels

There's the two channels. If you run this again without --filter.regex-inclusive, the channel count will be the total minus 2, since now it's excluding things that match the filter:

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL> --filter.regex="AFG: TOLO"
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 8013 channels

Typically, you'll be using --filter.regex-inclusive and specifying a list of things to keep, since you'll be filtering the majority of the channels from your playlist to get down below Plex's 420-channel limit.

For example, say I want all the ESPN channels, all the premium movie channels, all the Fox Sports channels:

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL> --filter.regex-inclusive --filter.regex="ESPN|HBO|Showtime|Cinemax|Fox Sports"
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 146 channels

The vertical bars there mean OR, so that translates as:

'give me channels whose name includes "ESPN" OR "HBO" OR "Showtime" OR "Cinemax" OR "Fox Sports"'.

Devising a regex that matches the channels you want to include is left as an exercise for the reader. It will depend entirely on how your IPTV provider names channels. I will use just "ESPN" to keep the channel list short. You should do something similar; enter a filter that results in a short list of channels.

The last three required flags have to do with networking:

--discovery.ssdp 
--web.listen-address=0.0.0.0:6077
--web.base-address=192.168.1.61:6077

--discovery.ssdp sets up some networking that Plex uses to discover the virtual DVR. The other two control what IP address telly listens on, and what IP address Telly tells Plex to connect to.

Set the base address to the IP address of the machine which is running telly. No changes are required to the others. Add those flags and run telly:

➜  telly-1.0.3.darwin-amd64 ./telly --iptv.playlist=<IPTV_M3U_URL> --filter.regex-inclusive --filter.regex="ESPN" --discovery.ssdp --web.listen-address=0.0.0.0:6077 --web.base-address=192.168.1.61:6077
INFO[0000] Starting telly (version=1.0.3, branch=master, revision=e543e7080a57eb6d7b6dd4b0ad27b789d3aa6c08)
INFO[0000] Build context (go=go1.10.3, user=root@21d9dfe90d82, date=20180811-23:23:07)
INFO[0000] found 57 channels
INFO[0000] requests_total registered.
INFO[0000] request_duration_seconds registered.
INFO[0000] response_size_bytes registered.
INFO[0000] request_size_bytes registered.
INFO[0000] Listening and serving HTTP on 0.0.0.0:6077

That's it; telly is running.

To verify this, open a new terminal window and request the default page from telly [or course, replace "192.168.1.61" with the appropriate address]:

➜  ~ curl http://192.168.1.61:6077
<root xmlns="urn:schemas-upnp-org:device-1-0"><specVersion><major>1</major><minor>0</minor></specVersion><URLBase>http://192.168.1.61:6077</URLBase><device><deviceType>urn:schemas-upnp-org:device:MediaServer:1</deviceType><friendlyName>HDHomerun (telly)</friendlyName><manufacturer>Silicondust</manufacturer><modelName>HDTC-2US</modelName><modelNumber>HDTC-2US</modelNumber><serialNumber></serialNumber><UDN>uuid:12345678</UDN></device></root>

Check the channel list by requesting the lineup:

➜  ~ curl http://192.168.1.61:6077/lineup.json
[{"GuideNumber":"10000","GuideName":"PS ESPN","URL":"http://192.168.1.61:6077/stream/aHR0cDovL2lyaXNsaW5rcy5uZXQ6ODMvbGl2ZS85NzgzNTc2OC8zNzIxMzExMC8zMDczOTgudHM="},{"GuideNumber":"10001","GuideName":"PS ESPN Deportes","URL":"http://192.168.1.61:6077/stream/aHR0cDovL2lyaXNsaW5rcy5uZXQ6ODMvbGl2ZS85NzgzNTc2OC8zNzIxMzExMC8zMDc0MDMudHM="},{"GuideNumber":"10002","GuideName":"PS ESPN Goal Line","URL":"http://192.168.1.61:6077/stream/aHR0cDovL2lyaXNsaW5rcy5uZXQ6ODMvbGl2ZS85NzgzNTc2OC8zNzIxMzExMC8zMDczMjAudHM="},{"GuideNumber":"10003","GuideName":"PS E
**REMAINDER CLIPPED**