hdtilt

An open-source IPTV player that works like TiviMate. Bring your own M3U playlist or Xtream Codes login and get a channel list, a TV guide and catch-up. It runs in the browser (installable PWA), on the desktop, and in the terminal.

hdtilt.com · MIT licensed · no account, no tracking, no channels included

hdtilt is a player. It ships with no content. You add a playlist from a provider you already pay for, or from any source you have the right to watch.

What it does

• Playlists: M3U / M3U8 URLs, local .m3u files, Xtream Codes (player_api.php) logins. An Xtream get.php link pasted as an M3U is detected and upgraded to the Xtream API.
• TV guide: XMLTV (plain or .gz), taken from the playlist's url-tvg or given by hand. Channels are matched by tvg-id, then by name. Shows what's on now and next, with progress bars and a full guide grid.
• Catch-up: Xtream timeshift, plus the M3U catchup / catchup-source / tvg-rec forms (default, append, shift, flussonic).
• Playback through @profullstack/player: HLS (hls.js), MPEG-TS (mpegts.js) and MP4. It restarts stalled live streams and explains codec failures.
• Movies & Shows: an Xtream line's films and series in their own tab, a category at a time (a big line has hundreds of thousands of titles, so nothing loads them all at once). Search covers every title; a show opens into seasons and episodes; Continue watching resumes where you stopped, and the next episode follows. Providers serve films as ripped, usually MKV with AC-3 / E-AC-3 / DTS sound that no browser plays, so the server converts them on the fly: the picture is copied, only the sound becomes AAC (cheap), delivered as HLS. Seeking past what is converted restarts the conversion there. ◀ / ▶ jump 10 s / 30 s, n is the next episode. A plain M3U's /movie/ and /series/ entries show up there too.
• Subtitles from OpenSubtitles on any film or episode: the CC button (or c) lists what exists in your language, best match first. Matches use the provider's TMDB id when it has one, else the cleaned-up title and year (an episode by its show, season and episode), and a moviehash of the file itself puts subtitles made for that exact rip on top (marked THIS FILE). −½s / +½s (or ◀ / ▶ in the panel) fix timing; the pick and its timing are remembered per title. Each file is fetched from OpenSubtitles once and kept, so a film someone already watched with subtitles costs nothing.
• One page per view: /watch/<channel>, /channels/<group>, /favorites, /recent, /guide (lists take ?q= to filter), /vod/movies/<category>, /vod/shows/<category>, /vod/show/<id>, /settings, /account. Each can be bookmarked or reloaded, and the browser's Back button (or a remote's) steps back through them.
• A global nav with Live TV (with a filter box), Movies & Shows, TV Guide, ★ Favorites, Recent, Account and Settings. It is always on screen outside the picture; over the picture, Back or Menu brings it up, focused for the remote.
• iPhone and iPad Safari: they have no Media Source Extensions, so they cannot play an MPEG-TS stream directly. hdtilt asks an Xtream line for its HLS version when it offers one, and otherwise the server repackages the stream as HLS (ffmpeg -c copy, no transcoding, shared by everyone watching that channel). Self-hosters need ffmpeg on the PATH, or HDTILT_FFMPEG.
• Favorites: tap ☆ on any channel row or on the channel banner, or press F. They sit under ★ Favorites in the nav and sync with your account.
• The TiviMate basics: ↑/↓ zaps channels, OK opens the list, ◀ opens groups, digits jump to a channel number, Back returns to the last channel. Favorites and recents are built in. Every filter (Live TV, the guide, Movies & Shows, the CLI and MCP) finds all the words you type in any order, ignoring case, accents and punctuation, so espn us finds "US| ESPN HD" and sports1 finds "Sports 1". On a TV browser (Silk on Fire TV, Android TV, webOS, Tizen) big ▲ ▼ buttons page through every list, the guide and the category rails, because a TV pointer cannot scroll a list inside the page; ?pager=on or ?pager=off turns them on or off on any device. Works with a mouse, touch, a keyboard or a TV remote (Fire TV, Android TV, webOS, Tizen keys).

Accounts

On hdtilt.com an account comes first: sign up (username, email, password), confirm the email, then add your playlist. It keeps your playlists, favorites and recent channels the same on every screen you watch on. The desktop app and a self-hosted hdtilt serve need no account.

• Username and password. Sign in with either your username or your email. A TV has no mail client and no passkey, so a password is the way in on one.
• The email is confirmed before the account can sign in. The link signs you straight in, and "Forgot your password?" sends a reset link.
• Sign in with CoinPay comes first on sign-in and sign-up (OAuth 2.1 code + PKCE S256 + state + nonce against coinpayportal.com). The account is bound to your CoinPay sub, never matched by email: a first CoinPay sign-in makes a new account, and an existing account connects CoinPay from its Account page while signed in. Disconnect is refused when CoinPay is the account's only way in. Server env: COINPAY_OAUTH_CLIENT_ID, COINPAY_OAUTH_CLIENT_SECRET.
• The CLI and TUI sign in with OAuth 2.1: hdtilt login opens the browser (authorization code + PKCE, a loopback redirect), and hdtilt login --manual works over SSH by pasting a code; the sign-in page it opens offers Sign in with CoinPay too. Tokens live in ~/.config/hdtilt/auth.json (0600). hdtilt sync merges the account's playlists and favorites into the local config, and hdtilt tui syncs when it starts.
• Provider logins inside a synced library are encrypted at rest (AES-256-GCM).

This is the beginning of the README. Read the rest at the original. Read the full README ↗