订阅源格式与协议 — api.json 文件到底长什么样

订阅源的两种形态

NewBox 支持两种订阅源格式：影视源（api.json 后缀）和直播源（通常为 txt 后缀）。二者功能不同——影视源负责影视点播，直播源负责电视直播频道。实际使用中，多数玩家会同时添加一条影视源和一条直播源。

影视源的基本结构

影视源的典型形态是一个 JSON 格式文件，包含以下几个关键字段：

• 播放线路：定义视频点播接口的请求地址
• 解析脚本：部分源会附带一段 JavaScript 解析代码，用于处理特定格式的视频流
• 分类规则：定义首页展示哪些分类，以及分类的标签页结构
• 搜索接口：指定关键词搜索的请求地址和返回格式
• 筛选接口：按地区、年份、类型等维度筛选影片的结构化接口

用户不需要手动解析这些字段——NewBox 在添加订阅源时会自动读取 JSON 结构并完成适配。

直播源的基本结构

直播源格式相对简单，通常是 txt 文本文件，每行是一条频道记录，格式一般为频道名称加播放链接。部分影视源的 JSON 结构里会同时附带直播频道数据，此时添加一条影视源就能同时解锁直播频道。

订阅源的加载流程

当用户在 NewBox 中添加一条订阅源后，软件会按以下步骤工作：

1. 读取远程文件：向用户输入的订阅源地址发送 HTTP 请求，获取 JSON 或文本内容
2. 解析结构：识别是影视源还是直播源，提取关键字段
3. 注入首页：将影视源的分类标签页注入首页导航栏
4. 建立缓存：在本地缓存接口地址和解析脚本

这个过程通常在几秒内完成，完成后首页就从空盒状态变成了有完整分类导航的影视浏览界面。

订阅源的有效性

订阅源的有效性取决于远程维护者。一条源可能今天能用、明天就失效。NewBox 在播放时会对每条播放线路做可用性检测，当当前线路返回错误时自动切换到同一影片的备用线路——这是它比同类播放器更省心的一个设计点，具体见 多线路自动切换。

去哪里找订阅源

订阅源通常由社区玩家或维护者公开分享，常见分发渠道包括影视论坛、社交群组、个人博客等。添加前可以先在浏览器里访问一下订阅源地址，如果能直接打开返回 JSON 内容或文本列表，说明源本身存活。