Awesome Open Source
Awesome Open Source


LiveTVH provides live TV streaming for Plex via Tvheadend, including metadata from Tvheadend's EPG, theTVDB, and The Movie DB.


  • Plays all Tvheadend video channels, audio channels, and recordings, including IPTV and ATSC/DVB sources.
  • Direct streaming when the codec and resolution of channels are set using Tvheadend channel tags.
  • Provides the Tvheadend EPG for channels in the Plex channel description.
  • Displays metadata and artwork from theTVDB (using EPG zap2it IDs if available) and The Movie DB.
  • Supports Tvheadend stable versions 4.2.x and unstable development versions 4.3.x.

Release notes

  • 2018.07.25 - LiveTVH 1.4

    • New: Support both plain and digest authentication for Tvheadend HTTP authentication
    • New: Channel artwork via HTTPS now falls back to SSL without authentication if necessary due to a Plex issue
    • Changed: Plex Web no longer supports direct streaming 256kbps audio, lowered specified audio bitrate for audio direct streaming
    • Bugfix: Recordings failed to display when resolution was not set
    • Bugfix: Plugin failed to respond if theTVDB metadata is enabled and is unreachable
    • Bugfix: Plugin failed to respond when accessing recordings if the Tvheadend recordings data contains invalid UTF-8 characters, added fallback to ISO-8859-1 characters
  • 2018.07.08 - LiveTVH 1.3

    • Changed: Tvheadend channel tags support additional codecs, resolutions, and radio (audio-only) channels
    • Changed: Changed image filenames to match Plex channel guidelines
    • Changed: Replaced deprecated string substitution per #18
  • 2017.05.22 - LiveTVH 1.2

    • New: Paginated channel lists with a configurable number of items per page - this helps with longer channel lists (a necessity for IPTV providers with thousands of channels).
    • New: Tvheadend recordings for playback - located at the end of the first page of the channel list (a display bug with several Plex clients prevents placing it at the beginning of the list).
    • New: Codec identification using Tvheadend channel tags (experimental). This can enable direct streaming for H264-AAC streams on some clients (see setup notes below).
    • Changed: EPG parser to improve support for IPTV sources, including using images for a show if specified in the EPG (if other metadata providers are not available or are missing artwork).
    • Changed: EPG item limit to 20k items/20MB (again, for IPTV sources).
    • Changed: Plex clients will now display channel thumbnails as video clip objects (widescreen thumbnails) if metadata providers are disabled.
    • Changed: Code housekeeping (partially PEP8-conformant)
    • Bugfix: transcoding quality options not visible during playback
    • Bugfix: episode names from EPG were not set on Plex for Android
  • 2017.05.14 - LiveTVH 1.1

    • EPG is no longer hard set - the number of EPG items requested is now based on the number of channels and hours of EPG data necessary (up to a maximum of 10,000 items or 10MB of data).
    • Bugfix: Thumbnails fallback to a channel logo when a show matches theTVDB but does not have a poster.
    • Bugfix: 12-hour time displays correctly on non-linux platforms.
    • Bugfix: Year displays for movies (when available from TMDb).
  • 2017.05.10 - Initial release 1.0


Plex Web Posters Screenshot Plex Web Screenshot Plex Web Recordings Screenshot Plex Home Theater Screenshot Plex Media Player Screenshot Plex iOS Screenshot


  1. Download LiveTVH.bundle and unzip to the Plex Media Server/Plug-ins directory. Alternatively, git clone this repository to the Plug-ins directory to keep track of the latest changes.

  2. Open the Tvheadend web interface and navigate to Configuration > Users > Passwords. Create a user and password.

  3. Navigate to Configuration > Users > Access Entries and create a new access entry for the user.

  4. Select "Web interface", Streaming > "Basic", and Video recorder > "Basic".

    Tvheadend Access Entry screenshot

  5. Set the LiveTVH preferences with the Tvheadend LAN IP address/hostname (or WAN for remote access), username, and password.

    Prefs Screenshot

  6. Watch!


  • Channels will take a bit of time to load initially while metadata is fetched and speed up over time as the cache is built up and stored for 30 days. Up to 30 channels per page works reasonably well.

  • Direct streaming of channels on Plex Web, iOS, Roku, and Android requires identifying the channel's codecs and resolution using Tvheadend channel tags. Create and set channel tags in Tvheadend as appropriate for each channel:

    • Video tags: H264, MPEG2, HEVC, VP8, VP9
    • Audio tags: AAC, AAC-LATM, AC3, EAC3, MP2, MP3, VORBIS
    • Video and audio tags may be combined into single tags: MPEG2-AC3, H264-AAC, etc.
    • Video resolution tags: HDTV, 720p, SDTV

    Tvheadend Channel Tags Screenshot

  • Radio (audio-only) channels are also identified using Tvheadend channel tags - create and set a Radio tag in Tvheadend on the appropriate channels for audio-only playback, as well as audio tags (for example, AAC) for direct streaming.

  • While Tvheadend recordings can be played, managing new recordings will need to be handled outside of Plex, or by using Plex DVR and tvhProxy).

  • Watching remotely may require Tvheadend to have a public-facing address, as some clients will attempt to directly play the Tvheadend stream instead of running through the Plex transcoder.

    In this case, putting Tvheadend behind a reverse proxy with SSL is highly recommended, as the Tvheadend username and password is sent using HTTP Basic Authentication and is not secure over plain HTTP.

  • LiveTVH preferentially searches for metadata on theTVDB using a show's zap2it ID if provided through Tvheadend's EPG.

    For example, zap2xml produces an XMLTV file with a zap2it ID for each show (if available) - Tvheadend includes this information in its EPG, and LiveTVH will use this ID to match the correct show. If a zap2it ID is not available, LiveTVH will fallback to searching by name.

    If searching theTVDB fails by zap2it ID but succeeds by name, LiveTVH will display the zap2it ID in the summary as an alert that the show's zap2it entry on theTVDB may be missing/incorrect - consider updating with the correct information to improve search results. For example, many shows are in the older SHxxxxxx format, while the current format is EPxxxxxxxx.

    zap2it Screenshot

Known Issues

  • Plex Web currently does not display a detailed pre-play page if metadata is enabled - this is a bug/side effect of setting up the channels as movies instead of video clips to display posters correctly. Channels can be played directly from the channel list.
  • Plex for Xbox One fails to play channels - this may be due to a known Plex issue.
  • Metadata searches are not localized.
  • Plex does not provide options to flag a stream as interlaced in channels - expect combing artifacts on Plex clients that do not support deinterlacing, unfortunately. Plex's native live TV viewing works with tvhProxy and supports deinterlacing.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (50,798
plex (79
iptv (26

Find Open Source By Browsing 7,000 Topics Across 59 Categories