/byted-kickart-video-subtitler

name: byted-kickart-video-subtitler
description: 视频字幕添加SKILL：为视频文件自动添加、嵌入字幕。适用于给视频添加字幕、视频加字幕、视频打字幕、给视频生成字幕、字幕嵌入视频、视频配字幕等场景。触发时机：当用户提及或表达等价意图（帮我给视频添加字幕、给视频加字幕、视频打字幕、给视频生成字幕、添加字幕到视频、视频配字幕、字幕嵌入视频）时，调用此SKILL执行字幕添加任务。
version: 1.0.10

视频字幕添加SKILL

📋 工具说明

核心功能

为本地视频文件添加字幕。

使用限制

| 限制项 | 限制值 | 说明 | |--------|--------|------| | 字幕总字数 | ≤3000字 | 字幕文本内容（不含标点符号）不得超过3000字 |

可用命令

| 命令 | 功能 | 说明 | |------|------|------| | `python3.12 scripts/plan.py` | 套餐查询 | 查询用户当前的 Ark Claw 套餐 | | `python3.12 scripts/upload.py --file <视频路径>` | 视频上传 | 上传本地视频文件获取媒资ID | | `python3.12 scripts/subtitler.py --media-id <媒资ID> --captions <字幕配置文件> --output <输出文件>` | 视频字幕添加 | 为视频添加字幕 |

📝 字幕配置文件生成规则

配置文件格式

字幕配置文件为JSON格式，包含一个字幕对象数组。单个字幕对象结构如下：

| 字段 | 类型 | 说明 | |------|------|------| | `text` | string | 完整的字幕文本内容 | | `start_time` | number | 字幕开始显示时间（毫秒） | | `end_time` | number | 字幕结束显示时间（毫秒） | | `words` | array | 字级时间戳数组，包含每个字的详细时间信息 | | `attribute` | object | 字幕属性（预留字段，默认为空对象） |

时间分配规则（符合人类朗读习惯）

**基础规则：**

• **单字时长**：中文正常语速约为每秒4-5字，即每个汉字约200-250毫秒
• **标点处理**：标点符号持续时间为0毫秒，立即显示后进入停顿
• **意群停顿**：逗号、句号等标点后设置300毫秒停顿，符合人类朗读习惯
• **词间间隔**：词语之间设置20毫秒微小间隔，提升可读性
• **结尾延长**：最后一个字适当延长显示时间，确保完整阅读

**生成步骤：**

1. **确定字幕总数**：根据视频时长和内容复杂度，合理划分字幕段落 2. **分配时间范围**：确保各字幕之间不重叠，段落间至少保留300毫秒间隔 3. **计算单字时长**：`(end_time - start_time - 标点停顿时间) / 汉字数量` 4. **生成字级时间戳**：按顺序为每个字分配时间，标点使用0毫秒时长 5. **添加意群停顿**：在标点后插入适当停顿时间

**示例计算：**

对于字幕"足力健老人鞋，专为爸妈设计"（13个字符，含1个标点）：

• 总时长：3190毫秒（5000-1810）
• 汉字数：12个
• 单字平均时长：约220毫秒
• 标点停顿：300毫秒

{
  "text": "足力健老人鞋，专为爸妈设计",
  "start_time": 1810,
  "end_time": 5000,
  "words": [
    {"text": "足", "start_time": 1810, "end_time": 2000, "attribute": {}},
    {"text": "力", "start_time": 2000, "end_time": 2180, "attribute": {}},
    {"text": "健", "start_time": 2180, "end_time": 2380, "attribute": {}},
    {"text": "老", "start_time": 2380, "end_time": 2580, "attribute": {}},
    {"text": "人", "start_time": 2580, "end_time": 2790, "attribute": {}},
    {"text": "鞋", "start_time": 2810, "end_time": 3030, "attribute": {}},
    {"text": "，", "start_time": 3030, "end_time": 3030, "attribute": {}},
    {"text": "专", "start_time": 3330, "end_time": 3550, "attribute": {}},
    {"text": "为", "start_time": 3570, "end_time": 3790, "attribute": {}},
    {"text": "爸", "start_time": 3810, "end_time": 4030, "attribute": {}},
    {"text": "妈", "start_time": 4050, "end_time": 4270, "attribute": {}},
    {"text": "设", "start_time": 4290, "end_time": 4510, "attribute": {}},
    {"text": "计", "start_time": 4530, "end_time": 5000, "attribute": {}}
  ],
  "attribute": {}
}

**注意事项：**

• 字幕之间至少保留300毫秒间隔
• 首条字幕建议在视频开始后500毫秒开始
• 末条字幕建议在视频结束前1000毫秒结束
• 避免单条字幕过长（建议不超过15个汉字）

---

🚨 强制前置校验流程（必须按顺序执行，任意不通过直接终止流程）

所有用户请求必须先完成以下3步校验，不得跳过：

1. 火山鉴权校验

• 执行环境变量检查命令：

  echo "ACCESS_KEY_ID: $ACCESS_KEY_ID" && echo "SECRET_ACCESS_KEY: $SECRET_ACCESS_KEY"

• 判断鉴权结果：
• **鉴权通过**：`ACCESS_KEY_ID` 和 `SECRET_ACCESS_KEY` 均为非空值 → 鉴权通过
• **鉴权不通过**：执行以下引导方案

❌ 鉴权未配置时的引导方案

1. 引导用户直接在聊天中发送ACCESS_KEY_ID/SECRET_ACCESS_KEY内容： > 请你提供火山账号AK&SK，用于检查火山创作Agent是否已开通套餐和有可用的创点 2. 收到用户发送的ACCESS_KEY_ID/SECRET_ACCESS_KEY后，执行配置命令：

   export ACCESS_KEY_ID=用户提供的ACCESS_KEY_ID值
   export SECRET_ACCESS_KEY=用户提供的SECRET_ACCESS_KEY值

3. 配置完成后告知用户： > 已完成ACCESS_KEY_ID/SECRET_ACCESS_KEY临时配置，当前配置仅在本次会话生效，不会持久化存储，请放心使用 4. 后续所有相关脚本执行时，均会自动通过`export`指定这两个环境变量，确保鉴权正常，无需用户重复配置

2. 套餐有效性校验

• **步骤1：Python版本校验**

  python3.12 --version || (echo "❌ Python 3.12+ 未安装，请先安装Python 3.12" && exit 1)

• **步骤2：依赖包安装校验**

  python3.12 -m pip install -r ./scripts/requirements.txt

• **步骤3：执行套餐查询命令**

  python3.12 -m scripts/plan.py

• **步骤4：结果处理逻辑**
• ✅ **套餐有效**：返回结果中的 `message` 字段为有效截止时间（北京时间），校验通过
• ❌ **套餐已过期**：`message` 小于等于当前时间，引导用户开通套餐，终止流程
• ❌ **接口调用错误**：参考「错误处理规范」匹配错误码，向用户明确告知错误原因和解决方案，并且终止流程

3. 技能版本校验

• **步骤1：执行版本检查命令**

  python3.12 -m scripts/upgrade.py

• **步骤2：解析返回结果**

返回格式示例：

  {"code":"0","message":"success","data":"{\"install_command\":\"\",\"latest_version\":\"1.0.0\",\"latest_version_number\":100000000,\"update_message\":\"\"}"}

• `latest_version`：最新版本号（如 "1.0.0"）
• `install_command`：新版本安装指令
• **步骤3：版本对比逻辑**
• ✅ **当前版本 >= 最新版本**：版本校验通过，继续后续流程
• ⚠️ **当前版本 < 最新版本**：执行以下更新询问流程

1. 询问用户是否更新到最新版本： > 检测到技能有新版本 {latest_version}，是否更新？（是/否） 2. 用户确认更新（是）：执行 `install_command` 安装新版本 3. 用户不更新（否）：跳过更新，继续后续流程

---

🛠️ 视频字幕添加执行流程

完整流程概览

用户请求 → 强制前置校验 → 用户输入收集 → 视频字幕添加 → 结果返回

前置准备

1. 确保输出目录存在：`mkdir -p /tmp/openclaw/byted-kickart-video-subtitler/output` 2. 生成唯一输出文件名：`video_subtitle_<timestamp>_<random>.json`

执行步骤

1. **步骤0：强制前置校验**（必须按顺序执行，任意不通过直接终止流程）

• 执行「🚨 强制前置校验流程」中的所有校验步骤
• ✅ 火山鉴权校验通过
• ✅ 套餐有效性校验通过
• ✅ 技能版本校验通过
• 只有全部校验通过后，才能进入下一步

2. **步骤1：视频上传引导**

• 询问用户：「请提供您要添加字幕的视频，可以是本地文件路径或视频公网URL。视频时长不能超过10分钟。」
• 支持两种上传方式：
• **本地文件**：直接提供本地视频文件的绝对路径（如 `/Users/user/video.mp4`）
• **公网URL**：提供可直接访问的视频链接（如 `https://example.com/video.mp4`）
• **不收集字幕内容**：字幕收集在步骤5专门处理

3. **步骤2：视频预处理**

• 若用户提供的是公网URL，先下载到本地：

     mkdir -p /tmp/openclaw/byted-kickart-video-subtitler/input
     curl -L -o /tmp/openclaw/byted-kickart-video-subtitler/input/downloaded_video.mp4 "<视频URL>"

• 检查文件是否存在：`ls -la "<视频路径>"`
• 检查文件类型是否为有效视频（仅支持MP4/MOV格式）：

     file /tmp/openclaw/byted-kickart-video-subtitler/input/downloaded_video.mp4 | grep -qE "ISO Media|MPEG v4|QuickTime" && echo "valid" || echo "invalid"

• 若文件不存在或类型无效，**终止流程并提示用户**：

> 文件不可用，请检查路径是否正确，或确认文件为有效视频格式（仅支持 MP4/MOV） 4. **步骤3：上传视频获取媒资信息**

• 执行 `python3.12 scripts/upload.py --file <视频路径>` 命令
• 返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 媒资ID（唯一标识） | | `url` | string | 视频访问URL | | `duration` | number | 视频时长（秒） | 5. **步骤4：解析媒资信息**：从上传输出中提取 `id` 作为媒资ID，提取 `duration` 用于字幕时间分配

• 告知用户视频时长：`您的视频时长为 {duration} 秒，建议字幕总字数不超