byted-mediakit-shared

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MediaKit 专业媒体处理入口

MediaKit Professional Media Processing Entry

MediaKit 是面向音视频与图像处理的专业工具集。它将常见的媒体加工、内容理解和智能增强能力统一到

mediakit-cli

，适合从素材处理到成片制作的完整工作流。

MediaKit is a professional toolset for audio-visual and image processing. It unifies common media processing, content understanding, and intelligent enhancement capabilities into

mediakit-cli

, suitable for complete workflows from material processing to final production.

使用规则

Usage Rules

通过本 Skill 或领域 Skill 实际执行
```
mediakit-cli
```
业务命令时，必须在同一次调用中注入来源与宿主，避免 CLI 无法识别调用来源：
- ```
MEDIAKIT_SURFACE=skill
```
  （本 Skill / 领域 Skill 调用固定为
```
skill
```
  ）
- ```
MEDIAKIT_RUNTIME=<当前 Agent 宿主>
```
  （无法判断时用
```
unknown
```
  ）
注入方式：在命令前设置环境变量（推荐），不要把这两个值当成 CLI flag 或业务参数。
```
--help
```
/
```
--schema
```
/
```
--domains
```
/
```
--version
```
等只读发现命令可不注入；一旦发起真实处理或
```
shared query-task
```
，必须注入。

示例（每次真实调用都带上）：

bash

MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video --video-url <url> --sub-image-url <url>
MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli shared query-task --task-id <task_id>

<runtime>

填当前宿主标识（如

cursor

、

claude-code

、

codex

）；不确定时填

unknown

。不要省略

MEDIAKIT_SURFACE=skill

。

When actually executing
```
mediakit-cli
```
business commands through this Skill or domain Skills, you must inject the source and host in the same call to prevent the CLI from failing to recognize the call source:
- ```
MEDIAKIT_SURFACE=skill
```
  (fixed as
```
skill
```
  for calls from this Skill / domain Skills)
- ```
MEDIAKIT_RUNTIME=<current Agent host>
```
  (use
```
unknown
```
  if unable to determine)
Injection method: Set environment variables before the command (recommended), do not treat these two values as CLI flags or business parameters.
Read-only discovery commands like
```
--help
```
/
```
--schema
```
/
```
--domains
```
/
```
--version
```
do not require injection; injection is mandatory once real processing or
```
shared query-task
```
is initiated.

Example (attach this to every real call):

bash

MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video --video-url <url> --sub-image-url <url>
MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli shared query-task --task-id <task_id>

Fill

<runtime>

with the current host identifier (e.g.,

cursor

claude-code

codex

); fill

unknown

if uncertain. Do not omit

MEDIAKIT_SURFACE=skill

能力范围

Capability Scope

视频剪辑与合成：裁剪、拼接、转场、调速、音量调整、视频滤镜、运镜、画面叠加、字幕压制、混音、淡入淡出、音视频提取与合流、文字滚屏、图转视频和多画面编排。
音频与音轨处理：音频转码与媒资探测、语音边界定位、人声与背景声分离，以及面向视频音轨的处理。
视频理解与增强：视频内容分析、剧情/剧本与精彩高光拆条、画质增强与画质检测、抽帧、语音转字幕与字幕提取、字幕擦除、水印处理、隐私保护、场景与语义分段、画面文字识别、转码转封装、抠像与换脸等。
图像处理与内容理解：尺寸缩放与体积治理、元信息探测、裁剪旋转翻转与圆角、颜色与锐化、负片、模糊与打码、水印、背景移除、文字识别、画质评估与智能裁剪等。

Video Editing and Synthesis: Cropping, splicing, transitions, speed adjustment, volume adjustment, video filters, camera movements, picture overlay, subtitle embedding, audio mixing, fade in/out, audio-visual extraction and merging, text scrolling, image-to-video conversion, and multi-screen arrangement.
Audio and Track Processing: Audio transcoding and media detection, speech boundary positioning, separation of human voice and background sound, as well as processing for video audio tracks.
Video Understanding and Enhancement: Video content analysis, plot/script and highlight clipping, image quality enhancement and detection, frame extraction, speech-to-subtitle and subtitle extraction, subtitle erasure, watermark processing, privacy protection, scene and semantic segmentation, picture text recognition, transcoding and repackaging, keying and face swapping, etc.
Image Processing and Content Understanding: Size scaling and volume management, metadata detection, cropping, rotation, flipping and rounding, color and sharpening, negative effect, blurring and masking, watermarking, background removal, text recognition, image quality evaluation and intelligent cropping, etc.

能力选择与优先加载

Capability Selection and Priority Loading

按用户的处理对象和明确目标选择领域 Skill：

用户目标	优先加载
对现有素材进行裁剪、拼接、转场、滤镜、运镜、叠加、混音或成片编排	`byted-mediakit-editing`
处理音频转码、音轨、语音边界或人声与背景声	`byted-mediakit-audio`
处理单张或批量图片、尺寸体积治理、文字识别、图片质量或图像编辑	`byted-mediakit-image`
视频理解、高光拆条、抽帧、画质增强或检测、提取字幕、语音转字幕、字幕擦除、水印、隐私、转码或视频智能处理	`byted-mediakit-video`

如果一个请求同时包含多个阶段，先加载与主要产出最匹配的领域 Skill，再按工作流需要加载其他领域 Skill。只说明“处理一个视频”或“处理一张图片”而没有说明目标时，先向用户澄清，不要根据媒体类型猜测具体能力。

选定领域后，必须先读取该领域 Skill，再读取最终选定工具的完整 reference，最后依据当前 CLI 的机器合同构造参数。共享入口只负责能力导航和通用 CLI 使用方式，不重复具体工具的参数、枚举或结果字段。

Select domain Skills according to the user's processing object and clear goal:

User Goal	Priority Loading
Crop, splice, add transitions, apply filters, adjust camera movements, overlay, mix audio, or arrange existing materials into a finished video	`byted-mediakit-editing`
Process audio transcoding, tracks, speech boundaries, or separation of human voice and background sound	`byted-mediakit-audio`
Process single or batch images, size/volume management, text recognition, image quality or image editing	`byted-mediakit-image`
Video understanding, highlight clipping, frame extraction, image quality enhancement or detection, subtitle extraction, speech-to-subtitle, subtitle erasure, watermarking, privacy protection, transcoding or intelligent video processing	`byted-mediakit-video`

If a request involves multiple stages, first load the domain Skill that best matches the main output, then load other domain Skills as needed for the workflow. When users only state "process a video" or "process an image" without specifying the goal, clarify with the user first, do not guess specific capabilities based on media type.

After selecting the domain, you must first read the corresponding domain Skill, then read the complete reference of the finally selected tool, and finally construct parameters according to the current CLI's machine contract. The shared entry is only responsible for capability navigation and general CLI usage, and does not repeat parameters, enumerations or result fields of specific tools.

安装与可用性检查

Installation and Availability Check

首次使用时安装 CLI 与随附 Skills：

bash

npx @volcengine/mediakit-cli install -y

安装后验证公开入口：

bash

mediakit-cli --version
mediakit-cli --help

需要重装当前版本携带的 Skills 时执行：

bash

npx @volcengine/mediakit-cli install --skills-only -y

Install the CLI and accompanying Skills for the first use:

bash

npx @volcengine/mediakit-cli install -y

Verify the public entry after installation:

bash

mediakit-cli --version
mediakit-cli --help

Execute this to reinstall Skills carried by the current version:

bash

npx @volcengine/mediakit-cli install --skills-only -y

初始化与检查

Initialization and Check

bash

mediakit-cli init
mediakit-cli config show
mediakit-cli doctor

doctor

用于检查当前 CLI 与本地处理依赖；具体工具是否支持本地处理，以对应领域 Skill 和工具 reference 为准。

bash

mediakit-cli init
mediakit-cli config show
mediakit-cli doctor

doctor

is used to check the current CLI and local processing dependencies; whether a specific tool supports local processing is subject to the corresponding domain Skill and tool reference.

命令发现与机器合同

Command Discovery and Machine Contract

bash

mediakit-cli --domains
mediakit-cli <domain> --help
mediakit-cli <domain> <tool> --help
mediakit-cli <domain> <tool> --schema

--schema

只读取当前有效模式的机器合同，不发起业务调用；顶层包含

name

、

description

、

input_schema

和

output_schema

。构造参数前先读取目标工具的

--help

与

--schema

，并以完整 reference 中的字段说明为 Agent 使用指引。

bash

mediakit-cli --domains
mediakit-cli <domain> --help
mediakit-cli <domain> <tool> --help
mediakit-cli <domain> <tool> --schema

--schema

only reads the machine contract of the current valid mode and does not initiate business calls; the top-level includes

name

description

input_schema

and

output_schema

. Before constructing parameters, read the

--help

and

--schema

of the target tool, and use the field descriptions in the complete reference as the Agent usage guide.

媒体输入

Media Input

直接把用户提供的媒体输入传给工具参数。本机文件请传本地文件路径（如

/path/to/file.jpg

或

./file.jpg

），不要自行添加

mediakit://

前缀；CLI 的媒体输入适配器会处理上传。不需要额外创建上传命令或上传参数。

Directly pass the media input provided by the user to the tool parameters. For local files, pass the local file path (e.g.,

/path/to/file.jpg

./file.jpg

), do not add the

mediakit://

prefix on your own; the CLI's media input adapter will handle the upload. No additional upload commands or parameters are required.

Cloud / Local 模式

Cloud / Local Mode

未指定模式时，由 CLI 当前配置选择 Cloud-first 或 Local-first。

--local

与

--cloud

只用于单次命令覆盖；CLI 的

--help

与

--schema

只显示所选模式的参数与结果。

规范命令顺序为：

bash

mediakit-cli --cloud <domain> <tool> [flags]
mediakit-cli --local <domain> <tool> [flags]

Local 不支持的参数不能被静默忽略；应改用 Cloud 或移除对应参数。Local 工具同步返回处理结果，不产生 Cloud 异步任务。Local 输出目录通过 CLI 配置管理：

bash

mediakit-cli config set output-path <输出目录>

When no mode is specified, the CLI's current configuration selects Cloud-first or Local-first.

--local

and

--cloud

are only used to override for a single command; the CLI's

--help

and

--schema

only display parameters and results for the selected mode.

The standardized command order is:

bash

mediakit-cli --cloud <domain> <tool> [flags]
mediakit-cli --local <domain> <tool> [flags]

Parameters not supported by Local cannot be silently ignored; switch to Cloud or remove the corresponding parameter instead. Local tools return processing results synchronously and do not generate Cloud asynchronous tasks. The Local output directory is managed through CLI configuration:

bash

mediakit-cli config set output-path <output directory>

异步结果

Asynchronous Results

Cloud 异步能力返回

task_id

。先使用共享查询命令获取任务状态与最终业务结果：

bash

mediakit-cli shared query-task --task-id <task_id>

需要持续等待终态时，按 query_task.md 中的查询协议执行。

Cloud asynchronous capabilities return

task_id

. First use the shared query command to obtain the task status and final business results:

bash

mediakit-cli shared query-task --task-id <task_id>

When continuous waiting for the final state is required, execute according to the query protocol in query_task.md.

更新

Update

bash

mediakit-cli update
mediakit-cli update --check
mediakit-cli version --check

bash

mediakit-cli update
mediakit-cli update --check
mediakit-cli version --check

共享查询协议

Shared Query Protocol

协议	说明	命令	参考
query-task	查询 Cloud 异步任务状态与终态业务结果。	`mediakit-cli shared query-task`	reference/query_task.md

Protocol	Description	Command	Reference
query-task	Query the status and final business results of Cloud asynchronous tasks.	`mediakit-cli shared query-task`	reference/query_task.md