用途：youtube-chapters 用于为视频生成可直接粘贴到 YouTube 的章节时间戳列表。它接收 YouTube 链接（任意语言）、本地视频或音频文件，或用户粘贴的转写文本/SRT，输出带时间戳的章节清单。它不负责无时间戳的摘要，也不做视频剪切与编辑。
主要能力：第一步获取带时间戳的转写。对于有字幕的 YouTube 视频，脚本通过 yt-dlp 只拉取字幕轨，无需下载视频或做语音识别，且人工字幕优先于自动字幕。对于本地文件或无字幕视频，使用 Whisper 语音转写，按可用条件依次选择 GROQ_API_KEY 或 OPENAI_API_KEY 的 Whisper API、本地安装的 faster-whisper、或 whisper CLI；若都没有，脚本会打印需要安装的内容。脚本输出 TITLE、DURATION、LANGUAGE、SOURCE 以及“M:SS⇥文本”形式的逐行转写。
使用方式：运行 python3 scripts/transcript.py "<youtube-url-or-file-path>"，可选参数包括 --lang ar 强制语言、--window 12 设置每行秒数、--out t.txt 保存结果。随后由使用者阅读完整转写，按话题切换点切分章节，每个章节使用该话题起始行的 M:SS 时间；第一章固定为 0:00 并为开场重新命名，第三章数不少于 3 个，相邻章节至少相隔约 10 秒，最后一章必须早于 DURATION。标题要简短、具体、可扫读，使用视频口语语言；阿拉伯语保持自然方言（RTL），不书面化。技术/品牌术语保留拉丁写法以便搜索，如 Claude Code、Next.js、API、GitHub、Vercel、MCP。不得编造转写中不存在的内容。
输出格式：默认按 YouTube 标准，时间在前、每行一章：0:00 标题、0:24 标题、1:05 标题。纯文本输出（除非用户要求否则不加代码围栏），并保存为“<video-title-slug> - youtube chapters.txt”。另有时间放在行尾的变体（标题 0:00），仅在创作者确认其频道可用时采用；0:00 起始、至少 3 行、间隔 ≥10 秒的规则同样适用。YouTube 只在同时满足首行 0:00、至少 3 行、每行比上一行晚至少 10 秒时才显示章节，否则不出现章节。
适用场景：为 YouTube 视频补章节、生成时间轴或分区导航；给本地录制的视频/音频做时间戳；处理已粘贴的转写或 SRT 时可直接跳到切分步骤。
限制：章节划分依赖使用者的判断，工具本身只负责获取转写；转写质量取决于字幕轨或 Whisper 可用选项；不符合首行 0:00、至少 3 章、间隔 ≥10 秒的格式会导致 YouTube 不显示章节；常见错误包括第一章不是 0:00、逐句切章、时间超出视频范围、把阿拉伯语标题书面化、直接引用字幕当标题。