atv-player 详细帮助文档

本文档面向终端用户，按“快速开始 -> 主窗口 -> 播放器 -> 直播源 -> 插件 -> 排障”的顺序说明实际使用方法。

atv-player 是一个围绕 alist-tvbox 后端工作的桌面播放器：

• 主窗口负责登录、浏览内容、全局搜索、查看历史、管理插件和直播源。
• 播放器窗口负责实际播放、切换线路、恢复进度、管理字幕、弹幕、清晰度和媒体刮削。
• 应用会在本地保存大部分使用状态，以便下次启动时继续上次的工作位置。

如果你使用的是 GitHub Release 提供的打包版本，可直接按下面的“快速开始（3 分钟）”完成首次使用；如果你是从源码运行或自行打包，再看后面的源码运行说明。

如果你使用的是发布页面提供的打包单体包，推荐按下面顺序完成首次使用：

1. 下载与你平台对应的发行包并解压。
2. 直接运行 atv-player。
3. 启动 alist-tvbox 后端。
4. 在登录页输入后端地址、用户名和密码。
5. 登录成功后，在顶部搜索框输入影片名。
6. 双击结果进入播放。

如果你要直接打开 YouTube 等页面链接，还需要单独安装 yt-dlp。如果你在启动、登录或播放时遇到问题，再继续阅读后文对应章节。

如果你使用的是发布页面提供的打包版本，启动前只需要确认：

• 有一个可访问的 alist-tvbox 后端
• 当前网络环境能访问你要使用的内容来源
• 如果要直接播放 YouTube 等页面链接，系统里已经单独安装可用的 yt-dlp

yt-dlp 不随 atv-player 一起打包。常见安装方式：

• macOS：brew install yt-dlp
• Windows：winget install yt-dlp.yt-dlp
• Linux / 通用 Python 环境：pipx install yt-dlp
• 如果你已经有 Python 环境，也可以使用：python -m pip install -U yt-dlp

安装后建议先在终端确认：

yt-dlp --version

如果这条命令不能执行，应用通常也无法直接播放 YouTube 页面链接。

如果你是开发者，或希望从源码运行 / 自行打包，再按下面准备：

• 安装 Python 3.12+
• 安装 uv
• 系统中存在可用的 libmpv

Linux 上推荐先验证以下两步：

uv sync --group dev
./start.sh

start.sh 实际执行：

uv run atv-player

如果启动时报错找不到 libmpv，优先先解决系统运行库问题，再继续排查应用本身。

如果你在 Linux 上能启动应用，但播放 YouTube 时明显比 Windows 更容易反复缓冲、缓存一直很浅，除了检查网络环境，也要检查系统里的 mpv/libmpv 版本是否过旧。

以 Linux Mint 22.x / Ubuntu 24.04 为例，系统仓库中的 libmpv 往往仍然偏旧。如果你需要排查这类问题，建议先确认：

hash -r
/usr/local/bin/mpv --version
ldconfig -p | grep libmpv
yt-dlp --version

如果 mpv/libmpv 版本明显落后，而你又主要依赖 YouTube 等页面解析播放，通常比继续调应用内缓存参数更值得优先处理运行时版本问题。

如果你是用仓库内的 scripts/build_mpv.sh 自行编译新版 mpv/libmpv，还要注意 Lua 脚本运行时不能缺失。对 YouTube 页面 URL 来说，mpv 通常还需要 ytdl_hook 这类内置脚本能力；如果构建摘要里出现 lua : NO，就很可能出现“视频信息显示失败”或“无法识别媒体格式 (-17)”。

新版脚本在 apt-get 可用时会自动尝试安装这个包：

sudo apt install liblua5.2-dev

如果当前桌面会话是 X11，脚本还会检查 xpresent 开发包；缺失时会自动尝试安装：

sudo apt install libxpresent-dev

启动应用后会先进入登录页：

• 后端地址默认值是 http://127.0.0.1:4567
• 应用会自动回填上次使用的后端地址和用户名
• 登录成功后会自动获取并缓存 vod token
• 应用不会保存密码

首次使用建议按下面顺序操作：

1. 确认 alist-tvbox 后端已经启动并可访问。
2. 输入后端地址、用户名和密码。
3. 登录成功后进入主窗口。
4. 如果之前登录状态已经过期，应用会自动回到登录页要求重新登录。

主窗口顶部主要有以下入口：

• 全局搜索框
• 插件管理
• 直播源管理
• 高级设置（外观主题、播放设置、元数据增强、网络代理等）
• 退出登录

主内容区是标签页导航。标签页不是固定死的，而是由后端能力和当前启用插件共同决定。

系统会按能力显示这些页面：

• 豆瓣电影
• 电报影视
• B站
• 网络直播
• Emby
• Jellyfin
• 飞牛影视
• 盘搜
• 文件浏览
• 播放记录
• 每个启用的 TvBox Python 插件标签页

如果插件标签过多，超出的插件会进入“更多”抽屉：

• “更多”按钮会显示隐藏插件数量
• 抽屉内支持搜索插件名
• 适合插件很多时快速定位某个来源

全局搜索会并发查询所有已启用、支持搜索的来源。

搜索时会发生这些行为：

• 状态栏显示“搜索中...”
• 每个来源的结果显示在独立标签页中
• 标签标题会追加结果数量，例如 豆瓣电影(23)
• 没有结果时显示“无搜索结果”

全局搜索还支持“直接打开”：

• 输入 magnet:? 或 ed2k://：进入离线下载打开流程
• 输入常见网盘分享链接：进入网盘详情/解析流程
• 输入 YouTube 页面链接：如果系统里有可用的 yt-dlp，应用会尝试直接拉起播放器
• 输入普通 HTTP/HTTPS 媒体或页面地址：走内置全局解析并直接拉起播放器

如果你输入的是普通 URL，但应用提示“当前未配置内置解析”，说明当前运行环境里没有可用的内置解析服务链路。

也就是说，YouTube 这类页面地址不需要你先手动转换成直链媒体文件；只要系统里能找到可用的 yt-dlp，应用会优先尝试走 yt-dlp 打开。

当你输入 YouTube、X/Twitter、Instagram、TikTok 这类页面链接时，应用可能会调用系统中单独安装的 yt-dlp 提取可播放地址、标题、封面、字幕和清晰度信息。

如果你主要关心 YouTube 播放，至少先确认下面几件事：

1. 终端里执行 yt-dlp --version 能成功返回版本号。
2. 当前网络环境能访问 YouTube。
3. 你输入的是有效的 YouTube 页面链接，例如 https://www.youtube.com/watch?v=...。
4. 某些视频如果受地区、年龄或登录状态限制，可在"高级设置" → "播放设置"中选择浏览器提取 Cookie。

请注意：yt-dlp 是外部工具，不随 atv-player 的发行包一起提供。安装了 yt-dlp 也不代表所有 YouTube 视频都一定能播放。站点限制、账号限制、地区限制和网络环境都会影响结果。

常见排查顺序：

• 如果应用提示 yt-dlp 未安装：先在终端执行 yt-dlp --version，确认命令本身是否存在。
• 如果终端里能运行 yt-dlp，但应用里仍提示未安装：确认启动应用和安装 yt-dlp 使用的是同一个系统环境或 PATH。
• 如果提示地区限制：优先检查网络环境。必要时在"高级设置" → "播放设置"中选择浏览器提取 Cookie。
• 如果能看到详情但无法起播：先确认视频链接本身有效，再检查网络环境和站点限制。
• 如果清晰度或字幕数量和网页看到的不一致：这通常取决于 yt-dlp 当次提取到的结果，并不一定表示应用异常。

主窗口按 F1 会打开帮助对话框，包含两部分内容：

系统信息区域：

• 显示关键组件的版本：atv-player、Python、PySide6、mpv、ffmpeg、yt-dlp、Platform
• "一键复制"：将系统信息复制到剪贴板，方便反馈问题时粘贴
• "导出诊断信息"：将诊断信息保存为文本文件

快捷键表格：

• 列出当前窗口所有可用快捷键
• 再次按 F1 不会重复打开多个窗口，而是激活已有窗口
• 打开播放器、插件管理、直播源管理等操作时，会关闭当前帮助对话框

播放器窗口按 F1 只显示快捷键表格（不含系统信息）。

这些页面的交互方式基本一致：

• 中间区域是海报卡片网格
• 左侧通常是分类列表
• 顶部或侧边会有筛选条件
• 底部或列表区域带分页

适合的操作方式：

1. 先在左侧选择分类。
2. 需要时按年份、地区、类型等进一步筛选。
3. 点击海报进入详情页。
4. 在详情页选择剧集、线路或播放项进入播放器。

B站页支持更明显的层级导航：

• 可浏览番剧、电影、电视剧等分类
• 支持文件夹式层级导航和面包屑返回
• 详情区域会显示投币、点赞、收藏、回复、弹幕等统计
• 播放时支持 DASH 清晰度选择和外挂字幕
• 会结合本地记录恢复播放位置

Emby 和 Jellyfin 页更接近媒体库浏览体验：

• 可浏览电影、剧集、收藏等媒体库
• 支持文件夹层级导航
• 播放进度会向服务器回报
• 同时保留本地播放恢复

盘搜页用于跨网盘检索资源：

• 输入关键词后可搜索多个网盘来源
• 搜索结果可直接继续打开浏览或进入播放流程

文件浏览页偏向网盘目录操作：

• 支持面包屑导航
• 支持按列排序
• 支持分页，页大小可选 20 / 30 / 50 / 100
• 支持按网盘类型筛选，例如百度、夸克、阿里、PikPak 等
• 会记住每个路径的分页状态

常见使用方式：

1. 从首页一路进入某个目录。
2. 用内联搜索面板缩小结果范围。
3. 双击文件或目录继续浏览/播放。

播放记录页是一个可分页表格，支持：

• 双击恢复播放
• 删除选中记录
• 清空当前页记录
• 刷新当前页

“来源”列会显示记录来自哪里，例如：

• 插件
• Emby
• B站
• Jellyfin
• 飞牛影视
• 全局解析
• 远程

播放器使用独立窗口，适合把播放逻辑和主窗口浏览逻辑分开处理。

常用控制包括：

• 播放/暂停
• 进度条拖动
• 15 秒和 60 秒快进快退
• 上一集 / 下一集
• 音量与静音
• 倍速切换
• 重新播放

播放器还会保存这些状态：

• 当前音量
• 是否静音
• 宽屏模式开关
• 日志面板显示状态

• Enter：切换全屏
• W：切换宽屏模式，隐藏侧边栏以扩大视频区域
• Ctrl+P：返回主窗口
• Esc：如果当前全屏，先退出全屏；否则返回主窗口

播放器可以处理多层来源：

• 来源分组：适合“国语 / 粤语”“正片 / 花絮”这类分组
• 线路：适合同一内容的多条播放线路
• 剧集列表：适合同一线路下的具体集数

常见表现：

• 右侧或侧边面板显示当前来源的播放列表
• 双击列表项切换集数
• 有多组来源时可先切换来源分组，再切换线路
• 播放结束后可自动播放下一集
• 播放失败时可自动切换到下一条线路（可在"高级设置"中启用/禁用）

详情面板会显示：

• 海报
• 影片详情字段（元数据增强后会包含简介、评分、演员、导演等信息）
• 可点击的元数据 ID 链接（IMDb、TMDB、豆瓣、Bangumi 等，点击可跳转对应页面）
• 插件自定义动作按钮
• 可点击的详情字段值
• 播放日志

播放日志适合用来观察这些问题：

• 线路切换后是否成功拉流
• 解析是否成功
• 弹幕或字幕是否加载成功
• 某些播放失败时的错误提示

有些播放项不是最终媒体地址，而是待解析地址。此时播放器会启用“解析”下拉框。

支持的内置解析器包括：

• 虾米
• fish
• jx1
• jx2
• mg1
• tx1

使用规则：

• 只有当前播放项需要解析时，这个下拉框才会启用
• 你切换偏好解析器后，应用会保存这个选择
• 如果当前集正在播放且仍属于“待解析”项，切换解析器会自动重放当前项

播放器支持主字幕和次字幕两套选择：

• 主字幕：自动选择 / 关闭 / 手动选择轨道 / 外挂字幕
• 次字幕：关闭 / 手动选择轨道 / 外挂字幕

还支持这些能力：

• 外挂 ASS / SRT 自动加载
• ASS 覆盖模式
• 右键菜单调整主字幕和次字幕的位置、大小
• 位置支持预设和 5% 微调
• 大小支持预设和 5% 微调

音轨：

• 支持自动选择和手动切换
• 会显示编码、声道数、采样率等信息

清晰度：

• 对 DASH 内容启用清晰度切换
• 显示分辨率、编码、码率等信息

播放器内置完整弹幕工作流，支持的提供方：

• 腾讯
• 优酷
• B站
• 爱奇艺
• 芒果

自动搜索时会做这些处理：

• 标题模糊匹配
• 集数识别
• 时长过滤
• 电影版本变体识别
• 过滤预告、花絮、特辑等补充内容
• 根据来源 URL 优先选择合适提供方
• 多提供方并发搜索

按 D 打开“弹幕源”对话框，可以：

• 修改媒体标题
• 修改集数
• 指定搜索来源
• 重新搜索
• 恢复默认搜索词
• 从候选结果中切换并加载

如果自动搜索结果不理想，优先先在这里手动改标题和集数。

按 Ctrl+D 打开“弹幕设置”对话框，可以调整：

• 显示行数
• 显示模式：静态 / 仅滚动 / 混合
• 位置预设
• 颜色模式：统一颜色 / 保留原色
• 统一颜色
• 文字大小
• 滚动速率

还可以一键恢复默认值。

应用会缓存以下内容以减少重复请求：

• 搜索缓存，默认 7 天
• XML 原始缓存
• 按渲染参数区分的 ASS 缓存

播放器内置媒体元数据刮削功能，可以从多个来源获取并补充影片的元数据信息。

按 S 打开"刮削"对话框，可以：

• 修改搜索标题
• 修改年份
• 选择搜索来源（支持按来源筛选或搜索全部）
• 重新搜索
• 恢复默认搜索词
• 从候选结果中选择并应用

应用结果后，播放器会更新海报、元数据字段、详情字段和剧集标题。

刮削服务会并发搜索以下来源：

• 豆瓣
• TMDB
• Bangumi
• B站
• 腾讯
• 爱奇艺
• 插件提供的自定义来源

结果按来源分组显示。左侧显示各来源及其结果数量，右侧显示当前选中来源的候选结果列表。

当你手动选择并应用一条刮削结果后，应用会记住这个绑定关系：

• 下次播放同一内容时，会优先使用你手动绑定的来源
• 绑定信息会保存到本地数据库

如果自动匹配结果不理想，可以在刮削对话框中点击"重置"清除缓存和手动绑定，重新开始自动搜索。

除了手动刮削，应用还支持自动元数据增强。在主窗口"高级设置"中可以配置：

• 启用/禁用元数据增强
• 启用/禁用剧集标题增强
• 填写 TMDB API Key（用于 TMDB 来源）
• 填写 Bangumi Access Token（可选；留空时使用匿名访问）
• 填写豆瓣 Cookie（用于豆瓣来源）

启用后，打开播放器时会在后台自动搜索并补充元数据。

播放器会尽量恢复上次观看位置：

• 根据 URL 或集数索引匹配回正确位置
• 定时向后端上报进度
• 记录本地播放历史
• 启动应用时会尝试恢复上次播放会话

应用内置本地 HLS 代理（默认监听 127.0.0.1:2323），用于：

• M3U8 重写
• 广告片段过滤
• TS 分片缓存
• DASH 处理

这个代理在后台自动运行，通常不需要手动配置。

播放器支持远程蓝光 ISO 文件的流式播放：

• 通过 HTTP range 请求读取远程 ISO
• UDF 文件系统解析
• BDMV 播放列表和片段信息检测
• 自动选择最佳流

当你通过文件浏览或全局搜索打开一个 .iso 文件时，播放器会自动检测并进入蓝光播放模式。

播放器支持卡拉 OK 逐字歌词渲染：

• 支持 QQ 音乐 QRC、酷狗 KRC、网易 YRC 格式
• 逐字时间同步
• 翻译歌词支持
• ASS 渲染输出
• 插件可提供卡拉 OK 歌词数据

直播功能除了后端提供的直播分类，也支持本地自维护直播源。

在主窗口点击“直播源管理”可打开管理对话框。这里可以：

• 添加远程源
• 添加本地源
• 添加手动源
• 重命名
• 删除
• 启用/禁用
• 刷新
• 管理手动源频道

表格会显示：

• 名称
• 类型
• 地址
• 启用状态
• 刷新状态
• 最近刷新时间

• 输入一个远程 M3U 地址
• 应用会用 URL 路径自动推断默认名称
• 添加后建议立刻刷新一次，确认源内容可读

• 选择本地 *.m3u、*.m3u8 或 *.txt 文件
• 默认名称取文件名

• 先创建一个手动源名称
• 再进入“管理频道”逐条维护频道

手动源支持维护以下字段：

• 分组
• 频道名
• 地址
• Logo URL

管理频道时可以：

• 添加频道
• 编辑频道
• 删除频道
• 上移 / 下移调整顺序

如果多个频道名称相同且处于同一分组，应用会把它们合并成一个频道，并把不同地址组织成多线路播放列表。

#EXTM3U
#EXTINF:-1 tvg-logo="https://img.example/cctv1.png" group-title="央视频道" http-user-agent="AptvPlayer-UA" http-header="Referer=https://site.example/&Origin=https://origin.example",CCTV-1综合
https://live.example/cctv1.m3u8

支持读取的常见属性：

• group-title
• tvg-logo
• http-user-agent
• http-header

其中 http-header 使用 & 连接多个请求头，例如：

http-header="Referer=https://site.example/&Origin=https://origin.example"

央视频道,#genre#
CCTV-1综合,https://live.example/cctv1.m3u8
CCTV-2财经,https://live.example/cctv2.m3u8

#genre# 用来声明后续频道所属分组。

直播源管理窗口上方支持配置 EPG URL：

• 一行一个 URL
• 可以填写多个备用地址
• 支持点击“保存”
• 支持点击“立即更新”

如果当前频道能匹配到节目单，播放器详情区会显示：

• 当前节目
• 后续节目安排

点击主窗口”插件管理”可进入插件管理对话框。

插件管理支持：

• 添加本地插件
• 添加远程插件
• 批量导入
• 编辑名称
• 编辑配置
• 分类管理
• 启用/禁用
• 上移 / 下移
• 调整顺序
• 刷新
• 查看日志
• 删除

表格中可查看：

• 名称
• 来源类型
• 版本
• 地址
• 启用状态
• 当前状态或最近错误
• 最近加载时间

管理窗口还支持这些辅助能力：

• 搜索名称或地址
• 按启用状态筛选（全部 / 仅启用 / 仅禁用）
• 按当前顺序、名称、最近加载排序
• 选中单个插件时显示插件自定义动作区

“批量导入”支持两种入口：

• 输入 GitHub 仓库 URL
• 输入 spiders_v2.json 清单 URL
• 应用会显示进度对话框
• 完成后会展示新增 / 更新 / 跳过数量

• “编辑配置”适合给插件填写自定义文本配置
• “分类管理”适合调整单个插件内部分类的顺序、显示名称和隐藏状态
• “查看日志”适合检查插件加载失败、运行错误或兼容性问题

插件顺序会影响：

• 标签页显示顺序
• 全局搜索结果标签顺序
• 某些用户对来源的使用习惯

如果需要一次性重排多个插件，优先使用“调整顺序”：

• 支持置顶
• 支持上移/下移
• 支持置底
• 支持拖拽移动

远程插件会在本地执行 Python 代码，所以必须遵守这一条：

• 只加载受信任来源

如果你不确定插件来源是否安全，不要启用它。

点击主窗口"高级设置"可打开设置对话框，包含五个标签页。

• 界面主题：选择浅色、深色或跟随系统
• 跟随系统模式会在应用启动时读取当前系统浅深色设置
• 播放器播放区始终保持偏暗，不受主题影响

• 播放失败自动切换线路：播放失败时自动尝试下一条线路
• YouTube Cookie：选择从哪个浏览器提取 Cookie（不使用 / Chrome / Edge / Firefox），用于受限制的 YouTube 视频
• 播放缓存大小：16 - 4096 MB
• 解码模式：硬件解码（默认）或软件解码
• 网络超时：1 - 300 秒
• 普通流预读时长：1 - 600 秒（只影响普通流；ISO / YouTube / DASH 仍保留内置专用参数）
• 更多 MPV 配置：一行一个 key=value，例如 cache-pause-wait=8。这些选项会在最后应用，可覆盖同名内置参数

普通用户建议：

• 播放缓存大小：默认 512 MB，通常保持默认即可
• 解码模式：优先使用硬件解码
• 网络超时：一般保持默认或按网络情况小幅调整
• 普通流预读时长：默认 20 秒，通常保持默认即可
• 只有在播放卡顿、超时或兼容性异常时，再逐项调整

• 启用元数据增强：打开播放器时自动搜索并补充元数据
• 启用剧集标题增强：从 TMDB 等来源获取更准确的剧集标题
• TMDB API Key：用于 TMDB 元数据来源
• Bangumi Access Token：可选；留空时使用匿名访问
• 豆瓣 Cookie：用于豆瓣官方抓取；留空时跳过豆瓣官方来源

• 代理模式：直连（默认）、系统代理、HTTP、HTTPS、SOCKS5
• 代理地址：例如 socks5://user:pass@127.0.0.1:1080
• 直连规则：一行一条，匹配的域名不走代理。支持主机名和 CIDR，例如 localhost 或 10.0.0.0/8
• 代理规则：留空则代理所有域名；填写后仅匹配域名走代理，例如 .google.com
• 覆盖范围：API 请求、元数据、解析源、弹幕、海报、插件下载、HLS 上游请求、yt-dlp

• 启用日志记录：关闭后不再写入新日志，但仍可查看历史日志
• 支持按来源、级别、分类和关键字筛选
• 支持导出当前筛选结果
• 支持清空活动日志和归档日志

应用支持的内容来源和协议大致可以分为以下几类：

• YouTube
• B站
• 腾讯视频
• 爱奇艺
• 优酷
• 芒果 TV

• Emby
• Jellyfin
• 飞牛影视

• 百度网盘（免费）
• 天翼网盘（免费）
• 迅雷网盘（免费）
• 夸克网盘
• UC网盘
• 阿里云盘
• 常见网盘分享链接

• 普通 HTTP/HTTPS 媒体地址
• M3U8
• 远程蓝光 ISO

• HLS
• DASH
• magnet:?
• ed2k://
• 外挂字幕
• QRC / KRC / YRC

实际可用性取决于当前后端能力、插件、网络环境和第三方站点状态。

• mpv 播放
• 主字幕 / 次字幕
• 弹幕搜索、切换、渲染和缓存
• 元数据刮削与展示
• 本地 HLS 代理
• 远程蓝光 ISO 流式读取
• 播放设置、日志、海报与本地缓存管理

• 登录
• 文件浏览
• 播放记录
• 网盘解析
• 离线下载
• 由后端能力驱动的标签页和媒体浏览

• yt-dlp
• 代理网络
• 浏览器 Cookie
• TMDB / Bangumi / 豆瓣等第三方服务配置
• 远程插件及其自身可用性

• mpv 硬件解码：优先使用系统可用的硬件解码能力，降低 CPU 压力。
• DASH 多清晰度切换：对支持的内容显示可选清晰度和相关编码信息。
• 多线路与自动切线：同一内容支持多条线路，必要时可手动切换或自动切换。
• 本地 HLS 代理与分片缓存：重写 M3U8、过滤广告片段并缓存分片，减少重复请求。
• 远程蓝光 ISO 流式读取：通过 HTTP range 请求直接读取远程蓝光镜像内容。
• ASS 弹幕渲染：把弹幕转换为可控样式的 ASS 覆盖层。
• 主字幕 / 次字幕双轨：支持同时管理主字幕和次字幕。
• yt-dlp 页面提取：可直接从受支持站点页面链接提取播放地址和元数据。
• 卡拉 OK 歌词渲染：支持 QRC、KRC、YRC 逐字歌词显示。
• 播放恢复：尽量恢复上次观看位置和相关播放状态。

应用会把状态写到 Qt 标准数据目录和缓存目录。Linux 上通常是：

~/.local/share/atv-player
~/.cache/atv-player

不同平台的实际路径可能不同，但应用使用的是 Qt 标准目录。

常见内容包括：

• app.db：主配置数据库
• logs/application.jsonl：当前应用日志
• logs/application.*.jsonl.gz：按大小轮转后的归档日志
• plugins/：插件缓存
• posters/：海报缓存
• subtitles/：弹幕缓存
• playlists/：M3U8缓存
• danmaku-search-cache.json：弹幕搜索缓存
• danmaku-series-preferences.json：弹幕来源偏好
• metadata/：元数据搜索和详情缓存
• app.db 内的 metadata_bindings 表：元数据手动绑定记录

应用会保存这些使用状态：

• 登录令牌和 vod token
• 上次标签页和窗口位置
• 浏览路径和分页状态
• 播放恢复信息
• 宽屏模式、日志面板可见性
• 弹幕和解析器偏好
• 直播源、EPG、插件配置
• 主题模式偏好（浅色/深色/跟随系统）
• 网络代理配置（模式、地址、规则）
• 播放设置（自动切源、YouTube Cookie 浏览器、MPV 缓存、解码模式、超时、预读、额外选项）
• 元数据增强设置（启用状态、TMDB API Key、Bangumi Token、豆瓣 Cookie、剧集标题增强）
• 元数据手动绑定记录

应用会缓存以下内容，以减少重复请求并提升加载速度：

• 海报
• 插件缓存
• 弹幕搜索结果
• 弹幕 XML / ASS
• 元数据结果
• HLS / TS 分片

这些缓存的作用主要是减少重复请求、加快再次打开时的加载速度，而不是要求你手动维护。

如果你希望恢复初始状态，可删除以下目录：

~/.local/share/atv-player
~/.cache/atv-player

如果你希望尽量保留登录状态、插件、直播源、播放历史、元数据绑定和偏好设置，可复制以下目录到新环境：

~/.local/share/atv-player
~/.cache/atv-player

应用不会保存密码。

优先检查：

• 如果你使用的是发布版：应用是否完整解压，系统运行库是否齐全
• 如果你是从源码运行：Python 版本是否满足 3.12+，是否已经执行 uv sync --group dev
• 如果提示 libmpv 相关错误：优先先解决系统运行库问题

如果应用本体能启动，但登录后无法继续，再检查 alist-tvbox 后端是否可访问。

常见原因：

• 保存的登录状态已经过期
• 后端地址可访问，但当前令牌无效
• 后端暂时返回错误

处理方式通常是重新登录一次。

先区分三类情况：

• 输入的是普通 URL：检查是否提示“当前未配置内置解析”
• 输入的是网盘分享链接：检查当前环境是否已配置网盘解析链路
• 输入的是磁力/电驴链接：检查后端离线下载能力是否可用

建议按这个顺序排查：

1. 查看播放器右侧“播放日志”。
2. 如果当前内容支持多线路，先切换线路。
3. 如果当前项需要解析，切换“解析”下拉框。
4. 确认原始来源本身没有失效。

先尝试：

1. 按 D 打开弹幕源。
2. 手动修改标题或集数。
3. 指定单个弹幕提供方重搜。
4. 重新选择候选结果并加载。

优先检查：

• 直播源是否已启用
• 远程源是否已经成功刷新
• 本地文件路径是否仍然存在
• M3U 或 TXT 格式是否符合示例

优先检查：

• 是否已填写至少一个有效 EPG URL
• 是否点击过“立即更新”
• 当前频道名称是否能和节目单中的频道名匹配

建议操作顺序：

1. 打开“插件管理”。
2. 查看该插件的状态列。
3. 打开“查看日志”。
4. 必要时执行“刷新”或临时禁用插件。

如果是远程插件，先确认插件源码本身可被信任，再继续排查兼容性问题。

建议操作顺序：

1. 按 S 打开刮削对话框。
2. 手动修改搜索标题，去掉多余的修饰词或符号。
3. 补充或修正年份。
4. 指定单个来源重新搜索，避免多来源混淆。
5. 如果之前手动绑定过错误结果，点击"重置"清除缓存和绑定后重试。

如果某个来源始终搜不到结果，可能是对应的 API 配置不完整。在主窗口"高级设置"中检查：

• TMDB 来源需要填写有效的 TMDB API Key
• 豆瓣来源需要填写豆瓣 Cookie

如果部分内容加载失败或超时：

1. 检查"高级设置" → "网络代理"中的代理配置是否正确。
2. 如果使用代理规则（仅匹配域名走代理），确认目标域名包含在规则中。
3. 如果使用直连规则，确认目标域名未被误设为直连。
4. 对于 YouTube 等需要特定网络环境的站点，优先确认代理模式和网络可达性。

如果 YouTube 视频提示需要登录或受地区限制：

1. 在"高级设置" → "播放设置"中选择浏览器提取 Cookie。
2. 确保所选浏览器已登录 YouTube 账号。
3. 如果仍有问题，尝试更换浏览器选项。

如果同一个 YouTube 视频在 Windows 上播放流畅，但在 Linux 上缓存始终只有几 MB 到十几 MB、经常反复缓冲，建议按下面顺序排查：

1. 先确认终端中的 yt-dlp --version 能正常返回版本号。
2. 再确认 mpv --version 和系统实际加载到的 libmpv 版本。
3. 如果你使用的是 Linux Mint / Ubuntu 一类发行版，优先怀疑系统仓库中的 mpv/libmpv 版本偏旧。
4. 不要先假设是应用里的“播放缓存大小”配置失效。这个值通常只是上限，实际缓存深度还会受站点吞吐、运行时版本和播放器内部缓冲策略影响。

常用检查命令：

hash -r
/usr/local/bin/mpv --version
ldconfig -p | grep libmpv
yt-dlp --version

如果确认 mpv/libmpv 明显偏旧，而你又主要使用 YouTube 页面链接播放，建议优先升级系统的 mpv/libmpv 运行时，再重新测试。

对 Linux Mint / Ubuntu 用户，更实用的做法通常是：

• 不要只依赖系统仓库里的旧版 libmpv
• 优先考虑更新的第三方包源，或自行构建较新的 mpv/libmpv
• 升级完成后，再回到应用里观察系统信息和播放日志中的 mpv / ffmpeg 版本是否已经变化