SubRenamer 字幕批量匹配、改名与 FFsubsync 自动调轴 WebUI
1.3K
基于 SubRenamer 核心算法的 Docker + WebUI 改造版。
字幕批量匹配、改名与自动调轴工具。复用原项目 SubRenamer.Core 匹配算法(零修改),提供浏览器 Web 界面和 Docker 部署支持。
SubBackup 备份SubRenamer.Core diff 算法关联视频与字幕chs、cht、zh、ja、en 等语言标记linux/amd64 和 linux/arm64 镜像镜像地址:beiming712/subrenamerweb
Docker 会根据设备自动选择 AMD64 或 ARM64 版本:
docker run -d \
--name subrenamer \
-p 38080:8080 \
-v /path/to/media:/media \
--tmpfs /uploads:mode=1777 \
--tmpfs /work:mode=1777 \
--restart unless-stopped \
beiming712/subrenamerweb:latest
浏览器访问 http://宿主机IP:38080。
媒体目录需要可写权限,因为旧改名接口和显式
commit会写入视频所在目录。调轴执行阶段只写/workstaging。
修改 docker-compose.yml 中的媒体目录、UID 和 GID:
volumes:
- /path/to/media:/media
user: "1000:10"
使用已发布镜像启动:
docker compose pull
docker compose up -d
从源码重新构建:
docker compose up -d --build
默认访问地址为 http://localhost:38080。
no_sync 模式,在独立 staging 中执行并查看逐项结果调轴功能调用固定版本的 FFsubsync 分析视频音轨,并通过 FFmpeg 辅助处理:
/work/<taskId>/,包含 manifest.json、output/、logs/ 和 backup/video_global、实验性 video_split、subtitle_reference 和 no_synccommit 默认拒绝已存在目标;显式允许覆盖时,旧文件先备份到任务 backup/rollback 会校验当前目标哈希,只处理本任务提交且未被外部修改的文件commit / rollback 返回明确的幂等结果调轴依赖视频中存在可分析的音轨。处理大文件时需要一定 CPU、内存和临时存储空间,ARM 设备耗时通常更长。
任务成功后状态为 awaiting_commit,表示候选结果仍位于 staging。全部候选提交后状态为 completed;回滚后重新回到 awaiting_commit。PR 合并或镜像发布不代表 NAS 已部署。
docker-compose.yml 默认使用 1000:10 运行容器。请按宿主机媒体目录的所有者修改:
id
如果容器可以扫描但无法改名或调轴,通常是 /media 没有写权限。不要为了省事给媒体库设置 777,优先让容器 UID/GID 与目录所有者一致。
启动后访问 http://宿主机IP:38080/api/docs 查看 Swagger。
主要接口:
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/files/scan?dir= | 扫描媒体目录 |
| POST | /api/subtitles/upload | 批量上传字幕 |
| POST | /api/match | 匹配视频与字幕 |
| POST | /api/rename | 执行改名 |
| POST | /api/sync、/api/sync/tasks | 创建 staging 调轴任务,返回 taskId |
| GET | /api/sync/{taskId}/status、/api/sync/tasks/{taskId} | 查询总体状态、逐项指标和有限日志 |
| POST | /api/sync/{taskId}/cancel、/api/sync/tasks/{taskId}/cancel | 取消排队中或执行中的任务 |
| POST | /api/sync/{taskId}/commit、/api/sync/tasks/{taskId}/commit | 提交通过质量门禁的候选结果;默认不覆盖 |
| POST | /api/sync/{taskId}/rollback、/api/sync/tasks/{taskId}/rollback | 回滚本任务已提交且未被外部修改的文件 |
| POST | /api/sync/plans | 创建纯预览调轴计划,返回唯一目标名称与逐项校验结果 |
/api/sync/plans 不会写入媒体目录。它支持 subtitle_reference、video_global、video_split 和 no_sync 模式;未识别语言使用稳定的 und 后缀,同一视频的多个字幕会生成互不冲突的候选文件名。
基础功能需要 .NET 8 SDK:
dotnet restore SubRenamer.Web.sln
dotnet build SubRenamer.Web.sln -c Release --no-restore
dotnet test SubRenamer.Web.sln -c Release --no-build --filter "Category!=EndToEnd"
dotnet run --project src/SubRenamer.Web/SubRenamer.Web.csproj
开发工作请从独立分支发起,并通过 Pull Request 和 CI 合并。分支、提交、测试及发布门禁参见 参与开发 和 开发与交付流程。
如果需要在非 Docker 环境测试调轴,还需安装:
ffsubsync Python 包真实调轴端到端测试会调用锁定版本的 FFsubsync,并由 FFmpeg 动态生成测试视频,覆盖:
video_global:校正整体晚 2 秒的字幕,并验证 staging、commit 与 rollback;subtitle_reference:按参考字幕时间轴校正,同时确认输入字幕与参考字幕均未修改;video_split:把前后两组分别晚 2 秒和 4 秒的字幕校正到同一视频时间轴。python3 -m venv .venv-e2e
.venv-e2e/bin/python -m pip install "ffsubsync==0.5.1"
RUN_REAL_SYNC_E2E=1 \
PYTHON_EXECUTABLE="$PWD/.venv-e2e/bin/python" \
FFMPEG_EXECUTABLE=ffmpeg \
dotnet test tests/SubRenamer.Web.Tests/SubRenamer.Web.Tests.csproj \
-c Release \
--filter "Category=EndToEnd"
未设置 RUN_REAL_SYNC_E2E=1 时,普通单元测试不会要求开发机安装 FFmpeg 或 FFsubsync;GitHub Actions 会在独立的 Real FFmpeg + FFsubsync E2E 作业中强制执行该测试。
video_split 的 offsetSeconds 是 FFsubsync 对各字幕偏移量计算的中位数,仅用于汇总展示;分段模式不会对所有字幕应用同一个偏移,最终 staging 文件才是逐条校正结果的权威来源。
本地运行时可通过环境变量指定目录:
MEDIA_DIR=/path/to/media \
UPLOAD_DIR=/tmp/subrenamer-uploads \
WORK_DIR=/tmp/subrenamer-work \
dotnet run --project src/SubRenamer.Web/SubRenamer.Web.csproj
调轴运行参数:
| 环境变量 | 默认值 | 说明 |
|---|---|---|
WORK_DIR | /work | staging、manifest、日志和备份根目录 |
MAX_CONCURRENT_SYNCS | 1 | 同时执行的任务数 |
MAX_QUEUE_SIZE | 20 | 等待队列最多容纳的任务数 |
SYNC_TIMEOUT_SECONDS | 900 | 单个字幕的默认超时 |
TASK_RETENTION_HOURS | 24 | 已完成或遗留 staging 的保留时间 |
MAX_TASK_LOG_ENTRIES | 200 | 每个任务最多保留的内存日志条数 |
PYTHON_EXECUTABLE | python3 | Python 可执行文件 |
Docker 构建参数 FFSUBSYNC_VERSION 默认锁定为 0.5.1。
SubRenamer.Web/
├── .github/workflows/ # AMD64/ARM64 镜像发布流水线
├── docs/ # 开发、API 与迁移文档
├── CHANGELOG.md # 版本变更与已知限制
├── src/
│ ├── SubRenamer.Core/ # 原项目核心匹配算法(零修改)
│ └── SubRenamer.Web/ # ASP.NET Core Web API + 单页前端
│ ├── Controllers/ # 扫描、上传、匹配、改名、调轴接口
│ ├── Models/ # DTO 与任务状态模型
│ ├── Services/ # 文件、改名和调轴服务
│ ├── scripts/ # FFsubsync Python 包装程序
│ └── wwwroot/ # WebUI
├── tests/ # 单元、集成与端到端测试
├── SubRenamer.Web.sln # 本地开发与 CI 统一入口
├── Dockerfile
├── docker-compose.yml
└── README.md
推送到 main 分支后,GitHub Actions 自动构建多架构镜像并发布:
beiming712/subrenamerweb:latestbeiming712/subrenamerweb:main推送版本标签(例如 v1.1.0)时还会发布:
beiming712/subrenamerweb:1.1.0beiming712/subrenamerweb:1.1创建版本标签前应完成 v1.1.0 发布检查清单,并遵循 版本与标签规范。版本变化参见 更新日志。镜像发布不代表已经部署到 NAS。
本项目基于 GPL-2.0 授权的 SubRenamer.Core,整体遵循仓库中的 GPL-2.0 License。原项目地址:qwqcode/SubRenamer。
Content type
Image
Digest
sha256:ce7f6b3ee…
Size
285.1 MB
Last updated
3 months ago
docker pull beiming712/subrenamerweb