tvtui 2.0.0

Terminal UI for IPTV with EPG browsing

tvTUI

tvTUI is a fast terminal UI for browsing IPTV channels with EPG (now/next) information, favorites, categories, and quick search.

Features

• Search-as-you-type channel list with category tags.
• EPG preview with now/next details and descriptions.
• Favorites and history.
• Mouse support (scroll, click, double-click).
• Configurable player and subtitle defaults.

Install (pipx)

pipx install .

For a published package:

pipx install tvtui

Run

tvtui
tvtui -f
tvtui --categories

Keybindings

• Enter play selected channel
• f toggle favorites view
• F add/remove favorite
• c categories
• m content mode (tv/movie/series)
• s sort (default/name/category)
• r refresh channels/EPG
• / search mode
• Left/Right cycle description
• t subtitles on/off (next playback)
• h toggle help panel
• q quit

Mouse:

• Wheel scroll
• Click select
• Double-click play

Configuration

Config file defaults to ~/.config/tvtui/config.json.

{
  "epg_url": "https://raw.githubusercontent.com/doms9/iptv/refs/heads/default/EPG/TV.xml",
  "source_url": "https://s.id/d9Base",
  "streamed_base": "https://raw.githubusercontent.com/doms9/iptv/default/M3U8",
  "show_help_panel": true,
  "use_emoji_tags": false,
  "player": "auto",
  "player_args": ["--ontop"],
  "custom_command": ["myplayer", "--flag"],
  "custom_subs_on_args": ["--subs=on"],
  "custom_subs_off_args": ["--subs=off"],
  "mpv_subs_on_args": ["--sub-visibility=yes", "--sid=auto"],
  "mpv_subs_off_args": ["--sub-visibility=no", "--sid=no"],
  "vlc_sub_track": 1,
  "subs_enabled_default": false,
  "xtream_base_url": "http://xtreamcode.ex:8080",
  "xtream_username": "Mike",
  "xtream_password": "1234",
  "xtream_use_for_tv": true
}

Xtream API

If xtream_base_url, xtream_username, and xtream_password are set, use m to toggle content mode between live TV, movies, and series. The TV mode uses Xtream live streams when xtream_use_for_tv is true; otherwise it falls back to the M3U source.

Requirements

• Python 3.9+
• mpv or vlc for playback

Disclaimer

The default channel and EPG sources are provided for inspiration and testing. tvTUI is not affiliated with, endorsed by, or sponsored by those sources or their authors.

License

MIT. See LICENSE.