tv

A small Linux launcher for country-based IPTV playlists.

tv opens the matching iptv-org country playlist in mpv and returns the shell prompt immediately. It is meant to behave like a desktop app launcher, not like a long-running terminal command.

TV_COUNTRY=TR -> https://iptv-org.github.io/iptv/countries/tr.m3u
TV_COUNTRY=DE -> https://iptv-org.github.io/iptv/countries/de.m3u

Features

• single command: tv
• terminal settings wizard: tv settings
• no playlist URL input
• quiet background mpv launch
• optional HTTP proxy mode
• optional Linux network namespace mode for VPN/tunnel setups

Requirements

• Linux
• Bash
• mpv
• systemd, only for netns mode

Install

User install:

PREFIX="$HOME/.local" ./install.sh

System install:

sudo ./install.sh

Make sure the install directory is in PATH. For a user install:

export PATH="$HOME/.local/bin:$PATH"

Configure

Run:

tv settings

The wizard asks for:

• country code: TR, DE, US, ...
• network mode: direct, proxy, or netns
• proxy URL, only for proxy mode
• namespace name, only for netns mode

The first interactive run opens the settings wizard automatically if no config exists.

Run

tv

Extra arguments are passed to mpv:

tv --fullscreen

By default tv starts mpv in the background and suppresses mpv/ffmpeg output. For debugging:

TV_DETACH=0 tv
TV_DRY_RUN=1 tv

Network modes

direct

Uses the normal network connection.

proxy

Passes an HTTP proxy to mpv:

http://host:port

Configure it with tv settings.

netns

Runs mpv inside an existing Linux network namespace:

/run/netns/<name>

This works with any setup that provides a namespace: WireGuard, OpenVPN, Mullvad, ProtonVPN, NordVPN, or a custom VPS tunnel. tv does not create or manage the tunnel; it only launches mpv inside it.

Configuration

Settings are stored in:

~/.config/tv/config

A system-wide config may also be placed at:

/etc/tv/config

Typical config:

TV_COUNTRY=TR
TV_MODE=direct

Proxy config:

TV_COUNTRY=US
TV_MODE=proxy
TV_PROXY=http://127.0.0.1:8080

Namespace config:

TV_COUNTRY=DE
TV_MODE=netns
TV_NETNS=mullvad

Notes

Country selection chooses the iptv-org country playlist. It does not change your network location. If a stream is region-locked, use a proxy or namespace whose exit location is allowed to access that stream.

Some iptv-org entries may be offline, geo-blocked, or misconfigured upstream. tv keeps these player warnings out of the terminal by default.

Development

bash -n tv install.sh
TV_DRY_RUN=1 TV_COUNTRY=DE TV_MODE=direct ./tv

License

MIT