discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

dengzi008/DramaLens · source

Snapshot 0 · 2026-11-04T12:47:28Z · JavaScript · AGPL-3.0

GitHub description at capture

Local-first Chrome extension for timestamped transcription and human-reviewed short-form drama analysis.

README at capture

# DramaLens｜短剧创作拆解助手

DramaLens 是一个本地优先的 Chrome 扩展与 Python 服务，用于将用户有权处理的短剧、访谈和其他视听素材整理为带时间码的文本，并生成可人工复核的创作结构分析。

它解决的核心问题是：创作者在研究节奏、冲突、反转和人物关系时，需要反复播放素材、记录时间点、整理台词和撰写分析，手工流程耗时且容易遗漏。

> 项目仍处于早期阶段。AI 转写、角色推断和结构分析都可能出错，输出必须人工复核。

## 功能

- 主动捕获当前 Chrome 标签页音频，不下载视频
- 使用 Windows WASAPI Loopback 或 macOS CoreAudio + BlackHole 录制桌面应用正在播放的声音
- 使用本地 `faster-whisper` 生成中文时间轴
- 在扩展中修改文本、合并片段、填写或校对角色
- 通过 OpenAI 兼容文本接口生成单集创作拆解
- 分析剧情梗概、本集作用、人物关系、开场钩子、冲突节点、情绪曲线、反转和结尾悬念
- 保存项目报告，生成前 10 集、前 30 集或全部已保存集数的整体分析
- 导出单集或多集 Word 报告
- 转写与 AI 分析在扩展后台运行，关闭弹窗后仍可继续

## 工作方式

```text
用户主动录制标签页音频
          ↓
本地 faster-whisper 转写
          ↓
时间轴与角色人工校对
          ↓
可选：调用用户配置的文本模型生成分析
          ↓
人工复核并导出 Word
```

原始音频仅发送到本机 `127.0.0.1:3211`。只有用户点击 AI 分析时，整理后的文本才会发送到其自行配置的 OpenAI 兼容接口。

## 安装要求

- Windows 10/11，或 macOS 13 及更高版本
- Chrome 或兼容 Chromium 的浏览器
- Python 3.11
- 建议至少 8 GB 内存；本地 `medium` 模型首次运行需要下载模型文件

## 快速开始

### 1. 安装本地服务

macOS 用户请直接阅读 [macOS 安装与录音说明](docs/MACOS.md)。Windows 用户按以下步骤操作。

克隆仓库后，在项目目录中双击：

```text
install-local-asr.cmd
```

安装完成后复制环境变量模板：

```powershell
Copy-Item .env.example .env
```

如果需要 AI 分析，在 `.env` 中填写自己的接口地址、模型名和密钥。语音转写本身不需要 API 密钥。

### 2. 启动本地服务

双击：

```text
start-asr.cmd
```

浏览器访问 `http://127.0.0.1:3211/api/health`。看到 `"ok": true` 后即可加载扩展。

### 3. 加载 Chrome 扩展

1. 打开 `chrome://extensions/`
2. 开启“开发者模式”
3. 点击“加载已解压的扩展程序”
4. 选择本项目的 `extension` 目录

### 4. 使用

1. 打开你有权处理的素材并正常播放
2. 在“项目采集”填写项目名称和集数范围；单集任务将起止集填写相同
3. 点击“开始采集”；多集每集结束按 `F8`，单集或最后一集结束按 `F10`
4. 等待后台完整识别，可对失败集单独重试
5. 可选：点击“AI校对并生成报告”
6. 点击“保存到项目”，再进行单集复核、整体分析或Word导出

## 配置

`.env.example` 提供以下配置：

| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| `OPENAI_API_KEY` | 可选，文本模型接口密钥 | 空 |
| `OPENAI_BASE_URL` | OpenAI 兼容接口基础地址 | `https://api.openai.com/v1` |
| `AI_MODEL` | 文本分析模型名称 | `gpt-4.1-mini` |
| `LOCAL_ASR_MODEL` | faster-whisper 模型 | `medium` |
| `LOCAL_ASR_DEVICE` | 推理设备 | `cpu` |
| `LOCAL_ASR_COMPUTE_TYPE` | 推理精度 | `int8` |
| `ASR_PORT` | 本地服务端口 | `3211` |
| `MAX_AUDIO_BYTES` | 单个音频最大字节数 | `26214400` |
| `MACOS_AUDIO_DEVICE` | macOS 桌面录音输入设备名称 | `BlackHole` |

不要提交 `.env`。项目不会要求维护者代管用户 API 密钥。

## 统一项目采集

单集和多集统一使用“项目采集”，不再需要选择不同录音入口：

1. 填写剧名、起始集数和可选的结束集数
2. 单集任务将起止集数填写相同；多集任务填写对应范围
3. 点击“开始采集”和“打开置顶控制器”
4. 多集任务每集结束按 `F8`，程序保存当前集并立即开始下一集
5. 单集或最后一集结束按 `F10`，后台继续完成完整识别队列
6. 失败集可单独重试；识别完成后点击“AI校对并生成报告”
7. 点击“保存到项目”，再生成人工审核后的整体分析和Word报告

批量音频、队列状态和转写草稿保存在本地 `recordings/batch`，不会提交到Git。程序只会自动合并时间重叠、文本高度相似的重复片段；有剧情意义的重复对白仍需人工判断。

## 隐私与安全边界

- 扩展只在用户主动点击后捕获当前标签页音频
- 不调用目标平台隐藏接口，不绕过登录、付费、加密或技术保护
- 不自动下载视频，也不批量抓取站点内容
- 本地服务只监听 `127.0.0.1`
- AI 接口由用户自行配置；第三方中转接口的隐私和可靠性由其运营者决定
- 不应对不可信来源的 `.env`、脚本或模型文件放宽系统权限

安全问题请参阅 [SECURITY.md](SECURITY.md)。

## 合法使用

DramaLens 面向创作研究、无障碍转写、个人学习以及获得授权素材的整理。使用者应遵守所在地法律、素材授权条款和目标网站服务条款。

本项目不授予任何第三方影视、音频或文本内容的复制、传播或商业利用权。请勿使用本项目绕过访问控制、批量复制受版权保护的作品，或向他人交付未经授权的完整台词文本。

## 当前限制

- 当前录音仍是实时流程，倍速播放会让时间码对应录制时间，而不是原始视频时间
- 桌面录音在 Windows 采集默认扬声器输出；macOS 通过 BlackHole 采集 CoreAudio 输出。录制时请关闭消息提示音和其他媒体
- 最近一次桌面录音会保留在本地 `recordings` 目录，开始下一次录音时自动替换
- 角色名称由语言模型根据上下文推断，准确率受台词信息影响
- 本地 Whisper 的速度取决于电脑配置
- macOS 桌面 App 录音需要额外安装和配置 BlackHole；浏览器标签页录音不需要
- 项目尚无 Chrome Web Store 正式版本，需要开发者模式加载

## 路线图

- [x] macOS 启动脚本、CoreAudio 录音适配与安装文档
- [ ] Linux 启动脚本与安装文档
- [ ] 自动化测试与固定测试样本
- [ ] 更可靠的角色一致性检查
- [ ] 可编辑的分析模板和提示词
- [ ] 项目数据的导入、导出和备份
- [ ] 可选的 GPU 推理配置
- [ ] 无障碍和国际化改进

## 真实使用案例

- [案例 001：单集素材从标签页录音到创作拆解报告](docs/CASE_STUDY_001.md)
- [案例 002：真实编剧客户的 19 集批量创作分析](docs/CASE_STUDY_002.md)

案例只公开操作流程、脱敏统计和维护结论，不公开原始录音、完整台词或可识别的第三方作品内容。

## 参与贡献

欢迎提交 Issue、功能建议和 Pull Request。开始贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

本项目使用 GNU Affero General Public License v3.0。详见 [LICENSE](LICENSE)。

## 维护者

由 [@dengzi008](https://github.com/dengzi008) 创建和维护。