lastthree/doublestack-subtitle repository overview

⁠DoubleStack Subtitle（双栈工坊字幕）

一个基于 Docker 的媒体库字幕搜索与下载工具。支持递归扫描媒体文件、识别影片标题、关联本地封面，并通过多个字幕源聚合搜索结果。

⁠功能特性

• 🎬 媒体库扫描 - 递归扫描挂载目录中的常见视频文件，并按封面卡片展示媒体标题
• 🖼️ 本地封面识别 - 自动关联视频目录中的同名图片，以及 poster、folder、cover、movie 等常见封面文件
• 🔎 聚合字幕搜索 - 使用识别后的媒体标题或手动输入关键词，同时查询五个影视字幕源和一个成人字幕源
• ⬇️ 字幕下载 - 从搜索结果直接下载字幕，并保存到映射的字幕目录
• 🧩 字幕源控制 - 可在设置页面选择启用或关闭各个字幕源，状态保存到 SQLite
• 🧾 正则标题识别 - 支持添加多条媒体名称识别正则，并提供文件名测试功能
• 🗄️ SQLite 配置 - API 自动令牌、字幕源开关、标题正则和 FlareSolverr 地址统一持久化
• 🕘 下载历史 - 记录字幕来源、文件名、保存路径、下载时间以及成功或失败状态
• ⚡ 搜索缓存 - 按关键词和字幕源缓存结构化搜索结果，减少短时间内重复访问字幕站
• 📚 媒体增量索引 - 根据文件大小、修改时间、目录变化和正则签名，仅重新处理发生变化的媒体
• 📱 响应式界面 - 提供主页、媒体、字幕和设置页面，侧边栏支持展开与收起
• 🐳 Docker 运行 - 使用无需本地构建的 Compose 文件启动已发布镜像

⁠系统要求

• Docker 20.10+
• Docker Compose 2.0+
• Chrome、Firefox、Edge 等现代浏览器
• FlareSolverr
• OpenSubtitles API

⁠快速开始

⁠方式一：Compose 部署（推荐）

# 1. 克隆项目
git clone https://github.com/Double-Stack-Workshop/doublestack-sub.git
cd doublestack-sub

# 2. 创建默认映射目录
mkdir -p media subtitles

# 3. 启动服务
docker compose up -d

# 4. 查看运行状态
docker compose ps

启动后访问：

• Web 界面：http://localhost:8000⁠
• API 文档：http://localhost:8000/docs⁠

docker logs doublestack-subtitle

自动生成的令牌保存在字幕映射目录的 .doublestack-sub/doublestack-sub.db 数据库中，容器重建后会继续使用相同令牌。

为兼容已有安装并避免设置、历史记录和媒体索引丢失，内部数据目录继续使用旧路径 .doublestack-sub；这不影响新的项目英文名和镜像名称。

⁠方式二：Docker Run 部署

# 创建映射目录
mkdir -p media subtitles

# 启动容器
docker run -d \
  --name doublestack-subtitle \
  -p 8000:8000 \
  -e API_TOKEN='请替换为高强度随机令牌' \
  -v "$(pwd)/media:/media:ro" \
  -v "$(pwd)/subtitles:/downloads" \
  --shm-size=1g \
  --restart unless-stopped \
  lastthree/doublestack-subtitle:v0.0.1

⁠目录映射说明

⁠使用说明

⁠媒体文件

支持以下常见视频扩展名：

3gp, avi, divx, flv, m2ts, m4v, mkv, mov, mp4,
mpeg, mpg, mts, rm, rmvb, ts, webm, wmv

媒体页会递归遍历 /media，展示识别后的标题及封面。点击媒体卡片上的字幕搜索按钮，可将标题带到字幕页面继续搜索。

⁠封面文件

支持 JPG、JPEG、PNG、WebP 和 AVIF。程序会优先查找：

1. 影片名-poster.jpg
2. 影片名.poster.jpg
3. 影片名_poster.jpg
4. 与视频文件同名的图片
5. poster、folder、cover、movie 等图片

当目录中只有一张支持的图片时，也会将其作为封面。

⁠媒体名称识别正则

设置页面最多可添加 20 条正则，每条最长 300 个字符。程序按顺序使用第一条匹配成功的规则；存在捕获组时，使用第一个捕获组作为媒体标题。

默认规则：

(.*?)\s*\(\d{4}\)

示例：

文件名：十二生肖 (2012) - 1080p.mkv
识别结果：十二生肖

其他示例：

⁠项目结构

doublestack-subtitle/
├── app/
│   ├── main.py                 # FastAPI 应用入口与接口路由
│   ├── config.py               # 运行参数
│   ├── models.py               # API 数据模型
│   ├── version.py              # 项目名称与版本
│   ├── services/
│   │   ├── media_library.py    # 媒体扫描、标题和封面识别
│   │   └── settings_store.py   # SQLite 设置、迁移及数据校验
│   └── static/
│       ├── index.html          # 前端页面
│       ├── app.js              # 前端交互
│       ├── styles.css          # 页面样式
│       └── logo.png            # 项目标识
├── Dockerfile                  # Docker 镜像构建文件
├── docker-compose.yml          # 无需构建的 Compose 配置
├── requirements.txt            # Python 依赖
└── README.md                   # 项目说明

⁠技术栈

• 后端：FastAPI + Uvicorn
• 页面：原生 HTML、CSS、JavaScript
• 字幕解析：Requests + Beautiful Soup + Playwright
• 验证码识别：ddddocr
• 容器运行：Docker + Docker Compose

⁠API 接口

Web 页面可直接访问，无需输入 Token。对外提供的 /api/* 接口除健康检查外均需要 Bearer Token；页面内部使用的公开接口不会显示在 Swagger API 文档中。

命令行调用示例：

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  http://localhost:8000/api/media

Swagger API 文档右上角的 Authorize 按钮也可填写同一令牌。

⁠版本信息

⁠许可证

本项目当前未附带开源许可证。除非获得项目所有者授权，否则不授予复制、修改或分发源代码的权利。

⁠联系方式

• GitHub：https://github.com/Double-Stack-Workshop/doublestack-sub⁠
• 博客：https://blog.doublestack.top⁠