📦 Castor 详细部署教程

Castor 是一款终端工具，它能将任意网页中的视频流提取出来，实时转码后投屏到你的智能电视上，并支持烧录字幕。它通过启动无头 Chrome 浏览器监听网络请求来获取视频流，解决了智能电视无法直接播放网页视频或屏幕镜像画质差、延迟高的问题。

重要提示：Castor 是一个通用投屏工具，不捆绑任何视频源或目录，它只投屏你指向的、你有权使用的内容。它不接触 DRM，无法投屏受 DRM 保护的服务。请确保你的使用行为合法合规。

⚙️ 部署前准备

1. 硬件与网络要求

一台与电视在同一局域网内的电脑 (Linux/macOS/Windows) 或 Linux 服务器。
一台支持 DLNA、Chromecast 或 Roku 协议的智能电视或播放设备。
网络互通：设备发现依赖 SSDP/mDNS 组播，这通常不会跨越 VLAN 或子网。如果 castor scan 发现不了设备，你可以通过 IP 地址手动指定。

2. 必须安装的依赖工具

Castor 需要调用三个外部工具，请确保它们已安装并添加到系统的 PATH 环境变量中。

工具	版本要求	用途
Chrome / Chromium	任意较新版本	无头模式提取视频流
ffmpeg	7.1 或更新版本	视频转码和流复制
ffprobe	7.1 或更新版本	探测源视频格式

特别提醒：Castor 使用了较新的 ffmpeg 参数（如 -readrate_initial_burst），旧版本会报错。请务必从 ffmpeg 官网下载 7.1+ 版本。

🚀 安装 Castor

方式一：使用 Homebrew 安装 (macOS 推荐)

1	brew install --cask stupside/tap/castor

方式二：从源码编译 (所有平台)

此方法需要安装 Go 1.26+ 和 cmake，因为 Castor 使用了 cgo 绑定的 whisper.cpp 进行字幕生成。

# 克隆仓库（必须包含子模块）
git clone --recurse-submodules https://github.com/stupside/castor.git
cd castor

# 编译（会自动构建 libwhisper.a 和 castor 二进制文件）
make

编译成功后，二进制文件位于当前目录，你可以将其移动到 PATH 目录下（如 /usr/local/bin）。

注意：不能使用 go install，因为 Castor 通过本地路径引用 vendored 的 whisper.cpp 绑定，必须先通过 make 构建静态库。

🔧 首次配置

1. 发现并指定你的电视

运行以下命令，扫描局域网内的投屏目标：

1	castor scan

从输出结果中找到你的电视名称（如 "Living Room TV"），然后在工作目录下创建 config.yaml 配置文件，写入：

1
2
3

device:
  name: "Living Room TV"  # 必须与 scan 结果完全一致
  type: dlna              # 可选 dlna, chromecast, roku

2. (可选) 配置 TMDB API 密钥以使用交互式浏览

如果你想使用 castor cast 命令在终端中交互式搜索并投屏电影/剧集，需要获取 TMDB API 密钥：

在 themoviedb.org 注册账号并申请 API 密钥（免费）。
为避免将密钥提交到 Git，创建一个 git-ignored 的 config.local.yaml 文件覆盖配置：
1
2
tmdb:
api_key: "你的TMDB_API_密钥"

注意：直接使用 castor cast movie <ID> 等命令不需要 TMDB 密钥。

3. (可选) 配置视频源

Castor 本身不捆绑任何影视源。要使用 castor cast movie 或 castor cast episode 命令，你需要在配置文件中添加自己的源（即你被授权使用的网站）。示例如下：

sources:
  - proxies: ["https://your-source.example.com"]   # 基础 URL
    templates:
      movie: "/embed/movie/{itemID}"                # {itemID} 会被替换为 IMDB/TMDB ID
      episode: "/embed/tv/{itemID}/{season}-{episode}"

📺 开始投屏

完成基本配置后，使用以下命令投屏：

投屏一个包含视频播放器的网页：

1	castor cast player https://example.com/watch/some-video

直接投屏一个视频流或文件 URL：

1	castor cast url https://example.com/path/to/video.m3u8

使用交互式浏览器（需 TMDB 密钥）：
1
castor cast
此命令会启动一个终端 UI，让你搜索并选择要投屏的影视内容。

🐳 Docker 部署 (可选)

Castor 官方提供了 Docker 镜像，适用于 Linux 主机（因为它需要 --network host 访问局域网）。

1. 扫描设备

1	docker run --rm --network host ghcr.io/stupside/castor:latest scan

2. 投屏

将你的 config.yaml 挂载到容器内，并传递 Intel GPU 以启用硬件加速（可选）：

docker run --rm --network host \
  -v "$PWD/config.yaml:/config.yaml" \
  -v castor-cache:/root/.cache \  # 持久化 whisper 模型
  ghcr.io/stupside/castor:latest \
  cast player https://example.com/watch/some-video

注意：在 Docker Desktop (macOS/Windows) 上，--network host 无效，请使用原生二进制。

❓ 常见问题与故障排查

castor scan 找不到电视：
- 最常见原因是网络隔离。组播无法跨 VLAN 或子网，且在 Android/Termux 上会被阻止。
- 解决方案：在 config.yaml 的 device 下直接指定电视的 IP 地址（host: 192.168.0.3），Castor 会改用单播通信，绕过发现流程。
1
2
3
4
device:
name: "Living Room TV"
type: dlna
host: 192.168.0.3 # 电视的局域网 IP
投屏时电视显示”空闲”图标但无画面 (Chromecast)：
- 这通常是因为某些源返回的 HLS 分段使用了伪装的文件扩展名（如 .jpg），Chromecast 无法识别。
- 解决方案：在配置中强制 Castor 代为转发流 (delivery: serve)：
1
2
cast:
delivery: serve # 总是由 Castor 中继流
- 此选项会消耗本机的带宽和 CPU 进行转码，建议按需使用。
ffmpeg 版本报错：
- 确保已安装 ffmpeg 7.1 或更高版本。运行 ffmpeg -version 检查。
- 如果系统版本较旧，可以从官网下载静态构建版本，并将其路径添加到 PATH 中。