# hdtilt 中文文档 规范地址：https://npmcn.com/package/hdtilt/ 版本：0\.7\.1 npm 元数据更新时间：2026-11-03T17:21:40.374Z 中文译文更新时间：2026-11-03T20:27:23.447Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/hdtilt 原文对照：https://npmcn.com/package/hdtilt/?lang=original 项目主页：https://hdtilt.com/ 源码仓库：https://github.com/profullstack/hdtilt.com ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.3 MB，47 个文件 - 模块格式：ESM + CJS - TypeScript 类型：未声明 - Node.js 要求：\>=22\.6 - 运行依赖：12 个 - 首次发布：2026-10-09T22:19:11.539Z - 最新版本发布：2026-11-03T17:21:40.190Z - 已发布版本数：23（近 12 个月 23 个） ## 中文简介 开源IPTV播放器：M3U， xstream Codes和XMLTV，带有电视指南。Web/PWA，桌面，CLI， TUI， MCP和API。 ## 安装 ```sh npm install hdtilt ``` 也可以使用：`pnpm add hdtilt`、`yarn add hdtilt`、`bun add hdtilt` ## README # hdtilt **一个开源的IPTV播放器，像TiviMate一样工作。** 带上你自己的M3U播放列表或xstream代码登录并获得频道列表，电视指南和追赶。它可以在浏览器（可安装的PWA）、桌面和终端中运行。 **[hdtilt.com](https://hdtilt.com/)** ·麻省理工学院许可·无账户，无跟踪，无渠道 Hdtilt是一个播放器。它没有任何内容。您可以从您已经付费的提供商或您有权观看的任何来源添加播放列表。 ## 它是做什么的 - **播放列表:** M3U / M3U8 url，本地 `.m3u` 文件、xstream代码(`player_api.php`)登录。一个Xtream `get.php` 作为M3U粘贴的链接被检测并升级到xstream API。 - **电视指南:** XMLTV（纯xml或xml） `.gz`)，取自播放列表 `url-tvg` 或者是手写的。通道通过 `tvg-id`，然后是名字。显示什么是现在和下一个，与进度条和一个完整的指导网格。 - **追赶:** xstream移时，加上M3U `catchup` / `catchup-source` / `tvg-rec` 形式(`default`， `append`， `shift`， `flussonic`）. - **回放** 通过 [`@profullstack/player`](https://github.com/profullstack/player)： HLS (HLS .js), MPEG-TS （mpeg .js）和MP4。它重新启动停滞的直播流并解释编解码器故障。 - **电影和节目：** xstream线的电影和系列在他们自己的标签中，一次一个类别（一个大的线有成千上万的标题，所以没有一次加载它们）。搜索涵盖所有标题；一部剧以季和集开头；继续看刚才的简历，下一集就开始了。 供应商提供的电影是被撕开的，通常是带有AC-3 / E-AC-3 / DTS声音的MKV，没有浏览器播放，所以服务器在运行中转换它们：图片被复制，只有声音变成AAC（便宜），以HLS的形式传递。查找经过转换的内容将在那里重新启动转换。▼跳跃10秒/ 30秒； `n` 是下一集。一个普通的M3U `/movie/` 和 `/series/` 条目也显示在那里。 - **字幕** 从 [OpenSubtitles](https://www.opensubtitles.com/) 在任何电影或剧集：CC按钮(或 `c`)列出在你的语言中存在的，最好的匹配在前面。匹配使用提供者的TMDB id（如果有的话），否则使用清理后的标题和年份（按其节目、季节和剧集划分的剧集），并且文件本身的moviehash将为该片段制作的字幕放在顶部（标记为THIS file）。−½s / +½s（或面板中的“↑”/“↑”）固定时间；每个标题都会记住选择和时机。 每个文件都从open字幕中获取一次并保存，所以有人已经看过的带有字幕的电影不需要任何费用。 - **每次查看一页：** `/watch/`， `/channels/`， `/favorites`， `/recent`， `/guide` (列表 `?q=` 过滤), `/vod/movies/`， `/vod/shows/`， `/vod/show/`， `/settings`， `/account`． 每一个都可以加入书签或重新加载，浏览器的后退按钮（或遥控器的后退按钮）可以后退。 - **全球导航** 与直播电视（带过滤框），电影和节目，电视指南，★收藏夹，最近，帐户和设置。它总是在画面外的屏幕上；在图片上方，“后退”或“菜单”会将其调出，以供遥控器对焦。 - **iPhone和iPad Safari：** 它们没有媒体源扩展，所以它们不能直接播放MPEG-TS流。当提供HLS版本时，hdtilt要求xstream行提供HLS版本，否则服务器将流重新打包为HLS（）。`ffmpeg -c copy`（没有转码，由观看该频道的所有人共享）。Self-hosters需要 `ffmpeg` 在PATH上，或 `HDTILT_FFMPEG`。 - **最喜欢的:** 在任何频道行或频道横幅上点击☆，或按F.它们位于导航中的★收藏夹下，并与您的帐户同步。 - **TiviMate基础知识：** “↑/↓”选择“通道”，“OK”打开列表，“options”打开组，数字跳转到通道号，“Back”返回到上一个通道。收藏夹和最近记录是内置的。每个过滤器（Live TV, guide, Movies & Shows， CLI和MCP）发现你按任何顺序输入的所有单词，忽略大小写，重音和标点符号，所以 `espn us` 找到“US| ESPN HD”和 `sports1` 找到“Sports 1”。在电视浏览器（Silk On Fire TV、Android TV、webOS、Tizen）上，大▲▼按钮可以浏览每个列表、指南和类别，因为电视指针无法在页面内滚动列表； `?pager=on` 或 `?pager=off` 在任何设备上打开或关闭它们。使用鼠标、触摸、键盘或电视遥控器（Fire TV、Android TV、webOS、Tizen按键）即可工作。 ## 账户 在hdtilt.com上，首先是一个帐户：注册（用户名，电子邮件，密码），确认电子邮件，然后添加您的播放列表。它可以让你的播放列表、收藏夹和最近的频道在你观看的每个屏幕上保持相同。桌面应用和自托管 `hdtilt serve` 不需要解释。 - **用户名和密码。** 使用您的用户名或电子邮件登录。电视没有邮件客户端，也没有密码，所以密码是进入其中的一种方式。 - **确认邮件后，账户才能登录。** 这个链接会让你直接登录，而“忘记密码了吗？”会发送一个重置链接。 - **使用CoinPay登录** 首先是登录和注册（OAuth 2.1代码+ PKCE S256 +状态+ nonce针对coinpayportal.com）。该账户绑定到您的CoinPay `sub`第一次登录CoinPay会创建一个新账户，现有账户在登录时从其账户页面连接CoinPay。当CoinPay是账户的唯一进入方式时，断开连接被拒绝。服务器env: `COINPAY_OAUTH_CLIENT_ID`， `COINPAY_OAUTH_CLIENT_SECRET`。 - **CLI和TUI使用OAuth 2.1登录：** `hdtilt login` 打开浏览器（授权码+ PKCE，一个环回重定向），并且 `hdtilt login --manual` 通过粘贴代码在SSH上工作；它打开的登录页面也提供CoinPay的登录功能。令牌存在于 `~/.config/hdtilt/auth.json` (0600)。 `hdtilt sync` 将帐户的播放列表和收藏夹合并到本地配置中，并且 `hdtilt tui` 启动时同步。 - 同步库中的提供程序登录是静态加密的（AES-256-GCM）。 ## 每一个面 | 表面 | 如何 | | --- | --- | | Web / PWA | [hdtilt.com](https://hdtilt.com/),或 `hdtilt serve` 在你自己的盒子里 | | 桌面 | 电子应用程序（Linux AppImage/deb, macOS dmg, Windows exe）从 [释放](https://github.com/profullstack/hdtilt.com/releases) | | CLI | `hdtilt now`， `hdtilt play cnn`， `hdtilt guide 101` … | | 途易 | `hdtilt tui`群组、频道和正在播放的节目；输入播放在mpv或VLC | | MCP | `hdtilt mcp` (它的),或 `POST /mcp` 在任何服务器上； `movies_shows` 浏览和搜索电影和电视剧 | | API | JSON在 `/api` （`POST /api/vod` 对于电影和节目)，加上流代理在 `/p/` 和转换 `/hls/` | ## 安装 ```sh curl -fsSL https://hdtilt.com/install.sh | sh ``` 这样就安装了 `hdtilt` 命令为 `~/.local` (无根)。如果有的话，它使用Node 22+ 一个，否则它将获取一个正式的Node构建（校验和验证） `~/.local/share/hdtilt`。 重新运行以升级； `sh -s -- --version X` 别针一放；用 `sh ~/.local/share/hdtilt/uninstall.sh`． 桌面应用程序（AppImage, deb, dmg, exe）在 [发布页面](https://github.com/profullstack/hdtilt.com/releases/latest)。 或者自己安装软件包： ```sh npm i -g hdtilt # or: bunx hdtilt hdtilt add home http://provider.example/get.php?username=U&password=P&type=m3u_plus hdtilt now # what's on hdtilt tui # browse and play (needs mpv or VLC) hdtilt serve # the web app on http://127.0.0.1:8930 ``` Xtream代码: ```sh hdtilt add home --xtream http://provider.example:8080 --user U --pass P ``` 播放列表和登录 `~/.config/hdtilt/config.json` (0600)模式。桌面应用和 `hdtilt serve` 读取相同的文件，因此从CLI添加的播放列表显示在窗口中。 ## CLI ``` hdtilt add [--epg ] hdtilt add --xtream --user --pass

hdtilt playlists | use | remove | refresh [name] hdtilt groups hdtilt channels [query] [--group ] [--json] hdtilt now [query] [--group ] hdtilt guide [--hours 12] [--from -6] hdtilt url [--at ] # --at = catch-up hdtilt play [--player mpv|vlc|ffplay] hdtilt fav hdtilt subs --key [--user --pass

] hdtilt subs [--year Y] [--season S --episode E] [--lang en,fr] [--tmdb id] [--get <n> -o file.vtt] hdtilt login [--manual] | whoami | sync | logout hdtilt tui | serve [--port] [--host] [--public] | mcp ``` 通道可以通过其编号、id或其名称的一部分来命名。 ## MCP 将其添加到任意MCP客户端： ```json { "mcpServers": { "hdtilt": { "command": "npx", "args": ["-y", "hdtilt", "mcp"] } } } ``` 工具: `list_playlists`， `add_playlist`， `list_groups`， `list_channels`， `whats_on`， `channel_guide`， `stream_url` (追赶), `movies_shows`， `find_subtitles`， `fetch_subtitle` (本地)。通过HTTP (`POST /mcp`)，公共服务器不保留播放列表，因此每次调用都传递自己的播放列表 `source`。 ## API | 方法 | 路径 | 主体/结果 | | --- | --- | --- | | 得到 | `/api/health` | `{ ok, version, public }` | | 帖子 | `/api/load` | `{ source }` → `{ channels, groups, epgUrl, account }` | | 帖子 | `/api/guide` | `{ url, channels:[{id,name,tvgId}], from?, to? }` → `{ programmes: { [channelId]: [...] } }` | | 帖子 | `/api/nownext` | `{ url, channels }` → `{ [channelId]: { now, next } }` | | 得到 | `/api/playlists`， `/api/playlists/:name` | 仅本地安装 | | 帖子 | `/api/auth/register` `login` `verify` `resend` `forgot` `reset` `refresh` `logout` | 帐户（每个地址每分钟20次） | | 得到 | `/api/me` | 已登入的帐户(`Authorization: Bearer`（会话或OAuth令牌） | | 取/放 | `/api/library` | 同步库；把 `{ data, baseVersion }`如果另一个设备先写入，则为409 | | 得到 | `/.well-known/oauth-authorization-server` | OAuth 2.1元数据 `/oauth/token`， `/oauth/revoke`;客户端 `hdtilt-cli` | | 帖子 | `/oauth/device_authorization` | 电视登录(客户端 `hdtilt-tv`）： `{ device_code, user_code, verification_uri }`;批准在 `/link`,调查 `/oauth/token` 使用device\_code授权 | | 帖子 | `/api/tv/load` `channels` `vod` | Roku应用程序播放列表的页面视图：分组，然后是频道或标题页面，每个都有 `play: { url, format, fallback? }` | | 帖子 | `/api/subtitles` | `{ title?, year?, tmdbId?, season?, episode?, languages?, url? }` → `{ items: [{ fileId, language, release, downloads, hashMatch, … }], moviehash }` | | 得到 | `/subs/<fileId>.vtt?shift=<s>` | 其中一个副标题为WebVTT，线索移动 `shift` 秒 | | 得到 | `/hls/<base64url>/index.m3u8` | 重新打包为HLS的MPEG-TS流（用于没有MSE的浏览器） | | 得到 | `/p/<base64url>/<name.ext>` | 流代理;HLS播放列表被重写，因此片段和键通过它返回 | | 帖子 | `/mcp` | MCP json - rpc | `source` 是 `{ "type": "m3u", "url": "…" }` 或 `{ "type": "xtream", "server": "…", "username": "…", "password": "…" }`，加上可选的 `"epg"`。 ## Roku `roku/` 是hdtilt.com的原生SceneGraph应用程序。第一次发射时，它会显示一个代码；开放 **hdtilt.com/link** 在手机上，登录并输入它。然后打开该帐户的播放列表： 收藏夹，所有频道，搜索，电影，节目和每个组，用▲▼来改变频道。 流媒体的Roku解码播放直接从提供商；传输流（以及任何可以传输流的东西） 失败)通过hdtilt的HLS重新设计。 构建副加载zip `npx -p brighterscript bsc --project roku/bsconfig.json` （`dist-roku/hdtilt-roku.zip`（也附在每个版本中），然后将其上传到 `http://<roku-ip>` 设备处于开发者模式。 ## 隐私和代理 在hdtilt.com上，播放列表和登录信息被保存下来 **在浏览器中** （IndexedDB），并发送给服务器仅用于加载列表。那里没有存储任何东西。浏览器无法播放 `http://` 流 `https://` 页，大多数提供商流不发送CORS头，所以这些流通过hdtilt.com的代理。公共代理只服务于登录的观看者（在登录时设置HttpOnly媒体cookie，因为视频元素不能发送令牌），拒绝私有和内部地址，并限制每个观看者并发3个流。 如果你不想中间有任何东西，可以使用桌面应用程序或 `hdtilt serve`． 两者都在您自己的机器上运行相同的服务器，其中代理也可以到达LAN上的调谐器。 ## 自托管 ```sh git clone https://github.com/profullstack/hdtilt.com && cd hdtilt.com bun install && bun run build PORT=8930 node bin/hdtilt.js serve --host 0.0.0.0 --public # --public for a shared server ``` 环境: `PORT`， `HOST`， `HDTILT_PUBLIC=1`， `HDTILT_JWT_SECRET` （打开账户）， `DATABASE_URL` （Postgres用于帐户，内存没有）， `HDTILT_LIBRARY_KEY`， `RESEND_API_KEY`， `MAIL_FROM`， `SITE_URL`， `HDTILT_ISSUER` （CLI的帐户服务器）， `HDTILT_UA` （发送给提供商的用户代理）， `HDTILT_HOME` / `HDTILT_CACHE`， `HDTILT_PLAYER`， `OPENSUBTITLES_API_KEY` (打开字幕；免费 [opensubtitles.com/consumers](https://www.opensubtitles.com/consumers)）， `OPENSUBTITLES_USERNAME` / `OPENSUBTITLES_PASSWORD` （一个帐户的每日下载津贴，而不是每个IP 5）， `HDTILT_SUBS_PER_DAY` （公共服务器上每个观看者每天的新下载，默认为10）。 ## 发展 ```sh bun install bun test # core, server, proxy, MCP and CLI against a fake provider bun run lint bun run dev # build the web app and serve it bun run desktop # the Electron window ``` 布局: `src/core` （playlists, xstream， XMLTV, guide, config；大部分也在浏览器中运行）， `src/server` （http + McP）， `src/cli` （TUI，播放器启动器）， `web/` (市政工程局), `desktop/` (电子) `bin/hdtilt.js`。 ## 许可证 MIT©Profullstack, Inc。 ## 常见问题 ### hdtilt 是什么？ 开源IPTV播放器：M3U， xstream Codes和XMLTV，带有电视指南。Web/PWA，桌面，CLI， TUI， MCP和API。 ### 如何安装 hdtilt？ 在项目目录运行 npm install hdtilt，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hdtilt，可以用 npx hdtilt 直接运行。 ### hdtilt 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/hdtilt 是否存在。 ### hdtilt 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### hdtilt 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.6。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### hdtilt 可以商用吗？ hdtilt 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### hdtilt 还在维护吗？ 最新版本 0\.7\.1 发布于 2026/11/04（今天）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。