pipeline-ktv/README.md

# pipeline-ktv — KTV产线适配器

KTV产线的step_type和handler适配器，独立于pipeline-service核心引擎。

## 定位

- **pipeline-service**: 底层引擎（DAG调度、状态机、存储），稳定不变
- **pipeline-ktv**: 业务适配器（17个KTV步骤处理器），独立演进

## 架构

```
宿主应用 (pipeline-app)
  │
  ├── load_pipeline_service()    ← 加载引擎
  └── load_ktv_adapter()         ← 加载KTV适配器
        ├── register_step_type() × 17  ← 注册步骤类型元数据
        └── register_handler()  × 17  ← 注册步骤处理器
```

## 使用方式

```python
from pipeline_service import load_pipeline_service
from pipeline_ktv import load_ktv_adapter

# 1. 加载引擎（只加载一次）
load_pipeline_service()

# 2. 加载KTV适配器
load_ktv_adapter()

# 3. 正常使用产线API
env = ServerEnv()
await env.pipeline_submit(tenant_id, ktv_pipeline_id, owner_id, title, params)
```

## 步骤类型

### 模式A — 音频→KTV（最常见）
```
audio_preparing → demucs_separating → lyric_calibrating → subtitle_rendering
                                                        → music_generating → music_polling
                                                        → character_designing → character_image_generating
                                                        → storyboard_generating → scene_video_generating
                                                          → scene_video_evaluating → scene_video_concatenating
                                                          → ktv_synthesizing
```

### 模式B — 视频→KTV
```
video_preparing → demucs_separating → lyric_calibrating → subtitle_rendering → ktv_synthesizing
```

### 模式C — AI全生成
```
lyric_generating → lyric_evaluating → music_generating → music_polling
                 → character_designing → character_image_generating
                 → storyboard_generating → scene_video_generating
                   → scene_video_evaluating → scene_video_concatenating
                   → subtitle_rendering → ktv_synthesizing
```

## 17个步骤处理器

| step_type | 类别 | 说明 |
|-----------|------|------|
| audio_preparing | media | 下载音频，提取时长 |
| video_preparing | media | 下载视频，提取音频轨道 |
| demucs_separating | media | GPU运行Demucs分离人声/伴奏 |
| lyric_calibrating | llm | ASR+LLM校准歌词时间戳 |
| subtitle_rendering | media | 生成ASS卡拉OK字幕 |
| subtitle_exporting | media | 导出字幕文件 |
| lyric_generating | llm | LLM创作歌词 |
| lyric_evaluating | llm | LLM评估歌词质量 |
| music_generating | media | 提交Suno/MiniMax音乐生成 |
| music_polling | media | 轮询音乐生成结果 |
| character_designing | llm | LLM设计MV角色 |
| character_image_generating | media | GPU生成角色图片 |
| storyboard_generating | llm | LLM生成分镜脚本 |
| scene_video_generating | media | GPU T2V/Ref2V生成场景视频 |
| scene_video_evaluating | media | 评估场景视频质量 |
| scene_video_concatenating | media | ffmpeg拼接场景视频 |
| ktv_synthesizing | media | 合成KTV双轨+MTV最终视频 |

## 依赖

- pipeline_service >= 3.1.0（引擎核心）
- pipeline_service.llm_bridge（LLM调用）
- GPU服务器（Demucs、wan2.2视频生成）
- ffmpeg（本地视频处理）

## 目录结构

```
pipeline-ktv/
├── pipeline_ktv/
│   ├── __init__.py       # 包导出
│   ├── adapter.py        # load_ktv_adapter() + 注册逻辑
│   └── handlers.py       # 17个step handler函数
├── init/
│   └── data.json         # KTV appcodes
├── pyproject.toml
└── README.md
```

## 适配器模式说明

每种产线类型都是一个独立的适配器包：

| 适配器 | 产线 | 状态 |
|--------|------|------|
| pipeline-ktv | KTV/MTV音乐视频 | ✅ 当前 |
| pipeline-sdlc | 软件开发全生命周期 | 🔜 计划中 |
| pipeline-xxx | 未来产线... | 按需创建 |

创建新产线适配器的步骤：
1. `mkdir pipeline-xxx && cd pipeline-xxx`
2. 创建 `pipeline_xxx/handlers.py` — 编写step handler函数
3. 创建 `pipeline_xxx/adapter.py` — 定义step_type元数据 + load函数
4. 创建 `pyproject.toml` — 依赖 `pipeline_service>=3.1.0`
5. 宿主应用中调用 `load_xxx_adapter()`

**pipeline-service核心代码永远不需要修改。**