Metadata-Version: 2.4
Name: live-digest
Version: 0.1.0
Summary: 解析直播录屏/长视频，本地转写+场景抽帧+大模型提炼，生成带时间戳跳转回放的结构化 HTML 报告
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: scenedetect>=0.6.5
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: openai>=1.40
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: local-asr
Requires-Dist: funasr>=1.1.0; extra == "local-asr"
Requires-Dist: torch>=2.0; extra == "local-asr"
Requires-Dist: torchaudio>=2.0; extra == "local-asr"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"

# live-digest · 直播录屏摘要工具

解析直播录屏/长视频：本地场景抽帧 + 语音转写 + 大模型提炼，生成**带时间戳跳转回放**的结构化 HTML 单页报告。提供本机网页工作台（拖入视频、实时进度、历史报告）与命令行两种入口，支持目录批处理与断点续跑，兼容 Windows / macOS。

## 工作原理

```
录屏文件 ──① ffmpeg 提音频 + VAD 剔除无人声
        ──② 语音转写（二选一，设置里随时切换）
             ☁ 云端：OpenAI 兼容转写服务（默认硅基流动 SenseVoice，约 0.1 元/小时）
             💻 本地：SenseVoice 本地推理（免费，需另装本地引擎 + 1-2GB 模型）
        ──③ PySceneDetect 场景抽帧（640px 压缩）
        ──④ 大模型两阶段提炼（段级并发 → 全局聚合，自动判定带货/知识培训/娱乐）
             带货类型追加关键帧视觉理解（提取商品/价格/公告）
        ──⑤ 渲染自包含 report.html（写入视频同目录，点时间戳回放原片）
```

## 快速开始（两套门面，按你的情况选）

安装是同一次（下面方式一二三任选），装完后有两套使用门面，共享同一份配置和报告数据。

### 安装

**方式一：一键安装脚本（推荐，Windows/macOS 通用）**

1. 把整个 `live-digest` 文件夹拷到你电脑
2. Windows 双击 `scripts\install-windows.bat`（macOS 双击 `scripts/install-macos.command`）
3. 跟着中文向导走：选服务商 → 粘贴 API Key → 自动创建桌面图标和全局命令 → 启动工作台

脚本会自动完成：Python/ffmpeg 环境检测与引导、依赖安装、**桌面/开始菜单快捷方式**、**`digest` 全局命令注册**（之后任何终端都能直接用）。

**方式二：包管理器（技术用户，需 PyPI 发布后）**

```bash
pipx install live-digest            # 核心包（轻量，云端转写开箱即用）
pipx install "live-digest[local-asr]"  # 需要本地转写引擎再装这个
```

**方式三：源码开发**

```powershell
cd live-digest
pip install -e .
```

---

### 门面 A：网页工作台（给不想碰命令行的人）

1. 双击桌面「live-digest 工作台」图标（自动打开浏览器）
2. 「处理任务」页：把录屏文件或整个文件夹拖进去（或粘贴路径）→ 看实时进度
3. 处理完到「历史报告」页点「打开报告」
4. 第一次使用先到「设置」页：选服务商（下拉框）→ 照页面指引拿 Key → 粘贴 → 点「测试连接」看到 ✓

日常就三步：**打开 → 拖入 → 点报告**。关掉网页任务继续跑。

### 门面 B：命令行 CLI（给技术用户，可被 ZCode 等编码 agent 直接调用）

**传统一次性命令**（处理完出报告）：

```powershell
digest D:\录屏\某场直播.mp4     # 单视频
digest D:\录屏\                 # 目录批处理
digest workbench                 # 启动工作台
```

**Agent 对话模式**（自然语言操作本地数据，免记命令）：

```powershell
digest agent
你> 都有哪些场次？
你> 第一场讲了什么？
你> 帮我搜一下讲过"赛马机制"的片段
你> 把 D:\录屏 处理了          ← 会先列出清单确认
```

**原子命令（ZCode/Codex 等编码 agent 的工具）**：输出纯 JSON、退出码表意、无交互提示，编码 agent 直接执行解析即可：

```powershell
digest reports list        # 所有历史报告
digest reports show 场次A   # 某场摘要（TL;DR/重点/时间戳）
digest search "赛马机制"    # 全库搜文字稿
digest status              # 任务进度
digest process D:\录屏\    # 发起后台处理
digest config get          # 读配置
```

> 在 ZCode 里使用：无需任何配置，直接让编码 agent 执行上面的命令并解析 JSON。例如对它说「用 digest search 搜一下报告里关于定价的内容，整理成要点」。

---

## 配置（BYOK：费用走你自己的服务账号）

工作台「设置」页提供**内置供应商下拉框**（端点/模型自动带出，只需粘贴 Key，每项附获取 Key 指引）：

- **转写服务商**：硅基流动（推荐）/ 阿里云百炼 / OpenAI / 火山引擎（即将支持）
- **提炼服务商**：DeepSeek / 智谱 GLM / 阿里百炼通义 / Kimi
- 高级用户可在下拉框选「自定义」手填任何 OpenAI 兼容服务端点

环境变量方式（CI/自动化）：`DIGEST_API_KEY`（提炼）、`DIGEST_ASR_API_KEY`（转写，留空回退提炼 key）、`DIGEST_ASR`（local/cloud）、`DIGEST_API_BASE`、`DIGEST_MODEL`。也可写入 `digest.toml`（用户目录，工作台设置页同源）。

## 使用

**Agent 对话模式**（技术用户，自然语言操作本地数据）：

```powershell
digest agent
你> 都有哪些场次？
你> 第一场讲了什么？
你> 帮我搜一下讲过"赛马机制"的片段
你> 把 D:\录屏 处理了          ← 会先列出清单确认
```

**机器调用（编码 agent / 脚本）**：原子子命令输出纯 JSON、退出码表意、无交互提示，可被 ZCode 等工具直接执行解析：

```powershell
digest reports list        # 所有历史报告
digest reports show 场次A   # 某场摘要（TL;DR/重点/时间戳）
digest search "赛马机制"    # 全库搜文字稿
digest status              # 任务进度
digest process D:\录屏\    # 发起后台处理
digest config get          # 读配置
```

**网页工作台**（推荐）：

```powershell
digest workbench
```

自动打开浏览器 → 拖入/粘贴视频或文件夹 → 实时看每个视频的处理阶段 → 完成后在「历史报告」一键打开。**关闭浏览器任务继续跑**。

**命令行**：

```powershell
digest D:\录屏\某场直播.mp4     # 单视频
digest D:\录屏\                 # 目录批处理（逐视频失败隔离 + 汇总）
digest 某视频.mp4 --force       # 完全重跑（默认跳过已完成、断点续跑）
```

## 报告功能

- 概览卡（核心结论/内容类型/话题标签/转写质量）、章节时间轴
- 重点区主分组随内容类型自适应：知识培训→知识点打头（含展开要点）；带货→商品价格打头
- 带货/混合类型：关键帧画面识别的商品/价格/公告（「画面信息」区块）
- 章节卡片含关键帧缩略图；完整文字稿可搜索
- **点任意时间戳 → 右下角播放器定位回放原片**（报告须与视频同目录；ESC 收起并暂停；视频不在同目录自动降级纯文本）

## 产出位置

```
视频所在目录/
├── report.html                    # 报告（与视频同目录 → 跳转可用）
└── output/视频名/                  # 工作目录（meta.json 进度 + 转写/帧/摘要中间产物）
```

## 平台说明

- **Windows**：完整支持（本地/云端转写均验证）
- **macOS**：云端转写完整可用；本地转写引擎暂未验证（安装向导会建议用云端）
- 首次以云端转写处理即开即用；本地引擎为可选增强（`[local-asr]` extras）

## 开发

规格驱动（SpecKit-CN）：规格见 `specs/001-video-digest/` 与 `specs/002-distribution/`；测试 `pytest`（200+ 用例，默认全离线；`pytest -m slow` 跑真安装用例）；质量门禁 `ruff check .` + `mypy live_digest`。

## 常见问题

- **凭证未配置**：工作台会引导到设置页；命令行报错提示设置 `DIGEST_API_KEY`
- **ffmpeg 未找到**：安装脚本自动引导（winget/brew）；手动装后重跑脚本
- **工作台打不开**：终端会打印实际端口（默认 27887，被占用自动 +1）
- **转写质量差**（BGM 盖人声）：报告概览会标注「置信度低」
- **报告时间戳不能跳转**：报告需与视频文件在同一目录
- **macOS 选本地转写提示未验证**：正常，建议用云端转写
