SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-kickart-subtitle-extractor

byted-kickart-subtitle-extractor

General & other

View repository

Updated 10-15 17:30

About this skill

Video subtitle extraction SKILL

📋 Tool Description

Core Features

  1. Extract subtitles from a specified video file
  2. Support generating subtitle files that conform to the standard SRT specification

Available Commands

Command Function Description
python3.12 scripts/plan.py Plan query Query the user's current Ark Claw plan
python3.12 scripts/upload.py --file <视频路径> Video upload Upload a local video file to obtain the media asset ID
python3.12 scripts/extractor.py --media-id <媒资ID> --output <输出文件> Video subtitle extraction Extract subtitles from a specified video

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

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

1. Volcano authentication check

  • 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 send the ACCESS_KEY_ID/SECRET_ACCESS_KEY content directly in the chat:

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

  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. When all related scripts are subsequently executed, they will automatically pass throughexportSpecify these two environment variables to ensure normal authentication, with no need for the user to configure them repeatedly

2. Plan validity check

  • Step 1: Python version check 
    python3.12 --version || (echo "❌ Python 3.12+ 未安装，请先安装Python 3.12" && exit 1)
  • Step 2: Dependency package installation check 
    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: the message field in the returned result is the valid expiration time (Beijing time), check 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 check

  • 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 (such as "1.0.0")
    • install_command: new version installation command
  • Step 3: Version comparison logic
    • ✅ Current version >= latest version: Version check passed, continuing 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 {latest_version} of the skill 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 extraction execution process

Complete process overview

用户请求 → 强制前置校验 → 用户提供视频 → 视频字幕提取 → 结果返回

Preliminary preparation

  1. Ensure the output directory exists:mkdir -p /tmp/openclaw/subtitle-extractor/output
  2. Generate a unique output file name:subtitle_<timestamp>_<random>.json

Execution steps

  1. Step 0: Mandatory preliminary verification(must be executed in order; if any check fails, terminate the process immediately)

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

  2. Step 1: Video upload guidance

    • Ask the user: "Please first provide the video from which you want to extract subtitles: you can send me a video TOS link, or upload an MP4/MOV file (recommended ≤10 minutes, ≤200MB, ≥480p; expected processing time within 5 minutes)"
    • Two upload methods are supported:
      • Local file: Directly provide the absolute path of 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）

  3. Step 2: Video preprocessing

    • If the user provides a public URL, first download it locally: 
      mkdir -p /tmp/openclaw/byted-kickart-video-analyzer/input
curl -L -o /tmp/openclaw/byted-kickart-video-analyzer/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-analyzer/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 is supported)

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

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

  5. Step 4: Call the tool to extract video subtitles

    • Execute the subtitle extraction command: 
      python3.12 scripts/extractor.py --media-id <媒资ID> --output <输出文件路径>
    • Parameter description:
      Parameter Type Description
      --media-id string Media asset ID obtained in step 3
      --output string Subtitle result output file path (JSON format)
    • Execution process:
      1. Call the ICCP service to submit the subtitle extraction task
      2. Poll the task status (query once every 30 seconds, up to 5 minutes)
      3. After the task is completed, save the result to the specified output file
    • Return result description (JSON format):
      Field Type Description
      video_url string Video access URL
      captions object Subtitle information object
      captions.end_time number Subtitle end time (milliseconds)
      captions.start_time number Subtitle start time (milliseconds)
      captions.attribute object Subtitle attributes (reserved field)
      captions.text string Complete subtitle text content
      captions.words array Word segmentation list
      captions.words[].end_time number Word end time (milliseconds)
      captions.words[].start_time number Word start time (milliseconds)
      captions.words[].attribute object Word attributes (reserved field)
      captions.words[].text string Single word text

  6. Step 5: SRT subtitle file generation (optional)

    • Trigger condition: The user needs a standard SRT format subtitle file
    • Trigger method: After subtitle extraction succeeds, ask the user in the message template whether they need an SRT format subtitle file
    • Generation method: The Agent directly generates a standard SRT format subtitle file based on the subtitle JSON result, without relying on a script
    • SRT format description: 
      1
00:00:00,000 --> 00:00:01,800
it's a filter in a bottle with SPF!

2
00:00:01,800 --> 00:00:10,200
This isnt even a foundation

Agent execution special requirements

  1. Timeout setting: 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 API to confirm the backend status. Do not directly determine that the task has failed

📝 User display message template

Strict requirements: Must be displayed in plain body text format, must never use bold syntax (**), and must strictly preserve the line break for each line!

Video upload success template:

📤 视频上传成功！

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

Subtitle extraction success template:

✨ 字幕提取任务已完成！
🎥 视频链接
[点击查看视频]({video_url})

🔤 字幕全文
{full_text}

🔤 字幕分词详情

| 时间戳（秒） | 分词文本 |
|-------------|----------|
{word_rows}

---

📁 字幕JSON文件路径：{output_file_path}

需要帮你生成SRT格式的带时间戳字幕文件吗？

{word_rows} Generation rule: iterate over the captions.words array, filter out entries whose text is blank, divide start_time/end_time by 1000 to convert to seconds, with each line formatted as | {start_sec}-{end_sec} | {text} |, and all non-empty word segmentation entries must be generated completely without omission.

⚠️ Error handling specification

All errors must clearly inform the reason and an executable solution. Vague prompts are prohibited!!!

Error code Error description Detailed description User handling 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 credits When calling the API, the user account has insufficient credit quota Please go to the Credit recharge page to recharge credits or upgrade the plan
1410 Service ID does not exist When calling the API, the input parameters contain a service ID that does not exist
1411 Input resolution error When calling the API, the resolution of the image or video 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 be generated at this time. Please wait for a future version update
1415 Output contains sensitive information error When calling the API, the result returned by the service contains sensitive information, such as personal privacy data Marketing videos with people cannot be generated at this time. Please wait for a future version update
1416 Input media quantity error The quantity of materials input by the user exceeds the limit The quantity of media materials provided exceeds the limit; the excess materials may not be used
1417 Large model call error Model call 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 the production request within the 0-60s duration limit. If the problem persists, contact Volcano technical support
1501 User package expired When calling the API, the user package has expired Please go to Package Activation Page to activate a package
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 Consoleto confirm
100013 Missing service permission Missing the RegisterArkClawCombo permission for the iccloud_muse service Your enterprise account has not activated the Kickart permission. Please contact the Volcano primary account administrator to activate it for you, or consult Volcano technical support for details
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 during material upload, 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 to the API is incorrect Please try again later. If the problem persists, contact Volcano technical support
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 the task may have been deleted
Other - Other error conditions not explicitly listed Try again later. If the problem persists, contact Volcano Technical Support.