OpenCreator KrillinAI Subtitle 技能实战用一条 CLI 命令完成 YouTube / Bilibili / 本地视频的多语言字幕生产【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreator导读本指南围绕 OpenCreator 仓库中krillinai-subtitle技能文档展开讲解如何通过内置 KrillinAI CLI 的subtitle命令从 YouTube 链接、Bilibili 链接或本地视频一键生成原文字幕、目标语言字幕、双语 SRT 与竖屏短字幕四种产物并覆盖平台字幕优先、Whisper 转录兜底、双语顺序控制、字幕样式覆盖、dry-run 校验与 manifest 产物定位等完整实操细节。读完本文你可以独立运行subtitle阶段理解其输出契约JSON、manifest、退出码并知道在 OpenCreator 的 Agent 工作流中该技能是如何被调度与验证的。krillinai-subtitle技能定义位于 skills/krillinai-subtitle/SKILL.md它是 OpenCreator 内置 KrillinAI 创作流水线中负责字幕阶段的核心技能与krillinai-tts配音、krillinai-render-horizontal/krillinai-render-vertical渲染等技能共同组成完整的视频生产链路。一、技能定位在 Agent 流水线中扮演什么角色krillinai-subtitle是一个面向 Agent 的指令型技能skill其 front-matter 声明name: krillinai-subtitle description: Use when generating subtitles with KrillinAI CLI from a YouTube link, Bilibili/local video, or existing media, including platform caption download, Whisper fallback, translation, bilingual SRT, and short vertical subtitle output.它解决的具体问题是当 Agent 拿到一个视频来源URL 或本地路径时如何可靠地得到一套可供后续配音、渲染阶段复用的字幕文件。技能文档明确要求使用该技能前先阅读 skills/krillinai-cli/references/cli-contract.md以获得二进制位置、执行工作目录、配置方式和 JSON 行为等前置知识——这说明subtitle是 KrillinAI CLI 契约体系下的一个阶段命令而不是独立脚本。从 OpenCreator 的 Agent 适配层看subtitle阶段在 apps/daemon/src/creator/krillin/adapter.ts 中被映射为stageType: subtitle允许的输出产物集合为source_video、source_subtitle、target_subtitle、bilingual_subtitle、vertical_subtitle并且会把是否双语目标语言在上还是在下字幕样式等用户状态翻译成 CLI 参数bilingual、bilingualTop、subtitleStyle分别对应--bilingual-top与--subtitle-style-file。二、标准命令与最小可运行示例技能文档给出的标准命令如下(cd $KRILLINAI_CWD $KRILLINAI_CLI subtitle input \ --origin-lang en \ --target-lang zh_cn \ --workdir $WORKDIR \ --caption-source any \ --prepare-video)其中$KRILLINAI_CLI、$KRILLINAI_CWD、$WORKDIR的取值方式在 skills/krillinai-cli/references/cli-contract.md 中有明确约定REPO_ROOT$PWD TARGET$(node -p process.platform - process.arch) SUFFIX$(node -p process.platform win32 ? .exe : ) KRILLINAI_CLI$REPO_ROOT/.runtime/build/krillinai/$TARGET/bin/krillinai-cli$SUFFIX KRILLINAI_CWD$REPO_ROOT/runtime/krillinai WORKDIR$REPO_ROOT/tasks/demo test -f $KRILLINAI_CLI mkdir -p $WORKDIR要点先构建二进制在 OpenCreator 仓库根目录执行pnpm krillinai:build会编译runtime/krillinai/cmd/cli与runtime/krillinai/cmd/server产物写入.runtime/build/krillinai/platform-arch/bin/krillinai-cli[.exe]、krillinai-server[.exe]和manifest.json。执行工作目录CLI 是相对进程工作目录加载config/config.toml的因此源码检出环境下要用runtime/krillinai作为工作目录(cd $KRILLINAI_CWD ...)并从 runtime/krillinai/config/config-example.toml 复制出被 gitignore 的config/config.toml发布包则从解包根目录运行。路径全部使用绝对路径--workdir、输入、字幕、音频、输出路径在更换进程工作目录后都必须显式给出绝对路径。专用任务目录技能与契约文档反复强调每个任务使用独立--workdir产物不要散落到仓库根目录。结合 skills/krillinai-cli/SKILL.md 的最小工作流一个完整演示可以这样串联subtitle与后续的竖屏渲染REPO_ROOT$PWD WORKDIR$REPO_ROOT/tasks/demo mkdir -p $WORKDIR (cd $REPO_ROOT/runtime/krillinai $KRILLINAI_CLI subtitle \ https://www.youtube.com/watch?vVIDEO_ID \ --origin-lang en \ --target-lang zh_cn \ --workdir $WORKDIR \ --caption-source any \ --prepare-video) (cd $REPO_ROOT/runtime/krillinai $KRILLINAI_CLI render-vertical \ --workdir $WORKDIR)render-vertical阶段会直接从 manifest 读取字幕与视频产物无需重复猜测文件名。三、支持的输入类型与平台字幕策略技能文档对三类输入给出了明确指引输入类型写法示例行为说明YouTube 链接https://www.youtube.com/watch?vVIDEO_ID优先--caption-source any先尝试平台字幕失败再回退 Whisper 转录本地视频local:/abs/path/video.mp4使用local:前缀或 CLI 可接受的路径直接进入转录音轨流程Bilibili 或其他 yt-dlp 支持的链接任意 yt-dlp 可下载的 URL平台字幕行为可能因站点而异通常需要回退到转录从源码看YouTube 输入判定在 runtime/krillinai/internal/pipeline/subtitle.go 的IsYouTubeInput函数中实现subtitle.go#L327-L338它解析 URL 的 hostname命中youtu.be、youtube.com、*.youtube.com、youtube-nocookie.com及子域即视为 YouTube 输入。而GenerateSubtitlessubtitle.go#L33-L121的流程清晰地体现了平台字幕优先、转录兜底的分支逻辑PrepareMedia准备媒体来源下载视频或提取音频若输入为 YouTube 且--caption-source不是whisper则尝试DownloadYouTubeSubtitle下载平台 VTT 字幕再经ProcessYouTubeSubtitle解析翻译平台字幕成功时manifest 中caption_source记为youtube_vtt若同时要求了--prepare-video还会调用prepareOriginalMediaForRendering补齐原始视频供渲染阶段使用平台字幕失败时向 manifest 写入警告平台字幕不可用回退到转录然后走GenerateSubtitlesFromAudio的音频转录 翻译路径caption_source记为whisper若用户显式指定了--caption-source whisper强制转录则跳过平台字幕步骤直接转录。CaptionSource的完整取值定义在 runtime/krillinai/internal/pipeline/types.go#L19-L27any、manual、auto、platform、whisper。四、核心 Flags 全解技能文档中的参数表格是实操的核心下面结合 runtime/krillinai/internal/cli/commands.go#L113-L131 中subtitle命令的 help 输出逐项展开Flag用途说明与源码佐证--origin-lang lang源语言如en、zh、ja必填--target-lang lang目标语言如zh_cn必填翻译阶段使用--user-lang lang生成消息的 UI 语言可选源码中默认简体中文LanguageNameSimplifiedChinese见 subtitle.go#L200-L204--workdir dir专用任务目录所有产物与 manifest 的落盘位置必填且建议绝对路径--task-id id任务 ID可选写入 manifest 便于区分多个任务--caption-source source字幕来源策略any平台优先、转录兜底/platform/manual/auto/whisper强制转录默认any--prepare-video为后续渲染准备原视频要求真实产生非空origin_video产物见下方验证章节--source-only只出原文字幕生成源语言字幕不做翻译成功时target_srt、bilingual_srt、short_*会被置空subtitle.go#L269-L275--bilingual-top双语字幕中目标语言放上方CLI 默认truecommands.go#L494对应源码中SubtitleResultTypeBilingualTranslationOnTop / OnBottom二选一--max-word-one-line n每行最大字数可选源码默认defaultSubtitleMaxWordOneLine 12subtitle.go#L15--subtitle-style-file file合并 JSON 字幕样式覆盖文件覆盖文件与默认样式做字段级合并详见第六节--dry-run只校验命令形状不下载、不调用 AI、不写 manifest 与产物见第五节-h, --help显示帮助所有子命令均支持技能文档特别强调的--bilingual-toptrue直接映射到 ASS 字幕的双语排版目标语言在顶部时对应源码中的LineModeBilingualTargetTop否则为LineModeBilingualTargetBottomruntime/krillinai/internal/pipeline/srt.go#L86-L103。五、dry-run零成本校验命令形状subtitle --dry-run用于在真实下载和 AI 调用之前验证命令形状是否合法是 Agent 工作流中的标准前置动作。技能文档明确说明dry-run 会校验命令形状但不会写入 manifest也不会产生任何输出文件。来自 skills/krillinai-cli/references/cli-contract.md 的命令形状校验示例(cd $KRILLINAI_CWD $KRILLINAI_CLI subtitle local:demo.mp4 \ --origin-lang en \ --target-lang zh_cn \ --workdir $WORKDIR \ --dry-run)这个检查不需要 provider 凭证也不需要 ffmpeg / yt-dlp 等媒体依赖适合在 CI 或 Agent 规划阶段快速验证参数拼写。契约文档还给出了各命令 dry-run 行为的差异subtitle、render-horizontal、render-vertical、speech、pipeline的 dry-run 都不写任务 manifest而tts与cover的 dry-run 会写入krillinai_manifest.json但不会产出媒体voices --dry-run只返回本地音色列表不会调用外部 provider。六、配置文件与字幕样式覆盖6.1 主配置config/config.toml真实运行subtitle需要配置转录与翻译服务。参考 runtime/krillinai/config/config-example.toml与字幕阶段直接相关的配置段如下[app] segment_duration 5 # 音频切分处理间隔单位分钟建议值5-10 transcribe_parallel_num 1 # 并发转录数量上限建议值1-3本地模型建议 1 translate_parallel_num 3 # 并发翻译数量上限建议值3TPM 限制严格的 API 可调低 transcribe_max_attempts 3 # 转录最大尝试次数 translate_max_attempts 5 # 翻译最大尝试次数小模型或失败率高可调高 max_sentence_length 70 # 每句最大字符数超过会被拆分建议值50-70 enable_block_vtt_batch false # 是否启用块级 VTT 批量翻译 vtt_batch_size 10 # VTT 批量翻译批次大小 target_language_first true # 双语字幕中目标语言是否在上方 short_subtitle_max_chars 20 # 短字幕每行最大字符数建议值15-25 proxy # 网络代理地址如 http://127.0.0.1:7890 [llm] # 支持所有兼容 OpenAI 请求格式的模型服务 base_url # 自定义 base url留空为 OpenAI 官方 API api_key # API 密钥 model # 指定模型名留空默认为 gpt-4o-mini json false # 所用 LLM 接口是否支持 json 格式 [transcribe] # 视频转文本 provider openai # 可选openai, fasterwhisper, whisperkit, whisper.cpp, aliyun enable_gpu_acceleration false # fasterwhisper GPU 加速50 系显卡务必开启 [transcribe.openai] base_url api_key model whisper-1 [transcribe.fasterwhisper] model medium # 可选tiny, medium, large-v2 [transcribe.whisperkit] model large-v2 [transcribe.whispercpp] model tiny这些[app]参数直接控制subtitle阶段音频转录与字幕翻译的并发度、重试次数、句子切分与双语排版是影响运行时长与成功率的调优入口。例如target_language_first与 CLI 的--bilingual-top效果等价transcribe_parallel_num在使用本地 whisper 模型时建议调为 1。6.2 字幕样式覆盖文件--subtitle-style-file--subtitle-style-file接收一个 JSON 文件其结构与默认样式文件 runtime/krillinai/config/subtitle-style-default.json 一致分为horizontal/vertical两个屏幕方向每个方向下再分major/minor两档样式。关键字段示例{ version: 1, horizontal: { major: { font_name: Arial, font_size: 14, primary_color: #FFBF00, outline_color: #000000, bold: true, outline: 2.5, shadow: 1.5, alignment: 2, margin_l: 10, margin_r: 10, margin_v: 20 } } }从 runtime/krillinai/internal/subtitle_style/style.go 的源码看覆盖机制是字段级合并Mergestyle.go#L96-L112先以默认样式为基底再逐字段覆盖未提供的字段保留默认值文件解析使用DisallowUnknownFields未知字段直接报错并经过Validate校验style.go#L114-L122。校验规则覆盖了颜色格式#RRGGBB/#RRGGBBAA或 ASS 的HAABBGGRR、字号1-200、对齐1-9、描边/阴影0-20等。样式最终会被生成为 ASS 字幕头BuildAssHeader与对话行标签供后续渲染阶段烧录进视频。七、输出产物与 manifest 契约7.1 字幕阶段产物技能文档列出的主要产物文件均在--workdir下文件含义origin_language_srt.srt源语言原文字幕target_language_srt.srt目标语言翻译字幕bilingual_srt.srt双语字幕顺序由--bilingual-top决定short_origin_mixed_srt.srt竖屏短字幕混排供竖屏渲染使用origin_video.mp4当媒体准备产出或--prepare-video要求时出现origin_audio.mp3当转录准备产出音频时出现此外从 manifest.go#L98-L120 的ApplyDefaultOutputs可以看到还会生成short_origin_srt.srt、output/origin_language.txt、output/target_language.txt等配套文件。7.2 读取 manifest 而非猜测文件名真实运行后产物路径一律以krillinai_manifest.json为准。契约文档给出该文件的输出键与默认路径对应表输出键默认路径origin_videoworkdir/origin_video.mp4origin_audioworkdir/origin_audio.mp3origin_srtworkdir/origin_language_srt.srttarget_srtworkdir/target_language_srt.srtbilingual_srtworkdir/bilingual_srt.srtshort_origin_mixed_srtworkdir/short_origin_mixed_srt.srttts_audioworkdir/tts_final_audio.wavvideo_with_ttsworkdir/video_with_tts.mp4horizontal_videoworkdir/horizontal_bilingual.mp4vertical_videoworkdir/vertical_bilingual.mp4transferred_vertical_videoworkdir/transferred_vertical_video.mp4origin_coverworkdir/origin_cover.jpggenerated_coverworkdir/generated_cover.pngcover_promptworkdir/cover_prompt.final.txt横/竖屏配音变体分别使用horizontal_dubbed.mp4、vertical_dubbed.mp4文件名但 manifest 键仍为horizontal_video/vertical_video。manifest 的 JSON 结构定义在 runtime/krillinai/internal/pipeline/manifest.go#L17-L29包含task_id、workdir、input_url、origin_language、target_language、caption_source、outputs、warnings、failed_indexes、stages等字段stages记录每个阶段subtitle、tts、render-horizontal等的ok状态与错误信息。写入采用临时文件 os.Rename的原子替换方式manifest.go#L62-L96避免中途崩溃导致 manifest 损坏。八、输出协议JSON Lines、成功/失败结构与退出码8.1 逐行解析 stdoutCLI 的 stdout 是 JSON Lines 格式需要逐行解析最后一个对象即终态响应。当环境变量OPENCREATOR_KRILLINAI_CLI1时subtitle和tts会在终态响应前先输出进度帧{type:progress,phase:translating_subtitles,percent:50,message:正在翻译字幕}进度帧的phase与percent来自 subtitle.go#L123-L171 的进度上报逻辑整个字幕阶段从preparing_source10%→reading_platform_captions/processing_platform_captions20%-25%→transcribing_audio30%→translating_subtitles40%-75%→collecting_outputs95%Agent 可以据此向用户展示阶段性进度。8.2 成功与失败结构成功响应{ ok: true, stage: subtitle, workdir: tasks/demo, task_id: demo, outputs: {} }失败响应{ ok: false, error: { kind: retryable, code: audio_transcription_failed, message: connection timeout, retryable: true } }error.kind的可选值在 types.go#L39-L44 定义为usage参数或输入问题、retryable可重试、dependency依赖缺失、internal内部错误。retryable为true当且仅当kind retryable。subtitle阶段常见的错误码还包括prepare_media_failed、platform_caption_failed、audio_transcription_failed、source_video_missing--prepare-video要求但未产出原视频时见 subtitle.go#L261-L268等。8.3 退出码退出码含义0成功1参数使用错误2可重试错误3依赖错误注意内部错误目前也以1退出因此分类应以error.kind为准不能只看退出码。错误处理策略usage→ 修正 flags 或缺失输入retryable→ 延迟重试或切换 provider/来源dependency→ 安装或暴露ffmpeg、ffprobe、yt-dlpinternal→ 检查日志与已生成文件。九、验证清单Agent 如何确认字幕阶段成功技能文档给出的验证步骤是 Agent 接管的操作规范终端 JSON 必须ok: true以 stdout 最后一个 JSON 对象为准确认krillinai_manifest.json存在于--workdir下manifest 是阶段真实完成的唯一证据抽查bilingual_srt.srt的双语顺序确认目标语言是否按--bilingual-top的期望位于上方/下方抽查short_origin_mixed_srt.srt的可读性竖屏短字幕的断句与换行是否自然当请求了--prepare-video时要求存在非空origin_video产物若原视频缺失源码会以source_video_missing报可重试错误subtitle.go#L262-L267。此外契约文档补充了两条通用原则以krillinai_manifest.json和实际产物文件为事实来源后续阶段tts、渲染复用 manifest 中的路径而不是猜测文件名避免在 manifest 已有有效上游产物时重复运行昂贵阶段。从 runtime/krillinai/internal/pipeline/srt.go 的源码还可以看到成功保存前会调用validateExistingSubtitleOutputs检查字幕时间线SRT 块按序号、时间戳、文本三行一组解析srt.go#L42-L84并对五类字幕文件做存在性与重叠校验short_origin_mixed_srt.srt允许时间重叠其余不允许见 srt.go#L105-L120。校验失败会以invalid_subtitle_timeline标记阶段失败并写入 manifest。十、从技能文档到 OpenCreator 的完整链路krillinai-subtitle不是孤立的手工命令而是 OpenCreator AI workspace for creators 中模板化创作流水线的一环。理解它需要把它放进三层结构里看技能层skills/krillinai-cli/SKILL.md 是顶层路由技能按用户意图把任务分发给krillinai-subtitle字幕、krillinai-tts配音、krillinai-render-horizontal/krillinai-render-vertical渲染、krillinai-cover封面等子技能skills/krillinai-subtitle/SKILL.md 则是subtitle阶段的专用技能。契约层skills/krillinai-cli/references/cli-contract.md 统一定义构建、路径、命令、manifest、JSON、退出码与错误分类是所有阶段命令共同遵守的接口规范。实现层Go 运行时 runtime/krillinai 内的internal/pipeline字幕管线、internal/cliflag 解析与命令分派、internal/subtitle_style样式合并与 ASS 生成、internal/service平台字幕、转录、翻译服务以及 runtime/krillinai/config/config-example.toml 共同承载实际能力OpenCreator Daemon 侧的 apps/daemon/src/creator/krillin/adapter.ts 则负责把创作任务状态翻译为 CLI 参数并校验输出产物。技能文档中 skills/krillinai-cli/references/cli-contract.md 还特别提醒在 OpenCreator 中运行时Daemon 会准备隔离的 launcher 目录和配置不要用源码树里的配置替代这条自动化流程同时不要声称cover使用了参考图当前 CLI 只接受完整文本提示词与尺寸也不要向voices请求 Edge TTS 音色目录目前仅支持aliyun、openai、minimax。这些约束保证了 Agent 在真实 OpenCreator 环境下的行为与手工 CLI 调用保持一致。结语krillinai-subtitle技能把从任意视频来源到多语言字幕产物这一复杂流程收敛为一条可预测、可验证、可复用的 CLI 契约输入侧兼容 YouTube 平台字幕优先 Whisper 转录兜底输出侧用krillinai_manifest.json统一登记四类 SRT 与媒体产物交互侧用 JSON Lines、ok终态与error.kind分类保证 Agent 可编程接管dry-run 与命令形状校验则让错误在产生成本之前就被发现。无论是手工在终端调试还是让 Agent 在 OpenCreator 流水线中编排本文给出的命令、参数表、配置说明与验证清单都可以直接照做。延伸阅读构建与二进制定位见 skills/krillinai-cli/references/cli-contract.md命令路由见 skills/krillinai-cli/SKILL.md转录与翻译配置见 runtime/krillinai/config/config-example.toml字幕管线实现见 runtime/krillinai/internal/pipeline/subtitle.go 与其配套的 subtitle_test.go。【免费下载链接】OpenCreatorFormerly KrillinAI. Open-source AI workspace for creators, powered by Codex. Create videos, images, voice, avatars, translations, and edits with Agents in one place.项目地址: https://gitcode.com/GitHub_Trending/kr/OpenCreator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考