帮助

三种格式，都是自带一切的 —— Python、Qt、libmpv 和 ffmpeg 都在下载包里，旁边不需要再装什么。

AppImage —— 拿不准就用它，任何发行版都能跑：

chmod +x dopeIPTV-*.AppImage
./dopeIPTV-*.AppImage

Debian 或 Ubuntu 上用 .deb：

sudo apt install ./dopeiptv_*_amd64.deb

Flatpak：

flatpak install --user dopeIPTV-*.flatpak

三种都有 arm64 版本，可用于树莓派或 ARM 服务器。

打开 .dmg，把 dopeIPTV 拖到「应用程序」。需要 macOS 15 或更新，应用运行在 Apple Silicon 上 —— 1.2.10 是最后一个带 Intel 构建的版本。

首次启动会被拒绝，因为应用没有经过 Apple 的公证。右键点应用选打开，然后在对话框里再点一次打开。如果这样还不行，看下面的「macOS 说无法打开这个应用」。

没有安装程序。把 dopeIPTV-*-windows-x64.zip 解压到任何地方 —— 用户文件夹就行，不需要管理员权限 —— 然后运行里面的 dopeiptv.exe。

为骁龙笔记本准备了原生 arm64 构建；x64 构建在那上面也能跑，只是通过模拟，因此更慢。

想在开始菜单或桌面放快捷方式：设置 → 界面 → 维护 → 创建快捷方式。压缩包里的 README.txt 列出了想彻底删除应用时需要删掉的一切。

首次启动会问你 Xtream Codes 账号的三样东西：

• 服务器 —— 带端口的地址，例如 http://example.com:8080。不是完整的播放列表网址，只要主机。
• 用户名和密码 —— 服务商给你的那组。

这些会被保存。以后要再加一个账号，或者改这一个：设置 → 播放列表。应用运行时就能切换播放列表，收藏和历史按播放列表分开保存。

可以。添加播放列表时选 M3U，粘贴服务商给你的地址。

不过 Xtream 账号能从应用里榨出更多东西 —— 回看、账号到期时间、服务商自己的节目指南 —— 因为这些来自一个 M3U 列表没有的 API。M3U 列表能播，也可以单独给它一个 XMLTV 指南地址，这就补上了大部分差距。

可以。设置向导提供演示频道：Mux、Apple 和 Bitmovin 的几路免费公开测试流，让你在输入任何东西之前先看看应用是怎么工作的。这些是官方测试流，不是谁的电视服务，你随时可以换成真正的播放列表。

在中间那列里双击，或者点右侧面板的 ▶ 播放。换一个频道是就地替换流，而不是把播放器拆掉重建 —— 这就是换台快的原因。

播放条上的上一个和下一个按钮会在你所处的那份列表里前后移动 —— 频道、某部剧集的分集、录制或历史。

电影、剧集、录制和回看 —— 凡是时长已知的内容：

• 把指针移到画面上，进度条会滑上来，带已播时间、总时长和 −10 秒 / +30 秒按钮。
• 在视频上点一下，然后用方向键：按一下跳十秒，按住则连续快进。

直播频道不能拖动，也刻意不显示进度条。要在直播频道里前后移动，需要时移 —— 见下文。

双击画面，或按 F。Esc 退出 —— 悬浮控制条上那个明确的退出全屏按钮也一样，它存在的意义正是让谁都不必知道 Esc。

控制条和鼠标指针在静止几秒后会自己隐藏，稍有移动就回来。

可以 —— 把播放器弹出成独立窗口，拖到你想要的位置。

它默认无边框：在画面上任意位置拖动即可移动。右键可选置顶、显示标题栏或退出。Esc 也能把它收回来。这期间主窗口照常工作。

播放条上的 ⚙ 按钮 —— 全屏控制条里也有 —— 装着与当前这路流有关的一切：

• 音轨和字幕轨
• 音频延迟，声音对不上时用
• 画面比例（16:9、4:3、拉伸等）
• 网络缓冲大小
• Stats for nerds：编解码器、分辨率、帧率、硬件解码、音画同步、丢帧、缓存和网速，实时叠在画面上

你选的轨道会被记住，剧集里还会带到下一集。如果想为所有流设一个偏好，见下面的设置。

• 空格 —— 暂停和继续
• F —— 全屏，Esc 退出
• ← / → —— 十秒，按住可持续快进退
• M —— 静音

在主窗口、全屏和弹出窗口里表现一致。

记得，对电影、剧集分集、录制和你自己的本地文件都记。再次打开时会问你要继续还是从头开始。

非常接近开头或结尾的位置会被刻意忽略，免得对刚开始看或其实已经看完的东西提议「继续」。

来自你的服务商。列表里每个直播频道都带进度条显示当前在播什么，详情面板显示接下来是什么。

指南按播放列表缓存在磁盘上，所以应用一启动就在屏幕上 —— 新的一份在后台下载并替换它。如果那次下载失败，缓存的指南会保留，而不是让你什么都看不到。

有。侧栏的节目指南按钮会打开一张覆盖全部频道、可搜索的节目网格，带可滚动的时间轴。搜索能按名称在所有频道里找到某个节目。

在有回看的频道上，双击已经播过的节目就会从存档里播放它。

给那份播放列表配一份自己的指南，替代服务商的：

1. 设置 → 播放列表
2. 选中播放列表并编辑
3. 在自定义指南栏里填一个 XMLTV 地址

它会取代服务商发来的那份。应用先按 EPG id、再按频道名把你的频道和这份指南对上，所以来自别处的指南通常也能对齐。

有些服务商发布的时间和他们实际播出的对不上。设置 → 播放 里有两个各自独立的修正：

• EPG 偏移会平移指南显示的每一个时间。
• 回看偏移平移回看和时移开始播放的位置，不动节目单本身。

它们分开，是因为服务商会在其中一个上出错而另一个正常。

有些服务商会为每个频道保留几天的录像。你的服务商这么做的地方，频道在列表里会带一个 ⏪ 标记，详情面板会写明存档往回有多少天。

某个频道没有标记，就是服务商没有为它提供存档。那是他们的设置，应用里没有任何东西能把它打开。

按播放器里的 ⏪ 按钮 —— 全屏控制条里也有 —— 或者右键点频道选时移。然后选从头开始。

播的是存档里的一段，所以能像电影一样拖动：进度条和方向键在里面都有效。

能。时移菜单会按天分组列出过去的节目 —— 双击其中一个就能看。也可以按固定步长往回跳，而这些步长会随你的服务商存档的实际深度而变，从三十分钟到一周。

有些服务商会接受存档请求，却悄悄给你直播信号。应用会检查并告诉你，而不是让你以为自己在看昨天的节目。

两个入口：

• 播放器里的 REC 按钮，录你正在看的。
• 右键点任意频道 → 录制，录你没在看的频道。

不选时长的话，它会一直录到你停止。录制中的文件可以边录边看。

都可以。REC 菜单提供 30 分钟、1、2 或 4 小时，定时录制则要一个开始时间和一个结束时间。

定时任务能挺过应用重启，但触发时应用必须在运行 —— 它是一个程序，不是后台服务。录制 → 进行中和已排期会显示待办的任务。

如果录的是你正在看的频道，不会：录制是从播放器自己的流上分出来的，不额外花费什么，在只允许同时一路流的常见账号上也能用。

但录制另一个频道，或者稍后才启动的定时任务，就会向服务商另开一条连接。

关于在播放器里录制有一点要知道：它在录制停止时收尾，所以停止播放、换台或者流出错都会结束它。

能，有两个层面。设置 → 录制 接受一个对所有录制都生效的大小上限 —— 一个数字加 MB、GB 或 TB。播放器的 REC 菜单里还有一个只对当前这次生效的快捷上限，从 250 MB 到 10 GB。

在你于设置 → 录制里指定的位置。侧栏的录制区可以浏览它们，子文件夹充当分类：可以建文件夹、重命名、在文件夹之间移动，也可以多选一次性删除。

一个单独的窗口，用网格同时显示 2、4、6 或 9 个直播频道，每一格都是独立的一路流。它们可以来自不同的播放列表，甚至不同的账号。

从侧栏打开；网格大小在设置 → 多画面里。双击某一格可以放大它。

点某一格就把声音给它 —— 红色边框标出你正在听的那一格。

右键点任意一格可以：静音、切换音轨和字幕轨、移动或与另一格互换、或者移除。带回看的频道会在自己那一格里得到独立的存档时间轴，于是你可以把一个频道往回倒，其他几个仍是直播。

因为确实如此 —— 每格一个。多数 IPTV 账号只允许同时一到两路流，所以九格的网格在大多数服务商那里会被直接拒绝。

应用会说一次，免得你从一堵失败的流里才发现。看到「已达连接数上限」，通常就是这个原因。

右键点频道、电影或分集 → 投送到 Chromecast…，然后选设备。直播频道以 HLS 发送，这正是 Cast 接收端期待的格式。

投屏会停止本地播放 —— 两者同时进行就相当于对服务商多开一条连接。播放器上方会有一条横幅写明设备和正在播的内容，并带停止按钮。在应用里播放任何东西同样会结束投屏、把播放交回来。

有些频道是普通的 H.264 视频，但音频是 Dolby Digital Plus。不是 Ultra 也不是 Google TV 的 Chromecast 没有对应解码器，会拒绝这路流而且不说原因。

应用会在这台电脑上转换这类流，并把结果放在你自己的局域网里：视频原样拷贝 —— 只重编码音频，代价很小 —— 而且只在设备确实拒绝之后才这么做。你的设备本来就能播的频道，永远拿到服务商的原始流，未经改动。

这需要 ffmpeg，它在每一个打包好的下载里都有。

设置 → Trakt。你在 trakt.tv 上建一个应用，把它给的两个密钥粘进去，然后在打开的浏览器里授权。

此后你看过的内容会被记录，待看列表和历史可以在应用里浏览。你自己的本地文件也会被记录，只要 TMDB 能认出这个文件。

能。侧栏的本地文件会浏览你在设置 → 本地文件里添加的文件夹。

系统已经挂载好的网络共享会自己出现 —— Linux 上的 gvfs SMB 挂载、macOS 上 /Volumes 下的共享、Windows 上的映射盘。对应用来说这些只是普通路径，所以它内部并没有一个可能出岔子的 SMB 客户端。

都有，在中间那列切换。

• 文件夹按磁盘上的样子原样展示目录树。
• 媒体库读取文件名，据此组成带季和集的剧集，电影归到「电影」下 —— 和服务商自己的分区形状一致。

来自 TMDB，凡是能按名称和年份匹配上的都有。匹配不上的会从视频里截一帧，音乐则从文件标签或文件夹里的封面图取封面。

文件名里既没有年份也没有发布标记的，绝不会去猜。这是有意的：错的海报比缩略图更糟。想让它被匹配上，就把年份加进文件名。

能。专辑会归置在一起，艺人、专辑和曲名来自标签，还有一个播放队列：加一首、把整个文件夹排进队列，或者让某首接着播。一首放完会自己接下一首。

另外还有可视化效果和十段均衡器。

它被移动了、被改名了，或者它所在的共享没有挂载。历史会说明是哪一种，并提议移除这条记录，而不是无声地失败。

如果是共享：挂上再试 —— 这条记录会和以前一样能用。

设置 → 界面。界面已翻译成 27 种语言，切换即时生效，无需重启。阿拉伯语、波斯语、希伯来语和乌尔都语会把整个布局镜像过来。

同一个标签页里有五套配色主题和七种强调色，即时生效。

设置 → 播放决定在你不每次动手的情况下应该发生什么：

• 偏好的音轨语言
• 字幕开或关，以及第一和第二偏好语言
• 默认画面比例和网络缓冲
• 「下一集」卡片提前多久出现 —— 关闭，或一到十分钟

播放器里的 ⚙ 菜单仍然可以为当前这路流覆盖其中任何一项。

能。一个 PIN 码保护被锁定的分类和被锁定的收藏分组。锁定的分组在输入 PIN 之前连里面有哪些频道都不显示 —— 它藏的是内容，不只是播放。

PIN 是加盐哈希后存储的，不是明文。

右键点任意频道、电影或剧集即可重命名或隐藏。结果实际上就是一份你自己编辑过的播放列表，按播放列表分别保存，而恢复默认频道…会把一切原样还原成服务商发来的样子。

整个分类也可以从分类的右键菜单里隐藏、重命名或锁定。被隐藏分类里的频道同样不会出现在「全部」里。

在设置 → 播放列表里想加多少份就加多少份，应用运行时随意切换。每一份都保有自己的收藏、历史、隐藏频道和重命名。

每一份还可以有自己的 XMLTV 指南地址和自己的刷新计划 —— 从不、启动时、每 2、6 或 12 小时、每天或每周。

日志能把「用不了」变成可以修的东西，而且凭据会被自动遮蔽掉，所以附到 issue 里是安全的。

从终端启动应用并设置 DOPEIPTV_LOG_FILE，它就会在屏幕之外再往那里写一份日志。

Linux — AppImage

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log ./dopeIPTV-*.AppImage

Linux — .deb 或 pipx

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log dopeiptv

macOS

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log \
  /Applications/dopeIPTV.app/Contents/MacOS/dopeiptv

Windows — PowerShell，在解压出来的文件夹里

$env:DOPEIPTV_LOG_FILE="$env:TEMP\dopeiptv.log"
.\dopeiptv.exe

复现问题，关掉应用，把文件附上。想要详细得多的内容，在同一条命令前加上 DOPEIPTV_LOG=debug。

从终端启动它 —— 上面那条答案给出了适用于你系统的确切命令 —— 然后看它打印了什么。多数情况下原因就写在那里。

打包好的构建自带所需的一切。如果你是用 pipx 从源码安装的，还需要发行版里的 mpv 和 ffmpeg：

sudo apt install mpv ffmpeg     # Debian/Ubuntu
sudo dnf install mpv ffmpeg     # Fedora
sudo pacman -S mpv ffmpeg       # Arch

内置播放器没有拿到视频显示面。

1. 打开 ⚙ → Stats for nerds，看看到底有没有帧进来 —— 这能把流的问题和显示的问题分开。
2. 在 Wayland 上试试设置 → 播放 → 通过 X11 后端运行，然后重启应用。
3. 从终端运行，找带 GL 或 mpv 字样的行。

它还没有经过 Apple 的公证。右键点应用选打开，然后在对话框里点打开 —— 或者在系统设置 → 隐私与安全性 → 仍要打开里放行。

如果 macOS 说的是应用「已损坏」，那是下载时打上的隔离标记。清掉它：

xattr -dr com.apple.quarantine /Applications/dopeIPTV.app

这两种提示都不表示应用有问题 —— 只是说明构建没有签名，而签名需要一张付费的 Apple 证书。

SmartScreen 不认识发布者，因为构建没有签名 —— 签名需要付费证书。点更多信息，再点仍要运行。

误报。其中两个原因在 1.2.10 里已经修掉：启动器现在从源码编译，而不再是杀毒引擎有特征码的那个现成文件；可执行文件也带上了正规的版本资源。

如果你的引擎仍然报，请在杀毒软件里放行该文件夹，并向 Microsoft 报告误报 —— 最终把问题解决掉的是这一步，而且是为所有人解决，不只是你。

应用会去问服务商，然后用人话告诉你原因，而不是甩一个干巴巴的错误：账号过期、已达连接数上限、流不存在、服务器连不上等等。

如果别的频道能播，问题就在这个频道。如果一个都播不了，看看设置 → 播放列表 —— 账号面板会显示到期日期和账号允许的连接数。

你的账号允许同时开一定数量的流，而它们都被占用了。按可能性排序：

1. 多画面开着 —— 每一格都是一条连接。
2. 正在录制另一个频道。
3. 另一台设备或另一个人在用这个账号。
4. 之前的会话在服务商那边还没超时；等一分钟往往就好了。

录制你正在看的那个频道不算第二条连接。

在 Wayland 上，GNOME 和 KDE 从与窗口匹配的桌面条目里取图标，而忽略程序自己设置的那个。AppImage 在有东西装上这样一个条目之前是没有的。

1. 应用第一次启动时会提议加一个。答应它 —— 然后重启应用，因为已经打开的窗口会保留它开启时的图标。
2. 如果你当时拒绝了，同一个开关在设置 → 播放里。
3. 如果图标仍然不出现，那是过期的图标缓存挡住了它。GTK 会读那个文件而不是去扫描文件夹：

rm ~/.local/share/icons/hicolor/icon-theme.cache

用 .deb 安装的话，条目本来就有，这些都不适用。

那个选项会启动系统里独立的 mpv 或 vlc，所以两者之一必须已安装 —— 内置播放器不需要任何额外东西，也不受影响。

sudo apt install mpv vlc        # Debian/Ubuntu
sudo dnf install mpv vlc        # Fedora
sudo pacman -S mpv vlc          # Arch