SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-kickart-video-subtitler

byted-kickart-video-subtitler

Design & creation

View repository

Updated 10-15 17:30

About this skill

Video Subtitle Addition SKILL

📋 Tool Description

Core Function

Add subtitles to local video files.

Usage Limits

Limit Item Limit Value Description
Total subtitle word count ≤3000 words The subtitle text content (excluding punctuation marks) must not exceed 3000 words

Available Commands

Command Function Description
python3.12 scripts/plan.py Package Query Query the user's current Ark Claw package
python3.12 scripts/upload.py --file <视频路径> Video Upload Upload a local video file to obtain the media asset ID
python3.12 scripts/subtitler.py --media-id <媒资ID> --captions <字幕配置文件> --output <输出文件> Video Subtitle Addition Add subtitles to a video

📝 Subtitle Configuration File Generation Rules

Configuration File Format

The subtitle configuration file is in JSON format and contains an array of subtitle objects. The structure of a single subtitle object is as follows:

Field Type Description
text string The complete subtitle text content
start_time number Subtitle start display time (milliseconds)
end_time number Subtitle end display time (milliseconds)
words array Character-level timestamp array, containing detailed time information for each character
attribute object Subtitle attributes (reserved field, defaults to an empty object)

Time Allocation Rules (consistent with human reading habits)

Basic Rules:

  • Per-character duration: Normal Chinese speech rate is about 4-5 characters per second, i.e., each Chinese character is about 200-250 milliseconds
  • Punctuation handling: The duration of punctuation marks is 0 milliseconds; they are displayed immediately and then a pause begins
  • Sense-group pause: Set a 300-millisecond pause after punctuation such as commas and periods, consistent with human reading habits
  • Inter-word interval: Set a tiny 20-millisecond interval between words to improve readability
  • Ending extension: Appropriately extend the display time of the last character to ensure complete reading

Generation Steps:

  1. Determine the total number of subtitles: Reasonably divide subtitle segments according to video duration and content complexity
  2. Allocate time ranges: Ensure that subtitles do not overlap and that at least a 300-millisecond interval is reserved between segments
  3. Calculate per-character duration：(end_time - start_time - 标点停顿时间) / 汉字数量
  4. Generate character-level timestamps: Assign time to each character in order, with punctuation using a duration of 0 milliseconds
  5. Add sense-group pauses: Insert appropriate pause times after punctuation

Example calculation:

For the subtitle "足力健老人鞋，专为爸妈设计" (13 characters, including 1 punctuation mark):

  • Total duration: 3190 milliseconds (5000-1810)
  • Number of Chinese characters: 12
  • Average per-character duration: about 220 milliseconds
  • Punctuation pause: 300 milliseconds
{
  "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": {}
}

Notes:

  • Keep at least a 300-millisecond interval between subtitles
  • It is recommended that the first subtitle start 500 milliseconds after the video begins
  • It is recommended that the last subtitle end 1000 milliseconds before the video ends
  • Avoid making a single subtitle too long (it is recommended not to exceed 15 Chinese characters)

🚨 Mandatory pre-validation process (must be executed in order; if any check fails, terminate the process immediately)

All user requests must first complete the following 3 validation steps, and they must not be skipped:

1. Volcano authentication validation

  • Execute the environment variable check command: 
    echo "ACCESS_KEY_ID: $ACCESS_KEY_ID" && echo "SECRET_ACCESS_KEY: $SECRET_ACCESS_KEY"
  • Determine the authentication result:
    • Authentication passed：ACCESS_KEY_ID and SECRET_ACCESS_KEY are both non-empty values → authentication passed
    • Authentication failed: execute the following guidance plan

❌ Guidance plan when authentication is not configured

  1. Guide the user to directly send the ACCESS_KEY_ID/SECRET_ACCESS_KEY content in the chat:

    Please provide your Volcano account AK&SK, to check whether the Volcano Creation Agent has activated a plan and has available creation credits

  2. After receiving the ACCESS_KEY_ID/SECRET_ACCESS_KEY sent by the user, execute the configuration command: 
    export ACCESS_KEY_ID=用户提供的ACCESS_KEY_ID值
export SECRET_ACCESS_KEY=用户提供的SECRET_ACCESS_KEY值
  3. After configuration is complete, inform the user:

    The temporary configuration of ACCESS_KEY_ID/SECRET_ACCESS_KEY has been completed. The current configuration is effective only for this session and will not be persistently stored. Please use it with confidence

  4. During all subsequent related script executions, it will automatically passexportSpecify these two environment variables to ensure normal authentication, without requiring the user to configure them repeatedly

2. Plan validity validation

  • Step 1: Python version validation 
    python3.12 --version || (echo "❌ Python 3.12+ 未安装，请先安装Python 3.12" && exit 1)
  • Step 2: Dependency package installation validation 
    python3.12 -m pip install -r ./scripts/requirements.txt
  • Step 3: Execute the plan query command 
    python3.12 -m scripts/plan.py
  • Step 4: Result handling logic
    • ✅ Plan valid: in the returned result, the message field is the valid expiration time (Beijing time), validation passed
    • ❌ Plan expired：message is less than or equal to the current time, guide the user to activate a plan, and terminate the process
    • ❌ API call error: refer to the "Error Handling Specification" to match the error code, clearly inform the user of the error cause and solution, and terminate the process

3. Skill version validation

  • Step 1: Execute the version check command 
    python3.12 -m scripts/upgrade.py
  • Step 2: Parse the returned result Return format example: 
    {"code":"0","message":"success","data":"{\"install_command\":\"\",\"latest_version\":\"1.0.0\",\"latest_version_number\":100000000,\"update_message\":\"\"}"}
    • latest_version: latest version number (e.g. "1.0.0")
    • install_command: new version installation instruction
  • Step 3: Version comparison logic
    • ✅ Current version >= latest version: version validation passed, continue with the subsequent process
    • ⚠️ Current version < latest version: execute the following update inquiry process
      1. Ask the user whether to update to the latest version:

        A new version of the skill {latest_version} has been detected. Do you want to update? (Yes/No)

      2. User confirms update (Yes): execute install_command to install the new version
      3. User does not update (No): skip the update and continue with the subsequent process

🛠️ Video subtitle addition execution process

Complete process overview

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

Preliminary preparation

  1. Ensure the output directory exists:mkdir -p /tmp/openclaw/byted-kickart-video-subtitler/output
  2. Generate a unique output filename:video_subtitle_<timestamp>_<random>.json

Execution steps

  1. Step 0: Mandatory pre-checks(Must be executed in order; if any check fails, terminate the process immediately)

    • Execute all verification steps in the "🚨 Mandatory Pre-check Process"
    • ✅ Volcano authentication check passed
    • ✅ Package validity check passed
    • ✅ Skill version check passed
    • Only after all checks pass can you proceed to the next step

  2. Step 1: Video upload guidance

    • Ask the user: "Please provide the video you want to add subtitles to. It can be a local file path or a public video URL. The video duration must not exceed 10 minutes."
    • Two upload methods are supported:
      • Local file: directly provide the absolute path to the local video file (e.g., /Users/user/video.mp4）
      • Public URL: provide a directly accessible video link (e.g., https://example.com/video.mp4）
    • Do not collect subtitle content: subtitle collection is handled specifically in Step 5

  3. Step 2: Video preprocessing

    • If the user provides a public URL, first download it locally: 
      mkdir -p /tmp/openclaw/byted-kickart-video-subtitler/input
curl -L -o /tmp/openclaw/byted-kickart-video-subtitler/input/downloaded_video.mp4 "<视频URL>"
    • Check whether the file exists:ls -la "<视频路径>"
    • Check whether the file type is a valid video (only MP4/MOV formats are supported): 
      file /tmp/openclaw/byted-kickart-video-subtitler/input/downloaded_video.mp4 | grep -qE "ISO Media|MPEG v4|QuickTime" && echo "valid" || echo "invalid"
    • If the file does not exist or the type is invalid,terminate the process and prompt the user：

      The file is unavailable. Please check whether the path is correct, or confirm that the file is in a valid video format (only MP4/MOV are supported)

  4. Step 3: Upload the video to obtain media asset information

    • Execute the python3.12 scripts/upload.py --file <视频路径> command
    • Returned field descriptions:
      Field Type Description
      id string Media asset ID (unique identifier)
      url string Video access URL
      duration number Video duration (seconds)

  5. Step 4: Parse media asset information: Extract id from the upload output as the media asset ID, and extract duration for subtitle time allocation

    • Inform the user of the video duration:您的视频时长为 {duration} 秒，建议字幕总字数不超过 {duration * 4} 字

  6. Step 6: Subtitle content collection and verification

    • Ask the user: "Please provide the subtitle content. You can choose one of the following methods:
      1. Directly enter the subtitle text (only single-line is supported)
      2. Provide the path to an SRT subtitle file (standard SRT format)
      3. Provide subtitle text + timestamp data (including sentence timestamps, word timestamps, and word segmentation text)"
    • Prompt the user to create subtitles with reference to the video duration (the total number of subtitle characters must not exceed 3000)
    • If the user chooses method 3, guide the user to provide complete timestamp data
    • Character count verification: Check the total number of characters in the subtitle text (excluding punctuation). If it exceeds 3000 characters, prompt the user to condense the subtitle content and terminate the process:

      The subtitle character count exceeds the limit (currently {count} characters, limit 3000 characters). Please condense the subtitle content and submit again

  7. Step 6: Generate subtitle configuration

    • Method 1: The user provides subtitle text: Generate the subtitle configuration JSON according to the "Subtitle Configuration File Generation Rules" based on the video duration and the subtitle text provided by the user
      • Multiple subtitle branches: If the subtitle text contains line breaks (number of lines > 1), automatically split it into multiple subtitles by line break, and divide the video duration equally (duration of each subtitle = (total duration ms - 1500ms margin) / number of subtitles)
    • Method 2: The user provides an SRT file: Parse the SRT file content and convert it to the subtitle configuration JSON format
      • SRT format example: 
        1
00:00:00,000 --> 00:00:02,000
第一条字幕内容

2
00:00:02,000 --> 00:00:04,000
第二条字幕内容
      • Parsing rules: Extract the sequence number, start time, end time, and subtitle text, and convert them to the subtitle configuration JSON
    • Method 3: The user provides subtitle text + timestamp data: Directly generate the subtitle configuration JSON based on the sentence segmentation timestamps, word segmentation timestamps, and word segmentation text data provided by the user
      • Input data format example: 
        分句1：0-2000ms
分词：词1(0-500ms)、词2(500-1000ms)、词3(1000-1500ms)、词4(1500-2000ms)

分句2：2000-4000ms
分词：词5(2000-2500ms)、词6(2500-3000ms)、词7(3000-3500ms)、词8(3500-4000ms)
      • Parsing rules: Directly build the subtitle configuration JSON according to the timestamp data provided by the user, including complete sentence segmentation and word segmentation time information

  8. Step 7: Subtitle confirmation(Before adding to the platform, confirmation from the user is required)

    • Show the user a summary of the generated subtitle configuration (number of subtitles, first subtitle text, estimated total duration)
    • Ask the user for confirmation: "The subtitle configuration has been generated. Are you sure you want to submit it for addition? (Confirm/Cancel)"
    • User cancels → Terminate the process, no creativity points are consumed
    • User confirms → Continue to the next step

  9. Step 8: Add subtitles: Execute the following command

    python3.12 scripts/subtitler.py \
  --media-id <媒资ID> \
  --captions /tmp/openclaw/byted-kickart-video-subtitler/output/video_subtitle_<timestamp>_<random>.json \
  --output /tmp/openclaw/byted-kickart-video-subtitler/output/subtitle_result_<timestamp>_<random>.json
    • Important：
      • --captions The parameter value is theabsolute path of the subtitle configuration JSON file(not an inline JSON string); generated in step 6 and saved in the /tmp/openclaw/byted-kickart-video-subtitler/output/ directory
      • --output The parameter value is theabsolute path of the result JSON file(not the video file path); the script will save the subtitle addition result to this JSON file

  10. Step 9: Parse the result and extract the video URL

    • Read --output the content of the specified JSON file
    • Extract the video field value from the JSON as the video URL after subtitles are added
    • Use the "Subtitle Addition Success Template" to show the result to the user, including the video preview link
    • Output field descriptions
      Field Type Description
      uuid string Unique identifier of the subtitle addition task
      video string Video URL after subtitles are added (includes authentication parameters)

Agent execution special requirements

  1. Timeout settings: When calling the exec tool to start the script, set yieldMs to ≥180000ms (3 minutes)
  2. Friendly prompt: If the script does not return a result immediately, first reply to the user: "We are analyzing the video for you. The task may take a long time to execute. Please wait a moment~"
  3. Exception handling: If the script exits due to timeout/exception, immediately use the persisted Task ID to call the task query interface to confirm the backend status. Do not directly determine that the task has failed

📝 User display message template

Video upload success template:

📤 视频上传成功！

🆔 媒资ID: {media_id}
🔗 视频URL: [点击查看]({url})
📊 分辨率: {width}x{height}
⏱️ 时长: {duration}秒

Subtitle added successfully template:

✨ 字幕添加任务已完成！

🎥 [点击预览视频]({video})

📝 字幕已自动添加到视频中，您可以直接下载使用！

⚠️ Error Handling Specification

All errors must clearly inform the reason and executable solutions; vague prompts are prohibited!!!

Error Code Error Description Detailed Explanation User Action Suggestion
0 No Return Value The API call succeeded, but the service returned an empty result Please try again later; if the problem persists, contact Volcano Technical Support
1400 ParamErr Parameter Error Parameter error Contact technical support
1402 Insufficient Creation Credits When calling the API, the user's account creation credit balance is insufficient Please go to Creation Credit Recharge Page to recharge creation credits or upgrade your plan
1410 Service ID Does Not Exist When calling the API, the input parameters contain a non-existent service ID
1411 Input Resolution Error When calling the API, the image or video resolution in the input parameters does not meet the requirements Please check whether the material resolution meets the specification requirements (e.g., ≥480p)
1412 Image Format Error When calling the API, the input parameters contain an unsupported image format Please check whether the image format is a supported format such as jpg or png
1413 Invalid Media URL Error When calling the API, the input parameters contain an invalid media URL Please check whether the URL you provided is correct and avoid special characters or format errors
1414 Input Contains Sensitive Information Error When calling the API, the input parameters contain sensitive information, such as personal privacy data Marketing videos with people cannot currently be generated. Please wait for future version updates
1415 Output Contains Sensitive Information Error When calling the API, the service return result contains sensitive information, such as personal privacy data Marketing videos with people cannot currently be generated. Please wait for future version updates
1416 Input Media Quantity Error The number of materials input by the user exceeds the limit The number of media materials provided exceeds the limit; the extra materials may not be used
1417 Large Model Invocation Error Model invocation error, usually caused by incorrect input parameters There is a problem with media material processing. Please try again; if the problem persists, contact Volcano Technical Support
1418 Duration Billing Parameter Error There is a problem with the input time parameter at submission The required final video duration does not meet the skill requirements. Please submit production requests within the 0-60s duration limit; if the problem persists, contact Volcano Technical Support
1501 User Plan Expired When calling the API, the user's plan has expired Please go to Plan Activation Page to activate a plan
1600 Task Does Not Exist When querying task status, the specified task ID does not exist Please confirm whether the task ID is correct, or whether the task has been deleted
100010 Signature Verification Failed AK/SK signature verification failed Please check whether the Volcano authentication AK/SK you provided is correct. You can visitVolcano Engine ConsoleConfirm
100013 Missing service permission Missing the RegisterArkClawCombo permission for the iccloud_muse service Your enterprise account has not enabled the Kickart permission. Please contact the Volcano primary account administrator to enable it for you, or contact Volcano technical support for more information.
x01001 AK/SK not configured The user has not configured AK/SK Please enter the AK/SK for Volcano authentication. You can visitVolcano Engine Consoleto obtain it
x01010 Valid package missing An error occurred while uploading the material. This is usually due to the package. Please go to package activation page to activate a package
A0101 Session metadata format error The Session metadata format passed in through the API is incorrect Please try again later. If the problem persists, contact Volcano technical support.
A0402 File validation failed The file entered by the user does not meet the validation requirements Guide the user to re-upload a file that meets the requirements
Other - Other error situations not explicitly listed Please try again later. If the problem persists, contact Volcano technical support.