Standalone Walkthrough: Mac OS X with config file

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.

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.1.0-Beta3/telly-1.1.0.2.darwin-amd64.tar.gz

Uncompress the archive and cd into the new directory:

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

And run telly with the -h flag to show the help:

➜  telly-1.1.0.2.darwin-amd64 ./telly -h
Usage of ./telly:
  -c, --config.file string          Path to your config file. If not set, configuration is searched for in the current working directory, $HOME/.telly/ and /etc/telly/. If provided, it will override all other arguments and environment variables. $(TELLY_CONFIG_FILE)
      --log.level string            Only log messages with the given severity or above. Valid levels: [debug, info, warn, error, fatal] $(TELLY_LOG_LEVEL) (default "info")
      --log.requests                Log HTTP requests $(TELLY_LOG_REQUESTS)
      --version                     Show application version
  -b, --web.base-address string     The address to expose via discovery. Useful with reverse proxy $(TELLY_WEB_BASE_ADDRESS) (default "localhost:6077")
  -l, --web.listen-address string   Address to listen on for web interface and telemetry $(TELLY_WEB_LISTEN_ADDRESS) (default "localhost:6077")
pflag: help requested
➜  telly-1.1.0.2.darwin-amd64

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

There are only a few flags, but the best practice is to leave all the configuration in the config file; everything config-related can and should be set via the config file [except, of course, the location of the config file].

Step one is to create a config file.

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**