---
name: subtitle-srt
description: 当用户说"生成字幕"、"做 SRT"、"字幕文件"、"subtitle-srt"，或在 workflow 里要把分段文本 + 时长信息转成标准 SRT 字幕文件时使用。给定 cue 列表（每条带文本和起止时间或时长），生成符合 SRT 规范的字幕文件。
---

# subtitle-srt —— SRT 字幕生成

> 通用 skill，不绑定语种 / 不绑定视频比例 / 不绑定字体（字体是视频合成阶段的事）。

## 输入约定

支持两种输入形态：

### 形态 A：cues_json（一次性给所有 cue）

```
cues_json=<JSON 数组> output=./subs.srt [encoding=utf-8]
```

`cues_json` 是合法 JSON 数组，每个元素至少有 `text`，时间可以两种方式给：

```json
[
  {"text": "开场白", "start": 0.0, "end": 3.5},
  {"text": "第二幕", "start": 3.5, "end": 7.7}
]
```

或者只给时长，由本 skill 自动累加：

```json
[
  {"text": "开场白", "duration": 3.5},
  {"text": "第二幕", "duration": 4.2}
]
```

### 形态 B：texts + durations（两个并列数组）

```
texts=<JSON 字符串数组> durations=<逗号分隔秒数> output=./subs.srt
```

例：
```
texts=["开场白","第二幕","第三幕"] durations=3.5,4.2,3.0 output=./subs.srt
```

> 形态 B 比形态 A 易写，适合 workflow 里用 capture 拼出的简单场景。

## 标准执行流程

### 1. 解析输入

判断是哪种形态：含 `cues_json=` 字段走 A，含 `texts=` + `durations=` 走 B。两者都不满足 → 报错。

### 2. 计算每条 cue 的起止时间戳

如果给了 `start` + `end`（形态 A 第一种），直接用。

否则按 `duration` 累加：
- cue 1: start=0.0, end=duration[0]
- cue 2: start=end[0], end=start[1]+duration[1]
- ...

### 3. 时间戳格式转换

SRT 时间戳格式：`HH:MM:SS,mmm`（毫秒前**用逗号不用点**）。

公式：
```
total_ms = round(seconds * 1000)
hh = total_ms // 3600000
mm = (total_ms % 3600000) // 60000
ss = (total_ms % 60000) // 1000
ms = total_ms % 1000
formatted = f"{hh:02d}:{mm:02d}:{ss:02d},{ms:03d}"
```

### 4. 拼 SRT 内容

每条 cue 4 行（序号 / 时间戳 / 文本 / 空行）：

```
1
00:00:00,000 --> 00:00:03,500
开场白

2
00:00:03,500 --> 00:00:07,700
第二幕

```

> ⚠️ 最后一条 cue 末尾**也要有空行**，否则部分播放器会吞掉最后一句。

### 5. 写入文件

用 Write 工具：
- `file_path = OUTPUT`
- `content = <上面拼好的 SRT 字符串>`

或者用 Bash + heredoc（注意编码，Windows 上要保证 UTF-8 无 BOM）：
```bash
mkdir -p "$(dirname "$OUTPUT")"
cat > "$OUTPUT" <<'EOF'
1
00:00:00,000 --> 00:00:03,500
开场白

EOF
```

### 6. 自检（可选）

如果机器有 ffprobe，跑一下确认字幕可读：
```bash
ffprobe -v error -loglevel error -i "$OUTPUT" 2>&1 || echo "ffprobe 验证未通过：$?"
```

ffprobe 失败不算硬错（部分版本对 SRT 解析比较宽松），但要打印 warning。

### 7. 收尾输出

```
saved: <OUTPUT> (cues=<N>, duration=<TOTAL_SEC>s)
```

## 注意事项

- 长文本自动换行：单 cue 文本超过 ~30 字时，在自然标点处插入换行（`，` / `。` / `？` / `！`）。SRT 单条多行用真实换行符即可
- **不打印用户文本内容到日志**（隐私）
- 字符编码强制 UTF-8 无 BOM；Windows PowerShell 写文件时显式 `-Encoding utf8`
- 不假设语种 —— 中英日韩都按字符长度判断换行（中文 1 字符 ≈ 英文 2 字符的视觉宽度，可按 30 字符切）
