OpenMontage 中 HeyGen 视频字幕完全指南：自动字幕配置、SRT 多语言翻译与无障碍实践

OpenMontage 中 HeyGen 视频字幕完全指南：自动字幕配置、SRT 多语言翻译与无障碍实践

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

导读

本指南以 OpenMontage 仓库内 HeyGen 技能包的字幕参考文档（.claude/skills/heygen/references/captions.md）为主体，系统讲解 HeyGen 数字人视频的自动字幕（Captions）能力：从caption开关到字体、字号、颜色、位置等样式定制，从多语言字幕到自定义 SRT 翻译输入，再到 TikTok、YouTube、LinkedIn 等平台的适配策略与无障碍最佳实践。读完本文，你将掌握在 HeyGen/v2/video/generate与 Video Agent 工作流中为 AI 虚拟人视频一键生成专业字幕的完整方案，并能结合 OpenMontage 仓库中的 Remotion 字幕烧录工具与字幕生成技能实现"HeyGen 生成 → 本地字幕增强"的闭环流水线。

文档定位：在 OpenMontage 中，.claude/skills/heygen/SKILL.md标注该技能包已标记为DEPRECATED，其工作流已被更聚焦的create-video（基于 Prompt 的 Video Agent API）与avatar-video（基于 v2 API 的精确头像/场景控制）取代。但字幕能力在上述两条新工作流中依然是标准配置项，本参考文档（captions.md）的技术细节对二者同样适用。

一、什么是 HeyGen 自动字幕

HeyGen 可以在生成数字人视频时自动生成字幕（Captions / Subtitles）。与手工在剪辑软件里逐句敲字幕不同，自动字幕由平台基于语音内容直接产出，主要带来两类收益：

• 可访问性（Accessibility）：让听障/重听观众也能完整获取视频信息；
• 参与度（Engagement）：大量用户（尤其是移动端、静音刷屏场景）依赖字幕理解内容，带字幕的视频完播率更高。

在 OpenMontage 的语境中，HeyGen 被用作头像数字人视频（Talking-head / 讲解视频 / 演示视频）的云端生成引擎，对应的工具封装位于 tools/video/heygen_video.py。该工具的supports声明中native_audio为False、cloud_generation为True，即字幕与音频均依赖云端能力，而字幕正是提升这类纯云端产出视频信息密度的关键一环。

二、开启字幕：caption字段

字幕可以在生成视频时通过配置开启。在/v2/video/generate请求中，caption是一个顶层字段（非video_inputs内部字段），与dimension、title、test等平级，其类型为布尔值，表示"是否启用自动字幕"。

最小开启示例：

const videoConfig = { video_inputs: [ { character: { type: "avatar", avatar_id: "josh_lite3_20230714", avatar_style: "normal", }, voice: { type: "text", input_text: "Hello! This video will have automatic captions.", voice_id: "1bd001e7e50f421d891986aad5158bc8", }, }, ], // Caption settings (availability varies by plan) caption: true, };

要点说明：

• character.type目前支持"avatar"（数字人）与"talking_photo"（照片说话人）两种类型，字幕对二者均可启用；
• voice.type: "text"表示使用文本转语音（TTS），字幕即根据这段input_text的语音生成；若使用"audio"类型（上传自定义音频）或"silence"类型，字幕生成行为会因语音来源不同而有所差异；
• 官方注释明确提示"availability varies by plan"：字幕样式等高级能力与订阅套餐相关，接入时应先确认当前账号套餐支持范围（详见下文"局限性"一节）。

在 OpenMontage 的参考文档 .claude/skills/heygen/references/video-generation.md 中，caption也被列入/v2/video/generate顶层请求字段表：

开发建议：联调阶段建议同时开启test: true（输出带水印、不消耗积分），避免反复生成消耗配额。配额体系的具体规则参见参考文档 .claude/skills/heygen/references/quota.md。

三、字幕配置项：CaptionConfig

当caption不再满足于"开/关"这种二元控制时，可以传入对象形式的完整配置。参考文档给出了CaptionConfig接口：

interface CaptionConfig { // Enable/disable captions enabled: boolean; // Caption style style?: { font_family?: string; font_size?: number; font_color?: string; background_color?: string; position?: "top" | "bottom"; }; // Language for caption generation language?: string; }

字段逐项解析：

• 当仅需默认样式时，直接写caption: true即可，平台会用默认样式渲染；
• 当需要自定义样式时，使用caption: { enabled: true, style: {...} }对象形式，二者不能混用（对象形式下enabled仍需显式置true）；
• language字段用于覆盖字幕语言；不传时，字幕语言跟随语音语言（详见第五节"多语言字幕"）。

四、字幕样式：从基础到自定义

4.1 基础字幕（默认样式）

只需要字幕、不关心外观时，最小配置：

const config = { video_inputs: [...], caption: true, // Enable with default styling };

video_inputs数组内仍是标准的character+voice（+ 可选background）结构，可参考 .claude/skills/heygen/references/video-generation.md 中的多场景（Multi-Scene）示例：一个video_inputs数组元素即一个场景，字幕会贯穿全部场景生成。

4.2 自定义样式字幕

const config = { video_inputs: [...], caption: { enabled: true, style: { font_family: "Arial", font_size: 32, font_color: "#FFFFFF", background_color: "rgba(0, 0, 0, 0.7)", position: "bottom", }, }, };

这是一套典型的"白字 + 半透明黑底 + 底部"组合：rgba(0, 0, 0, 0.7)提供了 70% 不透明度的深色背景条，能在任何画面上保证文字可读性，同时不会完全遮挡画面内容。

样式设计的三条核心原则：

1. 对比度优先：深底白字或浅底深字，避免中灰背景上出现灰色文字；
2. 字号与画幅匹配：1080p 视频建议 32px 起；手机竖屏（9:16）建议更大字号（见第八节社交平台考量）；
3. 背景半透明：全不透明背景会形成硬色块，半透明（如0.5–0.9）兼顾可读性与画面观感。

五、多语言字幕：跟随语音语言生成

对于不同语言的视频，字幕会基于语音的语言自动生成。也就是说：语音是什么语言，自动字幕就是什么语言，无需单独指定language字段。

西班牙语视频配西班牙语字幕的示例：

// Spanish video with Spanish captions const spanishConfig = { video_inputs: [ { character: { type: "avatar", avatar_id: "josh_lite3_20230714", avatar_style: "normal", }, voice: { type: "text", input_text: "¡Hola! Este video tendrá subtítulos en español.", voice_id: "spanish_voice_id", }, }, ], caption: true, };

注意：示例中的voice_id: "spanish_voice_id"为占位符。实际使用时需先通过语音列表接口查询对应语种（locale）的voice_id，参见参考文档 .claude/skills/heygen/references/voices.md。

由此可以推导出多语言批量生产的通用模式：

• 每种语言维护一份{ input_text, voice_id }映射；
• 依次调用生成接口，每份请求都带上caption: true；
• 生成结果即为"对应语言的数字人口播 + 对应语言的自动字幕"。

这一模式与 OpenMontage 仓库中的本地化配音流水线（localization-dub管线的技能目录位于 skills/pipelines/localization-dub）配合使用，可组成"HeyGen 多语言口播 + 字幕"的一站式本地化方案。

六、SRT 文件：格式与自定义输入

6.1 SRT 标准格式

SRT（SubRip Text）是行业标准的字幕交换格式，其结构为"序号 + 时间轴 + 文本"的重复块，时间轴格式为HH:MM:SS,mmm --> HH:MM:SS,mmm：

1 00:00:00,000 --> 00:00:03,000 Hello! This video will have 2 00:00:03,000 --> 00:00:06,000 automatic captions generated. 3 00:00:06,000 --> 00:00:09,000 They sync with the audio.

格式要点：

• 序号从 1 开始递增；
• 时间戳中毫秒用逗号分隔（而非小数点）；
• 文本可跨行（一个字幕块可含多行文本）；
• 块与块之间以空行分隔。

6.2 使用自定义 SRT：视频翻译场景

在进行视频翻译时，可以传入自己的 SRT 文件来控制字幕内容与翻译方向：

const translationConfig = { input_video_id: "original_video_id", output_languages: ["es-ES", "fr-FR"], srt_key: "path/to/custom.srt", // Custom SRT file srt_role: "input", // "input" or "output" };

参数语义：

提示：output_languages使用带地区码的格式（如es-ES西班牙（西班牙）、fr-FR法语（法国）），这与语音列表接口中的 locale 字段风格一致。

6.3 仓库内的字幕生成配套

如果你不希望完全依赖平台的自动字幕，OpenMontage 仓库提供了本地生成/处理字幕的完整配套，可作为 SRT 的生产上游：

• tools/subtitle/subtitle_gen.py：字幕生成工具；
• skills/core/whisperx.md：基于 WhisperX 的转写与对齐技能（含时间戳级精度）；
• skills/core/subtitle-sync.md：字幕时间轴同步技能。

典型链路为：WhisperX 转写 → 生成 SRT → 校验时间轴 → 作为srt_key传入 HeyGen 翻译接口，实现完全可控的字幕生产。

七、字幕位置：底部与顶部

7.1 底部（默认）

底部是绝大多数视频的标准字幕位置：

caption: { enabled: true, style: { position: "bottom" } }

适用场景：常规横屏讲解、演示视频、访谈类内容——观众的阅读习惯是从上到下扫视画面，底部字幕符合主流视频平台的默认排版（YouTube、B 站等均默认底部）。

7.2 顶部

当视频底部区域被其他内容占据时（例如底部有品牌条、进度条、Logo、人物关键手势，或竖屏底部被平台 UI 遮挡），应切换为顶部：

caption: { enabled: true, style: { position: "top" } }

适用场景：TikTok/Instagram Reels 等底部常被点赞、评论、分享按钮遮挡的竖屏平台（详见第八节）。

八、无障碍最佳实践

参考文档给出了 5 条经过实践检验的字幕无障碍准则：

1. 始终开启字幕（Always enable captions）—— 提升听障/重听观众的可访问性，同时服务大量静音观看场景；
2. 高对比度（Use high contrast）—— 白字深底或深字浅底，避免低对比配色；
3. 可读字号（Readable font size）—— 标准视频至少 24px，移动端应更大（参考文档在社交媒体一节建议 42px 以上）；
4. 不遮挡关键内容（Don't cover important content）—— 字幕位置应避开关键视觉元素（尤其是数字人的嘴部与面部）；
5. 时间轴精准（Sync timing）—— 确保字幕与音频时间严格对齐，错位字幕比没有字幕更影响体验。

这 5 条准则同样适用于 OpenMontage 的 remotion-composer/src/components/CaptionOverlay.tsx 组件——仓库内的本地字幕渲染组件同样采用高对比、可配置字号、可配置位置的实现（默认白色#F8FAFC文字 + 琥珀色#FBBF24高亮 + 半透明黑底rgba(0, 0, 0, 0.6)），与上述无障碍原则完全一致。

九、字幕辅助函数与预设

为便于在代码中复用字幕样式，参考文档提供了一个预设注册表 + 工厂函数的辅助实现。先定义样式接口：

interface CaptionStyle { font_family: string; font_size: number; font_color: string; background_color: string; position: "top" | "bottom"; }

然后内置四套开箱即用的预设：

const captionPresets: Record<string, CaptionStyle> = { default: { font_family: "Arial", font_size: 32, font_color: "#FFFFFF", background_color: "rgba(0, 0, 0, 0.7)", position: "bottom", }, minimal: { font_family: "Arial", font_size: 28, font_color: "#FFFFFF", background_color: "transparent", position: "bottom", }, bold: { font_family: "Arial", font_size: 36, font_color: "#FFFFFF", background_color: "rgba(0, 0, 0, 0.9)", position: "bottom", }, branded: { font_family: "Roboto", font_size: 30, font_color: "#00D1FF", background_color: "rgba(26, 26, 46, 0.9)", position: "bottom", }, };

四套预设的适用场景：

工厂函数按预设名一键生成完整配置：

function createCaptionConfig(preset: keyof typeof captionPresets) { return { enabled: true, style: captionPresets[preset], }; }

用法示例：

const config = { video_inputs: [...], ...createCaptionConfig("bold"), // 直接得到 { enabled: true, style: { ... } } };

该"预设 + 工厂"模式与 OpenMontage 仓库中 tools/video/_shared.py 的做法一脉相承：后者同样通过HEYGEN_PROVIDERS提供多提供方（VEO、Sora、Kling、Runway、Seedance 等）的预设元数据，并用estimate_quality_cost/estimate_speed_runtime等工厂函数按预设生成成本与耗时估算（见 tools/video/heygen_video.py 的estimate_cost/estimate_runtime实现）。

十、社交媒体平台的字幕适配

不同平台的 UI 遮挡区域与观看习惯差异巨大，字幕策略需要按平台定制。

10.1 TikTok / Instagram Reels（竖屏短视频）

• 字幕放在画面居中或偏上位置：底部 20% 区域会被点赞、评论、分享、作者信息等 UI 元素遮挡；
• 避免底部 20%：这是平台 UI 的重灾区，字幕放这里会被盖住；
• 使用更大字号：手机观看、屏幕小、观看距离近，大字号才能保证可读。

const socialCaptions = { enabled: true, style: { font_size: 42, position: "top", // Avoid bottom UI elements }, };

10.2 YouTube

• 标准底部字幕即可良好工作（YouTube 播放器的字幕安全区就在底部）；
• YouTube 还支持上传封闭字幕（closed captions）：如果希望观众可开关、可搜索，可在 YouTube Studio 中上传 SRT 文件，而非烧录进画面。

10.3 LinkedIn

• 强烈建议开启字幕：大量 LinkedIn 用户在办公室/通勤场景静音观看；
• 偏好专业样式：建议使用default或branded预设，避免过于花哨的配色，与职场内容调性一致。

十一、局限性

自动字幕并非万能，参考文档明确列出以下限制：

• 字幕样式受订阅套餐限制：不同 tier 可用的样式能力不同，style中的部分字段可能在高阶套餐才可用；
• 部分高级字幕功能可能仅限网页端：API 暴露的能力是网页端功能的子集，某些高级特性（如逐字高亮、自定义动画）需在 HeyGen 网页编辑器中完成；
• 多说话人字幕检测可用性有限：多人对话场景下，自动区分说话人的能力可能不可用或表现受限；
• 字幕准确率取决于音频质量与语音清晰度：背景噪音、口音、语速都会影响 ASR（自动语音识别）的准确率，生成后应人工抽检关键片段。

对应到工程实践，建议对平台自动字幕做质量兜底：将最终视频 + 字幕文件送入 tools/video/remotion_caption_burn.py（Remotion 字幕烧录工具），或按 skills/core/whisperx.md 的流程用 WhisperX 重新转写校对，保证交付级准确率。

十二、与视频翻译的集成

使用视频翻译功能时，字幕会被自动处理：

// Video translation includes caption generation const translationConfig = { input_video_id: "original_video_id", output_languages: ["es-ES"], // Captions generated in target language };

即：指定output_languages后，平台会为目标语言重新生成语音，并自动附带目标语言的字幕——翻译与字幕是一次请求内完成的原子操作，无需二次配置caption。

两种字幕来源的配合策略：

关于视频翻译的更多细节，参考文档末尾原链接指向video-translation.md，该文件未包含在当前仓库的 reference 目录中（可用的参考文件完整列表见 .claude/skills/heygen/references），本文档基于现有仓库内容进行说明。

十三、完整实战链路：把字幕能力接入 OpenMontage 流水线

综合上述所有能力，一条可落地的"HeyGen 数字人字幕视频"生产链路如下：

1. 生成：调用/v2/video/generate（或 Video Agent 的/v1/video_agent/generate），在请求中带上caption: { enabled: true, style: captionPresets.default }，配好dimension与多场景video_inputs（多场景写法参见 .claude/skills/heygen/references/video-generation.md）；
2. 状态轮询：通过/v2/videos/{video_id}轮询直至status === "completed"，获取video_url（轮询模式细节参见 .claude/skills/heygen/references/video-status.md）；
3. 多语言扩展：如需本地化，以源视频video_id发起翻译请求，传output_languages批量产出多语言字幕版本；
4. 质量兜底（可选）：将关键成片送入 tools/video/remotion_caption_burn.py，该工具会把词级转写片段转换为 RemotionWordCaptionJSON 并通过 remotion-composer/src/components/CaptionOverlay.tsx 渲染逐词高亮字幕（等价于 TikTok 风格的字幕动画）；若 Remotion 不可用，则自动回退到 FFmpegsubtitles滤镜烧录底部字幕；
5. 发布前检查：对照第八节无障碍准则做最终走查——对比度、字号、位置遮挡、时间轴同步。

环境前置：以上所有 HeyGen API 调用均需HEYGEN_API_KEY环境变量（设置方式见 .claude/skills/heygen/references/authentication.md）。OpenMontage 的heygen_video工具同样以该环境变量作为可用性判断依据（见 tools/video/heygen_video.py 的get_status方法）。

结语

自动字幕是 HeyGen 数字人视频"开箱即用"的高价值特性：一行caption: true即可获得可访问、提参与度的成片字幕；通过CaptionConfig的样式与位置定制、多语言跟随、自定义 SRT 输入，又能满足品牌化、本地化、多平台分发的专业需求。结合 OpenMontage 仓库中的 Remotion 逐词高亮字幕烧录、WhisperX 转写校对等配套能力，你可以构建一条从"云端生成"到"本地增强"的完整字幕生产流水线，让数字人视频的每一句话都清晰可读、处处可及。

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage