feat: 初始化 doco 子项目 P1 阶段(视频双路拆分预处理)

2026-06-12 16:31:21 +08:00
parent 70e2647fae
commit 0e6322ad97
10 changed files with 1149 additions and 13 deletions
@@ -0,0 +1,116 @@
+# 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`