OBS Studio 如何为 Hybrid MP4/MOV 录制添加章节标记？

在 OBS Studio 中，如果你希望一段 MP4/MOV 录制文件在播放器或剪辑软件里带有可跳转的章节点（chapter），需要满足两个前提：录制容器选为 Hybrid MP4 或 Hybrid MOV，并且通过快捷键或前端 API 在录制过程中插入标记。这个能力由前端 API obs_frontend_recording_add_chapter 提供，从 30.2 版本开始可用（见 docs/sphinx/reference-frontend-api.rst）。本文说明如何配置录制格式、插入标记，以及从哪里确认标记已经生效。

一、把录制格式设为 Hybrid MP4/MOV

章节标记只对 MP4/MOV 文件输出中的 Hybrid 容器生效，其他格式（MKV、FLV、非 Hybrid 的 MP4/MOV 等）会直接返回失败。

在「设置 → 输出」的录制格式（Recording Format）下拉框中选择：

• Hybrid MP4 (.mp4)
• Hybrid MOV (.mov)

这两个选项同时出现在简单输出和高级输出的格式列表中，对应的值为 hybrid_mp4 / hybrid_mov（注册位置见 frontend/settings/OBSBasicSettings.cpp）。新建配置时默认容器通常就是 Hybrid 格式：源码中 macOS 定义为 hybrid_mov，其他平台定义为 hybrid_mp4（见 frontend/widgets/OBSBasic.cpp），所以可能不需要手动更改，以你当前「输出」页的实际显示为准。

二、插入章节标记的两种方式

方式 1：使用内置快捷键（无需编程）

OBS 为这个功能注册了专用快捷键，快捷键 ID 为 OBSBasic.AddChapterMarker，界面上显示的名称是：

Add Chapter Marker (Hybrid MP4/MOV only)

名称里的 "Hybrid MP4/MOV only" 即来源文档给出的适用限制（英文文案见 frontend/data/locale/en-US.ini）。在快捷键设置里为它指派按键后，录制过程中按下该键即插入一个标记。该快捷键的回调传入的名称参数是 nullptr，因此通过快捷键插入的章节会自动生成名称 Unnamed 1、Unnamed 2……（编号自增，见 plugins/obs-outputs/mp4-output.c 中未命名章节的生成逻辑）。快捷键的注册与回调见 frontend/widgets/OBSBasic_Hotkeys.cpp。

方式 2：调用前端 API 插入自定义名称

如果需要指定章节名，通过前端 API 调用：

bool obs_frontend_recording_add_chapter(const char *name);

声明位于 frontend/api/obs-frontend-api.h，文档语义（docs/sphinx/reference-frontend-api.rst）：

• name 为章节名；传 NULL 时使用自动生成的名称（"Unnamed " 或对应本地化文本）；
• 返回 true 表示插入成功；
• 返回 false 的三种情况：录制未激活、录制处于暂停中、当前输出不支持章节插入。

调用示例（返回值语义按文档原样处理，不自行扩展成功判定）：

if (obs_frontend_recording_add_chapter("Intro")) {
    // 插入请求已被接受
} else {
    // 录制未激活、暂停中，或当前输出格式不支持章节
}

OBS 前端的实现先检查录制状态，再通过输出对象的 proc handler 调用 MP4 输出注册的 add_chapter 过程，其中 chapter_name 即你传入的名称（见 frontend/OBSStudioAPI.cpp 与 plugins/obs-outputs/mp4-output.c 中注册的 void add_chapter(string chapter_name)）。

三、标记如何写入文件，在哪里验证

插入成功后，标记不是立刻写进文件的，源码给出了明确的落盘时机：

1. 入队：标记与当前视频帧时间戳一起入队（mp4-output.c）。

2. 对齐到视频帧：当某个视频包的画面时间追上标记时间戳时，章节才真正提交给 muxer，此时 OBS 日志会输出一行形如以下的记录：

   Adding chapter "Intro" at 00:01:23.456
   

   这是 mp4-output.c 中 info 日志的实际格式，HH:MM:SS.mmm 为该章节在录制中的时间位置。查看 OBS 日志中出现这一行，是插入后最直接的即时反馈。

3. 自动补 "Start" 章节：章节轨道要求从时间 0 开始；如果你第一个标记插在 t=0 之后，muxer 会自动在 0 处补一个名为 Start 的章节（见 plugins/obs-outputs/mp4-mux.c，Start 文案来自输出模块的本地化定义）。

4. 最终落盘：章节包只在输出最终 flush 时才写入文件（mp4-mux.c 中 "Only write chapter packets on final flush" 的处理路径）。因此停止录制、文件完成后，章节轨道才完整存在于该 MP4/MOV 文件中；录制过程中你无法靠重新打开文件来核对。

四、限制与边界

• 格式限制：只有 Hybrid MP4/MOV 录制的输出注册了 add_chapter 过程；其余格式调用 API 会得到 false，这是文档定义的「当前输出不支持」情形，不是错误。
• 状态限制：录制未开始或处于暂停时，API 直接返回 false，标记不会入队。
• 快捷键只有自动命名：内置快捷键固定传入 nullptr，产生 Unnamed N 名称；需要自定义章节名时必须走 API 调用。
• 验证依据：即时验证看 OBS 日志的 Adding chapter "<名称>" at ... 行与 API 返回值；文件层面的章节在录制停止后的成品文件中体现。

完成一次插入后，若日志中看不到上述 Adding chapter 行且返回值为 false，优先检查录制格式是否为 Hybrid MP4/MOV、录制是否处于活动且未暂停状态。