MPV-IPTV-Player

Project Overview

MPV IPTV Player is deeply customized on the mpv player and the uosc interface framework, designed for live TV and catch-up. It offers a four-level sliding menu that drills down from groups to channels, date buckets, and the EPG, with a top search box that matches channel names only and supports Chinese, full pinyin, and initials. Beyond live playback, it supports XMLTV EPG data with time-jump catch-up, plus cached startup and background refresh for remote M3U subscriptions.

A remote-like four-level menu that keeps IPTV live and catch-up well organized.

Key Features

• Four-level sliding menu: drills down through groups, channels, date buckets, and the EPG, with channel search on top
• Channel search: matches Chinese, full pinyin, and initials, matching channel names only, not program titles
• In-group zap: switch to the previous or next channel within the current group during live playback
• EPG catch-up: supports XMLTV EPG data with time-jump catch-up
• Catch-up preload: queues the next segment as the current one nears its end to reduce stutter
• Catch-up search: searches all catch-up programs across channels in reverse time order
• Remote subscription: configure a remote M3U URL to start instantly from local cache, then refresh in the background
• Force refresh: one-key refresh of the EPG, and in subscription mode of both the M3U and the EPG
• History memory: automatically saves and restores the last channel, merging writes during rapid zapping to cut IO
• Smart context menu: shows different menus for IPTV and ordinary video

Target Audience

• Users who watch IPTV live streams with mpv
• Live TV users who need an EPG and catch-up
• Users who like fast channel finding with keyboard shortcuts

Quick Start

1. Download mpv (a Windows build is recommended)
2. Put the repository's portable_config into the mpv root directory
3. Double-click a local M3U file, or run mpv tv.m3u on the command line
4. Press F8 to open the IPTV menu and type a channel name to filter
5. For a remote subscription, put the M3U URL into m3u_download_url in script-opts/epg.conf, then start mpv with no arguments
6. Press Shift+F9 to force-refresh the EPG, and F9 to search catch-up programs across channels

Core Advantages

• Clear menus: the four-level sliding menu makes finding channels and reading the EPG intuitive
• Thoughtful search: Chinese, pinyin, and initials are supported, matching channel names only to avoid false hits
• Smooth catch-up: preloading queues the next segment early to cut switching stutter
• Fast startup: remote subscription mode starts instantly from local cache, then refreshes in the background

System Requirements

Item	Requirement
Player	mpv
UI framework	uosc 5.12 (bundled and customized with the config)
OS	Windows, Linux, macOS
Data sources	M3U/M3U8 live sources, optional XMLTV EPG

Notes

• If the EPG is missing, check that x-tvg-url is reachable and verify the download URL in epg.conf
• If catch-up does not work, check that the catchup-source time template in the live source is correct
• Some channels fail to open directly in mpv; the script retries with HLS only when mpv clearly errors on a source that looks like IPTV
• This script is for study and research only; follow local laws and use IPTV resources responsibly