This application provides an interface between locast.org and Plex Media Server (PMS) or Emby by acting like an HDHomerun or an m3u tuner and an XMLTV provider.
locast2tuner can imitate one or more digital tuners and provides geo cloaking across regions.
- locast2tuner
- Table of Contents
- Features
- Background
- TODO
- Getting started
- Usage
- Configuration
- Submitting bugs or feature requests
- Override your location using ZIP code or GPS coordinates
- Multiple digital tuners in a single server, either as separate servers or as one (multiplexing)
- Acts like either an HDHomerun or an m3u tuner
- Provides locast EPG information as an XMLTV guide
locast2tuner is a rewrite in Rust of locast2dvr, which in turn is a rewrite of locast2plex. Thanks to the locast2plex developers for writing it and figuring out how to stitch things together!
I rewrote locast2plex to be able to more easily add functionality, use libraries wherever possible (like HTTP, m3u, starting multiple devices, etc), heavily document, generally write clean code, and provide a better user experience (command line argument parsing, automatic download of FCC facilities, etc). And since python's GIL gave me a headache, I rewrote the whole thing in Rust.
Apart from the fact that everything is Rust now, the big difference between locast2tuner and locast2dvr is that locast2tuner does not require ffmpeg anymore. Actually, I completely dropped support for it and only implemented the direct mode that locast2dvr supports. Next to that, I removed a few debugging features (like --multiplex-debug), that don't seem to be used.
Even though this project started as a locast to PMS interface, it's more focused on integrating locast with Emby, since Emby provides a bit more functionality when it comes to Live TV and Tuner (like m3u tuners, XMLTV, etc).
This project isn't complete yet. It works, but there are a few things I'd like to get done. These can be found on the Issues page
Before you get started with installing and running locast2tuner, make sure you have an active locast.org account with an active donation.
Ubuntu/Debian packages are available for both amd64 and arm7 (Raspbian):
# Add the PPA key
$ curl -s "https://wouterdebie.github.io/ppa/KEY.gpg" | sudo apt-key add -
# Add the locast2tuner repository
$ sudo curl -o /etc/apt/sources.list.d/locast2tuner.list "https://wouterdebie.github.io/ppa/sources.list"
$ sudo apt update
# Install locast2tuner
$ sudo apt install locast2tunerCreate a config file. Don't forget to edit the config file!
$ sudo cp /etc/locast2tuner/config.example /etc/locast2tuner/config
# Edit the config file
$ nano /etc/locast2tuner/configFinally, enable and start the service:
$ sudo systemctl enable locast2tuner
$ sudo systemctl start locast2tunerA MacOS package is available though Homebrew:
$ brew tap wouterdebie/repo
$ brew install locast2tunerA Docker image is available from ghcr.io/wouterdebie/locast2tuner:latest and is built from this Dockerfile.
To run:
# Create a config directory (e.g. $HOME/.locast2tuner) and copy the example file in there:
$ mkdir $HOME/.locast2tuner
$ curl -o $HOME/.locast2tuner/config https://raw.githubusercontent.com/wouterdebie/locast2tuner/main/assets/config.example
# ... edit the file ...
$ docker pull ghcr.io/wouterdebie/locast2tuner:latest
$ docker run -p 6077:6077 -v $HOME/.locast2tuner/:/app/config --name locast2tuner -d ghcr.io/wouterdebie/locast2tuner:latestIf you'd like to use docker-compose you can use the sample docker-compose.yml.
Note: The instructions above will work with Docker on Linux and Mac. If you are using Docker for Windows, you will have to modify the volume mapping (
-v) accordingly. You may also have to rundos2unix configbefore launching the container to remove DOS/Windows carriage-returns.
The only build requirement locast2tuner has is Rust 1.50.0+.
- MacOS:
brew install rust - Linux:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ git clone https://github.com/wouterdebie/locast2tuner
$ cd locast2tuner
$ cargo build --releaseYou'll end up with a binary in ./target/release/locast2tuner. You can copy this to the directory of your choosing (/usr/local/bin is a good place to start).
For usage options, please run locast2tuner -h.
locast2tuner parameters can be specified as either command line arguments or in a TOML configuration file that can be specified using the --config argument.
The configuration file format is:
string_option = "<value1>"
flag = <true/false>
numerical_option = <number>
list_option = ["<value1>", "<value2">]Example:
username = "<Locast username>"
password = "<Locast password>"
verbose = 2
multiplex = true
override_zipcodes = ["85355", "90210"]See assets/config.example for more information and a description of each option.
You can display your running config (which could be a combination of a config file and command line parameters) by opening the /config path (e.g. http://127.0.0.1:6077/config). Normally the password is obfuscated, but if you add the query parameter show_password (e.g. http://127.0.0.1:6077/config?showpass), the password will become visible.
Along with the technical info below, detailed instructions are available for integrating locast2tuner with both Plex and Emby if you want to get started quickly.
By default locast2tuner uses your IP address to determine your location, but it also allows you to override the locast.org location you're creating a Tuner for:
override_zipcodes, which takes a comma separated list of ZIP codes as an argument. E.g.--override_zipcodes 90210,55111for Los Angeles and Minneapolis.
locast2tuner allows starting multiple instances. This is done using the override_zipcodes option. A file with all available locast regions is included in the locast2tuner distribution.
When using multiple regions, locast2tuner will start multiple instances on TCP ports starting at the value that is specified with the port (or the default 6077) argument and incremented by one and it will generate UUIDs for each tuner.
Note: PMS supports multiple devices, but does not support multiple Electronic Programming Guides (EPGs). Emby supports both. I personally use Emby since it allows for multiple EPGs.
locast2tuner can act as both a HDHomerun device or as an m3u tuner. Plex mainly supports HDHomerun, while Emby supports both. In case locast2tuner is used as an HDHomerun device it will copy the mpegts stream from locast to the Media server. When using locast2tuner as an m3u tuner, it will pass on the m3u from locast to the media server without any stream interference. This means that the media server will directly connect to
the stream.
- For use as a HDHomerun tuner, use
IP:PORT(defaults to127.0.0.1:6077) to connect - For use as an m3u tuner, use
http://IP:PORT/tuner.m3u(defaults tohttp://127.0.0.1:6077/tuner.m3u) as the URL to connect.
locast2tuner also provides Electronic Programming Guide (EPG) information from locast.org. This is served in the XMLTV format. Emby and PMS both have support for XMLTV which can be used by adding http://IP:PORT/epg.xml (defaults to http://127.0.0.1:6077/epg.xml) as an XMLTV TV Guide Data Provider.
locast2tuner normally starts an HTTP instance for each Tuner, starting at port (default 6077). But with the option --multiplex, it will start a single HTTP interface multiplexing all Tuners through one interface for both streaming and EPG.
For example: if you use --multiplex --override_zipcodes=90210,55111, all channels from both ZIP codes will be available, but multiplexed at localhost:6077.
Note: This type of multiplexing makes sense in Emby, since you can add a single tuner at http://PORT:IP or http://PORT:IP/lineup.m3u and a single EPG at http://PORT:IP/epg.xml
In case you override multiple zip codes, Emby and Plex will sort channels by channel number, which means channels from different locations might be intermingled. In order circumvent this, you can remap channels. locast2tuner offers two ways of remapping channels. Note that these two options are mutually exclusive, but both can appear in a config file. If both appear, then the --remap option takes precedence.
The easiest way is to use --remap option. This causes locast2tuner to rewrite the channel number based on the amount of instances there are. Locast will remap a "channel_number" to "channel_number + 100 * instance_number", where the instance_number starts at 0. E.g. you override 3 zip codes, then the channels from the first location will be untouched (since 100*0 == 0 the stations for the second location will start at 100 (e.g. 2.1 CBS becomes 102.1 CBS) and the stations for the third location will start at 200 (e.g. 13.2 WWFF becomes 213.2 WWFF).
Another way to do remapping is to use the --remap_file=filename option. You specify a JSON file containing your remappings. To get your current mappings, you can go to http://PORT:IP/map.json. Copy that content to a JSON file (you'll want to pretty it up too to make it easier to work with) and you can edit that JSON file, save it, and then use this option to load those remappings the next time you run locast2tuner. You will need to restart locast2tuner in order to see any changes you made (and you may need to recreate your tuner/EPG setup to have Plex or Emby reflect the right channels). NOTE This is currently a manual edit process, so if you want to go this route, please be sure that the JSON content is valid JSON before trying to use it. A web-based remap editor is in the works.
locast2tuner has a few options for logging: directly to the terminal (default), logging to a file and logging through syslog. You can combine the way you want to log by specifying multiple options:
--quiet: disable logging to the terminal--syslog: log through syslog--logfile <filename>: log to a file separately
When you encounter a bug, please use Github Issues:
- Add a detailed description of the issue you're experiencing.
- Explain what steps can be taken to reproduce the issue.
- If possible, add an excerpt of the log file that shows the error.
- Add a copy of your config. You can get a copy of your running config by opening
/configin a browser (e.g http://localhost:6077/config). This will not expose your locast password. If you can't access/config, please add your config file without your password. - Before submitting, mark the issue as a "Bug".
When you have a features you'd like to see added, please use Github Issues and mark the issue as an "Enhancement".
If you're so awesome that you want to fix bugs or add features yourself, please fork this repository, code, and create a Pull Request. Please squash your commits into a single commit before sending the pull request.