FreeBox

吾生也有涯，而知也无涯。——庄子

FreeBox：把 TVBox 的味儿，搬到桌面端

超级随意版介绍来啦（撒花✿）。FreeBox 是一个用 JavaFX 写的桌面影视播放软件，作者给它的定位是“TVBox 电脑版/姊妹软件，致力于 TVBox 功能和生态的跨平台扩展”。
它既延续了 TVBox 的使用习惯，又把“资源审计”等 PC 侧才方便做的事情加了进来；同时，强烈强调“空壳播放器”属性：不内置任何媒体资源，用户自己配置第三方来源，自己负责合法合规。

• 仓库主页：kknifer7/FreeBox
• README 永久链接（信息来源）：README.md@cbc6058
• 默认分支：main
• 许可协议：GPL-3.0（另附详细补充条款，见 README“许可协议”章节）
• 技术栈：Java + JavaFX（JDK 17+，JavaFX 21.0.9）
• 关键词：catvod、tvbox、javafx

LOGO（来自作者说明的素材来源）：

---

这玩意儿有啥特点？

作者用四个词总结得很到位：小巧、易用、更新方便、跨平台。

• 小巧：安装包大约 50M。作者的原则是“非必要不引入”，严格控制体积；
• 易用：延续经典 TVBox 风味，配置项直观、逻辑对味；
• 更新方便：持续维护发版，安装版支持“自更新”（免手动折腾）；
• 跨平台：主流三端（Windows/macOS/Linux）与双架构（amd64/arm64）都照顾，Linux 还提供 AppImage。

再加上“资源审计”，它就不只是“桌面播放”，还是一个“帮源作者与 Spider 开发者做质量把关”的工具。对于纯用户来说，审计能帮你直观看出“哪些站点可用、哪些不可用”。

另外非常重要的定位：FreeBox 是“空壳播放器”。它本身不提供任何资源、也不会推荐任何资源；播放的一切都来自用户自行配置的第三方来源。合法合规是第一要义，详见 README 的许可与免责声明条款。

---

快速开始（强烈推荐先看视频）

• B 站介绍视频：BV1AXgmzUENg
• 下载安装（推荐安装版，而不是 zip/tar.gz）：Releases
• 安装指南（先读一遍更稳）：Wiki：软件安装、升级

下载表里已经给了不同系统的包（MSI/DMG/DEB/RPM/AppImage 等），很省心。启动之后，FreeBox 会自动检测你是否安装了“受支持的播放器”（比如 VLC、MPV 等），详见 Wiki 的“播放器选择和支持”。

---

播放源怎么整？

FreeBox 目前支持两类来源：导入源、TVBox 源。

A. 导入源（直接导第三方接口）

• 直接把接口链接配置到软件里（只支持 Java 格式的 Spider，type=3；其他类型会按需逐步考虑支持）
• 导入之后会长期保留，不需要重复导入
• README 提供了一个演示用的公共源（致谢原作者）：
  Greatwallcorner/CatVodSpider → 配置地址
  https://ghproxy.net/https://raw.githubusercontent.com/Greatwallcorner/CatVodSpider/master/json/config.json

导入源操作演示（GIF）：

B. TVBox 源（和移动端“影视-K”配对打通）

这个方案的目标很清晰：让 PC 端也能播放“安卓端接口”而不用装手机模拟器。
使用方法（摘自 README）：

1. 在“影视-K”App 右下角进入设置，点击“FreeBox 配对”
   

2. 在弹出的对话框里，输入 FreeBox 主界面显示的“本机 IP”和“WebSocket 服务端口”（颜色框对应要一一匹配）
   

3. 点击“连接/重连”，连接成功后两边都会有提示

作者也在考虑更优的安卓源兼容方案，欢迎去参与讨论：
更好的安卓源兼容方案 · Issue #100

---

资源审计：给源作者与 Spider 开发者的“看家工具”

谁需要这个功能？

• 源接口维护者：看看站点功能是否都正常、请求/响应数据是否符合预期；
• Spider 开发者：审查站点可用性，排查问题；
• 好奇的进阶用户：想知道某源里哪些站点好用、哪些坑多。

怎么用？

1. 首页源列表中选中要审计的源
2. 点击“播放源审计”，进入审计窗口
3. 左侧列出源内所有站点，支持“批量审计”“单独审计”两种模式

审计界面（示意）：

审计结果可以帮助你快速识别“不可用站点”，并给出问题信息（请求与响应数据），极大地提升维护效率。

---

点播体验 & 设置

• 点播逻辑基本等同 TVBox：选源→进入→按分类/搜索→播放（对用户很友好）
• 对 TVBox 源：播放记录、进度、收藏等数据与手机端互通
• 对导入源：上述数据独立保存，可在设置中清理

点播界面（示意）：

设置入口很直观（网络设置一般无需更改，知道自己在做什么就随意；其他常规项可以慢慢探索）：

---

功能亮点与开发计划（摘自 README）

已完成的亮点：

• m3u8 广告过滤（原创算法，准确度高）
• 直播源支持
• 字幕支持（在线搜索，格式多样）
• 弹幕支持（导入 ASS 格式弹幕）
• 外部播放器支持（VLC、MPV）
• 字体一键切换
• 更好的打包分发（三端双架构）

计划中的/进行中：

• 影片离线缓存
• JS 源支持
• 播放器“空降”（跳过片头片尾）
• 在线放映室（连上后端服务，房间/分享/同步播放）
• 更丰富的源作者与 Spider 开发者支持（优先完善“源审计”的“自定义审计”）
• 界面样式优化（欢迎 CSS 能力者帮忙）

完整表格在 README“功能列表 & 开发计划🎯”章节，随版本推进会更新。

---

安全与合规（必读！）

FreeBox 的许可与免责声明非常详细，核心意思就是：
它是一个“技术性播放器外壳”，本身不提供任何资源；你播放的内容全部来自你自行配置的第三方来源。
你需要保证自己访问/播放/分享的内容合法合规，尊重知识产权，不要侵犯他人权益。
开发者不认可也不支持任何试图规避技术保护（DRM 等）的行为。
这类风险与责任全部由用户承担。请务必遵守所在地法律法规！

建议使用前认真阅读 README“许可协议”章节（超长条款，写得很完整）。

---

上点代码（演示用，非仓库源码）

以下示例只是“给你点灵感”，帮助你理解 FreeBox 背后的“桌面端 + 外部播放器 + 源配置”思路。
不要把它当作官方 API 哦（请以 README 和 Wiki 为准）。

1) 调用外部播放器（MPV/VLC）播放一个地址

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class LaunchPlayerDemo {
    public static void main(String[] args) throws IOException {
        // 假设拿到一个可播放的媒体地址（来自你导入/配对的源）
        String mediaUrl = "https://example.com/path/to/video.m3u8";

        // 选择 MPV 或 VLC
        boolean useMpv = true;
        List<String> cmd = new ArrayList<>();

        if (useMpv) {
            cmd.add("mpv");
            cmd.add("--no-terminal");
            cmd.add("--force-window=immediate");
            // 可选：加载字幕/弹幕等参数
            // cmd.add("--sub-file=/path/to/subtitle.srt");
        } else {
            cmd.add("vlc");
            cmd.add("--play-and-exit");
            // 可选：添加弹幕/日志等参数
        }

        cmd.add(mediaUrl);

        // 启动外部播放器
        new ProcessBuilder(cmd)
                .inheritIO()   // 把播放器日志打印到当前控制台
                .start();
    }
}

设计要点：

• FreeBox 就是这么做“外部播放器支持”的（从 README 可知支持 MPV/VLC）；
• 你可以在参数层面拓展字幕、弹幕、硬解等能力；
• 实操中需考虑跨平台路径与播放器安装检测（FreeBox 会自动检测，参见 Wiki）。

2) 拉取并保存一个“导入源”配置（HTTP 客户端）

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

public class FetchSourceConfigDemo {
    public static void main(String[] args) throws IOException, InterruptedException {
        // README 演示用的公共源（致谢原作者）
        String url = "https://raw.githubusercontent.com/Greatwallcorner/CatVodSpider/master/json/config.json";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();

        HttpResponse<byte[]> resp = client.send(req, HttpResponse.BodyHandlers.ofByteArray());
        if (resp.statusCode() == 200) {
            Path out = Path.of("config.json");
            Files.write(out, resp.body());
            System.out.println("已保存到：" + out.toAbsolutePath());
        } else {
            System.err.println("拉取失败，HTTP " + resp.statusCode());
        }
    }
}

说明：

• 真正的“导入源”逻辑由 FreeBox 自己完成，这里只是演示“把一个远程 JSON 拉下来”的思路；
• 后续你可以把这个 JSON 喂进你的“源管理”界面，做持久化、校验与审计。

3) 一个极简 JavaFX 壳（感受一下桌面端风味）

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;

public class FxShellDemo extends Application {
    @Override
    public void start(Stage stage) {
        Button importBtn = new Button("导入源");
        Button auditBtn = new Button("源审计");
        Button playBtn = new Button("播放");

        importBtn.setOnAction(e -> System.out.println("打开导入源对话框（演示）"));
        auditBtn.setOnAction(e -> System.out.println("进入审计界面（演示）"));
        playBtn.setOnAction(e -> System.out.println("选择站点并播放（演示）"));

        VBox root = new VBox(10, importBtn, auditBtn, playBtn);
        stage.setScene(new Scene(root, 360, 180));
        stage.setTitle("FreeBox 风味壳（演示）");
        stage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

这段代码只是个“壳”，真实的 FreeBox 逻辑要复杂得多（源管理、配对、播放器集成、审计引擎、数据互通、设置项等等）。

---

面向开发者

• PC 端 Spider 的写作参考：kknifer7/CatVodSpider-PC
• 提建议/报 Bug：Issues
• 邮箱联系作者：knifer@duck.com
• 作者不维护线上群组（认真做事型），欢迎在仓库交流

---

最后的小结：This is the way

FreeBox 的核心价值很朴素：
把 TVBox 的使用体验搬到桌面端（同时做跨端数据互通），提供“资源审计”让源作者与 Spider 开发者能更快掌握站点质量状况，再用“外部播放器”把真实播放这件事做好做稳。
一切资源由用户自己配置与决定，合法合规是底线中的底线。

如果你在 PC 端也想有 TV 上那套“点播体验”，又或者你正在维护/开发自己的源与爬虫，FreeBox 值得你装起来试试；先看 B 站视频，再读一遍 README 的“安装指南”和“许可协议”，然后就开搞吧。

— 参考与原始信息：

• 仓库主页：kknifer7/FreeBox
• README（permalink）：README.md@cbc6058