tps-dashboard/doco/README.md

# Doco - TPS 中台终版文稿生成子模块

> 央视《军事科技》栏目 - 终版文稿自动生成流水线

## 项目状态

**当前 Phase: P1** - 视频双路拆分预处理

## 功能概述

Doco 将一期《军事科技》节目视频拆分为两路输入,供下游三方融合(P3)使用:

| 输出 | 规格 | 存放位置 |
|---|---|---|
| B 稿 | 带时间戳的 txt,`[Nm Ns] 句子`格式 | `work/b_manuscript.txt` |
| 音频 | 16kHz / 单声道 / 16bit WAV | `work/audio_16k.wav` |
| 关键帧索引 | JSON | `work/keyframes.json` |

## 系统依赖

### ffmpeg (必须)

**Windows 用户:**
1. 从 https://www.gyan.dev/ffmpeg/builds/ 下载 ffmpeg (建议用 essentials 版本)
2. 解压到本地目录(如 `C:\ffmpeg`)
3. 把 `C:\ffmpeg\bin` 加入系统 PATH
4. 打开 cmd,验证: `ffmpeg -version`

**Mac 用户:**
```bash
brew install ffmpeg
```

**Linux 用户:**
```bash
apt install ffmpeg
```

### Python >= 3.12

## 安装

```bash
# 1. 克隆仓库后进入 doco 目录
cd doco

# 2. 安装依赖
pip install -e .

# 3. 配置凭证
cp .env.example .env
# 编辑 .env,填入三组 API 凭证
```

## 凭证配置

Doco 使用三组独立凭证,互不混用:

| 服务 | 用途 | 申请地址 |
|---|---|---|
| 讯飞开放平台 - 录音文件转写(标准版) | 音频转文字 | https://console.xfyun.cn/ |
| DeepSeek Vision | OCR 识别 | https://platform.deepseek.com/ |
| Anthropic Claude API | AI 融合层(P3) | https://console.anthropic.com/ |

> 注意: 讯飞要用"录音文件转写标准版",不要用"大模型版"

## 使用步骤(按顺序,不要跳步)

### Step A. 安装 ffmpeg

见上方"系统依赖"一节。安装后打开 cmd 验证 `ffmpeg -version` 能看到版本号。

### Step B. 生成迷你测试视频(验证 ffmpeg 装好了)

```bash
ffmpeg -f lavfi -i testsrc=duration=5:size=320x240:rate=1 \
       -f lavfi -i anullsrc=channel_layout=mono:sample_rate=16000 \
       -c:v libx264 -c:a aac -shortest \
       doco/tests/fixtures/mini_test.mp4 -y
```

出现 `mini_test.mp4` 文件即成功。

### Step C. 把 demo 视频放到指定位置

```bash
# 把 demo 视频文件复制到:
programs/ep001_20260612_fangkong_fandao/source/video.mp4
```

> video.mp4 由制片人放入,不放进 git(已加入 .gitignore)

### Step D. 配置凭证

```bash
cp doco/.env.example doco/.env
# 用记事本或 VS Code 编辑 doco/.env,填入三组真实 API key
```

### Step E. 安装 doco 包

```bash
cd doco && pip install -e .
```

### Step F. 跑 dry-run(只裁切,不调 OCR API)

**重要:先跑 dry-run,确认裁切框包住字幕后再跑正式版。**

```bash
doco split \
  --episode-id ep001_20260612_fangkong_fandao \
  --input-video programs/ep001_20260612_fangkong_fandao/source/video.mp4 \
  --output-dir programs/ep001_20260612_fangkong_fandao/work/ \
  --dry-run
```

**验收 dry-run 结果:**
1. 检查 `work/frames/` 目录下的前 3-5 张关键帧小图
2. 确认字幕被完整框住、没有切掉字
3. 如果裁切位置不对,停下来反馈

### Step G. 跑正式版(去掉 --dry-run)

dry-run 验收通过后,跑正式版:

```bash
doco split \
  --episode-id ep001_20260612_fangkong_fandao \
  --input-video programs/ep001_20260612_fangkong_fandao/source/video.mp4 \
  --output-dir programs/ep001_20260612_fangkong_fandao/work/
```

### 输出产物

```
programs/ep001_20260612_fangkong_fandao/work/
├── frames/                # 抽出的帧(临时)
├── audio_16k.wav          # 音频(16kHz/单声道/16bit)
├── b_manuscript.txt       # B 稿([Nm Ns] 句子格式)
└── keyframes.json         # 关键帧索引(含裁切参数)
```

## P1 验收标准

1. `work/b_manuscript.txt` 格式为 `[Nm Ns] 句子`,每行一句
2. `work/audio_16k.wav` 规格为 16kHz/单声道/16bit,能被讯飞 ASR 接收
3. `work/keyframes.json` 字段符合定义

## 目录结构

```
doco/
├── src/
│   ├── __init__.py
│   ├── cli.py              # CLI 入口
│   ├── video_split.py      # P1 核心:视频双路拆分
│   ├── asr_adapter.py     # 讯飞 ASR 适配层
│   └── ocr_adapter.py      # P2:DeepSeek Vision OCR
├── tests/
│   ├── test_video_split.py # 单元测试
│   └── fixtures/
│       └── mini_test.mp4   # 迷你测试视频(需 Step B 生成)
├── docs/
├── .env.example            # 凭证模板
├── README.md
└── pyproject.toml
```

## 相关文档

- Brief: `docs/doco/Doco子项目_Brief.md`
- 设计文档: `docs/doco/doco_project_design.md`
- 讯飞接入笔记: `docs/doco/doco_xfyun_integration_notes.md`
- 主项目回复: `docs/doco/主project对Doco_PRDv2的回复.md`