Communitygithub.com

Perso SRT 抽取+翻译 — 字幕源通

用 Perso AI STT 从视频/音频/URL 抽取 SRT,再翻译到目标语言并保留时间轴。免费字幕路径,喂给配音与硬烧出货。

Perso SRT 抽取+翻译 — 字幕源通 是什么?

Video Localization 配方第 1 步(ASR/翻译):perso-dubbing-plugin-srt。视频/URL → 源语言 SRT → 多语翻译 SRT,交给口型配音与中英硬烧。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/perso-ai/perso-dubbing-plugin/tree/HEAD/skills/srt

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

/srt

一个技能,通过 Perso AI STT API 提取视频/音频的源语言字幕——然后由**你(智能体)**将其翻译成请求的语言。

核心规则(必须遵循)

  • 只有工作进程能看到原始密钥。 切勿使用 Read 打开密钥、回显或将其作为命令行参数传递。工作进程仅在 XP-API-KEY 标头中发送它。
  • 一个命令 = 完整的提取过程。 scripts/srt.mjs 自行处理上传、转录和 SRT 下载。
  • 始终在后台运行 srt.mjs。 转录需要几分钟;前台 shell 超时会中途终止运行。
  • 未指定语言 → 目标语言为 en。
  • 仅转录,不翻译(用户要求“原样字幕/转录文本”、“仅原始语言的 SRT”)→ 使用 --transcribe-only 而不是 --target 运行。下载的原始 SRT 就是最终交付物——完全跳过“翻译”部分。
  • 多种语言放在一个命令中 (--target en,ja) — 无论有多少种语言,每个输入都会创建一个字幕项目,并将其单个原始 SRT 翻译成每种语言。
  • 如实传递进度。 将工作进程的 stdout [progress] 行原样或总结后传达给聊天。缩进的 stderr 详细日志无需传达。对于批处理,工作进程为每个输入流式输出一行 [progress],并打印一个 [status] 心跳(subtitles 3/20,附带 next check ~Nm 提示)——在启动后约 3 分钟检查后台输出,然后按提示的间隔检查,传达新行。切勿编造百分比或 ETA。
  • 为遥测命名您的运行时(静默)。 如果可能,在工作进程命令中添加 --host <claude-code|codex|cursor|antigravity|gemini>,指定您正在作为哪个智能体运行。它仅标记使用遥测——切勿向用户展示或询问。如果不确定则省略。
  • 不支持的格式会自动跳过,其余格式继续处理——传达跳过通知。
  • 离线操作永远不需要密钥——切勿为其运行任何密钥检查/注册: srt.mjs --check/--retime,style.mjs 与本地视频 + SRT(除了 --project 之外的所有内容),以及翻译用户交给您的 SRT。
  • 此技能共享配音技能的库:dubbing 文件夹必须与 srt 一起安装(每种安装方法都会一起提供它们;只有手动单独复制 srt 文件夹才会破坏这一点)。

设置(惰性——无需前置步骤)

与 /dubbing 相同——密钥注册不是您首先运行的步骤。 工作进程本身会在需要 Perso API 的命令运行时(提取或 style.mjs --project)进行门控,然后打开浏览器流程(文件回退);传达其打印的指令。在无头/SSH 机器上,它会跳过浏览器流程,自动从文件/--import 注册开始。切勿主动运行密钥检查/注册。切勿将密钥粘贴到聊天中。

运行

收集输入(本地路径或 URL——如果缺失则重新询问)并在后台运行(工作进程在提取实际开始时自行门控密钥):

  • 单个:node scripts/srt.mjs "<文件|URL>" [--target en] [--space "空间名称"] [--out 文件夹]
  • 多语言/多输入:node scripts/srt.mjs "<URL>" "<文件>" --target en,ja
  • 文件夹(批处理):node scripts/srt.mjs "<文件夹>" [--target en] [--recursive] [--out 文件夹]
  • 仅转录(无翻译):node scripts/srt.mjs "<文件|URL>" --transcribe-only

提取的原始 SRT 文件保存在每个源文件旁边(或保存到 --out 指定的文件夹),保留服务器的文件名(…_OriginalSubtitle_….srt)。

保存位置 — 与 /dubbing 相同的策略:默认在每个源文件旁边;无需询问。在会话的第一个任务中,在启动行中说明并立即开始。用户在此会话中之前命名的文件夹将持续应用(--out "<文件夹>"),直到他们更改;翻译后的 SRT 会保存到与其原始文件相同的文件夹。例外:当每个输入都是 URL 时,在开始前询问保存位置。

空间选择 — 如果有多个工作区,工作进程会在上传前停止,打印 [space-select] 行(名称 | (计划) | 剩余积分)并停止。仅向用户展示这些选项(无内部编号),询问选择哪个,然后使用 --space "<空间名称>" 重新运行。如果只有一个支持配音的空间 → 无需询问;PERSO_SPACE_SEQ 会固定选择。

超过计划限制的媒体 — 此技能不会自动分割。如果工作进程报告媒体超过了计划的长度/大小限制,传达其消息:用户可以自行分割/修剪文件或升级计划,然后重试。在免费工作区中,该消息以 [free-limit] 行形式出现(较短的视频或升级——没有继续标志);传达它们并停止。

免费计划(无本地 .srt) — 免费工作区正常转录,但服务器拒绝每次下载,因此不会在本地保存任何内容。工作进程打印 Free plan — <名称>: subtitles ready on Perso → <链接> (downloads need a paid plan) 且没有 [srt-original] 行。没有文件就没有内容可翻译:完全跳过“翻译”部分,将该链接作为已交付的结果传达(运行已完成——未失败,无需恢复),并提及可下载的 .srt 文件需要付费计划。

积分 — 每个字幕项目消耗与媒体长度成比例的积分(每个输入一个项目)。服务器计费是权威的;不要引用确切价格。

翻译(这是您做的部分)

用户直接提供 SRT(无 STT): 没有工作进程步骤,也没有 [srt-original] 行——将给定的 SRT 视为 path,将用户要求的语言视为 langs,然后按编写的方式执行步骤 1-5,从 SRT 自身的文件名中推导出步骤 3 的 {stem}。完全离线:仅 --check/--retime,无密钥,无积分。

当提取完成时,工作进程为每个输入打印一行,包含每个目标语言:

[srt-original] {"input":"video.mp4","langs":["en","ja"],"path":"C:\\clips\\video_OriginalSubtitle_2026-07-15.srt","seq":389259}

如果 langs 为 null(一个 --transcribe-only 运行),则没有内容可翻译:按原样将该文件交付给用户并在此停止。

展示翻译进度。 STT 提取已完成,但翻译成每种语言也需要时间——使其可见。在开始之前,发布一行,说明您将生成的语言(例如“字幕已提取——现在翻译成日语和英语”)。在完成并保存每种语言的文件后,发布一行更新(例如 日语 ✓ (1/2)),以便用户像多语言配音一样看到每种语言的进度。长文件在您批处理其部分时可能在单一语言内保持静默——这没问题。

对于每个 [srt-original] 行,将 path 处的一个文件翻译成 langs 中的每种语言:

步骤 1 — 首先完整读取文件并构建上下文。 在翻译任何内容之前,从头到尾阅读 path 处的 SRT,并确定:

  • 内容是什么(讲座、教程、vlog、戏剧、广告……)以及受众是谁
  • 说话者的语气和语域(正式/随意/幽默/技术性)——并决定与之匹配的目标语言风格
  • 反复出现的名称和术语——在整个文件中为每个名称和术语使用一致的翻译

步骤 2 — 将每种 langs 中的语言分段翻译(批处理长文件,但将步骤 1 中确定的语气和术语应用于每个批次;步骤 1 每个文件执行一次,而不是每种语言):

  • 仅翻译文本行。 保持提示编号、时间戳行(-->)、空行和提示计数完全不变——翻译时切勿更改时间戳或合并/拆分提示(重新计时是单独的后期步骤,步骤 5)。
  • 每个提示的文本保留在其自身提示中。 STT 按说话长度切割源,而不是按语法,因此提示经常在短语中间结束——不要在翻译中模仿该中断。以可读的单元结束每个提示,并使用逗号或连续句子继续。仅在说话者确实被切断或打断时保留片段。
  • 含义和情绪优先:优先选择能传达步骤 1 语气的自然翻译,而不是逐字逐句的翻译。使用目标语言中的等效表达来呈现习语、文字游戏和幽默。
  • 布局——每个提示最多 2 行文本,每行最多 42 个字符(拉丁文字)或 20 个字符(中日韩文字)。 较长的行会被播放器强制换行成 3 行或更多行,覆盖画面。在自然短语边界处换行;如果文本无法容纳,按以下优先级缩短。
  • 保持在每个提示的显示时间内: 预算法则 ≈ 提示持续时间 × 17 字符/秒(拉丁文字)或 9 字符/秒(中日韩文字);超过约 21/秒(13 中日韩文字),字幕会在可读之前消失。自然翻译通常适合,因此大多数提示无需修剪——仅缩短那些溢出的提示。
  • 当必须缩短时,保持此优先级: 含义 → 语气/细微差别 → 长度。首先删除填充词、冗余和重复;最后保留核心信息、妙语和情感表达。如果双关语确实无法容纳,用更短但仍能体现幽默的行替换——将其扁平化为平淡的摘要是最后的手段。

步骤 3 — 保存:UTF-8 编码,在同一文件夹中,每种语言一个文件,命名为 {stem}_{lang}_Subtitle.srt,其中 stem 是输入文件的文件名(不含扩展名)——从 [srt-original] 行的 input 字段获取(例如 "input":"video.mp4" + ["en","ja"] → video_en_Subtitle.srt 和 video_ja_Subtitle.srt;对于 URL 输入,使用媒体标题或简短简称)。不要从下载的文件名中推导 stem——服务器根据项目标题构建该文件名。保留原始 SRT 文件——不要删除或覆盖它。

步骤 4 — 验证每个保存的文件(离线——无密钥,无网络,无积分):

node scripts/srt.mjs --check "<翻译后的.srt>" --source "<原始的 .srt>"

[check] FAIL 行表示文件破坏了提示对齐、2×42 布局或阅读速度上限。仅重写列出的提示(相同的含义优先优先级),保存并重新运行,直到没有 FAIL 剩余。WARN 行是可选的润色。在步骤 5 之前运行此步骤——重新计时后,提示数量故意不再与源匹配。

步骤 5 — 可读性重新计时(离线;每个交付的文件执行一次,在检查通过后):

node scripts/srt.mjs --retime "<翻译后的.srt>"

它会将太快的提示扩展到后续静默中,并将相邻的短提示合并为一个 2 行事件(Netflix 风格),就地重写文件——提示编号可能会更改;未触及的原始 SRT 保留 1:1 时间映射。然后:

  • 缩短其仍列为太快的提示的文本(真正快的说话),并且
  • 对于喜剧/戏剧内容,检查其 [retime] merged 行:如果合并过早展示了妙语或完成了有意中断的行,则从合并前的状态恢复这两个提示及其原始时间。

向用户报告已保存的翻译文件路径,并提及原始文件保留在旁边。如果用户想打开 Perso 上的字幕项目,从 [srt-original] 行的 seq 构建链接:https://perso.ai/en/workspace/vt/stt/<seq>。

样式化与烧录字幕(硬字幕)

可选择使用 scripts/style.mjs 将样式化的字幕轨道烧录到视频上(永久硬字幕)。这是一个本地的 ffmpeg 步骤——无密钥,无积分(除了 --project,它会从 Perso 下载源)。需要 ffmpeg;如果缺失,告诉用户安装并停止。

何时提供(两个入口点):

  • 翻译后: 一旦交付 SRT,提供添加样式化字幕的选项——使用自然的用户面向的措辞,而不是“烧录/硬字幕”。对于几种语言,询问全部或仅部分。
  • 直接请求(视频 + SRT 交给您): 直接进入预设选择。

流程:

  1. 始终首先展示预设——切勿跳过到应用预设。 展示方式取决于界面:
    • Claude 应用(或任何可以渲染交互式小部件的界面): 展示预设画廊——每个预设一个可由用户选择的磁贴,带有应用按钮,将选择作为生成请求发送。在此处优先使用。
    • CLI / Antigravity / Codex / 任何没有交互式渲染的地方(通用回退): 附加 assets/style_presets.png(静态预览)并运行 node scripts/style.mjs --list-presets 获取文本菜单。 两者来自相同的预设。分组为短格式(9:16)/ 长格式(16:9)。用户可以选择一个预设或描述任何样式(例如“黄色文本,黑色轮廓,底部”)。按方向建议默认(竖屏 → 短格式,横屏 → 长格式),但让他们选择。仅在他们选择或描述后应用。
  2. 应用。 在后台运行工作进程(编码需要时间):
    • 从 Perso STT 项目:node scripts/style.mjs --project <seq> --preset <id> [--out 文件夹]
    • 从本地文件:node scripts/style.mjs "<视频>" "<字幕.srt>" --preset <id> [--out 文件夹]
    • 当您烧录的 SRT 来自 Perso STT 提取(一个 [srt-original] 文件或其翻译),添加 --origin perso;对于用户自己提供的字幕文件,省略。仅用于遥测——不会改变输出。
    • 自定义样式: 将用户的描述映射到任何基础预设之上的覆盖标志——--position center|lower|bottom|upper,--font,--fontsize,--primary RRGGBB,--outline RRGGBB,--outline-width,--box RRGGBB@opacity|none,--karaoke/--no-karaoke,--highlight RRGGBB,--uppercase,--bold/--no-bold(参见 --help)。
    • 字体: --font "<名称>" 使用已安装的字体;未安装的名称会自动回退到最接近的系统字体(在相关时提及)。用户提供的字体文件(.ttf/.otf/.ttc)作为 --font-file "<路径>" 传入——从文件本身读取字体系列名称。
    • 多种语言: 每种语言的 SRT 运行一次,使用相同的 --preset,添加 --lang <代码> 以便输出以该语言命名,并使用适合该语言的字体设置。推荐的 --lang 值与用于字幕的语言代码匹配。
    • 批量样式化来自文件夹: node scripts/style.mjs "<视频文件夹>" "<srt 文件夹>" --preset <id> [--recursive] 会将每个视频与其文件名匹配的 SRT 配对。提示计数和语言顺序必须匹配;报告任何不匹配。

编码后: 交付生成的 .mp4 文件路径。不要删除原始视频。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能