# 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` |

## 系统依赖

- **Python >= 3.12**
- **ffmpeg >= 4.x** (必须安装并加入 PATH)
  - Windows 下载: https://ffmpeg.org/download.html
  - macOS: `brew install ffmpeg`
  - Linux: `apt install ffmpeg`

## 安装

```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/ |

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

## P1 使用方法

### 准备素材目录

```
programs/
└── ep001_20260612_fangkong_fandao/
    └── source/
        └── video.mp4   ← 放入节目视频
```

> video.mp4 由制片人放入,不放进 git

### 运行拆分

```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   # 迷你测试视频
├── 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`