video-chapters git:20260828.21694ddA

Immutable. This exact content is served forever at /api/v1/blob/2af4df61055c537d.

---
name: video-chapters
description: "视频章节 / 时间戳目录：给中长视频自动生成章节划分和时间戳目录，用于 B站分P/YouTube 章节/视频描述区，方便观众跳转、提升完播。当用户说 视频章节、章节目录、时间戳、分章节、视频目录、chapters、B站章节、YouTube 章节、给视频加时间点、看点目录、视频大纲时间戳 时使用。编排复用 asr.py（带时间轴转录），章节划分与命名由 LLM 完成。与 video-to-article 区别：那个把视频改写成成篇图文，本 SKILL 只出章节时间戳目录。"
layer: produce
---

# 视频章节 / 时间戳目录

> 给中长视频生成章节时间戳目录（B站/YouTube 描述区可用）。带时间轴转录走 `asr.py`，
> **章节切分与命名由你（LLM）完成**。

> 出成篇图文见 **video-to-article**；出字幕见 **auto-subtitle**；切成短视频见 **video-highlights**。

## 输入

| 字段 | 必填 | 说明 |
|------|------|------|
| 视频文件 | 是 | 中长视频（教程/评测/讲座/直播回放；没给就问） |
| 目标平台 | 否 | B站 / YouTube / 通用（影响格式与措辞） |
| 章节数 | 否 | 期望章节数（默认按内容自然划分，通常 5-12 段） |

## 输出（`outputs/主题名/`）

- `chapters.txt` — 时间戳目录（每行 `mm:ss 章节名`，可直接贴描述区）
- `chapters.json` — 结构化（start 秒 + 标题），供程序化使用
- `transcript.txt` — 转录原文（备查）

## 执行步骤

脚本路径（相对项目根）：`skills/shared/scripts/asr.py`。

### 1. 带时间轴转录
```bash
python skills/shared/scripts/asr.py transcribe -i <视频> --format json \
  -o outputs/主题名/transcript.json
```
（首次跑 ASR 需外网代理下模型，见 auto-subtitle 前置说明。）

### 2. 划分章节（你来做）
读 transcript.json（每段带 start/end），按**话题转折**划分章节：
- 找主题切换点作为章节边界（不是均匀切时间，而是按内容）。
- **第一章从 00:00 开始**（平台要求，否则章节功能不生效）。
- 每章名 6-16 字，动词开头或点明看点（如"实测续航翻车了""3 分钟教你上手"），不写"第一部分"。
- 章节数适中（太碎观众烦，太粗没用），一般 5-12 段；短视频（<3 分钟）通常不需要章节。
- 章节最短 ≥10 秒（平台 YouTube 要求相邻章节间隔 ≥10s）。

### 3. 输出目录
写 `chapters.txt`（每行 `mm:ss 章节名`，首行必须 `00:00`）：
```
00:00 开场｜今天聊什么
01:24 第一个坑：xxx
03:50 实测环节
...
```
同时写 `chapters.json`：`[{"start": 0, "title": "开场｜今天聊什么"}, ...]`。

## 平台格式差异

- **YouTube**：贴在视频描述区，首个必须 `0:00`，≥3 章、每章 ≥10s 自动生效。
- **B站**：作为"看点/进度条章节"或分P说明，格式 `mm:ss 标题`。
- **通用**：`chapters.txt` 通用可读。

## 规则

1. 章节边界按**话题转折**定，不是均匀切时间。
2. 首章必须 00:00；相邻章节间隔 ≥10s。
3. 章节名点明看点、简洁有吸引力，不用"第一部分"这类空名。
4. 不编造视频没讲的内容；依据转录如实划分。
5. 产物统一进 `outputs/主题名/`。

## 参考来源

章节时间戳是 YouTube/B站 提升完播与检索的标准做法（首章 0:00、≥10s 间隔为平台硬规则）。
转录用 faster-whisper（asr.py）出时间轴，话题切分交给 LLM——确定性 IO 与语义划分分层。